Workflow API
Author:
Fluent Commerce
Changed on:
24 Oct 2023
Overview
A workflow defines the orchestrated business logic to be applied to an entity on a given event. A workflow consists of Workflow States and Workflow Rule Sets for an Entity. The Workflow States specify the states that the entity could be in at any given point in time. The Workflow Rule Sets specify the business rules behind the progression of these states.
Key points
- This API method supports the creation or update of a Workflow within the Fluent Platform.
- This API method validates the body of the request to ensure that the structure of the Workflow is correct.
- Requests containing invalid Workflows will respond with an error.
Property | Value |
URL | |
Methods | |
Scheme | |
Auth | |
Permissions | |
Content-Type | |
Operations
[PUT] /workflow Creates or updates an existing Workflow
This API method supports the creation or update of a Workflow within the Fluent Platform. This API method validates the body of the request to ensure that the structure of the Workflow is correct. Requests containing invalid Workflows will respond with an error (see response codes below).
Versioning is an important part of creating and updating Workflows on the Fluent Platform. To see how versions are used on the Fluent Platform, see the Workflow Versioning section of our documentation.
Authentication
WORKFLOW_VIEW, WORKFLOW_CREATE, and WORKFLOW_UPDATE permissions are required for the RETAILER context.
Parameters
Name | Description |
body *Required | A valid Workflow Object |
Responses
Response Content-Type:
`application/json`Code | Description |
200 | Successful Operation |
400 | Client Error - Bad Request |
401 | Authorization Error - Invalid Bearer Token / No permission |
403 | Forbidden |
404 | Unable to find Workflow |
500 | Error occurred whilst saving Workflow |
Example Request:
1//Workflow
2{
3 description (string),
4 entityType (string),
5 entitySubtype (string),
6 retailerId (string),
7 rulesets (Ruleset[]),
8 statuses (Status[]),
9 version (string),
10 versionComment (string)
11}
12
13//Ruleset
14{
15 name (string),
16 type (string),
17 subtype (string),
18 triggers (Trigger[]),
19 rules (RuleInstance[])
20}
21
22//Trigger
23{
24 status (string)
25}
26
27//RuleInstance
28{
29 name (string),
30 props (object)
31}
32
33//Status
34{
35 name (string),
36 entityType (string),
37 category (string)
38}Language: json
Name: Model
Description:
[Warning: empty required content area]1{
2 "description": "A custom Workflow for Order Customer Collection",
3 "entityType": "ORDER",
4 "entitySubtype": "CC",
5 "retailerId": "1",
6 "rulesets": [
7 {
8 "name": "CC",
9 "type": "ORDER",
10 "subtype": "CC",
11 "triggers": [
12 {
13 "status": "CREATED"
14 }
15 ],
16 "rules": [
17 {
18 "name": "FLUENTRETAIL.base.ChangeState",
19 "props": {
20 "status": "CCSTATUS"
21 }
22 }
23 ]
24 },
25 {
26 "name": "HD",
27 "type": "ORDER",
28 "subtype": "HD",
29 "triggers": [
30 {
31 "status": "CREATED"
32 }
33 ],
34 "rules": [
35 {
36 "name": "FLUENTRETAIL.base.ChangeState",
37 "props": {
38 "status": "HDSTATUS"
39 }
40 }
41 ]
42 }
43 ],
44 "statuses": [
45 {
46 "name": "HDSTATUS",
47 "entityType": "ORDER",
48 "category": "BOOKING"
49 },
50 {
51 "name": "CCSTATUS",
52 "entityType": "ORDER",
53 "category": "BOOKING"
54 },
55 {
56 "name": "CREATED",
57 "entityType": "ORDER",
58 "category": "BOOKING"
59 },
60 {
61 "name": "",
62 "entityType": "",
63 "category": "BOOKING"
64 }
65 ],
66 "version": "1.4",
67 "versionComment": "Making minor change to Workflow"
68}Language: json
Name: Sample Value
Description:
[Warning: empty required content area]Example Success Response:
1{
2 entityId (string),
3 eventStatus (string)
4}Language: json
Name: Model
Description:
[Warning: empty required content area]1{
2 "entityId": "1-ORDER::CC::1.0",
3 "eventStatus": "COMPLETE"
4}Language: json
Name: Sample Value
Description:
[Warning: empty required content area]Example Error Response:
1//Error
2{
3 entityId (string),
4 eventStatus (string),
5 error (ErrorMessage),
6 warning (ErrorMessage)
7}
8
9//ErrorMessage
10{
11 message (string),
12 code (string),
13 workflowValidationError (WorkflowValidationError[]),
14}
15
16//WorkflowValidationError
17{
18 type (string),
19 code (string),
20 attributes (Attribute[]),
21}
22
23//Attribute
24{
25 name (string),
26 value (string),
27 type (string)
28}Language: json
Name: Model
Description:
[Warning: empty required content area]1{
2 "entityId":"0.0",
3 "eventStatus":"FAILED",
4 "error":{
5 "code":400,
6 "workflowValidationError":[
7 {
8 "type":"ERROR",
9 "code":"RULE_NOT_FOUND",
10 "attributes":{
11 "name":"FLUENTRETAIL.base.ChangeState"
12 }
13 }
14 ]
15 },
16 "warning":{
17 "code":400,
18 "workflowValidationError":[
19 {
20 "type":"WARN",
21 "code":"UNUSED_CATEGORY_FOUND",
22 "attributes":{
23 "categories":[
24 {
25 "name":"HDSTATUS",
26 "entityType":"ORDER",
27 "category":"BOOKING"
28 }
29 ]
30 }
31 }
32 ]
33 }
34}Language: json
Name: Sample Value
Description:
[Warning: empty required content area][GET] /workflow/{retailerId}/{workflowRef}/{workflowVersion} Retrieve an existing Workflow
Returns a specific version of a workflow from the Fluent Platform.
Authentication
Required
Permissions
WORKFLOW_VIEW permission is required for the RETAILER context.
Parameters
Name | Default Value | Description |
retailerId | - | The ID of the Retailer who owns the Workflow |
workflowRef | - | The identifier of the Workflow which is in the format |
workflowVersion | - | The version of the Workflow being requested which is in the format |
Responses
Response Content-Type:
`application/json`Code | Description |
200 | Successful Operation |
400 | Client Error - Bad Request |
401 | Authorization Error - Invalid Bearer Token / No permission |
403 | Forbidden |
404 | Unable to find Workflow |
500 | An error occurred whilst retrieving Workflow |
Example
Request:
`https://<AccountId>.sandbox.api.fluentretail.com/api/v4.1/workflow/1/ORDER::CC/1.4`Response:
1//Workflow
2{
3 createdBy (string),
4 createdOn (string),
5 description (string),
6 entityType (string),
7 entitySubtype (string),
8 id (string),
9 name (string),
10 retailerId (string),
11 rulesets (Ruleset[]),
12 statuses (Status[]),
13 version (string),
14 versionComment (string)
15}
16
17//Ruleset
18{
19 name (string),
20 type (string),
21 subtype (string),
22 triggers (Trigger[]),
23 rules (RuleInstance[])
24}
25
26//Trigger
27{
28 status (string)
29}
30
31//RuleInstance
32{
33 name (string),
34 props (object)
35}
36
37//Status
38{
39 name (string),
40 entityType (string),
41 category (string)
42}Language: json
Name: Model
Description:
[Warning: empty required content area]1{
2 "createdBy": "RET28cbef60",
3 "createdOn": "2019-07-10T05:21:25.712+0000",
4 "description": "A custom Workflow for Order Customer Collection",
5 "entityType": "ORDER",
6 "entitySubtype": "CC",
7 "id": null,
8 "name": "ORDER::CC",
9 "retailerId": "1",
10 "rulesets": [
11 {
12 "name": "CC",
13 "type": "ORDER",
14 "eventType": "NORMAL",
15 "rules": [
16 {
17 "name": "FLUENTRETAIL.base.ChangeState",
18 "props": {
19 "status": "CCSTATUS"
20 }
21 }
22 ],
23 "triggers": [
24 {
25 "status": "CREATED"
26 }
27 ],
28 "userActions": []
29 },
30 {
31 "name": "HD",
32 "type": "ORDER",
33 "eventType": "NORMAL",
34 "rules": [
35 {
36 "name": "FLUENTRETAIL.base.ChangeState",
37 "props": {
38 "status": "HDSTATUS"
39 }
40 }
41 ],
42 "triggers": [
43 {
44 "status": "CREATED"
45 }
46 ],
47 "userActions": []
48 }
49 ],
50 "statuses": [
51 {
52 "name": "HDSTATUS",
53 "entityType": "ORDER",
54 "category": "BOOKING"
55 },
56 {
57 "name": "CCSTATUS",
58 "entityType": "ORDER",
59 "category": "BOOKING"
60 },
61 {
62 "name": "CREATED",
63 "entityType": "ORDER",
64 "category": "BOOKING"
65 },
66 {
67 "name": "",
68 "entityType": "",
69 "category": "BOOKING"
70 }
71 ],
72 "version": "1.4",
73 "versionComment": "Making minor change to Workflow"
74}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": "InvalidInput, Logged in user has no retailer"
6 }
7 ]
8}Language: json
Name: Sample Value
Description:
[Warning: empty required content area][GET] /workflow Search for Workflows belonging to a Retailer
Returns a list of Workflows filtered by the given combination of parameters.
Authentication
Required
Permissions
WORKFLOW_VIEW permission required for the RETAILER context.
Parameters
Name | Default Value | Description |
retailerId | - | The unique Retailer Id |
accountId | - | The unique Account Id |
start | 1 (i.e. index 0) | The offset of results |
count | 10 | Number of results shown |
sort | | Sorting options requested |
name | - | Name of the workflow. e.g. |
latest | false | True returns the latest workflow Versions for all Root Entities |
Responses
Response Content-Type:
`application/json`Code | Description |
200 | Successful Operation |
400 | Client Error - Bad Request |
401 | Authorization Error - Invalid Bearer Token / No permission |
403 | Forbidden |
404 | Unable to find Workflow |
500 | An error occurred during the search |
Example
Request:
`https://<AccountId>.sandbox.api.fluentretail.com/api/v4.1/workflow?retailerId=1&name=ORDER::CC`Example Success Response:
1//SearchResponse
2{
3 count (integer),
4 start (integer),
5 total (integer),
6 retailerId (string),
7 results (Workflow[]),
8 sort (string)
9}
10
11//Workflow
12{
13 version (string),
14 name (string),
15 entityType (string),
16 entitySubtype (string),
17 description (string),
18 versionComment (string),
19 createdBy (string),
20 createdOn (date)
21}Language: json
Name: Model
Description:
[Warning: empty required content area]1{
2 "count": 10,
3 "start": 1,
4 "total": 2,
5 "retailerId": "1",
6 "results": [
7 {
8 "version": "1.9",
9 "name": "ORDER::CC",
10 "entityType": "ORDER",
11 "entitySubtype": "CC",
12 "description": "A custom Workflow for Order Customer Collection",
13 "versionComment": "Making minor change to Workflow",
14 "createdBy": "RET28cbef60",
15 "createdOn": "2019-07-10T05:17:50.055+0000"
16 },
17 {
18 "version": "1.6",
19 "name": "ORDER::CC",
20 "entityType": "ORDER",
21 "entitySubtype": "CC",
22 "description": "A custom Workflow for Order Customer Collection",
23 "versionComment": "Making minor change to Workflow",
24 "createdBy": "RET28cbef60",
25 "createdOn": "2019-07-10T05:17:10.426+0000"
26 }
27 ],
28 "sort": "createdOn DESC"
29}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": "InvalidInput, Logged in user has no retailer"
6 }
7 ]
8}Language: json
Name: Sample Value
Description:
[Warning: empty required content area]
