Event System

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

The event system has three main methods (which are described in this guide):

eventSystem.publish(topic, payload);

eventSystem.subscribe(source, topic, handler);

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:

"topics" : {
    "launch": {
        "type": "object",
        "required": ["rocket"],
        "properties": {
            "rocket": {}
        }
    },
    "bananas": {}
}

The above example defines two topics that can be emitted as events by the Itential application, launch and bananas. The launch object contains a JSON schema that defines what its event payload should look like. As you can see the property rocket is required for the event's payload. If it is not present in the payload 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 how its payload should look. You can publish as many events as you like.

"topics" : {
    "eventName1": {
        -JSON Schema-
    },
    "eventName2": {
        -JSON Schema-
    }
    .
    .
    .
    "eventNameN": {
        -JSON Schema-
    }
}

Namespace

These events are automatically namespaced in the system using the model name of the application (e.g., @itential/app-workflow_engine). This allows developers to have events with the same name. Hence, the event name "rocket" could be used in both @itential/app-workflow_engine and @itential/app-configuration_manager.

Registration

When an application connects to IAP it automatically sends all of its defined event topics. IAP adds the event topics to the global list it maintains and then broadcasts the updated global list to all other applications. This allows the other applications to subscribe to the new events.

Note: Currently there is no verification of event payload within IAP. This is handled by the eventSystem in the application when it receives an event it is subscribed to.

Subscription

To handle a particular event, call the eventSystem.subscribe method. After an event is subscribed to, the event system will call the handler function when it receives the event and verify the payload matches the schema.

eventSystem.subscribe(source, topic, handler)

Example

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

Unsubscribing

To stop listening for an event, call the eventSystem.unsubscribe method. This will cause the event system to stop calling the handler function for a particular event. Unsubscribing tells the event system you no longer care about that event topic.

eventSystem.unsubscribe(source, topic, handler)

Example

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

Publish

To send an event, call the eventSystem.publish method. This will send the event to IAP for broadcast to all the other applications in the IAP environment. Notice there is no source 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);