> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL. > > Documentation indexes by section: > - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt > - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt > - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt > - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt > > Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth > Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks > > OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json > MCP server: https://docusign.docs.buildwithfern.com/_mcp/server # File output cloud storage extension contract reference > Get technical details about file output cloud storage extension requests and responses. The file output cloud storage extension writes documents generated from a Workflow Builder workflow [Send Documents for Signature step](https://support.docusign.com/s/document-item?bundleId=yff1696971835267\&topicId=uww1698167288211.html) to a cloud storage platform. You can include this extension when you [register an extension app](/extension-apps/build-an-extension-app/register). If you register the extension app [using a form](/extension-apps/build-an-extension-app/register/use-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](/_fern-files/_img/7f379b402da8cea7a9754d8da8145e82fcb4c0c615b85731de49224926efebb9.webp) > **Note** > > During the form-based extension app registration process, if you select a [file IO extension](/extension-apps/extension-apps-101/supported-extensions), its required actions are automatically added to the app. You can then configure the actions' endpoint URIs and other properties on the [Integration Details](/extension-apps/build-an-extension-app/register/use-form/integration-details) page. The extension's optional capabilities can be added or removed only by [editing the app manifest file](/extension-apps/build-an-extension-app/update-registration/use-manifest). After you've added capabilities via the manifest file, you can edit them on the Integration Details page. See [Action schema](/extension-apps/extension-app-reference/app-manifest-reference/action) for information about action and capability properties in the app manifest file. If you register the extension app [using an app manifest file](/extension-apps/build-an-extension-app/register/use-manifest), 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](/extension-apps/build-an-extension-app/example-use-case) 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: ```text "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: ```text "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](/extension-apps/extension-apps-101/supported-extensions/file-output-cloud-storage#file-output-cloud-storage-actions-and-capabilities). > **Note** > > When registering an extension app, you cannot include both a [file output system of record extension](/extension-apps/extension-apps-101/supported-extensions/file-output-system-of-record) and a [file output cloud storage extension](/extension-apps/extension-apps-101/supported-extensions/file-output-cloud-storage) 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](/extension-apps/build-an-extension-app/register/use-form). If you register your extension app [using an app manifest file](/extension-apps/build-an-extension-app/register/use-manifest), make sure that you: 1. Include a definition for the action in the `actions` object. See [Action schema](/extension-apps/extension-app-reference/app-manifest-reference/action) 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` 2. Include the value from the `actions.name` property in the `extensions.actionReferences` array. See [Extension schema](/extension-apps/extension-app-reference/app-manifest-reference/extension) for details. See [Example extension app use cases](/extension-apps/build-an-extension-app/example-use-case) 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 Request with hardcoded folder and file names: ```text { "files": [ { "contents": "JVBERi...VFT0YK", "basename": "MyFileName.pdf", "path": "MyFolder/MyFileName.pdf", "pathTemplateValues": [ ] } ], "rootId": "root" } ``` #### Example request 2 Request with folder and file names containing hardcoded text and variables: ```text { "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" } ``` | 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](/_fern-files/_img/b8fa90c908be309a6b8573a1fcc1859f14664b8dd34a1e9f2d0f68ee746b485d.webp) 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](/_fern-files/_img/0a0ce0082814fb592da0a5e9e797e9530223f7a7ea82fd0239a1029f92205922.webp) 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: ```text { "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: 1. Replace `{{``Account owner Name``}}` with `Test Customer` 2. Replace `{{``Send Documents for Signature.Envelope ID``}}` with `11721000-xxxx-xxxx-xxxx-2a498b65b09b` 3. 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 ```text { 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](/extension-apps/build-an-extension-app/test/integration-tests#run-an-extension-test) is run. It is not displayed to end users during workflow instance execution. | #### List Drives (FileIO.Version1.ListDrives) This optional [capability](/extension-apps/extension-apps-101/concepts/capabilities) 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](/extension-apps/build-an-extension-app/register/use-form). If you register your extension app [using an app manifest file](/extension-apps/build-an-extension-app/register/use-manifest), make sure that you: 1. Include a definition for the capability in the `actions` object. See [Action schema](/extension-apps/extension-app-reference/app-manifest-reference/action) 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` 2. Include the value from the `actions.name` property in the `extensions.actionReferences` array. 3. Include the value from the `actions.template` property in the `extensions.capabilities` array. See [Extension schema](/extension-apps/extension-app-reference/app-manifest-reference/extension) for details about the `actionReferences` and `capabilities` arrays. See [Example extension app use cases](/extension-apps/build-an-extension-app/example-use-case) 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 ```text { "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 ```text { "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:1) A workflow process builder selects from a list of drives (or other containers) on the file output step configuration page. 2) The process builder selects **Add Folder** on the step configuration page. 3) 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](/extension-apps/extension-apps-101/concepts/capabilities) 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](/extension-apps/build-an-extension-app/register/use-form). If you register your extension app [using an app manifest file](/extension-apps/build-an-extension-app/register/use-manifest), make sure that you: 1. Include a definition for the capability in the `actions` object. See [Action schema](/extension-apps/extension-app-reference/app-manifest-reference/action) 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` 2. Include the value from the `actions.name` property in the `extensions.actionReferences` array. 3. Include the value from the `actions.template` property in the `extensions.capabilities` array. See [Extension schema](/extension-apps/extension-app-reference/app-manifest-reference/extension) for details about the `actionReferences` and `capabilities` arrays. See [Example extension app use cases](/extension-apps/build-an-extension-app/example-use-case) 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 Request when **List Directory Contents** is called after after a process builder selects a drive (or similar container type) and then selects **Add Folder**: ```text { "filterOptions": { "entryType": "folder" }, "parentId": "drive-id-1" } ``` #### Example request 2 Request when **List Directory Contents** is called after after a process builder selects **Add Folder** if the **List Drives** capability has not been implemented: ```text { "filterOptions": { "entryType": "folder" }, "parentId": "root" } ``` #### Example request 3 Request when **List Directory Contents** is called after a process builder selects **Add Subfolder**: ```text { "filterOptions": { "entryType": "folder" }, "parentId": "folder-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 ```text { "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](/extension-apps/extension-apps-101/supported-extensions/file-output-cloud-storage) of the file output cloud storage extension and how it can be used. * Explore the options for [testing](/extension-apps/build-an-extension-app/test) a file output cloud storage extension. * Find out about other [supported extensions](/extension-apps/extension-apps-101/supported-extensions).