File output system of record test: Workflow step creates envelopes (beta) | Docusign

This procedure explains how to set up and execute a functional test that invokes a file output system of record extension from a workflow. For this test, you configure and run a workflow that displays a document for signature and writes the signed document to a system of record.

The files to be exported are generated by the workflow’s Send Documents for Signature step. To test a scenario in which any envelope sent from the account can be stored to the system of record if it meets certain conditions, follow the procedure in File output system of record test: An event triggers the workflow. See Identify the file source for information about the two options.

The high-level steps to create and run this test are:

This is one of many possible approaches to setting up a workflow. For additional options, see the workflow user documentation.

Make sure that you’ve completed all the requirements listed for functional tests in Test prerequisites.

Step 1. Identify or create an eSignature template

Before you create the workflow, make sure that you have an eSignature template in your account that you can use in a signing step in the workflow. The document to be signed in that step will be derived from the template. You can use an existing eSignature template in your account, or create a new template.

When selecting or creating a template:

For a simpler workflow setup, the template should have a single recipient instead of multiple recipients.
The recipient type must be Needs to Sign.
Do not hard-code a recipient name or email in the template.
Make sure that the template document includes, at minimum, a Signature tab.

See Template Requirements for additional information about templates to be used with a workflow signing step.

Step 2. Create and publish the workflow

To create a workflow that tests a file output system of record extension:

Log in to the Workflow Designer.
Follow the steps in Create a Basic Workflow to create and save a workflow. When creating a workflow, select Blank Workflow. Your workflow should include:
- The workflow start method From within Maestro.
- A step that defines an eSignature template containing a document to be signed. See Prepare eSignature Template step for configuration guidelines.
- A step that displays a document for signature. See Send Documents for Signature step for configuration guidelines.
- A step that invokes your extension app to write the signed document to the system of record. See File output system of record extension step for configuration guidelines.
- A step that displays a message confirming that all workflow steps are complete. See Show a Confirmation Screen step for configuration guidelines.
  
  When youʼve finished configuring the start method and the steps, the workflow should appear as shown.
Complete the steps in Review and Publish a Workflow. Then you can execute instances of the workflow to test your extension app.

Prepare eSignature Template step

The first step in your workflow should be a Prepare eSignature Template step. A procedure for adding this type of step appears in Configure a Prepare eSignature Template step.

When you add this step, configure the settings as follows:

Setting	Value
Select a template	Select the eSignature template that you created for the workflow test, or an existing template that you’ve identified for use with the test. See Step 1. Identify or create an eSignature template for more information.
Mapping fields	Optional. This enables you to populate fields on the document with values from the workflow, so that you don’t have to enter values during the signing process when you execute the test.

Send Documents for Signature step

The next step in your workflow should be a Send Documents for Signature step, which generates an eSignature envelope for the user to sign. A procedure for adding this type of step appears in Configure a Send Documents for Signature Step.

When you add this step, configure the settings as follows:

Setting	Value
What documents would you like to send?	Select the template associated with the Prepare eSignature Template step.
How should we send the envelope?	Select Automatically.
Confirm recipient details	The role name associated with the recipient from your eSignature template is displayed here. Under Match the template’s signer recipient to one of this workflow’s participants, select User who starts this workflow. Under User who starts this workflow name, select the option to search users, contacts, and groups. You can then select from a list of users associated with your account.
Choose direct or remote signing	Select Use a direct signing session.

File output system of record extension step

This step will invoke your extension app.

To add this step, display the Apps tab on the Add New Step panel and select the extension thatʼs defined in your extension app registration. The Add New Step panel displays the values from the extensions.name and extensions.description properties in the app manifest.

Note: The step for your extension will not appear in the Connected Apps list if the extension app is not installed and connected to your account.

When you configure this step, the Get Type Names capability will be invoked to retrieve a list of objects in the system of record. When you execute an instance of the workflow, this step invokes the Write File action.

When you add this step, configure the settings as follows:

Setting	Value
What are you storing?	Select Combined Envelope File under Send Documents for Signature.
Where are you storing it?	Select connection: Select the default connection. Select record: Select a workflow variable whose runtime value should be sent with the Write File request. This should be a value that the external system can use to uniquely identify the record to write the file to. See Workflow variables for information about the variables that you can select. Object: Select the system of record object to write files to. The list is populated with objects returned by the Get Type Names request to the external system.
What will you call it?	Define a naming convention for the file. The naming convention can include hardcoded text, workflow variables, or a combination of the two.

Workflow variables

When defining the File Output step, you can include workflow variables for the record identifier and file naming convention. Variables will be populated with values at workflow instance run time.

The types of variables available for selection include:

Workflow step variables. For example, variables associated with the Send Documents for Signature step include the unique ID of the eSignature envelope and values from the envelope fields.
Workflow participant variables. These are values associated with the customer who completes the steps in a workflow instance. They include the name and email address.
Workflow instance variables. These are values associated with the workflow instance, such as the instance ID and the start date and time.

Show a Confirmation Screen step

The last step in your workflow should be a Show a Confirmation Screen step, which displays a message to indicate that the workflow is complete. A procedure for adding this type of step appears in Configure a Show a Confirmation Screen Step.

When you add this step, configure the settings as follows:

Setting	Value
Participant	User who starts this workflow
Message type	End of participantʼs tasks
Message title	Keep the default value
Message body	Keep the default value

Step 3. Execute a workflow instance

After you’ve published your test workflow, you can execute an instance of it, run through the steps as a customer would, and make sure that the file is written to the system of record successfully. You can monitor the progress of the workflow instance as it executes.

To execute a workflow instance:

Follow the steps in the From Within Workflow Builder section of How to Start a Workflow to execute a workflow instance. The document to be signed is displayed in your browser.
Complete the signing process. The File Output step is executed and the confirmation page is displayed.
Check the object and record to which the external service stores files, and confirm that the File Output step succeeded.

If your extension is not invoked successfully, run the Developer Console connection and extension tests for the extension app to get detailed error messages and troubleshoot.

Next steps

Find out more about functional tests.
Review the File output system of record extension contract reference.
Learn how to run integration tests.