Merge Field Options

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

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

OPTION

NAME

DESCRIPTION

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.

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

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)

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. 

Example: 

[[E_Mail|pt=Matter__data|df=DataCollection_DataField]]

This 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:

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).

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]]

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.

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.

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).

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.

“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,

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.

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.

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".

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.  

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.

see display_width

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

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.

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.

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

See bold

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).

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]]

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

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.

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).

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.