> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL. > > Documentation indexes by section: > - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt > - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt > - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt > - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt > > Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth > Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks > > OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json > MCP server: https://docusign.docs.buildwithfern.com/_mcp/server # Data IO extension workflow test > Learn how to test a data IO extension in a workflow. These procedures explain how to set up and execute a [functional test](/extension-apps/build-an-extension-app/test/functional-tests) that invokes a data IO extension from a [Workflow Builder workflow](/docs/workflow-builder-api/workflow-builder101/workflows). For this test, you run a workflow that reads data from your external system, populates [web form](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=brp1660583998599.html) 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](/extension-apps/extension-app-reference/extension-contracts/data-io) 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: * [Step 1. Identify or create a web form](/extension-apps/build-an-extension-app/test/functional-tests/data-io-workflow#step-1-identify-or-create-a-web-form) * [Step 2. Create and publish the workflow](/extension-apps/build-an-extension-app/test/functional-tests/data-io-workflow#step-2-create-and-publish-the-workflow) * [Step 3. Execute a workflow instance](/extension-apps/build-an-extension-app/test/functional-tests/data-io-workflow#step-3-execute-a-workflow-instance) This is one of many possible approaches to setting up a workflow. For additional options, see the [workflow user documentation](https://support.docusign.com/s/document-item?bundleId=yff1696971835267\&topicId=dnx1696972415150.html). > **Warning** > > Make sure that you’ve completed all the requirements listed for functional tests in [Test prerequisites](/extension-apps/build-an-extension-app/test#test-prerequisites). **Walkthrough playlist:** You can also see a video overview of the data IO extension workflow test using the [Data IO Reference Implementation](https://github.com/docusign/extension-app-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](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=tpj1664990031635.html) in your account, or [create a new web form](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=euk1665093155272.html). 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 ](https://support.docusign.com/s/document-item?bundleId=yff1696971835267\&topicId=oha1716325069710.html) 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](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=wor1676501633875.html) 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: 1. Log in to the [Workflow Designer](https://apps-d.docusign.com/send/workflows/). 2. Follow the steps in [Create a Basic Workflow](https://support.docusign.com/s/document-item?bundleId=yff1696971835267\&topicId=uhm1697826856678.html) 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](/extension-apps/build-an-extension-app/test/functional-tests/data-io-workflow#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](/extension-apps/build-an-extension-app/test/functional-tests/data-io-workflow#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](/extension-apps/build-an-extension-app/test/functional-tests/data-io-workflow#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](/extension-apps/build-an-extension-app/test/functional-tests/data-io-workflow#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](/extension-apps/build-an-extension-app/test/functional-tests/data-io-workflow#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. 3. Complete the steps in [Review and Publish a Workflow](https://support.docusign.com/s/document-item?language=en_US\&bundleId=yff1696971835267\&topicId=iqm1698272226447.html). Then you can [execute instances of the workflow](/extension-apps/build-an-extension-app/test/functional-tests/data-io-workflow#step-3-execute-a-workflow-instance) to test your extension app. ![Workflow steps data IO](/_fern-files/_img/8ee03fbd744d06ee4bb2f7eae5beb42a4caa2e98e33b182d02a344355ed88b20.webp) ### 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](https://support.docusign.com/s/document-item?bundleId=yff1696971835267\&topicId=uhm1697826856678.html) 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](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-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](/extension-apps/build-an-extension-app/register/use-form), or the value from the [name](/extension-apps/extension-app-reference/app-manifest-reference) property in the app manifest if you registered the extension app by [uploading an app manifest file](/extension-apps/build-an-extension-app/register/use-manifest). ![Workflow read step selector](/_fern-files/_img/0151ee70e08dc3ed444239bc682a5342e5d9525bca43bfdb1e35817c03a7958a.webp) 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](https://support.docusign.com/s/document-item?bundleId=ous1698169987748\&topicId=ctg1698170340729.html). * The [Get Type Names](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-get-type-names) and [Get Type Definitions](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-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](/extension-apps/build-an-extension-app/test/integration-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](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-get-type-names) action. | ![Where will you read from](/_fern-files/_img/4bedc13f5e97ee9878aa929b642c2a64777abd02d851d99140ad9e45aced1295.webp) | | | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-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](/extension-apps/build-an-extension-app/test/functional-tests/data-io-workflow#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](/_fern-files/_img/e3d4ff00d65982ec5a7a578d917c30291a41a0ae0b849a047147e0839fca3a7d.webp) | | | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](https://support.docusign.com/s/document-item?bundleId=qwr1706590641805\&topicId=idr1713985144297.html) for details about previewing query results. | ![Which record are you reading from](/_fern-files/_img/5914b458f2257c48216f4416ea9a87289609de8f388fa88e4310e0c232c88b4d.webp) ### 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](https://support.docusign.com/s/document-item?bundleId=yff1696971835267\&topicId=gua1698120920620.html). 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](/extension-apps/build-an-extension-app/test/functional-tests/data-io-workflow#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](/extension-apps/build-an-extension-app/test/functional-tests/data-io-workflow#workflow-participant). | ![Web form step configuration](/_fern-files/_img/cc9badef3a24b86560a314f9d1f066b253099889366a6b79bd44ebc6bf70586f.webp) | | | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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:1) Select the dropdown below the form field name. 2) Scroll to the **Workflow Steps** list. 3) Select the data read step. 4) 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](/extension-apps/build-an-extension-app/test/functional-tests/data-io-workflow#data-read-step). | ![Web form step map data fields](/_fern-files/_img/c6724e6491b4b8bc28b434a5d5024ea9242be3f285ec75677727aeb82bf537cd.webp) ### 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](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-search-records), [Patch Record](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-patch-record), and [Create Record](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-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](/extension-apps/build-an-extension-app/register/use-form), or the value from the [name](/extension-apps/extension-app-reference/app-manifest-reference) property in the app manifest if you registered the extension app by [uploading an app manifest file](/extension-apps/build-an-extension-app/register/use-manifest). ![Step selector data write step](/_fern-files/_img/a59eb573621fda6f41ea3b49f237708c38ddaac5ae624981bfac1d7189972f24.webp) 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](https://support.docusign.com/s/document-item?bundleId=ous1698169987748\&topicId=ctg1698170340729.html). * The [Get Type Names](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-get-type-names) and [Get Type Definitions](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-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](/extension-apps/build-an-extension-app/test/integration-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](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-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](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-search-records) action. Then, if a matching record is found, executes [Patch Record](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-patch-record); otherwise, executes [Create Record](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-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. | ![Where will you write to](/_fern-files/_img/9b4551954a4960123036cc2d9b4559ead08d29a9e9cb2ffae0a190d6ae1f5029.webp) | | | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-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:1) Select the dropdown below the field name. 2) Scroll down to the **Collect Data with Web Forms** section. 3) 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](/extension-apps/build-an-extension-app/test/functional-tests/data-io-workflow#web-form-field-value-types) for details. | ![Which fields are you writing to](/_fern-files/_img/914d72dd584eb276fbae3d8b157fef6bfdc5d18eb0d6ba603255eede948f2f43.webp) | | | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/_fern-files/_img/a707994b59f81d170915d33663f74f468f861d286fb4dba9c9a47537c8f8854a.webp) ### 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 ](https://support.docusign.com/s/document-item?bundleId=yff1696971835267\&topicId=rpc1698682081448.html). 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](/extension-apps/build-an-extension-app/test/functional-tests/data-io-workflow#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](/_fern-files/_img/03407d4c07cf5978db7cbd8d4b5a3fc68641a78ce4bef70c7909a4ef0ec77359.webp) 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](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=fzu1672965301647.html) 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](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=fzu1672965301647.html) 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](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=rws1673560056362.html) 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](https://support.docusign.com/s/document-item?language=en_US\&bundleId=yff1696971835267\&topicId=iqm1698272226447.html), 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. 1. Follow the steps in the **From Within Workflow Builder** section of [How to Start a Workflow](https://support.docusign.com/s/document-item?bundleId=yff1696971835267\&topicId=glx1730400747416.html) to execute a workflow instance. 2. If the workflow includes a data read step, confirm that the web form loads with values retrieved from the external system. 3. Fill out and submit the web form. 4. Confirm the submitted form values. 5. The confirmation page is displayed. 6. If the workflow includes a data write step, check the external system to confirm that web form values were successfully written to it. > **Warning** > > If your extension is not invoked successfully, run the Developer Console [connection and extension tests](/extension-apps/build-an-extension-app/test/integration-tests) for the extension app to get detailed error messages and troubleshoot. ## Next steps * Find out more about [functional tests](/extension-apps/build-an-extension-app/test/functional-tests). * See reference information for the [data IO extension](/extension-apps/extension-app-reference/extension-contracts/data-io). * Learn how to run [integration tests](/extension-apps/build-an-extension-app/test/integration-tests).