Creating merge fields that reference custom fields

You can create merge fields that will reference custom fields in batch emails and batch printing processes. For example, if a NexJ CRM user would like to send a batch email or print a document congratulating contacts or other users with a work anniversary, they can insert a merge field that references a Work Anniversary custom field into their email or document.

Creating a merge field that references a custom field requires two procedures:

1. Adding custom fields using NexJ Admin Console.

   

   You must create the custom field using NexJ Admin Console, not the Customize workspace. When you add a custom field in NexJ Admin Console, the Reference Name field is displayed, allowing you to note its auto-generated value which you will need to include in the expression when you create the merge field. The Reference Name field is not displayed if you add a custom field on the Customize workspace.

2. Adding merge fields that reference custom fields.

Adding custom fields using NexJ Admin Console

To add a custom field that will be referenced by a merge field to the system:

1. In NexJ Admin Console, navigate to the Entity Codes page.
2. In the Custom Field Types tab, select Custom Field Types.
3. Click the Add button

   

   and select a custom field type to define values that the field accepts:
   
   • Text
     Accepts text values.
   • Number
     Accepts numerical values.
   • Currency
     Accepts and formats numerical values using the currency defined when the field is created.

   • Convertible Currency
     Accepts and formats numerical values into the currency selected by users in NexJ CRM.

     

     You must also configure currency conversion for your system. For more information on configuring currency conversion, see Configuring functionality for NexJ applications.

   • Date
     Accepts and formats date values. Users can type a date value or select a date value from a calendar.
   • Relationship
     Accepts an entity as a value and defines it as a relationship in the contact's hierarchy.
4. In the Add Custom Field dialog, in the Details tab, fill in the following information:
   • In the Name field, enter a display name for the custom field.
   • [Optional] In the Description field, enter a description of the custom field.

   • In the Group field, select a custom field group to define the custom field tab in which the custom field is available on the Contacts workspace.

   • Note the auto-generated value in the Reference Name field.

     

     You need to include the auto-generated Reference Name in the expression when you create a merge field that references this custom field.

5. In the Entity Types tab, assign Entity Types to the custom field.

6. In the Security tab, you can change the view and edit security levels for this custom field to:

   • Public
     Allow all users to view and edit the custom field.

   • Group
     Allow only a group of users to view and edit the custom field.

   • Private
     Allow only you to view and edit the custom field.

   

   You cannot modify view and edit security levels for the custom field after it has been created. If you want to restrict view or edit access to this custom field, you must set it now. The default view and edit settings are Public.

7. Click OK.

The custom field is added to the system. Users can now add the custom field to a contact by following the instructions for Adding custom fields to contacts in the end user documentation.

To create a merge field that will reference this custom field follow the Adding merge fields that reference custom fields procedure below.

Adding merge fields that reference custom fields

To add a merge field that references a custom field to the system:

Ensure the Birthday Mailer system preference is enabled.

1. In NexJ Admin Console, navigate to the Document Codes page.
2. In the Merge Fields tab, click the Add button

   

   .

3. In the Add Merge Field dialog, complete the following fields as appropriate:

   • Token Name
     Specifies the placeholder name for the merge field. This should be a meaningful indication of what information is populated.

   • Description
     Provides a brief description of the merge field's intended content.

   • Category
     Specifies the subject area that the merge field is applicable to.

   • Expression
     Provides a calculated code value that defines the merge field and determines what data is populated from the database. 

     • Syntax:
       The syntax for an expression that references a custom field is ${customFields[<Reference_Name>] <attribute of custom field>}, in which <Reference_Name> is the auto-generated value in the Reference Name field, in the Add Custom Field dialog, when you add a custom field to the system.
       For Relationship custom fields, the expression syntax is ${customFields[<Reference_Name>] entityValue <attribute of entity class>}.

     • Examples of expressions for each custom field type:
       

       Custom field type	Attribute of custom field	Example of an expression
       Date	dateValue	${customFields[RETIREMENT_DATE] dateValue}
       Relationship	entityValue	${customFields[SPOUSE] entityValue fullNameFirstLast}
       Number	numValue	${customFields[RETIREMENT_AGE] numValue}
       Text	stringValue	${customFields[SON_NAME] stringValue}
       Currency	currValue	${customFields[ANNUAL_EARNING] currValue}
       Convertible Currency	convertedValue	${customFields[ASSET_VALUE] convertedValue}

       For more information on expression requirements, see Merge field expressions in the development documentation.

   • Custom Token
     Maps a third-party mailer template token to a NexJ CRM merge field for batch printing.

     

     The Custom Token field is only available if you have enabled the Birthday Mailer feature.

4. Click OK.

The merge field is added to the system and available for use. Users can now insert the merge field in the body of an email or add it to a Microsoft Word document.

For more information, see Sending batch emails to contacts, Batch printing birthday mailers, Adding merge fields to documents, and Batch printing for contacts in the end user documentation.

Related links

Setting up NexJ Add-In for Microsoft Office
Configuring merge fields
Enabling application features