DocuSign API Adding TemplateRoles to a ServerTemplate/CompositeTemplate - docusignapi

I am trying to develop the following workflow in DocuSign:
There are two documents to be signed. The first is a template with 4 signatures required by 4 roles. The second document is uploaded, docx or pdf, and will be signed after the first document is complete.In the first document the first two signers need to be provided to the template and I could make this work when all I had in the envelope was the template document. After converting this to a compositeTemplate I don't see a place to add the roles to the template document. I am also unsure how to add the signature to the second document to the workflow for the template document.
The following is the json I am generating:
{
"templateRoles": [
{
"email": "EMAIL1",
"roleName": "ROLE1",
"name": "NAME1"
},
{
"email": "EMAIL2",
"roleName": "ROLE2",
"name": "NAME2"
}
],
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "TEMPLATE-ID"
}
]
},
{
"inlineTemplates": [
{
"sequence": "2",
"documents": [
{
"documentId": "1",
"name": "Contract",
"documentBase64": <DOC DATA>
}
]
}
]
}
],
"emailSubject": "[DocuSign C# SDK] - Sample Signature Request"
}
The template roles aren't picked up by the servertemplate and the documents are sent to the third person in the workflow.
Any help with this will be much appreciated.

You will have to use multiple composite templates to add a new document.
The templateRoles specified at the root level are ignored when your envelope definition contains composite templates. The templateRoles have to be spcified within the inlineTemplate.
The tabs can be added in the second composite template.
{
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "<Specify the serverTemplateId here>"
}
],
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"name": "NAME1",
"email": "EMAIL1",
"roleName": "ROLE1",
"recipientId": "1"
},
{
"name": "NAME2",
"email": "EMAIL2",
"roleName": "ROLE2",
"recipientId": "2"
}
]
}
}
]
},
{
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"name": "NAME1",
"email": "EMAIL1",
"roleName": "ROLE1",
"recipientId": "1",
"tabs": {
"signHereTabs": [
{
"documentId": "2",
"pageNumber": "1",
"xPosition": "50",
"yPosition": "50"
}
]
}
}
]
}
}
],
"document": {
"documentId": "2",
"name": "DocumentName",
"fileExtension": "docx",
"documentBase64": "<Specify document bytes here>"
}
}
],
"emailSubject": "[DocuSign C# SDK] - Sample Signature Request",
"status": "sent"
}

Related

Combining Signer Tasks on Composite Template

I am running some tests with the DocuSign API via PostMan for a solution proof of concept. My goal is to create a single envelope with multiple documents, each assigned to its own template.
Our goal is to create a dynamic envelope of templates as needed; i.e. sometimes we will only need to put one template into the envelope, other times we might need five or six. The tricky bit is that a single person might be a recipient on multiple documents at once. We are looking to see if its possible to configure the envelope so that they can sign all of their documents at once.
I've been able to use the API to generate an envelope with two documents assigned to two templates. Each template has three recipients (the same three people for both document). The envelope is automatically assigned to the first batch of recipients for the first template (Recipients A and B since they both have a routing order of 1). But when the recipient goes to sign the envelope, they only see the signature option for the first document and don't have an option to sign the second document.
Is what I am trying to achieve possible?
I'm testing this process in Postman. Below is a copy of the POST body. I appreciate any advice.
{
"compositeTemplates": [
{
"document": {
"documentBase64": "<<BinaryDataA>>",
"documentId": "1",
"fileExtension": "pdf",
"name": "Test Document A"
},
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"email": "<<recipient_a_email>>",
"name": "<<recipient_a_name>>",
"recipientId": "1",
"roleName": "Client A",
"routingOrder":"1"
},
{
"email": "<<recipient_b_email>>",
"name": "<<recipient_b_name>>",
"recipientId": "2",
"roleName": "Client B",
"routingOrder":"1"
},
{
"email": "<<recipient_c_email>>",
"name": "<<recipient_c_name>>",
"recipientId": "3",
"roleName": "Internal Review",
"routingOrder":"2"
}
]
}
}
],
"serverTemplates": [
{
"sequence": "1",
"templateId": "<<templateID_1>>"
}
]
},
{
"document": {
"documentBase64": "<<BinaryDataB>>",
"documentId": "2",
"fileExtension": "pdf",
"name": "Test Landscape Document"
},
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"email": "<<recipient_a_email>>",
"name": "<<recipient_a_name>>",
"recipientId": "1",
"roleName": "Client A",
"routingOrder":"1"
},
{
"email": "<<recipient_b_email>>",
"name": "<<recipient_b_name>>",
"recipientId": "2",
"roleName": "Client B",
"routingOrder":"1"
},
{
"email": "<<recipient_c_email>>",
"name": "<<recipient_c_name>>",
"recipientId": "3",
"roleName": "Internal Review",
"routingOrder":"2"
}
]
}
}
],
"serverTemplates": [
{
"sequence": "1",
"templateId": "<<templateID_2>>"
}
]
}
],
"status": "sent",
"emailSubject":"Please Sign this Document"}
Try this: (taken out of Gil's Composite Template Blog Post)
{
"emailSubject": "Please sign your lease agreement.",
"emailBlurb": "Each tenant must sign individual lease.",
"status": "sent",
"compositeTemplates": [{
"document": {
"documentId": "1",
"name": "Property-A",
"fileExtension": "pdf",
"documentBase64": "JVBERi...NCg=="
}
},
{
"serverTemplates": [{
"sequence": "1",
"templateId": "E5577130-xxxx-xxxx-xxxx-95DD79644971"
}],
"inlineTemplates": [{
"recipients": {
"signers": [{
"email": "wile.e.coyote#example.com",
"name": "Wile E. Coyote",
"roleName": "Tenant"
}]
},
"sequence": "2"
}]
},
{
"serverTemplates": [{
"sequence": "1",
"templateId": "E5577130-xxxx-xxxx-xxxx-95DD79644971"
}],
"inlineTemplates": [{
"recipients": {
"signers": [{
"email": "hunter_of_rabbits#example.com",
"name": "Elmer Fudd",
"roleName": "Tenant"
}]
},
"sequence": "2"
}]
}
]
}
The following JSON body allowed me to create an envelope with two Documents, each assigned to a different template. I did have to define the recipient information per composite item, but DocuSign recognised that they were the same person and they were able to sign both documents in a single session.
The blog (https://www.docusign.com/blog/dsdev-why-use-composite-templates) helped describe how composite envelopes are structured which was a big help.
{
"compositeTemplates": [
{
"compositeTemplateId": "1",
"document": {
"documentBase64": "<<BinaryDataA>>",
"documentId": "1",
"fileExtension": "pdf",
"name": "Test Document A"
},
"serverTemplates": [
{
"sequence": "1",
"templateId": "<<TemplateIDA>>"
}
],
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"email": "<<recipient_A_Email>>",
"name": "<<recipient_A_Name>>",
"recipientId": "1",
"roleName": "Client A",
"routingOrder":"1"
},
{
"email": "<<recipient_B_Email>>",
"name": "<<recipient_B_Name>>",
"recipientId": "2",
"roleName": "Client B",
"routingOrder":"1"
},
{
"email": "<<recipient_C_Email>>",
"name": "<<recipient_C_Name>>",
"recipientId": "3",
"roleName": "Internal Review",
"routingOrder":"2"
}
]
}
}
]
},
{
"compositeTemplateId": "2",
"document": {
"documentBase64": "<<BinaryDataB>>",
"documentId": "2",
"fileExtension": "pdf",
"name": "Test Document B"
},
"serverTemplates": [
{
"sequence": "1",
"templateId": "<<TemplateIDB>>"
}
],
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"email": "<<recipient_A_Email>>",
"name": "<<recipient_A_Name>>",
"recipientId": "1",
"roleName": "Client A",
"routingOrder":"1"
},
{
"email": "<<recipient_B_Email>>",
"name": "<<recipient_B_Name>>",
"recipientId": "2",
"roleName": "Client B",
"routingOrder":"1"
},
{
"email": "<<recipient_C_Email>>",
"name": "<<recipient_C_Name>>",
"recipientId": "3",
"roleName": "Internal Review",
"routingOrder":"2"
}
]
}
}
]
}
],
"status": "sent",
"emailSubject":"Please Sign this Document",
"emailBlurb":"This is a test email blurb"}

Docusign - Transform PDF text field to initialHereTab

Is it possible to transform PDF text field (not signature field) to initialHereTab ?
Note : it works well with signature field but not with text filed
Here is my JSON request:
{
"compositeTemplates": [
{
"compositeTemplateId": "1",
"document": {
"documentBase64": "PDFDocumentInBase64",
"documentId": "1",
"fileExtension": "pdf",
"name": "Merge_2020310203633868.pdf",
"transformPdfFields": "true"
},
"inlineTemplates": [
{
"recipients": {
"signers": [
{
"clientUserId": "1",
"email": "myEmail#email.ca",
"name": "Paul J Smith",
"recipientId": "1",
"tabs": {
"initialHereTabs": [
{
"tabLabel": "\\applicant1\\*"
}
]
}
}
]
},
"sequence": "1"
}
]
}
],
"emailSubject": "Please sign this legal form at your convenience",
"status": "created"
}
Yes, per the documentation:
If: Adobe name contains DocuSignInitialHere or eSignInitialHere
Then: a DocuSign Initials tab will be created

Docusign createEnvelope REST API with Composite Templates CANNOT_EXCLUDE_DOCUMENT Error

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:
Templateid- f09dc354-efd6-437e-9410-5270b181a1f1 Roles: Emp, Mgr (sign in sequence enabled)
Templateid- 8c919c05-ee1f-42c4-b521-861c5f2949b Roles: Emp
Templateid- 6b57ea78-5923-4c54-b4c1-15c8d5313e71 Roles: Emp, Mgr (sign in sequence enabled)
Success when sent with below sequence:
Templateid- 6b57ea78-5923-4c54-b4c1-15c8d5313e71 Roles: Emp, Mgr (sign in sequence enabled)
Templateid- f09dc354-efd6-437e-9410-5270b181a1f1 Roles: Emp, Mgr (sign in sequence enabled)
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?
I suspect how the Roles and Tabs are distributed matters, yet I can't see your template or the API Json sent.
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
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.
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.
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.

Docusign: composite templates with tabs

How do I specify prefilled fields with composite templates when creating an envelope.
I tried including the tabs information in the inlineTemplate.recipients.signers[0].tabs, but I get an error that System.String cannot be cast to API_REST.Models.v2.tabs.
If I include information as a template role in templateRoles, it is ignored. The documentation is light on information about how to do this. It seems like the prefill data should be specified in the inline template.
Other open questions I have include what does the recipientId do. What is the clientUserIdused for? We currently set clientUserId to the same value for all signers. I see it's used when signer requests a signature. Should it be unique to every signer for some reason?
It also looks like a single composite template overlays the server and inline templates on top of each other. What's the use case for having multiple server templates or multiple inline templates in a single composite template?
Are there plans to improve the documentation to describe how to use composite templates for various purposes?
Signer/template role:
{
"clientUserId": "clientUserId",
"email": "first+last#email.com",
"name": "First Last",
"roleName": "role1",
"tabs": {
"textTabs": [
{
"locked": true,
"tabLabel": "\\*FieldName",
"value": "prefillValue"
}
]
}
}
Example request:
{
"compositeTemplates": [
{
"inlineTemplates": [
{
"recipients": {
"signers": [
{
"clientUserId": "clientUserId",
"email": "first+last#email.com",
"name": "First Last",
"recipientId": 1,
"roleName": "role1",
"tabs": {
"textTabs": [{"tabLabel": "label", "value": "val"}]
}
}
]
},
"sequence": 1
}
],
"serverTemplates": [
{
"sequence": 1,
"templateId": "templateId1"
}
]
},
{
"inlineTemplates": [
{
"recipients": {
"signers": [
{
"clientUserId": "clientUserId",
"email": "first+last#better.com",
"name": "First Last",
"recipientId": 1,
"roleName": "role1",
"tabs": {
"textTabs": [{"tabLabel": "label", "value": "val"}]
}
}
]
},
"sequence": 2
}
],
"serverTemplates": [
{
"sequence": 2,
"templateId": "templateId2"
}
]
}
],
"emailSubject": "Email subject",
"status": "sent",
"templateId": null,
"templateRoles": null
}
Information on sending an envelope from a server template can be found here.
RecipientID is used by the tab element to indicate which recipient is to sign the Document while the clientuserID specifies if the user is remote or embedded and it is recommended it be unique per signer (but not required).
I'd also suggest reading this page about composite templates, hopefully the concept will make a bit more sense but I am with you that the lack of documentation on composite templates can be troublesome.
Unfortunately, I don't have a sample with tab data included, but adding the tab section under each recipient from my sample below should work with no issues.
{
"emailSubject": "DocuSign Comp Test 1",
"emailBlurb": "Example - Composite Templates",
"status": "sent",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "templateId1"
}
],
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"email": "testsigner123#gmail.com",
"name": "Test Tester",
"recipientId": "1",
"roleName": "Signer 1"
}
]
}
}
]
},
{
"serverTemplates": [
{
"sequence": "2",
"templateId": "templateId2"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"email": "testsigner123#gmail.com",
"name": "Test Tester",
"recipientId": "1",
"roleName": "Signer 1"
}
]
}
}
]
},
{
"serverTemplates": [
{
"sequence": "3",
"templateId": "templateId3"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"email": "testsigner123#gmail.com",
"name": "Test Tester",
"recipientId": "1",
"roleName": "Signer 1"
}
]
}
}
]
}
]
}

Docusign REST composite templates and embedded signing creates duplicate recipients

I'm having a problem creating an envelope from a composite template and having it not duplicate the recipient. Here is a sample of my call.
{
"emailSubject": "Please complete the following forms",
"status": "sent",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "5ff1b987-dc38-49b1-b394-840f10ad08bb"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"name": "Bob Sample",
"email": "bob.sample#example.com",
"roleName": "Client",
"clientUserId": "bob.sample#example.com",
"recipientId": "1"
}
]
}
}
]
},
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "02d947aa-6320-4a6b-b4b4-79c4c733d0d0"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"name": "Bob Sample",
"email": "bob.sample#example.com",
"roleName": "Client",
"clientUserId": "bob.sample#example.com",
"recipientId": "1"
}
]
}
}
]
}
]
}
When I look at the envelope it has Bob Sample twice in the signing flow. How do I make this call so that only one Bob Sample is required to sign?

Resources