Generate an Alert from an Orchestration

You can generate alerts based on the analytic output from an orchestration associated with a specific asset.

Configuring Tags for Alert Generation

The following steps represent a typical end-to-end workflow on how APM generates alerts from an analytic orchestration output:

Configure or use an existing Analysis View.
Configure or use an existing Alert Template.
Link an Asset Analysis View to an Alert Template.
Configure and deploy an analytic. Use the Alert Template as the output event.
Configure an Asset Filter for selection in the orchestration.
Add an orchestration. Use the Asset Filter for applicability in the orchestration.
Use the deployed analytic in the Analytic Data Flow in the orchestration.
During I/O Mapping, select and map the new calculated tag.
Create a deployment for the orchestration.
You can run the orchestration using one of three methods:
- On-Demand Run.
- Scheduled Recurrent Runs.
- Event-Based Triggering.

Analytic Orchestartion Generated Events and Alerts

The output of the analytic orchestration is stored in time series with a unique tag name and identifier. The APM alert services supports publishing of common properties and custom properties for output events in an analytic output. These properties are an array of key-value pairs that can be used to supplement the alert information. APM uses these output values to generate alerts, some of which can then be accessed via Alerts and other APM modules.

The following applies to analytic generated alerts:

APM uses the commonProperties in the analytic's ouput alert block for each alert event.
The commonProperties values defined within the event itself, takes precedence over the values defined in the commonProperties block at the root level. The commonProperties key-values generated as part of an analytic input cannot be currently visualized in the Alerts UI.
The template key-value defined within the output event, takes precedence over the ouput event definition in the analytic template.
```
{"date":40000,"score":5.2,"sensors":["S1","S2"],"template":"customAlertTemplate"}
```

The templateSuffix key-value gets appended to the base template.

{"date":50000,"score":10.2,"sensors":["S1","S2"],"templateSuffix":"_High"}

A null override removes the commonProperties from a specific event. A blank override for a key would save an empty string value for that key.

Table 1. Supported Data Types for Alert Generation
Data Source	Data Type
Inputs (for the analytic)	Time series
Constants	For Expression: String For Value: Double
Orchestration Output (single-step orchestration)	JSON Format Time series values as output
APM Alerts	APM Alert objects Based upon alert template configuration in the output event of the analytic template, or the custom alert template specified in the analytic output payload for the event.

When an analytic is deployed, a tagType and tag association is created for each asset if such tagType and tag association does not exist. The tag type name is created using the rule <analytic-name>_<output-name>. The tag association name is created using the rule <asset-source-key>_<analytic-name>_<deploy-cfg-name>_<output-name>.

Pre-Registering Custom Property Keys

For security considerations, prior to passing values as alert attributes via the custom properties of an analytic output, your are required to first register all related keys in custom properties within the specific APM Tenant. This step allows the APM tenant to recognize these keys as valid, and properly pass the key-values to an alert as an attribute, allowing access and visualization in APM Alerts via the grid view. To register key(s) as custom attribute(s) recognizable by APM, follow these steps.

Determine all keys to be registered.
Register all keys per instructions in the API documentation. Select the link below to access the API documentation:
https://apm-alarms-svc-apmprod.int-app.aws-usw02-pr.predix.io/docs#_create_custom_attribute
After you have registered all keys, follow the documentation below, regarding the JSON format and output.

Sample Input JSON (Request to Orchestration Engine)


[        
  {            
    "assetUri": "/assets/ddb90c85-64af-386d-a792-1b8733a63369",            
    "assetSourceKey": "56000",            
    "assetName": "56000",            
    "messageDateTime": 1472755021693,            
    "assetFilterFields": [                
      {                    
        "name": "ENGINE_FAMILY",                    
        "value": [                        
          "CF34"                    
        ],                    
        "dataType": "String",                    
        "priority": 1                
      },                
      {                    
        "name": "ENGINE_TYPE",                    
        "value": [                        
          "CF34"                    
        ],                    
        "dataType": "String",                    
        "priority": 2                
      },                
      {                    
        "name": "AIRCRAFT_FAMILY",                    
        "value": [                        
          "B737"                    
        ],                    
        "dataType": "String",                    
        "priority": 3                
      },                
      {                    
        "name": "AIRCRAFT_TYPE",                    
        "value": [                        
          "B737-800"                    
        ],                    
        "dataType": "String",                    
        "priority": 4                
      },                
      {                    
        "name": "CARRIER_CODE",                    
        "value": [                        
          "DELTA"                    
        ],                    
        "dataType": "String",                    
        "priority": 5                
      }            
    ]        
  }    
]

Alert Outputs

The following example payload represents the alert block of an analytic deployed in the Predix runtime.

{
"alerts":{
"commonProperties":{"prop1":"val1","prop2":"val2"},
"events":[
{"date":10000,"score":2.4,"sensors":["S1","S2"]},
{"date":20000,"score":3.1,"sensors":["S1","S2"]},
{"date":30000,"score":4.2,"sensors":["S1","S2"]},
{"date":40000,"score":5.2,"sensors":["S1","S2"],"template":"customAlertTemplate"},
{"date":50000,"score":10.2,"sensors":["S1","S2"],"templateSuffix":"_High"},
{"date":70000,"score":7.3,"sensors":["S1"],"prop1":"override"}
]
},
"time_series":{
"mean":[20, 30],
"time_stamp":[10000,20000,30000]
}
}

The following example payload is what APM sends to the Alert.

[
{
"name":<Template Name from IO Map>,
"eventStart":10000,
"scanGroupData":{"scores":2.4},
"storageReceiveTime":<Now>,
"severity":<Severity from Template>
"tagsOfInterest":["S1","S2"],
"prop1":"val1",
"prop2":"val2"
},
{
"name":<Template Name from IO Map>,
"eventStart":20000,
"scanGroupData":{"scores":3.1},
"storageReceiveTime":<Now>,
"severity":<Severity from Template>
"tagsOfInterest":["S1","S2"],
"prop1":"val1",
"prop2":"val2"
},
{
"name":<Template Name from IO Map>,
"eventStart":30000,
"scanGroupData":{"scores":4.2},
"storageReceiveTime":<Now>,
"severity":<Severity from Template>
"tagsOfInterest":["S1","S2"],
"prop1":"val1",
"prop2":"val2"
},
{
"name":"customAlertTemplate",
"eventStart":40000,
"scanGroupData":{"scores":5.2},
"storageReceiveTime":<Now>,
"severity":<Severity from customAlertTemplate>
"tagsOfInterest":["S1","S2"],
"prop1":"val1",
"prop2":"val2"
},
{
"name":<Template Name from IO Map>_High,
"eventStart":50000,
"scanGroupData":{"scores":10.2},
"storageReceiveTime":<Now>,
"severity":<Severity from <Template IO Map>_High>
"tagsOfInterest":["S1","S2"],
"prop1":"val1",
"prop2":"val2"
},
{
"name":<Template Name from IO Map>,
"eventStart":70000,
"scanGroupData":{"scores":7.3},
"storageReceiveTime":<Now>,
"severity":<Severity from Template>
"tagsOfInterest":["S1"],
"prop1":"override",
"prop2":"val2"
}
]

Output JSON

 
{    
  "uri": "/schedules/212a49f6-af98-45cf-9403-37511c21f33f",    
  "createdOn": 1480458946415,    
  "updatedOn": 1480465404146,    
  "orchestrationUri": "/orchestrations/578d2b94-3a87-4f2c-904c-5b6d87bb8c08",    
  "assetUri": "/assets/99009f66-67e0-3708-b8d0-75872ec19060",    
  "job": {      
    "id": "8cc7f428-14a4-4eee-9427-c82e8239da80",      
    "name": "Auto1480455130446d1eae08f-7317-4ee0-b0d2-e09c7f8316ea",      
    "description": "/orchestrations/578d2b94-3a87-4f2c-904c-5b6d87bb8c08, 1303e8a5-f81a-4e65-b7ac-abd091459fcc, /assets/99009f66-67e0-3708-b8d0-75872ec19060",      
    "cron": {        
      "seconds": "0",        
      "minutes": "0/7",        
      "hours": "*",        
      "dayOfMonth": "?",        
      "months": "*",        
      "dayOfWeek": "*",        
      "years": "*",        
      "timeZoneId": "UTC"      
    },      
    "state": "Active",      
    "executionRequest": {        
    "url": "https://predix-analytics-execution-release.run.asv-pr.ice.predix.io/api/v2/execution/async",        
    "httpMethod": "POST",        
    "httpHeaders": [          
      {            
        "name": "Content-Type",            
        "value": "application/json"          
      },          
      {            
        "name": "Predix-Zone-Id",            
        "value": "5f3fd009-dd9a-41d1-b7a2-4c34a0931237"          
      }        
    ],        
    "inputData": "{\"orchestrationConfigurationId\":\"1303e8a5-f81a-4e65-b7ac-abd091459fcc\",\"assetId\":\"/assets/99009f66-67e0-3708-b8d0-75872ec19060\",\"dataSource\":[]}"     
  },      
  "createdBy": "cg5t5bm878qhwofouta7r6jgw4o29hmmnp8m",      
  "updatedBy": "cg5t5bm878qhwofouta7r6jgw4o29hmmnp8m",      
  "createdTimestamp": "2016-11-29 22:35:46.39",      
  "updatedTimestamp": "2016-11-29 23:25:34.555"    
  },    
  "historyCheckedTime": 1480465398362,    
  "jobHistory": [      
    {        
      "jobEvent": {          
      "id": "bb3d2947-bdf4-4c69-a502-da8dae5295c4",          
      "jobId": "8cc7f428-14a4-4eee-9427-c82e8239da80",          
      "fireTime": "2016-11-29 22:42:01.49",          
      "scheduledFireTime": "2016-11-29 22:42:00.0",          
      "cron": "0 0/3 * ? * * * ",          
      "timeZoneId": "UTC",          
      "httpMethod": "POST",          
      "url": "https://predix-analytics-execution-release.run.asv-pr.ice.predix.io/api/v2/execution/async",          
      "httpStatusCode": 200,          
      "statusMessage": "completed",          
      "result":
      "{\"orchestrationExecutionStatus\":[{\"assetId\":\"/assets/99009f66-67e0-3708-b8d0-75872ec19060\",\"errorResponse\":null,\"orchestrationStepStatus\":[],\"contextId\":\"09407eb3-5c9e-4592-93c2-5075e2f26fe0-/assets/99009f66-67e0-3708-b8d0-75872ec19060\",\"startTime\":null,\"endTime\":null,\"status\":\"PROCESSING\"}],\"errorResponse\":null,\"orchestrationRequestId\":\"09407eb3-5c9e-4592-93c2-5075e2f26fe0\",\"status\":\"PROCESSING\"}"        
    },        
    "executionOutput": {          
    "executionResult": {            
    "orchestrationRequestId": "09407eb3-5c9e-4592-93c2-5075e2f26fe0",            
    "status": "COMPLETED",            
    "orchestrationExecutionStatus": [              
      {                
        "contextId": "09407eb3-5c9e-4592-93c2-5075e2f26fe0-/assets/99009f66-67e0-3708-b8d0-75872ec19060",                
        "assetId": "/assets/99009f66-67e0-3708-b8d0-75872ec19060",                
        "status": "COMPLETED",                
        "orchestrationStepStatus": [                  
          {                    
            "status": "COMPLETED",                    
            "analyticId": "2038d257-2e98-486c-832d-ca1ae39b6704",                    
            "analyticName": "Auto1480455130446",                    
            "analyticVersion": "1.8",                    
            "analyticRequestId": "0ddbc189-b685-11e6-8552-2ae52e760e7c-sid-c6b1bbb5-deb9-4349-8e13-9a3e82c5bd83",                    
            "stepId": "sid-c6b1bbb5-deb9-4349-8e13-9a3e82c5bd83",                    
            "startTime": 1480459326140,                    
            "endTime": 1480459340250,                    
            "output":
            "{"alerts":{
		"commonProperties":{"prop1":"val1","prop2":"val2"},
		"events":[
		{"date":10000,"score":2.4,"sensors":["S1","S2"]},
		{"date":20000,"score":3.1,"sensors":["S1","S2"]},
		{"date":30000,"score":4.2,"sensors":["S1","S2"]},
		{"date":40000,"score":5.2,"sensors":["S1","S2"],"template":"customAlertTemplate"},
		{"date":50000,"score":10.2,"sensors":["S1","S2"],"templateSuffix":"_High"},
		{"date":70000,"score":7.3,"sensors":["S1"],"prop1":"override"}
		]
		},
		"time_series":{
		"mean":[20, 30],
		"time_stamp":[10000,20000,30000]
		}
		}",                    
            "errorResponse": null                  
          }                
        ],                
        "startTime": 1480459326080,                
        "endTime": 1480459340250,                
        "errorResponse": null              
      }            
    ],            
    "errorResponse": null          
  },          
  "asyncExecuteRequestUri": null,          
  "alertsCreated": true,          
  "resultDeletedFromCache": true,          
  "isAlertsCreated": true        
  },        
  "alertCreateError": null      
}

Accessing Generated Tags

The newly created tag and its output value can be used to automatically generate alerts, which can then be accessed in an Alert Inbox. Alerts are generated based on the criteria configured for inputs, outputs, and constants in the analytic template. To access the generated Alert in the APM user interface, the user must link an Alert Template to the Analytic Template. The APM user will then be able to access the Alert in the user interface for dispositioning and review in other APM areas. Alerts may require several minutes to generate following completion of an analytic orchestration execution. Alerts automatically create an Alert Analysis that can be accessed and modified in Analysis.

Refer to About Alerts and its child topics to address any
alerts.

To Access an Alert Analysis, refer to Accessing an Alert Analysis Chart.

To access the tag in a dashboard, you will need to configure a dashboard, card and widget for the selected asset. Refer to Adding, Modifying, and Deleting Dashboards, Adding and Deleting Cards on a Dashboard, and Adding and Deleting Widgets on a Card. When you configure a selected widget, you can use the newly created tag.

Refer to Configure Widgets and its child topics.

Tip:

You can set up a widget to navigate to another dashboard such as Alerts or Cases, or to Analysis chart.

Refer to Navigating from a Widget or a specific widget under Configure Widgets.