Platform Order Attributes and Lifecycle

Platform Order Attributes

Platform Order Attributes are divided into the following categories:

  • Core: These are pre-defined attributes by the CoreOS Platform. Although, some of these attributes are optional.
  • System: These are system-defined attributes that indicate the current order state. These attributes can only be updated by the Platform Order Orchestrator.
  • Custom: These attributes are defined and configured by the Tenant depending on the use case. With these attributes, the Tenant can set up custom validations and mark them as indexed or non-indexed.
    • Indexed: These are attributes that users can utilize to apply filters and retrieve specific data.
    • Non-indexed: Users are not permitted to apply filters on these attributes and query the order data.
CategoryAttribute NameData Type ExpectedDescription
CoreTenant IDStringThe ID of the Tenant to whose realm the Order belongs.
SystemOrder IDUUIDSystem-generated order ID (unique across Tenants).
CoreClient NameVarChar
CoreClient IDVarCharClient Participant ID.
CoreClient Order IDVarCharThis is the reference ID for the Order that was generated by the Client. This may not be unique in the Tenant’s universe.
CoreReady To ProcessBooleanBy default, readyToProcess is set to true.
If it is set to false, the order will be created but it blocks job creation.
It can be updated from false to true only.
True - Move from Created to In Progress state automatically (by orchestrator).
False - Order will remain in the "Created" state and it will wait for an external command for moving it to In Progress state.
CoreCustomer/Consignee ContactVarCharUsers have the option to provide either contact details or a Contact ID. If contact details are provided, the service will automatically generate and store a Contact ID, as contact details are considered personally identifiable information (PII).
It's important to note that a contact phone number is expected to be a single phone number and not a list.
The attributes "Name" and "Phone" are grouped together under the key "contact".
CoreCustomer/Consignee Location IDUUIDAlthough the address will be passed in a standard address format for consumption Platform Order Service, it will be stored as a Location in Location Service. The corresponding Location ID will be stored here.
CoreWork Orders Execution Flow TypeEnumSpecifies the order in which the multiple work orders of an order will be executed by the orchestrator.

- SEQUENTIAL (Default)
CoreCancellation RequestedBooleanBy default, this attribute will be false. However, it can be set to True by the cancel API. The result of the cancellation attempt (async process), will eventually get updated in the system attributes CancelationStatus and CancelationStatusTimestamp.

- Cancellation requests should be rejected with a suitable error code if a cancellation request is already in process.
- If a cancellation request leads to Cancellation Failure, this field should still retain its True status.
- If a new cancellation request arrives after the previous request has been successful or failed, the request should be accepted and the Cancellation Status and Cancellation Status Timestamp need to be reset.
SystemCancellation Requested On (optional)Timestamp
SystemCancellation Requested By (optional)VarChar
SystemCancellation Status (optional)Enum- NONE - default
SystemCancellation Failure Reason Code (optional)VarChar
SystemCancellation Status Timestamp (optional)TimestampIf Order Canceled is True, this field indicates the Date/Time at which the order was canceled.
CustomCustom Attributes
1-to-n (indexed)
Key-valueCustom attributes for an Order with indexing. The tenant will be able to configure validations, if required, for these attributes.
CustomCustom Attributes
1-to-n (non-indexed)
Key-valueCustom attributes for an Order without indexing. The tenant will be able to configure validations, if required, for these attributes.
SystemWork Order List (optional)ListList of Work Order data.
SystemCurrent State (optional)VarCharStores the state of the Order
SystemCurrent Sub-state (optional)VarChar
CoreorderSummary (optional)
orderSummary>>InvoiceNumber (optional)StringInvoice Number associated with the order. Could contain alphabets and numbers.
minLength: 3
maxLength: 64
pattern: ^[a-zA-Z0-9:_-]*$
orderSummary>>orderDescriptionStringDescription of the Order. Could contain details on the type of Order, its contents, etc.
minLength: 1
maxLength: 256
pattern: ^([a-zA-Z])([a-zA-Z0-9,\s]*)$
orderSummary>>totalWeight (optional)
Total weight of the order information needed.
orderSummary>>totalItems (optional)NumberTotal number of containers in the order.
maximum: 1000
orderSummary>>totalOrderCostThe total cost of an Order
SystemSchema Version (optional)IntegerThe version of the order schema configuration (for custom attributes) that was active at the time of order creation.
SystemupdatedAt (optional)Timestamp
SystemCreated By (optional)VarChar
SystemUpdated By (optional)VarChar


Platform Order Orchestrator

The Platform Order Orchestrator allows tenants to pre-configure workflows for executing Work Orders. These workflows are based on the Work Order Type and are designed to create subsequent jobs necessary for fulfilling larger Work Orders. By utilizing the assigned workflow, current status, and external plugins, the Platform Order Orchestrator determines the next action required for seamless execution.

Creating Platform Custom Order Attribute

To create a Platform Order Custom Attribute, call the POST /config/attributes endpoint and pass the following parameters in the request body:

ParameterDescriptionValidationData type
nameName of the attribute.minLength: 1 maxLength: 32 pattern: ^[a-zA-Z]{1,32}$string
descriptionDescription of the attribute.minLength: 0 maxLength: 256 pattern: ^([a-zA-Z])([a-zA-Z0-9,\s]*)$string
datatypeThe data type of the Attribute.Valid values: string, number, boolean, object, array, moneystring
validationSpecifies all the validations that can be applied to Order attributes.
indexedSpecifies whether the Attribute is indexed. Filter or search operation based on a custom attribute is only allowed if this field is set as TRUE.boolean

Note: Some of the core Platform Order attributes can be updated. These attributes are listed below:

  • DropDetails
    • contact
    • location
  • OrderSummary
    • invoiceNumber
    • orderDescription
    • totalWeight
    • totalItems
    • totalOrderCost
    • readytoprocess(false to true only)

The following sample payload shows how to create Platform Order Custom Attributes namedstringValidations and intValidations:

  "attributes": [
      "name": "maxAttempts",
      "dataType": "number",
      "indexed": false,
      "validation": {
        "required": false
      "defaultValue": 1,
      "securityLevel": "OPEN",
      "delete": false
      "name": "stringValidations",
      "description": "string",
      "indexed": true,
      "dataType": "string",
      "validation": {
        "range": {
          "min": 0,
          "max": 5
        "regex": "string",
        "valueOneOf": [
        "required": false
      "name": "intValidations",
      "description": "int",
      "indexed": true,
      "dataType": "number",
      "defaultValue": 1,
      "validation": {
        "range": {
          "min": 0,
          "max": 5
        "valueOneOf": [
        "required": true

Platform Order Lifecycle

A Platform Order has the following six lifecycle states:

  • Initiated: In this state, the Client Order and its respective Work Orders are registered in Platform Order Service and are awaiting validation confirmation from the external plugin (if configured).
  • Created: Once the Order is validated using the external plugins (if configured), the entries are created for Work Order. This state means one of the following:
    • The Order is validated but awaiting the ‘Ready To Process’ signal.
    • The Order is validated and is ‘Ready To Process’ but it is yet to be picked up by Order Orchestrator.
  • In-progress: This state signifies that at least one Work Order of the Order is being processed, i.e., a job has been created for the Work Order by the orchestrator, and at least one Work Order is in the ‘In-progress’ state.
  • On-hold: This state can be used by Apps to put the state transitions in cases where orders are temporarily withdrawn from their execution/fulfillment lifecycle. It is an additional option that can be opted out by the user. If this state is used, it will put Work Orders and associated Jobs on hold this means that the associated Job can not be assigned to Dispatch.
  • Executed: This state signifies that all the Work Orders of the Order have been ‘Completed’.
  • Closed: This state signifies one of the following:
    • The order was executed and all post-execution processes (for example, billing, payment, collection) for the Order have been ‘Completed’.
    • The Order validation 'Failed'.
    • The Order was ‘Canceled’ before the execution was started.

Order Lifecycle

Platform Order Service provides the Tenant with an option to configure sub-states under any of the six lifecycle states and the rules governing the corresponding state and sub-state transition.

State transition Rules

  • The state transition to and from the Initiated state will be managed and triggered by the Platform Order Service only.
  • If the Order is set to On Hold, the state of the job will be on hold and it will not get assigned for Dispatch.
  • When the ready to process is set to false, all transitions to non-terminal states are restricted. This means that transitions such as "created to in-progress" and "created to on hold" will only occur when the "readyToProcess" is set to true, which can be achieved through an external update API.