File output cloud storage extension overview | Docusign

The file output cloud storage extension exports completed agreements to a cloud storage service. Agreements are written to cloud storage in real time as customers complete tasks in a workflow. For example, a workflow for adding an account beneficiary can automatically store the beneficiary document after a customer has signed it.

Docusign offers extension apps that integrate with Google Drive, Dropbox, Box, OneDrive, and SharePoint. If you want to store files to these services, visit the Docusign App Center for details.

Use a file output cloud storage extension in a workflow

After a file output to cloud storage extension app has been installed and connected to a Docusign account, a workflow process builder can include a step that invokes the extension. In the example described here, a process builder defines a workflow that adds a beneficiary to a financial account. The workflow steps include:

A customer supplies beneficiary information in a web form and submits it.
The customer completes an eSignature envelope to confirm the beneficiary update.
The extension writes the completed envelope to the cloud storage system.

Expand the sections below to see how a file output cloud storage extension functions during workflow configuration and execution. See File output cloud storage actions and capabilities for details about the functionality.

Workflow configuration: The process builder selects the extension

When adding a workflow step to write a file to cloud storage, the process builder selects the extension that has been installed to their Docusign account.

File output step selection

Workflow configuration: The process builder selects a drive

The process builder configures the file output step. During step configuration, the file output cloud storage extension can be invoked to list the drives in the cloud storage system. This enables the process builder to select the destination drive for completed agreements.

Drive selection is an optional capability for file output to cloud storage. If the extension does not implement this feature, process builders will not be able to select a 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 extension can retrieve a list of those containers instead. They will appear in the step configuration pageʼs Select drive list.

File output step drive selection

Workflow configuration: The process builder selects a folder

Another configuration option is the ability to select a destination folder on the cloud storage system. The file output cloud storage extension can be invoked to display a list of folders in a drive or directory. After selecting a folder, the process builder can drill down further in the folder structure by displaying a list of subfolders in the current directory, which again invokes the extension. This process continues until the process builder selects a destination folder in which to store completed agreements.

The process builder can also define a naming convention for a new folder to be created during workflow execution. The naming convention can include hardcoded text; variables whose values are specific to each workflow instance, such as the envelope ID or signer name; or a combination of the two.

Folder selection is an optional capability for file output to cloud storage. If the extension does not implement this feature, process builders will not be able to select a folder.

File output step folder selection

Workflow configuration: The process builder defines a file naming convention

The process builder defines a naming convention for files written to cloud storage. File names can consist of hardcoded text; variables whose values are specific to each workflow instance, such as the envelope ID or signer name; or a combination of the two.

File output step file name definition

Workflow execution: The customer completes a web form

When the example workflow is executed, the customer’s first step is the completion of a web form. The customer populates information about the beneficiary to be added to the account and submits the form.

Web form step in workflow instance

Workflow execution: The customer completes an eSignature envelope

In the next workflow step, the submitted beneficiary information from the form is populated automatically in an eSignature envelope, and the customer signs and completes the envelope.

Workflow instance signature step

Workflow execution: The completed envelope is written to cloud storage

After the customer has completed the eSignature envelope, the workflow reaches the file output step. The file output cloud storage extension is invoked to store the completed envelope in the drive and folder that the process builder selected, using the specified naming convention.

Workflow instance write file step

File output cloud storage actions and capabilities

A file output cloud storage extension implements the actions and capabilities listed below. Both actions and capabilities send requests to an external API service. Actions are required and provide the core functionality for an extension. Capabilities are optional and offer additional features to enhance the core functionality.

Action or capability	Executed when	Description
Write File action	A running workflow instance reaches a file output step that stores a completed agreement in a cloud storage system.	Required. Writes a completed agreement file to the cloud storage system. If the file output cloud storage extension implements List Drives, the file is written to the drive (or similar container type) that the process builder selected during workflow configuration. If the extension implements List Directory Contents, the file is written to the folder that the process builder selected.
List Drives capability	While configuring a file output to cloud storage workflow step, a process builder selects a connection. If only one connection is available, this request is sent when the step configuration page loads.	Optional. Gets a list of drives on the cloud storage system. This enables the process builder to select a destination drive. This capability is appropriate for cloud storage systems that have drives or similar structures that contain folders and files.
List Directory Contents capability	While configuring a file output to cloud storage step, a process builder selects Add Folder or Add Subfolder to display a list of folders.	Optional. Gets a list of the folders in the selected drive (or similar container type) or directory on the cloud storage system. This enables the process builder to select a destination folder from a list of existing folders or to specify a naming convention for a new folder.

Workflow configuration requests to the external system

This flow shows how the file output cloud storage extension’s optional capabilities can be invoked during configuration of a Maestro workflow. These capabilities enable a process builder to configure a file destination in the cloud storage system.

This flow describes the sequence of calls to the external system when an extension app implements the optional List Drives and List Directory Contents capabilities. An extension app that writes to cloud storage can be implemented without these capabilities. See External system logic to return file output destination options for details.

List Drives capability: When a process builder configures a file output step, Docusign sends a List Drives request to the external system to retrieve a list of drives or similar structures that contain folders and files. The file output step configuration page displays the list in a dropdown.

List Directory Contents capability: The process builder’s selection of the Add Folder button on the step configuration page causes Docusign to launch a List Directory Contents request. The page displays the folder names from the response in a dropdown. The process builder selects the destination folder for files that will be written to cloud storage. To drill down further in the directory structure, the process builder can select Add Subfolder one or more times, and a List Directory Contents request is launched each time.

Workflow instance runtime requests to the external system

This flow shows how the file output cloud storage extension is invoked during the execution of a workflow instance.

Write File action: When a running workflow instance reaches a file output to cloud storage step, Docusign sends a Write File request to the external system. The request includes a Base64-encoded string representing the file contents, as well as naming details for the file and the location where it should be stored. The external system responds with a message indicating the result.

Plan a file output to cloud storage implementation

These sections describe options that should be considered when planning a file output to cloud storage implementation:

Extension implementation details

Your implementation choices for the file output cloud storage extension determine the details of how files are written to cloud storage. See the next two sections for guidance.

External system logic to return file destination options

The file output cloud storage extension supports capabilities that enable workflow process builders to select the location where completed agreements will be archived. Below are the available options and the capabilities that enable each option.

To enable the process builder to	Implement this capability
Select a drive or similar structure that contains folders and files	List Drives
Select an existing folder at any level in the directory structure, specify the creation of a new folder, and define a naming convention for new folders	List Directory Contents
Select a drive or similar structure, select an existing folder at any level in the directory structure, specify the creation of a new folder, and define a naming convention for new folders	List Drives and List Directory Contents

If the extension enables the process builder to select a drive (or similar container type) and/or a folder, at workflow instance runtime, Docusign sends the configured container and/or folder path with Write File requests.

If the app does not implement capabilities to allow process builders to select a file destination, Write File requests will include a file naming convention only. The external system must implement logic to select a storage location. If the cloud storage system has a structure similar to Google Drive, Docusign recommends implementing both the List Drives and List Directory Contents capabilities.

See the file output cloud storage extension contract for details about the request formats and the expected response formats. See API proxy for guidance about transforming requests and responses to the correct format.

External system logic to process Write File requests

Docusign includes the file contents, a file naming convention, and, optionally, a drive (or similar container type) and/or a folder in Write File requests.

Some considerations for the external system logic to process these requests include:

If the extension does not implement capabilities that allow a workflow process builder to specify a storage location, how will the external system select a location when it receives a request to write a file?
Both the file and folder name in the request can include variables whose values are populated during workflow instance execution. The external system must implement logic to construct the folder and/or file names from the variable values in requests. See Write File for details.
Will the external system allow an existing file to be overwritten, if the file name in the request already exists in the specified directory? If not, will it write the file with a different name or return an error?

For details about the Write File request and response formats, see the Write File action contract. See API proxy for guidance about transforming requests and responses to the required format.

Configuration options and restrictions

Workflow Builder workflows are highly customizable and offer many possibilities for constructing the steps in an agreement process. To write files to cloud storage, a workflow must be configured with these steps at minimum:

Send Documents for Signature step. This is a step in which a customer completes an eSignature envelope. Detailed requirements and the process to define this type of step appear in Configure a Send Documents for Signature Step.
File output step. This step invokes the file output cloud storage extension. This step will be available to workflows in any Docusign account that has the extension app installed and connected.

You can add other types of steps as needed based on business requirements. For a walkthrough of the process to define a simple workflow that invokes a file output cloud storage extension, see File output cloud storage extension workflow test.

These restrictions apply when implementing file output to cloud storage:

When you register an extension app, you cannot include both a file output cloud storage extension and a file output system of record extension in the same app. If you need to use both types of output in workflows, register a separate app for each extension.
Only envelopes generated from a workflow Send Documents for Signature step can be written to cloud storage.
The maximum supported size for a file to be written to cloud storage is 10 MB. The workflow process builder must ensure that the template selected in the Send Documents for Signature step is within this limit.
If multiple envelopes are to be written to cloud storage, the process builder must define a separate file output to cloud storage step for each envelope.

Mechanisms for starting workflow instances

Docusign supports multiple options for starting workflow instances that write files to cloud storage. A workflow instance is a runtime execution of workflow steps that enables a customer to complete tasks such as filling out a form and signing an agreement.

To review the options for starting workflow instances manually, see How to Start a Workflow.

To start workflow instances programmatically, you can implement a Docusign Workflow Builder API integration that includes the Workflows: triggerWorkflow request. See Workflow Builder API 101 overview for an introduction to the API, and see How to trigger a Workflow Builder workflow for example code and a detailed walkthrough.

Next steps

Get an overview of the process to build an extension app.
See File output cloud storage extension contract reference for details about the action and capability requests and responses.
Learn how to programmatically trigger workflows that write files to cloud storage.