Skip to navigation
Extension app referenceExtension contractsFile IO

File input system of record extension contract reference (beta)

View as Markdown

This extension can be invoked from a step in a Workflow Builder workflow to retrieve files from a system of record. The files to import can be identified using workflow data, such as values captured earlier in the workflow or returned from other extension steps. See File input system of record extension overview for details about how the extension is invoked in Workflow Builder and other behaviors and restrictions.

The file input system of record extension defines a structured interface between Docusign and the external service provider:

  • Docusign initiates a request for files using context data populated by the workflow users.
  • The external system identifies the relevant records and returns the corresponding file metadata.
  • Docusign retrieves each document through a secure, managed pipeline for ingestion.

You can include this extension when you register an extension app. If you register the extension app using a form, select the File Input System of Record extension in the form-based UI, as shown in this figure:

form based UI extension selecton

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, make sure that you:

  • Set the extensions.template value in your app manifest to FileIO.Version1.GetFiles.

  • Include a definition for the required action in the actions object, using these values:

    • name: get-files
    • template: FileIO.Version1.GetFiles

  • Include the value from the actions.name property in the extensions.actionReferences array.

See Update extension and action settings for information about defining actions using the form-based registration process. See Action schema for information about action properties in the app manifest file.

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

A file input system of record extension app requires the GetFiles action. This action is executed when a Maestro workflow reaches a file input system of record step, triggering a request to the external system to retrieve documents from the system of record. The retrieved files are then available for use in downstream workflow steps, such as a Prepare eSignature Template step or a Send Documents for Signature step.

See Example extension app use cases for a complete sample app manifest for file input from system of record.

HTTP method

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

Request

{
  "containerId": "Loan Applications",
  "filterOptions": {
    "type": "fileNameContains",
    "nameFilter": "Jane Doe"
  }
}
PropertyTypeOccuranceDescription
containerIdStringRequiredA comma-separated string containing values that reference a container where files are hosted.
This string is used to locate files and can include:
- For Systems of Record: recordType and recordId, or just the recordId.
- For Cloud Providers: siteId, driveId, folderPath, and other relevant identifiers.
filterOptionsObject[]RequiredAn array of properties used to filter files in the system of record.
The filterOptions array contains the filterOptions.type and filterOptions.nameFilter elements.
When configuring the File Input System of Record step, the workflow process builder sets the value of the above elements to locate specific documents.
filterOptions.typeStringRequiredA string that determines how the action selects which files to retrieve from the external system of record during workflow execution.
Valid values:
- allFiles: Retrieves all files associated with the record identified by the containerId. Used when the entire document set is required.
- fileNameContains: Retrieves only files whose names contain a specified value or pattern. Used to target specific document types (for example, “Loan Estimate” or “ID Document”).
-latestDocumentOnly: Retrieves the most recent document that matches the criteria, typically the most recently created or updated file.
filterOptions.nameFilterStringRequiredA substring to match file names. Required only if filterOptions.type is set to fileNameContains.

Response

{
  "files": [
    {
    	"documentId": "dms_blob_id_98765",
    	"format": ".pdf",
    	"fileName": "Jane Doe - Credit Report",
    	"source": "Fontara System of Record",
    	"size": 76659
  	 }
  ]
}
PropertyTypeOccurenceDescription
filesObject[]RequiredThe object containing metadata for each imported file.
files.documentIdStringRequiredThe unique identifier for a file object stored in the Document Management System (DMS)
files.formatStringRequiredSpecifies the document file format using a MIME type string. See the List Directory Contents request body for more information about supported MIME types.
files.fileNameStringRequiredName of the file as defined in the system of record
files.sourceStringRequiredIdentifies the originating system (for example, Salesforce)
files.sizeStringRequiredSpecifies the file size in bytes. Each document is limited to 10 MB, or a maximum of 100 MB per request.

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. Developers are responsible for providing an error code and message for each error.

Next steps