Concepts

Tasks

Settings

Creating 4D Calculation Inputs Based on Other Reading Data

You can include data other than indicator readings as an input to a calculation. For example, you might want to use an indicator reading’s collection date in a calculation so that you can determine the length of time that has elapsed between two readings.

Note: Users who want to use inputs other than indicator readings as calculation inputs should have a basic understanding of object-oriented modeling concepts, as well as knowledge of the APM object model as it relates to indicator readings.

If your input is based on an indicator reading, you can select any eligible attribute (field) on the Indicator Reading class itself or on any class that is related to it through a single-cardinality relationship. For example, you could select an attribute on the asset that owns the indicator. You can select attributes from classes related through a single-cardinality relationship:

•	References one

•

Scoped by

•

Owned by

•

Contains

•	Hierarchical parent

The following graphic illustrates examples of classes related to the indicator reading class:

Similarly, for filter-type inputs, you can select any eligible attribute from the class you are filtering or from any class related to it through a single-cardinality relationship.

Eligible attributes on which inputs can be based are:

Numeric Attributes	Non-Numeric Attributes
Floats	Booleans
Integers	Dates
Quantities	Date and times
Durations	Enumerated types
Prices	Object IDs
Currency amounts	Strings
Base currency amounts	Times

For more information about relationships and attributes, see Relationship Types, and Data Types.

To learn more about the APM object model, see Object Model Overview.

This topic explains how to create an indicator reading-based calculation input that uses data other than the indicator reading value. To create a regular indicator reading-based input, see Creating 4D Calculation Inputs Based on Indicator Readings.

To Create a Calculation Input

1.	Open the calculated or performance indicator to which you need to add inputs.

2.	Make sure that editing is enabled.

3.	Select the Calculation tab. This tab shows the formula to be used for the indicator and any existing calculation inputs.

4.	To create a calculation input based on an indicator, click New. The Calculation Input dialog appears. For example:

5.	In the Input name box, type the name of the corresponding variable in your calculation, for example, “Input1”.

6.	In the Description box, enter a detailed description of the indicator this variable represents.

7.	Select the indicator to use with one of these two methods:

•	Beside the Asset number box, click the browse icon. The Asset Selector dialog appears. Select the asset that owns the indicator and click OK.

Select an indicator from the Indicator to use list, which contains the selected asset’s 4D indicators.

•	Click Browse to filter a table of the site’s indicators. Select the indicator to use and click OK.

8.	Select an option in the Number of readings to use area:

Readings to Use

Select one of the following options: • Use the last reading only: The value of the indicator’s most recent reading is used in the calculation. • Include the last [n] readings: This setting allows you to indicate the specific number of readings that you want to include to derive the input’s value (for example, use the last 10 readings). • Readings collected: This setting allows you to specify a moving time period from which all of the readings entered will be used to derive the input’s value (for example, readings collected this month, this week, in the last 10 days, and so on) The possible choices are: • In the last... With this choice you must also enter a duration (for example, in the last six months). • Last month • Last week • Last year • This month • This week • This year • Today • Yesterday

9.	Select the Attribute Info tab.

On this tab you can select the data that you want to use for the input. The Aggregation type options are available when more than one reading is involved.

10.	Select the attribute to use to derive the value for the input:

Setting Name

Description

Relationship from

If you want the input value to be based on an attribute that does not belong directly to the Indicator Reading class but to a class that is related to it, you can identify the relationship to the other class in this box. The relationship is specified using a join-path. Click in the Relationship from box. The Select Join Path dialog appears. Select the class in the hierarchy that owns the attribute you want to use and click OK. For example, to pick an attribute from the Asset that owns the indicator, open the Indicator to Read class and then select Asset. The attributes for the selected class now appear in the Attribute list. You can select any relationship with a cardinality of one. This includes the following relationship types only: • References one • Scoped by • Owned by • Hierarchy parent • Contains

Attribute belongs to

The name of the object (class) that owns the selected attribute. By default, this will be the object on which the calculation input is based (for filter-based inputs), or the Indicator Reading or Indicator State classes (for reading-based inputs). If you have selected a relationship to another object, the name of that object will appear in the box. You cannot directly change the object listed in the box.

Attribute to use

Select the attribute for the input. By default, the list will contain all eligible attributes owned directly by the object (class) on which this input is based. To select an attribute from another class, you must first select another class using a join path in the Relationship from box.

Allow Null Value

By default, the system stops the calculation and displays a warning message if the input’s value is null (no value). Select this option to allow the system to complete the calculation even if this input returns a null value. For example, an input might be null when: • The input is from an indicator that has no readings • The input is from an attribute that has no data Note: You can tell the system to allow null values on individual calculation inputs. If you select to allow a null value in a calculation, you might want to account for this possibility in the VB.NET or C# script in your calculation.

Unit of measure to use

If the data type of the selected attribute is a duration, quantity or price, the attribute’s value for each instance that meets the selection criteria may be expressed in a different unit of measure. For this reason, you will need to select the unit of measure in which to express the resultant value.

Currency to use

If the data type of the selected attribute is a currency or price, the attribute’s value for each instance that meets the selection criteria may be expressed in a different currency. For this reason, you must select the currency to use for the resultant value.

11.	If you are using data from multiple indicator readings, select the aggregation type that you want to use:

Aggregation Type

Select one of the following options to determine how the system will define a value for the input: The supported aggregation types are: • Sum returns the total value for all the readings or objects selected • Average returns the average value for all the readings or objects selected • Median returns the median value for the selected readings or objects • Minimum returns the lowest value among all the readings or objects selected • Maximum returns the largest value among all the readings or objects selected • Difference returns the difference between the first and the last reading in a range of readings. (Only available for inputs based on indicator readings.) • Array returns lists of values. Typically used for inputs based on non-numeric data such as strings and dates. You can use VB.NET or C# scripting to work with the individual elements in the array. Note: The array aggregation type is not supported for indicators that are calculated using a stored procedure. • First returns the first element in a list • Last returns the last element in a list

12.	If you are using the Array, First, or Last aggregation types, select the Sorting Info tab.

13.	On this tab, you can select the order in which the data is ordered.

Setting Name

Description

Relationship from

If you are using the array, first, or last aggregation types, you can use an attribute to sort the array. If you want to sort the list by an attribute that belongs to a related class, you can specify the join-path for the relationship here. Click in the Relationship from box. The Select Join Path dialog appears. Select the class in the hierarchy that owns the attribute you want to use and click OK. You can select any relationship with a cardinality of one. This includes the following relationship types only: • References one • Scoped by • Owned by • Hierarchy parent • Contains

Attribute belongs to

The name of the object (class) that owns the selected attribute. If you have selected a relationship to another object, the name of that object will appear in the box. You cannot directly change the object listed in the box.

Attribute to use for ordering

Identify the attribute that you want to use to sort the elements in the array. The elements are always sorted in ascending sequence. For example, if you're sorting based on a date field, the first element in the array will have the earliest date and the last element will have the latest date.

14.	Select the Test Value tab. For example:

Setting Name

Description

Test Value

Enter the value(s) that you want to use to test the calculation. Choose a value that makes it easy for you to verify that the calculation works correctly. You must enter a value in the same data type that is expected from the calculation input. For example: • Input is from a numeric indicator reading: Enter a number • Input is an array: Enter the expected number of values in the array. That is, if you expect five values, you must enter five test values. Each value must be separated by a semicolon. For example: January 1, 2004;January 2, 2004;January 3, 2004;January 4, 2004;January 5 2004 You can test the calculation by clicking the Check (Test) button on the Calculation tab of the Indicator window. Note: If you do not enter a test value or the correct number of test values for an array, the system displays a warning message when you save the indicator.

15.	When you are finished entering information for the input, click OK.