Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

More about Map Values

Updated on November 15, 2021

Map value rules can be updated as needed to reflect changing business conditions, without the need to ask a skilled developer to modify complex activities or other rules.

Uploading an Excel spreadsheet to start

If you have in advance an Excel spreadsheet in XLS file format that contains useful starting information for a map value, you can incorporate (or "harvest") the XLS file and the information it contains directly into the new rule.


Both rows and columns contain a Type field (set on the Headers tab). The system makes comparisons according to the data type you recorded on the Headers tab, converting both the input and the conditions to the specified data type.

At runtime, the system evaluates row conditions first from top to bottom, until one is found to be true. It then evaluates column conditions for that row, left to right, until one is found to be true. It returns the value computed from that matrix cell.

Where map values are used

You can reference map values in the following places:

  • In activities that use the Property-Map-Value method or the Property-Map-ValuePair method. These methods evaluate a one-dimensional or two-dimensional map value, compute the result, and store the result as a value for a property.
  • In other map values, through a Call keyword in a cell.
  • Through a standard function ObtainValuePair() in the Pega-RULES:Map library.
  • On the Rules tab of a collection.

Input parameters in called map values rules

If a map value is evaluated through a decision shape on a flow, or one of the two methods noted above, the input value or values may be literal constants or may be property references, recorded in the flow or in the method parameters.

However, if a map value is evaluated by a Call from a cell in another map value, the evaluation always uses the Input Property on the Header tab. Nothing in the Call can override this source.

Special processing with Declare Expression calls

When a Declare Expression rule has Result of map value for the Set Property To field, special processing occurs at runtime when a property referenced in the decision table is not present on the clipboard. Ordinarily such decision rules fail with an error message; in this case the Default value is returned instead. For details, see the Pega Community article Troubleshooting: declarative expression does not execute when a decision rule provides no return value.


The Pega Platform does not limit the number of nodes in a map value. However, as a best practice to avoid slow performance when updating the form and also avoid the Java 64KB code maximum, limit your map value rules to no more than 300 to 500 rows.

You can view the generated Java code of a rule by clicking ActionsView Java. You can use this code to debug your application or to examine how rules are implemented.

Parent class

Through directed inheritance, the immediate parent of the Rule-Obj-MapValue class is the Rule-Declare- class. However, despite the class structure, this rule type does not produce forward or backward chaining. Technically, it is not a declarative rule type.

Standard rules

The Pega Platform includes a few standard map values that you copy and modify. Use the Records Explorer to list all the map values available to you.

Applies ToMap NamePurpose
Data-SetCorrPreference Selects a correspondence type based on an input value. For example, if the input value is "Home Address", the correspondence type result is Mail. Allows outgoing correspondence to be sent based to on available addresses, for a Data-Party object.
WorkOfficersCan associate an Operator ID or email addressee with officers based on the titles CEO, CFO, COO, and VP. (Cells are blank in the standard rule.)

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us