Skip to navigation
Troubleshooting

Troubleshooting for connected fields extensions

View as Markdown

This topic provides troubleshooting guidance for issues that may arise when working with connected fields extensions in eSignature or in the Docusign App Center.

eSignature envelope or template preparation issues

Issue

In the eSignature Add Fields view, App Fields does not appear after you select Custom Fields, or you do not see your extension app name under App Fields. Connected fields extension apps should appear under App Fields.

Possible causes and recommendations

  • The extension app may not be installed or connected to your account. See Run a connection test for instructions to install and connect it in the Developer Console, or install and connect it to your account in the App Center.
  • When the extension app was connected to your account, 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.
  • The connection to the external service was invalidated due to authorization issues or deleted. Re-establish the connection for the extension app in the Docusign App Center. See Connection behaviors and best practices for more information.
  • You are working with an eSignature template that you added to your account by uploading a template that was downloaded from another account. However, the account to which you uploaded the template does not have the connected fields extension app installed or connected. See Run a connection test for instructions to install and connect it in the Developer Console, or install and connect it to your account in the App Center.

Issue

In the eSignature Add Fields view, the list of available connected fields for your extension app is out of date.

Possible causes and recommendations

  • The data model changed after the extension app was connected to your account. Refresh the connection for the extension app in the Docusign App Center. This keeps the connection intact and causes Docusign to execute Get Type Names and Get Type Definitions actions to retrieve the latest data model.
  • When the extension app was connected to your account, 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.

Issue

In the eSignature Add Fields view, multiple copies of the extension app are listed with different connection names, but you only expect to see one listing.

Possible cause and recommendation

Repeatedly running connection tests on the Developer Console Testing page causes multiple connections to be created. You can delete connections in the App Center. For an extension app in Draft status, you can uninstall and reinstall it on the Developer Console Testing page, and then run a new connection test to create a single connection. Because uninstalling and reinstalling in the Developer Console deletes all existing connections, this option is not recommended for extension apps that are being used in production. See Connection behaviors and best practices for more information.

Issue

In the eSignature Add Fields view, a connected field is displayed as required (indicated by an asterisk), but it should be optional.

Possible causes and recommendations

  • The property is marked with the IsRequiredForVerifyingType decorator in your data model. To check this, run the extension test for the Get Type Definitions action and review the response. If the decorator is present for a property that should be optional, remove it from the data model.
  • The property is not defined as optional in the data model. By default, Docusign treats properties as required if they are not explicitly defined as optional. Add an isOptional property set to true in the Concerto definition.

eSignature envelope signing view issues

Issue

After populating a value in one or more connected fields, a Verification failed error is displayed instead of the expected verification result and message from the external system.

Possible causes and recommendations

  • Your extension app registration is not configured with the correct parameters to connect to the external service. Run the Developer Console extension tests for the Get Type Names, Get Type Definitions, and Verify actions, and then check for any errors accessing the external service.
  • Docusign does not have an up-to-date data model for your system of record. Refresh the connection for the extension app in the Docusign App Center to update the data model information that Docusign stores. See Connection behaviors and best practices for more information.
  • The connection to the external service was invalidated due to authorization issues or deleted. Re-establish the connection for the extension app in the Docusign App Center. See Connection behaviors and best practices for more information.
  • If envelopes are being created programmatically via API requests, the connected field values in the Envelopes:create request’s extensionData objects may be outdated or incorrect. Send a TabInfo:GetConnectedFieldsTabGroups request, and make sure the required values from the response are included in the Envelopes:create request. See Connected fields concepts for more information.
  • During template or envelope preparation, only optional connected fields were added to the document. Verification fails if a document does not contain any required connected fields. In the eSignature Add Fields view, be sure to add required connected fields (marked with an asterisk) to the document, and then send a new envelope.

Issue

The signing view allows users to enter non-permitted values in a connected field, such as letters in a field that’s intended for numeric values.

Possible cause and recommendation

The connected field did not have any data validation applied after it was added to the template or envelope in the eSignature Add Fields view. Most Concerto properties appear as text fields in the Add Fields view. See Transform logic for details. To require signers to enter specific types of values, such as numeric values, use the data validation feature after adding connected fields to a template or envelope.

App Center issues

Issue

When trying to add or refresh a connection, the connection management page displays a Data Error banner.

Possible cause and recommendation

Adding or refreshing a connection causes Docusign to execute Get Type Names and Get Type Definitions requests, but Docusign was unable to process both responses, 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.

Next steps