Analytics Developer Reference

About Analytics Developer Documentation

GE Digital APM includes some developer documentation to bridge the gap between Predix platform documentation and GE Digital APM user documentation.

Developer documentation included here:

  • Clarifies preparation work for privileged users.
  • Adds information and procedures for back-end functionality.
  • Provides reference material for developers when configuring tenant provisioning.
  • Provides reference material for developers when using GE Digital APM APIs.

Sample Data Map for Analytic Template Definition

The data map shows the correlation between the analytic template definition in the user interface and the analytic inputs and outputs.

At least one input is required. An analytic can optionally define outputs, events, or both. Inputs, outputs, and constants in the analytic template definition must match the input parameters, output parameters, and constants specified in the developed analytic to enable its successful deployment.

Template input definitions and constants correlate with the JSON body of inputs:

The analytic must follow the JSON contract prescribed by the respective runtime environment and language for succesfully running the analytic and generating the output. Template output definitions and constants correlate with the JSON body of outputs:



Output events in the analytic template definition map to an existing alert template or the alert template provided as part of the template definition:



Config.json information for developing analytics can be found in the sub-topics in the related link below.

Analytic Definition Files

You can create .csv files containing the relevant inputs, constants, and outputs for your analytic instead of entering them manually in the analytic template. To do this, you must save a copy of the .csv template and add the appropriate definitions before uploading it to the analytic template. If you upload a file with the wrong format or incorrect values, a dialog box displaying the invalid entries appears, and the file is not loaded. You can fix the indicated errors, and retry.
Tip: You can use the apm-analytic-csv-generator found on GitHub if you have access. You can request access from your support team. The .csv generator parses a sample .json analytic input file and writes out input and constant .csv files.

Define Analytic Input CSV

Before You Begin

You have created an analytic in the analytic catalog.

About This Task

Use this procedure if you want to configure multiple inputs through .csv upload. You can skip this procedure if you want to add inputs directly through the UI.

Configure the template to specify input tags for the analytic you are adding or have added to the analytic catalog. This information is needed to run the analytic.

Procedure
  1. In the Analytic Template section, select in the Input Definitionsubsection to download a copy of the .csv template and save it locally.
  2. Rename the file with a name related to the analytic.
    For example, rename the AnalyticInputDefTemplate.csv file as AnalyticInputDef_data_wind_trend.csv and save it locally.
  3. Open the saved file in a CSV editor.
  4. Verify that the template matches the following definition guidelines. They can be defined in spreadsheet columns or as comma-separated values.
    Table 1. Input Definition Guidelines
    This definitionUses this guideline
    NameA valid tag name that matches the analytic input parameter. It must match the regular expression pattern ^[A-Za-z0-9-_]+$.
    DescriptionThe tag description. If there is no description for the tag, define blank entries as empty table cells, or offset them in a comma-delimited set (, ,).
    UnitsThe engineering unit that matches the engineering unit name in the conversion database.
    Data TypeThe value must be one of the following data types:
    • STRING
      Note: You must select string data type for data of type string, character, enum, or grid.
    • INTEGER
    • DOUBLE
    • BOOLEAN
    Data FormatThe format of the data being retrieved or written as part of the analytics computation logic. The two acceptable values are Asset Attributes and APM Timeseries.
    Entity TypeThe mapping level in the asset business hierarchy. During the I/O mapping step in deployment, the mapping level tells Application Analytics to retrieve the tags and attributes of all assets and their children starting at the defined Entity Type. For example, if you configure the Entity Type for your analytic input at the Site level, then all tags and attributes of the Site and its children become available for mapping during deployment.
    RequiredThe value must be checked or unchecked. This indicates whether the input is required.
  5. Make any required modifications and save the file.
What To Do Next
Upload the template to the new analytic created in the catalog.

Define Analytic Constants CSV

Before You Begin

You have created an analytic in the analytic catalog.

About This Task

Use this procedure if you want to configure multiple constants through .csv upload. You can skip this procedure if you want to add constants on the UI.

Configure the template to specify constants for the analytics you are adding or have added to the analytic catalog. This information is needed to run the analytics.

Procedure
  1. In the Analytic Template section, select in the Constantssubsection to download a copy of the .csv template and save it locally.
  2. Rename the file with a name related to the analytic.
    For example, rename the AnalyticConstantsTemplate.csv file as AnalyticConstantsTemplate_data_wind_trend.csv and save it locally.
  3. Open the saved file in a CSV editor.
  4. Verify that the template matches the following definition guidelines. They can be defined in spreadsheet columns or as comma-separated values.
    Table 2. Constants Guidelines
    This definitionUses this guideline
    NameA valid tag name must match the analytic constant parameter. It must match the regular expression pattern ^[A-Za-z0-9-_]+$.
    DescriptionThe tag description or null. If there is no description for the tag, define blank entries as empty table cells, or offset them in a comma-delimited set (, ,).
    UnitsThe engineering unit that matches the engineering unit name in the conversion database.
    Data TypeThe value must be one of the following data types:
    • STRING
    • INTEGER
    • DOUBLE
    • BOOLEAN
    Data FormatThe format of the data being retrieved or written as part of the analytics computation logic. The two acceptable values are Asset Attributes and APM Timeseries.
    Entity TypeThe mapping level in the asset business hierarchy. During the I/O mapping step in deployment, the mapping level tells Application Analytics to retrieve the attributes of all assets and their children starting at the defined Entity Type. For example, if you configure the Entity Type for your analytic constant at the Site level, then all attributes of the Site and its children become available for mapping during deployment.
    Value (optional)If there is no default value, you must define blank entries as empty table cells or offset them in a comma-delimited set (, , ).
  5. Make any required modifications and save the file.
What To Do Next
Upload the template to the new analytic created in the catalog.

Define Analytic Output CSV

Before You Begin
You have created an analytic in the analytic catalog.
About This Task

Use this procedure if you want to configure multiple outputs through .csv upload. You can skip this procedure if you want to add outputs on the UI.

Configure the template to specify output tags for the analytic you are adding or have added to the analytic catalog. This information is needed to run the analytic.

Procedure
  1. In the Analytic Template section, select in the Outputssubsection to download a copy of the .csv template and save it locally.
  2. Rename the file with a name related to the analytic.
    For example, rename the output-def.csv file as output-def_data_wind_trend.csv and save it locally.
  3. Open the saved file in a CSV editor.
  4. Verify that the template matches the following definition guidelines. They can be defined in spreadsheet columns or as comma-separated values. Make sure your outputs match your analytic definition.
    Table 3. Outputs Definition Guidelines
    This definitionUses this guideline
    NameA valid tag name that matches the analytic constant parameter. It must match the regular expression pattern ^[A-Za-z0-9-_]+$.
    DescriptionThe tag description or null. If there is no description for the tag, define blank entries as empty table cells, or offset them in a comma-delimited set (, ,).
    UnitsThe engineering unit that matches the engineering unit name in the conversion database.
    Data TypeThe value must be one of the following data types:
    • STRING
    • INTEGER
    • DOUBLE
    • BOOLEAN
    Data FormatThe format of the data being retrieved or written as part of the analytics computation logic. The two acceptable values are Asset Attributes and APM Timeseries.
    Entity TypeThe mapping level in the asset business hierarchy. During the I/O mapping step in deployment, the mapping level tells Application Analytics to retrieve the tags and attributes of all assets and their children starting at the defined Entity Type. For example, if you configure the Entity Type for your analytic output at the Segment level, then all tags and attributes of the Segments and its children become available for mapping during deployment.
  5. Make any required modifications and save the file.
What To Do Next
Upload the template to the new analytic created in the catalog.

Generate an Alert from an Orchestration

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

Configure Tags for Alert Generation

The following steps represent a typical end-to-end workflow of how the system generates alerts from an analytic orchestration output:
  1. Configure or use an existing Analysis View.
  2. Configure or use an existing Alert Template.
  3. Link an Asset Analysis View to an Alert Template.
  4. Configure and deploy an analytic. Use the Alert Template as the output event.
  5. Configure an Asset Filter for selection in the orchestration.
  6. Add an orchestration. Use the Asset Filter for applicability in the orchestration.
  7. Use the deployed analytic in the Analytic Data Flow in the orchestration.
  8. During I/O Mapping, select and map the new calculated tag.
  9. Create a deployment for the orchestration.
  10. You can run the orchestration using one of three methods:
    • On-Demand Run.
    • Scheduled Recurrent Runs.
    • Event-Based Triggering.

      Refer to Scheduling an Orchestration and Event-Based Triggering of an Analytic Execution Using an External Packet (Data Set).

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 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. GE Digital APM uses these output values to generate alerts, some of which can then be accessed via Alerts and other modules.

The following applies to analytic generated alerts:

  • GE Digital 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 4. Supported Data Types for Alert Generation
Data SourceData 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
GE Digital APM Alerts
  • GE Digital 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 tenant. This step allows the tenant to recognize these keys as valid, and properly pass the key-values to an alert as an attribute, allowing access and visualization in GE Digital APM Alerts via the grid view. To register key(s) as custom attribute(s) recognizable by GE Digital APM, follow these steps.

  1. Determine all keys to be registered.
  2. Register all keys per instructions in the API documentation. Select the link below to access the API documentation:

    https://apm-apidocs-preprod.preprod-app-api.aws-usw02-pr.predix.io/alarms/#_create_custom_attribute

  3. 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 the system 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 user interface, the user must link an Alert Template to the Analytic Template. The user will then be able to access the Alert in the user interface for dispositioning and review in other 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.

Event-Based Triggering of an Analytic Execution Using an External Packet (Data Set)

You can implement a REST API to trigger orchestration runs from external data packets.

Use the following REST API to retrieve external data packets, trigger orchestrations, and then process the analytic output data.

One or more data sets that are stored in an external system are provided to the system for processing. This event allows you to trigger an analytic orchestration execution. The system processes each data packet in the order in which it is received.

During processing, the resolveAndExecute API gathers and uses data from the external data packet, and Asset and Time-Series data stores. The orchestrationExecution API is triggered and an output is achieved. The output may be used elsewhere in GE Digital APM.

You will need the following REST APIs:
Table 5. REST APIs
APIDescription
resolveAndExecute and orchestrationExecution
  • Retrieves the initial data packet.
  • Initiates data gathering for Asset and Time-Series.
  • Resolves and matches the appropriate orchestration to execute for the asset or asset groups associated with the data packet. The resolveAndExecute API calls the orchestrationExecution API to trigger execution of the orchestrations appropriate for the event (receipt of data packet).
  • Manages all orchestration execution activity, including output.
Note: For more information regarding use of this API, see the AsciiDoc set (https://apm-apidocs-rc.run.asv-pr.ice.predix.io/).
Table 6. Supported Data Types for GE Digital APM Processing and Orchestration Execution
Data SourceData Type
External Data PacketString
Asset DataString
Inputs for Analytics/OrchestrationsTime-Series
Outputs for Analytics/OrchestrationsTime-Series
Constants for Analytics/OrchestrationsNumeric
Orchestration OutputTime-Series

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>.

Before You Begin

Make sure you have done the following:

  • Set up an Analytic Template.
  • Set up an Alert Template.
  • Created an analytic that the orchestration can use.
  • The APIs can access and read the data from the selected data store.
  • An external source containing the data packets for GE Digital APM to use is available. This source can consist of a Postgres table, message queue, or another type that can serve to provide data for packets.

The data packets must have the following JSON structure:

 [  
  {      
    "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                
      }            
    ]        
  }    
]

Prepare and Load the Data

You will need to configure at least three data stores to use with the GE Digital APM analytics event-based triggering;
  • GE Digital APM Asset - to load the asset-related data.
  • GE Digital APM Time-Series - to load the assets time-series related data.
  • External data store - to store data packets, or events, which are utilized to initiate analytic orchestration execution.
  1. Load asset related data to the GE Digital APM Asset data store in your tenant.
  2. Load time-series data (tags) to the GE Digital APM Time-Series data store.
  3. Configure a data store outside of GE Digital APM to store external data packets.

The individual data packets are considered the events which are utilized to initiate analytic orchestration execution. APIs use this external data as the criteria for matching the appropriate Asset and Time-Series data in GE Digital APM for analytic orchestration execution.

Initiate GE Digital APM Processing

To initiate processing, call the resolveAndExecute API for each data packet. This will retrieve data packets available in the external queue, then access data from the data packet.

After you have uploaded and configured all of the individual Analytics called by the resolveAnd Execute API, the system does the following:
  1. Extract the appropriate Asset data from the report.
  2. Link and extract the appropriate Asset, Tag, and Time-Series data from GE Digital APM using existing data in GE Digital APM Asset and Time-Series.
  3. Retrieve the appropriate Inputs, Outputs, and Constants for the Orchestration to be executed.

The resolveAndExecute API passes this data to the execution function of GE Digital APM Analytics (orchestrationExecution API) to initiate execution of the analytic and related orchestrations. Analytics are passed to orchestrationExecution one-by-one and are executed individually.

The JSON output of the orchestration is an output “object” containing the status and results of the orchestration.

The specific output of an analytic is a Time-Series data point.

Sample Response from Orchestration Engine

 
[       
  {            
    "assetUri": "/assets/6995a24b-937a-30de-be36-e071a426c13d",            
    "assetSourceKey": "56001",            
    "assetName": "56001",            
    "messageDateTime": 1474504115555,            
    "executionOutputs": [                
      {                    
        "executionResult": {   
          "orchestrationRequestId": "3869f0ae-f81d-45b7-a70a-6db8b280c742",
          "status": "PROCESSING",                        
          "orchestrationExecutionStatus":[                            
            {                                
              "contextId": "3869f0ae-f81d-45b7-a70a-6db8b280c742-/assets/6995a24b-937a-30de-be36-e071a426c13d",                                
              "assetId": "/assets/6995a24b-937a-30de-be36-e071a426c13d",
              "status": "PROCESSING",                                
              "orchestrationStepStatus":[],                                
              "startTime": null,                                
              "endTime": null,                                
              "errorResponse": null                            
            }                        
          ],                        
          "errorResponse": null                    
        },                    
        "alertsCreated": false,                    
        "resultDeletedFromCache": false,                    
        "isAlertsCreated": false                
      }, {                    
        "executionResult": {                        
          "orchestrationRequestId": "d0475114-8969-4f81-8bbf-ecca7926b89e",
          "status": "PROCESSING",                        
          "orchestrationExecutionStatus": [                            
            {     
              "contextId": "d0475114-8969-4f81-8bbf-ecca7926b89e-/assets/6995a24b-937a-30de-be36-e071a426c13d",                                
              "assetId": "/assets/6995a24b-937a-30de-be36-e071a426c13d",                                
              "status": "PROCESSING",                                
              "orchestrationStepStatus":[],                                
              "startTime": null,                                
              "endTime": null,                                
              "errorResponse": null                            
            }                        
          ],                        
          "errorResponse": null                    
        },                    
        "alertsCreated": false,                    
        "resultDeletedFromCache": false,                    
        "isAlertsCreated": false                
      }            
    ]       
  }   
]

Use of Output in GE Digital APM

The specific output of an analytic is a Time-Series data point. Time-Series data points can be used in other areas of GE Digital APM, such as Analysis.

Use the specified tag in the GE Digital APM application to view the value. For instance, you can create a chart in Analysis, or configure a widget in Dashboards.

Alerts can be generated if the results generated meet the criteria configured in the Analytic Template to produce an alert. An alert with the Alert Template name is available in the Templates module.
Note:
  • Refer to Adding and Deleting an Asset Analysis View in the Help documentation to set up an Analytic Template.
  • Refer to Creating, Configuring and Deleting an Alert Template and Adding and Removing Analysis View in an Alert Template in the Help documentation to set up an Alert Template.

Status and Error Notifications

In passing Analytics to the orchestrationExecution API, you can track the status of orchestration execution using two mechanisms:
Sync mode
The output object from the analytic provides a final response to the orchestration execution (Pass, Fail). Use the asciidoc for orchestrationExecution to configure for Sync mode.
Async mode
You will receive a request ID to monitor the status of orchestration execution using the output object. Then you receive the status of each step in the orchestration using the object to monitor the request. An API can be used to pass the request ID to the system for status. Use the asciidoc for orchestrationExecution to configure for Async mode.