File output cloud storage extension contract reference | Docusign

The file output cloud storage extension writes documents generated from a Workflow Builder workflow Send Documents for Signature step to a cloud storage platform.

You can include this extension when you register an extension app. If you register the extension app using a form, select the File Output Cloud Storage extension in the form-based UI, as shown in this figure:

Selecting the file output cloud storage extension when registering an extension app

During the form-based extension app registration process, if you select a file IO extension, its required actions are automatically added to the app. You can then configure the actions’ endpoint URIs and other properties on the Integration Details page. The extension’s optional capabilities can be added or removed only by editing the app manifest file. After you’ve added capabilities via the manifest file, you can edit them on the Integration Details page. See Action schema for information about action and capability properties in the app manifest file.

If you register the extension app using an app manifest file, set the extensions.template value in your app manifest to FileIO.Version1.FileOutputCloudStorage.

This extension has one required action and two optional capabilities. Below is a list of their identifiers as they appear in the form-based app registration UI and the app manifest. See Example extension app use cases for a complete sample app manifest for file output to cloud storage.

Form-based UI name	App manifest actions.template value	App manifest actions.name value	App manifest extensions.capabilities value	Required
Write File	`FileIO.Version1.WriteFile`	`write-file`	N/A	Yes
List Directory Contents	`FileIO.Version1.ListDirectoryContents`	`list-directory-contents`	`FileIO.Version1.ListDirectoryContents`	No
List Drives	`FileIO.Version1.ListDrives`	`list-drives`	`FileIO.Version1.ListDrives`	No

Both the action and the capabilities are defined in the app manifest fileʼs actions object. This definition includes a template value, a name, and the endpoint URL. The action and capabilities must also be referenced from the extensions object as follows:

For both the action and capabilities, include the actions.name value from the actions object in the extensions.actionReferences array.
Include a reference to each capability in the extensions.capabilities array. Use the value from the App manifest extensions.capabilities value column in the table above.

For example, the manifest file action definitions for the Write File action and the List Drives capability look like this:

"actions": [
  {
    "name": "write-file",
    "description": "Writes a file to a cloud storage system",
    "template": "FileIO.Version1.WriteFile",
    "connectionsReference": "authentication",
    "params": {
      "uri": "https://fontara.com/api/writefile"
    }
  },
  {
    "name": "list-drives",
    "description": "Retrieves a list of drives on a cloud storage system",
    "template": "FileIO.Version1.ListDrives",
    "connectionsReference": "authentication",
    "params": {
      "uri": "https://fontara.com/api/listdrives"
    }
]

The extensions object includes the actions.name values for both the Write File action and the List Drives capability in the actionReferences array. In addition, the List Drives capability is included in the capabilities array:

"extensions": [
  {
    "name": "My File Output Cloud Storage Extension",
    "description": "Writes files to a cloud storage system",
    "template": "FileIO.Version1.FileOutputCloudStorage",
    "capabilities": ["FileIO.Version1.ListDrives"],
    "actionReferences": [
      "write-file",
      "list-drives"
    ]
  }
]

For details about what the actions and capabilities do when invoked, see File output cloud storage actions and capabilities.

When registering an extension app, you cannot include both a file output system of record extension and a file output cloud storage extension in the same app. If you need to use both types of output in workflows, register a separate app for each extension.

Action contracts

Write File (FileIO.Version1.WriteFile)

This required action writes a completed agreement to a cloud storage system. It can be triggered from a Maestro workflow.

Write File is the label that appears when you register an extension app using a guided, form-based process.

If you register your extension app using an app manifest file, make sure that you:

Include a definition for the action in the actions object. See Action schema for details about the required properties. The action definition must include these values, which are specific to this action:
- name: write-file
- template: FileIO.Version1.WriteFile
Include the value from the actions.name property in the extensions.actionReferences array. See Extension schema for details.

See Example extension app use cases for a complete sample app manifest for file output to cloud storage.

HTTP method

This action initiates a POST request to the external API service.

Request

Example request 1

Example request 2

Request with hardcoded folder and file names:

{
  "files": [
    {
      "contents": "JVBERi...VFT0YK",
      "basename": "MyFileName.pdf",
      "path": "MyFolder/MyFileName.pdf",
      "pathTemplateValues": [
      ]
    }
  ],
  "rootId": "root"
}

Property	Type	Occurrence	Description
`files`	`Object[]`	Required	An array of files to write to the cloud storage system. Note: In the current release, Maestro does not support defining different destination folders or file names for multiple files in the same file output step. If a workflow will write multiple files to cloud storage, the process builder should create separate file output steps for each file so that the desired folder and file name can be defined. Each file output step will result in a separate Write File request to the external system.
`files.basename`	`String`	Required	The file name, including the extension. Docusign populates this value based on the file name that a process builder defines while configuring a Maestro workflow file output step. The naming convention can use workflow variables, such as an envelope ID, and hardcoded values. See the next sections for details.
`files.path`	`String`	Required	If the extension app implements the List Directory Contents capability, this property contains the path to the directory where the file is to be written, followed by the file naming convention with extension. Docusign populates this value based on the destination folder and file name that a process builder defines while configuring a Maestro workflow file output step. The naming convention can use workflow variables, such as an envelope ID, and hardcoded values. See the next sections for details. If the directory specified in the request does not exist, the external system should create it. If the extension app does not implement the List Directory Contents capability, this value consists of the file naming convention only, with no path. The external service must determine where to store the file.
`files.contents`	`String`	Required	The file contents, converted to a Base64 string.
`files.pathTemplateValues`	`String[]`	Optional	If the workflow was configured with a file or folder naming convention that includes variables, the elements in this array consist of the workflow instance–specific variable values. The external system must extract the variable values in this array and use them to construct the file and/or folder name. See the next sections for details.
`rootId`	`String`	Optional	If the extension app implements the List Drives capability, this is the ID of the drive (or similar container type) that the workflow process builder selected when configuring the file output step. Drive IDs are returned in the response to the List Drives request. If the extension app does not implement the List Drives capability, this property is omitted from the request. The external service must select a drive (or similar container type) in which to store the file if the cloud storage system has multiple structures that contain folders and files.

Hardcoded file and folder names

A workflow process builder can hardcode file and folder names when defining a file output to cloud storage step, as shown here:

Workflow file output step configuration with hardcoded names If the folder and file names are hardcoded, the same folder and file name will be used for every file that is written to the cloud storage system when workflow instances are executed. The hardcoded folder path and file name will be populated in the Write File requestʼs files.path property. The file name appears in files.basename.

Note: Folder paths can be specified during workflow step configuration only if the extension implements the List Directory Contents capability.

File and folder names that include workflow variables

Instead of hardcoding file and folder names, a process builder can use workflow variables to construct names that will be unique for each workflow instance. The variable values will be set during instance execution.

Note: Because hardcoded values will result in the same file and folder names being used for every workflow instance, Docusign recommends using variables in the names.

Shown here is an example in which a process builder has constructed a folder and file naming convention that consists of a combination of hardcoded values and variable names. The variable names appear in square brackets in the File path.

Workflow file output step configuration with variables in folder and file names If a file output step specifies a folder and/or file name containing variables, the Write File request body will include a files.pathTemplateValues array that lists the workflow instance–specific variable values. When it receives the Write File request, the external system must use values from the files.path property and the files.pathTemplateValues array to construct the folder and file name as follows:

Parse the files.path value in the request to determine which variables must be replaced with values. Each variable is listed in double curly braces in the format [workflow source].[variable name]. For example, {{``Send Documents for Signature.Envelope ID``}} refers to an envelope ID variable from the workflowʼs Send Documents for Signature step.
For each variable in files.path, replace the string in double curly braces with the corresponding instance-specific value from the pathTemplateValues array. The order of the pathTemplateValues elements matches the order of the files.path variables.

Below is an example Write File request based on the folder and file naming convention shown in the screenshot:

{
  "files": [
    {
      "contents": "JVBERi...VFT0YK",
      "basename": "Envelope ID {{Send Documents for Signature.Envelope ID}}_{{Instance Details.Start Date and Time}}.pdf",
      "path": "Participant {{Account owner Name}}/Envelope ID {{Send Documents for Signature.Envelope ID}}_{{Instance Details.Start Date and Time}}.pdf",
      "pathTemplateValues": [
        "Test Customer",
        "11721000-xxxx-xxxx-xxxx-2a498b65b09b",
        "2025-Jun-16-06:31PM"
      ]
    }
  ],
  "rootId": "drive-id-3"
}

The external system would complete these steps to derive the folder and file name:

Replace {{``Account owner Name``}} with Test Customer
Replace {{``Send Documents for Signature.Envelope ID``}} with 11721000-xxxx-xxxx-xxxx-2a498b65b09b
Replace {{Instance Details.Start Date and Time}} with 2025-Jun-16-06:31PM

Note: The external system should remove or replace prohibited characters in the file path and name before attempting to store the file.

The file path and name to use for the file sent in the request would be:

Participant Test Customer/Envelope ID 11721000-xxxx-xxxx-xxxx-2a498b65b09b_2025-Jun-16-06_31PM.pdf In this example, the prohibited colon character in the start date/time has been replaced with an underscore.

Response

{
  message: "File successfully saved"
}

Property	Type	Occurrence	Description
`message`	`String`	Required	Information describing the result of the file write operation. This message is displayed with the test result when a Developer Console extension test is run. It is not displayed to end users during workflow instance execution.

List Drives (FileIO.Version1.ListDrives)

This optional capability can be implemented for a file output cloud storage extension. It returns the drives available in the cloud storage system. If this capability is implemented, a workflow process builder can select from a list of drives when configuring a file output step.

Note: If the cloud storage system does not have the concept of drives and instead organizes folders and files under a different container type, this capability can retrieve a list of those containers instead. They will appear in the file output step configuration pageʼs Select drive list.

List Drives is the label that appears when you register an extension app using a guided, form-based process.

If you register your extension app using an app manifest file, make sure that you:

Include a definition for the capability in the actions object. See Action schema for details about the required properties. The action definition must include these values, which are specific to this capability:
- name: list-drives
- template: FileIO.Version1.ListDrives
Include the value from the actions.name property in the extensions.actionReferences array.
Include the value from the actions.template property in the extensions.capabilities array.

See Extension schema for details about the actionReferences and capabilities arrays. See Example extension app use cases for a complete sample app manifest for file output to cloud storage.

HTTP method

This action initiates a POST request to the external API service.

Request

{
  "containerType": "drive",
  "parentId": ""
}

Property	Type	Occurrence	Description
`containerType`	`String`	Required	Valid value: `drive` Note: If the cloud storage system does not have the concept of drives and instead organizes folders and files under a different container type, the request will still have a value of `drive` for this property.
`parentId`	`String`	Optional	Docusign includes this property in requests but does not populate it with a value.

Response

{
  "containerType": "drive",
  "data": [
    {
      "containerId": "drive-id-1",
      "containerName": "Drive 1"
    },
    {
      "containerId": "drive-id-2",
      "containerName": "Drive 2"
    }
  ]
}

Property	Type	Occurrence	Description
`containerType`	`String`	Required	Valid value: `drive` Note: If the cloud storage system does not have the concept of drives and instead organizes folders and files under a different container type, the response must still have a value of `drive` for this property.
`data`	`Object[]`	Required	An array of drives or similar structures that contain folders and files.
`data.containerId`	`String`	Required	A unique ID for the drive or other container type. If the extension app implements List Directory Contents as well as List Drives, a `containerId` returned in this response will be included in a subsequent List Directory Contents request as follows: A workflow process builder selects from a list of drives (or other containers) on the file output step configuration page. The process builder selects Add Folder on the step configuration page. Docusign launches a List Directory Contents request to the external system that includes the `containerId` of the container selected in step 1 so that the external system can retrieve a list of folders from the selected container.
`data.containerName`	`String`	Required	The name of the drive or other container type. Maestro displays `containerName` values in a list on the file output step configuration page.

List Directory Contents (FileIO.Version1.ListDirectoryContents)

This optional capability can be implemented for a file output cloud storage extension. It returns a list of folders on the cloud storage system. If this capability is implemented, a workflow process builder can select from a list of folders when configuring a file output step or specify a naming convention for a new folder to be created.

Maestro can call List Directory Contents multiple times as a process builder configures a file output step, to enable the process builder to drill down in the folder structure. For example, the process builder can select Add Folder to choose a top-level folder. The process builder can then select Add Subfolder to choose a folder one level lower. Additional selections of Add Subfolder can be made to drill down further, and each time, a List Directory Contents request is executed.

List Directory Contents is the label that appears when you register an extension app using a guided, form-based process.

If you register your extension app using an app manifest file, make sure that you:

Include a definition for the capability in the actions object. See Action schema for details about the required properties. The action definition must include these values, which are specific to this capability:
- name: list-directory-contents
- template: FileIO.Version1.ListDirectoryContents
Include the value from the actions.name property in the extensions.actionReferences array.
Include the value from the actions.template property in the extensions.capabilities array.

See Extension schema for details about the actionReferences and capabilities arrays. See Example extension app use cases for a complete sample app manifest for file output to cloud storage.

HTTP method

This action initiates a POST request to the external API service.

Request

Example request 1

Example request 2

Example request 3

Request when List Directory Contents is called after after a process builder selects a drive (or similar container type) and then selects Add Folder:

{
  "filterOptions": {
    "entryType": "folder"
  },
  "parentId": "drive-id-1"
}

Property	Type	Occurrence	Description
`parentId`	`String`	Required	One of the following: If the extension app implements List Drives and a process builder has selected a drive (or similar container type) and then selects Add Folder, this value will be the ID of the selected container. Container IDs are returned in the response to the List Drives request. If the extension app does not implement List Drives and a process builder selects Add Folder, this value will be `root`. If the process builder has already selected a folder and selects Add Subfolder, this value will be the ID of the previously selected folder.
`filterOptions.entryType`	`String`	Optional	Valid value: `folder`

Response

{
  "parentId":"drive-id-1"
  "data":[
    {
      "type":"folder",
      "name":"Folder 1",
      "id":"folder-id-1",
      "parentId":"drive-id-1"
    },
    {
      "type":"folder",
      "name":"Folder 2",
      "id":"folder-id-2",
      "parentId":"drive-id-1"
    }
  ]
}

Property	Type	Occurrence	Description
`parentId`	`String`	Required	The external service should return the same `parentId` value that was supplied in the List Directory Contents request.
`data`	`Object[]`	Required	An array of folders in the drive (or similar container type) or directory specified in the request’s `parentId` property.
`data.type`	`String`	Required	Valid value: `folder`
`data.name`	`String`	Required	The folder name. Maestro displays the `name` value in the folder list on the file output step configuration page.
`data.id`	`String`	Required	The folder ID. If a workflow process builder selects Add Subfolder during file output step configuration to drill down further in the directory structure, the `id` of the selected folder will be passed as the `parentId` in the List Directory Contents request.
`data.parentId`	`String`	Required	This value should be the same as the `parentId`.

Error handling

The external system should return a 200 response code to Docusign if a request succeeded. Any other response code indicates that the request was not successfully executed.

This applies to all actions and capabilities. Developers are responsible for providing a code and message for each error.

Next steps

Get an overview of the file output cloud storage extension and how it can be used.
Explore the options for testing a file output cloud storage extension.
Find out about other supported extensions.