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 participant commonly used in logistics operations can be defined and represented. Examples of some commonly used participants are given below:

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 cater to better classification of a Tenants' business entities.

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:

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"
      ]
    }
  ],
    "callback": {
        "url": "https://examplecallbackurl.com",
        "meta": {
            "key1": "Post ptp type".
        }
    }
}

{
  "category": [
    {
      "name": "vehicle",
      "description": "category for a vehicle",
      "subCategory": [
        "VmT_r"
      ]
    }
  ],
  "allowedOwner": {
    "oneOf": [
      "vendors",
      "users",
      "tenants"
    ],
    "not": [
      "vehicle"
    ]
  },
   "callback": {
        "url": "https://examplecallbackurl.com",
        "meta": {
            "key1": "Post ptp type".
        }
    }
}

Attributes of a Participant

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.

Predefined Attributes

The following table provides a list of predefined attributes:

📘

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.

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,  //will always be true for owner app.
         "indexed":false,
         "defaultValue":"2012",
         "validation":{
            "range":{
               "min":1,
               "max":10
            },
            "required":false
         }
      }
   ],
    "callback": {
        "url": "https://examplecallbackurl.com",
        "meta": {
            "key1": "Post ptp type" // Optional. Meta object can not exceed 512 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 & 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.

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 example shows a request body for creating a Participant Template and a request body for updating a Participant Template:

{
  "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:

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

Here are the sample CSV files for Batch Creation & Updation of Participants

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

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

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

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

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.