Merge Field Options

Created by Allison Cloyd, Modified on Mon, 23 Jan 2023 at 03:07 PM by Dakota Martin

Information:

Options are used to add additional attributes to merge fields such as specifying which data element to select, text substitution, and to control the presentation format.

 

Note: The following characters are not supported for use in merge fields or merge field options.

  • < (less than)
  • > (greater than)
  • " (quotation)
  • & (ampersand)

 

Option List

OPTION

NAME

DESCRIPTION

ptParticipant Type

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

 

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

IMPORTANT: The merge field will generate as uppercase, lowercase, or mixed case depending on the case of the Participant Type option.

Example: [[FirstName|pt=CLIENT]] will generate as JOHN, [[FirstName|pt=Client]] will generate as John, and [[FirstName|pt=client]] will generate as john.

NOTE: You can use the following special value for the pt option to specify participants other than action participants (note the double underscore characters):

pt=Div_ _action (the division this action is linked to)

pt=Div_ _user (the division 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)

 

For more information you can see the video below:

fmDate and Phone FormatWithout this option Actionstep will display the merged data in a default format (fm=b).  Use the Format option to override the default formatting.

Phone Number Formats

a: +64 21 555 1212

b: +64 (21) 555 1212 (default)

c: (021) 555 1212

d: 021 555 1212

e: (21) 555 1212 (no leading zero inserted)

f: 21 555 1212 (no leading zero inserted)

 

 

Example: [[Phone Business|pt=Client|fm=b]] will show +64 (21) 555 1212 in the document.

Date Formats

The PHP date formatting directives are used to format dates (as documented in the “strftime()” function in PHP).

 

Example:

[[SignatureDate|fm=Signed_this_%nth_day_of_%B_%Y|]]

will display as

Signed this 16th day of February 2012

if SignatureDate is 16-Feb-12.

 

Common date format fields:

 %a       Day of week "Mon", "Tue", etc.

 %A      Day of week "Monday", Tuesday" etc.

 %b       Month "Jan", "Feb", etc.

 %B       Month "January", "February", etc.

 %d       Day of month - 2 digits "01" through "31" (leading zero)

 %e       Day of month – 2 digits " 1" through "31" (leading space)

 %-e      Day of month – 1-2 digits "1" through "31" (no leading space)

 %nth   Day of Month as "1st", "2nd", "3rd", "4th" etc.

 %H      Hour in 24-hour format

 %l        (using a lower case "L") Hour in 12-hour format without leading zero. "1" through to "12"

%I (using an upper case "i") Hour in 12-hour format with two digits. "01" through to "12"

%m      Month (numeric) – 01, 02, 03, etc

%-m Month (numeric) - removed the leading zero - 1, 2, 3, etc

 %M      Minutes

 %p       "am" or "pm"

 %S       Seconds

 %y       2-digit year "05" for 2005

 %Y      4-digit year "2005"

 %Z      Timezone

 

To change the language for the month you can set the “locale” option (default = en_NZ.utf8).  For example if you wanted the date to show in Mexican Spanish use [[System_Date|locale=es_MX.utf8]]

Note:

If you have a date, time and memo option and want the memo to show you will have to use "fm=description" in the merge field. the fm=description cannot be used in conjunction with other fm= options. You would have to create a separate merge field for it. For example, [[Example_Date|fm=%d/%m/%Y]] [[Example_Date|fm=description]]

Note:

Merge fields for calendar appointments will, by default, only display the date of that appointment. To pull in the time of the appointment you must modify the merge field with both date and time options. For example: [[Sample_Calendar_appointment|fm=%nth_of_%B_%Y_at_%l_%p]]

 

Gender Formats

Gender without using "fm=" will display either "M" or "F" for Male or Female. Use the fm=full to display the full name.


fm=full       "male" or "female"

fm=Full      "Male" or "Female"

fm=FULL   "MALE" or "FEMALE"

 

Salutation

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, in this case displaying Sir or Madam based on the gender.

fm=textDisplay currency as textWill convert currency to a text string.

For example: 53.47 will display as “Fifty Three Dollars and Forty Seven Cents”.

As per other doc-merge syntax, fm=TEXT will return in all caps, fm=text will return in lower-case and fm=Text will be in Mixed Caps.

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

rnRecord NumberUsed 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 below).

trueBoolean TRUEThe 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”.   

Checkboxes will be “true” when checked or “false” when not checked.

 

For example if you have a custom data Boolean field (checkbox) called “has_insurance” then you might specify the option as

true=”the_client_has_insurance_cover”

which will generate as “the client has insurance cover” in place of this merge field when the document is generated.

(note the use of underscores to specify spaces)

 

If you do not specify a value for this option then Actionstep will substitute the text “true” for this merge field.

 

If you woudl like one of the options to return a blank result (for example, leave blank if "false") then you will have to have that option equaling 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 reulst is true the output will read "My True text"

If the result is false the result will be blank.

falseBoolean FALSEOpposite of Boolean TRUE.  See above.
c1Choice OneSimilar to Boolean choices except this applies 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.

 

Example: The merge_field "i_c" substitutes text depending on whether the participant is an individual (i) or a company (c). So,

 

[[i_c|c1=Resides_at|c2=Has_its_offices_at|pt=Shareholder|rn=3|]]

will be read by the application 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 is a company.

c2Choice TwoSecond choice (see above)
pnPronoun PersonFirst, Second, Third person for Pronouns (pn=1st, pn=2nd, pn=3rd) - only these values are allowed.

 

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 merge fields

  • pronoun1
  • pronoun2
  • pronoun3
  • pronoun4

 

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

 

Refer to the pronoun substitution table in the Pronouns for merge fields article for technical details on how the substitutions will be performed.

sortSort OrderSort directive for multi-row data collection in a repeat block (see below).
ifnullMissing Data OverrideIf this is not specified then Actionstep will insert the Missing Merge Field Text, ****. However sometimes you just want to leave it blank if there is no data e.g. if address_line_2 is empty then just don't insert anything.

ifnull=ignore  (this will leave it blank)

ifnull=Any_other_text (will print this text instead). Remember to use '_' for spaces.  So "Any_other_text" will merge as "Any other text".

widthImage width

For fields like DivisionLogo which inserts an image this formatting option can specifiy either the width or height of the image in pixels.  The default behaviour is to display the image in it's natural dimensions.

Unlink the display_width option (See below) this will resize the image completely.  

heightImage heightSee width
display_width Image width

For fields like DivisionLogo which inserts an image this formatting option can specifiy either the width or height to display the image in pixels.  The default behaviour is to display the image in it's 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 x 10,000 pixels and you want it to be 400 x 400 in high res, you may want to use:

width=1200|display_width=400

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

display_height image height

see display_width

zoomImage zoom

zoom=T, if true the image will be zoomed rather then scaled, ie 100x100 image with width=50|height=100 will zoom the image to 100 height and clip the left/right 25px, zoom=F would use white bars on the sides that do not match the aspect ratio

tablerowRepeat Table Row

Used to specify the beginning and end of a row of cells in a table.

 

If used in a repeat block then the repeat block will include the whole row (see examples below under 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.

dpDecimal Places

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

boldBold text style

Currently only available for sale/purchase merge fields.

heading=bold,italic or item=bold,italic or child=bold,italic. This way you can bold a heading, ie: heading=bold or italics a child item: child=italic. Works in docx, html or rtf. Requires code logic so currently only in sale/purchase line-item code. Multiple styles can be used with commas: ie heading=bold,italic|item=bold|child=italic

italicItalic text style

See bold

prefix, suffixOptional text before (prefix), or after (suffix), a number or text field

If you want to add text before/after a number field e.g. “You have 5 days to respond” you could code this as

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

Notes:

  • the underscore will insert spaces and
  • for number fields the comma separates the singular and plural versions of the prefix/suffix (plural is optional).
strip_spacesRemove space characters

Useful for merge fields like InitialsAll which will change “A B K” to “ABK”.

Values: “T” – strip spaces, “F” – do not strip spaces (default)

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

calcSummary operations on multi-row numeric data

Use with multi-row data-collection fields (it will also work on single-row, but all methods will return the same number)

 

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

 

For example: [[test_field|calc=sum]] 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 when there is no |rn= flag

caseSet UPPERCASE or lowercase

Example: “the QUICK brown fox”

 

|case=upper == “THE QUICK BROWN FOX” – upper case all letters

|case=lower == “the quick brown fox” – lower case all letters

|case=ucfirst = “The QUICK brown fox” – upper case the first letter of the phrase, no-change the rest

|case=ucwords = “The QUICK Brown Fox” – upper case the first letter of every word, no-change the rest

|case=uclowerwords = “The Quick Brown Fox” – upper case the first letter of every word, lower-case the rest

|case=uclowerfirst = “The quick brown fox” – upper case the first letter, lower-case the rest

 

 

None of these options are “Mc” friendly etc… ie “mcdonald”  can’t be converted to “McDonald”

 

This feature runs AFTER the existing formatting of |pt=CLIENT or pt=Client or pt=client formatting, but unlike pt= it will run on the result of *any* field.

 newlineAdd a new line (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

Name
Address Line 1
Address Line 2
City, State, Zip

But if there is no Address Line 2 for the contact then you will end up with a blank line in the output.

The solution is to use the newline option:

[[Fullname|pt=Client]]
[[Addressline1]][[Addressline2|newline=before]]
Etc.. 

This will insert a newline before AddressLine2 only if it contains a value.

The syntax is quite simple: [[Field|newline={option}]]
Where {option} can be one of: before, after, 2before, 2after, both, 2both  (where the 2* options are for two line breaks).
show_currency_symbol=FRemoves the currency symbol ($) from the front of a numerical monetary amount

This can be used for people who would like the amount to show a monetary without the currency symbol preceding the number. For example, for use on a check template when the template already has the dollar symbol pre-printed.


Related Articles: