What are Fluent OMS Entities? (Entity)

What are Entities?

The entity is a data object that can store and process data. For example, an order entity stores customer order-related information as an object within OMS, and the order entity data can be used or processed later in the order journey.

Each entity contains a defined set of fields and connections for storing the relevant data. For example, an

`order->type`

`order->fulfilments`

`BOOKED`

`CANCELLED`

`COMPLETE`

Most transactional entities have attribute fields available where users can use attributes to store specific values that can be used for the downstream workflow.  

What do you need to know about Entities?

The Entity is accessible by using GraphQL. Using order as an example again, the

`createOrder`

`updateOrder`

`orderByID`

`orders`

Removing Entities

As a SaaS platform, entities cannot (should not) be deleted in OMS. Typically, the user should use the status field to control the entity's functionality.  However, some "remove" mutations allow the user to remove the connection between entities, whereas update mutations cannot remove the connections for certain entities—for example,

`removeNetworkFromLocation`

`removePermissionsFromRole`

Orchestratable Entity

The orchestratable entity is an entity whose life cycle can be orchestrated by a workflow. This means the different status this entity can be in, and any update of the entity should be done via its workflow. 

The list of Orchestratable Entities can be found in the GraphQL Orchestrateable Reference.

Here is an example of the

`OrderCancel`

1[{
2    "name": "OrderCancel",
3    "description": "Cancels order",
4    "type": "ORDER",
5    "subtype": "HD",
6    "eventType": "NORMAL",
7    "rules": [
8        {
9            "name": "{ACCOUNTID}.core.SetState",
10            "props": {
11                "status": "CANCELLED"
12            }
13        },
14        {
15            "name": "{ACCOUNTID}.order.SendEventForAllFulfilments",
16            "props": {
17                "eventName": "CancelFulfilment"
18            }
19        }
20    ],
21    "triggers": [
22        {
23            "status": "CREATED"
24        },
25        {
26            "status": "RECEIVED"
27        },
28        {
29            "status": "BOOKED"
30        }
31    ],
32    "userActions": [
33        {
34            "context": [
35                {
36                    "label": "CANCEL ORDER",
37                    "type": "PRIMARY",
38                    "modules": [
39                        "adminconsole"
40                    ],
41                    "confirm": true
42                }
43            ],
44            "attributes": []
45        }
46    ]
47},
48{
49    "name": "CancelFulfilment",
50    "description": "Cancels all the fulfilments when the order is cancelled,sends an event to inventory catalog to reset any reserved inventory against the fulfilment",
51    "type": "FULFILMENT",
52    "eventType": "NORMAL",
53    "rules": [
54        {
55            "name": "{ACCOUNTID}.order.CancelFulfilment",
56            "props": null
57        },
58        {
59            "name": "{ACCOUNTID}.order.SendEventToUpdateInventoryQuantity",
60            "props": {
61                "eventName": "UpdateInventoryQty",
62                "operation": "UNRESERVE",
63                "retailerId": "5000299",
64                "inventoryCatalogueRef": "DEFAULT:5000299"
65            }
66        }
67    ],
68    "triggers": [
69        {
70            "status": "CREATED"
71        },
72        {
73            "status": "PROCESSING"
74        },
75        {
76            "status": "AWAITING_WAVE"
77        }
78    ],
79    "userActions": []
80}
81]

Here is an example of the EVENT API call for the

`OrderCancel`

1POST: {{fluentApiHost}}/api/v4.1/event/async
2
3{
4  "name": "OrderCancel",
5  "accountId": "{ACCOUNTID}",
6  "retailerId": "5000299",
7  "rootEntityRef": "HD_789535507",
8  "rootEntityType": "ORDER",
9  "entityRef": "HD_789535507",
10  "entityType": "ORDER",
11  "attributes": {
12    "CANCEL_REASON": "CREDIT FAILED"
13  }
14}
15
16
17

As you can see in the example, the workflow is orchestrated from the EVENT API call

`OrderCancel`

`OrderCancel`

`CancelFulfilment`

`CancelFulfilment`

`updateOrder`

Orchestratable Entities that send a CREATE event

Here is the list of "Orchestratable Entity" if successfully created, will generate a CREATE event associated with the mutation:

• Order
• Fulfilment
• Article
• Wave
• Fulfilment Option
• Fulfilment Plan
• Product Catalogue
• Standard Product 
• Variant Product
• Category
• Inventory Catalogue
• Inventory Position
• Inventory Quantity
• Return Order
• Return Fulfilment
• Billing Account
• Credit Memo
• Invoice
• Payment
• Payment Transaction

Where do Fluent Commerce Entities fit in the Digital Commerce Journey?

Fluent Commerce's key domain entities serve unique purposes for different stages of the digital commerce journey. Workflows bring these entities and their purposes to life. The table below explains where each is used.

Green cells indicate a direct relationship between an entity and that stage of the workflow, while light green cells indicate that the entity is only partially involved. For example, the

`fulfilment`

`fulfilment`

See the video below on how to look for statuses within a workflow, you can learn more about entities and their available statuses in the Fulfilment and Order reference modules.