Creating heartbeat alerts

You can configure heartbeat alerts so that alerts are sent every 30 minutes, starting on the hour.

Before you begin

To complete step 2 and step 4 of this task, you must generate a token. For more information, see Creating authentication tokens. Following this procedure is easier if you understand the Alerting component. For more information, see Alerting concepts.

Procedure

Optional: Create a contact file to ensure that heartbeat alerts are emailed. For more information, see Creating contacts.

Create a contact_upload.json file with the following content.

Update the parameter values for tenantId, firstName, lastName, and emailAddress.

{"eventCode": "objectUpsertEvent", "tenantId": "{tenant_id}", "eventDetails": {"businessObject": {"contactIdentifier":
"HEARTBEAT_CONTACT", "type": "Contact", "firstName": "", "lastName": "", "emailAddress": "{email_id}", "locale": "en",
"globalIdentifiers": [{"name": "eis.geospatial.globalId", "value": "HEARTBEAT_CONTACT"}]}}}

Create an endpoint.

Add an endpoint authentication secret.
Create a JSON file called endpointsecretkey.json with the following content for the secret:
```
{  
  "value" : "${AUTHORIZATION_STRING}"
}
```

Make the following API call to create the secret named endpointsecretkey.

Update the TENANT_ID and endpointsecretkey in the URL and the parameter values for TENANT_ID and JWT_TOKEN in the headers.

curl -v -X PUT --location "https://api.ibm.com/infohub/run/metadata/api/v1/na/tenants/${TENANT_ID}/webhook/endpointsecretkey" \
  --header "X-IBM-Client-Id: infohub-${TENANT_ID}" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${JWT_TOKEN}" \
  -d @endpointsecretkey.json

Create an endpoint JSON file with the following payload:

Update the parameter values for name, logicalName, webhookPayloadUrl, tenantId, and apiKeyName.

Note: The apiKeyName in the payload must be the same as the apiKeyName that is at the end of the URL in step 2c.

{
"endpointType": "AlertEndpoint",
"isPublicUrl": false,
"name": " {any_name} ",
"logicalName": "{any_name}",
"webhookPayloadUrl": "{endpoint_url}",
"isGloballyVisible": false,
"isMetadataOnly": false,
"tenantId": "{tenant_id}",
"authType": "basic",
"contentType": "default",
"apiKeyName": "endpointsecretkey",
"allowedOperations": [
       "create",
       "update",
       "delete"
   ]
}

Make the following API call to create an endpoint:

Update the parameter values for TENANT_ID and JWT_TOKEN in the headers.

curl -X POST 
   --location "https://api.ibm.com/infohub/run/metadata/api/v1/na/endpointdefinitions " \
  --header "X-IBM-Client-Id: infohub-${TENANT_ID}" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${JWT_TOKEN}" \
  --data @endpoint_upload.json

Create an asset.

The location of this asset is in the far North of Canada. In Step 7, you create asset endpoint subscriptions so that this asset receives only HEARTBEAT alerts.

Create an asset_upload.json with the following content:

Update the parameter value for tenantId. If you do not want to receive emails for heartbeat alerts, remove the contact field.

{"eventCode": "objectUpsertEvent", "tenantId": "{tenant_id}", "eventDetails":
{"businessObject": {"currentLocationCoordinates": "58.474311344996245,-
97.22213745117188", "assetIdentifier": "HEARTBEAT", "type": "Asset", "description":
"Asset for the Heartbeat alerts", "globalIdentifiers": [{"name":
"eis.geospatial.globalId", "value": "HEARTBEAT.STATIC"}], "assetType": "STATIC",
"status": "active", "contacts": [{"globalIdentifiers": [{"name":
"eis.geospatial.globalId", "value": "HEARTBEAT_CONTACT"}]}]}}}

In Job Management, upload the JSON file.
For more information about uploading the file, see Creating assets.

In Criteria builder, check if your account contains the base heartbeat criteria named HEARTBEAT_BASE. If your account does not contain the base heartbeat criteria names, follow the steps in Defining criteria to upload the criteria in step 4a.

Contact the IBM migration team if you have any problems.

Update the parameter value for tenantId and upload the following criteria through the API endpoint:

{ 
    "name": "HEARTBEAT_BASE", 
    "logicalName": "HEARTBEAT", 
    "tenantId": "{tenant_id}", 
    "description": "Base criteria for the heartbeat alert",
    "type": "WeatherEvent", 
    "enabled": true, 
    "hint": { 
        "viewId": "geospatialevents" 
    }, 
    "advancedFilter": { 
        "OR": [         
            { 
                "GREATER_EQUALS": [ 
                  { 
                    "SELECT": "HEARTBEAT" 
                  }, 
                  { 
                    "VALUE": "0" 
                  } 
                ] 
            }  
        ] 
    } 
}

Create another criteria.

Option Steps

Use the API

Option	Steps
Use the API	Use the criteria that you created in the previous step and use the following payload:Update the parameter value for tenantId. `{ "name": "HEARTBEAT", "logicalName": "heartbeat", "tenantId": "{tenant_id}", "description": "Criteria for the heartbeat alert", "type": "SavedFilter", "enabled": true, "hint": { "viewId": "geospatialevents" }, "advancedFilter": { "OR": [ { "MATCHES_SAVED_FILTER": { "VERSION": 1, "LOGICAL_NAME": "HEARTBEAT" } } ] } }`
Use Criteria builder	In the Criteria builder library, open HEARTBEAT. In Configure criteria, for the criteria type, choose Select existing, for database view, select geospatialevents, and select the HEARTBEAT_BASE criteria.

Use the criteria that you created in the previous step and use the following payload:Update the parameter value for tenantId.

{
    "name": "HEARTBEAT",
    "logicalName": "heartbeat",
    "tenantId": "{tenant_id}",
    "description": "Criteria for the heartbeat alert",
    "type": "SavedFilter",
    "enabled": true,
    "hint": {
        "viewId": "geospatialevents"
    },
    "advancedFilter": {
        "OR": [        
            {
                "MATCHES_SAVED_FILTER": {
                    "VERSION": 1,
                    "LOGICAL_NAME": "HEARTBEAT"
                }
            }
        ]
    }
}

Use Criteria builder

In the Criteria builder library, open HEARTBEAT.
In Configure criteria, for the criteria type, choose Select existing, for database view, select geospatialevents, and select the HEARTBEAT_BASE criteria.

Add a rule for the HEARTBEAT parameter. For more information, see Defining criteria.

Option Steps

Use the API

Option	Steps
Use the API	Update the tenantId, endPointId, and endpointLogicalName values: { "type": "AlertRule", "tenantId": "<<tenant_id>>", "isGloballyVisible": false, "logicalName": "HEARTBEAT", "name": "HEARTBEAT", "description": "Rule for the heartbeat alert", "primaryBusinessObject": [ "WeatherEvent" ], "isComplete": true, "enabled": true, "databaseViewUsedByThisRule": "geospatialevents", "instructions": { "ifEvent": { "OR": [ { "MATCHES_SAVED_FILTER": { "VERSION": 1, "LOGICAL_NAME": "heartbeat" } } ] }, "thenNotify": [ { "notificationType": "sendObjectUpsertEvents" }, { "endpoint": { "endpointLookupFieldPath": "eventDetails.businessObject.recipients.endpoint", "endPointId": "endpoint_ID", //Update endpoint id, can also add multiple json blocks for multiple endpoints "endpointLogicalName": "{endpoint_logical_name_from_step2}", "isLookup": true }, "notificationType": "webhook" }, { "emailMessageTemplateLogicalName": "default_template", "notificationType": "email", "contacts": { "contactLookupFieldPath": "asset.contacts.id", "isLookup": true } } ] } }
Use Rule Builder	In the Rules library, open HEARTBEAT. In Configure trigger criteria, for the primary data object, select WeatherEvent, for the database view, select geospatialevents, and select the HEARTBEAT criteria. In Actions, specify an action such as `Create geospatial event`. Add an action, for the alert method select Email, and select a message template. Add an action, for the alert method select API endpoint, and select the endpoint that you added in step 2.

Update the tenantId, endPointId, and endpointLogicalName values:

{
    "type": "AlertRule",
    "tenantId": "<<tenant_id>>",
    "isGloballyVisible": false,
    "logicalName": "HEARTBEAT",
    "name": "HEARTBEAT",
    "description": "Rule for the heartbeat alert",
    "primaryBusinessObject": [
        "WeatherEvent"
    ],
    "isComplete": true,
    "enabled": true,
    "databaseViewUsedByThisRule": "geospatialevents",
    "instructions": {
        "ifEvent": {
            "OR": [
                {
                    "MATCHES_SAVED_FILTER": {
                        "VERSION": 1,
                        "LOGICAL_NAME": "heartbeat"
                    }
                }
            ]
        },
        "thenNotify": [
            {
                "notificationType": "sendObjectUpsertEvents"
            },
            {
                "endpoint": {
                    "endpointLookupFieldPath": "eventDetails.businessObject.recipients.endpoint",
                    "endPointId": "endpoint_ID", //Update endpoint id, can also add multiple json blocks for multiple endpoints
                    "endpointLogicalName": "{endpoint_logical_name_from_step2}",                     
                    "isLookup": true
                },
                "notificationType": "webhook"
            },
            {
                "emailMessageTemplateLogicalName": "default_template",
                "notificationType": "email",
                "contacts": {
                    "contactLookupFieldPath": "asset.contacts.id",
                    "isLookup": true
                }
            }
        ]
    }
}

Use Rule Builder

In the Rules library, open HEARTBEAT.
In Configure trigger criteria, for the primary data object, select WeatherEvent, for the database view, select geospatialevents, and select the HEARTBEAT criteria.
In Actions, specify an action such as Create geospatial event.
Add an action, for the alert method select Email, and select a message template.
Add an action, for the alert method select API endpoint, and select the endpoint that you added in step 2.

Create contact alert subscriptions for the contacts that you added to the asset in step 1.

Note: The asset must be subscribed to the HEARTBEAT criteria to receive email alerts for heartbeats.

Create a contact_subscriptions.json file with the following content:

Update the parameter value for tenantId.

{"eventCode": "objectUpsertEvent", "tenantId": "{tenant_id}", "eventDetails":
{"businessObject": {"type": "ContactAlertSubscriptions", "subscriptions":
["heartbeat"], "globalIdentifiers": [{"name": "eis.geospatial.globalId", "value":
"HEARTBEAT_CONTACT"}], "contact": {"globalIdentifiers":[{"name": 
"eis.geospatial.globalId", "value": "HEARTBEAT_CONTACT"}]}}}}

In Job Management, upload the JSON file.

Create asset endpoint subscriptions for the asset in step 1.

Note: The asset must be subscribed to the HEARTBEAT criteria to receive endpoint alerts for heartbeats.

Create an asset_subscriptions.json file with the following content:

{"eventCode": "objectUpsertEvent", "tenantId": "{tenant_id}", "eventDetails":
{"businessObject": {"type": "AssetEndpointSubscriptions", "subscriptions":
["heartbeat"], "globalIdentifiers": [{"name": "eis.geospatial.globalId", "value":
"HEARTBEAT.STATIC"}], "asset": {"globalIdentifiers": [{"name":
"eis.geospatial.globalId", "value": "HEARTBEAT.STATIC"}]}}}}

Update the parameter value for tenantId.
In Job Management, upload the JSON file.

Results

The endpoints in the rule and contacts that you added in the asset now receive HEARTBEAT alerts every 30 minutes. To disable these alerts, in the Rule builder, deactivate the HEARTBEAT rule.

Example

Sample payload for HEARTBEAT alerts:

[   
    {
        "ruleTexts":[
            {
                "name":"HEARTBEAT_BASE",
                "description":"Base criteria for the heartbeat alert",
                "languageCode":"en",
                "default":true
            }
        ],
        "assetIdentifier":"HEARTBEAT",
        "assetDescription":"Asset for the Heartbeat alerts",
        "ruleDescription":"Rule for the heartbeat alert",
        "ruleExternalId":"ce653652-7e1a-4e3b-8e4b-f8edfa536f76",
        "assetId":"34e3421f-65b6-4ccf-bb79-6d1450439f96",
        "eventParameter":"HEARTBEAT",
        "eventEndTime":1695739205000,
        "ruleName":"HEARTBEAT|heartbeat|HEARTBEAT",
        "ruleExternalName":"HEARTBEAT",
        "matchedConditions":[
            {
                "parameterId":"HEARTBEAT",
                "timestamp":1695738605958,
                "startTime":1695738605000,
                "endTime":1695739205000,
                "expireTime":1695739205000,
                "ingestTime":1695738605958,
                "ingestId":"f8849445-9855-41af-94e0-08467f88456a",
                "conditionType":"VECTOR_EVENT",
                "impact":{
                    "locationHash":"526861c",
                    "fullyCovered":false
                },
                "geometryId":"9f134be2-99a0-41bd-98cb-4055b4d33058",
                "values":[
                    null
                ]
            }
        ],
        "eventStartTime":1695738605000
    }
]