Populating Tabs In An Existing Draft Envelope With The tabLabel - docusignapi

Is it possible to map data to tabs in an existing envelope using tabLabels? If not, do I just need to specify the tabId to indicate which tab should be populated with my data or is there a different identifier that I should use?
Background - I've been populating tabs while creating envelopes with a template based on this process. So if I'm populating a text tab, my json looks like:
{
"textTabs": [
{
"tabLabel": "text",
"value": "Jabberwocky!"
}
]
}
I'm mapping the contents of form fields from another form building service to the tabs in my DocuSign form and since I can specify which tabs should be populated based on the tabLabel, I've mapped my form fields to tabLabels. This works fine when creating a draft envelope.
But I need to populate more tabs in my draft envelope with the contents of subsequent form submissions from separate forms. I'd like to use my existing map of form fields > tabLabels but when I try with Envelopes Update or EnvelopeRecipientTabs (I'm not sure which I need to use here), DocuSign adds new tabs to my envelope, rather than mapping my data to the existing tabs 🥲
As far as I can tell, unique tabIds are generated each time a new envelope is created. So it'd be much easier to use tabLabels, which are always the same for each envelope.

In the end I did have to use tabIds when updating recipient text, checkbox and radio tabs in a draft envelope but that's it.
As I mentioned, when populating tabs while creating an envelope I can use the tabLabel + value. When updating tabs, I can use the tabId + value.
Rather than creating a new map based on tabIds, I was able to fetch the draft envelope's recipient tabs and match them with the keys in my existing map, based on the tab's tabLabel, which remained the same after the draft envelope was created.
Examples
Text or checkbox tabs
During envelope creation:
newTab = [
'tabLabel': label,
'value': tabValue
]
Updating recipient tabs for a draft envelope:
newTab = [
'tabId': tabId,
'value': tabValue
]
Radio button tabs
During envelope creation:
radioButton = [
'selected': true,
'value': value
]
Updating recipient tabs for a draft envelope:
radioButton = [
'selected': true,
'tabId': tabId
]
Obviously radio button tabs need to be put in a group like
newTab = [
'groupName': groupName,
'radios': [radioButton]
]

You should use EnvelopeRecipientTabs like you mentioned.
Which means you need to have the recipientId for the specific recipient that the tab is associated with (every tab is part of a specific recipient).
So you build a URL like this:
PUT restapi/v2.1/accounts/{ACCOUNT_ID}/envelopes/{ENVELOPE_ID}/recipients/{RECIPIENT_ID}/tabs
Now in the body of the request you need to have the following fields:
documentId, recipientId, tabLabel, tabId, value
tabId is a unique GUID that you can find if you check your envelope (you can make a GET to the envelope and include tabs)
tabLabel must also match

Related

DocuSign - Add pre-fill tabs through JSON marker

I'm creating a html document and want to place tabs using JSON markers. This method works for common tabs of signers. However, I want to add pre-fill tabs for senders using the same approach but all pre-fill tabs are not showing up.
I'm using CompositeTemplate to generate the envelope. As pre-fill tabs don't belong to any recipients, so I put them under document level. The code snippet looks like
EnvelopeDefinition().apply {
emailSubject = ...
emailBlurb = ...
this.status = "created"
compositeTemplates = listOf(
CompositeTemplate().apply {
document = Document().apply {
documentId = "1"
name = "some document.pdf"
htmlDefinition = "<div>{{\"tabLabel\": \"exampleTextTab\"}}</div>"
tabs = Tabs().apply {
prefillTabs = listOf(
PreFillTab().apply {
tabLabel = "exampleTextTab"
font = "arial"
fontSize = "size8"
locked = "true"
}
)
}
Pre-fill tabs don't currently work with Composite Templates. DocuSign internal ticket TT-5404
Solutions
Will your API program be setting the values of the pre-fill tabs? If so, then don't use pre-fill tabs. Instead:
use regular tabs with the first signer
set the locked attribute to true
This makes the tabs read-only and they will be visible to all recipients. This will have the same effect as your API application adding and setting pre-fill tabs to the envelope.
Pre-fill tabs are needed when the Sender needs to fill in the values and the Sender is not one of the recipients of the envelope.
For an API program that uses the Sender View to enable the Sender to review the envelope and fill in pre-fill tabs, there are some options:
Your API application can ask the Sender for the pre-fill tab values. Your application can then set those values as regular (locked) tabs as described above.
Or you could add the pre-fill tabs to the template itself.
Or (I have not tried this), instead of adding the pre-fill tabs as part of the composite template object, make an additional API call to add the pre-fill tabs by using EnvelopeDocumentTabs:create

What is a DocuSign template's documentID?

I'm using a DocuSign template that has multiple documents. I want to use composite templates to substitute a new document at runtime.
How do I determine the document ID that the template is using?
The template's first document usually has ID 1.
To see a specific document ID:
Open the template for editing
Click View for the document of interest
On the document's modal display: open the browser's menu and choose "Open image in new tab"
Inspect the new tab's URL. The number after /documents/ is the document ID. Eg URL .../documents/456/pages/... has document ID 456

How can I attach a Custom Tab to a Docusign Envelope?

Looking through the Docusign API documentation I am unable to figure out how to attach a Custom Tab to an Envelope. Using the traditional tabs sometimes forbid me from setting the text. Hence, the need for a Custom Tab. Using the CustomTabsAPI I can create a Custom Tab. What remains is the ability to attach the Custom Tab to the envelope.
You can add custom tabs to envelopes and templates by setting the
customTabId property when creating an envelope, template recipient, or
when adding a new tab for an existing recipient.
I am using the EnvelopeDefinition to create my envelope. I was expecting something like:
envelope_definition = EnvelopeDefinition(
custom_fields=custom_fields,
documents=documents,
recipients=recipients,
status='created',
event_notification=event_notification,
email_settings=email_settings,
custom_tabs=custom_tabs # <------ SOMETHING LIKE THIS
)
Any suggestions? An example of how to add custom tabs? Documentation? TIA
EDIT: Here is the textTab I currently have in place
signer = Signer(**args)
title_text = Text(
anchor_string=anchor_string,
anchor_units="pixels", anchor_y_offset="10",
anchor_x_offset="0", width="180", value=initial_value
)
signer.tabs = Tabs(text_tabs=[title_text])
example img of text not editable
example img of custom tab this can be edited
If I can get the TextTab to be edited, that would be great.
Summary of the solution:
The title tab is a system tab so the value can't be set.
Instead, the OP will use a text tab, set its value, and set the attribute locked to false to enable the signers to update it.

Docusign, pre-filling template, text and radio confusion - general data tab?

I'm using the ruby_gem to pre-fill a Docusign template in embedded signing. I currently have mostly textLabels, 1 radio and a couple of checkboxes.
It just dawned on me that to proper pre-fill the values on docusign, I have to tie the docusign data model to to match Docusigns...
What I'm trying to do
signer = DocuSign_eSign::TemplateRole.new({
clientUserId: form["user_id"],
email: form["email"],
name: form["full_name"],
roleName: 'signer',
tabs: {
"textTabs" => form.map { |k, v| { "tabLabel" => k, "value" => v } },
},
})
Now what I was hoping, was that I could simply call out the tabLabel, and have the value passed along. So textTabs is obvious, for radio buttons, simply select the value passed along, and for checkboxes, my data will say true/false
However, radioButtons do not get the value, because as I can tell from the documentation, I have to add a secondary tap style, called radio_group_tabs? And I imagine it's the same story with checkboxes...which means, I have to to tie my data model to that of docusigns, or at least build some middleware to pluck radio data, and checkbox data...which really now, docusigns API is bleeding into my code like nothing else.
Is there ANY way around this? What I want seems simple. Declare the tabLabel, assign the value
radio buttons are part of a group, because their logic dictates that. You don't want someone to be able to pick more than one, but how do you know which ones they can or cannot pitck?
Checkboxes are not like that, but their value is not what you are looking for, you need to either have them checked or not.
So, no, if you're looking for DocuSign object model to be like that of HTML DOM, it's not the case, you do have to work out the differences.

Text Tab Locking

My application has workflow that defines all of the content needed to sign a document on the DocuSign platform aside from signatures. I'm using a parameter in my text tabs to ensure that values can only be edited within my application and workflow:
tabs: {
textTabs: [
{
name: 'Name',
tabLabel: '\\*Label',
value: 'foo',
locked: true
}
]
}
When the value of the tab has no content provided, it becomes an editable field on the platform during signing; is there a way to prohibit modification of a tab entirely? It is my preference that only signatures can be provided and the remainder of the document is left uneditable.
Some options:
If the text tab is blank, and you do not want a recipient to enter information into the tab do not include it when creating your envelope
You can specify the locked=true property. The tab itself will not be visible to a signer if it is locked=true and empty.

Resources