How to automatically export Docusign agreement data to cloud spreadsheets

Simplify compliance for hiring workflows

Developers often build the processes that execute compliance checks and maintain records. To be prepared for audits, it can be helpful to record compliance checks in a single source of truth like a spreadsheet. 

But when that sheet must be updated manually, there’s a higher risk that entries might be missed or contain errors.

The file output tabular format extension eliminates the need for manual spreadsheet updates, simplifying compliance in common hiring workflows. When hiring, HR needs to verify employees’ identities, confirm their ability to work legally, and collect tax forms. Tracking these records is complex; missing a manual step quickly leads to outdated spreadsheets. 

The file output tabular format extension reduces that manual work. You can build an extension app that uses the file output tabular format extension to export data from steps in an agreement process to tabular format files stored in cloud storage systems, for example Excel sheets stored in SharePoint.

Follow these steps to build a hiring workflow with the file output tabular format extension:

1. Build an extension app manifest: Create an API service for Docusign to call and set up associated backend processing

2. Register the extension app with Docusign: Provide Docusign with the information it needs to send requests to your app.

3. Test the extension app: Use Docusign tools and procedures to verify the extension app functionality.

4. Publish the extension app: Initiate a review with Docusign to make the app available for production use.

5. Configure a Maestro workflow: Use the extension app in a hiring workflow containing multiple steps including a web form, identity verification, and the file output to tabular format extension app.

How to use the file output tabular format extension in hiring workflows

In a workflow, a file output tabular format extension writes Docusign data directly to cloud-based spreadsheets to log hiring compliance results.

Before the technical implementation, here is the end-user experience for this workflow. This example demonstrates how to complete the Right to Work check, a compliance requirement for all employers in the United Kingdom. This step verifies that all new hires are legally authorized to work in the UK. HR teams are responsible for verifying a prospective employee’s identity document, recording the employee’s share code (a personal identifier that proves a worker’s immigration status), and retaining the results of the verification for the employee’s tenure at the company. 

Here’s what that experience looks like at a high level:

1. The employee receives a link to start the workflow

2. The employee completes a web form, entering their identity information and share code if applicable.

3. If the employee is a UK or Irish citizen, they are directed to complete the identity verification process.

4. The employee’s information is written to a spreadsheet.

The employee receives a link to start the workflow

The prospective employee accesses the workflow via a link. This link could be emailed to the prospective employee or embedded in an HR application.

Depending on how you configure the workflow start method, you will run the workflow differently. In this example, the workflow start method is From a Link. To start workflows from within your own applications using the Maestro API, you’ll need to set the workflow start method to From an API call. Then, you’ll be able to trigger workflows through the API and embed the workflow steps in your website or application.

The employee completes a web form

The employee is directed to a web form that asks whether they are a UK or Irish citizen. If they are not a UK or Irish citizen, they will be asked to input their share code. The employee fills out and submits the form. Employees who input a share code have now completed their portion of the workflow.

UK and Irish citizens: Identity verification

Employees who indicate that they are UK or Irish citizens will be directed to complete the digital identity verification process. 

The employee’s information is written to a spreadsheet

The employee’s information, including their share code or identity document, is automatically written to a spreadsheet in cloud storage. 

The following sections explain how to build and tailor this solution to your needs.

How to implement an extension app

Extension apps integrate custom logic into Docusign processes by receiving and executing API requests.

Extension apps support several extension types. Each extension has a set of requests that Docusign sends to the extension app to implement the extension's features. For this use case, the file output tabular format extension is used. This extension's requests are triggered from a Maestro workflow. The request flow is shown below.

Build an extension app manifest

Your organization creates an extension app that can receive and respond to requests that Docusign sends to your app’s API endpoints. The following sections describe these requests. Details about the request and response formats appear in the file output tabular format extension contract reference.

List Drives request

Docusign sends this request when you configure a file output step in the workflow builder. The request returns a list of drives (or other container types) available in the cloud storage system. 

This request is optional. If it is implemented, a process builder can select the drive or other container type where files will be stored. If this request is not implemented, the destination drive will be determined by the extension app's logic.

An example List Drives response is shown here:

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

List Directory Contents request

Docusign sends this request during the file output step configuration to retrieve a list of folders and tabular format files in the cloud storage system.

This request is optional. If implemented, a process builder can drill down through the directory structure to open the correct folder and select a file where the data will be stored. If this request is not implemented, the destination folder and file are determined by the app’s business logic.

An example List Directory Contents response is shown here:

{
  "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"
    }
  ]
}

List Headers request

Docusign sends this request during the file output step configuration to verify that the selected destination file has enough columns to accommodate the number of variables being exported.

An example List Headers response is shown here:

{
    "success": true,
    "headers": [“Name”,”Email”,”Date”,”Amount"],
    "errorMessage": null
}

Export to Destination request

Docusign sends this request at workflow run time to write the values of workflow variables to the specified destination file. 

An example Export to Destination request is shown here:

{
  "destinationId": "abc123",
  "headers": ["Name”,”Email”,”Date"],
  "data": [
    [
       "John Doe”,”john@example.com”,”2024-10-24"],
       "Jane Smith”,”jane@example.com”,”2024-10-23"
    ]
  ]
}

IT infrastructure to support the extension app

The infrastructure to support an extension app includes these components:

• API proxy: Required if requests from Docusign are not in the format required by the extension app’s API endpoints, or if the responses are not in the format that Docusign expects.

• Authorization: The extension app must support the authorization parameters that Docusign sends and meet the authorization response requirements.

• Network configuration: Review the required network configuration to ensure Docusign can reach your app. 

Register the extension app with Docusign

Any extension app that will be called from Docusign agreement processes must be registered with Docusign. Registration provides Docusign with information it needs to obtain authorization from the extension app and send requests to its endpoints.

During registration, you have the option to choose private distribution instead of public if you want to make an app available only to specified Docusign accounts. You can also limit your app’s regional availability. 

Note: Only members of the Docusign Partner Program can publish a public extension app.

Extension apps can be registered in the Developer Console using a guided, form-based UI or by uploading a JSON extension app manifest file. Below is a sample app manifest file for an extension app that implements file output to cloud storage. Authorization parameters, including endpoint URLs, appear in the connections object. The extensions object specifies that this is a file output tabular format extension. The actions object defines each request type that Docusign will send to the external service, including the endpoint URL. See App manifest reference for details about the file structure and properties.

{
	"name": "File Output Tabular Format",
	"description": {
	  "short": "App for exporting data to a tabular format",
	  "long": "This app is designed to enable users to export data to tabular format files"
	},
	"icon": {
	  "data": "iVBORw0…Jggg==",
	  "mediaType": "image/png"
	},
	"screenshots": [],
	"publisher": {
	  "name": "Fontara",
	  "email": "sampleemail@fontara.com",
	},
	"termsOfServiceUrl": "https://www.fontara.com/tos",
	"privacyUrl": "https://www.fontara.com/privacy-security",
	"supportUrl": "https://www.fontara.com/support",
	"connections": [
	  {
		"name": "authentication",
		"description": "secure connection to the fileOutputTabularFormat proxy",
		"type": "oauth2",
		"params": {
		  "provider": "CUSTOM",
		  "scopes": [],
		  "clientId": "[omitted]",
		  "clientSecret": "[omitted]",
		  "customConfig": {
			"profile": {
			  "url": "https://www.fontara.com/api/oauth/userinfo",
			  "httpMethod": "GET",
			  "idKey": "sub",
			  "emailKey": "email"
			},
			"tokenUrl": "https://www.fontara.com/api/oauth/token",
			"authorizationUrl": "https://www.fontara.com/api/oauth/authorize",
			"authorizationParams": {
			  "access_type": "offline",
			  "prompt": "consent"
			},
			"authorizationMethod": "header",			
			"scopeSeparator": " ",
			"requiredScopes": []
		  }
		}
	  }
	],
	"extensions": [
	  {
		"name": "File Output Tabular Format",
		"description": "export tabular data to cloud storage",
		"template": "FileIO.Version1.FileOutputTabularFormat",
		"actionReferences": [
		  "list-headers",
		  "export-to-destination",
		  "list-directory-contents",
		  "list-drives"
		],
        "capabilities": [
		  "FileIO.Version1.ListDirectoryContents",
		  "FileIO.Version1.ListDrives"
		]
	  }
	],
	"actions": [
	  {
		"name": "list-headers",
		"description": "This is a description of my list headers action",
		"template": "FileIO.Version1.ListHeaders",
		"connectionsReference": "authentication",
		"params": {
		  "uri": "https://www.fontara.com/api/listHeaders"
		}
	  },
	  {
		"name": "export-to-destination",
		"description": "This is a description of my export to destination action",
		"template": "FileIO.Version1.ExportToDestination",
		"connectionsReference": "authentication",
		"params": {
		  "uri": "https://www.fontara.com/api/exportToDestination"
		}
	  },
	  {
		"name": "list-directory-contents",
		"description": "This is a description of my list directory contents action",
		"template": "FileIO.Version1.ListDirectoryContents",
		"connectionsReference": "authentication",
		"params": {
			"uri": "https://www.fontara.com/api/fileIOListDirectoryContents"
		}
	  },
	  {
		"name": "list-drives",
		"description": "This is a description of my list sites drives container contents action",
		"template": "FileIO.Version1.ListDrives",
		"connectionsReference": "authentication",
		"params": {
			"uri": "https://www.fontara.com/api/fileIOListdrives"
		}
	  }
	],
	"signupUrl": "https://www.fontara.com/signup",
	"publicationRegions": [
		"US"
	],
	"distribution": "PUBLIC"
  }

Test the extension app

After an extension app has been registered with Docusign, these Developer Console testing features verify that Docusign can access the extension app:

• Connection test: Verifies that Docusign can obtain authorization from the extension app

• Extension tests: Verify that Docusign can send requests to the extension app or API proxy endpoints and process the responses. For file output tabular format extension apps, there are a variety of extension tests that test each of the requests for the actions described previously including List Drives, List Directory Contents, List Headers, and Export to Destination.

For help with common errors such as authorization or API request failures, see the extension app Troubleshooting page.

Docusign also recommends performing a test from a Maestro workflow to confirm that the extension app is invoked from Maestro and exports values from the workflow correctly. See File output tabular format extension workflow test for details.

Publish the extension app

To use a file output to tabular format solution in production, you must submit the app for Docusign review. After Docusign approves it, you can publish it for use in the production environment. If you registered the extension app for public distribution, it will be available on the App Center for any Docusign user to install and use. If you registered the app for private distribution, it will be accessible only to your organization or your customers.

How to configure a Maestro workflow for the Right to Work check

A Maestro workflow is an object that represents your end-to-end agreement workflow, including all pre and post-signing steps. You can use the no-code Maestro workflow designer to build a workflow.

The example workflow described here includes steps that collect data in a web form, verify someone’s identity, and export data using the file output tabular format extension app described previously. The workflow also includes multiple branching rules so the flow of the process can differ depending on the prospective employee’s citizenship and the result of the identity verification step.

The completed workflow configuration looks like this:

Using the workflow template

You can build this workflow by starting with the Right to Work (UK) template in the Maestro template library. This template preconfigures the web form and identity verification steps for you, so the only additional configuration you need to do is update the last step in the template to use your extension app rather than writing a completed file to Google Drive.

To find the template, navigate to Templates in your developer account, and choose Workflow Templates in the left menu. The Right to Work (UK) template can be found under the HR section. Select Use Template to create a new workflow in your account using the template.

Configuring a file output tabular format step

By default, the template uses the Google Drive extension app to store verification documents. For this example, that step will be replaced by a file output tabular format step using the extension app implementation described. Alternatively, you can add the file output tabular format step after the Google Drive step, or make any additional customizations to fit your use case.

When adding this step to a workflow, you select your extension app. For the extension app to appear in the step selection list, it must be registered with Docusign and installed and connected to the Docusign account in which the workflow is being created.

During file output tabular format step configuration, you can:

• Select a drive or other container type on the cloud storage system. The step configuration page allows this selection only if the extension app implements the List Drives request.

• Select the tabular format file to which you will export the data. The step configuration page allows this selection only if the extension app implements the List Directory Contents request.

• Choose the variables whose values will be exported to the sheet by the Export to Destination request. Ensure you export the employee’s share code and identity verification details.

After configuring the file output tabular format step, you can save and publish the workflow. 

Build your own file output to tabular format extension app

A file output tabular format implementation can help ensure compliant hiring processes by making it easy to pull data from agreement workflows and store it in spreadsheets. 

The Docusign for Developers suite of tools provides everything you need to develop an application tailored to your organization’s or your customers’ specific business cases. To take the first steps, visit the Docusign Developer Center to sign up for a free developer account and learn more, or explore the benefits of the Docusign Partner Program. Ready to try it? Get started with our file output to tabular format reference implementation.

Have questions or need help implementing this? Ask in the Docusign Community's Developer Forum.

Additional resources

• Read an introduction to the file output tabular format extension.

• Get details about the extension’s requests and responses.

• Learn what you can do with Maestro workflows.

• Get an overview of the Maestro API.

• Learn how to trigger workflows with the Maestro API.