Rolling Up Through a Hierarchy

Classification Rollup Fields

A field of type Classification Rollup can be configured either to allow a number to be directly entered into it or to contain the total of numbers from fields in child records. Classification Rollup fields are associated with a classification. The classification determines how data rolls up into or out of the field. The classification associated with a Classification Rollup field is set when the field is defined.

Classification Rollup fields should be used only in business objects that are in a hierarchy module.

The form showing the properties of a Classification Rollup field looks like the following:

• Section: General
• Field Type: Classification Rollup
• Name: _____
• Label: _____
• Description: _____
• Purpose: _____
• Required: []
• Do not Auto Populate: []
• Result Column: []
• Mobile Field: []
• Read Only: [x]
• Rollup Source: Roll Up
• Display Mask: #.####
• Storage Precision: 12
• Rounding Rule: Half Up
• Root Classification
• Formula: []
• Threshold Source Attribute

Most of the properties in a Classification Rollup field are the same as other kinds of fields and are described in detail in the “Data Types” chapter of Application Building. Four properties visible when a Classification Rollup field is first added are specific to Classification Rollup fields. They are as follows:

• The value of the Root Classification property determines the classification associated with the field. Click the Search icon to identify the classification.
• The value of the Rollup Source property determines how data gets into the field. The four choices in the drop-down list are as follows:

These values for Rollup Source allow two different ways to roll totals up through a hierarchy. The Data Entry andRoll Up values for Rollup Source allow data to be rolled up in a predetermined path, using classifications specified in the Data Modeler to determine which Classification Rollup fields will roll up into a given Classification Rollup field. When Rollup Source is Classification, data is filtered and rolled up in a path that is determined by the value of records’ Classification fields at the time of the rollup.

• When there is a value in the Threshold Source Attribute property, this Classification Rollup field is a scored Classification 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 Classification 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 Classification 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 Classification 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 Classification Rollup field with that of the Threshold record. If a conversion is needed, the platform converts the Classification 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 Classification Rollup field displays without a score.

The score is updated when the tab is reloaded. This means that if the value of the Classification 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.

When designing a hierarchy for rolling up data, there is an important restriction to be aware of. Classification Rollup fields with Rollup Source set to Classification ignore child records that contain Classification Rollup fields. This means that a record can be a child for one kind of rollup or the other, but not both.

Classification Rollup fields have no unit of measure. This means that it is crucial for all numbers rolled up into a Classification Rollup field to have the same unit of measure. Because Classification Rollup fields have no unit of measure, no conversions are done to resolve inconsistencies between different fields being rolled up.

Cost, Quantity

Sometimes you want numbers to be rolled up from a field in child records into a parent record’s Classification Rollup field that has the Rollup Source property set to Classification. This is straightforward if all the child records are the same kind of record. You just need to specify the name of the field you want the numbers to come from.

If there is more than one kind of child record, it is still straightforward to specify which field the numbers will come from if the field that the number comes from in each kind of child record has the same name. If there is more than one kind of child record and for each kind of child record numbers should come from fields with different names, things are more complex. Maximo Real Estate and Facilities allows you to handle this by indirectly specifying from which field the numbers should come.

The indirect specification of field names is done in the mapping properties of the business object used to create each kind of child record. First designate a number field as the quantity or cost of records created from the business object. Then configure the Classification Rollup field to get its values from the quantity or cost of the child records.

To access a business object’s mapping properties, select the business object in the Data Modeler and select BO Mapping from the Data Modeler’s Tools menu. You can read more about the Data Modeler, mapping properties, and BO Mapping in Application Building. The following shows what the form for editing a business object’s mapping properties looks like:

(a) Mapping Properties:

• Name: [Find]
• Cost: [Find][+][Find][+][Find][+][Find]
• Quantity: [Find]
• Image
• Conversion Group
• Exchange Date
• Control Number: [] Based on Prefix
• Prefix: [Find][Add][Delete]
• Suffix: [Find][Add][Delete]
• Start With: 1
• Delimiter

Although the first two properties after Name are labeled Cost and Quantity, they do not have to be used for those purposes.

The value for Quantity is the value of whatever field is selected. The value for Cost is a simple formula that can refer to more than one field.

You can configure a Classification Rollup field to roll up the values specified as Cost or Quantity by specifying Classification as the value of its Rollup Source property and selecting Cost or Quantity as its Rollup Type.

Rollup Actions

Unlike a spreadsheet that updates totals as details are added or changed, the totals in a hierarchy are not updated automatically. A record’s Classification Rollup fields are updated from values in child records only when requested.

There are two ways to ask for values to be rolled up from a record’s children:

• A user can manually cause a rollup to be done on a record. When using a form to interactively edit a record created from a business object that is in a hierarchy module, the form will have a Roll Up action in its menu bar. Clicking the Roll Up action causes values from the record’s children to be rolled up into its Classification Rollup fields.
• A workflow can cause a rollup to be done on a record by performing a Rollup action on the record.

Whichever of these mechanisms is used to cause a rollup, values are rolled up only from a record’s immediate children. If there is a lower level to the hierarchy and the values in a record’s immediate children do not reflect changes to the lower level, it is these stale values that will be rolled up.

To use this one-level-at-a-time rollup to make all rolled up totals consistent after a detail has changed, do a rollup into the immediate parent of the record that changed, then do a rollup into its parent until you have rolled up the new totals to the hierarchy’s root.

If you interactively edit a record that is part of a hierarchy and contains rolled up totals, it is important to do a roll up after you change a number that should be rolled up into the parent record. It is also important to remember that the rollup has to be done to the parent record, not the child record that was modified. The easiest way to ensure that these are not forgotten is to have a workflow associated with the record’s Save and Save & Close actions do the rollup on the parent. Expecting users to remember to edit a record’s parent to roll up changes made in a child record is not a good idea, because it is too easy to forget.

Consider the soda containers hierarchy shown earlier. After a change is made to numbers in the record named “Glass Soda Bottle 8 oz. Coca-Cola 1998 Christmas Design” you may want to roll up the new numbers in the total to the records above it in the hierarchy. To do this, first perform a rollup on the record labeled Soda Bottles. Then finish by doing a rollup on the record named Soda Containers.

This piecemeal way of rolling up data makes the most sense when changes are infrequent and the shape of the hierarchy is wide and shallow. In this situation, having workflows perform rollups on just the affected records may be faster than a method that would involve recomputing and rolling up all the totals in the hierarchy.

There are situations when recomputing and rolling up all the totals in the hierarchy all at once makes more sense. For example, if changes to the data in the hierarchy are frequent but the rolled up totals are seldom used, it may make more sense to recompute and roll up all the totals in the hierarchy just before they are needed.

A workflow can cause all the totals in the hierarchy to be recomputed and rolled up all at once. If a workflow performs a Rollup All action on a record, it causes data from all of the record’s children to be rolled up, not just the immediate children. If a workflow performs a Rollup All action on the root of a hierarchy, it causes all the totals in the hierarchy to be recomputed and rolled up.

Storage Precision

Classification Rollup fields use values from many records in a hierarchy to compute values. The platform handles the computation involved in rolling up these values based on the value of the Storage Precision and Rounding Rule properties. Storage Precision specifies the maximum number of decimal places to use when the field is stored in the database and when performing computations. Rounding Rule identifies how the platform will round raw data to the precision in Storage Precision.

When the platform performs classification rollup computations, it uses intermediate values as part of the computation. No intermediate rounding is explicitly done; however, some rounding may have occurred already based on the Storage Precision and Rounding Rule specified in the records being rolled up. The system uses Storage Precision of 12 and Rounding Rule of ROUND_HALF_UP for intermediate calculations. Only the final calculation to that produces the result is rounded based on the Storage Precision and Rounding Rule in the Classification Rollup field.

For example, the diagram shows an example rollup hierarchy for Storage Precision.

In this example, rollupTotal=A+B+C+D+E. Assume the storage precisions for A, B, C, D, and E are 4, 6, 3, 7, 8 respectively, and the storage precision for rollupTotal is 2. A, B, C, D and E will be added to an intermediate value with a precision of 12. Then, that value is stored as rollupTotal using the storage precision of 2 (defined on the business object for rollupTotal) and the appropriate rounding rule.

Hierarchy Rollup Example

This section uses the soda containers hierarchy shown earlier to demonstrate a hierarchy rollup. This hierarchy keeps information about a collection of soda cans and bottles. Assume the purpose of this hierarchy is to keep track of how many cans and bottles are in the collection. This can be accomplished using Classification Rollup fields with their Rollup Source property set to Roll Up or Data Entry. This kind of rollup is called a straight rollup.

For a straight rollup, a hierarchy contains two kinds of records: those containing detail data and those containing rolled up totals. Both kinds of records use a Classification Rollup field to contain their data. In records that contain detail data, the Rollup Source property of their Classification Rollup field is Data Entry. In records that contain rolled up totals, the Rollup Source is Roll Up.

In the soda containers hierarchy example, records that describe soda cans contain detail data and records that describe glass and plastic soda bottles also contain detail data. The record in the hierarchy that is the parent for all kinds of soda bottles contains a rolled up total, the total number of bottles in the collection. The record in the hierarchy that is the parent for all kinds of soda containers also contains a rolled up total that contains the total number of cans and bottles in the collection.

The example below shows the fields in Glass Soda Bottle records. The fields for Plastic Soda Bottle and Soda Can records are similar. The field involved in the straight rollup is the Classification Rollup field named RollupQuantity (cstRollupQuantityCR).

(a) Field List

• Field Name | Field Label | Field Type
• cstBrandCL | Brand | Classification
• cstDescriptionTX | Description | Text
• cstHasTwistOffTopBL | Has Twist-Off Top | Boolean
• cstNameTX | Name | Text
• cstRollupQuantityCR | Quantity | Classification Rollup

The RollupQuantity field is shown below:

(b) Field Properties

• Section: General
• Field Type: Classification Rollup
• Name: cstRollupQuantityCR
• Label: Quantity
• Description: _____
• Purpose: _____
• Required: []
• Do not Auto Populate: []
• Result Column: []
• Mobile Field: []
• Read Only: [x]
• Rollup Source: Data Entry
• Display Mask: #.####
• Storage Precision: 12
• Rounding Rule: Half Up
• Root Classification: each
• Formula: []
• Threshold Source Attribute

The Rollup Source property is set to Data Entry. This setting allows a user to enter numbers into the field.

The Root Classification field is set to each. For straight rollups, there are just two considerations for choosing a classification:

• The classification in the child field must be the same as the classification in the parent field. Only child fields that are supposed to rollup into a particular field in the parent should have the same Root Classification setting as the field in the parent.
• The platform does not care which classification is used for the Root Classification setting. To help document the rollup’s purpose, choose a classification that suggests something about its nature.

In our example, the full path of the chosen classification is Classifications/Unit Type/Quantity/each. This is a classification, not a unit of measure. However, its name suggests that the rollup has something to do with quantities measured in each, which is exactly what it is. The following shows the fields in the Soda Bottles record.

(a) Field List

• Field Name | Field Label | Field Type
• cstDescriptionTX | Description | Text
• cstNameTX | Name | Text
• cstRollupQuantityCR | Quantity | Classification Rollup

The fields in the Soda Containers record are similar. The field involved in the straight roll up is also named RollupQuantity. This field is shown below:

(b) Field Properties

• Section: General
• Field Type: Classification Rollup
• Name: cstRollupQuantityCR
• Label: Quantity
• Description: _____
• Purpose: _____
• Required: []
• Do not Auto Populate: []
• Result Column: []
• Mobile Field: []
• Read Only: [x]
• Rollup Source: Data Entry
• Display Mask: #.####
• Storage Precision: 12
• Rounding Rule: Half Up
• Root Classification: each
• Formula: []
• Threshold Source Attribute

Now suppose that many of the cans and bottles in the collection are brands such as A&W and Diet Coke that are owned by The Coca-Cola Company. In addition to knowing the total number of cans and bottles, we also want to know how many of the cans or bottles are brands that are owned by The Coca-Cola Company.

We have already taken the first step towards doing this. Records created from the Glass Soda Bottle, Plastic Soda Bottle, or the Soda Can business objects have a field named Brand. The Brand field is a Classification field with the root classification of Brands.

Since we already have a way to know the brand of each can and bot­tle, we just need a way to tell if a particular brand belongs to The Coca-Cola Company. One way is to organize the brands so that those that belong to The Coca-Cola Company have a common parent in the Classification hierarchy, as shown below:

(a) Hierarchy of The Coca-Cola Company Brands

• Coca-Cola (Brands)
• A&W (Brands)
• Barq’s (Brands)
• Caffeine-free Barq’s (Brands)
• Caffeine-free Coca-Cola (Brands)
• Caffeine-free Diet Coke (Brands)
• Cherry Coke (Brands)
• Coca-Cola (Brands)
• Coke II (Brands)
• Diet A&W (Brands)
• Diet Barq’s (Brands)
• Diet Cherry Coke (Brands)
• Diet Coke (Brands)

The next steps are as follows:

• Have a field in the Soda Bottles record that contains the total number of bottles in the collection. And another field in the Soda Bottles record that contains the number of bottles in the collection that are a brand owned by The Coca-Cola Company.
• Have a field in the Soda Containers record that contains the total number bottles in the collection. And another field in the Soda Containers record that contains the number of bottles in the collection that are a brand owned by The Coca-Cola Company.

To have a field that contains a total of just cans or bottles that are Coca-Cola brands, we need a Classification Rollup field with the Rollup Source property set to Classification. Because a child record can participate in a straight rollup or a classification rollup but not both, we also need a Classification Rollup field with the Rollup Source property set to Classification for the totals that reflect all brands.

If a Classification Rollup field’s Rollup Source is Classification, it ignores any child records that contain Classification Rollup fields. We need to remove the Classification Rollup field from the Glass Soda Bottle and the Soda Can business objects, and replace the Classification Rollup field named Rollup Quantity with a Number field named Quantity. The example below lists the fields in the Glass Soda Bottle business object after we have done this.

(b) Field List

• Field Name | Field Label | Field Type
• cstBrandCL | Brand | Classification
• cstDescriptionTX | Description | Text
• cstHasTwistOffTopBL | Has Twist-Off Top | Boolean
• cstNameTX | Name | Text
• cstRollupQuantityCR | Quantity | Classification Rollup

We may avoid unnecessary work by having the Classification Rollup fields roll up numbers from the child record’s Quantity rather than getting it directly from a field. This is because in the future we might want to add a different kind of record to the hierarchy that does not have the same fields as the records we are using now. By rolling the numbers up as the child’s Quantity, we can add additional records later that have different fields and not have to spend time changing anything but the new child records.

To make the numbers roll up through the Quantity property of Glass Soda Bottle records, set it up in the business object’s mapping properties, as shown below:

(c) Mapping Properties

• Name: Name [Add][Delete]
• Cost: [Find][+][Find][+][Find][+][Find]
• Quantity: Quantity
• Image
• Conversion Group
• Exchange Date
• Control Number: [] Based on Prefix
• Prefix: [Find][Add][Delete]
• Suffix: [Find][Add][Delete]
• Start With: 1
• Delimiter

To roll up the total number of bottles and the number of Coca-Cola bottles to the Soda Bottles record, the Soda Bottles business object needs two Classification Rollup fields. The following shows the fields in the Soda Bottles business object.

(d) Field List

• Field Name | Field Label | Field Type
• cstCocaColaQuantityCR | Coca-Cola Quantity | Classification Rollup
• cstNameTX | Name | Text
• cstRollupQuantityCR | Quantity | Classification Rollup

The two Classification Rollup fields are named RollupQuantity and CocaColaQuantity. The details of the CocaColaQuantity field are shown below:

(e) Field Properties

• Section: General
• Field Type: Classification Rollup
• Name: cstCocaColaQuantityCR
• Label: Coca-Cola Quantity
• Description: _____
• Purpose: _____
• Required: []
• Do not Auto Populate: []
• Result Column: []
• Mobile Field: []
• Read Only: [x]
• Rollup Source: Classification
• Rollup Type: Quantity
• Display Mask: #.####
• Storage Precision: 12
• Rounding Rule: Half Up
• Root Classification: Coca-Cola
• Formula: []
• Threshold Source Attribute

The details of the Coca-Cola Quantity field most relevant to the rollup are that its Rollup Source property is Classification, its Rollup Type property is Quantity, and its Root Classification is Coca-Cola. When a rollup happens, it will compute the total of the Quantity of all child records that have a value of or under Coca-Cola in a Classification field. Since the Glass Soda Bottle business object only has the Classification field named Brand, only bottles of a brand owned by The Coca-Cola Company will be included in the total.

The details of the RollupQuantity field are shown below:

(f) Field Properties

• Section: General
• Field Type: Classification Rollup
• Name: cstRollupQuantityCR
• Label: Quantity
• Description: _____
• Purpose: _____
• Required: []
• Do not Auto Populate: []
• Result Column: []
• Mobile Field: []
• Read Only: [x]
• Rollup Source: Classification
• Rollup Type: Quantity
• Display Mask: #.####
• Storage Precision: 12
• Rounding Rule: Half Up
• Root Classification: Brands
• Formula: []
• Threshold Source Attribute

The important difference between the Rollup Quantity field and the Coca-Cola Quantity field is that Root Classification is set to Brands. Since this is the root classification for all brands, the Quantity from all child records will be totaled into this field.

The last part of the hierarchy to examine is the Soda Containers record. We want to roll up two sets of numbers into this record: The all-brands total and the Coca-Cola total for soda cans. We also want to roll up similar totals for soda bottles.

Use classification to roll up these totals for cans into the Soda Containers record. This is almost the same thing we did to roll up totals for glass bottles into the Soda Bottles record.

We cannot use classification to roll up the totals for bottles from the Soda Bottles record to the Soda Containers record because in their totaled form the numbers are not connected to a classification. However, we can use a straight rollup to roll up bottle totals from the Soda Bottles record to the Soda Containers record. The only thing to do differently is make the Root Classification of the appropriate Classification Rollup fields in the Soda Containers record be the same as the Root Classification of the corresponding fields in the Soda Bottles record, as shown below:

(g) Field List

• Field Name | Field Label | Field Type
• cstCanCocaColaQuantityCR | Can Coca-Cola Quantity | Classification Rollup
• cstCocaColaQuantityCR | Coca-Cola Quantity | Classification Rollup
• cstNameTX | Name | Text
• cstRollupQuantityCR | Quantity | Classification Rollup

The Can Coca-Cola Quantity field and the Can Quantity field are used to roll up totals for cans. The Coca-Cola Quantity and the Rollup Quantity fields are used to roll up bottle totals from the Soda Bottles record. Below are the details of the Coca-Cola Quantity field:

(h) Field Properties

• Section: General
• Field Type: Classification Rollup
• Name: cstCocaColaQuantityCR
• Label: Coca-Cola Quantity
• Description: _____
• Purpose: _____
• Required: []
• Do not Auto Populate: []
• Result Column: []
• Mobile Field: []
• Read Only: [x]
• Rollup Source: Roll Up
• Display Mask: #.####
• Storage Precision: 12
• Rounding Rule: Half Up
• Root Classification: Coca-Cola
• Formula: []
• Threshold Source Attribute

Notice that the Coca-Cola Quantity field is a straight rollup with its Root Classification set to Coca-Cola. The Root Classification is set to Coca-Cola so that it will match the Coca-Cola Quantity field in the Soda Bottles record. Similarly, the Rollup Quantity field has its Root Classification set to Brands so that it will match the Rollup Quantity field in the Soda Bottles record.