OS1 Services
...
Participant
Integrate with Participants
Update Attributes and State with a Single API
8min
this api enhancement enables developers to update both the state of an entity and its attributes in a single idempotent api call this is useful when both actions need to be performed in the same flow to ensure that they are validated together and handled atomically key benefits idempotency it ensures the same request can be made multiple times without causing unintended side effects atomic operations both state transition and attribute updates are processed as a single transaction simplified workflow reduces the number of api calls and validation steps for common use cases integrating single api in state transition and attribute updates when integrating, you will need to include both properties (for attribute updates) and the statetransition object (for state changes) in the request body if only one of these is needed, you can omit the statetransition or use the api as usual with just the properties field the system will validate both the state transition and attribute update together this ensures consistency and accuracy when performing both operations at once to update participant attributes and perform state transitions in a single call, pass the statetransition object along with the existing properties object in the api request body step 1 include a statetransition object in the request body in addition to the existing properties, you can now include a statetransition object in the request body json { "properties" { }, "statetransition" { "eventcode" "e 351", "reasoncode" "r 5334" } } eventcode code representing the state transition event reasoncode code representing the reason for the state transition sample request json put {{baseurl}}/participant/{participanttypepluralname}/{participantid} content type application/json { "properties" {}, "name" "string", "owner" "string", "templateid" "string", "category" "string", "subcategory" "string", "onrequest" { "url" "string", "requestheader" {}, "requestbody" {}, "method" "post", "onresponse" { "wait" true, "acceptablestatuscodes" \[ 0 ], "raiseerroronstatusmismatch" true } }, "onerror" { "url" "string", "requestheader" {}, "requestbody" {}, "method" "post", "onresponse" { "wait" true, "acceptablestatuscodes" \[ 0 ], "raiseerroronstatusmismatch" true } }, "callback" { "url" "string", "meta" {} }, "statetransition" { "eventcode" "string", "reasoncode" "string" } } the above request body explains the following properties the properties object contains the key value pairs of attributes that need to be updated for the entity instance this is the same behavior as the standard attribute update statetransition the statetransition object is new and allows you to specify details about the state transition this is an optional field, but when included, both the state transition and the properties will be validated and updated together statetransition object fields eventcode specifies the event associated with the state transition (e g , "e 351") reasoncode provides the reason or justification for the state transition (e g , "r 5334") event handling response events step 2 when the api is invoked with a statetransition object, the system will produce one of two events based on the outcome the two new events have been introduced to handle the result of this combined operation participantattributeandstateupdationsuccessevent this event is triggered when both the attribute update and state transition are successful participantattributeandstateupdationfailedevent this event is triggered if either the attribute update or the state transition fails both success and failure events will include two new fields smeventcode reflects the event code of the state transition smreasoncode reflects the reason code for the state transition json examples event response example success { "businesscommand" "participantstesttemplatedentityupdate", "requestid" "request test", "entityname" "testtemplated", "entityversion" "1 0 0", "commandname" "participantattributeandstateupdationsuccessevent", "payloadvalidated" true, "reason" "", "entityinstanceid" "testtemplated\ a45079e3 e5b9 5431 bfeb c5d98c4fe0e8", "tenantid" "developcore1", "data" { "entityname" "testtemplated", "updatedby" { "id" "id", "name" "abc", "appid" "app\ abc" }, "updatedat" "1728908593228", "appid" "participants", "properties" { "failurereason" "", "inprogress" false, "isfail" false, "processingstage" "isactive", "servicecode" "", "system" false }, "uniquecode" "fe0a3bfe 51eb 4040 8c7f fbb544cbb5cd", "eventcode" "e 022", "reasoncode" "r 0001" }, "entity" { "domain" "participants", "entitytype" "participantentity", "entitymeta" { "entitytype" "participantentity", "cassandra" { "fields" { "status" "", "created" { "$db function" "totimestamp(now())" } }, "key" \[ "id" ] }, "schemaversion" "1 0 0", "schemanamespace" "participant", "dynamo" { "hashkeys" \[ "tenant id", "participant id" ], "delimiter" "##", "sortkeys" \[] }, "hasinfiniteretry" true, "skipentitykafkapush" true, "primarykeysforreadstore" \[ "tenant id", "participant id" ], "kafka" { "topic" "participantentity", "keyfield" "participant id" }, "lock" { "seqno" 1 } }, "aggregateroot" "participants testtemplated", "type" "testtemplated", "tenant id" "developcore1", "participant type" "testtemplated", "participant id" "testtemplated\ a45079e3 e5b9 5431 bfeb c5d98c4fe0e8", "participant code" "fe0a3bfe 51eb 4040 8c7f fbb544cbb5cd", "owner id" "tenants 7155bea5 dd62 52f3 9573 611672371d9e", "participant name" "updatedi", "is active" true, "state" "active\ active", "indexed attributes" {}, "non indexed attributes" { "failurereason" "", "inprogress" false, "isfail" false, "processingstage" "isactive", "servicecode" "", "system" false }, "callback" "https //webhook site/64f40780 dff3 46f7 aa78 c28d45fe5902", "created at" 1728908574196, "updated at" 1728908593296, "updated by" { "id" "id", "name" "abc", "appid" "app\ abc" }, "created by" { "id" "id", "name" "abc", "appid" "app\ abc" } }, "callbackmeta" { "string" "string" } } event response example failure { "businesscommand" "participantstesttemplatedentityupdate", "requestid" "request test", "entityname" "testtemplated", "entityversion" "1 0 0", "commandname" "participantattributeandstateupdationfailedevent", "payloadvalidated" false, "reason" "invalid state transition", "errorcode" "101170021090", "entityinstanceid" "testtemplated\ a45079e3 e5b9 5431 bfeb c5d98c4fe0e8", "tenantid" "developcore1", "data" { "entityname" "testtemplated", "appid" "participants", "updatedby" { "id" "id", "name" "abc", "appid" "app\ abc" }, "uniquecode" "fe0a3bfe 51eb 4040 8c7f fbb544cbb5cd", "eventcode" "e 022", "reasoncode" "r 0001" }, "entity" {}, "callbackmeta" { "string" "string" }, "event" { "id" "e952ce0f 1b54 4c65 a9c7 5b44ad749e53", "eventversion" "1 0 0", "eventtype" "participantattributeandstateupdationfailedevent", "createdtime" "mon, 14 oct 2024 12 23 25 gmt", "sequentialexecution" false, "domain" "participants", "participant id" "testtemplated\ a45079e3 e5b9 5431 bfeb c5d98c4fe0e8", "participant type" "testtemplated", "tenant id" "developcore1", "batchid" "testtemplated\ a45079e3 e5b9 5431 bfeb c5d98c4fe0e8", "requestid" "request test", "failurereason" "invalid state transition", "callback" { "url" "https //webhook site/64f40780 dff3 46f7 aa78 c28d45fe5902", "meta" { "string" "string" } }, "callbacksecret" "", "userinfo" { "id" "id", "name" "abc", "appid" "app\ abc" }, "uniquecode" "fe0a3bfe 51eb 4040 8c7f fbb544cbb5cd", "errorcode" "101170021090", "smeventcode" "e 022", "smreasoncode" "r 0001" } }