Code Walkthrough: Anchor Tabs

Anchor Tab Overview
In this electronic signature code walkthrough, we'll cover Anchor Tabs. If you want a general overview of DocuSign Tabs, you can click for more information.

An Anchor Tab is any DocuSign Tab defined by its relative location to a string in the document's text. To illustrate this, let's consider the scenario of a user signing up for a new service. The user will have to sign a service contract, and this contract may change depending on where the user lives. When the contract changes, the place where the user must sign will also change - it will shift down the page as more lines are added to the contract.

If we attempt to use a Fixed Tab in this scenario, we will have to calculate the Fixed Tab location for every possible variant of the contract, and store those in our application, and then use the correct location depending on where the user lives. Clearly we don't want to do this additional work.

The solution to this problem - Anchor Tabs. Since an Anchor Tab works by matching a string present in the document's text, we would just need to examine the document and see if there is a suitable bit of text. Many contracts have something like “Sign Here” printed on the document, so we could use that as the anchor text, and then DocuSign would place a Signature Tab on the document everywhere it finds the text “Sign Here”.

Now, if for some reason we insert a new paragraph in the middle of the contract, and the “Sign Here” text moves down the page, the Signature Tab will follow it.

That's the simple scenario, just to illustrate the concept. Let's look a little deeper to examine some real implementation strategies.

The Details
Anchor Tab placement happens when your envelope is sent to DocuSign. DocuSign will parse the envelope. If it sees an Anchor Tab defined, then it will perform a Text search on the specified document. It will get the X & Y coordinates of every instance of the anchor text, and create a new Fixed Location tab using those coordinates. It does this by finding the bounding box of the anchor text (basically the rectangle containing the text) and using the Lower Right corner of the bounding box as the Lower Left corner of the Tab.

You can fine tune the position of the placed Tab by setting the X and Y offset properties of the Anchor Tab. This will simply move the Tab in the X or Y from its calculated position. You can set the Units for the offset, so it can specified in Pixels, or Inches, or Centimeters, or Millimeters. Remember that the offset will be applied to every tab generated by the Anchor Tab - so if your anchor text is found in five places, you will get five Fixed Tabs, and they will all be shifted by the offset amount.

Selecting your Anchor Text can be challenging - sometimes it's obvious, but other times it isn't. Remember that you can use any text as an anchor, so as long as the text is in a fixed location relative to the signature block. You should also remember that the anchor text should only be present near the signature block - If you use a common word or phrase as the anchor, you will end up with a Tab at every place that the anchor text shows up in the document.

If you can't find good anchor text in your document, you may be able to add it. One very common solution is to edit the contract, and place text strings in every location that needs a Tab. Once entered, you change the text to the document's background color so they are effectively invisible but still parseable. You can utilize a naming convention that will help you assign the tabs correctly. For example, a signature tab for the first recipient might be indicated by placing '\s1\' at the appropriate place, and the signature tab for the co-Signer could be indicated by '\s2\'. Initials could be indicated by '\i1\' and '\i2\', optional initials by '\oi1\' and so on and so forth.

If you are having trouble getting the Tab placed correctly, you can always log in to the DocuSign console and create a new envelope with your document and use the Web Tagger to create Anchor Tabs and see them positioned in real time. This exercise will familiarize you with Anchor Tabs in general.

The Anchor Tab also supports a flag, called “IgnoreIfNotPresent”, that allows you to control what DocuSign will do if it doesn't find the anchor text in the document. If this flag is set to False, then DocuSign will throw an exception if it doesn't find the text. If it is true, then no exception will be thrown and the envelope will be sent. This allows you to specify Anchor Tabs that will be placed if the text is found, and ignored otherwise. This can be very handy if your documents are generated dynamically and may contain optional clauses that require initials if present.

The Code
So that we know all about Anchor Tabs, let's place a couple of them. If you read the article on Create And Send Envelope , I'm using the same code here, so this will just be adding an anchor tab to the envelope that we constructed there. We will add a tab that looks for the text “X:”, and is offset 50 pixels right and 100 pixels down. We will also specify the flag that tells DocuSign to send the envelope even if it doesn't find the Anchor Text.

// .NET
Tab tab = new Tab();
tab.DocumentID = "1";
tab.RecipientID = "1";
tab.Type = TabTypeCode.SignHere;
tab.PageNumber = "1";
tab.AnchorTabItem = new AnchorTab();
tab.AnchorTabItem.AnchorTabString = "X:";
tab.AnchorTabItem.Unit = UnitTypeCode.Pixels;
tab.AnchorTabItem.UnitSpecified = true;
tab.AnchorTabItem.XOffset = 50;
tab.AnchorTabItem.YOffset = 100;
tab.IgnoreIfNotPresent = true;

// PHP
$tab = new Tab();
$tab->Type = "SignHere";
$tab->DocumentID = "1";
$tab->RecipientID = "1";
$tab->PageNumber = "1";
$tab->AnchorTabItem->AnchorTabString = "X:";
$tab->AnchorTabItem->Unit = "Pixels";
$tab->AnchorTabItem->XOffset = 50;
$tab->AnchorTabItem->YOffset = 100;
$tab->AnchorTabItem->IgnoreIfNotPresent = true;

So that's it. Remember, Anchor Tabs are a Tab Location option, and they can be used with any type of Tab, not just Signature Tabs. As always, if you have any questions about these API methods, please use the DocuSign DevCenter forums for assistance.

Photo by Dorron