Merge Fields and Tags

Intro

Merge Fields (a.k.a. Merge Tags) are a special syntax employed by 3B Docs to allow merging of Salesforce data within a document. Merge tags are characterized by that they always have a context

Usage

Adding merge tags requires some knowledge of the context structure of a document. The context of the document is usually the object from which you will be merging data from, however in certain scenarios, you may be merging data from related parent or child records to the document’s contextual record.

You can also format a merge tag’s return value using Value Formatters.

How To

You can obtain a merge tag in a number of ways, however the end result is always going to be that if the merge tag is valid, you will get the value from the field in Salesforce to replace the added merge tag.

A generated merge tag will look something like this: #{Contact.Id:Account.Parent.Name}

Let’s digest this:

• The starting pound sign and curly bracket (#{ ) indicate the start of the merge tag
• “Contact” is the Merge Object context
• Immediately after, “Id” is how we match the merge object’s record. In this case, we match it by the ID. If this tag was added at the base of the Template, we would require that the URL Param’s “recordId” param is set to that of a valid Contact in the system.
• The “:” column indicates that we want a particular field relative from the merge object
• “Account.Parent.Name” is the field path relative from the Contact Object
• The ending curly bracket indicates the end of the merge tag

Here are a few ways to get a merge tag:

Using The Merge Tag Composer

You can use the merge tag composer to get a merge tag generated based on the selections you make.

The merge tag composer is the three top most drop downs that you see within the template editor.

• The first Drop Down determines the contextual object (a.k.a. Context Object)
• The second Drop Down determines merge tag’s context (a.k.a. Merge Object)
• The third Drop Down allows you to select a field on the Merge Object. If you select a relationship, you will automatically traverse to the parent object of the Merge Object. You can traverse as many levels deep as you like!

Using The Special “#” Symbol

Whenever you type the pound (“#”) sign in the document editor, you will see a drop down with field options. This drop down is generated based on the current context. Simply select the field you want to add via your keyboard or mouse.

Writing The Merge Tag Yourself

As you get more and more experienced with the product, you may start writing merge tags yourself!

Error Handling

Let’s say that somehow you managed to misspell the field “LastName” on the Contact object. If you added a merge tag like this #{Contact.Id:LastNameWrong}, the generated document would catch this bad merge tag and will ignore it. Instead of merging with data from Salesforce, you will see the merge tag replaced with “Invalid Field”

Please note that we vet all fields to ensure that they are valid and we strip them when getting the data from Salesforce. This means, that if all of your fields are valid but one is invalid, we will still render the document as usual, but the invalid field will be clearly replaced with "Invalid Field”

In order to avoid exposing documents with wrong/invalid fields, please make sure to use the Document Preview feature before Publishing the document.

Tips & Tricks

Remember that you can always apply Value Formatters to merge fields in order to transform the return value of the merge field.