Formula Presentation Configuration

A detailed explanation of configuration options and syntax for the PSPA Tech Formula Presentation Enhancement.

Overview

The Formula Presentation Enhancement is used to tell a Benefit Calculation story.

Formula Presentation Templates allow users to configure detailed descriptions of how a benefit was calculated. Templates are stored as a Rich-Text long text field. The Templates can include conditional logic and variable substitutions to present results in a concise and meaningful natural language story.

The Formula Presentation process is similar to a BI Publisher report using an RTF Template, but it eliminates the need for programming to generate an XML data source, enables the presentation of the results within an application page, and is optimized for displaying PeopleSoft Pension results.

Implementing Templates

Formula Presentation Templates are configured using one of these three pages:

Formula Presentation Configuration

Set Up HCM > Product Related > Pension > Components > Formula Presentation Config

This page allows users to create or edit any Formula Presentation template, regardless of whether it is tied to a Definition. Formula Presentation templates associated with a Definition will be resolved for display on the Overview page only when the Definition was used to resolve a Function Result in the member’s calculation.

Standalone Formula Presentation configurations are tied to a Benefit Plan, have a new Function Name of PRESENT, and do not need to be added to the Plan Implementation. All active (Use = All) standalone Formulas for the Benefit Plan results being displayed will be resolved for display on the Overview page.

Sequence

The Sequence Number provides the ability to create and save multiple versions of templates for a particular Formula Presentation configuration.

Use

The Use field identifies when a template should be applied.

The Template with the highest sequence number for the applicable Use will be used.

This field is expected to expand to additional values as features are developed, such as Overview, Worksheet, or Letter.

Sort

The Sort field configures the sort order when multiple formula results are presented together.

Expand

The Expand Formula by Default checkbox configures whether the formula results should be expanded or collapsed by default when presented with a collapsable header. The formula can also include conditional expand-formula and collapse-formula keywords that override the default.

Description

An optional Description can be entered for Formula Presentation configurations not tied to a Definition.

Benefit Plan

The Benefit Plan associated with a Formula Presentation configuration must be entered for Formulas not tied to a Definition. Only formulas associated with the calculation results plan will be displayed.

Highlight

The Validate and Highlight button checks for common syntax errors and provides a message describing the error. This helps the configurator set up Templates that will execute without error at run-time. Conditional Logic, Keywords, Comments, and Links will be color-highlighted in Template text for greater clarity and easier review. These system-generated color highlights may be left in the text because they will not appear in the final results.

Here is an example formula with highlighting for Data Sets, If/Then/Else/End-If, and Keyword Hide-Row:

Validate

Here is an example of an error, such as an extra brace, caught by the Validation button:

Messages give you details of the errors found:

Error is highlighted in Red for easy identification:

Clear Highlights

The Clear Highlights button removes color highlights added by the Validate and Highlight button.

Header

The header Template is used for the section heading when multiple formula results are presented together. Text formatting options are not used in the display of the resolved header.

Formula

The formula Template is used for the section detail. This is where the concise and meaningful natural language story of how this part of the benefit was computed is configured.

Comment

Comments can be added with notes from the configurator. Comments are stored as RTF data, so sections of a Formula can be copied to the comments for backup or discussion.

Benefit Formula

Set Up HCM > Product Related > Pension > Components > Benefit Formula > Formula Presentation

The Formula Presentation page is included in the Benefit Formula component, configuring the Template alongside the Benefit Formula Custom Statement logic.

Default

The Default button on the Formula Presentation in the Benefit Formula component uses an improved Custom Statement Algorithm to create a default Formula Presentation Template.

Click the Show Algorithm to see an improved description of the Custom Statement configuration:

Click the Formula Presentation Configuration Default button to generate a Formula based on the Algorithm output:

Descriptions are pulled from the parameter configuration where possible, and the values are displayed. Additional manual editing may be required to get the Formula to present exactly as you want.

The assignment result for the Then and Else rows includes a sequence number so the viewer can identify if the Then or the Else row caused the final result assignment. The result will show N/A for the row not used to assign a value.

Custom Statement Sequence

Two new enhancements to pages that use Custom Statements, such as this Benefit Formula page, make it easier to edit Custom Statements.

As delivered, inserting rows into a Custom Statement between two rows sets the sequence number in increments of two, often making it impossible to insert rows where needed.

The row inserts now set the new sequence number halfway between the two existing rows.

In addition, there is a new button to Resequence the entire Custom Statement.

Starting with this Custom Statement and Formula like below, click the Resequence button:

The results include a new set of sequence numbers with space between to add new rows.

References to the sequence numbers in the formula have also been updated.

But the formula itself is not updated until the Default button is pressed again:

Other formulas may reference the sequence numbers modified by the resequence button. They will need to be identified and updated manually.

Early/Late Adjustments

Set Up HCM > Product Related > Pension > Components > Early/Late Adjustments > Formula Presentation

The Formula Presentation page is included in the Early/Late Adjustments component, configuring the Template alongside the Early/Late Adjustment configuration.

Configuration Design

This section presents hints for designing Formula Presentation configuration.

Definitions

Formula Presentation templates are either associated with a Definition or standalone. They are not associated directly with a Function Result. The logic behind this design is that the Story details are closely tied to which Definitions were used. The story behind how a Function Result was computed can differ depending on which Definition was used.

As such, it will be necessary to configure a unique story for each Definition included in the Function Result. The Run-Time Engine will display Formula Presentation results only for Definitions resolved when the Calculation was processed. Standalone Formula Presentation templates associated with the Benefit Plan will also be displayed.

Include

Using the Include command, it is possible to roll up results from multiple Formula Presentation templates. This is useful if you want to include more depth of details within one Formula Presentation.

One powerful feature of the Include commands is a Function Result Name may be specified. The Formula Presentation for the Definition used to compute the Function Result will be included at run-time. Using Include with a Function Result Name simplifies the consolidation of many possible paths the Calculation may have taken.

If you have many different Definitions included in the Early Retirement Factor, and you want to include details of the Early Retirement Factor in our Early Retirement Benefit Formula, reference the Early Retirement Factor Function Result Name in the Include command and the Formula Presentation defined for the Definition used to resolve the Early Retirement Factor Function Results will be included.

Calculation Details

A section with general information about the Calculation can be added:

Historical Calculation Warning

A warning message can be set up for when the Calculation was run before Pre-Requisite Updates were implemented or run without the Detailed Worksheet option selected, using the {HAS_GROUP_RESULTS} and {CALC_DETAILED_WORKSHEET} Pre-Defined Field:

Disclaimer

A disclaimer or generic message can be added to all Formula Presentation displays.

Which would appear as follows:

The Disclaimer can be disabled by changing the Use of the Formula Presentation template from All to None:

Overrides

Overrides can be displayed using a Formula Presentation when applicable:

Here’s an example of a message displayed when an override has been used. There will be no FAE details rows in the event an override was used:

In other cases, the OVERIDE Data Set, can be searched for a particular Function Result.

{Begin OVERRIDE AND PROC_NAME = ‘MY_FR’}{IF {OVERRIDE.OVERRIDE} = Y Then}Override Used{End-If}{End OVERRIDE}

Messages

Calculation Process Messages can be displayed using a Formula Presentation:

Editing Templates

The Rich-Text Template fields include an editor ribbon.

Most icons and capabilities should be familiar, but understanding these options can be helpful:

Expand

Expand opens a secondary page to edit the field using all the available screen real estate. This can be very helpful to get a bigger picture of all the configuration data. Click the expand button again to return to the main page, where changes can be saved.

Source

Toggles the display of Template configuration between the Rich-Text display and the code behind the Rich-Text display.

It can be useful to toggle Source, select and copy Source, open a new configuration, toggle Source, paste Source, and toggle back to standard RTF. This procedure will retain any formatting when copying and pasting.

Images

Images can be uploaded from a local drive but are stored in the instance and will not migrate with the configuration. It is better to use images that can be retrieved by URL.

Links

External Links can be added with the link icon. This is useful for including links to plan documents or statutes published online.

Text Formatting

Text formatting options used within Template syntax additions can cause problems with Validation and Highlighting functionality and Formula resolution. For best results, do not manually format the text of any conditional or keyword instructions. Text formatting options for variable substitutions should span and include the starting and ending braces ({}).

Data Substitutions

Variables wrapped in braces – {}

Variable substitution options are delimited by period – .

Unresolved values are highlighted in Red at runtime.

Function Results and Aliases

{Alias}

{Alias.Factor}

{Alias.Format}

{Alias.Factor.Format}

Alias

The Alias can be any resolved calculation parameter value with results saved in one of the alias results tables populated by the Calculation process – PA_CLC_ALS_VAL, PS_CLC_VAL_DEC, PA_CLC_VAL_DATE, PA_CLC_VAL_CHAR. This may include Function Results, Database Aliases, Date Aliases, Duration Aliases, Table Lookup Aliases, Function Result Aliases, Factor Aliases, and Custom Statements.

Format – Number

$ and % should be added outside of the variable substitution with formatting.

${MY_BEN_F.%15.2Rv}

{MY_PCT_F.%6.6Rv}%

The Format parameter has the following format:

%[flags][width][.precision][R | T] [type]

• Flags have the following format:

• Width must be specified as a non-negative integer. Specifying an asterisks (“*”) allows for dynamic field width specification. The maximum width is 50.
• Precision specifies how many digits follow the “.”. It must be specified as a non-negative integer. Specifying an asterisks (“*”) allows for a dynamic precision specification. The maximum precision is 50.
• R specifies rounding in conversion from the internal PeopleCode representation, that is, specifying 12.345 with precision of 2 (%n.2Rt) prints 12.35. In the absence of the R control rounding is the default.
• T specifies truncation in conversion from the internal PeopleCode representation, that is, specifying 2.345 with precision of 2 (%n.2Tt) prints 12.34.
• Type has the following format:

Example

Format – Date

Not Implemented

{EVENT_DT.%”m/d/y”}

Uses DateTimeToLocalizedString Patterns

Using the Pattern Parameter

Pattern takes a string value, and indicates how you want the DateTime or Date value converted.

The valid values for Pattern are as follows.

Note: The values for Pattern are case-sensitive. For example, if you specify a lowercase m, you get minutes, while an uppercase M displays the month.

The number of pattern letters determines the format.

Any characters in Pattern are not in the ranges of [‘a’..’z’] and [‘A’..’Z’] are treated as quoted text. For instance, characters like ‘:’, ‘.’, ‘ ‘, ‘#’ and ‘@’ appear in the resulting string even they’re not within single quotes.

A pattern containing any invalid pattern letter results in a runtime error.

Examples using a United States locale:

Format – Character

Not Implemented

Add the capability to change case L, U, F.

Add the capability to get a substring.

{MY_CHAR_A.%F1.2} = Formal Substring from 1 for 2.

Factor

Substituted variables may be adjusted by a Factor. The factor functionality allows simple mathematical operations to be performed with a static value or a simple variable.

This functionality is useful for shifting the decimal position when displaying percentages:

{MY_PCT_F./100}%

It can also be used for very simple calculations when a stored result is not available:

{MY_BEN_F.*{MY_FCTR_A}.%15.2Rv}

The Factor parameter has the following format:

.[operator][number]

• Operator has the following format:

• Number has the following format:

• Multiple factor operations may be included, separated by periods. Order of operations is from left to right.
• Limited to simple variable substitution.

Examples

Pre-Programmed Variables

{Variable}

{Variable.Factor}

{Variable.Format}

{Variable.Factor.Format}

Variable

Pre-Programmed variables have been defined to retrieve calculation and process instance data related to the calculation results being reviewed. In addition, pre-programmed variables have been defined to display the applicable Function Result, Group Definition, and Definition for the Definition being displayed.

Pre-Programmed variables are referenced by name using the standard brace-wrapped notation.

Here is the complete list of pre-programmed variables available for reference in a Formula Presentation Template:

Pre-Programmed Variable List

Custom Programmed Variables

Custom Programmed Variables can be set up for Formula Presentation substitution by adding logic to the Replace_Operand function.

Custom variables are referenced by name using the standard brace-wrapped notation:

{APPL_OPTION}

Here are example custom variables:

Examples

Function Result Alternative Results

{FunctionResult.Alternative}

{FunctionResult.Alternative.Factor}

{FunctionResult.Alternative.Format}

{FunctionResult.Alternative.Factor.Format}

Function Result

The Function Result specified can be any Benefit Formula, Service, Early/Late Adjustment, or Plan Participation Function Result that returns additional alternative results.

Alternative

Function Results return a primary result and can be referenced by standard Alias syntax:

{MY_ERF_F}

Some types of Function Results return additional results, which can be referenced by specifying the Alternative descriptor as follows:

{MY_ERF_F.PRD_OF_ADJ}

This is a list of the Alternative Results supported:

Examples

Custom Statement Assignments / Temporary Variables

{Sequence.CustomStatement.Assignment}

{Sequence.CustomStatement.Assignment.Factor}

{Sequence.CustomStatement.Assignment.Format}

{Sequence.CustomStatement.Assignment.Factor.Format}

This pattern returns the assigned value. This pattern will return N/A if no assignment was performed on the sequence numbered row, for example, due to IF-THEN-ELSE logic in the custom statement.

Sequence

The Sequence corresponds with a particular row of a Custom Statement. Since Temporary Variable and Custom Statement Result can be assigned on more than one row, the Sequence tells the run-time engine the row for which you want to display the assignment.

Custom Statement

Only Custom Statement Aliases and other Definitions based on the Custom Statement format, such as Benefit Formulas, have Sequence-numbered rows and can be used with this pattern.

Assignment

The assignment value is Operand 3 from the Custom Statement, where a result is assigned. This may be a Custom Statement result assignment or a Temporary Variable assignment.

Examples

This formula uses two different tables and displays only one depending on whether the benefit formula result was assigned on sequence number row 200 or 220:

Data Sets

Data Sets are used to display multiple rows of data. Fields can be referenced between the Begin Set and End Set commands. Counts can be referenced after the End Set command.

Syntax Patterns

{Begin Set Where}

{Set.Field.!} – Long Translate Value

{Set.Field.$} – Short Translate Value

{Set.Field.Factor}

{Set.Field.Format}

{Set.Field.Factor.Format}

{End Set}

{Set.#} – Count

Sets

The Set is the predefined, programmed name for a set of data retrieved from a table, view, or SQL statement.

Pre-Programmed Data Sets

Custom Data Sets

Begin Set

The Begin command opens a data set for retrieval. The optional Where clause addition can be included to select a subset of the defined data set. For example,

{Begin FAE AND A.FUNCTN_RESULT_NM = ‘S_FAE12_F’}

get rows from the FAE results for a specific Function Result.

Field

The Field is the field name from the record containing the data set.

Translate Value

The translate value for fields in the data set that have them can be retrieved using these suffixes:

End Set

The End command closes a data set for retrieval.

Count

The number of rows included in a data set can be accessed after the data set has been closed with the {End Set} command.

The number of rows can be displayed using the {Set.#} command, for example:

{FAE.#}

Conditional logic can be added to display data only if there are rows returned:

{Begin FAE AND A.FUNCTN_RESULT_NM = ‘S_FAE12_F’}{End FAE}{If  {FAE.#} > 0 Then}Show My Results{End-If}

Custom Data Set Counts

Examples

Here is an example that includes additional Where clause criteria and returns the number of rows found:

Here is an example that added a row to a table for each row in the Data Set. Then, based on the number of rows returned, either includes a link to access a data set-related page or hides the formula altogether.

Here are some sample results for the above configuration:

Here is an example using the OPTFORM data set:

Conditional Logic

If Then Else

IF statements can be used to introduce conditional logic for the run-time engine to evaluate. This capability is useful in producing a formula presentation tailored to the member’s calculation.

Syntax Patterns

{If Conditions Then}Result_1{Else}Result_2{End-If}

A condition can be formatted as:

{Alias} Operator {Alias}

{Alias} Operator Value

Value Operator {Alias}

Value Operator Value

Conditions can be joined with And/Or:

Condition AND Condition

Condition OR Condition

The order of And/Or operations is from left to right, and parenthesis would be ignored.

Alias

The Alias can be any variable substitution. Do not include format options.

Value

The value can be a number, character, or date value. It must not include spaces or quotes.

The keywords SPACE or SPACE can be compared against a blank result.

The keyword N/A can be used in conjunction with CS assignment substitutions.

Dates should be formatted MM/DD/YYYY with leading zeros and always be ten characters long.

Operator

Operator can be =, <, >, <>, >=, or <=

Result

The results may include any template data, including additional If Then Else constructs, variable substitutions, tables, keywords, or text. Results may include carriage return.

Nesting of If/Evaluate is partially supported. Test more carefully.

Still some problems with nesting within Data Set results.

Examples

Evaluate

Evaluate Statements can be another useful tool for transforming data to be presented.

Syntax Patterns

{Evaluate {Alias}}{When Value}Result_1{When Value}Result_2{When-Other}Result_3{End-Evaluate}

Internal Links

Bookmark / Anchor

{#Anchor.Name.MouseOver}

Bookmark Link

{@Anchor.Name}

The section with the Anchor needs to be expanded for the Bookmark Link to find it.

PeopleSoft Internal Link

Preconfigured options are available to include context-sensitive internal PeopleSoft links in the formula presentation. There are limitations on the state of the original window if updates are made in the target window.

Syntax Pattern

{^Link.Name.MouseOver}

Internal Link Options

Name

The Name is the label that appears in the Formula Presentation.

MouseOver

The MouseOver is the description that appears when the cursor is placed over the Label in the Formula Presentation.

External Links

Use the link icon in the editor to point to an external page/anchor.

Include

Including other Formula Presentation templates within another to roll up multiple details into one primary section.

Syntax Pattern

{Include Formula}

Formula

The formula is any Formula Presentation template or a Function Result name. When a Function Result name is specified, the run-time engine resolves and includes the Definition used to compute the specified Function Result.

Example

Keywords

Keywords are not contained in braces – {}.

Hide-Row

A row in a table can be conditionally hidden using the Hide-Row keyword.

Hide-Table

A table can be conditionally hidden using the Hide-Table keyword.

Hide-Formula

A formula presentation can be conditionally hidden using the Hide-Formula keyword.

Collapse-Formula

Using the Collapse-Formula keyword, a formula presentation can be conditionally displayed in a collapsed section. This would override the Expand Formula by Default settings.

Expand-Formula

A formula presentation can be conditionally displayed in an expanded section using the Expand-Formula keyword. This would override the Expand Formula by Default settings.

Comments

Comments

Comments bracketed by /* */ or <* *> are removed from the Formula presented at run-time.

Outstanding

• Date Formatting
• Character Formatting
• Add != compare operator
• Ensure all substitutions where a value can not be resolved are highlighted in red.
• Ensure Tools are displayed when Show Hidden button exposes hidden formulas.

Additional Resources

How to Tell a Tailored Benefit Calculation Story