Skip to navigation
API referenceSending Function Group

Rules for CreateEnvelopeFromTemplates

View as Markdown

CreateEnvelopeFromTemplates refers to Templates to establish many of the properties of an Envelope. However, the CreateEnvelopeFromTemplates schema also overlaps the Template capabilities, so it is necessary to establish rules of usage and precedence to address incidents of data collision between the values in the SOAP request and the Template(s); or between the Template(s) themselves, since they are logically unrelated to each other.

See Data Override rules for the data override rules for the CreateEnvelopeFromTemplates schema.

Template execution rules

The rules below are enforced when sending an Envelope based on a Template specification.

  • If a Template role is specified as Optional, remove the signing instructions associated with the role, including all Tabs, if the role is not assigned in the CreateEnvelopesFromTemplates request.
  • If any of the data override rules are violated (indicated by “must” statements in the Data Override descriptions), an exception is returned that describes the violation.

Rules for mapping data from PDF forms

Data will be mapped from the incoming PDF form based on a direct correlation between the field name of the Form and the TabLabel of the Docusign Tab. Fields will only be mapped if TransformPDFFields is set to true in the document node.

Note: Docusign will not transform PDF form fields that have the text “DocusignIgnoreTransform” or “eSignIgnoreTransform” as part of the name of the PDF form field.

Mapping must be supported for static XFA-based PDF forms and AcroForms. The order of preference for establishing the form type is:

  1. Derived on Docusign server (transparent to client)
  2. Pre-configured in a Docusign structure (i.e. design-time configuration in a template)
  3. Passed in via API request.
Rule #Description
1When a PDF form is submitted, the Docusign mapping component will interrogate the form for any fields and apply the data from those fields to Docusign Form Fields of the same name.
2Fields from XFA-based PDF forms will be evaluated by their fully-qualified field name (ex: “form/customer/address/line1[0]”)
3The Docusign component will map any fields that match (per the requirement above). Any fields that do not have a matching field (i.e. field exists in form but not in Envelope; or field exists in Envelope but not in form) will be disregarded by the mapping component.
4Docusign form fields are limited in scope to the document that they pertain to.
5Edit rules for the fields must be pre-configured for the Docusign fields (ex: editable vs. locked, required vs. optional, edit masks). Edit rules will not be derived by the Docusign mapping component.
6The following field types are supported for data mapping: text boxes, check boxes, radio buttons, drop-down lists, text areas.\n\nRegarding drop-down lists and radio buttons, the data mapping is for the selected value only. The list of available values must be pre-configured in the Docusign fields.

Error rules

All errors from CreateAndSendEnvelope and CreateEnvelope apply in addition to the following:

  • Template_Cannot_Add_Document – error thrown if the template location is set to PDFMetaData and the PDF bytes within the Document node of the template reference are invalid.
  • Template_Not_Provided – error thrown if the template XML cannot be found in the PDFMetaData or TemplateReference Template node.
  • Template_Unable_To_Load – error thrown if the template provided cannot be loaded.
  • Template_Cannot_Add_Document – error thrown if the template and document cannot be loaded.
  • Template_Unable_To_Load_FieldData – error thrown if the PDF form data exists in the PDF and it cannot be extracted.
  • Template_Unable_To_Process_FieldData – error thrown if the PDF form data exists and it cannot be mapped properly to the recipients Docusign Tab data.
  • Template_Unable_To_Flatten_PDF – error thrown if the PDF form data exists and it cannot be flattened.
  • Template_RoleSpecified_Does_Not_Exist – error thrown if a recipient is mapped to a role that does not exist in the template.
  • Template_RecipientID_For_Role_NotFound – error thrown if a recipient ID is mapped to a role and the recipient ID does not exist in the template.
  • Template_Required_Recip_Not_Satisfied – error thrown if there is a required recipient in the template and no recipient/role mapping satisfied the recipient.
  • Template_To_Envelope_Error – error thrown if the template provided cannot be transformed to a Docusign envelope.
  • Template_Override_EnvelopeInformation_Error – error thrown if any items in the EnvelopeInformation data cannot be applied to the envelope.
  • Template_AdditionalTabs_Error – error thrown if an items in the AdditionalTabs data cannot be applied to the envelope.
  • Template_Override_RecipientData_Error – error thrown if an items in the Recipient data that should override the template data cannot be applied to the envelope.