Event System
  • 24 May 2023
  • Dark
    Light
  • PDF

Event System

  • Dark
    Light
  • PDF

Article summary

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)
Attribute Type Description
source string The application publishing the event. For example: @itential/app-workflow_engine
topic string The name of the event topic you care about. For example: launch
handler function A handler function that processes the payload data of the event.

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)
Attribute Type Description
source string The application publishing the event. For example: @itential/app-workflow_engine
topic string The name of the event topic you no longer care about. For example: launch
handler function A handler function that previously processed the payload of the event.

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)
Attribute Type Description
topic string The name of the event you are sending. For example: launch
payload object The data related to your event. The payload data must match the JSON schema defined in pronghorn.json for this event. If it does not match, the event will not be processed by subscribers.

Example

// Notice required rocket field
const launchPayload = {
    "rocket": "Saturn V",
    "destination": "Luna"
};

eventSystem.publish("launch", launchPayload);

Was this article helpful?

What's Next
Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.