Participant

introduction the participant service api allows you to manage participants in your os1 platform a participant can be an organization, asset, or individual that performs tasks it is represented by a set of required and optional attributes and is governed by its state understanding participants is crucial for managing workflows in logistics operations effectively participants are entities that interact within the platform they can be classified into various types such as tenants, clients, operators, vehicles, users, facilities, and devices each type serves a specific role within the logistics framework 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 integrate with participants docid\ qmfbzzlnwgbwjjdjoeb7q types of 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 why use participants? participants allow for the representation and management of various logistical entities, facilitating better organization and tracking of tasks and workflows they help in defining relationships, roles, and responsibilities within the platform when to create or update a participant? you should create or update a participant when onboarding a new organization or asset adjusting the attributes or capabilities of an existing participant configuring custom participant types that meet specific business needs 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 docid\ myijbqyiqm0cyhpqluu q 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 entity docid\ aybe70hu6gdjh5mpverll 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 docid\ oj1bqsmubmbdphlu zddv 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 create 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" } } } update participant 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 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 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 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 custom attributes { "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 } } ], "callback" { "url" "https //examplecallbackurl com", "meta" { "key1" "post ptp type" } } 📘 important note regarding custom attribute creation 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 type as data type 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 { "name" "\<attributename>", "description" "\<description>", "datatype" "participant type", "defaultvalue" "\<ptpinstanceid>", "indexed" true/false "validations" { "valueoneof" \[ "\<participanttypepluralname>" ], "required" \<true/false> } } 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 participant docid\ ixssds2yvjpwqx3 zmq70 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 create a new template docid\ ku4yplqcixm9t8ikiaytc and a request body for update a template with a given id docid\ c v7mxjuedyklvj izuny 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 create participant type { "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" } } } update 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" "templateputapi" } } } creating participant to create a participant, call the create a new participant docid\ ah8 z5vvvjhd52j3twxmn 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 docid 2 ty5ucdncf2paaq4uiog 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 create participant { "owner" "tenants 06676c3b ab94 48cf dbe92f2dfcdf", // tenants uuid "uniquecode" "295a41m44wp zvo", "name" "john doe", "properties" { "region" "america", "email" "johndoe\@gmail com", "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" } } } update participant { "properties" { "region" "africa", "email" "johndoe\@gmail com", "name" "jack" } } creating participants in a batch 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 perform create operation on participants in batch docid\ rnnrardtcwh oxjdbxmr9 endpoint to update participants in batch, call the perform update operation on participants in batch docid\ jgx40su9bqpkoe1 kkwnk endpoint attributes for batch request 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 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 create participants in batch { "payload" \[ { "uniquecode" "qk6a ji6s 7etr", "name" "car1", "owner" "worldlogistics", "properties" { "color" "red" } }, { "uniquecode" "xnss hsjw 3ngu", "name" "car2", "owner" "worldlogistics", "properties" { "color" "blue" } }, { "uniquecode" "nhle l6mi 4ge4", "name" "car3", "owner" "worldlogistics", "properties" { "color" "black" } }, { "uniquecode" "6eti uil2 9wax", "name" "car4", "owner" "worldlogistics", "properties" { "color" "silver" } }, { "uniquecode" "2e62 e3sr 33fi", "name" "car5", "owner" "worldlogistics", "properties" { "color" "white" } } ], "callback" { "url" "https //examplecallbackurl com" } } update participants in batch { "payload" \[ { "id" "try\ d208e2b0 ab66 5738 8916 0d5271ec02a0", //this is a sample participant id use a proper participant id instead "properties" { "color" "blue" } } ] } 👍 creating/updating participant batch request via csv 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 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 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 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 docid\ onamjh1ianfuwvykha69n 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 transition