1 General overview
2 Principle
- 2.1 Interface and tools
  - 2.1.1 Interface interactions
  - 2.1.2 Diagram details
    - 2.1.2.1 Starting state
    - 2.1.2.2 Transition
- 2.2 Entities
  - 2.2.1 Order workflow
    - 2.2.1.1 Order
    - 2.2.1.2 Line Item Group
    - 2.2.1.3 Parcel
    - 2.2.1.4 Bundle
  - 2.2.2 Return parcel workflow
    - 2.2.2.1 Return Parcel
    - 2.2.2.2 Return Line Item Group
  - 2.2.3 Store and Warehouse workflow
    - 2.2.3.1 Endpoint Order
    - 2.2.3.2 Piece Group
    - 2.2.3.3 Containers
    - 2.2.3.4 Operators
- 2.3 Condition
- 2.4 Action
- 2.5 Operation of the workflow
  - 2.5.1 Trigger a transition
    - 2.5.1.1 Automatic
    - 2.5.1.2 Manual
  - 2.5.2 Process of the transition
    - 2.5.2.1 Operation : A transition is triggered
    - 2.5.2.2 Technical Specificity :
      - 2.5.2.2.1 Cascading principle
3 How to configure
- 3.1 Available conditions
- 3.2 Available actions
  - 3.2.1 Notification Parameters:

General overview

The Order Management System is the core service that handles multiple entities linked to orders in OneStock: Orders, articles, parcels.

To handle the different entities, API routes are detailed in the documentation for each action on order elements (Creation, modification, retrieval).

Once an entity is created in the system, it follows a path that is configured in the Order Management Center called “Order Life Cycle” or “Workflow”. This path allows to define the different possible states for an order, an article, or a parcel.
Depending on interconnected property, status, or attribute, the entity will transition from a state to another, and a list of linked action will be activated.
Transitions are triggered automatically or manually through app or API interactions.

The purpose of the Workflow is to :

Define states for an entity
Allow transitions between controlled states
Apply actions

Example of Order workflow

This workflow is custom built to replicate the fulfillment management of an order, an article, or a parcel. Thus it is configured to reflect the unique business capabilities of any entity for a retailer.

Match the existing business capabilities with the configured Workflow

Define what actions and changes are technically allowed through via the configuration.

Principle

There is 3 different categories of workflows in OneStock :

Order workflow
Return parcel workflow
Store and Warehouse workflows

Order workflow is dedicated to treating orders, articles, parcel and bundles in OneStock. This workflow allows to integrate, manage stocks, orchestration and delivery to an order. It is a mandatory workflow to use OneStock as an OMS.

Return parcel workflow is specifically dedicated to create and handle return parcels. If this workflow is missing, no returns will be possible. (More informations here).

Store and Warehouse workflows shaped to handle entity flows for the Store App. They are required to make the Store App usable for a stock location, and critical to process orders through the app.

Interface and tools

All workflows have the same interface and works using same mechanism for consultations and modifications.

In the following, we detail what are the user capabilities through the interface, and what are the interpretation of visual information for technical purpose.

Interface interactions

The base mode of the order lifecycle is the view mode to consult all existing workflows.

Create a new view to filter graphs, and save.

View allows to filter and save a workflow display

Use action filters to quickly spot the transitions that contains a targeted action you want to identify.

Watch all the conditions and action by clicking on the transition.

To modify your workflow, create a draft and enter the draft mode.

To add a state in a graph, use the state dropdown, or right clic on a free space.

To add a condition or an action, click on the targeted transition (or starting state), and use the dedicated button.

For advanced users, a code mode is available for display and modification of workflow actions and conditions.
The code mode is accessible on global, entity workflow view (by clicking on the three dots option), or in the transition detail (by using the right tab).

To activate the modified workflow once modifications are done, publish the draft by clicking on the dedicated button. When a draft is published, all workflows are published at the same time.
If necessary, it is possible to cancel all the modifications by deleting the draft.

If deleted, a draft cannot be retreived

Diagram details

Starting state

When defining an entity, a starting state needs to be defined. Only one state can be tagged as a start state. It is recognizable by its dotted border.
This first state is the only one having the possibility to execute actions after its creation.

If you want to add new states, we recommend adding a state that is already included in the mapping detailed here: BI Suite. This will automatically be taken into account in our data analyses.

However, you can still create a 100% customized state, but you must follow these two points :

State names must contain ONLY lowercase letters and underscores.
Notify your Onestock contact so that they can modify the mapping for data analyses

Transition

Transitions are links having a starting and a arrival state. It has a defined unique direction.

Transitions can be either Automatic or Manual. Automatic transitions are dotted arrows, while manual transition are plain arrows.

Pending > Orchestrating : Automatic transition
Pending > Paid : Manual transition

Automatic transitions are triggered by a update_{entity}_state action without information on the target state. On the other hand, Manual transitions are triggered by a update_{entity}_state action with the target state, or by an API update of the entity.

Entities

Order workflow

Order

Orders are created through API or through the store app. Once an order is posted by the system, the entity is created and the dedicated action are launched.

Line Item Group

Line item groups are filled in within the POST /order details. They are created at the same time than the order. Dedicated actions are simultaneously launched.

Parcel

Parcels are either created during the workflow process or using API through integration layers. Actions are then processed at the moment of the creation, through delayed action or at the moment of the POST /parcel .

Bundle

Bundles are completely automated. The entity is created when the item ID corresponding to the bundle is detected, at the moment of the Line Item Group creation.

Return parcel workflow

Return Parcel

Return parcels are created through API, through the store app or using the dedicated extension. Once a return is posted by the system, the entity is created and the linked action are launched.

Return Line Item Group

Return line item groups are filled in within the POST /return parcel details. They are created at the same time than the return parcel and actions are simultaneously launched.

Store and Warehouse workflow

Every entity of the Store and Warehouse workflow are created by the partial order preparation system (Store and Warehouse workflows). Those entities are mandatory to run the Store app.

Endpoint Order

Representing a part of the order. An endpoint order is the entity similar to orders, but linked to a stock location. It is created as soon as one line item group of the order is claimed.

Piece Group

Alike a line item group, a piece group represents an item that needs to be prepared by a stock location. In the workflow, the piece group is created when a line item group is claimed by a stock location.

Containers

Containers are entities representing holding entities. Similar to a parcel, the embed other piece group (thus articles) or other containers depending on their nature.
Generally, a container are used to define the mean used to handle an article, such as Bag, Box, Trolley, etc.

Operators

Operators are workflow entities used to represent users interacting with containers. Though the workflow, operators are taking actions on other entities.

Condition

Conditions can be applied either for a transition or an action.

For a transition, a condition allows or blocks a change of state.

It is highly recommended to use conditions on automatic transitions. When multiple transitions are possible if an automatic transition is triggered, the OMS will raise an error.

For an action, a condition is used to define if the action is activated during the sequence.

Action

Actions can affect different entities or fields of the OMS. Some actions are mandatory to run OneStock services properly.
Eg : Reservation, Stock update, Dynamic tag, etc…

Actions are run in the sequence they are configured.

Each action require different parameters. Our interface helps the user identify the mandatory fields for an action to run.

There are multiple type of action possible :

Transition Triggers a transition for an entity
Enrichment Add details in an entity
Consumption Consumption of an element of a service
Deletion Deletion of an entity or element
Creation Creation of an entity or element
Update Modification of an element
Launch Start a service process

Operation of the workflow

Trigger a transition

Automatic

Automatic transitions can be triggered two ways :

Using the Transition action without any targeted state parameter in the workflow

Using a specific service that triggers a transition : Orchestration, Stocks, etc…

When an automatic transition is triggered without information on the target state, every reachable states conditions will be tested.
Make sure to have exclusive condition between each reachable state to avoid having errors.

If other automatic transition follows after the destination state, those following condition will be tested as well.
Make sure that the following conditions can be tested with all the detail available from the root status to avoid any error.

Manual

Transition can be triggered manually by 3 different ways :

Using API call to patch an entity using field from as a starting state, and to as the targeted state (Please see the API documentation)
Using the backoffice pages : Dropdowns for each entity allow the user to trigger a transition to an accessible state

Through the workflow using the Transition action with the targeted state parameter

Process of the transition

Operation : A transition is triggered

Conditions
Verification that the entity is matching the condition for the transition
Transition
The entity switch to the new state
Action
The configured action are then operated

Actions are processed in the same sequence they are configured
Depending on conditions, an action may not be run
In case of multiple entity trigger or multiple workflow, actions are run respecting the cascading principle (see technical specificity bellow)

Technical Specificity :

Order of the sequence of action is respected

Technically : The entity switch to the new state, then actions are done. This means conditions on actions need to be adapted to the targeted state.

Cascading principle

Actions on another entity are triggered at the moment of the “update_{entity}_state”. Then the remaining actions are run.

Action to another workflow happens AFTER every actions of the same workflow are processed.

How to configure

Config generator based Workflow.

The config generator ask you Q&A on the site needs and generates a base configuration as an output that matches the answers and allows a compatibility with most services.

As a result, the base workflow is refined depending on the questions to add dedicated states and actions.

Available conditions

Entity or field tested	Name	Parameters	Description	Available on the following workflows

Entity or field tested	Name	Parameters	Description	Available on the following workflows
Order	`order_in_states`	`states` (required) : The list of states to compare against the states of the order	Verify that the order linked to the entity is in one of the `states`	line_item_group parcel piece_group
Line item groups	`all_line_item_groups_in_states`	`states` (required) : A list of states to compare with the states of the `line_item_groups`	Verify that all the `line_item_groups` of the entity have their state included in the `states` list. For an order, the verification is performed on all its `line_item_groups`. For a parcel, the verification is performed on all `line_item_groups` contained within it. For a line_item_group, the verification is performed on itself.	line_item_group order parcel
Line item groups	`one_line_item_group_in_states`	`states`: (required) A list of states to compare with the state of the `line_item_group`	Verify that at least one line_item_group is on of the `states`	order parcel piece_group
Line item groups	`all_line_item_groups_in_parcels`	`in_states` : list of line item groups' states to consider	Verify that all the `line_item_groups` of the entity, whose state is in the `in_states` list, are correctly included in a parcel. Other `line_item_groups` are not taken into account.	line_item_group order parcel
Parcels	`all_parcels_in_states`	`states` (required) : A list of states to compare with the states of the `parcels`	Verify that all parcels have their state included in the list of states (`states`). For an order, the verification is performed on all its parcels. For a line_item_group, the verification is performed on the parcel containing it. For a parcel, the verification is performed on the parcel itself.	line_item_group order parcel
Piece group	`all_piece_groups_in_states`	`states`: The list of states to compare against the states of the piece groups	Verify that all `piece_groups` of the `line_item_groups` linked to the entity are in a specified list of states. If there are no `line_item_groups` linked to the entity, return true.	line_item_group order parcel
Parcel	`one_parcel_in_states`	`states` (required): The list of states to compare against the states of the parcels. `same_endpoint`: Indicates whether to check: True: Only parcels whose origin matches the endpoint of the request. False: All parcels in the order. `all_parcels`: Determines the scope of the parcels to check: True: All parcels in the order are considered. False: Only parcels directly linked to the entity are considered.	Verify that at least one of the parcel linked to the entity is in one of the `states`	line_item_group order parcel piece_group
Bundle	`all_bundles_in_states`	`states` (required) : list of bundle states to compare	Verify that all the bundles of the entity have their state included in the list of `states`.	line_item_group
Containers	`container_in_states`	`states` (required) : A list of states to compare with the states of the `parcels` `if_exists` : `false` boolean to return if a `parcel` doesn’t have any associated container	Verify that all containers have their state included in the list of `states`. Retrieve the linked parcels and call the `pop` function to obtain the states of the associated containers.	line_item_group order parcel
Piece group	`one_piece_group_in_states`	`states` : The list of states to compare against the states of the piece group	Verify that at least one of the piece group linked to the entity is in one of the `states`	line_item_group order parcel
Order	`delivery_type_is`	`type:` type of delivery	Verify that the delivery type of the entity associated to the order is equal to `type`.	line_item_group order parcel
Order	`order_type_is`	`in`: A list of types where at least one must match the order's type. `only`: A list of types that must exactly match the order's type. `out`: A list of types where none should match the order's type. Only one of these parameters (`in`, `only`, or `out`) can be specified at a time.	Verify the type of the order	line_item_group parcel piece_group
Stocks	`has_global_reservation` Warning The verification is not performed on `line_item_groups` that already have an `endpoint_id`. Therefore, it must be tested either before an `assign_origin` operation or after a `remove_origin` operation.		Verify that a `line_item_group` has a global reservation done	line_item_group
Stocks	`in_stock`	`stock_types`: A list of stock types to consider for the condition. `from`: A timestamp used to filter the stock to be considered. `to`: A timestamp used to filter the stock to be considered. `use_orchestration_rule_stock_constraints`: If set to true, uses stock constraints defined in the orchestration rules, corresponding to the globally reserved stock. This parameter must not be used for orders that do not go through orchestration (e.g., `ckc_ready`, `ropis`). Doing so will cause an error because the `line_item_group` will not have an associated `endpoint_id`, which is required to filter stock during retrieval.	Checks if the line item group's endpoint has enough stock to serve the line. If stock is lesser than the line item group's quantity, the condition will fail. Key request used to check for stock is `in_stock`. When retrieving stock, it will be filter by the line item group's endpoint. `endpoint_filters.use_requested_ids` must equal true for the filter to work. The line item group must be attributed to an endpoint at the time of checking this condition, otherwise the condition will fail. Autoclaim actions, claims done through de Store App and claims by API containing an endpoint ID, must send the endpoint ID required for filtering. In the case of a missing endpoint ID, the transition will return a 400 error code. If `use_orchestration_rule_stock_constraints` equals true, filters `stock_types`, `from` and `to` in the `in_stock` stock request will be ignored	line_item_group
Stock location (endpoint)

Workflows