Understanding and Using Practifi Merge Language (PML)

Overview

Practifi's Rulebook and Rule-Based Actions enable your firm to automate communications and workflows based on conditions in your data. For those communications to be genuinely useful, they need to reference the specific people, accounts, and details that triggered them, rather than relying on generic, static text. That's what Practifi Merge Language (PML) makes possible.

PML allows you to create merge fields that dynamically pull data from records in your Practifi instance, so that the alerts, notifications, and messages your firm sends are contextually relevant every time they're delivered. Whether you're notifying an advisor that a client's risk profile has changed or sending a portal user a link to their latest review, PML ensures the right information reaches the right person automatically.

This article covers how PML works, how to create formula fields that use it, and how to build both simple and advanced merge fields in your organization.

• Understanding Practifi Merge Language (PML)
• Creating a Formula Field
• Simple Merge Fields
• Advanced Merge Fields
  • Adding a Resource
  • Utilizing a Function
• PML Example

Understanding Practifi Merge Language (PML)

Merge fields are placeholders in a message or formula that get replaced with real data when the communication is sent. For example, rather than writing "Dear Client," you could use a merge field to insert the client's first name automatically. PML extends this concept across Practifi's alert channels, allowing you to reference fields, related records, user data, and more.

Understanding why PML exists requires some context on those alert channels. Merge field support varies significantly across them:

• Emails natively support merge fields using Salesforce’s Email Template Builder. However, their capabilities are limited, and different URLs are required for portal users vs. Practifi users.
• Notifications support merge fields through some automation methods, but they also have limitations, and those methods are incompatible with some Practifi features.
• Noticeboard posts have no built-in support for merge fields.

PML provides a consistent, capable solution that works across all of these channels. Its syntax is closely based on Salesforce's own formula field language, so if your team already works with formula fields in Salesforce, PML will feel familiar. With PML, two types of merge fields are available: simple and advanced.

• Simple merge fields can only be used to display field-level information stored in records, but have simpler formatting requirements.
• Advanced merge fields can be used to display various types of information captured in the system and format it in different ways. However, formatting these merge fields properly requires more knowledge.

---

Creating a Formula Field

PML is used when creating a formula field in your Practifi instance. Formula fields are a standard Salesforce feature that calculate and display a value based on other data in the record. When you use PML inside a formula field, the field's output can then be referenced in Rule Actions, Active Form Prompts, and other areas of Practifi to deliver dynamic content.

To create a formula field:

1. Navigate to Salesforce Setup by clicking the cog icon in the upper right-hand corner, then select Setup from the drop-down menu.

   
   

2. Click the Object Manager navigation menu tab. This will open a list of all available objects. 

3. Locate the object that you would like to create a formula field on and select its hyperlinked Label. 

   

4. Click the Fields & Relationships tab on the object's page. 

5. Click the New button to begin the field creation process. 

   

6. Select Formula from the field type options, then click Next to proceed. 

   

7. Enter the Field Label, then click into the Field Name field to auto-generate that information.

   Please note: Field names must be unique. If a field name has been used before, you will need to modify the auto-generated value. 

8. Select the appropriate Formula Return Type from the available options. This determines how the formula's calculated value is displayed within the field. Once selected, click Next to proceed.

   

9. Enter your formula into the field using PML. For simple merge fields, enter this information under the Simple Formula tab. For advanced merge fields, enter your formula under the Advanced Formula tab. Use the 'Check Syntax' button to ensure no syntax errors exist. Then click Next.
   
    

10. Set field visibility for the profiles you would like to be able to view the field, then click Next. 

    

11. You can select the page layouts on which you would like this field to appear, then click Save to finalize the field creation.

    

Please note: The field will still need to be added to your firm's page layout or Active Form layout for it to be visible within Practifi. 

---

Simple Merge Fields

Simple merge fields are the most straightforward way to insert dynamic data into your PML-powered content. Use a single percentage symbol (%) to indicate where the merge field begins and ends. The field reference inside the percentage symbols follows the same formatting as when specifying a field reference in a Salesforce formula field or when configuring Practifi features such as Active Forms and Rule Criteria.

Before writing a simple merge field, you need to identify the "starting object" — the object from which Practifi will begin traversing your data to find the field you're referencing. The starting object is always defined by the context in which you're using PML. For example, when using PML within a Rule Action, the starting object is defined in the Object field of the parent Rule Criteria record.

A simple merge field referencing the name of the related entity on a Task record would be written as: %practifi__Related_Entity__r.Name%

---

Advanced Merge Fields

Advanced merge fields give you access to a broader range of data sources and the ability to transform or format that data before it appears in your content. Use a double percentage symbol (%%) to indicate where the merge field begins and ends. Inside those delimiters, you will specify a resource and, optionally, a function.

This added flexibility makes advanced merge fields particularly well-suited for use cases such as generating direct links to records that work for both internal and portal users, or formatting date and text values in specific ways.

---

Adding a Resource

Resources in PML are references to data located elsewhere in Practifi, similar to how resources function in the Rule Builder. Because there is no visual selector available here, you refer to resource types using the codes listed below.

• Base URL: $Base_Url
  • Use this resource to return the URL that will direct an email recipient to the right environment. For example, if the email is sent to an internal user, the URL will direct them to your firm’s Practifi instance. If it’s sent to a portal user, the URL will direct them to their assigned portal.
  • Unlike other resource types, Base URL does not require additional resource selection. This is particularly useful for firms whose communications reach both advisors and their clients through the portal.
• Custom Permission: $PERMISSION
• Custom Setting: $SETUP
• Record Field: $Record
  • As with simple merge fields, the "starting object" for a Record Field resource is defined by the context in which PML is being used. For example, when using PML within a Rule Action, the starting object is defined in the Object field of the parent Rule Criteria record.
• Standard Permission: $PROFILE
• Standard Setting: $ORGANIZATION
• User Field: $USER
• User Role: $USERROLE

Once the resource type is specified, the resource itself must be identified. The syntax here behaves identically to field references in formula fields. For example:

• To create a formula field on the Task object that returns the name of the Related Entity, the field reference would be formatted as practifi__Related_Entity__r.Name.
• To reference the same field in a Rule Action using an advanced merge field, it would be formatted as %%$Record.practifi__Related_Entity__r.Name%%.

Utilizing a Function

Functions allow you to compute or transform data before it appears in your output. They work similarly to formulas in Excel: you call them by name, provide the required inputs, and receive a calculated result. This is useful any time you need to do more than display a raw field value. For example, formatting a date, manipulating a text string, or evaluating a conditional expression.

PML supports most, but not all, of the functions available in Salesforce formula fields. The supported functions are listed in the reference table below.

Name	Description	Usage	Example
ABS	Calculates the absolute value of a number. The absolute value of a number is the number without its positive or negative sign.	ABS(number)	ABS(-1)
ACOS	Returns the arc cosine of the number in radians if the given number is between -1 and 1. Otherwise returns NULL.	ACOS(number)	ACOS(0.5)
ADDMONTHS	Returns the date that is the indicated number of months before or after a specified date. If the specified date is the last day of the month, the resulting date is the last day of the resulting month. Otherwise, the result has the same date component as the specified date.	ADDMONTHS(date, num)	ADDMONTHS (StartDate, 5)
AND	Returns a TRUE response if all values are true; returns a FALSE response if one or more values are false.	AND(logical1, logical2, ...)	IF(AND(Price<1,Quantity<1),"Small", null)
ASCII	Returns the first character’s code point from the given string as a number.	ASCII(text)	ASCII("A")
ASIN	Returns the arc sine of the number in radians if the given number is between -1 and 1. Otherwise returns NULL.	ASIN(number)	ASIN(0.5)
ATAN	Returns the arc tangent of the number in radians.	ATAN(number)	ATAN(0.5)
ATAN2	Returns the arc tangent of the quotient of y and x in radians.	ATAN2(number1, number2)	ATAN2(0.5, 1)
BEGINS	Determines if text begins with specific characters and returns TRUE if it does. Returns FALSE if it does not.	BEGINS(text, compare_text)	IF(BEGINS (Product_type__c, "ICU"), "Medical", "Technical")
BLANKVALUE	Determines if an expression has a value and returns a substitute expression if it doesn’t. If the expression has a value, it returns the value of the expression.	BLANKVALUE(expression, substitute_expression)	BLANKVALUE(Department, “Undesignated”)
BR	Inserts a line break in a string of text.	BR()	ShippingStreet & BR() & ShippingCity
CASE	Checks a given expression against a series of values. If the expression is equal to a value, it returns the corresponding result. If it is not equal to any values, it returns the else_result.	CASE(expression, value1, result1, ..., else_result)	CASE(Field__c, "Partner", "P", Customer", "C", LEFT(Field__c, -5))
CASESAFEID	Converts a 15-character ID to a case-insensitive 18-character ID.	CASESAFEID(id)	CASESAFEID (Id)
CEILING	Rounds a number up to the nearest integer, away from zero if negative.	CEILING(number)	CEILING(2.5) returns 3; CEILING(-2.5) returns -3
CHR	Returns a string with the first character’s code point as the given number.	CHR(number)	CHR(85) returns "U"
CONTAINS	Compares two arguments of text and returns TRUE if the first argument contains the second argument. If not, returns FALSE.	CONTAINS(text, compare_text)	IF(CONTAINS(Product_Type__c, "part"), "Parts", "Service")
COS	Returns the cosine of the number in radians if the given number is between -1 and 1. Otherwise returns NULL.	COS(number)	COS(0.5)
DATE	Returns a date value from the year, month, and day values you enter. Salesforce displays an error on the detail page if the value of the DATE function in a formula field is an invalid date, such as February 29 in a non-leap year.	DATE(year, month, day)	DATE(2005, 01, 02)
DATERANGE	Returns a date range from a date literal	DATERANGE(literal, param1?, param2?)	DATERANGE("TODAY")
DATETIMEVALUE	Returns a year, month, day, and GMT value.	DATETIMEVALUE(expression)	DATETIMEVALUE("2005-11-15 17:00:00")
DATEVALUE	Returns a date value for a date/time or text expression.	DATEVALUE(expression)	DATEVALUE("2005-11-15")
DAY	Returns a day of the month in the form of a number from 1 through 31.	DAY(date)	DAY(Code_Freeze__c)
DAYOFYEAR	Returns the day of the calendar year (from 1 through 366).	DAYOFYEAR(date)	DAYOFYEAR(Code_Freeze__c)
EQUALS	Determines if any value selected in a multi-select picklist field equals the text literals you specify.	EQUALS(multiselect_picklist_field, text_literal)	EQUALS(multiselect_picklist_field, text_literal)
EXP	Returns a value for e raised to the power of a number you specify.	EXP(number)	EXP(3)
FIND	Returns the position of a string within a string of text represented as a number.	FIND(search_text, text, start_num?)	SUBSTITUTE(Email, LEFT(Email, FIND("@", Email)), "www.")
FLOOR	Returns a number rounded down to the nearest integer, towards zero if negative.	FLOOR(number)	FLOOR(2.5) returns 2; FLOOR(-2.5) returns -2
FORMATDURATION	Formats the number of seconds with optional days, or the difference between times or dateTimes as HH:MI:SS.	FORMATDURATION(duration)	FORMATDURATION(Code_Freeze__c - NOW())
GETSESSIONID	Returns the user’s session ID.	GETSESSIONID()	HYPERLINK ("https://www.myintegration.com?sId="& GETSESSIONID() & "?&rowID="&Name & "action=CreateTask","Create a Meeting Request")
HOUR	Returns the local time hour value without the date in the form of a number from 1 through 24.	HOUR(value)	HOUR(TIMEVALUE(ClosedDate))
HTMLENCODE	Encodes text and merges field values for use in HTML by replacing HTML-reserved characters, such as the greater-than sign (>), with their HTML entity equivalents, such as &gt;.	HTMLENCODE(text)	HTMLENCODE(text)
HYPERLINK	Creates a link to a URL specified that is linkable from the text specified.	HYPERLINK(url, friendly_name, target?)	HYPERLINK("/00U/e?retURL=%2F006x0000001T8Om&what_id=" & Id, "Create Event")
IF	Determines if expressions are true or false. Returns a given value if true and another value if false.	IF(logical_test, value_if_true, value_if_false)	IF(ISPICKVAL($Profile.UserType ,"Standard"), 100, 0.1)
IMAGE	Inserts an image with alternate text and height and width specifications.	IMAGE(image_url, alternate_text, height?, width?)	HYPERLINK("ymsgr:sendIM?" & Yahoo_Name__c, IMAGE("http://opi.yahoo.com/online?u=" & Yahoo_Name__c & "&m;=g&t;=0", "Yahoo"))
INCLUDES	Determines if any value selected in a multi-select picklist field equals a text literal you specify.	INCLUDES(multiselect_picklist_field, text_literal)	INCLUDES(multiselect_picklist_field, text_literal)
INITCAP	Returns the text as lowercase with the first character of each word in uppercase.	INITCAP(text)	INITCAP("hello world")
ISBLANK	Determines if an expression has a value and returns TRUE if it doesn’t. If it contains a value, this function returns FALSE.	ISBLANK(expression)	ISBLANK(Amount)
ISNULL	Determines if an expression is null (blank) and returns TRUE if it is. If it contains a value, this function returns FALSE.	ISNULL(expression)	OR(ISNULL(field__c), field__c<>1)
ISNUMBER	Determines if a text value is a number and returns TRUE if it is. Otherwise, it returns FALSE.	ISNUMBER(text)	OR(LEN(Bank_Account_Number__c) <> 10, NOT(ISNUMBER(Bank_Account_Number__c)))
ISOWEEK	Returns the ISO 8601-week number (from 1 through 53) for the given date, ensuring that the first week starts on a Monday.	ISOWEEK(date)	ISOWEEK(Code_Freeze__c)
ISOYEAR	Returns the ISO 8601 week-numbering year (in 4 digits) for the given date, ensuring that the first day is a Monday.	ISOYEAR(date)	ISOYEAR(Code_Freeze__c)
ISPICKVAL	Determines if the value of a picklist field is equal to a text literal you specify.	ISPICKVAL(picklist_field, text_literal)	IF(ISPICKVAL(StageName, "Closed Won"), ROUND(Amount *0.02, 2), 0)
JSENCODE	Encodes text and merges field values for use in JavaScript by inserting escape characters, such as a backslash (\), before unsafe JavaScript characters, such as the apostrophe (\').	JSENCODE(text)	JSENCODE(text)
JSINHTMLENCODE	Encodes text and merges field values for use in JavaScript inside HTML tags by replacing characters that are reserved in HTML with HTML entity equivalents and inserting escape characters before unsafe JavaScript characters. JSINHTMLENCODE(someValue) is a convenience function that is equivalent to JSENCODE(HTMLENCODE((someValue)). That is, JSINHTMLENCODE first encodes someValue with HTMLENCODE, and then encodes the result with JSENCODE.	JSINHTMLENCODE(text)	JSINHTMLENCODE(text)
LEFT	Returns the specified number of characters from the beginning of a text string.	LEFT(text, num_chars)	TRIM(LEFT(LastName, 5)) & "-" & TRIM(RIGHT(SSN__c, 4))
LEN	Returns the number of characters in a specified text string.	LEN(text)	LEN(PartNumber__c)
LN	Returns the natural logarithm of a specified number. Natural logarithms are based on the constant e value of 2.71828182845904.	LN(number)	LN(10) returns the natural logarithm of 10, which is 2.30.
LOG	Returns the base 10 logarithm of a number.	LOG(number)	LOG(10)
LOWER	Converts all letters in the specified text string to lowercase. Any characters that aren’t letters are unaffected by this function. Locale rules are applied if a locale is provided.	LOWER(text)	LOWER("MYCOMPANY.COM")
LPAD	Inserts characters you specify to the left side of a text string.	LPAD(text, padded_length, pad_string?)	LPAD(Name, 20)
MAX	Returns the highest number from a list of numbers.	MAX(number1, number2, ...)	MAX(1, 2, 3)
MCEILING	Rounds a number up to the nearest integer, towards zero if negative.	MCEILING(number)	MCEILING(2.5) returns 3; MCEILING(-2.5) returns -2
MFLOOR	Rounds a number down to the nearest integer, away from zero if negative.	MFLOOR(number)	MFLOOR(2.5) returns 2; MFLOOR(-2.5) returns -3
MID	Returns the specified number of characters from the middle of a text string, given the starting position.	MID(text, start_num, num_chars)	MID(Division, 3, 4)
MILLISECOND	Returns a milliseconds value in the form of a number from 0 through 999.	MILLISECOND(value)	MILLISECOND(TIMEVALUE(ClosedDate))
MIN	Returns the lowest number from a list of numbers.	MIN(number1, number2, ...)	MIN(1, 2, 3)
MINUTE	Returns a minute value in the form of a number from 0 through 60.	MINUTE(value)	MINUTE(TIMEVALUE(ClosedDate))
MOD	Returns a remainder after a number is divided by a specified divisor.	MOD(number1, number2)	MOD(3, 3) returns 0; MOD(4, 3) returns 1
MONTH	Returns the month, a number between 1 (January) and 12 (December), in number format of a given date.	MONTH(date)	MONTH(Code_Freeze__c)
NOT	Returns FALSE for TRUE and TRUE for FALSE.	NOT(logical)	IF(NOT(ISPICKVAL(Status, "Closed")), ROUND(NOW()-CreatedDate, 0), null)
NOW	Returns a date/time representing the current moment.	NOW()	NOW()
NULLVALUE	Determines if an expression is null (blank) and returns a substitute expression if it is. If the expression isn’t blank, it returns the value of the expression.	NULLVALUE(expression, substitute_expression)	NULLVALUE(Sample_Due_Date__c, StartDate +5)
OR	Determines if expressions are true or false. Returns TRUE if any expression is true. Returns FALSE if all expressions are false.	OR(logical1, logical2, ...)	OR(Sample_Rate__c < 0, Sample_Rate__c > 0.40)
PICKLISTCOUNT	Returns the number of selected values in a multi-select picklist.	PICKLISTCOUNT(value)	PICKLISTCOUNT($Record.Multi_Selected__c)
REGEX	Compares a text field to a regular expression and returns TRUE if there’s a match. Otherwise, it returns FALSE. A regular expression is a string used to describe a format of a string according to certain syntax rules.	REGEX(text, regex_text)	NOT( OR( LEN (SSN__c) = 0, REGEX(SSN__c, "[0-9]{3}-[0-9]{2}-[0-9]{4}")))
RIGHT	Returns the specified number of characters from the end of a text string.	RIGHT(text, num_chars)	TRIM(LEFT(LastName, 5))&"-"&TRIM(RIGHT(SSN__c, 4))
ROUND	Returns the nearest number to a number you specify, constraining the new number by a specified number of digits.	ROUND(number, num_digits)	ROUND (1.5, 0) = 2; ROUND (225.49823, 2) = 225.50
RPAD	Inserts characters that you specify to the right side of a text string.	RPAD(text, padded_length, pad_string?)	RPAD(Name, 20)
SECOND	Returns a seconds value in the form of a number from 0 through 60.	SECOND(value)	SECOND(TIMEVALUE(ClosedDate))
SIN	Returns the sine of the number, where the number is given in radians.	SIN(number)	SIN(0.5)
SQRT	Returns the positive square root of a given number.	SQRT(number)	SQRT(25)
SUBSTITUTE	Substitutes new text for old text in a text string.	SUBSTITUTE(text, old_text, new_text)	SUBSTITUTE(Name, "Coupon", "Discount")
TAN	Returns the tangent of the number, where the number is given in radians.	TAN(number)	TAN(0.5)
TEXT	Converts a percent, number, date, date/time, or currency type field into text anywhere formulas are used. Also, converts picklist values to text in approval rules, approval step rules, workflow rules, escalation rules, assignment rules, auto-response rules, validation rules, formula fields, field updates, and custom buttons and links.	TEXT(value)	TEXT(ExpectedRevenue)
TIMENOW	Returns a time value in GMT representing the current moment. Use this function instead of the NOW function if you only want to track time, without a date.	TIMENOW()	TIMENOW()
TIMEVALUE	Returns the local time value without the date, such as business hours.	TIMEVALUE(value)	TIMEVALUE(ClosedDate)
TODAY	Returns the current date as a date data type.	TODAY()	TODAY()
TRIM	Removes the spaces and tabs from the beginning and end of a text string.	TRIM(text)	TRIM(LEFT(LastName,5))& "-" & RIGHT(FirstName, 1)
TRUNC	Truncates a number to a specified number of digits.	TRUNC(number, num_digits)	TRUNC(1.2345, 2)
UNIXTIMESTAMP	Returns the number of seconds since 1 Jan 1970 for the given date, or number of seconds in the day for a time.	UNIXTIMESTAMP(datetime)	UNIXTIMESTAMP()
UPPER	Converts all letters in the specified text string to uppercase. Any characters that aren’t letters are unaffected by this function. Locale rules are applied if a locale is provided.	UPPER(text)	UPPER("http://mycompany.com ")
URLENCODE	Encodes text and merges field values for use in URLs by replacing characters that are illegal in URLs, such as blank spaces, with the code that represents those characters as defined in RFC 3986, Uniform Resource Identifier (URI): Generic Syntax. For example, blank spaces are replaced with %20, and exclamation points are replaced with %21.	URLENCODE(text)	http://www.google.com/search?q={!URLENCODE(Opportunity.AccountNameFormula__c)}
VALUE	Converts a text string to a number.	VALUE(text)	VALUE(Lead_Number__c)
VLOOKUP	Returns a value by looking up a related value on a custom object similar to the VLOOKUP() Excel function.	VLOOKUP(field_to_return, field_on_lookup_object, lookup_value)	AND( LEN(BillingPostalCode) > 0, OR(BillingCountry = "USA", BillingCountry = "US"), VLOOKUP( $ObjectType.Zip_Code__c.Fields.State_Code__c, $ObjectType.Zip_Code__c.Fields.Name, LEFT(BillingPostalCode,5)) <> BillingState )
WEEKDAY	Returns the day of the week for the given date, using 1 for Sunday, 2 for Monday, through 7 for Saturday.	WEEKDAY(date)	WEEKDAY(Code_Freeze__c)
YEAR	Returns the four-digit year in the number format of a given date.	YEAR(date)	YEAR(Code_Freeze__c)

---

PML Example

The table below shows a practical example of PML as it would appear in a Rule Action.

PML Field	Description
%%HYPERLINK($Base_Url + "/" + $Record.Id, $Record.Name)%%	Provides a direct link to the record that triggers a Rule, formatted as the record’s Name instead of a URL. Works with both internal & portal users thanks to the Base URL resource.