Docusign createEnvelope REST API with Composite Templates CANNOT_EXCLUDE_DOCUMENT Error

Question

Using documentation at createEnvelope with composite templates https://docs.docusign.com/esign/restapi/Envelopes/Envelopes/create/ https://developers.docusign.com/esign-rest-api/guides/features/templates

When we attempt to use this API for multiple templates we are getting error similar to below

{\r\n  \"errorCode\": \"CANNOT_EXCLUDE_DOCUMENT\",\r\n  \"message\": \"This document cannot be excluded for this recipient. Recipient: Enbmgr Enbmgr cannot be excluded from Document:TalentEmploymentAgreemt_0617AqVT.pdf\"\r\n}"}}

When the sequence of the templates are changed it works fine. What could be the cause for this?

The account is set up with Document Visibity: Sender can set "must sign to view unless sender"

Error when sent with below sequence:

1. Templateid- f09dc354-efd6-437e-9410-5270b181a1f1 Roles: Emp, Mgr (sign in sequence enabled)

2. Templateid- 8c919c05-ee1f-42c4-b521-861c5f2949b Roles: Emp

3. Templateid- 6b57ea78-5923-4c54-b4c1-15c8d5313e71 Roles: Emp, Mgr (sign in sequence enabled)

Success when sent with below sequence:

1. Templateid- 6b57ea78-5923-4c54-b4c1-15c8d5313e71 Roles: Emp, Mgr (sign in sequence enabled)

2. Templateid- f09dc354-efd6-437e-9410-5270b181a1f1 Roles: Emp, Mgr (sign in sequence enabled)

3. Templateid- 8c919c05-ee1f-42c4-b521-861c5f2949b Roles: Emp

Request giving error:

    {
      "emailSubject": "DocuSign API - Composite Templates",
      "emailBlurb": "Composite Templates Sample 1",
      "status": "sent",
      "compositeTemplates": [
        {
          "serverTemplates": [
            {
              "sequence": "1",
              "templateId": "f09dc354-efd6-437e-9410-5270b181a1f1"
            }
          ],
          "inlineTemplates": [
            {
              "sequence": "2",
              "recipients": {
                "signers": [
                  {
                    "email": "ranjesh+emp@enboarder.com",
                    "name": "Enbemp Enbemp",
                    "roleName": "Talent",
                    "recipientId": "1",
                    "tabs": {}
                  },
                  {
                    "email": "ranjesh+mgr@enboarder.com",
                    "name": "Enbmgr Enbmgr",
                    "roleName": "OM",
                    "recipientId": "2",
                    "tabs": {}
                  }
                ]
              }
            }
          ]
        },
        {
          "serverTemplates": [
            {
              "sequence": "3",
              "templateId": "8c919c05-ee1f-42c4-b521-861c5f2949bf"
            }
          ],
          "inlineTemplates": [
            {
              "sequence": "4",
              "recipients": {
                "signers": [
                  {
                    "email": "ranjesh+emp@enboarder.com",
                    "name": "Enbemp Enbemp",
                    "roleName": "Talent",
                    "recipientId": "1",
                    "tabs": {
                      "textTabs": [
                        {
                          "tabLabel": "\\*Market",
                          "value": " "
                        }
                      ]
                    }
                  }
                ]
              }
            }
          ]
        },
        {
          "serverTemplates": [
            {
              "sequence": "5",
              "templateId": "6b57ea78-5923-4c54-b4c1-15c8d5313e71"
            }
          ],
          "inlineTemplates": [
            {
              "sequence": "6",
              "recipients": {
                "signers": [
                  {
                    "email": "ranjesh+emp@enboarder.com",
                    "name": "Enbemp Enbemp",
                    "roleName": "Talent",
                    "recipientId": "1",
                    "tabs": {}
                  },
                  {
                    "email": "ranjesh+mgr@enboarder.com",
                    "name": "Enbmgr Enbmgr",
                    "roleName": "OM",
                    "recipientId": "2",
                    "tabs": {}
                  }
                ]
              }
            }
          ]
        }
      ]
    }

Request giving success:

    {
      "emailSubject": "DocuSign API - Composite Templates",
      "emailBlurb": "Composite Templates Sample 1",
      "status": "sent",
      "compositeTemplates": [
        {
          "serverTemplates": [
            {
              "sequence": "1",
              "templateId": "6b57ea78-5923-4c54-b4c1-15c8d5313e71"
            }
          ],
          "inlineTemplates": [
            {
              "sequence": "2",
              "recipients": {
                "signers": [
                  {
                    "email": "ranjesh+emp@enboarder.com",
                    "name": "Enbemp Enbemp",
                    "roleName": "Talent",
                    "recipientId": "1",
                    "tabs": {}
                  },
                  {
                    "email": "ranjesh+mgr@enboarder.com",
                    "name": "Enbmgr Enbmgr",
                    "roleName": "OM",
                    "recipientId": "2",
                    "tabs": {}
                  }
                ]
              }
            }
          ]
        },
        {
          "serverTemplates": [
            {
              "sequence": "3",
              "templateId": "f09dc354-efd6-437e-9410-5270b181a1f1"
            }
          ],
          "inlineTemplates": [
            {
              "sequence": "4",
              "recipients": {
                "signers": [
                  {
                    "email": "ranjesh+emp@enboarder.com",
                    "name": "Enbemp Enbemp",
                    "roleName": "Talent",
                    "recipientId": "1",
                    "tabs": {}
                  },
                  {
                    "email": "ranjesh+mgr@enboarder.com",
                    "name": "Enbmgr Enbmgr",
                    "roleName": "OM",
                    "recipientId": "2",
                    "tabs": {}
                  }
                ]
              }
            }
          ]
        },
        {
          "serverTemplates": [
            {
              "sequence": "5",
              "templateId": "8c919c05-ee1f-42c4-b521-861c5f2949bf"
            }
          ],
          "inlineTemplates": [
            {
              "sequence": "6",
              "recipients": {
                "signers": [
                  {
                    "email": "ranjesh+emp@enboarder.com",
                    "name": "Enbemp Enbemp",
                    "roleName": "Talent",
                    "recipientId": "1",
                    "tabs": {
                      "textTabs": [
                        {
                          "tabLabel": "\\*Market",
                          "value": " "
                        }
                      ]
                    }
                  }
                ]
              }
            }
          ]
        }
      ]
    }

I've found that the last template looks like this Template definition with excluded documents for a signer

How are excluded documents for signers setup in Docusign's application?

Answer 1

I suspect how the Roles and Tabs are distributed matters, yet I can't see your template or the API Json sent.

1. You can get the API log capture of the exact JSON/SOAP request posted by your API calls via Java to DocuSign by following steps explained at this DocuSign support article https://support.docusign.com/guides/ndse-user-guide-api-request-logging

2. Here is part of what you need to understand about Sequence numbers and physical order - In composite templates, physical order overrules the "index/sequence" per composite template node. The index is the internal glue, but not really the row order in the in-memory model. I suspect you really wanted to restart the sequence number in each node of "composite template" since you are saying I have "three" documents and x number of features and roles per document as both working and not working collapse to the following structure composite nodes structure except it looks like you had (corrected now) an extra "[" array grouping:

(corrected now in updated question)

"compositeTemplates": [{
"serverTemplates": [{
"inlineTemplates": [{
"document": ....

or to match yours:

"compositeTemplates": [
    {},
    {},
    {}
    ]

This all supposes you want three documents, if you want one document, then you keep the server templates in the same array collection inside the composite node to be applied to the contributing document, one with the lowest sequence number. Remember in JSON/REST if the JSON is malformed aka includes more than needed, the API just ignores it as "client comments" and takes what it can use.

4. The lower the sequence: document node (not documents) between server, inline and document being 0 is how the "PDF/DOC bytes are determined, and the higher the sequence number the feature that wins aka doc vis in one template, vs another or the notification days number.

5. I will have to probably wait for the logs, however I think the clue to the issue on doc vis error is the "tabLabel": "\*Market" which goes from middle to last between the two examples. Anchor strings are envelope wide, so I suspect it "meets" the needed criteria for the feature for that role which is probably required per the template. You can put the all the roles in the last composite template node of the last inline template node and it will apply them to all the previous composite template nodes where they are not supplied by an inline template.

So there is a best practice document I am about to publish explaining this on complex template assembly in envelopes, however, hope this helps for now.

Please attach your logs so we can see the real example and determine which played into the results you are describing.