Understanding and Using Practifi Merge Language (PML)

Follow

Overview

With the functionality of the Rulebook and Rule-Based Actions in Practifi, there is a need to use merge fields that dynamically source data from related records to make these actions contextually relevant. To make this possible, Practifi Merge Language (PML) can be used to create merge fields and send preformatted text to employees and, in combination with the Workflows for Portals feature, portal users. This article outlines the basic functionality of PML and provides information on creating simple and advanced merge fields in your organization.

Understanding Practifi Merge Language (PML)

Merge field compatibility varies across Practifi's alert channels:

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

To make it possible to achieve all the desired use cases across all our alert channels, PML can be used to create merge fields. PML is very similar to the syntax used in Salesforce’s own formula fields, which provides power and familiarity to the way in which merge fields are specified. With PML, two types of merge fields are available: advanced and simple.

  • 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. To create a formula field:

  1. Navigate to Salesforce Setup by selecting the cog icon in the upper right-hand corner and Setup from the drop-down.
  2. Select 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. Select 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 and then click Next to proceed. 
  7. Enter the Field Label and click into the Field Name field to auto-generate this 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 Formula Return Type from the available options. This is how you would like the value that is generated by the formula to display within the field. Once selected, click Next to proceed. 
  9. Enter your formula into the field using PML. If creating a simple merge field, enter this information under the Simple Formula tab. For advanced merge fields, enter your formula under the Advanced Formula tab.
    Screenshot_2023-05-25_at_11.52.44_AM.png
  10. Set field visibility for the profiles you would like to be able to view the field, then click Next
  11. Select the page layouts that you would like this field to be available on and press Save to finalize the field creation. The field will still need to be added to your firm's page or Active Form layout for visibility within Practifi.

Simple Merge Fields

To create a simple merge field, use a single percentage symbol - % - to indicate where the merge field begins and ends. Use the same formatting method used when specifying a field reference in a formula field or when configuring Practifi features such as Active Forms and Rule Criteria.

Determining the “starting object” from which you specify a record field is an important prerequisite. The object will always have been specified within the context of your PML usage, e.g., when using PML within a Rule Action, the starting object is defined in the Object field of the parent Rule Criteria record.

Advanced Merge Fields

To create an advanced merge field, use a double percentage symbol - %% - to indicate where the merge field begins and ends. A resource and function will then need to be specified. 

Adding a Resource

Similar to the Rule Builder, these are references to data located elsewhere in Practifi. The available resource types are similar, too. However, because there’s no visual resource selector to use here, you’ll instead refer to resource types using these codes:

  • 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.
  • Custom Permission: $PERMISSION
  • Custom Setting: $SETUP
  • Record Field: $Record
    • Determining the “starting object” from which you specify a record field is an important prerequisite. The object will always have been specified within the context of your PML usage, e.g., 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 selected. The syntax here behaves identically to field references in formula fields. For example:

  • If you were creating a formula field on the Task object that returned the name of the Related Entity, the field reference would be formatted as practifi__Related_Entity__r.Name.
  • If you were referencing the Related Entity’s Name in a Rule Action, the reference would be formatted as %%$Record.practifi__Related_Entity__r.Name%%.

Utilizing a Function

Functions are similar to formulas in Excel; you invoke them by name and provide the necessary inputs, then receive a computed output within your alert. PML supports most, but not all, of the functions found in formula fields. The supported functions are detailed in the 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 cosign 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, 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, 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 time 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 merge field values for use in HTML by replacing characters that are reserved in HTML, such as the greater-than sign (>), with 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 merge 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 merge 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 merge 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

Below is an example of PML:

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.

 

0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.