Alert Ingestion

About Alert Ingestion

Alert ingestion requires that you create an alert profile and ingest one or more assets before you ingest alerts into Predix Essentials.

Ingest Alerts

You must first create at least one alert profile and ingest one or more assets before you ingest alerts into Predix Essentials.

Before You Begin

Before ingesting alerts, you need the following information:

Ingestion payload for alerts in JSON format.
OAuth token to ingest alerts.
Important: Make sure you have a valid unexpired token. Tokens are client-specific and usually expire within a set time.
From the Setup section, obtain the following information:
- Client ID
- Alert ingestion URL
- Username
Ingestion password that was created during initial tenant setup.
Access to a REST client such as Postman or Advanced REST client.

About This Task

You can use the alerts REST service endpoint to perform bulk alert ingestion from your source system.

Procedure

Open your REST client.
Enter the ingestion URL in the HOST value field.

Note: You can obtain this from the Tenant Setup section – Alerts ingestion URL by logging in as a tenant admin. For example, https://apm-event-ingestor-alerts-svc-preprod.preprod-app-api.aws-usw02-pr.predix.io/v1/jobs/
Select the POST method.

In Headers, add the following parameters (key-value pairs).

Table 1. Asset Ingestion Service Headers
Parameter	Description
Authorization	Enter the token_type followed by a space, then the access_token from the response you previously obtained. For example, `bearer eyJhbGciOiJSUzI1NiJ9.A...` The following code sample includes a bearer token: `{ "access_token": "eyJhbGciOiJSUzI1NiJ9.A...", "token_type": "bearer", "refresh_token": "eyJhbGciOiJSUzI1NiJ9.e..", "expires_in": 86399, "scope": "openid", "jti": "5e2c90ea-9edd-4da1-80c8-4a0d67f77ef3" }`
tenant	The unique ID for the tenant (for example, `07F28C049E0F4F29B8E85E4A6C916D7F`)

Select application/json as Content-Type .

Paste the JSON payload into the request body.

Sample JSON payload:

{
  "taskList" : [ {
    "taskId" : "smartSignalTask",
    "type" : "createAlarm",
    "body" : {
      "name" : "alert-Length-70A701E8F0594532AB102F2A6FE0BAD7",
      "associatedMonitoredEntitySourceKey" : "Inverter1-ASSET-TYPE1",
      "eventStart" : 1446632335938,
      "storageReceiveTime" : 1446632335938,
      "severity" : 3,
      "incident" : {
        "incidentEventCount" : "125",
        "firstOccurance" : "2015-08-11T19:07",
        "lastOccurance" : "2015-08-19T15:47"
      },
      "scanGroupData" : {
        "BRG_1_VIB_2_1X_AMP" : "53.95484042",
        "BRG_1_VIB_1_OVERALL" : "62.4367112",
        "BRG_1_VIB_2_OVERALL" : "57.80885233",
        "BRG_1_VIB_2_1X_PHASE" : "305.013721",
        "BRG_1_VIB_1_1X_AMP" : "59.19077386"
      },
      "tagsOfInterest" : [ {
        "uuid" : "e6d65833-028f-4d0f-b0cc-8334bdcf2d53",
        "isContributing" : false,
        "displayGrouped" : true,
        "displayGroupedName" : "DRIVER_LOAD",
        "uom" : "KLB/HR"
      }, {
        "uuid" : "8288f357-4ab2-4e99-ab14-c0717b27fe5b",
        "isContributing" : false,
        "displayGrouped" : true,
        "displayGroupedName" : "PUMP_SPEED",
        "uom" : "rpm"
      }, {
        "uuid" : "34e1c35b-97f2-4668-9428-bdd5ea663137",
        "isContributing" : false,
        "displayGrouped" : true,
        "displayGroupedName" : "LUBE_OIL_TEMP",
        "uom" : "Celsius"
      } ],
      "alarmState" : {
        "name" : "Resolved"
      },
      "alarmDisposition" : {
        "name" : "None"
      },
      "sourceKey" : "AlarmSourceKey",
      "notes" : [ {
        "text" : "This is my first note",
        "userOwnerSourceKey" : "test002_mdmgr"
      }, {
        "text" : "This is my second note",
        "userOwnerSourceKey" : "test002_mdmgr"
      } ],
      "attachments" : [ {
        "name" : "test_bulk_attachments.txt",
        "blobBase64Encoded" : "YnVsayAgaW5nZXN0aW9uIHRlc3QK",
        "userOwnerSourceKey" : "test002_mdmgr"
      } ]
    },
    "links" : [ ]
  } ]
}

Results

On successful acceptance, you receive a 202 Accepted in the JSON response. Note that the ingestion occurs asynchronously, which means that your request is queued for the server to process it. Check the ingestion progress through HTTP GET to verify ingestion success. Save the uuid from the JSON response for tracking purposes.

Example

HTTP/1.1 202 Accepted
Content-Type: application/json
Content-Length: 158

{
  "uuid" : "8C3D72213EC44D7697A8C465F858F59E",
  "links" : [ {
    "rel" : "status",
    "href" : "/v1/jobs/8C3D72213EC44D7697A8C465F858F59E/status"
  } ]
}

What To Do Next

Use a GET method to track the ingestion progress:

In the REST client, select the GET method.
In the Host value field, enter the following:
https://apm-event-ingestor-alerts-svc-preprod.run.asv-pr.ice.predix.io/v1/jobs/8C3D72213EC44D7697A8C465F858F59E/status
Note:
This should be the Alerts ingestion URL obtained from the Setup page appended to /<UUID>/status. For example, if the following is the response from your alert ingestion:
```
{ 
"uuid" : "8C3D72213EC44D7697A8C465F858F59E",
   "links" : [ {
        "rel" : "status",
        "href" : "/v1/jobs/8C3D72213EC44D7697A8C465F858F59E/status"
   }]
}
```
then the URL to make a GET call to track the ingestion progress would be: https://apm-event-ingestor-alerts-svc-preprod.preprod-app-api.aws-usw02-pr.predix.io/v1/jobs/%7BtaskUuid%7D/status
Append the URL, with the uuid value that you obtained in the JSON response from the earlier POST method. It should look similar to the example above.
In the Header field, enter the Authorization token and tenant_uuid.

Select Send.

You should receive a sample response as shown below:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 155

{
  "id" : 5061,
  "uuid" : "8C3D72213EC44D7697A8C465F858F59E",
  "taskStatusList" : [ {
    "status" : "PENDING",
    "taskId" : "smartSignalTask"
  } ]
}

Alert Ingestion HTTP Status Codes

Having the HTTP Status Codes available can help you understand ingestion issues that may arise.

The following are the possible HTTP status codes for alert ingestion. The codes help you find possible ingestion issues.

Table 2. HTTP Status Codes
Status Code	Meaning
200 OK	The request completed successfully without errors.
202 Accepted	A new resource has been created successfully. Check the `Location` header in the response to get information on the resource `URI`.
204 No Content	An update to an existing resource has been applied successfully.
400 Bad Request	The request was not formatted appropriately. Review the response body for additional information on the type of error that occurred. For example, the request may contain invalid query syntax or operators.
401 Unauthorized	The request has failed authentication as the provided credentials are either invalid or were not provided. This could also happen when the token has expired.
404 Not Found	The requested resource could not be found. It could mean that your request was not created on the server side.