Conditional field values
Conditional fields enable the value of one eSignature envelope field to control the visibility of one or more other fields (tabs) in the document. These other fields are conditionally visible. For example, if a Yes/No dropdown field “Different Billing Address” is set to Yes, an additional set of address fields is shown to the signer. Within the eSignature API and the Developer Center documentation, the conditional field is referred to as the “parent” field.
Conditional fields are flexible; many types of fields can be used to control the visibility of other fields. A conditional field can also control the visibility of other conditional fields.
But how does your application determine the value of a field that is conditionally visible (controlled by the field’s parent field)? Note that the value attribute of a field that is not visible will vary, depending on whether the recipient entered a value into the field while it was visible or not.
If the tab (field) is conditionally visible, then it will have two additional attributes, conditionalParentLabel and conditionalParentValue. If these attributes are not present, then the tab is always visible. If the attributes exist, then use conditionalParentLabel to find the parent tab (same recipient) and conditionalParentValue to determine if the tab was visible or not.
Conditionally visible fields have three categories of values:
- The field is visible and has a value
- The field is visible and its value was not set (and the field is not required)
- The field is not visible (there is no useful value if the field is not visible)
Notes:
- The value of a conditionally visible field that is not visible is indeterminate. In some cases, if the recipient sets the field’s value and then causes the field to become not visible, the field will have the previously set “value” that should be ignored.
- The action of your application when the field is not visible is application-specific. For example, if a “Different Billing Address” field is set to No, then the conditionally visible billing address fields from the envelope must be ignored. Instead, the application’s billing address fields will be set from the shipping address fields.
Determining the value of a conditionally visible field
This JavaScript pseudocode can be used to determine the value of a conditional field. It sets two variables, visible and value. Important: value is only valid if visible === true
Note: The in operator returns true if the attribute exists within the JSON object.
recipientTabs = getApiResults("EnvelopeRecipientTabs:list")
function isVisible(conditionalParentLabel, conditionalParentValue) {
// Search through the Checkbox, Radio button, Dropdown,
// Numerical, and Text tabs for the matching tab where
// <tabLabel> === <conditionalParentLabel>
tab = find (conditionalParentLabel tab from within recipientTabs);
// compare the tab's value with <conditionalParentValue>
// If the tab is a Checkbox or Radio button and the
// conditionalParentValue is "on" then the Checkbox or Radio button
// must be selected.
visible = sameValue (getValue(tab), conditionalParentValue)
return visible
}
// the mainline
forEach (tab within recipientTabs) {
if ("conditionalParentLabel" in tab) {
// this tab is conditionally visible
visible = isVisible(tab.conditionalParentLabel,
tab.conditionalParentValue)
value = undefined
if (visible) {
value = getValue(tab)
// <value> or <selected> depending on tab type
print `Tab ${tab.tabLabel} is visible with value ${value}`
} else {
print `Tab ${tab.tabLabel} is NOT visible`
}
} else {
// this tab is always visible
visible = true
value = getValue(tab)
// <value> or <selected> depending on tab type
print `Tab ${tab.tabLabel} is visible with value ${value}`
}
}
Note: If the parent tab is a Numerical tab, then the comparison should first convert both the tab’s value and the conditionalParentValue to numbers. For example, if a tab should be visible when the Numerical tab equals 10, the tab may return “10.00” as its value. In this case, a string comparison would fail since the strings “10.00” and “10” are not the same.
Conclusion
Determining the value of a conditionally visible tab is complicated because the recipient may have made the tab visible, filled it in, and then later changed the parent tab, causing the first tab to become invisible. By design, if a tab becomes invisible, DocuSign keeps the previously entered value of the tab. This saves the signer the work of re-entering the data if they later make the tab visible again.
The DocuSign UX feature requires application developers to determine if a tab was visible or not when the recipient signed.
