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

TypeDescription
TenantA 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.
ClientClients are the business entities that own customer relationships and submit orders to the Platform.
OperatorOperators are the business entities that onboard Users, Vehicles, Facilities, and Devices to complete tasks associated with fulfilling a customer order.
VehicleA 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.
UserUsers represent the human resources scheduled, allocated, and used to perform the work of a Participant Organization.
FacilitiesFacilities represent the list of physical operational facilities or locations and their capabilities. Operational locations can be seller locations, hubs, PCs, FCs, DCs, etc.
DevicesDevices 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.

1920

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:

MemberDescriptionValidationData type
singularA unique singular name that represents a single participant of this participant type.pattern: ^[a-zA-Z]{1,16}$
minLength: 1
maxLength: 16
example: vehicle
string
pluralA unique plural name that defines multiple participants of this participant type.pattern: ^[a-zA-Z]{1,16}$
minLength: 1
maxLength: 16
example: vehicles
string
ttlSpecifies the Time-to-live (TTL) for a Participant of this Participant type in the transaction database.pattern: ^(\d{1,2}(?:d\s*))?(\d{1,2}(?:h\s*))?(\d{1,2}(?:m\s*))?(\d{1,2}(?:s\s*))?$
minLength: 2
string
callbackThe URL endpoint to call after the Participant type creation is completed.pattern: https?:\/\/(www\.)?[[email protected]:%._\+~#=]{2,256}\.[a-z]{2,4}\b([[email protected]:%_\+.~#?&//=]*)string
name Name of the category that needs to be updated.example: vehicle
pattern: ^[a-zA-z][a-zA-z0-9,_\-]{0,15}$
minLength: 1
maxLength: 16
string
descriptionDescription of the category.example: Category for a vehiclestring
subCategoryThe subCategory.pattern: ^[a-zA-z][a-zA-z0-9,_\-]{0,15}$
minLength: 1
maxLength: 16
string

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": "99d",
    "callback": {
        "url": "https://examplecallbackurl.com",
        "meta": {
            "key1": "Post ptp type"// Optional. Meta object can not exceed 256 Bytes.
        }
    }
}
}
{
   "ttl": "99d",
    "callback": {
        "url": "https://examplecallbackurl.com",
        "meta": {
            "key1": "Post ptp type" // Optional. Meta object can not exceed 256 Bytes.
        }
    }
}

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 NameCategoryDescriptionData Type Expected
Tenant IDBaseThe 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 IDBaseThis is a system-generated ID, that is expected to be unique within a Tenant.VarChar
Participant TypeBaseThe type of Participant.VarChar
Participant CodeBaseA 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 IDBaseThe 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 NameBaseA name is provided by the Onboarding entity for the participant. For example, Amazon India (Client), Delhivery Trucking (Operator).VarChar
Participant State
(Optional)
BaseThe 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)CustomCustom 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)CustomCustom 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 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:

📘

Custom Attributes

Learn about Custom Attribute Entitlement Framework.

MemberDescriptionValidationData type
nameName of the Attribute to be added or updated.minLength: 1 maxLength: 32pattern:^[a-zA-Z_]{1,32}$`string
descriptionDescription for the custom attribute.minLength: 0
maxLength: 256
string
dataTypeThe data type of the Attribute. Valid values: string, number, boolean, object, array.Valid values: string, number, boolean, object, array, address, phone, money, participant_typestring
isReadPublicTrue: All apps can read the Custom Attributes.
False (default): Only CAO and OTO will be able to read the Custom Attributes. To learn more, see Custom Attribute Doc.
default: falseboolean
indexedSpecifies 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.default: falseboolean
validationSpecifies 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.number
callbackSpecifies a callback URL that is used to notify the calling of the result status of the call.pattern: https?:\/\/(www\.)?[[email protected]:%._\+~#=]{2,256}\.[a-z]{2,4}\b([[email protected]:%_\+.~#?&//=]*)string

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",
         "isReadPublic": false,
         "indexed":false,
         "defaultValue":"2012",
         "validation":{
            "range":{
               "min":1,
               "max":10
            },
            "required":false
         }
      }
   ],
   {
   "ttl": "99d",
    "callback": {
        "url": "https://examplecallbackurl.com",
        "meta": {
            "key1": "Post ptp type" // Optional. Meta object can not exceed 256 Bytes.
        }
    }
}
}

📘

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.

Participant Category and Sub-category

Participant Category: The type of object or concept about which data is stored and manipulated. For example, a four-wheeler or two-wheeler is a category of participant vehicle.

Participant Sub-category: The type of Participant Category for which data is stored and manipulated. For example, a truck or a car is a participant sub-category for the participant category four-wheeler whose participant is a vehicle.

Participant Template

A Participant Template is created based on a participant category-sub-category pair. The attributes created in the participant template override the attributes created for the participant.

You can create templates that you can use to simplify the creation of Participant instances.

The process to create a template:

  • Define a Participant by creating the Base and Custom Attributes.
  • The participant instance is created using the Participant Template. The participant instance has the superset of all the attributes defined in the participant template and participant. If attributes with the same name exist in the participant template and participant definition, then the Attributes of the participant template will override the attributes of the participant.

The following examples show a request body for creating a Participant Template and a request body for updating a Participant Template:

MemberDescriptionValidationData type
name Name of the template.string
subCategorySubcategory for the template.pattern: ^[a-zA-z][a-zA-z0-9,_\-]{0,15}$
minLength: 1
maxLength: 16
string
attributes(optional)Participant type attributes configuration.
callbackCallback for operations sends status success/failed.pattern: https?:\/\/(www\.)?[[email protected]:%._\+~#=]{2,256}\.[a-z]{2,4}\b([[email protected]:%_\+.~#?&//=]*)string
{
  "name": "templates",
  "subCategory": "truck",
  "attributes": [
    {
      "name": "color",
      "description": "color of truck",
      "tags": [
        "vehicles"
      ],
      "dataType": "string",
      "indexed": false,
      "defaultValue": "black",
      "validation": {
    
        "valueOneOf": [
          "red","blue","black"
        ],
        "required": false
      }
    },
     {
      "name": "capacity",
      "description": "capacity of truck",
      "tags": [
        "vehicles"
      ],
      "dataType": "number",
      "indexed": false,
      "defaultValue": 20,
      "validation": {
    
        "valueOneOf": [
           20,30
        ],
        "required": false
      }
    }
  ],
  "callback": {
        "url":"https://examplecallbackurl.com",
        "meta": {
          "API req": "TemplatePostAPI"
        }
    }
}
{
  "name": "templates",
  "subCategory": "truck",
  "attributes": [
    {
      "name": "color",
      "description": "color of truck",
      "tags": [
        "vehicles"
      ],
      "dataType": "string",
      "indexed": false,
      "defaultValue": "black",
      "validation": {
    
        "valueOneOf": [
          "red","blue","black"
        ],
        "required": false
      }
    },
     {
      "name": "capacity",
      "description": "capacity of truck",
      "tags": [
        "vehicles"
      ],
      "dataType": "number",
      "indexed": false,
      "defaultValue": 20,
      "validation": {
    
        "valueOneOf": [
           20,30
        ],
        "required": false
      }
    }
  ],
  "callback": {
        "url":"https://examplecallbackurl.com",
        "meta": {
          "API req": "TemplatePutAPI"
        }
    }
}

Creating Participant

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

MemberDescriptionValidationData type
ownerThe ID of the Participant to whom this Participant belongs. For a Vehicle owned by an Operator, it will be the Operator ID. For a Client, it will be the Tenant ID. For a Tenant, it will be the Participant ID of the Tenant itself.string
uniqueCodeUnique code identifying the participant.minLength: 1
maxLength: 64
pattern: ^\S{1,64}$
string
nameName of the participant.minLength: 1
maxLength: 64
string
propertiesKey-Value representation of all core attributes of the participant.
callbackCallback for operations sends status success/failed.pattern: https?:\/\/(www\.)?[[email protected]:%._\+~#=]{2,256}\.[a-z]{2,4}\b([[email protected]:%_\+.~#?&//=]*)string

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":"tenants:06676c3b-ab94-48cf-9435-dbe92f2dfcdf", // tenants UUID
   "uniqueCode":"295A41M44WPHHZVO",
   "name":"John Doe",
   "properties":{
      "region":"Europe",
      "email":"[email protected]",
      "firstname":"John",
      "lastname":"Doe"
   },
   "category": "two-wheeler",
   "subCategory": "cycle",
   "templateId": "template:4683c678-ae78-3e00-a43a-bd59195a1b4a",
  
    "callback": {
        "url": "https://examplecallbackurl.com",
        "meta": {
            "key1": "Post ptp type" // Optional. Meta object can not exceed 256 Bytes.
        }
    }

}
{
  "properties": {
      "region":"Africa",
      "email":"[email protected]",
      "name":"Jack"
      }
}

👍

Participant Batch Processing

Participants can be created and updated in batch using Batch Processing API.

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.

1920

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.