Orchestrator Service

overview the os1 orchestrator allows developers to automate and manage workflows across multiple distributed components with the orchestrator, you can define custom business logic, create workflows, and automate the sequence of actions across various distributed components, all through a simple api integration this guide will walk you through what you can achieve with the orchestrator real world use cases for common workflows step by step instructions for setting up and integrating the orchestrator into your system how it works example order processing let’s consider a scenario when a new order is placed, multiple tasks need to happen at once validate the shipping address encode customer information (e g , phone number) generate a work order schedule a pickup traditionally, this would require complex, tightly coupled code across multiple services the orchestrator simplifies this by providing a flexible, event driven workflow management system similarly, you can use the platform orchestrator for some of the given common scenarios in the example https //docs google com/document/d/1q3 cjmoqnivj1 hmmuxh3bur 9yvqv0u4 6 6brq3x4/edit?tab=t 0#bookmark=id syq36ysi230 section use cases by using os1, you can automate workflows that span multiple microservices, saving time, reducing complexity, and providing customization capability for each tenant the orchestrator enables you to create a single system that can handle multiple business use cases customize workflows for each tenant without changing core system architecture break complex processes into configurable, reusable components coordinate actions across multiple microservices define custom plugins for specific business logic create event driven automated processes offers scalability by managing workflows across multiple services with minimal manual intervention getting started to start using os1 orchestrator, you’ll need to integrate its key components— plugins , workflows , and rules —into your system the following sections will guide you through setting up your api access, configuring workflows, and automating your processes with real world examples prerequisites before you start using an os1 orchestrator, ensure you have access to os1 orchestrator api (you will need your api keys and credentials) (link to authentication) your application where you want to integrate the orchestrator integration steps working with orchestrator orchestrator contains three main building blocks plugins, workflow, rules 1\ plugins a plugin is a custom code module that executes tenant specific or custom business logic that has to be written and hosted by the app developer plugins are where the actual work happens each plugin is a piece of code that does one specific task a tenant can host his own set of plugins that contains tenant specific code and business logic and integrate it with the os1 orchestrator currently, you need an https api to configure the plugin with os1 plugins allow you to implement custom business rules define specific actions for different events integrate unique tenant requirements 2\ workflows a workflow is an ordered set of plugins that executes the plugins in a specific sequence—pre, main, and post—according to their priority pre a plugin that runs before the main logic main the primary business logic plugins post plugins that run after the main workflow 3\ rules a rule determines which workflow can be executed based on the specific event generated in os1 for eg you can configure a plugin workflow for encoding phone number, encoding address, etc and map it against the order created event step by step instructions for integrating clear code examples and explanations for each step screenshots or diagrams to illustrate key points integrating with orchestrator with order processing scenario to integrate orchestrator with your apps or services, you need to set up orchestrator service setting up orchestrator for an order processing scenario, the orchestrator service is enabled by default and does not require additional configuration note if you are using the entity or participant services, the orchestrator must be explicitly enabled refer to their swagger documentation for detailed api configurations to enable and utilize the orchestrator in these cases plugins are custom code modules that perform specific actions in response to events when an event occurs (such as a new order being placed), plugins define what should happen—like encoding a phone number or validating a shipping address attribute description requirement name unique name for the plugin 3 50 characters, alphanumeric httpurl endpoint to be called when the plugin executes valid https url httpmethod api method for endpoint call (e g , post, get) required responsetype the expected response type sync or async (default async) secretkey the encryption key used for plugin calls ensures secure communication by default, the plugin payload is hmac encrypted with this key and must be decoded using the same key within the plugin similarly, the plugin response must be encrypted using the same key required httprequestbodytemplate the template for the body of the http request the outputjsonpath specifies the key and value to be mapped to the corresponding key in the plugin's request payload for example, "tid" " tenantid" maps the tenantid value to the tid key in the request payload note this follows json logic semantics for specifying the value path optional, depending on your use case for example, you can create a plugin that encodes a phone number as part of your order processing workflow example { "name" "encodephoneplugin", "httpurl" "https //api example com/encode phone", "httpmethod" "post", "httpheaders" { "plugin" "phoneencoder" }, "httprequestbodytemplate" \[ { "outputjsonpath" { "tenantid" "$ tenantid", "phonenumber" "$ order customerphone", "orderid" "$ orderid" } }, { "entity" "order", "input" { "tenant id" "$ tenantid", "id" "$ orderid" }, "outputjsonpath" { "encodedphone" "$ encodedphone" } } ], "requesttimeout" 5, "responsetype" "async", "secretkey" "secret key", "protocol" "http" } in this example, when a new order is created, this plugin will encode the customer's phone number workflows allow you to define the sequence in which plugins should run for example, a workflow may first validate data and then encode it you can define workflows for different stages (pre, main, post) depending on the sequence of operations you want to execute attribute description requirement name name of the workflow alphanumeric, 3 50 characters description a short description of what the workflow does optional pluginid id of the plugin created in the plugin registration process mandatory here, we're setting up an example workflow that validates and then encodes a phone number example workflow for order processing { "workflow" { "flows" { "pre" \[ { "name" "validatephoneplugin", "description" "validates phone number format", "pluginid" "plugin 08229ce8 d2b6 5178 9d76 b946f6d2ba10" } ], "main" \[ { "name" "encodephoneplugin", "description" "encodes customer phone number", "pluginid" "plugin 2388bbd4 59cf 5b7c 8e99 42ec039726e3" } ], "post" \[] } } } this workflow validates the phone number first (pre processing) and then encodes the phone number (main processing) when a new order is created rules connect specific events to workflows they determine when your workflow should run for example, a rule might trigger a workflow when a new order is created, or when a shipment is marked as delivered configuration attribute description requirement name name of the rule alphanumeric, 3 50 characters, unique event the event that triggers the workflow e g , ordercreatedevent workflow workflow to execute when the event occurs logic conditional logic for triggering the workflow json logic expression tenantid tenant identifier for multi tenant environments required example rule for triggering workflow on order creation { "name" "orderphoneencodingrule", "event" "ordercreatedevent", "workflow" { "flows" { "main" \[ { "name" "validatephoneplugin", "description" "validates phone number", "pluginid" "plugin 2388bbd4 59cf 5b7c 8e99 42ec039726e3" }, { "name" "encodephoneplugin", "description" "encodes phone number", "pluginid" "plugin 3388bbd4 89ff 467c 8e99 42ec039456g9" } ] } }, "servicename" "orchestrator", "workflowversion" 1, "logic" { "==" \[ "$ reason", "order created" ] }, "tenantid" "default" } in this example, the rule triggers our phone encoding workflow when a new order is created check execution status once your workflow is running, you'll want to monitor its execution use this api to check the status of your workflows and plugins get https //{tenantid} {baseurl}/core/api/v1/entitystatus/dashboard/{entityid} example response { "entityid" "order 123", "status" "completed", "workflows" \[ { "name" "orderphoneencodingrule", "status" "completed", "plugins" \[ { "name" "validatephoneplugin", "status" "completed" }, { "name" "encodephoneplugin", "status" "completed" } ] } ] } examples order & dispatch service 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 for specialized scenarios like transporting hazardous chemicals, you can add custom logic to define specific routing or handling requirements suppose, the shipment contains hazardous chemicals that can only be transported by road in this case, the developer can add custom logic in the app to deliver the shipment from point a to point b using roadways transportation participant and entity service use case automating entity and participant management scenario when a new vehicle entity is created or a participant is added (such as a customer or driver), we want to automate tasks like updating related entities (e g , shipments, containers) or triggering notifications the orchestrator service will automatically handle these tasks via custom plugins when specific events occur first, ensure that the orchestrator service is enabled for both entities and participants to allow event processing json { "enableorchestrator" true } this step ensures that the orchestrator can listen to the relevant events and trigger the corresponding actions the orchestrator listens to specific events for both entities and participants, triggering actions like plugin execution entitycreationsuccessevent triggered when a new entity (e g , vehicle) is created entityupdationsuccessevent triggered when an entity is updated participantcreationsuccessevent triggered when a new participant (e g , customer or driver) is added updateparticipantsuccessevent triggered when a participant’s details are updated whenever a vehicle entity is created, we want to update related entities, such as shipments or containers the vehicle entitycreationsuccessevent is triggered when a vehicle is created the orchestrator executes a plugin to update related entities (shipment, container, etc ) the plugin updates related entities with the vehicle information now, let's define and register the custom plugins that will be executed when the relevant events are triggered the plugin registers an action to update related entities (such as shipments or containers) when the event for vehicle creation occurs this plugin triggers a job creation when a new event is detected it performs tasks like updating locations and handling other relevant details json { "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" } to automate tasks across multiple steps, we can create plugin workflows that specify a sequence of plugins to be executed in this example, we create a ruletranslatorpluginworkflow to update both the container and work order { "name" "ruletranslatorpluginworkflow", "description" "workflow to update container and workorder", "tag" \[ { "name" "ruletranslatorpluginworkflow", "value" "workflow" } ], "pre" { "plugins" \[ "fetchdata" ] }, "main" { "plugins" \[ "containerruletranslatorplugin", "workorderruletranslatorplugin" ] } } this workflow first fetches any necessary data with the fetchdata plugin, and then executes the main plugins containerruletranslatorplugin and workorderruletranslatorplugin rules specify which workflows should be executed in response to specific events for example, when a vehicle entity is created, we want to trigger the ruletranslatorpluginworkflow in this example, the rule is triggered for a createjobevent, and the associated workflow is executed only if the container type is bags { 	"name" "workflowinstancecompletedeventrule", 	"event" "createjobevent", 	"pluginworkflowid" "plugin workflow 81182a29 92f5 54a1 88a8 dd6f730a0069", 	"servicename" "orchestrator", "logic" { "and" \[ { "==" \[ "$ container type", "bags" ] } ] } }