Introduction to the Events API
Authors:
Ankit Mehta, Movyn John, Cille Schliebitz, Anita Gu
Changed on:
3 Feb 2025
Overview
In this lesson, we'll look at Event APIs, learn more about Event Contracts and the role of Events in the Workflow Framework, as well as look at some common integrations that use the Events API.
Key points
- Intro / Recap on what Event is
- Events API
- Event Structure
- Event Contracts & relationship to Workflow
- Types of common integrations that use Events
- Events best practices
Events
Events are a fundamental part of the Fluent Platform and represent something that has, will, or is happening within the system. An Event is typically used to trigger the system to do something or log activity of what has happened within the system. Not only are they used to trigger workflow logic, but they are also used to capture everything that happens within the system.
Next, let's look at Events from an Integration & Connection point-of-view, with Events API.
Events API
ORCHESTRATION events are used to trigger the execution of workflow logic, while the ORCHESTRATION_AUDIT events describe what happened during that workflow execution.
API events, like ORCHESTRATION_AUDIT events, describe what happens within the system, rather than triggering any behaviour.
The Event API allows users and external systems to view and create events within the Fluent Platform.
Here, we look at some Get/Post Event API operations.
/event/{eventId} | Get an Event by Id Returns the Event identified by the <eventId> parameter. Returns a 404 HTTP Status code if not found. Authentication: Required |
/event | Finds all events for the given criteria Returns a page of events filtered by the given combination of parameters. If no parameters are provided, the default page size, date range, and sort order will be applied, and the events for which your authenticated user is authorised will be returned. Authentication: Required |
/event/async | Creates a new Event in the Fluent Platform Creates a new Event within the Fluent Platform to trigger a part or whole of a workflow. Authentication: Required |
Learn more about the parameters and responses here (opens in a new tab).
Sample Event to Trigger a Ruleset
Following are the main fields of an event
- name: This is the name of the event that matches with the ruleset in the respective workflow.
- retailerId: This is Fluent OMS's retailer ID.
- entityType: The entity against which the event is triggered. Example: FULFILMENT, LOCATION, INVENTORY_POSITION, etc.
- entityId: The ID of the entity against which the event is triggered. Example: fulfilmentId, locationId, etc.
- entityRef: The ref of the entity against which the event is triggered. Example: inventoryPositionRef, etc.
- rootEntityType: The root entity against which the event is triggered. Example: ORDER, INVENTORY_CATALOGUE, etc.
- rootEntityId: The ID of the root entity against which the event is triggered. Example: orderId, etc.
- rootEntityRef: The ref of the root entity against which the event is triggered. Example: orderRef, inventoryCatalogueRef, etc.
- attributes: The event attributes passed to the ruleset handling the event, these attributes are used by the rules of the ruleset.
Event Contracts & Relationship to Workflow
An Event Contract is defined by the Rulesets in a Workflow. And, within that Ruleset, all the rules that define event attributes, combine to form the Event Contract for that Ruleset.
Example: if you have a Ruleset that is expecting a certain set of values, such as the brand name, product reference, expected category, etc. then the Rules within that Ruleset validating those incoming attributes, is what's referred to as the Event Contract.
Recommended Practice: Use Async integration (https://<ACCOUNTID>.sandbox.api.fluentretail.com/api/v4.1/event/async), unless there is a real-time action (user interaction, fulfilment options) in it.
Common Integrations: Some common integrations that use the Events API are:
Custom Inventory Integration: Events are used if the Batch API cannot satisfy the client's inventory mechanism or requirement. For eg: Delta Inventory Event
Product Master Integration: External events from the Product Master (PIM) can be passed to the Fluent OMS to create Categories, Standard and Variant Products.
WMS Integration-Inbound (Pick / Ship Confirmation): Any fulfilment updates, like Pick / Ship Confirmation are sent to the Fluent OMS using events.
Carrier Integration: Any updates from the Carrier provider around Consignment and Tracking Details are sent to the Fluent OMS through events.
