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)
- Creating a Formula Field
- Simple Merge Fields
- Advanced Merge Fields
- PML Example
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:
- Navigate to Salesforce Setup by selecting the cog icon in the upper right-hand corner and Setup from the drop-down.
- Select the Object Manager navigation menu tab. This will open a list of all available objects.
- Locate the object that you would like to create a formula field on and select its hyperlinked Label.
- Select the Fields & Relationships tab on the object's page.
- Click the New button to begin the field creation process.
- Select Formula from the field type options and then click Next to proceed.
- 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. - 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.
- 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.
- Set field visibility for the profiles you would like to be able to view the field, then click Next.
- 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 >. |
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. |
Comments
Article is closed for comments.