> 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

# Connected fields extension envelope test

> Learn how to set up and execute a functional test that invokes a connected fields extension from an eSignature envelope.

This procedure explains how to set up and execute a [functional test](/extension-apps/build-an-extension-app/test/functional-tests) that invokes a [connected fields extension](/extension-apps/extension-apps-101/supported-extensions/connected-fields) from an eSignature [envelope](/docs/esign-rest-api/esign101/concepts/envelopes).

This test checks the functioning of *connected fields*, which are envelope fields that can be verified by data verification or connected field extensions defined in your account. To set up the test, you add connected fields to an [eSignature template](https://support.docusign.com/s/document-item?bundleId=xry1643227563338\&topicId=dqj1578456412286.html\&rsc_301), generate an envelope from the template, and access the envelope via an emailed link. While viewing the envelope, you supply values in the connected fields to confirm that your extension is successfully invoked.

> **Note**
>
> Instead of creating a template, you can add connected fields directly to an envelope. This test procedure specifies adding them to a template so that you can save and reuse it instead of adding connected fields to an envelope every time you want to test. Docusign also supports programmatically creating envelopes that include connected fields. See [Connected fields concepts](/docs/connected-fields-api/concepts) for details.

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

* [Step 1. Add connected fields to a template](/extension-apps/build-an-extension-app/test/functional-tests/connected-fields-envelope#step-1-add-connected-fields-to-a-template)
* [Step 2. Generate and send an envelope](/extension-apps/build-an-extension-app/test/functional-tests/connected-fields-envelope#step-2-generate-and-send-an-envelope)
* [Step 3. Access the envelope and supply data to verify](/extension-apps/build-an-extension-app/test/functional-tests/connected-fields-envelope#step-3-access-the-envelope-and-supply-data-to-verify)

> **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).

## Step 1. Add connected fields to a template

To add connected fields to a template:

1. Log in to the [eSignature web application](https://account-d.docusign.com/) and select **Templates** from the top navigation.
2. Do one of the following:

   * Follow the procedure in [To edit a template](https://support.docusign.com/s/document-item?bundleId=xry1643227563338\&topicId=uvw1578456369720.html) if you want to add connected fields to an existing template.
   * Follow the procedure in [To create a template](https://support.docusign.com/s/document-item?bundleId=xry1643227563338\&topicId=lsg1578456368117.html) to create a new template for the test.
3. While creating or editing the template, select **Next** to display the [Add Fields view](https://support.docusign.com/s/document-item?bundleId=ulp1643236876813\&topicId=odn1578456409392.html).
4. In the left navigation, select the **Custom Fields** icon.

   ![Custom fields icon](/_fern-files/_img/f9c902963386b5b6e69745c53cc9168837e141ddbf5ee28e7bbcd640197b8ba3.webp)
5. Expand the **App Fields** list. Then expand the entry that corresponds to your extension app name to display the list of connected fields. In the example shown here, the extension app name is **Transfer Authorization**.

   ![App Fields list](/_fern-files/_img/f4a608690af69f779c4c8d999f9f62ed3a6a8cb6f1421b10c46391e4211399f3.webp)

   The connected fields list includes every external system property under an object that has been marked with the `VerifiableType` decorator in the [Get Type Definitions](/extension-apps/extension-app-reference/extension-contracts/connected-fields#get-type-definitions) response. Properties that include the `IsRequiredForVerifyingType` decorator appear with an asterisk to indicate that they are required.

   > **Warning**
   >
   > If **App Fields** does not appear after you select **Custom Fields**, or if you do not see your extension app name under **App Fields**, then the extension app may not be installed or connected to your account.  See [Run a connection test](/extension-apps/build-an-extension-app/test/integration-tests#run-a-connection-test) for instructions to install and connect it. Another potential cause is that Docusign was unable to process the [Get Type Names](/extension-apps/extension-app-reference/extension-contracts/connected-fields#get-type-names) or [Get Type Definitions](/extension-apps/extension-app-reference/extension-contracts/connected-fields#get-type-definitions) response, possibly due to an error in the data model. To check this, run the [extension tests](/extension-apps/build-an-extension-app/test/integration-tests#run-an-extension-test) for these two actions. You can use the [Concerto VSCode extension](https://concerto.accordproject.org/docs/tools/vscode/) to validate your data model and check for errors.
6. Drag any required connected field to the document. When you do so, all required connected fields will be added as a group.

   ![Connected fields added to document as group](/_fern-files/_img/4fb2b24be011ab62cd06000d7c66271f589e34f02f62711bd425553b4e3c07f4.webp)

   If you want to include optional connected fields, drag them to the document, and they will be added to the field group. If you add an optional connected field to a document but do not include the required connected fields, verification will fail when you populate the optional field during envelope signing.
7. In the properties list on the right, expand **Data Verification**.
8. Confirm that your extension app name appears in the **Extension App** field.

   ![Extension app name in properties for field](/_fern-files/_img/454eab97a6f1b997a1484ce4a37c9575c8f95eed744c2da3bf50d909ce150371.webp)
9. Select **Must verify to sign** to require successful verification of the envelope data to complete the signing process. If you leave this option unchecked, verification will still occur.

   You are not required to add a **Signature** field or any other fields to the template in order to test a connected fields extension.
10. Move the fields on the document to position them as appropriate.

    ![Custom fields on document](/_fern-files/_img/d078f14c5a3236ae7b96904dba7d2ba73ef562d5ae0fc469480d867dc38f3fb4.webp)
11. Apply [data validation](https://support.docusign.com/s/document-item?bundleId=gbo1643332197980\&topicId=jgd1578456357365.html) to any connected fields that require it. For example, if you want a field to be populated with numbers only, select the **Numbers** validation option. See [Transform logic](/extension-apps/extension-apps-101/supported-extensions/data-model#transform-logic) for details about the default envelope field types for each data source type.
12. Select **Save and Close** to save the template.

> **Note**
>
> Once you’ve saved the template, you can generate an envelope from it whenever you want to test your extension. For example, if you update your back-end API service code to fix an issue, you can test the fix by generating a new envelope. If you [update the extension app registration](/extension-apps/build-an-extension-app/update-registration), you’ll need to take additional steps before running this test again. See [Connection best practices](/extension-apps/best-practices/connection-behaviors-and-best-practices#connection-best-practices) for details.

## Step 2. Generate and send an envelope

Follow the procedure in [Use a Template to Create an Envelope](https://support.docusign.com/s/document-item?bundleId=xry1643227563338\&topicId=nxv1578456289719.html) to generate an envelope and email a link to view the envelope. When completing this procedure, supply an address where you can receive email.

## Step 3. Access the envelope and supply data to verify

When you receive the email:

1. Open it and select **Review Document**.
2. Enter values in all the connected fields. Each field has a tooltip that lists the `value` returned for the property in the [Get Type Definitions](/extension-apps/extension-app-reference/extension-contracts/connected-fields#get-type-definitions) response.
3. When all required connected field values have been supplied, Docusign invokes your extension to verify them. A **Verifying data** message is displayed, followed by a message to indicate whether verification succeeded or failed.

   ![Connected fields verification succeeded](/_fern-files/_img/35b5277b835a92f7719423e82b41d5883aa6aef3e547ad44907b8d4107ec9ffa.webp)
4. Confirm that:

   * Supplying valid values results in successful verification.
   * Supplying invalid values results in failed verification.
   * The verification messages returned with the responses appear as expected.
   * Any suggested values in the responses are autofilled as expected.
5. Changing any of the required connected field values causes the verification operation to be triggered again.

> **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).
* Learn how to run [integration tests](/extension-apps/build-an-extension-app/test/integration-tests).
* Get an overview of the process to [publish an extension app](/extension-apps/build-an-extension-app/publish).