Transmit Exception Events to External Systems

As an administrator, configure rules that can trigger and transmit system or exception events such as route deviations, cargo condition alerts, and so on to Oracle Transport Management System (OTM) or any external system via an HTTP URL.

Oracle IoT Fleet Monitoring Cloud Service can transmit incidents and alerts to an external application as tracking events. Fleet Monitoring can send emails and SMS notifications. Additionally, custom status event codes, sensor data, metrics, location, system and custom attributes which are defined in rule conditions are transmitted as reference inputs to configured URLs .

As an administrator or shipper of an organization, you can configure business rules on vehicles, shipments, drivers, trips or their entities such as equipment, ship-unit, ship-items that generates incidents or alerts that are transmitted as exception events to Oracle Transportation Management (OTM) application, Oracle Intelligent Track and Trace (ITT), or any external system.

You need to configure notification accounts for HTTP providers, email providers or SMS providers and then add subscribers for these notification accounts.

When you configure a rule, you can define custom event codes that are transmitted with the incident or alert information.

When such a rule is triggered, the IoT service publishes a canonical event payload that complies with the CloudEvents specification. The event payload with relevant data transformation can be consumed by the external application.

Workflow to Transmit Events to External Systems

Step	Description	More Information
Share the event payload structure with the external systems' admin.	Event payload is the information that is transmitted to the external systems via a HTTP URL when an incident or alert is triggered by an event-based rule. The event payload structure complies with the `CloudEvents` specification. The associated external system should be aware of the event payload structure for it to accurately consume and transform the event data that it receives in the notification from the Fleet Monitoring application. The payload structure is relevant for notifications sent to a HTTP provider. For email or SMS notifications, the payload structure is not applicable. Note that for transmitting the event notification to OTM, the payload structure need not be shared because the Fleet Monitoring application will transform the notification data to XML format and then transmit to OTM.	Review the Event-Notification Payload Structure About Event Transmission to Oracle Transportation Management System
Configure the integration with the external system.	You should obtain the relevant URL of the external system such as OTM, ITT, and so on, which you need to add in the Fleet Monitoring application. The target system is also configured appropriately by their admin to receive event notifications from Fleet Monitoring. For example, in OTM, refnums and transmission codes are configured for it to receive and interpret the relevant sensor attribute values, metrics, and event codes from the event notification data from Fleet Monitoring.	Integrate with Oracle Transportation Management Integrate with Oracle Intelligent Track and Trace Integrate with Oracle Warehouse Management Cloud Service
Create notification accounts.	Create notification accounts for an SMS provider, an email provider or an HTTP provider. When a rule generates an incident or alert, notifications are sent to the configured subscribers including the HTTP subscriber. Note that for OTM, you don't need to add a HTTP based notification account because Fleet Monitoring seeds it after you've configured the integration with OTM.	Send Notifications for Incidents or Alerts
Add subscribers.	Add subscribers to the SMS, e-mail provider, or the HTTP provider that you've added as notification accounts. The subscribers receive the event notifications. For OTM, when you've configured the integration, the subscriber is added by default.	Add Subscribers for the Notifications
Create rules.	Before you create an event- based rule, define rule conditions which when met will trigger an incident or an alert. Define custom event codes that'll be sent with the event payload to the external system when a rule is triggered. An incident transmits an event-creation code or an event-resolution code when an incident is created or resolved respectively. An alert has a single event-creation code. Transmission codes should be configured on OTM system for the cloud event "code" field.	Create a Rule

Review the Event-Notification Payload Structure

When a rule triggers an incident or an alert, an event notification can be transmitted to an external system, which transforms and consumes the data.

The structure of each event-notification payload is shared with the external system's admin who in turn provides the external system's URL. In the Fleet Monitoring application, the admin uses the URL to configure an integration with the external system and then configures notification accounts with the external system's URL, a SMS provider, or an email provider. The event -notification payload structure complies with the CloudEvents specification.

Note:

For sending event-notifications to Oracle Transportation Management (OTM), this payload structure in JSON is not applicable because the Fleet Monitoring application transmits the information to OTM in XML format. See About Event Transmission to Oracle Transportation Management System

The following steps help you review the payload structure of a event notification triggered by an incident and by an alert.

Review this incident-triggered event notification payload structure for a ship-unit entity of a trip:

{
    "specversion": "1.0",
    "type": "com.oraclecloud.iot.incidentTriggered",
    "id": "2635236",
    "source": "/incidents/<incidentId>", // All fulfilments (& rules themselves) are always local ID
    "subject": "/shipunits/<shipunitId>",
    "time": "2021-04-05T17:31:50.52Z",
    "datacontenttype": "application/json",
    "data": {
        "summary": "Ship Unit Temperature Pressure Breach",
        "description": "Ship Unit Temperature Pressure Breach",
        "type": "OUTAGE",
        "priority": "HIGH",
        "state": "RESOLVED",
        "contexts": [
            {
                "id":  "<tripId>",
                "kind": "TRIP"
            },
            {
                "kind": "SHIPUNIT",
                "id": "<shipunitId>",
                "values": [
                    {
                        "id": "<sensorId>",
                        "name": "ora_temperature",
                        "type": "SENSOR",
                        "value": 40
                    },
                    {
                        "id": "<sensorId>",
                        "name": "ora_humidity",
                        "type": "SENSOR",
                        "value": 72
                    },
                    {
                        "id": "<metricId>",
                        "name": "sys_geoLocation",
                        "type": "METRIC",
                        "value": "<latitude>, <longitude>, <altitude>"
                    }
                ]
            }
        ]
    },
    "parent": "/trips/<tripId>",
    "org": "<orgId>",
    "code": "<eventCode>"
}

Review this alert-trigered notification payload structure a ship-unit entity of a trip:

{
    "specversion": "1.0",
    "id": "2635236",
    "type": "com.oraclecloud.iot.alertTriggered",
    "source": "/alerts/<alertId>",
    "subject": "/shipunits/<shipUnitId>",
    "time": "2021-04-05T17:31:50.52Z",
    "datacontenttype": "application/json",
    "data": {
        "summary": "Ship Unit Temperature Pressure Breach",
        "severity": "CRITICAL",
        "contexts": [
            {
                "id":  "<tripId>",
                "kind": "TRIP"
            },
            {
                "kind": "SHIPUNIT",
                "id": "<shipunitId>",
                "values": [
                    {
                        "id": "<sensorId>",
                        "name": "ora_temperature", 
                        "type": "SENSOR",
                        "value": 40
                    },
                    {
                        "id": "<sensorId>",
                        "name": "ora_humidity",
                        "type": "SENSOR",
                        "value": 72
                    },
                    {
                        "id": "<metricId>",
                        "name": "sys_geoLocation",
                        "type": "METRIC",
                        "value": "<latitude>, <longitude>, <altitude>"
                    }
                ]
            }
        ]
    },
    "parent": "/trips/<tripId>",
    "org": "<orgId>",
    "code": "<eventCode>"
}

Review the purpose of these fields in the payload structure:
- type: The value of this field follows a format similar to com.oraclecloud.iot.alertTriggered com.oraclecloud.iot.incidentTriggered and denotes if the event was triggered by an incident or an alert.
- id: The value represents a unique ID of the event.
- source: Its value denotes the ID of the specific alert or incident that generated the event.
- subject: The value contains the ID of the entity whose sensor data, metrics, location data, system or custom attributes are defined in the rule condition and caused the event-based rule to fire an incident or alert.
- time: Its value denotes the time when the incident or alert was generated in UTC format.
- parent: Its value denotes the parent entity of the subject entity. For example, a trip is the parent of a ship-unit.
- org: This denotes the organization ID to which the source entity belongs.
- code: For a new incident, it contains a creation event code and when the incident is resolved, it contains a resolution eventt code. In case of an alert, it contains only the creation event code.
- data: It contains several sub-fields such as summary, description, type, priority, state whose values have information about the incident or alert that the admin defined in the rule.
- context: This field has several sub-fields that describe those sensor attributes or metrics of the subject entity and the parent entity, which were used in the rule's condition. The geo-location of the entities would be added in all notifications by default.

Note the list of values allowed for the fields of the payload:

type: one of

["com.oraclecloud.iot.incidentTriggered", "com.oraclecloud.iot.alertTriggered"]

source: one of

["/alerts/<alertId>", "/incidents/<incidentId>"]

subject: one of

["/vehicles/<vehicleId>", "/drivers/<driverExternalId or driverId>", "/equipments/<trip equipment ref>


", "/facilities/<facility external Id>", "/shipitems/<ship item no.>", "/shipunits/<ship unit no.>", "/shipments/<shipment externalId or shipmentId>", "/trips/<trip ExternalId or tripId>"]

parent: one of

["/shipments/<shipment externalId or shipmentId>", "/trips/<trip ExternalId or tripId>"]

kind: one of



 ["VEHICLE", "DRIVER", "TRIP", "SHIPMENT", "FACILITY", "EQUIPMENT", "SHIPITEM", "SHIPUNIT"]

values:type: one of

["METRIC", "SENSOR", "SYSTEM", "CUSTOM", "LOCATION"]

About Event Transmission to Oracle Transportation Management System

The IoT Intelligent Fleet Monitoring application transmits event-notification payloads to Oracle Transportation Management (OTM) in XML format unlike in the other external systems where it transmits the payload in JSON format based on the CloudEvents specification.

As an administrator, you create a rule for an entity and add conditions which when met triggers an incident or alert that transmits an event-notification payload to OTM in XML format.

About Configurations

As an administrator, before you can create a rule to transmit exception events to OTM, complete these configurations in Fleet Monitoring and OTM applications:

For each of the entities, such as vehicle, trip, ship-unit, shipment, driver and so on, identify the sensor attributes, metrics, location attributes, system attributes or custom attributes which you'll use in the rule conditions. The OTM admin should configure refnum/value pairs that map to these attributes for each of the entities. This configuration is required when the Send Rule Attributes flag is enabled in the OTM configuration screen in Fleet Monitoring.
Define custom event codes for the incidents and alerts in your rule. The OTM admin should configure transmission codes mapping to these event codes. This configuration is mandatory for OTM to successfully process the event notifications from Fleet Monitoring.
In your organization, configure an integration with OTM. From the Design Center > Organization > Integrations option, go to the OTM Configurations page. Enable the Integration Status and Send Rule Attributes options. If the Send Rule Attributes is not enabled then the rule condition's attributes are not transmitted with the notification to OTM. See Connect to an Oracle Transportation Management Cloud Service Instance.
Obtain the OTM URL, domain name, user name, and password details from the OTM admin and use the details to add an OTM integration in your organization. See Integrate with Oracle Transportation Management.
The OTM admin should have enabled and configured the integration with Oracle IoT Intelligent Fleet Monitoring application in the OTM instance.

About Notification Account and Subscribers

In the IoT Intelligent Fleet Monitoring application, a pre-seeded notification account for OTM is available. After you've configured an integration with OTM, a pre-configured subscriber for the OTM notification account gets added. The Fleet Monitoring application uses these pre-existing configurations to transmit event notifications to OTM.

When you create a rule, select the target entity, add conditions, select the incident or alert option, and select the OTM subscriber that would receive the event notification. To view the various options, see Create a Rule.

To know the workflow to transmit events to other external systems see Transmit Exception Events to External Systems