Understanding Merge Field Options

In this article:

Introduction

A merge field option is a specified instruction for a merge field. Options can be used to access the correct data in your Actionstep system. It can also be used to apply additional logic to the merge field or format the text that gets merged in the completed document.

Some merge fields will have no options, while others will have many, depending on the field. 

Options (highlighted in red in the example below) are added to a merge field after the field name and a pipe character. Each new option requires its own pipe separator. For example: 

      FullName|pt=Client|ifnull=ignore

In this example, the pt option can be set to any valid participant type on the matter for which the template will be generated. In the example above, FullName pulls the first, middle, and last name of a client participant (which is denoted by pt=Client).

The ifnull option specifies what to do when no data is returned. In the example above, there may not be a client associated with the matter. If this happens, you may not want the document to show that the data is missing. You can instruct Actionstep what to do. In this scenario, Actionstep will ignore the field and display nothing.

To learn more about the different parts of a merge field, see Merge Fields Overview.

Participant Type Merge Field Options

Option: pt

Indicates which participant type should be examined to calculate the value of the merge field.

Example: [[FullName|pt=Client]] will merge the full name of the client associated with the matter.

• [[FirstName|pt=CLIENT]] will be merged as JOHN
• [[FirstName|pt=Client]] will be merged as John
• [[FirstName|pt=client]] will be merged as john

• pt=Div_ _action: The division this matter is linked to
• pt=Div_ _user: The division the current user is logged in to
• pt=Div_ _root: The root division
• pt=Current_ _user: Details of the user currently logged in
• pt=Action_ _assigned_to: Who the action is currently assigned to
• pt=Sp_ _theirname: The other party in an invoice/quote/order
• pt=Trust_ _client: The client participants associated with trust funds
• pt=Spi_ _TaskParticipant: For invoice headings and line items related to time-billing.  This will show contact fields associated with the person who completed the task.
• pt=Selected_ _Participant: When generating documents for a selected party in the action by right-clicking on the party on the Parties page. See Participant Type Custom Data Fields
• pt=Check_ _Payee: The payee on printed check templates
• pt=Cheque_ _Payee: Same as Check_ _Payee, above
• pt=BillFees__Timekeeper: Retrieves details for the person who recorded the time entry in the bill_fees data source. This is usually used within a repeat block with the rn=* option.
• pt=matter__data: This merge filed option can be used to pull details from a contact record when the contact is selected in a 'linked contact' custom matter data type field. FIelds of this type can be used as normal merge fields, ie, [[DataCollection_DataField]] which will return the display name of the contact loaded but you can use ordinary participant merge fields to collect other details about a the contact in the field. 
• pt=Matter__Data: Should be used with df= as well to nominate which custom matter data field you want to source. For example: [[E_Mail|pt=Matter__data|df=DataCollection_DataField]] will pull the email address of whichever contact is loaded against the custom data field DataCollection_DataField.

For more information on pt options, see the video below:

Date/Phone/Gender/Salutation Format Options

Option: fm

Date Options

Actionstep follows locale-based date formatting directives to format dates. 

Common date format fields:

• %a  will merge the day of week as Mon, Tue, etc.
• %A  will merge the day of week as Monday, Tuesday, etc.
• %b  will merge the month as Jan, Feb, etc.
• %B  will merge the month as January, February, etc.
• %d  will merge the day of the month as 2 digits: 01 through 31 (with a leading zero)
• %e  will merge the day of the month as 2 digits:  1 through 31 (with a leading space)
• %-e  will merge the day of the month as 1 or 2 digits: 1 through 31 (no leading space or zero)
• %nth  will merge the day of the month as and ordinal: 1st, 2nd, 3rd, 4th, etc.
• %H  will merge the hour in 24-hour format
• %l  (using a lower case "L") will merge the hour in 12-hour format without leading zero: 1 through to 12
• %I  (using an upper case "i") will merge the hour in 12-hour format with two digits: 01 through to 12
• %m  will merge the numeric month with a leading zero: 01, 02, 03, etc.
• %-m  will merge the numeric month with the leading zero removed: 1, 2, 3, etc.
• %M  will merge the minutes
• %p  will merge am or pm
• %S  will merge the seconds
• %y  will merge the 2-digit year: 25 for 2025
• %Y  will merge the 4-digit year: 2025
• %Z  will merge the time zone

Phone Options

Use the Format option to override the default formatting for phone numbers:

• |fm=a  will merge +64 21 555 1212
• |fm=b  will merge +64 (21) 555 1212 (default)
• |fm=c  will merge (021) 555 1212
• |fm=d  will merge 021 555 1212
• |fm=e  will merge (21) 555 1212 (no leading zero inserted)
• |fm=f  will merge 21 555 1212 (no leading zero inserted)

Example: 

[[Phone Business|pt=Client|fm=b]] 

This merge field will be inserted as +64 (21) 555 1212 in the document. If no option is specified, Actionstep displays the merged data in a default format (fm=b).  

Gender Format Options

You can use a merge field to insert gender.  If you insert a Gender option without using fm= will be displayed either M or F for Male or Female. Use the fm=full to display the full word.

Examples:

|fm=full will merge male or female

|fm=Full will merge Male or Female

|fm=FULL will merge MALE or FEMALE

Salutation Options

You can use [[Salutation|pt=Client]] to use what is stored in their contact record.

You could also use [[m_f|c1=Sir|c2=Madam|pt=Client]] to use specific salutations based on gender. In this example, the text Sir or Madam is inserted based on the gender.

Currency Option

Option: fm=text

This option converts a currency value to a text string (e.g., say you want to display $53.47 as “Fifty Three Dollars and Forty Seven Cents").

How you capitalize the option determines how the generated text will be capitalized: 

• fm=TEXT will merge text using all caps
• fm=text will merge text using lowercase
• fm=Text will merge text using mixed Caps

The currency will be detected from either the associated sale/purchase record or the base currency defined in accounting for the database.

Record Number Option

Option: rn

This option is used to identify a specific record or participant number if there could be more than one.

For example, there may be several “Trustee” participant types linked to a particular action.  If you wanted to create a signature block for each trustee then you could specify each one using rn=1, rn=2, etc.

Record numbers are most commonly used in REPEAT blocks (see Using Merge Field Repeat Blocks).

Boolean True/False Options

Option: true / false

The text that should be inserted if the data type of the linked custom data field is Boolean and the live data value of this field is true or false.   

Checkboxes will be “true” when selected or “false” when cleared.

For example, if you have a Boolean field (or checkbox) called "has_insurance", you might specify the option as

true="the_client_has_insurance_cover" which will merge the text “the client has insurance cover”. (Note the use of underscores to specify spaces.) If you do not specify a value for this option, Actionstep substitutes the text "true" for this merge field.

If you would like one of the options to return a blank result (for example, leave blank if "false"), set the option to equal nothing and insert ifnull=ignore to the merge filed. For example:

[[boolean_field_name|true=My_true_text|false=|ifnull=ignore]]

In this example, if the result is true, the output will read "My True text". If the result is false, the result will be blank.

Choice Options

Option: c1 / c2

These options are similar to Boolean choices except these apply to general merge fields that have two choices.  Examples of these merge fields include i_c (individual or company) and s_p (singular or plural).

c1 = First choice in merge fields that conditionally substitute text

c2 = Second choice in merge fields that conditionally substitute text

Example:  

More specifically, the full merge field will be processed as: "Find the 3rd (rn=3) shareholder (pt-Shareholder) associated with the action and substitute text Resides at if it's an individual or Has its offices at if it's a company.

Person Pronoun Option

Option: pn

Use this option to merge first, second, and third-person pronouns.

Examples:

|pn=1st

|pn=2nd

|pn=3rd

Only these values are allowed:

• 1st merges pronouns such as "I," "me," "we," and "us"
• 2nd merges pronouns such as "you"
• 3rd merges pronouns such as "he," "she," "it," "they," "him," "her," "his," and "them"

Actionstep will substitute pronouns (he, she, her, theirs, etc.) depending on the gender and number of participants referenced in the live data.  This field specifies whether to create the pronoun in the first, second, or third person format.

This option is valid for the following merge fields:

• pronoun1
• pronoun2
• pronoun3
• pronoun4

Example: 

[[Pronoun1|pn=1st|pt=Client_Primary_Contact]]

Refer to the pronoun substitution table in Using Merge Fields to Insert Pronouns for technical details on how the substitutions will be performed.

Sort Order Option

Option: sort

Sort directive for multi-row data collection in a repeat block. See Using Merge Field Repeat Blocks for more information.)

Missing Data Override (ifnull) Option

Option: ifnull

If this option is not specified, then Actionstep will insert the missing merge field text (****). However, sometimes you just want to leave a field blank if there is no data. For example,  if Address_line_2 is empty, then don't insert anything.

Examples:

• ifnull=ignore — This will leave the field blank
• ifnull=any_other_text – This will fill the space with the text you specify. Remember to use an underscore (_) for spaces (e.g., Any_other_text will be merge as "Any other text".

Image Width / Height Options

Option: width/height

This option can be used with fields like DivisionLogo, which inserts an image. This formatting option can specify either the width or height of the image in pixels.  The default behavior is to display the image in its natural dimensions.

Unlike the display_width option (see below), this will resize the image completely.  

Display Image Width / Height Option

Option: display_width/display_height

For fields like DivisionLogo (which inserts an image), this formatting option can specify either the width or height to display the image in pixels. The default behavior is to display the image in its natural dimensions.

This will not resize the image that is displayed, just the dimensions that it takes on the document.

As an example, if you upload a 10MB image which is 10,000×10,000 pixels and you want it to be 400×400 in high res, you may want to use:

width=1200|display_width=400

This will resize the actual image file to 1200×1200 but display it on the document in 400×400, meaning that it will be 3x the DPI compared to regular width=400.

Image Zoom Option

Option: zoom

Use this option to zoom and then scale an image. 

Example:

|zoom=T

If true, the image will be zoomed rather then scaled. For example, a 100×100 image with a width=50|height=100 will zoom the image to 100 height and clip the left/right 25px. If falls (zoom=F), the image would use white bars on the sides that do not match the aspect ratio.

Repeat Table Row Option

Option: tablerow

This option is used to specify the beginning and end of a row of cells in a table.

If used in a repeat block, the repeat block will include the whole row (see Using Merge Field Repeat Blocks).  This is helpful because quite often in Word you cannot see where exactly your merge field is being placed relative to the hidden mark-up language fields which specify the start and end of the row.  If you use tablerow, then Actionstep will automatically scan for the start and end tags in the mark-up language and take care of this for you.

Decimal Places Option

Option: dp

For data fields marked as decimal or currency as well as accounting fields, this option sets the number of decimal places to be displayed.  Note that the "money" data type is not affected since it inherits this setting.

Bold / Italic Text Style Option

Option: bold/italic

This option applies bold or italic text for sale/purchase-related merge fields. (It is currently only available for these types of fields.) 

Example: 

|heading=bold

|item=italic 

|child=bold,italic

This way you can apply bold or italic formatting to a heading or its child. 

This option works in docx, html or rtf. It does require code logic so it's currently only used in sale/purchase line-item code. 

Multiple styles can be used if they're separated using commas:

|heading=bold,italic|item=bold|child=italic 

Optional Text Before or After a Number or Text Field (Prefix, Suffix)

Option: prefix/suffix

Use this option if you want to add plural or singular text before/after a number field. 

Example:

You have [[DaysToRespond|suffix=_day,_days]] to respond

This example would merge the following text: You have 5 days to respond.

Notes:

• The underscore in the example inserts a space character. 
• For number fields, the comma separates the singular and plural versions of the prefix/suffix. (Plural is optional.)

Remove Space Characters

Option: strip_spaces

Use this option to remove spaces between merge fields. For example, you can remove the spaces between the initials C L S so that it appears as CLS. 

Example:

 [[InitialsAll|pt=Attorney|strip_spaces=T]]

Values: 

T: Remove spaces

F: Do not remove spaces (default)

Summary Operations on Multi-Row Numeric Data Option

Option: calc

Use this option to calculate the sum of multi-row data-collection fields. (It will also work on single-row, but all methods will return the same number.)

You can add calc=sum,avg,max,min on any multi-row number/currency field.

Example:

[[test_field|calc=sum]] 

This example will return the sum of all the data in that field.

sum will add all the numbers together

avg will sum then divide by the count

max will return highest number

min will return lowest number

NOTE: This will only work if there is no record number (|rn) option used. 

Case Option

Option: case

Use this option to change the capitalization used for the merge field. 

Example:  

• |case=upper – Applies uppercase to all letters: THE QUICK BROWN FOX 
• |case=lower – Applies lowercase to all letters: the quick brown fox
• |case=ucfirst – Applies uppercase to the first letter of the phrase, applies no changes to the rest: The QUICK brown fox
• |case=ucwords – Applies uppercase to the first letter of every word, applies no changes to the rest: The QUICK Brown Fox
• |case=uclowerwords – Applies uppercase to the first letter of every word, applies lowercase the rest: The Quick Brown Fox 
• |case=uclowerfirst – Applies uppercase to the first letter, applies lowercase to the rest: The quick brown fox 

This option cannot be used to change the case of letters within a word. For example, mcdonald can’t be formatted as McDonald.

This option is processed after the existing formatting of |pt=CLIENT,  pt=Client, pt=client, but unlike pt=, it will be processed for the result of any field.

New Line/Carriage Return Option

Option: newline

This option adds a new line (or carriage return) before or after a merge field if the merge field is not blank. This is commonly used in address blocks where you want something like the following:

Name

Address Line 1

Address Line 2

City, State, ZIP

However, if there is no Address Line 2, you want to remove that line from the address rather than have a blank line be inserted. 

To do this, use the newline option:

[[FullName|pt=Client]]

[[AddressLine1]][[AddressLine2|newline=before]]

etc.

This will insert a carriage return / new line only if Address Line contains a value. 

Option can be any of the following (where the 2* options are for two line breaks):

• before
• after
• 2before
• 2after
• both
• 2both

Remove Currency Symbol Option

Option: show_currency_symbol=F

This option removes the currency symbol ($) from the front of a numerical monetary amount. Use this when you want to show the amount without the currency symbol preceding the number, for example when using pre-printed checks where the dollar symbol is already printed.

Related Articles:

• Merge Fields Overview
• Using Merge Field Repeat Blocks