Participant

Introduction

A Participant is an Organization, asset, or individual that either creates or performs tasks. It is represented by a set of required and optional attributes and is governed by its state.

This topic discusses the different types of Participants, their data object model, APIs to create and update Participants, their lifecycle, and permissible states.

To best understand Participants, know their types. Each type of participant will help you understand how it is interconnected to the Platform. Moreover, how you can use them in your logistic business model.

For a quick start guide on creating Participants, see Creating Participants.

Types of Participants

Using the Core APIs of OS1 Platform any type of participants commonly used in logistics operation can be defined and represented. Examples of some common participants are below

Type

Description

Tenant

A Tenant is an Organization that has subscribed to the Platform. Tenants can create and govern the custom usage of their Platform instance for their Participants by configuring workflows and business models.

Client

Clients are the business entities that own customer relationships and submit orders to the Platform.

Operator

Operators are the business entities that onboard Users, Vehicles, Facilities, and Devices to complete tasks associated with fulfilling a customer order.

Vehicle

A Vehicle is used to move goods from Point A to Point B and aid in moving Individuals, shipments, and tools to provide services at a location.

User

Users represent the human resources scheduled, allocated, and used to perform the work of a Participant Organization.

Facilities

Facilities represent the list of physical operational facilities or locations and their capabilities. Operational locations can be seller locations, hubs, PCs, FCs, DCs, etc.

Devices

Devices represent the list of physical machines or hardware that is used for processing and/or fulfilling orders. An operator is responsible for registering the devices that are used to complete order(s).

Examples of devices are sorters, GPS devices, handheld devices, etc.

Custom Participant Type

In addition to the above pre-defined Participant types, Tenants have the option of defining custom Participant types that their processes might require. Custom Participant types allow for better classification of a Tenants' business entities.

19201920

Creating Participant Types

The Participant Service provides an asynchronous API and a library to onboard different types of Participants.

🚧

After a Participant type is created, you cannot delete it and its singular and plural names are immutable.

To create a Participant type, call the Create a new participant type endpoint and pass the following values in the request body:

Member

Description

singular

A unique singular name that represents a single participant of this participant type.

plural

A unique plural name that defines multiple participants of this participant type.

ttl

Specifies the Time-to-live (TTL) for a Participant of this Participant type in the transaction database.

callback

The URL endpoint to call after the Participant type creation is completed.

name

Name of the category that needs to be updated.

description

Description of the category.

subCategory

The subCategory.

To update a Participant type, call the Update participant type configuration endpoint and pass the members to update.

Request bodies are specified in JSON format. The following examples show a request body for creating a Participant type and a request body for updating a Participant type:

{
  "name": {
    "singular":"vehicle",
    "plural":"vehicles"
  },
  "category": [
    {
      "name": "twoWheeler",
      "description": "The participant vehicle has a category named twoWheeler.",
      "subCategory": [
        "gearless"
      ]
    }
  ],
  "ttl" : "10d",
  "callback":"https://examplecallbackurl.com"
}
{
   "ttl": "99d",
   "callback":"http://examplecallbackurl.com"
}

Attributes of a Participant

The Participant object supports two kinds of Attributes:

  • Base: These are the Attributes that are pre-defined by the Platform for the Participant. Some of these Attributes are required.
  • Custom: These are the Attributes that the Tenant defines for the Participants, to enhance their usability. Tenants can define custom validations, and also specify whether they are indexed or non-indexed.

Predefined Attributes

The following table provides a list of predefined attributes:

Attribute Name

Category

Description

Data Type Expected

Tenant ID

Base

The ID of the Tenant to whose data domain the Participant belongs. In the case of aParticipant Type Tenant, the Participant ID and Tenant ID are the same.

UUID

Participant ID

Base

This is a system-generated ID, that is expected to be unique within a Tenant.

VarChar

Participant Type

Base

The type of Participant.

VarChar

Participant Code

Base

A user-understandable unique code is provided by the Onboarding Entity. It is unique within the Tenant and the Participant type. For example, Vehicle Registration No., Facility ID, Employee ID, etc.

VarChar

Participant Owner ID

Base

The ID of the Participant to which this Participant belongs. For a Vehicle owned by an Operator, it is the Operator ID. For a Client, it is the Tenant ID. For a Tenant, it is the Participant ID of the Tenant itself.

VarChar

Participant Name
(Optional)

Base

A name is provided by the Onboarding entity for the participant. For example, Amazon India (Client), Delhivery Trucking (Operator).

VarChar

Participant State
(Optional)

Base

The current state of the participant. On Participant creation, the default state is set as ‘Onboarding’ (or default sub-state of ‘Onboarding’ state, if defined).

VarChar

Attributes 1 to n (Indexed)

Custom

Custom attributes for a participant type with indexing. If required,the Tenant is able to configure validations for these attributes.

Key-value

Attributes 1 to n (Non-Indexed)

Custom

Custom attributes for a participant type without indexing. If required, the Tenant is able to configure validations for these attributes.

Key-value

📘

INFO

Created-by, Created-On, Updated-by, and Updated-On for any operation done to the database need to be captured and maintained at the system level.

Creating a new Participant

To create a Participant, call the Create a new participant endpoint and pass the following values in the request body:

Member

Description

owner

The ID of the Participant to whom this Participant belongs. For example: For a vehicle owned by an operator, the owner id it is the operator id. For a Client, it is the Tenant ID. For a Tenant, it is the Participant ID of the Tenant itself.

uniqueCode

Unique code identifying the participant.

name

Name of the participant.

properties

Key-Value representation of all core attributes of the participant.

callback

Represents callback URL, which can be to notify status(success/failed) of API.

To update a Participant, call the Update core attributes of a participant endpoint and pass the members to update.

Request bodies are specified in JSON format. The following examples show a request body for creating a Participant and a request body for updating a Participant:

{
   "owner":"worldlogistics:06676c3b-ab94-48cf-9435-dbe92f2dfcdf",
   "uniqueCode":"295A41M44WPHHZVO",
   "name":"John Doe",
   "properties":{
      "region":"Europe",
      "email":"[email protected]",
      "firstname":"John",
      "lastname":"Doe"
   },
   "callback":"http://examplecallbackurl.com"
}
{
  "properties": {
      "region":"Africa",
      "email":"[email protected]",
      "name":"Jack"
      }
}

Creating Custom Attributes

To create a Custom Attribute, call the Get core attributes configurations of a participant type and pass the following values in the request body:

Member

Description

name

Name of the Attribute to be added or updated.

description

Description for the custom attribute.

dataType

The data type of the Attribute. Valid values: string, number, boolean, object, array.

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.

validation

Specifies all of the validations that are performed on the Attribute when a Participant of this type is created or updated.

range`

Specifies the range of values for the Attribute. In the case of the "string" data type, the range is the length of the string. min specifies the min value, inclusive. and max specifies the max value, inclusive.

callback

Specifies a callback URL that is used to notify the calling of the result status of the call.

The following shows a sample request body for creating a custom Attribute:

{
   "attributes":[
      {
         "name":"MemberSince",
         "description":"Year when the participant onboarded the Platform",
         "dataType":"string",
         "indexed":false,
         "defaultValue":"2012",
         "validation":{
            "range":{
               "min":1,
               "max":10
            },
            "required":false
         }
      }
   ],
   "callback":"http://examplecallbackurl.com"
}

📘

Important Note regarding Custom Attribute creation

  • If the attribute is already defined for the participant type, the validation rules for the Attribute are updated.
  • If the attribute is not defined for the participant type, it is added as a new core attribute for the participant type.
  • On successful execution of the call, all updates for the Participant type take effect immediately.
  • If the remove key is defined (list of attribute names), validation rules for this Attribute are removed from the Custom Attributes configuration for this participant type.

Getting Started with Participant Service

Participant Layer: Instance Creation

Participant Service Instance Creation is divided into three distinct layers that are collectively called Participant Layers. Any new instance of the Platform consists of setting up Participants so that they can perform transactions on the Platform. The instance creation process consists of the following layers: Tenant Setup, Participant Registration and Integration, and User Management.

Layer 1: Tenant Setup

Any instance of a platform starts with creating a tenant. And the tenant is an entity that manages and governs data objects on the platform.

To add multiple participants to the platform, you first need to set up Tenants. The Tenant is created during the onboarding of an Organization on the platform. At the time of creation, each Tenant is assigned a unique account ID called tenantId.

Layer 2: Participant Registration and Integration

This layer provides registration and integration tools to Participants so that they can perform transactions on the platform and further onboard clients, operators, and resources. In simple words, in this layer, the Tenants added in the first layer are able to onboard other Participants & complete the integration process.

  1. Participant Registration
    All Participants are registered as an entity on the Platform. The registration process will enable the Participants to make them discoverable on their capabilities/needs and can perform transactions on the platform. The registration process has the following step:
  • Create a Participant entity with company information, contact details, billing information, etc.
  • A unique Participant entity identifier called “Master Account” is created for the Participant.
  • A participant entity once registered can now onboard themselves as a client, operator, or resource.
  1. Participant Service Registry
    A Participant entity can register for one or more participant services.
  • Client Registration: A Participant entity can register as a client. A client registry includes basic information required so that the client can discover and perform transactions on the platform. A unique client ID is created and mapped to the participant master account.
  • Operator Registration: A Participant entity can register as an operator and onboard the service offerings that they provide so that it is discoverable on the platform. A unique operator identifier is generated and mapped to the Participant entity master account.
  • Resource Registration: An operator can register the resources that are used to complete order(s). Resource registration depends on the type of resource being onboarded (People, Device, Vehicle, Facility).
  1. Participant Integration

After a Participant is registered, it can integrate with the platform to request or fulfill an order. Integration of Participants involves connecting with Order management, Contract, User, Billing, Reports, and Event Updates services using APIs.

Layer 3: User Management

This layer provides a set of tools and services to manage User identity through authentication and User access through permission on the platform.

Lifecycle of a Participant

Using the Participant Service, we have onboarded Participants on the Platform. Each participant on the Platform will have its own lifecycle.

A lifecycle is the series of forms into which a participant changes as it develops. By looking at the lifecycle, we can find out the current status of a participant. A participant typically can move between different states and sub-states on the basis of workflows set in the application using it.

19201920

The platform will provide a default of three states for a participant:

Onboarding

The onboarding state depicts that a Participant is currently undergoing the registration process and is not ready to be used yet. Example- Any approval workflow can be built under this state.

Active

The active state denotes that a Participant has completed registration and can be used for operational duties.

Inactive

The inactive state signifies that data is now marked for archiving (removed from the transactional database and moved to the data warehouse) unless the Participant is moved to the Active state within ‘X’ hours (configurable) of the time at which the current state has been triggered.

The tenant will define the duration after which they would like to move Inactive participants to the data warehouse (the default value is 72 hours).

As we pointed out above in this documentation, a tenant also has the authority to introduce sub-states under each of the States and the rules governing the corresponding state transitions. Check out the State Machine Service to know more about State and State Transitions.

Tenant Level Configurability & Extensibility​

As discussed above, a tenant acts as a super-user and has its dedicated instance on the platform. The Tenants can create and govern custom usage of their platform instance for their participants by configuring workflows and business models.

Here are the configurations that a tenant can configure within the participant service. These are both in terms of participant attributes and their lifecycle:

Attribute level Configurability

  • As we know, there are some system-defined participant types, and other than those, tenants can add new custom participant types. Note that a tenant is not authorized to delete system-defined participant types from the configuration.
  • Tenants have complete control over defining additional participant types.
  • Tenants can define a set of custom attributes for every Participant type.
  • For each custom attribute, the tenant may tag the attribute to one or more attribute groups (Ex- Legal, Contact Details, Financial, etc.). Authorization to Users to access attribute information at the attribute group level. Attributes without any group are accessible to all.
  • Tenants can define the duration after which they would like to move Inactive participants to the data warehouse (default 72 hours).

Lifecycle Configurability

  • Tenants have the option to define a list of event names.
  • For each State, Tenants have the option to define a set of sub-states and the corresponding rules for State transition.
  • For each State, a sub-state (configurable by tenant) is kept as default. Transitions from a state/ sub-state to another state will always happen to the default sub-state of the destination State. For more information about State and Transition, see State Machine Service.

Did this page help you?