Skip to navigation
Extension apps 101Supported extensionsFile output system of record overview

Plan an implementation (beta)

View as Markdown

These sections describe options that should be considered when planning a file output to system of record implementation:

External system logic to process Write File requests

Docusign sends Write File requests during workflow instance execution to write one or more files to the system of record. The format of the request can vary depending on how a process builder has configured the workflow. See Workflow configuration for file output scenarios for more information.

The simplest scenario for a Write File request is one that includes a single file and specifies:

  • The file contents as a Base64 string in contents
  • The data source object name in rootId
  • A value that the external system uses to identify the destination record in parentID
  • A file name in basename

For example:

{
  "files": [
    {
      "basename": "EFTAuthorization.pdf",
      "path": "",
      "pathTemplateValues": [
      ],
      "parentId": "1227",
      "contents": "JVBERi...VFT0YK"
    }
  ],
  "rootId": "FinancialAccount"
}

Note: The request does not identify the data source property to which files should be written, so the external system logic must handle this.

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

Depending on how the workflow has been configured, the Write File request may have one or more variations in its values. These scenarios are described in the next sections.

Options for record identifier

Depending on how a process builder configures a File Output step, the value that a Write File request includes in the parentId can be any of the following:

  • A workflow variable value derived from the workflow start method or a previous workflow step
  • A data source record ID returned by a Read from step in the workflow
  • Another type of data source record value returned by a Read from step

The external system logic to identify a record to write to should handle these possibilities. See Identify destination records for more information.

Request includes multiple files

If a workflow is configured to start from an event, the File Output step configuration panel gives process builders the option to store envelope files individually. This can result in a Write File request that includes multiple files, and the external system logic should handle this. If the data source does not support writing multiple files to the same record, process builders should not select the option to store files individually. See Envelopes sent from the account for more information.

File names contain variables

File names in Write File requests can include variables whose values are populated during workflow instance execution. The external system must implement logic to construct the file names from the variable values in requests. See File names that include workflow variables for more information.

Mechanisms for starting workflow instances

Docusign supports multiple options for starting workflow instances that write files to a system of record. 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.

File output system of record restrictions

These restrictions apply when implementing file output to a system of record:

  • When you register 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.
  • The maximum supported total size for the files in a Write File request is 25 MB.
  • If files from multiple envelopes are to be written to the system of record, the workflow process builder must define a separate file output step for each envelope.

Next steps