Custom Merge Fields for Letters

Publications may find it useful to configure merge fields that pull in customized text, such as standard signatures, seasonal announcements, legal disclaimers, terms and conditions, or marketing messages. These custom merge fields may be inserted into letter templates for all letter families, added to customized letters, and used in all email contexts to all users. The fields may also be edited by system administrators at any time; only letters sent after the edits are submitted reflect the changes.

Adding custom merge fields to letters

Custom merge fields may be added manually to individual letters on any Customize Letter page or to letter templates (on the Edit Letters page in PolicyManager).

For Rich Text (HTML) letters, a button labelled {%} appears on the tool bar. For plain text letters, an Insert Custom Merge Field link appears above the letter text box. Both open a pop-up window that displays a list of the available custom merge fields.

Behavior of custom merge fields

Custom merge fields may be edited at any time by system administrators, but only letters sent after edits are submitted will reflect the changes.

Custom merge fields do not populate in the letter body box on the Customize Letter interface. Information pulled in by the custom fields may not be edited in the letter.

If a letter is resent, the contents of any custom merge fields populated in the original letter, and saved to the history, are reinserted into the letter. If the custom merge field is edited after the original letter was sent, the new content is not merged into the resent letter. The letter is resent with its original contents.

Custom merge fields may be defined to display images, such as logos, in letters. In rich text (HTML) letters, these images appear in the letter body when the custom merge field is populated. In plain text letters, these images appear as a link when the custom merge field is populated. The recipient must click the link to view the image.

Including system merge fields in custom merge field text

System merge fields may be included in the content defined for a custom merge field. When the custom merge field is populated in a letter, it will include all the defined custom text and the information populated by each individual system merge field that it contains. System merge fields will populate based on their defined conditions.

Examples:

%JOURNALFULLTITLE% will insert the publication’s full title into any letter.
%ARTICLE_TITLE% will insert the manuscript title into letters related to a submission.
System merge fields that do not populate in letters sent to cc’d and bcc’d recipients will not populate when nested in a custom merge field for those copied recipients.
System merge fields that populate only in letters in the Ad Hoc from Editor letter family will not populate when nested in a custom merge field used for a letter in a different family.

Including Additional Manuscript Detail merge fields in custom merge field text

Like system merge fields, publication-defined AMD merge fields may be included in the content defined for a custom merge field. AMD merge fields will populate only in email letters associated with a submission.

For details on AMD merge fields, see Additional Manuscript Detail Merge Fields for Letters.

To configure:

Go to PolicyManager > Email and Letter Policies > Define Custom Merge Fields, and click the Add New Field button.

The Define Custom Merge Fields page displays a list of all custom fields defined for the publication. The order of fields on this page is the same order in which they are displayed in the pop-up window shown when users click the Insert Custom Merge Field button or link.

To change the position of a field in the list, click the grip tool next to the field name, then drag and drop it up or down in the list. To arrange the whole list alphabetically, click the Sort in Alphabetical Order button.

To create a new custom merge field:

Click the Add New Field button.
Enter a name for the custom merge field in the Name text box. All letters appear in uppercase, and the system appends a prefix (%CUSTOM_) and suffix character (%) when it generates the merge field.
- Use only letters and numerals
- To indicate a space in the name, enter the underscore character: _
- The system ignores all other characters and spaces
Enter (type or copy and paste) the content to associate with the merge field into the Content text box.
Optional: Special characters may be included. To insert a special character:
1. Position the cursor in the Content box in the place to insert the special character.
2. Click the Insert Special Character link to open a palette of available characters.
3. Click the chosen character on the palette.
4. Click the Close button to close the palette.
Optional: An image may be included. Images must be uploaded to the system before they can be inserted in a custom merge field. For details, see Image Files for Use in Letters and Custom Merge Fields.
1. Position the cursor in the Content box.
2. Click the Insert Image link to open the Insert Image pop-up window.
3. In the pop-up window, use the drop-down menu to select an image.
4. Click the Insert Image button. The pop-up window closes and the image URL appears in the content box.
Optional: One or more system merge fields may be included. To insert a system merge field:
1. Position the cursor in the Content box.
2. Click the System link to open the Insert System Merge Fields pop-up window.
3. In the pop-up window, scroll or search to find the desired merge field.
4. Click the merge field name/link. The merge field appears in the content box.
Optional: One or more AMD merge fields may be included. To insert an AMD merge field:
1. Position the cursor in the Content box.
2. Click the Additional Manuscript Details link to open the Insert Additional Manuscript Details Merge Fields pop-up window.
3. In the pop-up window, scroll or search to find the desired merge field.
4. Click the merge field name/link. The merge field appears in the content box.
Click the Preview in HTML Format link to see how the content will display when merged into an email. (System merge fields and AMD merge fields will not populate in preview.)
When finished, click Submit.

Links on the Define Custom Merge Fields page allow a system administrator to edit and manage custom merge fields. Each custom merge field is followed by these action links:

View Content opens a preview window, showing how the merged custom content will appear when populated in letters.
Edit Definition opens the Edit Custom Merge Field page. Existing content may be changed. (This is the same page that displayed when the field was added and saved.)
Edit Letter Templates opens a pop-up window that lists all the email templates in which the custom merge field is used. A link for each template goes directly to the template's Edit Letters page.
Copy opens an Edit Custom Merge Field page. The Content box is pre-populated with the content copied from the existing merge field. The name text box is blank. Enter a name for the new field and edit as needed.
Remove deletes the custom merge field. Click the link to open the Remove Custom Merge Field pop-up window.
- For a merge field that has not been used in any letter templates: Click the Continue button in the pop-up window to complete the removal.
- For a merge field currently in use: The pop-up window lists all the email templates in which the custom merge field is used. For each template, do steps 1 - 3.
  1. Click the link to go to the Edit Letter page.
  2. Remove the custom merge field from the letter body.
  3. Click the Save button on the Edit Letter page to save changes and close the page.
  4. When the field has been removed from all templates, click the Continue button on the Remove Custom Merge Field pop-up window to complete the removal.

For additional information, see the video on using merge fields.

For related information, see:

Create Letters

Merge Fields for Letters