REST Event API

Home
Essential Knowledge
By Type
Building Blocks
APIs
Releases

Essential knowledge

Authors:

Lesley Dean, Girish Padmanabha, Boris Pocatko, Yulia Andreyanova, Randy Chan

Changed on:

17 Oct 2024

Overview

Events are a fundamental part of the Fluent Platform. Not only are they used to trigger workflow logic, but they also capture everything that happens within the system. Events are categorized by type.

Key points

Event Types: Understand the different event categories such as ORCHESTRATION, ORCHESTRATION_AUDIT, API, and GENERAL events, each serving distinct purposes within the Fluent Platform.
Event Retrieval: Use the GET methods with appropriate parameters to retrieve specific events or a filtered list of events, ensuring you handle possible 404 errors for not found items.
Event Creation: Leverage the POST methods to create new events either asynchronously (/event/async) or synchronously (/event/sync) based on the workflow requirements.
Authentication: Remember that authentication is required for all operations within the Event API, ensuring secure access and interaction with the event system.

Property	Value
URL	`<root_url>/api/v4.1/event`
Methods	`GET` , `POST`
Scheme	`https`
Auth	`OAUTH`
Content-Type	`application/json`

`ORCHESTRATION`

events are intended to trigger part of or the whole of a workflow, while

`ORCHESTRATION_AUDIT`

events describe what happened during that workflow execution. In addition to

`ORCHESTRATION`

and

`ORCHESTRATION_AUDIT`

events, there are also

`API`

events and

`GENERAL`

events.

`API`

and

`GENERAL`

events, like

`ORCHESTRATION_AUDIT`

events, describe what happens within the system, rather than triggering any behavior.

The Event API allows users and external systems to view and create events within the Fluent Platform.

Note

The Event API is currently only available in REST.

Operations

[GET] /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

Parameters

Name	Required	Default Value	Description
eventId	yes	-	A Unique Event Id

Responses

Response Content-Type:

`application/json`

Code	Description
200	Successful Operation
401	Authorization Error - Invalid Bearer Token / No permission
400	Client Error - Bad Request
403	Client Error - Forbidden
404	Client Error - Not Found (Invalid Event Id)
500	Server Error

Example

Request:

`https://<AccountId>.sandbox.api.fluentretail.com/api/v4.1/event/05838ba2-7025-11eb-b493-0f90922e985a`

Response:

1//Event
2{
3    id (string),
4    retailerId (string),
5    accountId (string),
6    name (string),
7    type (string),
8    category (string),
9    context (object),                   // See 'Context' below
10    eventStatus(string, Required)
11    attributes (Attribute[]),           // See 'Attribute' below
12    source (string),
13    generatedBy (string),
14    generatedOn (date)
15}
16
17//Context
18{
19    sourceEvents (String[]),
20    entityType (string),
21    entityId (string),
22    entityRef (string),
23    rootEntityType (string),
24    rootEntityId (string),
25    rootEntityRef (string)
26}
27
28//Attribute
29{
30    name (string),
31    value (string),
32    type (string)
33}
34

Language: json

Name: Model

Description:

[Warning: empty required content area]

1{
2    "id": "05838ba2-7025-11eb-b493-0f90922e985a",
3    "name": "DeactivateProduct",
4    "type": "ORCHESTRATION_AUDIT",
5    "accountId": "FCTRAINAU25",
6    "retailerId": "1",
7    "category": "ruleSet",
8    "context": {
9        "sourceEvents": [
10            "055c54d3-7025-11eb-912a-e98bb0976432"
11        ],
12        "entityType": "PRODUCT",
13        "entityId": null,
14        "entityRef": "PRD-SPECIAL-1",
15        "rootEntityType": "PRODUCT_CATALOGUE",
16        "rootEntityId": null,
17        "rootEntityRef": "FCRG:PC:MASTER"
18    },
19    "eventStatus": "FAILED",
20    "attributes": [
21        {
22            "name": "startTimer",
23            "value": 1613458987222,
24            "type": "STRING"
25        },
26        {
27            "name": "stopTimer",
28            "value": 1613458987329,
29            "type": "STRING"
30        }
31    ],
32    "meta": null,
33    "source": null,
34    "generatedBy": "Rubix User",
35    "generatedOn": "2021-02-16T07:03:07.329+0000",
36    "recordedBy": "Rubix User ",
37    "recordedOn": "2021-02-16T07:03:07.354+0000"
38}

Language: json

Name: Sample Value

Description:

[Warning: empty required content area]

Example Error Response:

1//Errors
2{
3    errors (Error[])
4}
5
6//Error
7{
8    code (string),
9    message (string)
10}

Language: json

Name: Model

Description:

[Warning: empty required content area]

1{
2    "errors": [
3        {
4            "code": "404",
5            "message": "Cannot find an event with id: 76b97221-8be4-11e9-beb2-c187ba8970a"
6        }
7    ]
8}

Language: json

Name: Sample Value

Description:

[Warning: empty required content area]

[GET] /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 authorized for will be returned.

Authentication

Required

Parameters

Name	Default Value	Description	Type
retailerId	-	A Unique Retailer Id	`List<String>`
eventType	-	It is possible to send multiple values at the same time. For example: `ORCHESTRATION` , `ORCHESTRATION_AUDIT` , `API` , and `GENERAL` event types	`List<String>`
Category	-	It is possible to send multiple values at the same time. For example: `exception` , `ruleSet` , `snapshot` , `ACTION` , `rule` , `BATCH`	`List<String>`
Name	-	The name of an event	`String`
context.rootEntityId	-	The `ID` of the root domain entity for which the event relates to.	`String`
context.rootEntityType	-	The `Type` of the root domain entity for which the event relates to. For example: Order, etc.	`List<String>`
context.entityId	-	The `ID` of the sub entity for which the event relates to.	`String`
context.entityType	-	The `Type` of the sub entity for which the event relates to. For example: Fulfilment, etc.	`List<String>`
eventStatus	-	The Status of the events to be returned.	`List<String>`
from	`to` - 1 hour	A UTC formatted DateTime. For example: 2019-01-01T00:00:00.000Z	`Date`
to	Now	A UTC formatted DateTime. For example: 2019-01-31T23:59:59.999Z	`Date`
start	0	The index of the first record of a page to be returned.	`Integer`
count	100	The number of results to be returned per page. Max 100.	`Integer`

Warning

Due to the high volume of events generated within the system every single second, we limit the maximum time range to retrieve Events to 1 hour.

The recommended

`from`

and
`to`
time range is 5 minutes.

Responses

Response Content-Type:

`application/json`

Code	Description
200	Successful Operation
401	Authorization Error - Invalid Bearer Token / No permission
400	Client Error - Bad Request
504	Gateway Timeout

Example

Request:

`https://<AccountId>.sandbox.api.fluentretail.com/api/v4.1/event?context.rootEntityId=1234&context.rootEntityType=Order`

Response:

1//Event
2{
3start (integer),
4count (integer),
5hasMore (boolean),
6results (Array):[{
7    id (string),
8    retailerId (string),
9    accountId (string),
10    name (string),
11    type (string),
12    category (string),
13    context (object),                   // See 'Context' below
14    eventStatus(string, Required)
15    attributes (Attribute[]),           // See 'Attribute' below
16    source (string),
17    generatedBy (string),
18    generatedOn (date)
19  }]
20}
21
22//Context
23{
24    sourceEvents (String[]),
25    entityType (string),
26    entityId (string),
27    entityRef (string),
28    rootEntityType (string),
29    rootEntityId (string),
30    rootEntityRef (string)
31}
32
33//Attribute
34{
35    name (string),
36    value (string),
37    type (string)
38}
39

Language: json

Name: Model

Description:

[Warning: empty required content area]

1{
2    "start": 1,
3    "count": 100,
4    "hasMore": false,
5    "results": [
6        {
7            "id": "2c8cf4f0-12fa-11e9-b498-6fc6e8a6a46e",
8            "name": "snapshot",
9            "type": "ORCHESTRATION_AUDIT",
10            "accountId": "ACME",
11            "retailerId": "1",
12            "category": "snapshot",
13            "context": {
14                "sourceEvents": [
15                    "2c7bb6e0-12fa-11e9-b498-6fc6e8a6a46e"
16                ],
17                "entityType": "FULFILMENT_OPTIONS",
18                "entityId": "13cbedf0-59b0-481b-8b6f-b95531a72625",
19                "entityRef": "13cbedf0-59b0-481b-8b6f-b95531a72625",
20                "rootEntityType": "FULFILMENT_OPTIONS",
21                "rootEntityId": "13cbedf0-59b0-481b-8b6f-b95531a72625",
22                "rootEntityRef": "13cbedf0-59b0-481b-8b6f-b95531a72625"
23            },
24            "eventStatus": "SUCCESS",
25            "attributes": [],
26            "source": null,
27            "generatedBy": "Rubix User",
28            "generatedOn": "2019-01-08T04:02:11.007+0000"
29        },
30        {
31            "id": "2c87c4d1-12fa-11e9-94cb-1953d3d0bd4a",
32            "name": "Change State",
33            "type": "ORCHESTRATION_AUDIT",
34            "accountId": "ACME",
35            "retailerId": "1",
36            "category": "ACTION",
37            "context": {
38                "sourceEvents": [
39                    "2c471250-12fa-11e9-94cb-1953d3d0bd4a"
40                ],
41                "entityType": "FULFILMENT_OPTIONS",
42                "entityId": "13cbedf0-59b0-481b-8b6f-b95531a72625",
43                "entityRef": null,
44                "rootEntityType": null,
45                "rootEntityId": null,
46                "rootEntityRef": null
47            },
48            "eventStatus": "SUCCESS",
49            "attributes": [
50                {
51                    "name": "myAttribute",
52                    "value": "MY_VALUE",
53                    "type": "STRING"
54                },
55                {
56                    "name": "myOtherAttribute",
57                    "value": "MY_OTHER_VALUE",
58                    "type": "STRING"
59                }
60            ],
61            "source": "Fluent-API",
62            "generatedBy": "Rubix User",
63            "generatedOn": "2019-01-08T04:02:10.957+0000"
64        }
65    ]
66}

Language: json

Name: Sample Value

Description:

[Warning: empty required content area]

Example Error Response:

1//Errors
2{
3    errors (Error[])
4}
5
6//Error
7{
8    code (string),
9    message (string)
10}

Language: json

Name: Model

Description:

[Warning: empty required content area]

1{
2    "errors": [
3        {
4            "code": "401",
5            "message": "Invalid user, Authorization header value does not belong to a valid user"
6        }
7    ]
8}

Language: json

Name: Sample Value

Description:

[Warning: empty required content area]

[POST] /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

Parameters

Name	Description
body *Required	A valid Event Object

Responses

Response Content Type:

`application/json`

Code	Description
200	Successful Operation
401	Authorization Error - Invalid Bearer Token / No permission
400	Client Error - Bad Request

Example Request:

1//Event
2{
3    name (string, required),
4    retailerId (string, optional),          // Required if authenticated as Account User
5    rootEntityType (string, required),
6    rootEntityId (string),                  // One of 'rootEntityId' / 'rootEntityRef' required
7    rootEntityRef (string),                 // One of 'rootEntityId' / 'rootEntityRef' required
8    entityType (string, required),
9    entityId (string),                      // One of 'entityId' / 'entityRef' required
10    entityRef (string),                     // One of 'entityId' / 'entityRef' required
11    attributes (Attribute[], optional)
12}
13
14//Attribute
15{
16    name (string, required),
17    value (string, required),
18    type (string)
19}

Language: json

Name: Model

Description:

[Warning: empty required content area]

1{  
2  "name":"CancelOrder",
3  "retailerId":"1",
4  "entityType":"ORDER",
5  "entityId":"1234",
6  "entityRef":"ON-1234",
7  "attributes":{  
8     "items":[  
9        {  
10           "skuRef":"SKU_1",
11           "locationRef":"LOC_1",
12           "quantity":60
13        }
14     ]
15  }
16}

Language: json

Name: Sample Value

Description:

[Warning: empty required content area]

Example Success Response:

1{
2    id (string)
3}

Language: json

Name: Model

Description:

[Warning: empty required content area]

1{
2    "id": "46a5e2d0-2424-11e9-bd19-45eb89bb628a"
3}

Language: json

Name: Sample Value

Description:

[Warning: empty required content area]

Example Error Response:

1//Errors
2{
3    errors (Error[])
4}
5
6//Error
7{
8    code (string),
9    message (string)
10}
11

Language: json

Name: Model

Description:

[Warning: empty required content area]

1{
2    "errors": [
3        {
4            "code": "401",
5            "message": "InvalidInput, Logged in user has no retailer"
6        }
7    ]
8}

Language: json

Name: Sample Value

Description:

[Warning: empty required content area]

[POST] /event/sync Creates a new Event in the Fluent Platform for User Actions

Creates a new Event within the Fluent Platform to trigger a part or whole of a workflow synchronously.

Recommended Practice

The synchronous Event API is not recommended for external system integration. The synchronous Event API is designed to cater for User Actions initiated from the Fluent Web Apps, or a 3rd party UI.

It is not recommended for middleware and 3rd party integrations, as it is not designed to scale effectively in these contexts, and should only be used when triggered by a real user action button.

Authentication

Required

Parameters

Name	Description
body *Required	A valid Event Object

Responses

Response Content Type:

`application/json`

Code	Description
200	Successful Operation
401	Authorization Error - Invalid Bearer Token / No permission
400	Client Error - Bad Request

Example Request:

1//Event
2{
3    name (string, required),
4    retailerId (string, optional),          // Required if authenticated as Account User
5    rootEntityType (string, required),
6    rootEntityId (string),                  // One of 'rootEntityId' / 'rootEntityRef' required
7    rootEntityRef (string),                 // One of 'rootEntityId' / 'rootEntityRef' required
8    entityType (string, required),
9    entityId (string),                      // One of 'entityId' / 'entityRef' required
10    entityRef (string),                     // One of 'entityId' / 'entityRef' required
11    attributes (Attribute[], optional)
12}
13
14//Attribute
15{
16    name (string, required),
17    value (string, required),
18    type (string)
19}

Language: json

Name: Model

Description:

[Warning: empty required content area]

1{  
2  "name":"CancelOrder",
3  "retailerId":"1",
4  "entityType":"ORDER",
5  "entityId":"1234",
6  "entityRef":"ON-1234",
7  "attributes":{  
8     "cancelReason": "Fraud"
9  }
10}

Language: json

Name: Sample Value

Description:

[Warning: empty required content area]

Example Success Response:

1{
2    eventId (string),
3    entityId (string),
4    eventStatus (string)
5}

Language: json

Name: Model

Description:

[Warning: empty required content area]

1{
2    "eventId": "52929cf4-483b-4b72-b47f-e5d47ac36446",
3    "entityId": "994",
4    "eventStatus": "COMPLETE"
5}

Language: json

Name: Sample Value

Description:

[Warning: empty required content area]

Example 404 Error Response (NO_MATCH):

1{
2    eventId (string),
3    entityId (string),
4    eventStatus (string)
5}

Language: json

Name: Model

Description:

[Warning: empty required content area]

1{
2    "eventId": "52929cf4-483b-4b72-b47f-e5d47ac36446",
3    "entityId": "994",
4    "eventStatus": "NO_MATCH"
5}

Language: json

Name: Sample Value

Description:

[Warning: empty required content area]

Example Error Response:

1//Errors
2{
3    errors (Error[])
4}
5
6//Error
7{
8    code (string),
9    message (string)
10}
11

Language: json

Name: Model

Description:

[Warning: empty required content area]

1{
2    "errors": [
3        {
4            "code": "401",
5            "message": "InvalidInput, Logged in user has no retailer"
6        }
7    ]
8}

Language: json

Name: Sample Value

Description:

[Warning: empty required content area]

REST Event API

Overview

Key points

Operations

[GET] /event/{eventId} Get an Event by Id

[GET] /event Finds all events for the given criteria

[POST] /event/async Creates a new Event in the Fluent Platform

[POST] /event/sync Creates a new Event in the Fluent Platform for User Actions

Related content

APIs Overview

Batch API

Inventory Batch API

Display REST API Data in Standard Library Components

GraphQL API

Lesley Dean

Contributors:

Building Blocks

By Type

Helpful Resources

Quick Links