Data IO extension workflow test | Docusign

These procedures explain how to set up and execute a functional test that invokes a data IO extension from a Workflow Builder workflow. For this test, you run a workflow that reads data from your external system, populates web form fields with the retrieved values, and writes values from the web form to the external system.

Note: You can configure a data IO extension so that it reads from an external system, but does not write to it. See Data IO extension contract reference for details. When setting up a workflow, you can omit the data read step or data write step if you only want to test one of these operations.

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.

Walkthrough playlist: You can also see a video overview of the data IO extension workflow test using the Data IO Reference Implementation below:

Step 1. Identify or create a web form

Before you create the workflow, make sure that your developer account has a web form that you can use in a data collection step in the workflow. You can use an existing web form in your account, or create a new web form.

When selecting or creating a web form:

The web form must be standalone. Web forms that are derived from eSignature templates cannot be used in workflows. Web Form Requirements and Data-Mapping Information explains how to create a standalone web form.
The web form should contain fields that correspond to fields in your external system. This enables you to test your extension by populating web form fields with values retrieved from the external system and/or writing web form field values to the external system.
Each web form field has a Field name property, which appears on the Properties panel in the Web Forms builder. Field names are also listed on Workflow Builder screens that map web form fields to external system fields. Make note of the field names in the Web Forms builder so that you can easily identify web form fields when configuring workflow steps in Workflow Builder.

Step 2. Create and publish the workflow

To create a workflow that tests a data IO 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 participant who fills out the web form. See Workflow participant for configuration guidelines.
- Optional: A step that invokes your extension to read external system data so that the values can be populated in the web form. See Data read step for configuration guidelines. If you want to test writing data but not reading data, omit this step.
- A step that displays a web form. See Collect Data with Web Forms step for configuration guidelines.
- Optional: A step that invokes your extension to write data collected in the web form to the external system. See Data write step for configuration guidelines. If you want to test reading data but not writing data, omit this step.
- 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, the workflow participant, and the steps for a test of both reading and writing data, the workflow should appear as shown. If you want to test reading data only or writing data only, do not include the unneeded step in the workflow.
Complete the steps in Review and Publish a Workflow. Then you can execute instances of the workflow to test your extension app.

Workflow participant

Although a workflow can have multiple participants, you only need one for a workflow that invokes a data IO extension. Create a Basic Workflow has information about configuring a participant. The participant role name that you enter will be displayed on configuration screens for workflow steps that require selection of a participant.

Data read step

Note: If you do not want to test reading data from an external data source, omit this step from the workflow.

This step will invoke your data IO extension to search for records in the external system and read values from them. This step tests the Search Records action.

When you add this step, you select the data read function for your extension. The workflow step dropdown displays Read from followed by the App name you selected when you registered the extension app via the form-based process, or the value from the name property in the app manifest if you registered the extension app by uploading an app manifest file.

Workflow read step selector

The Read from step for your extension will not appear in the dropdown if:

The extension app is not installed and connected to your account.
The Get Type Names and Get Type Definitions actions, which are executed when the connection is established, did not succeed. If you suspect that this is the case, run the Developer Console connection and extension tests to troubleshoot.

Configure the settings for this step as follows:

Setting	Value
Where will you read from?	Connection: Select the default connection [extension app name] object: Select the object type in the external system to read data from. The objects listed are those the Maestro service retrieved when it executed the Get Type Names action.


Which fields would you like to read?	Select Add or Remove Fields to choose the fields whose values the Maestro service should retrieve. The Add or Remove Fields page lists all fields in the selected source object that were returned by the Get Type Definitions action. In addition, the page lists any objects related to the source object that were included in the data model information returned to Docusign. You can select a related object, and then select fields in that object to read. Embedded objects are also listed, and their fields can be selected as well. Select fields that you can map to fields in the web form that you’ll use in the Collect Data with Web Forms step. You’ll configure that step to populate web form fields with values retrieved from the external system.

Which fields would you like to read?

Select Add or Remove Fields to choose the fields whose values the Maestro service should retrieve.
The Add or Remove Fields page lists all fields in the selected source object that were returned by the Get Type Definitions action. In addition, the page lists any objects related to the source object that were included in the data model information returned to Docusign. You can select a related object, and then select fields in that object to read. Embedded objects are also listed, and their fields can be selected as well.
Select fields that you can map to fields in the web form that you’ll use in the Collect Data with Web Forms step. You’ll configure that step to populate web form fields with values retrieved from the external system.


Which record are you reading from?	Add rules that the Maestro service will use to identify records to read data from. When defining a rule, you select a data source field, an operator, and a workflow field to compare to the data source field. For the data source field, you can select any field that was configured in the Which fields would you like to read setting. This includes fields from related and embedded objects, which are listed in the [app name] field list by object name followed by (reference). To select a field from a related or embedded object, you first select the object name and then select a field from the object. For testing purposes, select Manual entry under Workflow field, and then hard-code a value. To define additional rules, select the AND or OR button. Note: When the workflow is executed, the read step will fail if no record in the data source meets the criteria. Maestro uses only the first five records in the response in subsequent workflow processing. You can use the preview feature to see which records the search will return. See Configure a Read from Salesforce Step for details about previewing query results.

Which record are you reading from?

Add rules that the Maestro service will use to identify records to read data from.
When defining a rule, you select a data source field, an operator, and a workflow field to compare to the data source field. For the data source field, you can select any field that was configured in the Which fields would you like to read setting. This includes fields from related and embedded objects, which are listed in the [app name] field list by object name followed by (reference). To select a field from a related or embedded object, you first select the object name and then select a field from the object.
For testing purposes, select Manual entry under Workflow field, and then hard-code a value.
To define additional rules, select the AND or OR button.
Note: When the workflow is executed, the read step will fail if no record in the data source meets the criteria. Maestro uses only the first five records in the response in subsequent workflow processing.
You can use the preview feature to see which records the search will return. See Configure a Read from Salesforce Step for details about previewing query results.

Collect Data with Web Forms step

A Collect Data with Web Forms step displays a web form consisting of fields in which a participant can supply values. A procedure for adding this type of step appears in Configure a Collect Data with Web Forms Step.

Configure the settings for this step as follows:

Setting	Value
Which form would you like to use?	Select the web form that you created for the workflow test, or an existing web form that you can use. Only standalone web forms are available for selection. See Step 1. Identify or create a web form for more information.
Who will participate in this step?	Select the role name you entered when you configured the workflow participant.


Map data fields	Note: If your workflow does not include a data read step, do not map data fields. This section maps web form fields to fields in the external system. The form fields will be populated with values retrieved from the external system via the data read step when you execute the workflow. The configuration screen lists all web form fields. You are not required to map every form field to a field in the external system. To map a form field: Select the dropdown below the form field name. Scroll to the Workflow Steps list. Select the data read step. Select the external system field whose value should be displayed in the web form field. Note: The only external system fields available to select are those you configured in the Which fields would you like to read? section of the data read step.

Map data fields

Note: If your workflow does not include a data read step, do not map data fields.
This section maps web form fields to fields in the external system. The form fields will be populated with values retrieved from the external system via the data read step when you execute the workflow.
The configuration screen lists all web form fields. You are not required to map every form field to a field in the external system.
To map a form field:

Select the dropdown below the form field name.
Scroll to the Workflow Steps list.
Select the data read step.
Select the external system field whose value should be displayed in the web form field.
Note: The only external system fields available to select are those you configured in the Which fields would you like to read? section of the data read step.

Data write step

Note: If you do not want to test writing data to an external data source, omit this step from the workflow.

This step invokes your data IO extension to write values from the web form to the external system. This step tests the Search Records, Patch Record, and Create Record actions.

When you add this step, you select the data write function for your extension. The workflow step dropdown displays Writeback to followed by the App name you selected when you registered the extension app via the form-based process, or the value from the name property in the app manifest if you registered the extension app by uploading an app manifest file.

Step selector data write step

The Writeback to step for your extension will not appear in the dropdown if:

The extension app is not installed and connected to your account.
The Get Type Names and Get Type Definitions actions, which are executed when the connection is established, did not succeed. If you suspect that this is the case, run the Developer Console connection and extension tests to troubleshoot.
The extension app implements data read but not data write.

Configure the settings for this step as follows:

Setting	Value
Where will you write to?	Connection: Select the default connection. [extension app name] object: Select the object in the external system to write data to. The objects listed are those the Maestro service retrieved when it executed the Get Type Names action. Write settings: Select one of the following: Update or create: Attempts to identify a record to update based on criteria you supply. If no existing record meets the criteria, Maestro creates a new record. Executes the Search Records action. Then, if a matching record is found, executes Patch Record; otherwise, executes Create Record. Update: Updates a record based on criteria you supply. If no existing record meets the criteria, the write operation fails. Executes the Search Records action and then Patch Record if a matching record is found. Create: Creates a new record. Executes the Create Record action.

Setting

Value

Where will you write to?

Connection: Select the default connection.
[extension app name] object: Select the object in the external system to write data to. The objects listed are those the Maestro service retrieved when it executed the Get Type Names action.
Write settings: Select one of the following:

Update or create: Attempts to identify a record to update based on criteria you supply. If no existing record meets the criteria, Maestro creates a new record. Executes the Search Records action. Then, if a matching record is found, executes Patch Record; otherwise, executes Create Record.
Update: Updates a record based on criteria you supply. If no existing record meets the criteria, the write operation fails. Executes the Search Records action and then Patch Record if a matching record is found.
Create: Creates a new record. Executes the Create Record action.


Which fields are you writing to?	The Fields list contains the external system fields that this step will write to. By default, the list contains only fields that are marked as required and not read-only in the Get Type Definitions response. To update additional fields, select Add or remove fields. You can select fields and save the selections. The added fields appear in the Fields list. You can write only to one object. You cannot select fields from related or embedded objects. Map each external system field in the Fields list to a web form field: Select the dropdown below the field name. Scroll down to the Collect Data with Web Forms section. Select the web form field whose value should be written to this field in the external system. For some web form fields, you can select one of several value types. See Web form field value types for details.

Which fields are you writing to?

The Fields list contains the external system fields that this step will write to. By default, the list contains only fields that are marked as required and not read-only in the Get Type Definitions response.
To update additional fields, select Add or remove fields. You can select fields and save the selections. The added fields appear in the Fields list. You can write only to one object. You cannot select fields from related or embedded objects.
Map each external system field in the Fields list to a web form field:

Select the dropdown below the field name.
Scroll down to the Collect Data with Web Forms section.
Select the web form field whose value should be written to this field in the external system.
For some web form fields, you can select one of several value types. See Web form field value types for details.

Which record are you writing to? This setting appears only if Write settings is set to Update or Update or create.
Add rules that the Maestro service will use to identify a record to write to. When defining a rule, you select a data source field, an operator, and a workflow field to compare to the data source field. For the data source field, you can select any field that was configured in the Which fields would you like to read setting. This includes fields from related and embedded objects, which are listed in the [app name] field list by object name followed by (reference). To select a field from a related or embedded object, you first select the object name and then select a field from the object.
For the Workflow field, you can select a field from the read step or the web form, or you can select Manual entry, and then hard-code a value.
To define additional rules, select the AND or OR button.
If the rules defined here result in the retrieval of more than one matching record, the workflow instance execution fails with the error Found multiple records for the given search query.


Which record are you writing to?	This setting appears only if Write settings is set to Update or Update or create. Add rules that the Maestro service will use to identify a record to write to. When defining a rule, you select a data source field, an operator, and a workflow field to compare to the data source field. For the data source field, you can select any field that was configured in the Which fields would you like to read setting. This includes fields from related and embedded objects, which are listed in the [app name] field list by object name followed by (reference). To select a field from a related or embedded object, you first select the object name and then select a field from the object. For the Workflow field, you can select a field from the read step or the web form, or you can select Manual entry, and then hard-code a value. To define additional rules, select the AND or OR button. If the rules defined here result in the retrieval of more than one matching record, the workflow instance execution fails with the error `Found multiple records for the given search query`.

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 who will see messages	Select the role name you entered when you configured the workflow participant.
Message type	End of participant’s tasks
Message title	Keep the default value
Message body	Keep the default value

Web form field value types

When working with web form fields in Workflow Builder, you can select different value types for some fields. For fields that support multiple value types, the step configuration screen’s web form field list includes a row for each value type. In the sample screen shown here, the Last Review web form field has these value types available to select: Normalized, User Value, and Format.

Web form field value types

Below is a list of value types available for each web form field type.

Value type	Applicable web form field types	Value used in the operation when you select this type
	Text	The value entered in the web form field is always used, so text field listings do not include a value type.
User Value	Number Date	The value entered in the web form field, including any separators.
Normalized	Number Date	For a date field, the date in UTC format. For a number field, the number with a period as a decimal separator.
Format	Number Date	The format of the date or number field as defined in the web form. For a date field, this will be a format like `MM/DD/YYYY`. For a number field, possible values are `periodSeparatedNumber` (decimal separator is a period) and `commaSeparatedNumber` (decimal separator is a comma).
Selected Value	Dropdown Radio buttons	The API value of the selected dropdown item or radio button, as defined in the web form. See Add or Edit Field Properties on a Web Form for details. For enum variables read from an external system via Data IO, this corresponds to the API value variable — for example, State (API value).
Selected Label	Dropdown Radio buttons	The Option text of the selected dropdown item or radio button, as defined in the web form. See Add or Edit Field Properties on a Web Form for details. For enum buttons variables read from an external system via Data IO, this corresponds to the option text variable — for example, State (Option text).
[checkbox option text]	Checkbox	`true` if the checkbox is selected in the web form, otherwise `false`. The checkbox Option text is defined in the web form. See Add or Edit Properties for a Web Forms Checkbox Field for details. For boolean fields read from an external system via Data IO, the variable follows the naming pattern [field name] (Checkbox group) — for example, `IsActive` (Checkbox group).

Step 3. Execute a workflow instance

Once you’ve published your workflow, you can execute an instance of it to run through the steps as an end user would and make sure that the data read and write operations succeed.

Follow the steps in the From Within Workflow Builder section of How to Start a Workflow to execute a workflow instance.
If the workflow includes a data read step, confirm that the web form loads with values retrieved from the external system.
Fill out and submit the web form.
Confirm the submitted form values.
The confirmation page is displayed.
If the workflow includes a data write step, check the external system to confirm that web form values were successfully written to it.

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.
See reference information for the data IO extension.
Learn how to run integration tests.