Event system

The event system is a global service object named eventSystem that is available to application developers in the Itential Platform environment. The eventSystem allows a service to publish information to the Itential Platform environment that other services can react to.

The event system has three main methods:

1
eventSystem.publish(topic, payload);
2
3
eventSystem.subscribe(source, topic, handler);
4
5
eventSystem.unsubscribe(source, topic, handler);

Event definition

To define an event that you want your service to publish, add a topics section to the pronghorn.json of your application. For example:

1
"topics" : {
2
    "launch": {
3
        "type": "object",
4
        "required": ["rocket"],
5
        "properties": {
6
            "rocket": {}
7
        }
8
    },
9
    "bananas": {}
10
}

The example above defines two topics that can be emitted as events: launch and bananas. The launch object contains a JSON schema that defines what its event payload should look like. The rocket property is required for the event’s payload — if it is not present, the event will not be processed. If an event does not match the defined schema, it is rejected.

The bananas event has no requirement for its payload structure. You can publish as many events as you like:

1
"topics" : {
2
    "eventName1": {
3
        -JSON Schema-
4
    },
5
    "eventName2": {
6
        -JSON Schema-
7
    },
8
    "eventNameN": {
9
        -JSON Schema-
10
    }
11
}

Namespace

Events are automatically namespaced using the model name of the application (for example, @itential/app-workflow_engine). This allows developers to have events with the same name across different applications — for example, the event name rocket could exist in both @itential/app-workflow_engine and @itential/app-configuration_manager.

Registration

When an application connects to Itential Platform, it automatically sends all of its defined event topics. Itential Platform adds the event topics to the global list it maintains and then broadcasts the updated global list to all other applications, allowing them to subscribe to the new events.

Subscription

To handle a particular event, call the eventSystem.subscribe method. After subscribing, the event system calls the handler function when it receives the event and verifies the payload matches the schema.

$
eventSystem.subscribe(source, topic, handler)

Example

$
eventSystem.subscribe("@itential/app-workflow_engine", "launch", launchHandler);

Unsubscribe from an event

To stop listening for an event, call the eventSystem.unsubscribe method. This causes the event system to stop calling the handler function for that event.

$
eventSystem.unsubscribe(source, topic, handler)

Example

$
eventSystem.unsubscribe("@itential/app-workflow_engine", "launch", launchHandler);

Publish an event

To send an event, call the eventSystem.publish method. This sends the event to Itential Platform for broadcast to all other applications in the environment. No source is required when publishing — the namespace is automatically added by the event system to ensure proper scope.

$
eventSystem.publish(topic, payload)

Example

$
// Notice required rocket field
$
const launchPayload = {
>
    "rocket": "Saturn V",
>
    "destination": "Luna"
>
};
$
$
eventSystem.publish("launch", launchPayload);