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 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.

Category	Attribute Name	Data Type Expected	Description
Core	Tenant ID	UUID	The ID of the Tenant to whose realm the Order belongs.
System	Order ID	UUID	System-generated order ID (unique across Tenants).
Core	Client ID	VarChar	Client Participant ID.
Core	Client Order ID	VarChar	This is the reference ID for the Order that was generated by the Client. This may not be unique in the Tenant’s universe.
Core	Ready To Process	Boolean	The default value will be true. True- Move from Created to In Progress state automatically (by orchestrator). False- Order will remain in the Created state and wait for an external command to move it to In Progress state.
Core	Customer/Consignee Name	VarChar
Core	Customer/Consignee Phones	List of PII IDs	List of PII IDs for phone numbers. Although the phone numbers will be passed as raw phone numbers for consumption of Platform Order Service, they will be converted into PII IDs and stored here.
Core	Customer/Consignee Location ID	UUID	Although 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.
Core	Work Orders Execution Flow Type	Enum	Specifies the order in which the multiple work orders of an order will be executed by the orchestrator. START_TOGETHER COMPLETE_TOGETHER SEQUENTIAL
Core	Cancellation Requested	Boolean	By 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 needs to be reset.
System	Cancellation Requested On (optional)	Timestamp
System	Cancellation Requested By (optional)	VarChar
System	Cancellation Status (optional)	Enum	NONE - default PENDING ATTEMPTING SUCCESS FAILED
System	Cancellation Failure Reason Code (optional)	VarChar
System	Cancellation Status Timestamp (optional)	Timestamp	If Order Canceled is True, this field indicates the Date/Time at which the order was canceled.
Custom	Custom Attributes 1-to-n (indexed)	Key-value	Custom attributes for an Order with indexing. The tenant will be able to configure validations, if required, for these attributes.
Custom	Custom Attributes 1-to-n (non-indexed)	Key-value	Custom attributes for an Order without indexing. The tenant will be able to configure validations, if required, for these attributes.
System	Work Order List (optional)	List	List of Work Order IDs.
System	Current State (optional)	VarChar	state: substate
System	Current Sub-state (optional)	VarChar
System	Schema Version (optional)	Integer	The version of the order schema configuration (for custom attributes) that was active at the time of order creation.
System	Created On (optional)	Timestamp
System	Updated On (optional)	Timestamp
System	Created By (optional)	VarChar
System	Updated By (optional)	VarChar

Creating Platform Custom Order Attribute

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

Parameter	Description
`name`	Name of the attribute.
`description`	Description of the attribute.
`datatype`	The data type of the Attribute. Valid values: string, number, boolean, object, array.
`validation`	Specifies all of the validations that are performed on the Attribute when an order of this type is created or updated.
`indexed`	Specifies whether the Attribute is indexed. Filter or search operation on the basis of a custom attribute is only allowed if this field is set as TRUE.

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

{
  "attributes": [
    {
      "name": "stringValidations",
      "description": "string",
      "indexed": true,
      "dataType": "string",
      "validation": {
        "range": {
          "min": 0,
          "max": 5
        },
        "regex": "string",
        "valueOneOf": [
          "string123",
          "string124"
        ],
        "required": false
      }
    },
    {
      "name": "intValidations",
      "description": "int",
      "indexed": true,
      "dataType": "number",
      "defaultValue": 1,
      "validation": {
        "range": {
          "min": 0,
          "max": 5
        },
        "valueOneOf": [
          0,1,2,3,4,5
        ],
        "required": true
      }
    }
  ]
}

Platform Order Lifecycle

A Platform Order has the following five lifecycle states:

Initiated: This is the state where 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) then 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 not yet 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 this Work Order by the orchestrator and at least one Work Order is in the ‘In-progress’ state.
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.

Platform Order Service provides the Tenant an option to configure sub-states under Initiated, Executed, and Closed 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 already set as Ready To Process, state transition to and from the Created state will be managed and triggered by the Platform Order Service only.
If the Order is not set as Ready To Process, the state transition from Created to In-progress state will be triggered by setting the order as Ready To Process through an external API call.
A state transition from the In-progress state to Executed state will be managed and triggered by Order Service only.