OS1 Services

Orchestrator Service

19min

Overview
The Orchestrator service manages and coordinates events across multiple services within the OS1 platform. It listens to events related to orders, dispatch, entities, and participants and then executes specific custom plugins registered by developers. These plugins perform specific business logic in response to various events.
Enabling Orchestrator for Participants and Entities
To utilize the Orchestrator service to execute custom plugins on participant and entity events, you must set the enableOrchestrator attribute to true when creating or updating entity and participant types. Enabling this attribute allows the Orchestrator service to listen to and manage events for participants and entities and execute the registered custom plugins.
Example
JSON
{
  "enableOrchestrator": true
}

{
  "enableOrchestrator": true
}
﻿
Entity and Participant Events
We have included the following events for the Participant and Entity services for developers to apply execution rules on. 
Entity
EntityCreationSuccessEvent 
EntityUpdationSuccessEvent
ApplyEventSuccessEvent
Participant
ParticipantCreationSuccessEvent
UpdateParticipantSuccessEvent
ApplyEventParticipantSuccessEvent
﻿
Use Cases for Entity and Participant Events
In addition to handling Order and Dispatch events, the Orchestrator can handle events related to Entities and Participants. Here 
Entity Management
Scenario: Automatically update related entities when a new vehicle entity is created.
Event Triggered: vehicle-EntityCreationSuccessEvent
Orchestrator Action: When a vehicle entity is created, trigger the plugin to update related entities.
Plugin Action: Update other related entities with information from the newly created vehicle entity.
Use Cases Order and Dispatch
You can use the Platform Orchestrator for some of the given common scenarios:
Orchestrating different OS1 entities.
Creating a job for a new work order
Updating container and work order status based on job updates
Creating the next job once the previous leg is completed, etc.
For example, in the Order and Dispatch service, the Orchestrator will handle various shipment events such as failure to deliver, shipment delivered, or the customer refusing to accept the package. The Orchestrator processes these events according to the rules. In some cases, manual intervention is required, such as when a facility manager finds a damaged package. The system will continue to create work orders for such cases until the issue is resolved and the case is closed.
The tenant can add custom logic based on business requirements.
For example, suppose the shipment contains hazardous chemicals that can only be transported by road. In that case, the developer can add custom logic in the app to deliver the shipment from Point A to Point B using roadways transportation.
For more details, read an End-to-End Use Case﻿.
﻿
Plugin Management
Plugin Management oversees Plugins which essentially represent custom business logic supplied to the Orchestrator, and the developer can customize them according to the business requirement. For example, if a shipment arrives at an unexpected destination, the developer will determine the subsequent steps and create a new job based on the business logic, which is implemented as a Plugin.
OS1 provides a set of default Plugins to accommodate different scenarios, depending on the information provided by the businesses. Additionally, these Plugins can be configured independently by businesses based on their logic.
Whenever an event is triggered, the Orchestrator processes it through the rule engine, identifies the relevant Plugin, and calls upon it. Once the Plugin response is received, the Orchestrator takes action according to the Plugin’s instructions.
Registering Plugins
Establishing a Plugin Workflow.
Creating Rules
Register Plugin
Here, we have shown a sample payload for registering a Plugin with its attributes explained briefly.
Attribute Name
Description
Validation
Data Type
name*
The name of the Plugin
minLength: 3  
maxLength: 50  
pattern: ^[a-zA-Z0-9]$
string
description
(Optional)
Description of the Plugin
minLength: 3  
maxLength: 256
string
httpURL*
URL endpoint to be called when the plugin is executed
https/?://(www.)?[-a-zA-Z0-9@:%.+#=]{1,256}.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%+.#?&//=])
string
httpMethod*
API method with which the endpoint is called.
﻿
string
httpHeaders
(Optional)
Headers to be included in the request body for the Plugin API call
﻿
One of the:  String  Number
httpRequestBodyTemplate*
Template for getting plugin API request Body
minItems: 1
﻿
dlqOnFailure 
(Optional)
Push to DLQ if Plugin execution fails
﻿
boolean
requestTimeout
(Optional)
Timeout for an API request to return the response in seconds.
Example: 20  
Default: 5
number
callbackTimeout
(Optional)
Timeout for Plugin API to return a callback response in seconds.
Example: 20  
Default: 5
number
responseType*
The type of response that API will return can be - SYNC/ASYNC
Default: async
string
protocol
(Optional)
Plugin Protocol can be - HTTP/GRPC
Default: HTTP
string
secretKey*


The secret key for HMAC authentication at the callback handler level.
﻿
string
maxConcurrentCalls
(Optional)
The maximum number of concurrent calls allowed for a specific Plugin API at a time.
﻿
integer
The attributes marked with (*) are mandatory attributes for creating a Plugin. 
Sample JSON for Registering Plugin:
Register Plugin
{
   "name": "createJobPlugin",
   "httpUrl": "https://delhivery.preprod.fxtrt.io/core/api/v1/jobManager/",
   "httpMethod": "POST",
   "httpHeaders": {
       "plugin": "jobManager"
   },
   "httpRequestBodyTemplate": [
       {
           "outputJsonPath": {
               "tenantId": "$.tenantId",
               "pickupLocation": "$.workOrders[0].pickupDetails.location",
               "deliverLocation": "$.dropDetails.location",
               "deliverContact": "$.dropDetails.contact",
               "orderId": "$.orderId",
               "workOrderId": "$.workOrders[0].id"
           }
       }
   ],
   "dlqOnFailure": true,
   "requestTimeout": 5,
   "callbackTimeout": 5,
   "responseType": "ASYNC",
   "secretKey": "SECRET_KEY",
   "protocol": "HTTP"
}
{
   "name": "createJobPlugin",
   "httpUrl": "https://delhivery.preprod.fxtrt.io/core/api/v1/jobManager/",
   "httpMethod": "POST",
   "httpHeaders": {
       "plugin": "jobManager"
   },
   "httpRequestBodyTemplate": [
       {
           "outputJsonPath": {
               "tenantId": "$.tenantId",
               "pickupLocation": "$.workOrders[0].pickupDetails.location",
               "deliverLocation": "$.dropDetails.location",
               "deliverContact": "$.dropDetails.contact",
               "orderId": "$.orderId",
               "workOrderId": "$.workOrders[0].id"
           }
       }
   ],
   "dlqOnFailure": true,
   "requestTimeout": 5,
   "callbackTimeout": 5,
   "responseType": "ASYNC",
   "secretKey": "SECRET_KEY",
   "protocol": "HTTP"
}
﻿
Plugin Workflow
Here, we have shown a sample payload for creating a Plugin Workflow with its attributes explained briefly.
Here's your data converted into a markdown table:
Attribute Name
Description
Validation
Data Type
name*
Name of the Plugin Workflow
minLength: 3  
maxLength: 50  
pattern: ^[a-zA-Z0-9]$
string
description*
Description of the Plugin Workflow
minLength: 3  maxLength: 256
string
tag (Optional)
key-value pair
minLength: 3  
maxLength: 50  
pattern: ^[a-zA-Z0-9]$
string
pre plugins
(Optional)
List of Plugins to be initiated
minLength: 3  
maxLength: 50  
pattern: ^[a-zA-Z0-9]$
string
main plugins*
List of Plugins to be initiated sequentially
minLength: 3  
maxLength: 50  
pattern: ^[a-zA-Z0-9]*$
string
The attributes marked with (*) are mandatory attributes for creating a Plugin. 
﻿
Sample JSON for Plugin Workflow
JSON
{
    "name": "RuleTranslatorPluginWorkflow",
    "description": "workflow to update container and workOrder",
    "tag": [
        {
            "name": "RuleTranslatorPluginWorkflow",
            "value": "workflow"
        }
    ],
    "pre": {
        "plugins": [
            "fetchData"
        ]
    },
    "main": {
        "plugins": [
            "ContainerRuleTranslatorPlugin",
            "WorkOrderRuleTranslatorPlugin"
        ]
    }
}
{
    "name": "RuleTranslatorPluginWorkflow",
    "description": "workflow to update container and workOrder",
    "tag": [
        {
            "name": "RuleTranslatorPluginWorkflow",
            "value": "workflow"
        }
    ],
    "pre": {
        "plugins": [
            "fetchData"
        ]
    },
    "main": {
        "plugins": [
            "ContainerRuleTranslatorPlugin",
            "WorkOrderRuleTranslatorPlugin"
        ]
    }
}
﻿
Rules
Rules are defined for calling a particular Plugin. Here, we have shown a sample payload for establishing Rules with their attributes explained in brief.
Here's your data converted into a markdown table:
Attribute Name
Description
Validation
Data Type
name*
Name of the rule.
^[a-zA-Z][a-zA-Z ]{2,35}$
string
event*
Description of the Plugin Workflow.
minLength: 3  maxLength: 256
string
pluginWorkflowID*
Workflow that is associated with the event.
^[a-zA-Z0-9][a-zA-Z0-9_:-]{0,63}$
string
logic
(Optional)
JSON logic to be validated against the input request.
﻿
Any of:  Number  String  Boolean
WorkflowVersion
(Optional)
Workflow version of the Plugin Workflow ID specified
﻿
number
ServiceName*
Name of the CoreOS service with which the Plugin is associated.
^[a-zA-Z]{2,36}$
string
The attributes marked with (*) are mandatory attributes for creating a Plugin. 
Sample JSON for Creating Rules
Create Rule
{
	"name": "WorkflowInstanceCompletedEventRule",
	"event": "CreateJobEvent",
	"pluginWorkflowId": "plugin-workflow:81182a29-92f5-54a1-88a8-dd6f730a0069",
	"serviceName": "orchestrator",
  "logic": {
            "and": [
                {
                    "==": [
                        "$.container_type",
                        "bags"
                    ]
                }
            ]
        }
}

{
	"name": "WorkflowInstanceCompletedEventRule",
	"event": "CreateJobEvent",
	"pluginWorkflowId": "plugin-workflow:81182a29-92f5-54a1-88a8-dd6f730a0069",
	"serviceName": "orchestrator",
  "logic": {
            "and": [
                {
                    "==": [
                        "$.container_type",
                        "bags"
                    ]
                }
            ]
        }
}
﻿
Default Plugins
Below are some default Plugins that the Orchestrator listens to and executes:
﻿Job Manager Plugin﻿ - This Plugin interprets the current event and creates or updates a job accordingly.
﻿Work Order Manager Plugin﻿ - This Plugin interprets the current event and updates an existing work order as needed.
﻿Container Manager Plugin﻿ - This Plugin interprets the current event and updates an existing container as required.
﻿Workflow Manager Plugin﻿ - This Plugin reads the current event data from configuration files and determines which job workflow to use and what input data is needed.
﻿Cancellation Manager Plugin﻿ - This Plugin cancels a job or work order based on the received events.
How an End-to-End Use Case in CoreOs is solved using Orchestrator
﻿
To execute an order, a single service is not sufficient. Instead, an Orchestrator must coordinate events and trigger different services through Plugin Management based on specific events and responses.
When an order gets created, it triggers an event to create a Work Order in the Order Service as defined by the Rules. This event calls the Workflow Manager Plugin to retrieve current event data from configuration files, which calls the Job Manager Plugin.
The Job Manager Plugin interprets the current event and creates a new job or updates an existing one, if necessary. It then notifies the Orchestrator to call the Dispatch service and create a job.
Thus, any changes made in the Order service will impact the Dispatch service through the Orchestrator and Plugins. Ultimately, this process creates a Job command for the Dispatch service.
Try Orchestrator APIs.

Attribute Name	Description	Validation	Data Type
name*	The name of the Plugin	minLength: 3 maxLength: 50 pattern: ^[a-zA-Z0-9]$	string
description (Optional)	Description of the Plugin	minLength: 3 maxLength: 256	string
httpURL*	URL endpoint to be called when the plugin is executed	https/?://(www.)?[-a-zA-Z0-9@:%.+#=]{1,256}.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%+.#?&//=])	string
httpMethod*	API method with which the endpoint is called.		string
httpHeaders (Optional)	Headers to be included in the request body for the Plugin API call		One of the: String Number
httpRequestBodyTemplate*	Template for getting plugin API request Body	minItems: 1
dlqOnFailure (Optional)	Push to DLQ if Plugin execution fails		boolean
requestTimeout (Optional)	Timeout for an API request to return the response in seconds.	Example: 20 Default: 5	number
callbackTimeout (Optional)	Timeout for Plugin API to return a callback response in seconds.	Example: 20 Default: 5	number
responseType*	The type of response that API will return can be - SYNC/ASYNC	Default: async	string
protocol (Optional)	Plugin Protocol can be - HTTP/GRPC	Default: HTTP	string
secretKey*	The secret key for HMAC authentication at the callback handler level.		string
maxConcurrentCalls (Optional)	The maximum number of concurrent calls allowed for a specific Plugin API at a time.		integer

Attribute Name	Description	Validation	Data Type
name*	Name of the Plugin Workflow	minLength: 3 maxLength: 50 pattern: ^[a-zA-Z0-9]$	string
description*	Description of the Plugin Workflow	minLength: 3 maxLength: 256	string
tag (Optional)	key-value pair	minLength: 3 maxLength: 50 pattern: ^[a-zA-Z0-9]$	string
pre plugins (Optional)	List of Plugins to be initiated	minLength: 3 maxLength: 50 pattern: ^[a-zA-Z0-9]$	string
main plugins*	List of Plugins to be initiated sequentially	minLength: 3 maxLength: 50 pattern: ^[a-zA-Z0-9]*$	string

Attribute Name	Description	Validation	Data Type
name*	Name of the rule.	^[a-zA-Z][a-zA-Z ]{2,35}$	string
event*	Description of the Plugin Workflow.	minLength: 3 maxLength: 256	string
pluginWorkflowID*	Workflow that is associated with the event.	^[a-zA-Z0-9][a-zA-Z0-9_:-]{0,63}$	string
logic (Optional)	JSON logic to be validated against the input request.		Any of: Number String Boolean
WorkflowVersion (Optional)	Workflow version of the Plugin Workflow ID specified		number
ServiceName*	Name of the CoreOS service with which the Plugin is associated.	^[a-zA-Z]{2,36}$	string

Updated 17 Sep 2024

Did this page help you?

How to: Implement Custom Code in Dispatch Service

Integrate with Orchestrator