Schedule KPI callout

The Schedule KPI callout can be implemented to use custom logic to calculate the displayed schedule cost in the ASV and in the MR and OTS edit screens. The custom cost overrides the cost calculated by the default cost service, which is displayed the Total Cost field in ASV and in the Details panel in the MR and OTS edit screens.

The callout also allows customers to display up to six custom KPI values, with custom labels, in these screens. Custom KPIs are displayed as new fields in the Key Performance Indicators panel in ASV, and they are displayed in the KPI tab in the MR and OTS edit screens. Different cost calculations and custom KPIs can be defined for the ASV and for the MR and OTS edit screens. The logic defined in the implementation can consider localization, for example, to display different labels to users in different locales. It can also consider security, for example, to display or hide custom KPIs based on the user's security group membership.

Customers implementing this callout create an implementation for KPICalloutService to define the custom cost and KPI calculations. The bean ID for this custom service implementation is specified in the KPI_COST_SVC registry parameter.

Note: Clear the application cache after populating the registry with the callout implementation.

Data objects are sent as inputs to the callout implementation depending on which screen the user is currently using and the currently displayed schedule. This table lists the inputs used when users view schedules in the ASV or MR and OTS edit screens:


Object	Description	ASV	MR and OTS edit screens
`displayRange`	The time period currently being viewed.	Yes	Yes
`currentUser`	Contains this information on the current user that is viewing the schedule: User ID User Name User Locale User Role	Yes	Yes
`teamIds`	The team IDs of the currently selected teams.	Yes	No
`empIds`	The employee IDs of the currently selected employees.	Yes	No
`currentTab`	The current tab that is displayed in ASV.	Yes	No
`filter`	The current filter options selected in ASV.	Yes	No
`displayRotation`	The MR or OTS that is currently being viewed.	No	Yes
`displayMode`	The mode that the MR or OTS is currently being viewed in: SCHEDULE or TEMPLATE.	No	Yes

The custom cost and KPIs are returned by the callout implementation as KPIValue objects. Each instance of this object contains a string pair for the KPI label and value. The custom cost is returned as a single KPIValue object. Custom KPI values are returned as a group of up to six KPIValue objects. Custom KPIs are displayed in the screens in specific positions depending on their position from KPI1 to KPI6. KPI labels or values can be up to 25 characters long before the text is truncated using an ellipses (...) and a tooltip is enabled for users to view the full text.

Note: When returning cost, the label string in the KPIValue object is not displayed in the screens. You can localize the Total Cost field in ASV in Config mode. A label is not displayed for cost in the MR and OTS edit screens.

The default schedule cost service can be retained by returning the cost with the function KPIValueNotImplemented(). Custom KPIs that are not returned as part of the group of KPIs are not displayed on the screens.

To handle expected errors or exceptions, implementations of this callout can return the cost or KPI as KPIValueCalculationFailed(). When this is returned, a red error icon is displayed in the place of the cost value or in the place of the custom KPI label and value. If the callout encounters an unexpected exception, the red error icon is displayed in place of all custom KPIs.

See KPI_COST_SVC.