Support & Operations Activities

An introduction: Activities

In this lesson, we'll talk about some activities and tasks that may need to be undertaken from an operational point of view as part of Fluent application support and maintenance. Topics in this lesson include:

• Plugin Management
• Workflow Versioning 
• Audit Events

Plugin Management

Plugins are separately built artifacts containing one or more rules that can be uploaded and installed into the Fluent Workflow Framework to be used during workflow execution.

For a Developer or a Technical Lead, some common plugin management tasks include:

• Uploading plugins
• Activating plugins
• Viewing the active/inactive version of plugins
  • Checking which version of the plugin is active
  • Rolling back/forward between the previous and new versions
• Retrieving all the rules that are currently available in an account
• Managing custom rules on custom plugins

Using the Plugin API

The Plugin API provides methods for uploading, installing, and viewing Plugins.

Here's a quick look at the API:

Next, we look at the operations of the Plugin API.

With the Plugin API, you can conduct the following operations:

[GET] - returns the list of all rules that are active in an ACCOUNT

• Authentication: Required
• Permissions: PLUGIN_VIEW permission required for the ACCOUNT context.
• Responses: Response Content Type- application/json

`https://{{accountId}}.sandbox.api.fluentretail.com/orchestration/rest/v1/plugin`

[GET] / {bundleName}/status - returns the upload/installation status and other metadata of the specified plugin bundle. Only bundles that belong to the logged-in account can be viewed:

• Authentication: Required
• Permissions: PLUGIN_VIEW permission is required for the ACCOUNT context.
• Responses: Response Content Type - application/json

`https://{{accountId}}.sandbox.api.fluentretail.com/orchestration/rest/v1/plugin/{{accountId}}.fulfilment::2.0.3/status`

Understanding Workflow Versions

Before we look at the activities that surround workflow versions, let's understand what Workflow Versions are.

Within the Fluent Platform, all workflows are versioned. Any modification of an existing workflow by a Retailer automatically creates a new version.

Here are some things to remember about workflow versions.

• A major version represents a major change in the flow, such as adding a new state transition and new business logic.
• A minor change involves changing parameters, such as changing the email template for customer notifications or updating the expiry time of articles.

Okay, now that we've discussed Workflow versions, let's discuss the tasks and activities surrounding them.

Activities

Here are some activities that can be carried out around Workflow Versions:

• Submit a new version of the workflow
• Check what different workflow versions exist
• Get an extract of all the workflows that are currently available
• Go back and retrieve a particular workflow version

The Workflow API supports the following operations:

[PUT] - used for uploading a new workflow

`https://{{accountId}}.sandbox.api.fluentretail.com/api/v4.1/workflow`

[GET] - used to retrieve existing workflows.  This can be used to: 

• Return the latest current and historical workflows
• Return the latest version of the workflow declared in the URL
• Return a specific version of a workflow as declared in the URL

`https://{{accountId}}.sandbox.api.fluentretail.com/api/v4.1/workflow?retailerId={{retailerId}}&count=100`

`https://{{accountId}}.sandbox.api.fluentretail.com/api/v4.1/workflow/{{retailerId}}/ORDER::HD`

`https://{{accountId}}.sandbox.api.fluentretail.com/api/v4.1/workflow/{{retailerId}}/ORDER::HD/2.53`

Audit events

Orchestration Audit Events

Orchestration Audit Events record what has happened during orchestration processing. They are essentially a log of all activities for a particular entity and contain information valuable for determining what and how an entity was processed through a workflow. They also provide the most useful mechanism for debugging orchestration issues.

There are 3 different ways to view audit events:

• Event API (e.g. using Postman)
• Event Search (see Insights in Fluent OMS web app)
• Activity tab (inside Order detail view in Fluent OMS web app)

Audit Events are automatically generated by the Workflow Engine and include a number of categories that define what the audit event is about. 

Audit Event categories:

Snapshot — This event prints out a snapshot of the orchestrated entity at the time the event is triggered inside of the Workflow Engine.

• Why is it useful? : To see the state of the entity before the process is executed.

Ruleset — For each and every ruleset executed within a process, a Ruleset Audit event is created. 

• Why is it useful? : To trace the workflow path taken by the entity during that event or process.

Rule —  For each and every rule executed within a ruleset, a Rule Audit event is created

• Why is it useful? : To trace all rules executed in sequence within a process and determine what the last rule executed was in the case of an exception or interruption in processing. It can also be used to capture an audit of each entity's status change or webhook sent by filtering to those rules.

Action — An Action Audit event is created for each action produced from a Rule. 

• Why is it useful? : To validate if an expected Action was produced during processing.

Exception — An Exception Audit event is written whenever an exception is thrown from a Rule, back into the Workflow Engine. 

• Why is this useful? : To debug 'what exception has occurred' and 'why'. More importantly, it will log the stack trace of the exception. Therefore, it's important for Rule writers to make sure the real source exception is thrown or included as the cause of the exception being thrown from the Rule.

Additionally, the Log Action creates a custom Audit event. This is useful for Rule developers to provide additional audit information to the Audit log that is not included in the system-generated audit events.

Audit Event Structure

Like any Event, the Audit Event contains context information such as the Root Entity and Entity type, status, and ID / Ref. It also includes a timestamp, which is useful for reporting and analyzing processing and fulfillment times. Additional information is written in the Event Attributes array.

1{
2      “id”: “a3f154c0-3e19-11ed-a11c-198b938d27af”,
3      “name”: “Change State”,
4      “type”: “ORCHESTRATION_AUDIT”,
5      “accountId”: “FCTRAINAU1000",
6      “retailerId”: “1",
7      “category”: “ACTION”,
8      “context”: {
9        “sourceEvents”: [
10          “a37c24c0-3e19-11ed-b70a-0f9894474e93”
11        ],
12        “entityType”: “FULFILMENT_OPTIONS”,
13        “entityId”: “5c40405c-d647-4b11-825f-7d53aacc7983”,
14        “entityRef”: “FO_6081”,
15        “rootEntityType”: “FULFILMENT_OPTIONS”,
16        “rootEntityId”: “5c40405c-d647-4b11-825f-7d53aacc7983”,
17        “rootEntityRef”: “FO_6081”
18      },
19      “eventStatus”: “SUCCESS”,
20      “attributes”: [
21        {
22          “name”: “toStatus”,
23          “value”: “OPTIONS_PROVIDED”,
24          “type”: “STRING”
25        },
26        {
27          “name”: “startTimer”,
28          “value”: 1664251536270,
29          “type”: “STRING”
30        },
31        {
32          “name”: “stopTimer”,
33          “value”: 1664251536366,
34          “type”: “STRING”
35        }
36      ],
37      “source”: “94862882.CREATE”,
38      “generatedBy”: “Rubix User”,
39      “generatedOn”: “2022-09-27T04:05:36.366+0000"
40    }