> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-platform/2023-2/developer-guide/event-system/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Event system

> How to use the global eventSystem service object to publish and subscribe to events in Itential Platform.

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:

```js
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:

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

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:

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

## 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.

There is currently no verification of event payload within Itential Platform. This is handled by the `eventSystem` in the application when it receives a subscribed event.

## 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.

```bash
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**

```bash
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.

```bash
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**

```bash
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.

```bash
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 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**

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

eventSystem.publish("launch", launchPayload);
```

> How to use the global eventSystem service object to publish and subscribe to events in Itential Platform.