> For the complete documentation index, see [llms.txt](https://documentation.astera.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.astera.com/project-management-and-scheduling/events/custom-events.md). # Custom Events In this document, you'll build a complete custom event solution end to end: you'll define an event, raise it from one flow, and have separate subscriber flows react to it. ### Use Case A flow processes incoming orders. Whenever an order is received, we want to announce an `OrderReceived` event carrying the order's `OrderID` and `Amount`. Several independent subscriber flows react to it: * One subscriber logs **every** order. * Another subscriber reacts **only** to a specific order (using a match value). A custom event solution is made up of three parts, each in its own file: 1. A *Custom Event* definition, in a shared action. 2. A flow containing a *Raise Event* object, the producer. 3. One or more subscriber flows, each containing an *Event Subscription* object. We'll build them in that order. ### Step 1: Define the Custom Event The event definition is the contract shared by the producer and all subscribers. You define it once, in a shared action, so every flow in the project can reference it by name. 1. In your project, create a shared action and add a *Custom Event* object to it, from the **Events** category of the toolbox. 2. In the **object layout** define the **payload** by adding a field for each piece of data the event carries. For each field, specify a name and a data type:

3. Save the shared action. `Scenario1_Event` is now available throughout the project and appears in the event lists of the *Raise Event* and *Event Subscription* objects. {% hint style="info" %} **Note:** The *Custom Event* object only describes the payload structure. It does not process any data at runtime. Data is supplied when the event is raised (Step 2). {% endhint %} ### Step 2: Raise the Event The *Raise Event* object announces the event. It sits at the end of a flow like a destination: data flows into it, and for each incoming record it raises the event with that record's values. {% hint style="info" %} **Note:** *Raise Event* is used only with custom events. System events are raised automatically. See [System Events](/project-management-and-scheduling/events/system-events.md). {% endhint %} 1. Add a source or a set of *Variables* with `OrderID = "A100"` and `Amount = 999` to provide input data to the event's payload. Add a *Raise Event* object.

2. In the *Raise Event* object, select the event type to raise `Scenario1_Event`. Its input fields are populated automatically from the event's payload.

3. **Map** the incoming data into the payload fields (`OrderID`, `Amount`).

4. When this flow runs, each incoming record raises `Scenario1_Event` with the mapped values, and the event is delivered to every subscriber listening for it. ### Step 3: Subscribe to the Event Each subscriber is a separate flow that begins with an *Event Subscription* object, its source, and processes the payload however you like. 1. Create a new flow and add an *Event Subscription* object as its source.

2. Double-click the objects header to open its properties. Here, select the *Catalog Event* type to subscribe to (`Scenario1_Event`).

3. The event's payload fields appear as outputs under the **EventData** node. **Map** them to the rest of the flow.

4. To make a subscriber react only to a specific order, give it a **match value**. In its Event Subscription, enter a match value on the `OrderID` field, for example `A100`.

{% hint style="info" %} Match values are set per payload field. Set them on multiple fields and **all** must match; set none and the subscriber runs every time. Matching is not case-sensitive and ignores surrounding spaces. {% endhint %} ### Step 4: Run or Publish * **While building and testing**, run the producer flow (Step 2) as part of your project. The subscribers in the same project run automatically. * **To keep the subscribers listening on an ongoing basis**, so they react to `Scenario1_Event` raised by any flow, independently, **publish** them to the server.

See [How Events Are Delivered](/project-management-and-scheduling/events.md#how-events-are-delivered) for the difference between local and published subscribers. ### Recap You defined a custom event (`Scenario1_Event`), raised it from a producer flow, and reacted to it from a subscriber flow. Each piece lives in its own file, and together they form a complete event-driven solution. To do the same with a built-in platform event instead of one you define, see [System Events](/project-management-and-scheduling/events/system-events.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.astera.com/project-management-and-scheduling/events/custom-events.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.