Participant
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.
Using the Core APIs of the OS1 Platform any type of participant commonly used in logistics operations can be defined and represented. Examples of some commonly used participants are given 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. |
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 cater to better classification of a Tenants' business entities.
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 | Validation | Data type |
|---|---|---|---|
singular | A 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 |
plural | A unique plural name that defines multiple participants of this participant type. | pattern: ^[a-zA-Z]{1,16}$ minLength: 1 maxLength: 16 example: vehicles | string |
callback | The URL endpoint to call after the Participant type creation is completed. | { “url” : (string) pattern: https?://(www.)?[-a-zA-Z0-9@:%.+#=]{2,256}.[a-z]{2,4}\b([-a-zA-Z0-9@:%+.#?&//=]*) “meta” : { free object max size of 512 bytes } } | object |
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 |
description | Description of the category. | example: Category for a vehicle | string |
subCategory | The subCategory. | pattern: ^[a-zA-z][a-zA-z0-9,_\-]{0,15}$ minLength: 1 maxLength: 16 | string |
allowedOwner (Optional) | This defines what all types of participants can be or can not be the owner of the participant of a particular participant type. | { oneOf:[ ], not:[ ] } | |
entityCode (Optional) | Unique code of an entity that uniquely identifies the entity in ERC service. | | |
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:
The Participant object supports three 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.
- System: These are system-defined attributes and can be changed or modified by the system extensively.
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 a Participant Type Tenant, the Participant ID and Tenant ID are the same. | UUID |
Participant ID | System | 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 | Base | A name is provided by the Onboarding entity for the participant. For example, Amazon India (Client), Delhivery Trucking (Operator). | VarChar |
Participant State | System | The current state of the participant. On Participant creation, the default state is set as ‘Onboarding’ (or default sub-state of ‘Onboarding’ state, as defined by the system). | 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.
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.
Member | Description | Validation | Data type |
|---|---|---|---|
name | Name of the Attribute to be added or updated. | minLength: 1 maxLength: 32 pattern: ^[a-zA-Z_]{1,32}$ | string |
uniqueCode | Unique code. | minLength: 1 maxLength: 128 | string |
description | Description for the custom attribute. | minLength: 0 maxLength:256 | string |
dataType | The data type of the Attribute. Valid values: string, number, boolean, object, array. | Valid values: string, number, boolean, object, array, address, phone, money, participant_type, geo-point | string |
isReadPublic | True: 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: false | boolean |
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. | default: false | boolean |
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. | | number |
callback | Specifies a callback URL that is used to notify the calling of the result status of the call. | pattern: https?://(www.)?[-a-zA-Z0-9@:%.+#=]{2,256}.[a-z]{2,4}\b([-a-zA-Z0-9@:%+.#?&//=]*) | object |
The following shows a sample request body for creating a custom Attribute:
📘 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.
The participant_type data type allows you to reference participants (users, vehicles, teams) as properties within an entity schema. When creating or updating an entity type, you can now include participant_type as a custom attribute:
Participant Category: The type of object or concept about which data is stored and manipulated. For example, a four-wheeler & two-wheeler are the categories of participant vehicles.
Participant Sub-category: The type of Participant Category for which data is stored and manipulated. For example, a truck & a car are the participant sub-categories for the participant category four-wheeler whose participant is a vehicle.
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:
- 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 example shows a request body for creating a Participant Template and a request body for updating a Participant Template:
Member | Description | Validation | Data type |
|---|---|---|---|
name | Name of the template. | | string |
subCategory | Subcategory for the template. | Pattern: ^[a-zA-z][a-zA-z0-9,_\-]{0,15}$ minLength: 1 maxLength: 16 | string |
attributes (optional) | Participant type attributes configuration. | | |
callback | Callback for operations sends status success/failed. | Pattern: https?:\/\/(www\.)?[-a-zA-Z0-9@:%.\+~#=]{2,256}\.[a-z]{2,4}\b([-a-zA-Z0-9@:%\+.~#?&//=]*) | object |
To create a Participant, call the Create a new participant endpoint and pass the following values in the request body:
Member | Description | Validation | Data type |
|---|---|---|---|
owner | The 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 |
uniqueCode | Unique code identifying the participant. | minLength: 1 maxLength: 64 Pattern: ^\S{1,64}$ | string |
name | Name of the participant. | minLength: 1 maxLength: 64 | string |
properties | Key-Value representation of all core attributes of the participant. | | |
callback | Callback for operations sends status success/failed. | Pattern: https?:\/\/(www\.)?[-a-zA-Z0-9@:%.\+~#=]{2,256}\.[a-z]{2,4}\b([-a-zA-Z0-9@:%\+.~#?&//=]*) | string |
To update a Participant, call the Update core and custom attributes of a participant endpoint and pass the members to update.
Request bodies are specified in JSON format. The following example shows a request body for creating a Participant and a request body for updating a Participant:
Batch processing helps to create and update the Participants in the batch. The Batch processing supports two methods to supply the Participant data:
- JSON
- CSV file upload
To create Participants in batch, call the Create Batch Request endpoint. To update Participants in batch, call the Update Batch Request endpoint.
Member | Description | Validation | Data Type |
|---|---|---|---|
payload* | List of valid objects to create data in Participants. | maxItems: 1024 minItems: 1 | |
uniqueCode* | Unique code. | minLength: 1 maxLength: 128 | String |
name (Optional) | Name of the Participant. | minLength: 1 maxLength: 64 | String |
owner* | The 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. | minLength: 1 maxLength: 64 | String |
category (Optional) | Category of Participant | Example: vehicle Pattern: ^[a-zA-z][a-zA-z0-9,-]{0,15}$ minLength: 1 maxLength: 64 | String |
subCategory (Optional) | Sub-category of Participant | Example: car Pattern: ^[a-zA-z][a-zA-z0-9,-]{0,15}$ minLength: 1 maxLength: 64 | String |
properties* | Key-Value representation of all custom attributes of the participant. | | |
templateId (Optional) | | | String |
callback > url* | URL to notify the outcome of the request. | Pattern: https?://(www.)?[-a-zA-Z0-9@:%.+#=]{2,256}.[a-z]{2,4}\b([-a-zA-Z0-9@:%+.#?&//=]) | String |
callback > meta (Optional) | Any additional data that is required in the callback to the request. | | |
📘 Note
The items marked (*) are mandatory attributes required while creating the Participants via batch processing.
The request bodies are specified in JSON format. The following examples show request bodies for creating and updating Participants in Batches.
👍 Creating/Updating Participant Batch Request Via CSV
Participants can be created and updated in batch via CSV file upload. Here are the sample CSV files for Batch Creation & Updation of Participants.
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 can onboard other Participants & complete the integration process.
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.
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's 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).
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.
Using the Participant Service, we have onboarded Participants on the Platform. Each participant on the Platform will have a lifecycle of its own.
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 based on the workflows set in the application using it.
The platform will by default provide three states for a participant:
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.
The active state denotes that a Participant has completed registration and can be used for operational duties.
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.
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:
- 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 (For example- 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).
- 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 Transition.