I am currently using the REST api to create an envelope containing a document and a template which I have already set up in Docusign. I get the following error on the web request and can't find this error on the status code/error list provided by DocuSign to try debug the issue. Their support person suggests I ask here..
TAB_REFERS_TO_DOCUMENT_NO_TABS_ALLOWED -- The Tab refers to a document that does not allow tabs.
Has anyone experienced this?
Edit:
The issue appears to be related to the document section.
{
"emailBlurb":"Test Email Body",
"emailSubject": "Test Email Subject",
"status" : "sent",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence" : 1,
"templateId": "b1eccee3-9c00-4cb2-8d30-0400d51dcfe0"
}],
"inlineTemplates": [
{
"sequence" : 2,
"recipients": {
"signers" : [{
"email": "usera#bah.com",
"name": "usera",
"recipientId": "1",
"roleName": "Producer"
}]
}
}],
"document": {
"documentId": 1,
"name": "Test.docx",
"documentBase64":"[bytesremoved]",
"fileExtension":"docx"
}
}]
}
So you have a template on the server, with a document as part of the template?
But you want the envelope to use a different document with the template, yes?
It is my understanding that the documentId in the document section of the composite template must match the documentId used in the template if you want the document to be substituted for the template's document.
So check the definition of the template. Did you create the template programmatically or did you use the web browser DocuSign app? If the latter, then note that the first document in a template is not always given an id of 1.
Related
I created a DocuSign template that contains two roles: Provider and Recipient. I did this via the DocuSign Sandbox UI.
In my template, I have one document, with four tabs on it:
1. ProviderName
2. ProviderAddress1
3. RecipientName
4. RecipientAddress
Should I be using CustomFields vs. Tabs?
What's the API call(s) that I should be making to do the following, given a template with a document in it:
create an envelope for specific users
update the text within the document in the template for the specific users
send it out?
In the POSTMan sample, I tried using this URL, doing a POST:
{{baseUrl}}/envelopes
passing in a templateId, and the following JSON below in the POST body:
JSON:
{
"templateRoles": [{
"email": "{{signer1Email}}",
"name": "The Provider",
"roleName": "Provider",
"tabs": {
"textTabs": [{
"tabLabel": "ProviderName",
"value": "This is the provider!"
},
{
"tabLabel": "ProviderAddress1",
"value": "10 Provider Street, Baltimore, MD 21212"
}]
}
},
{
"email": "{{otherEmail}}",
"name": "Test Recipient",
"roleName": "Recipient",
"tabs": {
"textTabs": [{
"tabLabel": "RecipientName",
"value": "This is the recipient!"
},
{
"tabLabel": "RecipientAddress",
"value": "10 Main Street, Baltimore, MD 21212"
}]
}
}],
"emailSubject": "DocuSign API - Signature Request on Document Call",
"templateId": "<<template ID>>",
"status": "sent"
}
This does return an Envelope Id in the response, and I do receive the email with the DocuSign document to sign.
However, the tabs are NOT populated, they're blank.
Are the roles in the Template empty placeholders? If a name/email is defined on the template, the API call won't populate them as you might expect.
Try to add the documentId and pageNumber properties to your tabs. Also, ensure the label matches what is in the original template.
Lastly, you may need to add recipientId as well to each of the recipients to match what is in the template (this one may not be required since you have the roleName but just in case)
After reading (here and here) and trying out composite templates, I'm not quite sure I understand how to properly use the Server Templates within the API request. The documentation mentions If supplied they are overlaid into the envelope in the order of their Sequence value so I've interpreted this as they would be merged together as one document. It seems they are merged together but it is yielding a result that I would not expect. The first one in the sequence is what is shown and you cannot see the others.
What I'd like to do is have a couple common headers that contain our different logos and combine that with whatever template I'm sending out. We cannot use the branding approach because they want it as part of the document within the template and as far as I can tell, there is no way to make that happen with branding.
Below is my (scrubbed) request. See my comments.
{
"brandId": "{{brandId}}",
"emailSubject": "Testing Subject",
"status": "SENT",
"compositeTemplates": [{
"serverTemplates": [{ // First document
"sequence": "1",
"templateId": "{{headerTemplateId}}" //Header logo template
}, {
"sequence": "2",
"templateId": "{{document1TemplateId}}" // Template with content
}
],
"inlineTemplates": [{
"sequence": "1",
"recipients": {
"signers": [{
"email": "test#test.com",
"name": "Leeroy Jenkins",
"roleName": "Customer",
"recipientId": "1"
}
]
}
}
]
}, {
"serverTemplates": [{ // Second document
"sequence": "2",
"templateId": "{{document2TemplateId}}"
}
],
"inlineTemplates": [{
"sequence": "2",
"recipients": {
"signers": [{
"email": "test#test.com",
"name": "Leeroy Jenkins",
"roleName": "Customer",
"recipientId": "1",
"tabs": {
"textTabs": [{
"tabLabel": "Address",
"value": "123 Test Rd "
}, {
"tabLabel": "CityStateZip",
"value": "Test/XY/12345"
}
]
}
}
]
}
}
]
}
]
}
As #Drew says, your immediate issue is that each individual composite template can only include zero or one server template.
Re: How to properly use the Server Templates within a composite template
Each composite template composites together different aspects of an envelope:
Zero or one template definitions stored on docusign.com
Newly defined recipients, tabs, documents, etc.
For example, composite templates can be used to create an envelope that includes document "B" instead of using the document included in a template on docusign.com.
Changing logos in documents
Unfortunately, the DocuSign compositing feature does not include a feature for combining the images from one document with another document to create a new (combined) document.
Some ideas:
If only page one of the contract includes the logo, then you could have multiple versions of page one (treating each as a separate document), and combine the logoed page one with the other pages to form a complete envelope.
Note that a document can be as short as a page. Recipients will view all of the envelope's documents together.
Use a PDF library to manipulate the PDF document itself to change the logo. There are now many PDF libraries available, with APIs for many languages and operating systems.
Use a SAAS PDF rendering service to combine the images with the content to obtain the final PDF. Eg, webmerge
Send DocuSign the document in a non-PDF format. For example, you can send a .docx document. If you're using the Windows stack, it may be easier for your application to create a custom logo version of a Word doc than a PDF.
Using the docusign rest api i would like to create an envelope with 2 documents.
I will then be using the Post Recipient view to show document 1 to the first recipient (in an iframe) and once signed show document 2 in the same envelope to another recipients.
i have created the templates with different tempalteRoles (different names, order 5 and 10).
Its my understanding using a userId and the right settings in my docusign account, i can show document 1 to recipient 1 and then document 2 to recipient 2.
When i try and create the composite envelope the whole document is shown.
when i call the recipient status for the envelope it only shows one signer.
I have found the envelope will only create when the 2 template roles have the same clientUserId, userName and email, otherwise i get the error "ONESIGNALLSIGN_NOT_SATISFIED"
here is the envelope i am sending through
{
"accountId": "ACCOUNT_ID",
"emailSubject": "Email subject",
"status": "sent",
"templateId": "TEMPLATE_ID",
"templateRoles": [
{
"roleName": "PDS Customer",
"email": "pds#example.com",
"name": "TestFirstName TestSurname",
"clientUserId": "1",
"tabs": {
"textTabs": [
{
"tabLabel": "DocumentNumber",
"value": "123456789",
"locked": true,
"documentId": 1,
"pageNumber": 1
}
...removed some
]
}
},
{
"roleName": "Customer",
"email": "test#example.com",
"name": "mrTestFirstName TestSurname",
"clientUserId": "2",
"tabs": {
"textTabs": [
{
"tabLabel": "StorerEmail_LocalPart",
"value": "test",
"locked": true,
"documentId": 2,
"pageNumber": 1
}
...removed some
]
}
}
],
"compositeTemplates": [
{
"compositeTemplateId": 1,
"serverTemplates": [
{
"sequence": 1,
"templateId": "TEMPLATE_ID_2"
}
]
}
]
}
The error message is due to having Document Visibility enabled. In that scenario, each signer must have at least one tab present. Your second signer (embedded or not) must have at least one tab. In this case it'd probably be on the second document.
Your API call above does refer to a second documentId though so you may be okay there.
I would suggest that you not mix the "simple" sending (using templateRoles at the top level) with composite templates. Instead, add an inline template to the compositeTemplates structure with all of your recipient information. You may be seeing some odd behavior due to mixing those.
Lastly, the default Document Visibility configuration will show a document to a recipient only if they have a tab on that document. If your second signer should see all documents then you must either add a tab for them on each document or explicitly set visibility per document.
I am creating composite templates that work correctly and I'm running into this issue.
I am adding 2 templates to sign via docusign. I set the routing orders for both of them as shown below:
Form 1
Order 1 RoleName signer test1#gmail.com
Order 2 RoleName signer2 test2#gmail.com
Form 2
Order 1 RoleName dataEntry test1#gmail.com
Order 2 RoleName dataEntry2 test2#gmail.com
This will send one email to test#gmail.com. This user completes all of his fields for both Form 1 and Form 2 in one request. This is what I want and expect. However, when test1#gmail.com completes their process, test2#gmail.com will receive 2 different emails. One to sign form 1 and the other to sign form 2. I'm trying to understand why test2#gmail.com doesn't work the same as test1#gmail.com. Can someone help explain what the reason is for receiving 2 separate emails for test2#gmail.com may be and if there's a way to fix it?
Note: When I do this via the docuSign website, it doesn't allow for the same recipient to be in that same routingOrder. It will bring up the error:
The role 'signer' conflicts with 'dataEntry'
The role 'signer2' conflicts with 'dataEntry2'
This behavior seemed strange to me since I'm able to send the envelope using the docusign rest API. If somebody could give me some clarification on this as well I'd appreciate it.
Thank you!
I am unable to repro the issue you describe. Here's what I did, and the Result:
I created two separate templates in DocuSign, each having a single document and two recipients/signers (with Role Names and Routing Orders that you specify above in your question).
I used the REST API (JSON request included below) to create/send an Envelope from these two Templates, specifying identical recipient information (name/email/recipient ID/routing order) for Recipient 1 and Recipient 2 across both Inline Template structures.
Result: Recipient 1 receives an email first, opens the envelope, and signs both documents at once. Then Recipient 2 receives an email, opens the envelope, and signs both documents at once. The Envelope status is "Completed" at that point.
I've included my API request below for your reference -- perhaps compare/contrast this with what you're doing? Also -- make sure that Recipient information (Name / Email / Recipient ID / Routing Order) is identical (including case) for each recipient between the first Inline Template and the second Inline template within the API Request -- any small difference in Name/Email/Recipient Id/Routing Order, and DocuSign will treat them as different/separate people (recipients).
POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
"emailSubject": "Please sign",
"emailBlurb": "Please sign...thanks!",
"status": "sent",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence" : 1,
"templateId": "TEMPLATE_ID_1"
}],
"inlineTemplates": [
{
"sequence" : 2,
"recipients": {
"signers" : [{
"email": "adamsemail#outlook.com",
"name": "Adam Adamson",
"recipientId": "1",
"roleName": "signer",
"routingOrder": "1"
},
{
"email": "bobsemail#outlook.com",
"name": "Bob Burns",
"recipientId": "2",
"roleName": "signer2",
"routingOrder": "2"
}
]
}
}]
},
{
"serverTemplates": [
{
"sequence" : 1,
"templateId": "TEMPLATE_ID_2"
}],
"inlineTemplates": [
{
"sequence" : 2,
"recipients": {
"signers" : [{
"email": "adamsemail#outlook.com",
"name": "Adam Adamson",
"recipientId": "1",
"roleName": "dataEntry",
"routingOrder": "1"
},
{
"email": "bobsemail#outlook.com",
"name": "Bob Burns",
"recipientId": "2",
"roleName": "dataEntry2",
"routingOrder": "2"
}
]
}
}]
}]
}
I've been able to successfully start an envelope with a template using the templateID, but I'm attempting to generate an envelope with two documents inside that both have templates. In the DocuSign website interface it's possible to start a new envelope then "check off" multiple templates to add to the envelope.
I've found the API calls to:
Start an envelope with a template
Get a template
Add a document to an envelope
However, there's unfortunately nothing that I can find to add a template to a draft envelope once it's been created. The question here, in case it's not obvious, is: what is the API call to generate a new document from a template and add it to a pre-existing envelope in created status?
You can create an envelope based on multiple templates. The trick is to use the compositeTemplates optional property of the request.
Back in April 2013 I hosted a webinar focused on templates where I demonstrated 3 different template examples. They were increasing in complexity leading up to the third, where that last one shows how to combine multiple templates into one envelope. Here is the Gist for it, which contains PHP code and sample JSON bodies:
https://github.com/Ergin008/DocuSign-REST-API-Webinar-April2013
Here is the JSON for the third example, you'll want to add something similar to your request body:
{
"emailSubject": "DocuSign Templates Webinar - Example 3",
"emailBlurb": "Example #3 - Composite Templates",
"status": "sent",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "55A80182-2E9F-435D-9B16-FD1E1C0F9D74"
}
],
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"email": "test#docusign.com",
"name": "First Recipient",
"recipientId": "1",
"roleName": "RoleOne"
}
]
}
}
]
},
{
"serverTemplates": [
{
"sequence": "2",
"templateId": "44D9E888-3D86-4186-8EE9-7071BC87A0DA"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"email": "test2#docusign.com",
"name": "Recipient 2",
"recipientId": "1",
"roleName": "RoleOne"
}
]
}
}
]
}
]
}
Note that the sequence property of the server template can be used to change the order that the template documents show up in the envelope.
To add to Ergin's answer.
You can add a template to an existing envelope using the applyEnvelopeTemplates api.
You can add templates to a document in the specified envelope using the EnvelopeTemplate:applyToDocuments api