Using Monitor REST APIs

One of the REST interfaces exposed by Monitor is the ability to send in data that, when received, is considered to be an Event. This page provides notes on that topic.

REST requests are simple HTTP requests that carry payload and return response data. REST requests can be sent from any language capable of sending an HTTP request. This includes Java and JavaScript.

The Monitor REST Event catcher

When a client sends a REST Event to Monitor, monitor must "catch" that event and process it. We will call the application that receives the event the "catcher". The catcher is a Java EE application that when it receives the data, forwards that through CEI for normal Monitor processing. The catcher is listening on the URL at the context root of /rest/bpm/events.

The Monitor REST request

The request should be sent to /rest/bpm/events. It must have a MIME type of "text/xml". As of 8.0.1, there appears to be a need to send it to https.

A particularly good free tool for sending REST requests to monitor is "postman". To use this with monitor, the following screen shot shows some sample settings;

The Monitor REST response

The response back from Monitor following a REST request is a JSON string. It contains the following fields:


On an error, the response contains:

Sending a Monitor REST request from Java

In Java, the core class of interest to us is called URL. This class provides the ability to name an HTTP target, send data and receive a response. When sending a secure request, the HTTPS protocol should be used.

String data = "<data to send as the event>"; URL url = new URL("http://localhost:9080/rest/bpm/events"); HttpURLConnection httpUrlConnection = (HttpURLConnection) url.openConnection(); httpUrlConnection.setRequestMethod("POST"); httpUrlConnection.setDoOutput(true); httpUrlConnection.setRequestProperty("content-type", "text/xml"); OutputStreamWriter wr = new OutputStreamWriter(httpUrlConnection.getOutputStream()); wr.write(data); wr.flush(); InputStreamReader inReader = new InputStreamReader(httpUrlConnection.getInputStream()); BufferedReader br = new BufferedReader(inReader); String line = br.readLine(); while (line != null) { System.out.println("Line is: " + line); line = br.readLine(); }

Monitor REST Security

When sending a request to a secure Monitor, authentication must be performed. Adding the following before connecting to the server will achieve this:

String wasUserName = "<WAS Userid>"; String wasPassword = "<WAS Userid Password>"; String authorization = "Basic " + Base64.encode(new String(wasUserName + ":" + wasPassword).getBytes()); httpUrlConnection.setRequestProperty("Authorization", authorization);

If the caller is running in an authenticated context, then an LTPA token can be passed. Adding the following before connecting to the server will achieve this:

Set s = WSSubject.getCallerSubject().getPublicCredentials(WSCredential.class); WSCredential creds = (WSCredential) s.iterator().next(); byte token[] = creds.getCredentialToken(); httpUrlConnection.setRequestProperty("cookie", "LtpaToken=" + Base64.encode(token));

Notes

When sending a request over HTTPS, certificates may need to be exchange. One of the easiest ways to set this up is the following recipe.

First, obtain the Monitor Server certificate using the WAS admin console:

Security > SSL certificate and key management > Key stores and certificates > NodeDefaultKetStore > Personal certificates

To insert the

keytool -import -file ProcCtr.pem -alias ProcCtr -keystore cacerts

The initial password for the Java keystore is "changeit"

REST API Components

Getting models

This API returns a list of monitor models known to Monitor with their version information:

GET /rest/bpm/monitor/models

Example:

[ { "Model ID": "MonitorMonitoringModel", "Versions": [ { "Model Display Name": "MonitorMonitoringModel", "Version": 20140105011802 } ] } ]

Getting monitoring contexts

GET /rest/bpm/monitor/<ModelID>/mcs

Example:

{ "Model ID": "MonitorMonitoringModel", "MC Array": [ { "MCID": "Handle_Order", "MC Display Name": "Handle Order", "Cube Name": "MONITORMONITORINGMODEL_HANDLE_ORDER", "Child MCs": [], "Diagram Exists": false } ] }

Get Metrics

GET /rest/bpm/monitor/<ModelID>/mcs/<MC ID>/metrics

Example:

{ "MCID": "Handle_Order", "Model ID": "MonitorMonitoringModel", "Metric Array": [ { "Metric Sortable": "false", "Metric Type": "DECIMAL", "Metric Name": "amount", "Metric ID": "bmon_f_amount" }, { "Metric Sortable": "false", "Metric Type": "STRING", "Metric Name": "Aux Starting Process Instance ID", "Metric ID": "Aux_Starting_Process_Instance_ID" }, { "Metric Sortable": "true", "Metric Type": "BOOLEAN", "Metric Name": "COMPLETED", "Metric ID": "COMPLETED" }, { "Metric Sortable": "true", "Metric Type": "DATETIME", "Metric Name": "CreationTime", "Metric ID": "CreationTime" }, { "Metric Sortable": "false", "Metric Type": "DATETIME", "Metric Name": "End Time", "Metric ID": "bmon_EndTime" }, { "Metric Sortable": "false", "Metric Type": "STRING", "Metric Name": "Handle Order Instance ID", "Metric ID": "Handle_Order_Instance_ID" }, { "Metric Sortable": "false", "Metric Type": "STRING", "Metric Name": "orderType", "Metric ID": "bmon_f_orderType" }, { "Metric Sortable": "false", "Metric Type": "STRING", "Metric Name": "salesRep", "Metric ID": "bmon_f_salesRep" }, { "Metric Sortable": "false", "Metric Type": "DATETIME", "Metric Name": "Start Time", "Metric ID": "bmon_StartTime" }, { "Metric Sortable": "true", "Metric Type": "DATETIME", "Metric Name": "TerminationTime", "Metric ID": "TerminationTime" } ] }

Get instances

GET /rest/bpm/monitor/<ModelID>/mcs/<MC ID>/metrics

Example:

{ "Record Count": 2, "MCID": "Handle_Order", "Page Size": 10, "Model ID": "MonitorMonitoringModel", "FGSSecurityFilterApplied": false, "Metric ID Array": [ "bmon_f_amount", "bmon_f_amount Localized", "Aux_Starting_Process_Instance_ID", "COMPLETED", "CreationTime", "CreationTime Localized", "bmon_EndTime", "bmon_EndTime Localized", "Handle_Order_Instance_ID", "bmon_f_orderType", "bmon_f_salesRep", "bmon_StartTime", "bmon_StartTime Localized", "TerminationTime", "TerminationTime Localized" ], "Instance Data": [ { "Instance ID": 1, "Version": 20140105011802, "Metric Data": [ 100, "100.00", "8f5aff20-7b1f-4f6b-b30b-fcfea5fef005.2064.f35f2b68-0c54-46e8-bfd4-e07d53a82db.561", true, "2014-01-05T07:28:05", "January 5, 2014 1:28:05 AM", "2014-01-05T07:28:24", "January 5, 2014 1:28:24 AM", "8f5aff20-7b1f-4f6b-b30b-fcfea5fef005.2064.f35f2b68-0c54-46e8-bfd4-e07d53a82db.561", "Red", "cadmin", "2014-01-05T07:28:05", "January 5, 2014 1:28:05 AM", "2014-01-05T07:28:24", "January 5, 2014 1:28:24 AM" ], "Children": [] }, { "Instance ID": 2, "Version": 20140105011802, "Metric Data": [ 200, "200.00", "8f5aff20-7b1f-4f6b-b30b-fcfea5fef005.2064.f35f2b68-0c54-46e8-bfd4-e07d53a82db.562", true, "2014-01-05T07:28:31", "January 5, 2014 1:28:31 AM", "2014-01-05T07:28:43", "January 5, 2014 1:28:43 AM", "8f5aff20-7b1f-4f6b-b30b-fcfea5fef005.2064.f35f2b68-0c54-46e8-bfd4-e07d53a82db.562", "Blue", "kolban", "2014-01-05T07:28:31", "January 5, 2014 1:28:31 AM", "2014-01-05T07:28:43", "January 5, 2014 1:28:43 AM" ], "Children": [] } ], "Page Number": 1, "DisplayFGSIndication": false }

Getting KPI Contexts

GET /rest/bpm/monitor/<ModelID>/version/<Version>/kcs

[ { "Model ID": "MonitorMonitoringModel", "KPI Context Name": "Handle Order", "Version": 20140105011802, "KPI Context ID": "Handle_Order", "Diagram Exists": true } ]

Getting KPI Lists

GET /rest/bpm/monitor/<ModelID>/version/<Version>/kpis

[ { "Aggregated Metric Name": "Amount", "KPI Description": "", "KPI Origin": "runtime", "KPI Display Name": "My KPI", "Enable KPI Prediction": false, "KPI Context ID": null, "Target Localized": null, "Aggregated Metric ID": "bmon_f_amount", "User ID": "uid=admin,o=defaultWIMFileBasedRealm", "KPI Calc Method": "aggregated", "Target": null, "Model ID": "MonitorMonitoringModel", "Aggregated Function": "avg", "KPI Data Type": "decimal", "Calculated KPI Expression": null, "KPI ID": "My_x0020_KPI", "Version": 20140105011802, "KPI Context Name": null, "Version Aggregation": "allVersions", "Enable KPI History": true, "View Access": "personal" } ]

Getting KPI Value

GET /rest/bpm/monitor/<ModelID>/version/<Version>/kpis/value/<KPI ID>

This API retrieves the value of the KPI as well as its definition. The following is an example of what might be returned.

{ "Aggregated Metric MC Name": "Handle Order", "Aggregated Metric Name": "Amount", "Fixed Period End Localized": null, "KPI Display Name": "My KPI", "FGSKpiHistoryTrackingEnabled": null, "Effective End Date": null, "FGSKpiPredictionsEnabled": null, "Rolling Period Quantity": null, "Fixed Period Start": null, "Model ID": "MonitorMonitoringModel", "Aggregated Function": "avg", "Rolling Period Duration": null, "KPI Range Type": "actualValue", "Format Currency": null, "Repeating Period Timezone": null, "Model Display Name": "MonitorMonitoringModel", "Target Localized": null, "Fixed Period Timezone": null, "Time Period Method": null, "Aggregated Metric Type": "DECIMAL", "Aggregated Metric MC ID": "Handle_Order", "Aggregated Metric ID": "bmon_f_amount", "KPI Value Localized": "150", "Target": null, "KPI Value": 150, "KPI ID": "My_x0020_KPI", "Version": 20140105011802, "KPI Context Name": null, "KPI History Defaults": { "History Display Ranges": false, "History Granularity": "daily", "History Rolling Period Quantity": null, "History Repeating Period Basis": "periodInProgress", "History Repeating Period Quantity": 2, "History Timezone": null, "History All Versions": false, "History Time Range Method": "repeatingPeriod", "History Rolling Period Duration": null, "History Repeating Period Duration": "monthly", "History Time Range End": null, "History Time Range Start": null, "History Valid From": null, "History Display Target": false }, "Repeating Period Duration": null, "Time Period Metric ID": null, "View Access": "personal", "KPI Cache Override Interval": null, "KPI Description": "", "KPI History Granularity Options": [ { "KPI History Granularity Supported": [ { "Granularity Value": "hourly" }, { "Granularity Value": "daily" }, { "Granularity Value": "weekly" }, { "Granularity Value": "monthly" }, { "Granularity Value": "quarterly" }, { "Granularity Value": "yearly" } ], "KPI History Granularity Hours": 0, "KPI History Granularity Default": "hourly" }, { "KPI History Granularity Supported": [ { "Granularity Value": "hourly" }, { "Granularity Value": "daily" }, { "Granularity Value": "weekly" }, { "Granularity Value": "monthly" }, { "Granularity Value": "quarterly" }, { "Granularity Value": "yearly" } ], "KPI History Granularity Hours": 48, "KPI History Granularity Default": "daily" }, { "KPI History Granularity Supported": [ { "Granularity Value": "daily" }, { "Granularity Value": "weekly" }, { "Granularity Value": "monthly" }, { "Granularity Value": "quarterly" }, { "Granularity Value": "yearly" } ], "KPI History Granularity Hours": 336, "KPI History Granularity Default": "daily" }, { "KPI History Granularity Supported": [ { "Granularity Value": "daily" }, { "Granularity Value": "weekly" }, { "Granularity Value": "monthly" }, { "Granularity Value": "quarterly" }, { "Granularity Value": "yearly" } ], "KPI History Granularity Hours": 2208, "KPI History Granularity Default": "monthly" }, { "KPI History Granularity Supported": [ { "Granularity Value": "weekly" }, { "Granularity Value": "monthly" }, { "Granularity Value": "quarterly" }, { "Granularity Value": "yearly" } ], "KPI History Granularity Hours": 8784, "KPI History Granularity Default": "monthly" } ], "Effective End Date Localized": null, "Fixed Period End": null, "DisplayFGSIndication": true, "Time Period Metric Name": null, "KPI Data Type": "decimal", "Calculated KPI Expression": null, "Repeating Period Basis": null, "KPI Range Array": [ { "KPI Range Color": "#73bfe5", "KPI Range Start Value": 0, "KPI Range Icon": null, "KPI Range End Value Localized": "100", "KPI Range Display Name": "low", "KPI Range ID": "kpiRangeId###0###1389452567044", "KPI Range End Value": 100, "KPI Range Start Value Localized": "0" }, { "KPI Range Color": "#add9c1", "KPI Range Start Value": 100, "KPI Range Icon": null, "KPI Range End Value Localized": "150", "KPI Range Display Name": "medium", "KPI Range ID": "kpiRangeId###1###1389452573771", "KPI Range End Value": 150, "KPI Range Start Value Localized": "100" }, { "KPI Range Color": "#feb76b", "KPI Range Start Value": 150, "KPI Range Icon": null, "KPI Range End Value Localized": "200", "KPI Range Display Name": "high", "KPI Range ID": "kpiRangeId###2###1389452583442", "KPI Range End Value": 200, "KPI Range Start Value Localized": "150" } ], "Version Aggregation": "allVersions", "Enable KPI History": true, "History Include Predictions": false, "KPI Origin": "runtime", "Format Percentage": false, "Default Prediction Model ID": null, "KPI Metric Filter Array": [], "Format Decimal Precision": null, "KPI Context ID": null, "Enable KPI Prediction": false, "KPI Calc Method": "aggregated", "User ID": "uid=admin,o=defaultWIMFileBasedRealm", "Prediction Model Array": [], "FGSSecurityFilterApplied": false }

As we can see there is a bewildering number of properties returned. Here are some of the most important:

"KPI Value" – The current value of the KPI.

"KPI Range Array" – An array of objects defining the ranges that have been defined. Each object contains:


Creating new KPI definitions

In addition to viewing and listing KPI data, we also have the ability to dynamically create new KPI definitions.

POST /rest/bpm/monitor/models/{model id}/versions/{version}/kpis/config/{kpi id}[?locale={string}][&mode={string}]

The payload of the request contains the details of the definition. The following table is reproduced from the InfoCenter:

|| |Name|Type|Required|Description| |KPI ID|string|Yes*|The key performance indicator (KPI) ID. This value is required for KPI updates. It is not a required field to create a KPI. When a KPI is created, the KPI ID is derived from the KPI Display Name.| |Model ID|string|Yes|The monitor model ID| |Version|number|Yes|The monitor model version| |Locale|string|No|The locale. This value consists of lowercase ISO language code (ISO 639) and the uppercase ISO country code (ISO 3166) joined by an underscore (for example, en_US). Results will be returned in the locale specified. If no locale is specified, the locale of the REST server will be used.| |KPI Context ID|string|No|The key performance indicator (KPI) context ID| |KPI Display Name|string|Yes|The key performance indicator (KPI) display name| |KPI Cache Override Interval|number|No|Time in minutes for the KPI to cache the value. If set, this time interval overrides the KPI Cache Refresh set at the Model/version level on the Admin console. A value of zero indicates that the KPI should not be cached.| |KPI Description|string|No|The key performance indicator (KPI) description| |KPI Origin|string|Yes|The key performance indicator (KPI) origin. Valid values are "modeled" and "runtime"| |KPI Data Type|string|Yes|The key performance indicator (KPI) data type. Valid values are "decimal" and "duration"| |Target|number|No|The key performance indicator (KPI) target value. If the data type is "duration", the target is in milliseconds| |KPI Range Type|string|Yes|The key performance indicator (KPI) range type. Valid values are "actualValue" and "percentage". Percentage indicates a percent of the target, where 100 = 100% of target. Required if KPI Range Array is not empty.| |KPI Calc Method|string|Yes|The key performance indicator (KPI) calculation method. Valid values are "aggregated" and "calculated"| |Aggregated Metric ID|string|Yes*|The ID of the aggregated metric Required if KPI Calc Method is "aggregated". Required if KPI Calc Method is "aggregated".| |Aggregated Metric MC ID|string|Yes*|The ID of the monitoring context of the aggregated metric. Required if KPI Calc Method is "aggregated".| |Aggregated Function|string|Yes*|The aggregated function. Valid values are "avg", "sum", "min", "max", and "count". Required if KPI Calc Method is "aggregated".| |Version Aggregation|string|Yes|The scope of the metric aggregation, whether it is for instances within the same model version as the KPI or for instances across all model versions. Valid values are "singleVersion" and "allVersions". Required if KPI Calc Method is "aggregated".| |Time Period Metric ID|string|Yes*|The ID of metric used for time period qualification. This is a date or datetime metric. Required if KPI Calc Method is "aggregated" and a Time Filter is used.| |Time Period Method|string|Yes*|The time period method. Valid values are "repeatingPeriod", "rollingPeriod", and "fixedPeriod". Required if KPI Calc Method is "aggregated" and a Time Filter is used.| |Repeating Period Duration|string|Yes*|The repeating period duration. Valid values are "yearly", "quarterly", "monthly", and "daily". Required if KPI Calc Method is "aggregated" and Time Period Method is "repeatingPeriod".| |Repeating Period Basis|string|Yes*|The repeating period basis. Valid values are "previousPeriod" and "periodInProgress". For example, for year-to-date, use "periodInProgress". Required if KPI Calc Method is "aggregated" and Time Period Method is "repeatingPeriod".| |Repeating Period Timezone|string|Yes*|The repeating period time zone. This is a Java timezone identifier (for example, America/Los Angeles). Required if KPI Calc Method is "aggregated" and Time Period Method is "repeatingPeriod".| |Rolling Period Duration|string|Yes*|The rolling period duration. Valid values are "years", "months", "days", "hours", and "minutes". Required if KPI Calc Method is "aggregated" and Time Period Method is "rollingPeriod".| |Rolling Period Quantity|number|Yes*|The number of rolling periods. Required if KPI Calc Method is "aggregated" and Time Period Method is "rollingPeriod".| |Fixed Period Start|string|Yes*|The fixed period start time. Valid formats are '2007-01-01' and '2007-01-01T00:00:00' Either Fixed Period Start or Fixed Period End is required if KPI Calc Method is "aggregated" and Time Period Method is "fixedPeriod"| |Fixed Period End|string|Yes*|The fixed period end time. Valid formats are '2007-01-01' and '2007-01-01T00:00:00' Either Fixed Period Start or Fixed Period End is required if KPI Calc Method is "aggregated" and Time Period Method is "fixedPeriod"| |Fixed Period Timezone|string|Yes*|The fixed period time zone. This is a Java timezone identifier (for example, America/Los Angeles). Required if KPI Calc Method is "aggregated" and Time Period Method is "fixedPeriod".| |Calculated KPI Expression|string|Yes*|The calculated key performance indicator (KPI) expression. This must be a valid XPath expression. Other KPIs and UDFs can be referenced. Required if the KPI Calc Method is "calculated".| |User ID|string|No|The user ID of the key performance indicator (KPI) owner| |View Access|string|Yes|The view access, whether the KPI can be viewed by others or not. Valid values are "public" and "personal".| |Format Decimal Precision|number|No|The number of digits that are displayed after the decimal point for numeric KPIs.| |Format Currency|string|No|The currency code to be used for formatting numeric KPIs. This 3-letter code must conform to ISO 4217 standards.| |Format Percentage|boolean|No|The format percentage, whether the KPI will be displayed as a percentage or not. Valid values are "false" and "true".| |Enable KPI History|boolean|No|Flag to indicate if KPI History is enabled. Valid values are true and false . Default value is true .| |History Include Predictions|boolean|No|Flag to indicate if KPI History should include predictions. Valid values are "true" and "false". This parameter is only available for KPI Update. It defaults to "false" upon KPI create.| |KPI History Defaults|array|No|Array to contain KPI history default values. This parameter and all sub-parameters within the array are only available for KPI Update.| |History Time Range Start|string|No|Fixed period start date for retrieving KPI History. Valid formats are '20081201T123000' ,'2008-12-01' and '20081201'.| |History Time Range End|string|No|Fixed period end date for retrieving KPI History. Valid formats are '20081201T123000' ,'2008-12-01' and '20081201'.| |History Repeating Period Quantity|number|No|The number of KPI History periods to retrieve. For a periodInProgress query, the current period would count as 1. It defaults to 2 upon KPI create.| |History Rolling Period Duration|string|No|The rolling period duration. Valid values are "yearly", "quarterly", "weekly", "monthly", and "daily". It defaults to "monthly" upon KPI create.| |History Repeating Period Basis|string|No|The repeating period basis. Valid values are "previousPeriod" and "periodInProgress". For example, for year-to-date, use "periodInProgress". It defaults to "periodInProgress" upon KPI create.| |History All Versions|boolean|No|Flag to indicate if KPI History should include all version of the KPI. This flag must be false if the KPI is a single version KPI. Valid values are "true" and "false". It defaults to "false" upon KPI create.| |History Time Range Method|string|No|The time period method. Valid values are "repeatingPeriod", "rollingPeriod", and "fixedPeriod". It defaults to "repeatingPeriod" upon KPI create.| |History Rolling Period Quantity|number|No|The number of KPI History periods to retrieve.| |History Display Ranges|string|No|Flag to indicate if KPI Ranges should be displayed in the KPI History widget. Valid values are "true" and "false". It defaults to "false" upon KPI create.| |History Granularity|string|No|The value can be yearly, quarterly, monthly, weekly, daily and hourly. It defaults to "daily" upon KPI create.| |History Valid From|string|No|Timestamp used to indicate the earliest date/time that KPI History is valid. For example, this is initially set to the KPI creation date. KPI History would not be valid prior to the creation of the KPI.| |History Timezone|string|No|Timezone used by KPI History. This is a Java timezone identifier (for example, America/Los Angeles). It defaults to the server timezone upon KPI create.| |History Repeating Period Duration|string|No|The repeating period duration. Valid values are "yearly", "quarterly", "weekly", "monthly", and "daily".| |History Display Target|string|No|Flag to indicate if KPI Target should be displayed in the KPI History widget. Valid values are "true" and "false". It defaults to "false" upon KPI create.| |Enable KPI Prediction|Boolean|No|Flag to indicate if KPI Prediction is enabled. Valid values are "true" and "false". This parameter is only available for KPI Update. It defaults to "false" upon KPI create.| |Default Prediction Model ID|string|No|The ID for the default prediction model. This parameter is only available for KPI Update.| |KPI Metric Filter Array|string|No|Array of filters of aggregated key performance indicators (KPIs)| |KPI Metric Filter ID|string|No|The filter ID for each of the metric filters. This value is used if provided. Otherwise, it is automatically generated.| |Filter Metric ID|string|No|The ID of the metric used for filtering| |Filter Operator|string|Yes|The filter operator. Valid values are "equals", "lessThan", "lessThanOrEquals", "greaterThan", "greaterThanOrEquals", "notEquals", "in", "notIn", "isNull", "isNotNull", "like", "notLike".| |Filter Operator Case Sensitive|boolean|Yes|Whether the filter operator is case-sensitive or not when using string-based metric filters. Valid values are "false" and "true".| |Filter Value|string|Yes*|The filter value. For information on the format for each data type, see the section on filtering. Required unless the operators isNull or isNotNull are specified. The filter value can be specified as an array. For example, a string would be represented as ["'Smith'"]. An array of values included with the "in" operator would be represented as ["'Smith'", "'Jones'"]. Note that string values are surrounded by a single quotation marks for the XPath formatting and double quotation marks for the JSON formatting.| |KPI Range Array|array|No|Array to contain any KPI ranges| |KPI Range ID|string|No|The range ID for each of the key performance indicator (KPI) ranges. This value is used if provided. Otherwise, it is automatically generated.| |KPI Range Display Name|string|Yes|The key performance indicator (KPI) range display name| |KPI Range Start Value|number|Yes|The key performance indicator (KPI) range start value. This value can be defined as an actual value or as a percent of a target as defined by KPI Range Type. If KPI Range Type is "percentage", use a value such as 100 to represent 100%. If duration KPI and if KPI Range Type is an "actualValue", then the start value is in milliseconds| |KPI Range End Value|number|Yes|The key performance indicator (KPI) range end value. This value can be defined as an actual value or as a percent of a target as defined by KPI Range Type. If KPI Range Type is "percentage" use a value such as 100 to represent 100%. If duration KPI and if KPI Range Type is an "actualValue", then the end value is in milliseconds| |KPI Range Color|string|No|The display color in key performance indicator (KPI) gauges. Valid values are #000000 - #FFFFFF (omit the # sign)| |KPI Range Icon|string|No|The key performance indicator (KPI) range icon display icon in key performance indicator (KPI) tables, e.g. images/kpi/monitorIcons/IBM_down_red.gif|

This is a lot of data and some additional discussion is needed. Thankfully, all of these parameters can be grouped into sections.

Time Filters

Time filters are used to define which data will be aggregated together to build a KPI. There are four methods of filtering possibilities:


The method of filtering used is store in the "Time Period Method" property. If this property is NOT set then no time filter is assumed. Depending on which method is chosen, other properties come into play:

repeatingPeriod

"Time Period Metric ID"

"Repeating Period Duration"


"Repeating Period Basis"

"Repeating Period Timezone"

rollingPeriod

"Time Period Metric ID"

"Rolling Period Duration"


"Rolling Period Quantity" – a numeric

fixedPeriod


Get Historical KPI data

This REST API can be used to retrieve the historical values of a specific KPI.

GET /rest/bpm/monitor/models/{modelId}/versions/{version}/kpis/history/{kpiId}

An example of the data returned is shown below:

{ "Model ID": "BUSMONMonitoringModel" "Model Display Name": "BUSMONMonitoringModel", "Version": 20140127161149, "KPI Display Name": "A1", "KPI ID": "A1ID", "KPI Data Type": "decimal", "KPI Description": "A1 Desc", "Target": 200.0, "Target Localized": "200.00", "Range Start Timestamp": "2014-01-01T06:00:00", "Range Start Timestamp Localized": null, "Range Start Timestamp In Timezone": "2014-01-01T00:00:00", "Range End Timestamp": "2014-02-19T06:00:00", "Range End Timestamp Localized": null, "Range End Timestamp In Timezone": "2014-02-19T00:00:00", "DisplayFGSIndication": true, "FGSSecurityFilterApplied": false, "KPI Prediction Array": [], "KPI Value Array": [ { "KPI Value Localized": null, "Target": 200.0, "KPI Period Timestamp": "2014-01-02T06:00:00", "KPI Value": null, "KPI Period Timestamp In Timezone": "2014-01-02T00:00:00", "Target Localized": "200.00", "KPI Period Timestamp Localized": "Jan 1, 2014" } … ] "KPI Range Array": [ { "KPI Range Color": "#b22222", "KPI Range Start Value": 0.0, "KPI Range Icon": null, "KPI Range End Value Localized": "100.00", "KPI Range Display Name": "Low", "KPI Range ID": "Low", "KPI Range End Value": 100.0, "KPI Range Start Value Localized": "0.00" }, … ] }

There are other options that can also be supplied. These include:

granularity – This is definition of how many data points within a time range should be returned. The values of this option are:


timerangemethod – This definition determines the range of time over which the history is retrieved. The values of this option are:


For timerrangemethod = rollingPeriod, the following apply:

rollingperiodduration – This defines the duration of a rolling period unit. The choices are one of the following:


rollingperiodquantity – A numeric value defining how "many" of the rollingperiodduration intervals should be included.

For timerangemethod = repeatingPeriod, the following apply:

repeatingperiodbasis – A choice of whether to include or exclude the current period. Choices are one of:

repeatingperiodduration – The repeating period duration. Allowable values are one of:


repeatingperiodquantity – The number of periods to include.

For timerangemethod = fixedPeriod, the following apply:

Get Dashboard Alerts

Monitor maintains a list of alerts to be shown to the user on a dashboard. This API call retrieves that list.

GET /rest/bpm/monitor/alerts/dashboardalerts

The following is an example response:

{ "Record Count": 5, "Page Size": 10, "Dashboard Alert Array": [ { "Creation Timestamp Localized": "February 4, 2014 10:48:09 AM", "Model Display Name": "TestModel", "Model ID": "TestModel", "Status": "Available", "Priority": 3, "Creation Timestamp": "2014-02-04T16:48:09", "Instance ID": "1", "Acknowledged": true, "ID": "508E2F5B25C5AFEA7C4F1AA2", "Context ID": "P1", "Subject": "Hi Amount to Left" }, { …. }], "Page Number": 1 }

Get Alert Subscriptions

GET /rest/bpm/monitor/alerts/subscriptions

Create Alert Definition

POST /rest/bpm/monitor/situation/alerts/config

|| |Model ID|string|The model ID this alert is based on| |Version|number|The version of the model this alert is based on| |Name|string|The display name given by the user| |User ID|string|The owner of this situation. Only users with KPI-Administrator will be allowed to create situations with an owner other then themselves.| |State|string|The state of this situation. Possible states are: inactive, active, invalid.| |Description|string|The display description given by the user| |Subject|string|The subject line of the alert message| |Body|string|The body of the alert message| |GeneratedContent|boolean|This will indicate if the body and subject were system generated, Default is false.| |View Access|number|This will control access to view and subscriptions to this alert. 0 = private, 1 = public, Default is 0 (private).| |TimingInterval|string|Describes the base timing interval, options are:

            • | |TimingStartOffset|string|When TimingInterval MINUTE: intervals will be calculated starting at the specified minutes after the top of the hour.

When TimingInterval HOUR: intervals will be calculated starting at the specified hours and minutes after midnight in the TimingTimeZone property.

When TimingInterval DAY: will be the time of day in the TimingTimeZone property to evaluate the conditions.

When TimingInterval WEEK: will be the time of day and the day of the week in the TimingTimeZone property to evaluate the conditions.

When TimingInterval MONTH: will be the time of day and the day of the month in the TimingTimeZone property to evaluate the conditions.

When TimingInterval PERIOD: does not offset the evaluation time, the end of period time must be honored| |TimingMultiple|number|Describes a multiple of the base timing interval, optional will default to one.

When TimingInterval MINUTE: the number of minutes in the interval. (only allow even factors of the hour, 1, 2,3, 4, 5, 6, 10, 12, 15, 20 ,30 )

When TimingInterval HOUR: the number of hours in the interval (only allow even factors of the day, 1, 2, 3, 4, 6, 8, 12 )

When TimingInterval DAY: the number of days in the interval (allow 1 to 365).

When TimingInterval WEEK: the number of weeks in the interval (allow up to 52)

When TimingInterval MONTH: the number of months (allow up to 12).

When TimingInterval PERIOD: TimingMultiple property is not used.| |TimingRepeat|string|When the conditions will be allowed to send an alert.

REPEATING = whenever the condition evaluates to true

NONREPEATING = when the condition evaluates to true and not again until the condition evaluates to false

ONCEINPERIOD = when the condition evaluates to true and not again until the next KPI period| |TimingKPI|string|Describes the ID of the KPI to use for the period time evaluations, required when TimingRepeat=ONCEINPERIOD and TimingInterval=PERIOD.| |TimingTimeZone|string|Describes the Timezone to use in calculating the actual start time and next evaluation times, must use the JAVA based time zone strings, Optional, will use the server time zone.| |TriggerArray|array|Describes a conditional trigger. All triggers will be 'anded' together to determine if the situation will fire. Each trigger is described as an array item of the following properties.| |CheckKPI|string|Indicates which KPI should be used in this evaluation| |CheckPrediction|string|Indicates which Prediction KPI to be used in this evaluation| |CheckPredictionType|string|Indicates which Prediction KPI type to be used in this evaluation.

Types are:

end: for the end of the prediction period,

any: for any value within the prediction set| |CheckCondition|string|Indicates which type of condition to use. The operations will be done using the check KPI and the check field.| |CheckFieldType|string|Indicates what type of field will to be compared against the KPI.| |CheckField|string|Indicates actual value or where to get the value to use in the evaluation.

When CheckFieldType is 'value' check field will be the actual value to use.

When CheckFieldType is 'target' check field will be ignored."

When CheckFieldType is 'range' check field will be the name of the KPI range.| |Alert Subscription Array|array|Describes subscribers to this situation. Each subscription is describe as an array item of the following setting.| |User ID|string|The user who is subscribed to this alert| |E-mail|string|The alert format is E-mail| |Dashboard|boolean|The alert format is Dashboard| |Cell|boolean|The alert format is Cell| |Pager|boolean|The alert format is Pager|

Useful Monitor/REST JavaScript

Here are some useful JavaScript fragments for working with monitor data in the context of a JavaScript environment that is likely to be found within Web Browsers or Business Space Widgets.

Building a map of Instance data

The instance data returned by REST calls is an array format and not a "map". On occasion, map formatted data is better to work with. This JavaScript function will take a REST returned instances object and produce an Array of objects where each object is a map of name->value of instance metrics:

/** * Given an instances object retrieved from monitor, build a map of the data * * @param instancesObject An object returned from a REST query against Monitor * @returns An array of instance objects */ function buildInstanceMap(instancesObject) { var retArray = new Array(); // Iterate over each instance for (var i in instancesObject["Instance Data"]) { var currentInstance = new Object(); // Iterate over each metric in the instance for (var m in instancesObject["Metric ID Array"]) { var metricName = instancesObject["Metric ID Array"][m]; currentInstance[metricName] = instancesObject["Instance Data"][i]["Metric Data"][m]; } retArray.push(currentInstance); } return retArray; }

Page 26

No Comments
Back to top