Working with messages

You can use Rule-Message instances to add errors to a property or page on the clipboard. You can also use Rule-Message instances to add warnings or smart tips to a rule.

In most cases, adding an error to a clipboard page prevents the page from saving to the database but does not prevent further processing. The text of your message is not always displayed to users who trigger the error condition.

When you add a warning to a rule, the text of the message appears in the rule form header. Use the Records Explorer to view the full catalog of messages in your application.

Adding errors to a property or page

From an activity, call the Property-Set-Messages or Page-Set-Messages method with the name of your message. When you expand the activity step, you can pass a tab-delimited string to the message that contains parameter values. The system derives the class key part of the message by examining the class of the step page.

When using Java in an activity step, you can call variations of the Public API method addMessage(). These methods support literal string messages or the name of a message concatenated with tab-delimited parameter values. If you do not pass a class key part as a parameter to one of these methods, the system uses the class of the step page to find the Rule-Message instance.

For more details on the signatures, supported syntax, and overloaded instances of these methods, refer to the PegaRULES Java Engine Public API. Search for the following interface names:

• com.pega.pegarules.pub.clipboard Clipboard Page
• com.pega.pegarules.pub.clipboard Clipboard Property

Adding warnings to a rule

Use the pxAddGuardrailMessage function to add a message to the pxWarning page list of a rule. You must have at least one Rule-Message instance with the category set to Warning to use this function.

For example, you can add a Java step to the CheckForCustomWarnings extension point that runs when a rule is saved. In this step, add a call to pxAddGuardrailMessage when warning criteria is met. You can pass in the name of a Rule-Message instance, along with any supported parameters.

At run time, the function retrieves the text from a localized version of the message, if one exists. It then combines metadata, such as severity, from the base version of the message to display a cohesive warning to the user.

For more details on the run time behavior for this function, refer to the PegaRULES Java Engine Public API. Search for the addGuardrailMessage() method.

Retrieving messages

Use standard functions to retrieve the text of a message and determine if a page, property, or rule has associated warnings or errors.

You can call:

• getRuleMessage(tools, messageName) — Returns the localized text of the specified message.
• pyGetUnlocalizedRuleMessage(className, ruleMessageName) — Returns rule data for the specified message from the non-localized, base rule set.

• pyGetStringFormOfRuleMessage(messagePage, messageParameters) — Returns a string representation of the message and expected parameter names.

• hasMessages(stepPage) — Returns a boolean value, based on the presence of messages on the specified page.
• hasMessagesOnGivenProperty(myStepPage, myPropertyReference) — Returns a boolean value, based on the presence of messages on the specified property.

Page-Set-Messages method Property-Set-Messages method Completing the Parameters tab of the Message form Completing the Definition tab of the Message form How to extend the Message form

Open topic with navigation