Connected fields extension envelope test

This procedure explains how to set up and execute a functional test that invokes a connected fields extension from an eSignature envelope.

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, 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.

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

• Step 1. Add connected fields to a template
• Step 2. Generate and send an envelope
• Step 3. Access the envelope and supply data to verify

Step 1. Add connected fields to a template

To add connected fields to a template:

1. Log in to the eSignature web application and select Templates from the top navigation.

2. Do one of the following:

   • Follow the procedure in To edit a template if you want to add connected fields to an existing template.
   • Follow the procedure in To create a template to create a new template for the test.

3. While creating or editing the template, select Next to display the Add Fields view.

4. In the left navigation, select the Custom Fields icon.

   

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.

   

   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 response. Properties that include the IsRequiredForVerifyingType decorator appear with an asterisk to indicate that they are required.

   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 for instructions to install and connect it. Another potential cause is that Docusign was unable to process the Get Type Names or Get Type Definitions response, possibly due to an error in the data model. To check this, run the extension tests for these two actions. You can use the Concerto VSCode extension 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.

   

   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.

   

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.

    

11. Apply data validation 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 for details about the default envelope field types for each data source type.

12. Select Save and Close to save the template.

Step 2. Generate and send an envelope

Follow the procedure in Use a Template to Create an Envelope 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 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.

   

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.

Next steps

• Find out more about functional tests.
• Learn how to run integration tests.
• Get an overview of the process to publish an extension app.