Financial Rollup
A field of type Financial Rollup contains a number that is the total of amounts recorded in posted transactions that fit specified criteria.
The uses for Financial Rollup fields include:
- Keeping a total of the transactions posted with a particular purchase order or line item as the primary object.
- Keeping a total of the transactions posted with a particular accounting code.
- Keeping a total of transactions posted as part of a particular project.
For the amount in a posted financial transaction to be included in a total in a Financial Rollup field, the field must be in a record referenced by the financial transaction. When a financial transaction is posted, its amount is added to the total in Financial Rollup fields if the field is in a record referenced by the financial transaction and the transaction meets the criteria specified for the field.
A financial transaction can reference a record in several ways:
- A record can be referenced as a financial transaction’s primary object.
- A record can be referenced as a financial transaction’s reference object.
- A Capital Project record can be referenced by a financial transaction as its project.
- A record in the Cost Code module’s hierarchy can be referenced as a financial transaction’s detail or summary accounting code.
Financial Rollup Fields
This section describes how to specify criteria for deciding which financial transactions are included in a Financial Rollup field’s total.
When editing the properties of a Financial Rollup field, the Data Modeler’s Property panel looks like the following:
(a) Field Properties
- Section: General
- Field Type: Financial Rollup
- Name: triBudgetCurrentRollupFR
- Label: Budget Current
- Description: _____
- Purpose: _____
- Required: 🞏
- Do not Auto Populate: 🞏
- Result Column: 🞏
- Mobile Field: 🞏
- Read Only: 🗹
- Use Custom UOM Precision and Mask: 🞏
- Token: [Set Token]
- Hierarchy Object
- UOM Source Attribute
- Start Date Source
- End Date Source
- Threshold Source Attribute
Most of the properties in a Financial Rollup field are the same as when editing other kinds of fields and are described in detail in the “Data Types” chapter of Application Building. Seven properties appear that are specific to Financial Rollup fields. They are as follows:
| Property Name | Description |
|---|---|
| Use Custom UOM Precision and Mask | This property specifies whether or not this field will use the properties for Storage Precision and Display Mask as they are defined on the UOM. If it is not checked, the platform will refer to the UOM’s Storage Precision and Display Mask. If it is checked, the Storage Precision and Display Mask can be overridden. |
| Token |
Use the Token property to specify a set of criteria for which financial transactions will be included in the field’s total. This set of criteria is called a financial token. A financial token can be shared by multiple Financial Rollup fields. One way to specify the token is to click the List icon The other way to specify the token uses the hyperlink next to the icons. If the text of the hyperlink is Set Token, clicking the hyperlink causes a Token form to pop up for creating a new financial token. If the text of the hyperlink is something else, it is the name of an existing token. In this case, clicking the hyperlink causes that token’s form to pop up. The Token form is described in “Financial Tokens”. When editing an existing financial token be especially careful if the financial token is shared with other field definitions. Any changes you make to the financial token affects all field definitions that share the financial token. Financial tokens are the main tool for selecting which financial transactions are included in a Financial Rollup field’s total. Financial tokens are explained in greater detail in “Financial Tokens”. |
| Hierarchy Object |
Use the Hierarchy Object property to place an additional condition on which financial transactions are included in a Financial Rollup field’s total. The Hierarchy Object property restricts the financial transactions included in a Financial Rollup field’s total to only those associated with a particular accounting code. The value for the Hierarchy Object property is chosen from a drop-down list. The drop-down list always includes the choices None and Self. For Financial Rollup fields that are part of a business object in a hierarchy module, always choose Self. For Financial Rollup fields that are part of a business object that is not in a hierarchy module, the usual value is None. If the value for the Hierarchy Object is None, the system rolls up all financial transactions where the primary object or reference object is the same as the current record. If the value for the Hierarchy Object is defined (not None), the system rolls up all financial transactions association to that hierarchy and ignores any current content. If the Hierarchy Object is defined but there is no value at runtime, the system returns no result. You can restrict a Financial Rollup field to include only financial transactions associated with a particular accounting code if the field is part of a business object not in a hierarchy module. To do this, there must be a locator field in the same business object as the Financial Rollup field. The locator field must reference a record in the Cost Code module’s hierarchy. If there are any locator fields in the same business object as a Financial Rollup field, the drop-down list in the field’s Hierarchy Object property includes the names of the locator fields. Choose as the value of the Hierarchy Object property the name of the locator field that references a record in the Cost Code module’s hierarchy. The total in the Financial Rollup field will only include financial transactions associated with the accounting code represented by the record referenced by the locator field. |
| UOM Source Attribute |
A user can be given the option of setting the currency UOM of the Financial Rollup fields they see in a form. There are several steps to making this work for the user, one of which is specifying the UOM Source Attribute property in the Financial Rollup field. The following must be accomplished:
Then the user can override the currency UOM defined in the token, indicate a different currency UOM, and see the Financial Rollup fields in the selected currency UOM. The UOM Source Attribute specified must be part of the same business object as the Financial Rollup field and only applies to currency UOM fields. The UOM Source Attribute only affects the currency UOM displayed at runtime; currency values are still calculated and saved when the financial transaction is posted. If the UOM Source Attribute for a Financial Rollup field is blank, the currency users see is the currency UOM set in the Financial Rollup field’s token at design time. |
|
Start Date Source End Date Source |
The Start Date Source and End Date Source properties can be used to make the start and end dates used in a financial rollup be based on fields in the record. This makes the date range dynamic. To set a dynamic date range, select the Start Date Source and End Date Source from the drop-down lists. The values in the lists are Date or Date and Time fields in the Financial Rollup field’s business object. An example of how the Start Date Source and End Date Source properties are used in the system is capturing financial cost transactions within the context of a fiscal period located in the parent/reference record. If these properties are blank, the system uses the dates in the fields’ financial token. |
| Threshold Source Attribute |
When there is a value in the Threshold Source Attribute property, this Financial Rollup field is a scored Financial Rollup field, meaning it will be scored (as described in “Comparison” in Application Building). The score is displayed as a red, yellow, or green image to the left of the Financial Rollup field’s value. The value of the Threshold Source Attribute property must be a locator field that references the Threshold business object. This locator field must be in either a General section or a one-to-one smart section. For a Financial Rollup field that is in a smart section, the linked locator field must reside on the referenced business object. The Threshold record defines the threshold ranges and contains a UOM value that is used to convert the scored value. Select the linked locator field in the Threshold Source Attribute drop-down list. The list only shows locator fields in the same business object that references the Threshold business object. A scored Financial Rollup field can be used in a form section, non-table smart section, table smart section, or a vertical table section. The score for the field is calculated during the rendering of the field and is not stored. The platform compares the UOM of the Financial Rollup field with that of the Threshold record. If a conversion is needed, the platform converts the Financial Rollup value before comparing it with the threshold value to calculate the score. During runtime, the system uses the threshold record that is currently selected by the linked locator fields. If the locator field does not have a value, the Financial Rollup field displays without a score. The score is updated when the tab is reloaded. This means that if the value of the Financial Rollup field, or the threshold record, or the locator field that links to the threshold record, is changed, the score will not update (if needed) until the tab is reloaded. |
and select an
existing financial token to be used by the field. If you change
your mind and want to create a new financial token, click the Clear
icon 
to clear the previous
selection.Financial Tokens
In a Financial Rollup field, clicking Set Token or the hyperlinked token name causes the system to display a financial token form. It looks like the following:
(a) Financial Token Form
- Group: Group 1
- Token Name: _____
- Date Type: Transaction Date
- Start Date: _____
- End Date: _____
- UOM Type: --Any—
- UOM: --Any--
- Transaction Type: --Any--
The first two fields in the form are used to determine the name of the financial token. The first part of a financial token’s name comes from the list in the Group field. The second part of a financial token’s name comes from what is entered in the Token Name field.
Type whatever name you like in the Token Name field. To help avoid naming conflicts between applications, the first part of the name is chosen from the list in the Group field.
If you are writing a new application, you may want to add a new name to the Group field’s list. Clicking the New hyperlink to the right of the Group field causes a form to pop up in which you can add a new name to the Group field’s list. This form looks like the following:
(b) Add a New Group
- Group Name: _____
After you have specified the name of a financial token, use the financial token in one of the following ways to restrict which financial transactions will be included in Financial Rollup field:
-
You can restrict a Financial Rollup field to financial transactions from a specified range of time. This restriction can be based on either the financial transactions’ transaction date or system date, depending on which radio button is selected.
If you do not specify a date in the Start Date field or the End Date field, there is no date-based restriction in the financial transaction unless specified in Start Date Source and End Date Source. If you specify a date in the Start Date field, only financial transactions with a date on or after the specified date will be included. If you specify a date in the End Date field, only financial transactions with a date on or before the specified date will be included. If you specify a date in both the Start Date field and the End Date field, only financial transactions with a date on or between those dates will be included.
-
You can restrict a Financial Rollup field to financial transactions that have a number recorded with a particular unit of measure or currency. Use the UOM Type and UOM fields to do this.
When the UOM Type is set to Currency, you can choose SYSTEM_BASE in the UOM field to specify that the UOM of the financial token is the system's base currency, which is the currency that is specified in the BaseCurrency property in the TRIRIGAWEB.properties file.
Always specify a unit of measure or currency in every financial token. Financial Rollup fields do not have a unit of measure associated with them, so no conversion is performed if transactions with different units of measure are added into the same Financial Rollup field.
By specifying a unit of measure in the financial token, you ensure that all numbers totaled in a Financial Rollup field have a consistent unit of measure or currency. If you have defined a source UOM field for the Financial Rollup field, the source UOM would take precedence over any UOM defined on the Financial Token.
-
You can restrict a Financial Rollup field to financial transactions that have a specified transaction type with the Transaction Type field.
Always specify a transaction type in every financial token to avoid mixing numbers from different transaction types in the same Financial Rollup field.
At the bottom of the financial token form are two buttons labeled Update and Insert. At any given time, one is enabled and the other is grayed out. If the Update button is enabled, clicking it updates the existing financial token. If the Insert button is enabled, clicking it creates a new financial token.
Updating Totals in Financial Rollups
When a financial transaction is posted, all Financial Rollup fields affected by the posted financial transaction are updated to include the number from the newly-posted financial transaction. The only time a Financial Rollup field is automatically updated is when a financial transaction is posted.
Normally, updating the totals in a Financial Rollup field only when a financial transaction is posted is sufficient to keep the totals in Financial Rollup fields correct. This is not sufficient if the criteria for including financial transactions in a Financial Rollup field change. There is no automatic mechanism to recalculate the total in a Financial Rollup field after a change in its criteria for including financial transactions in its total.
The circumstances in which the total in a Financial Rollup field can become incorrect include the following:
- If a Financial Rollup field’s financial token changes, the field’s total may be incorrect.
- If the value in the Hierarchy Object property of a Financial Rollup field’s definition changes, the field’s total may be incorrect.
- If the value in the Hierarchy Object property of a Financial Rollup field’s definition is the name of a locator field and the accounting code the locator field refers to changes, the field’s total may be incorrect.
If you anticipate that any of these will happen to a Financial Rollup field, provide for your application to explicitly force recalculation of totals in Financial Rollup fields. Maximo® Real Estate and Facilities gives you a way to create a mechanism that will explicitly recalculate the totals in all Financial Rollup fields in a record. To create such a mechanism, configure a state transition to run some special logic that is intended for this purpose.
To configure a state transition to force the recalculation of a Financial Rollup field’s total, follow these steps:
- Navigate to the Data Modeler (described in the “Data Modeling” chapter of Application Building).
- Select the business object with the state transaction family that contains the state transition you want to configure.
- Click Tools and select BO State Transition. This causes a form to pop up that allows you to edit the state transition family.
- In the right panel, click the state transition you want associated with the special recalculation logic. This causes the color of the transition to change from gray to cyan. The fields that contain the state transition’s properties appear in the left panel. Type and apply the following:
(a) Transition Properties
- Action: cstRecalculate
- Label: Recalculate
- Class or Ejb Name: com.tririga.architecture.budget.ejb.BudgetHome
- Method Name: refreshAllTokens
- Apply the properties.
The next time a record goes through the configured state transition, the totals in all of its Financial Rollup fields will be recalculated.