Orchestrator Service
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.
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
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
In addition to handling Order and Dispatch events, the Orchestrator can handle events related to Entities and Participants. Here
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.
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 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
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:
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
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
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.
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.