Examples of Basic Merge Fields

Predefined Merge Field Codes

The following table provides a list of merge field codes that automatically map to certain values, mostly having to do with assignees. These predefined codes make it easy to quickly map merge fields to assignees' contact information. This technique can also be used for custom fields of type Involved, as described in Automatically Mapped Custom Fields.

Note: The technique behind the merge field codes for people is that the colon (:) is replacing the navigation.user.contact or .contact.

Predefined Merge Field Codes

Naming Merge Fields for Auto-mapping System Fields

You can cause system fields to be mapped automatically by following a naming convention in your merge field names:

@attributepath

where attributepath is the object attribute path that points from the starting object to the system field.

Object attributes are listed in Object Model: Read This First. To identify a system field that is related to the main object, create a path of attribute names that leads to the needed system field, delimited by periods (.).

Keep the following points in mind:

• If the system field is within the main object on which the template is based (such as the project number), then the path only contains one attribute with no periods.
• The final attribute cannot end with an arrow (->) in the attribute name as shown in Object Model: Read This First (or in related reference tables it points to) or the Object Navigator. For example, to select a contact, you must continue the path from contact-> to identify the name or some other attribute of the contact.
• You cannot create a path through an attribute that ends with List->, because these are related and sub-objects. For these, you must use loop@ or filter@ merge fields.
• System field names (known as object attributes) are case sensitive. Make sure to match the exact name and capitalization of the field name.

The following are examples of merge fields in a document template that is based on a project (such as Matter) that would be mapped automatically.

Examples of System Field Automatic Mapping

To automatically map a merge field to a custom field

1. Create a merge field with the following merge field name:
   @Detail[categoryTreePosition]/customFieldName
   where categoryTreePosition is the tree position of the category to which the custom field belongs, and customFieldName is the name (not the label) of the custom field.
   
   Examples:
   @Detail[CLMS_DEPA]/LiJudgeSettlemtDate
@Detail[PRTP_0013]/PartyDate1
    
2. If the custom field is of type Involved, and you want to retrieve an attribute of the Involved's contact record, you can append a colon (:) and the name of the attribute, as described in the Predefined Merge Field Codes table.
   
   For example, if InvolvedOCAttorney is a custom field of type Involved where an involved OC attorney is identified:
   @Detail[MATT_LITI]/InvolvedOCAttorney:name
@Detail[MATT_LITI]/InvolvedOCAttorney:firstName
@Detail[MATT_LITI]/InvolvedOCAttorney:phone
@Detail[MATT_LITI]/InvolvedOCAttorney:street
@Detail[MATT_LITI]/InvolvedOCAttorney:city
@Detail[MATT_LITI]/InvolvedOCAttorney:state
@Detail[MATT_LITI]/InvolvedOCAttorney:postalCode
    
3. If the custom field is of type Custom Object, and you want to retrieve an attribute of the Custom Object record such as the name or number, you can append a period (.) and the name of the attribute.
   
   For example, if Litigation is a custom field of type Custom Object where a Litigation is identified:
   @Detail[MATT_LITI]/Litigation.name
@Detail[MATT_LITI]/Litigation.numberString
    
4. If the custom field belongs to a related object of the main record for which the document template is created, nest the merge field within filter@ or loop@ merge fields. Otherwise, it does not need to be nested.

If you followed these steps correctly, the custom field is mapped automatically when you open the RTF in the Data Mapping tool in TeamConnect. See Locating the Data Mapping Tool for more information.

Tip: If you prefer not to map the custom field automatically, try mapping it manually in the Data Mapping tool, as described in Custom Field Mapping.

loop@ Merge Fields for Selecting Related or Sub-objects

If you need to include fields from sub-objects or related objects in the document template, and you do not want the user generating the document to select them from a list, then use loop@ in your merge field codes in the RTF file.

Note: For users of Document Generator, loop@ corresponds to the Document Generator tag tc:loop for sub-objects and tc:search for related objects.

The Data Mapping tool provides you with additional options for filtering the available sub-objects or related objects. For example, you may want to get the business address, not just any address listed for the contact. See Locating the Data Mapping Tool for more information.

In some cases, even with criteria that you specified, multiple sub-objects or related objects may be found. For example, a contact may have more than one business address. In this case, data from all of them will be listed in the generated document.

For details about how to perform mapping, see loop@ Merge Field Mapping.

Related and Sub-objects Available Through filter@ or loop@

When NOT to Use loop@

Do not use loop@ under the following circumstances:

• If you want the user to manually select which sub-object's or related object's information to include in the generated document, you should use filter@. For details, see filter@ Merge Fields for User-selected Related or Sub-objects.
  If you want the user to manually select a sub-object or related object only when more than one is found, you should also use filter@.
• If you want to retrieve the address (or other sub-object) of the contact in a contact-centric project, you cannot use loop@. Instead, it is recommended to retrieve the default address of that contact, using a basic merge field that is mapped to an object field.
• If you want to get a sub-object that is set as "default," such as the default category, default address, or default phone number, you can do this with a basic merge field or an auto-mapped merge field, instead of a loop@ merge field. For examples, see Automatically Mapped System Fields.
• If you want to get the main assignee's name, you can do this with a basic merge field or with an automatically mapped field. See Automatically Mapped System Fields.

Inserting loop@ Merge Fields

To set up loop@ merge fields for sub-objects or related objects

1. In the RTF, insert a merge field with a name that starts with loop@ followed by the text of your choice.
2. Insert (or nest) basic merge fields for the data that you need to retrieve from the sub-object or related object, formatted the way you want them to appear in the generated document.
3. Complete the loop with a merge field named simply loop@.

For example:

The local office is located at the following address:
<<loop@partyAddress>><<street>>
<<city>>, <<state>> <<zip>>
<<loop@>>

This would generate the following:

The local office is located at the following address:
124 North Woodranch Road
Glen Oaks, CA 94551

For details about how to map these merge fields to TeamConnect data, see loop@ Merge Field Mapping.

filter@ Merge Fields for User-selected Related or Sub-objects

Using filter@ merge fields causes the document generator to pause at runtime and prompt the user to make a selection before the generator continues.

If you want the user to select related objects or sub-object(s) from which data must be retrieved, use filter@ merge fields. The Related and Sub-objects Available Through @filter or @loop table provides a list of related objects and sub-objects that the user can select for including data in the generated document.

When you use filter@ to define merge fields, you specify which related object records or sub-objects the user can select while generating the document. Data is then pulled into the document from the user-selected related records or sub-objects.

You can also nest a filter within another filter. For example, if you need the user to select a child project, and then select an assignee, you would nest one set of filter@ merge fields within another.

Note: filter@ corresponds to the Document Generator tag tc:filter.

When NOT to Use filter@

You should not use filter@ in the following circumstances:

• If you want to retrieve sub-object or related object data automatically, and you do not want the user to select which sub-object or related object to retrieve, use loop@. See loop@ Merge Fields for Automatically Selecting Related or Sub-objects.
• If you want to get information from the parent record of a project, use an automatically mapped merge field. See Automatically Mapped System Fields.
• If you want to get information from a record that is not related to the record for which a document is being generated, this is currently not possible with EasyDocs. Instead, you must create a Document Generator template manually using XML tags, as described in About Document Generator.

Inserting filter@ Merge Fields

To set up filter@ merge fields for related or sub-objects

1. In the RTF, insert a merge field with a name that starts with filter@ followed by the text of your choice.
2. Insert (or nest) basic merge fields for the data that you need to retrieve from the sub-object, formatted the way you want them to appear in the generated document.
3. Complete the filter with a merge field named simply filter@.

For example:

The following parties are participants in this matter:
<<filter@Participants>><<@contact.firstName>> <<@contact.name>>,
<<@defaultCategory.name>> <<@Detail[PRTP]/AgencyNumber>>
<<filter@>>

This would generate the following, if several related objects are retrieved:

The following parties are participants in this matter:
Reingold & Silverman, Outside Counsel Firm A-3433
John Silverman, Outside Counsel Attorney A-3434
Susan Yessler, Judge/Arbiter A-3420

For details about how to map these merge fields to TeamConnect data, see filter@ Merge Field Mapping.

if@ Merge Fields for Conditional Text

If you need the document generator template to include certain content only under a certain condition, use if@ merge fields.

The conditional content can include document content, such as text, and any other types of merge fields (basic, automatically mapped, loop@, and filter@ merge fields).

An if@ merge field can do any of the following:

• Check if a certain category has been added.
• Check if a system field has a value or not.
• Check if a custom field has a certain value.
• Check if a sub-object of a certain type has been added.

You define what the condition is that you need to check when you map the merge field to TeamConnect data.

Note: if@ corresponds to the Document Generator tag tc:conditional.

To set up if@ merge fields to identify conditional content

1. In the RTF, insert a merge field with a name that starts with if@ followed by the text of your choice.
2. Insert (or nest) basic merge fields for the content that you need to be generated only when the condition is met, formatted the way you want it to appear in the generated document.
3. Complete the filter with a merge field named simply if@.

For example:

<<if@LitigationCategoryAdded>> If the condition is true, you will see the content of a related file.
Content of another file:
<<ImportedFileContent>>
<<if@>>

If true (that is, if the Litigation category exists), then the output in the generated document would be as follows:

If the condition is true, you will see the content of a related file. Content of another file:
"This is a paragraph of information that is shared among several templates and is therefore managed as a separate file."

For details about how to map the if@ merge field to define the condition, see if@ Merge Field Mapping.

To open the Document Templates folder

1. In TeamConnect, click the Setup link. The Designer opens.
2. In the Go to drop-down list, select Object Definitions. The Object Definition list view opens.
3. Click the Document object definition.
   The Document tab view opens to the General page.
   
4. Click the Go to Document folder link.
5. The Document page opens and the Document Templates folder is listed.
   
6. To open the Document Templates folder, click the Document Templates link in the Name column.
   The Document Templates folder opens.
   

Once you open the Document Templates folder, you can view the contents or select one of the following icons to perform a task.