Introduction - API differences
The APIs of both event mechanisms are very similar, with a few small differences highlighted below.
No changes in the flow are required, only payloads slightly change.
Please note, that with Public Events, subscriber has some flexibility to decide which events it subscribes to (using “event” field in the payload). With Private Events, subscribers will receive only intended events (which events are intended is controlled by the business logic, no actions required on subscriber side).
Subscription API
There are two changes in the subscription payload comparing to Public Events:
- “type” = “privateChaincode“, instead of “chaincode”
- “event” = “.*” (this value is fixed and should not be changed)
Callback API
There are two changes in the Private Event payload received through the callback mechanism:
1. “EventName” field is missing (this information is included in “Payload” field)
2. “Payload” field, once decoded from base64, has a structure of a key-value dictionary, where:
- Key – event name
- Value – event payload (this is original “Payload” content, recevied in Public Events)
There is an option to include multiple events in one “Payload” field (multiple key-value pairs), but it is not used as of now.
Example comparison of CreateShipment payload for Public vs. Private event:
| Public Event | Private Event |
| "EventName": "CreateShipment_11111111-2222-3333-4444-666666666666", | EventName is not available |
|
“Payload”: <base64 encoded>.
After decoding, there is a direct access to business data, for example: "Cargo":{"AssetType":"ccshipments.Cargo"[....]
|
“Payload”: <base64 encoded>.
After decoding, one obtains key-value pair, where: Key = EventName without suffix with recipient information (“CreateShipment”) Value = business data, identical to the one accessible in PublicEvent
Example: {
|
Migration flow
Step 1 - Introduce appropriate changes on a callBack client side
There are changes in the APIs that must be accommodated for. Please refer to “API differences” section.
Step 2 - Subscribe to Private Events
Please note, that after completion of this point, both Public and Private events will be received. One should handle duplicates or delete existing subscription first (in latter case, please accommodate for a risk of potential lost of events).
Example of the subscription request (impacted fields highlighted in yellow):
| Method | POST |
| URL | {node-url}/v1/restproxy/api/v2/channels/{lb-channel}/event-subscriptions |
| Headers | Authorization: Bearer <access_token> |
| Payload (mTLS disabled) |
{
|
Please refer to Logivity API - Subscribe to notifications documentation for more information on subscription process.
Here you will find a collection providing examples to create a new subscription: Notifications
Example of a callback response (impacted fields highlighted in yellow):
| Source CIDR | Logivity Blockchain is hosted on Oracle’s Frankfurt datacenter. All event notifications are sent from IP address 138.1.45.154 |
| Method | POST |
| Payload (Private Events) |
{ |
Structure of “Payload”, after decoding (impacted fields highlighted in yellow):
{"CreateShipment":
{"Capacity":
{"AssetId":"Capacity_lb-test_2d5b03117c656cf7804319fee1342d9a5c9cf09d034838bd1bd2692fad7a51a6",
"AssetType":"loadboard.Capacity",
"AutoAccept":"NO",
"CapacityId":"124237902668023382002",
"CarrierContractNumber":"700593112910001",
"CarrierReferenceNumber":"Parma",
"CreationDateTime":"2024-06-04T09:51:38Z",
"CreationTimeZone":"UTC",
"PartialAcceptanceAllowed":"NO",
"RootAssetId":"Cargo_lb-test_2d5b03117c656cf7804319fee1342d9a5c9cf09d034838bd1bd2692fad7a51a6",
"ShipFrom":{"Position":{}},
"ShipTo":{"Position":{}},
"SourceAssetId":"",
"SourceChannelName":"",
"State":"ASSIGNED",
"StructVersion":"1.1.0",
"SystemOfRecordCapacityId":"63440990"},
"Cargo":{"AssetId":"Cargo_lb-test_2d5b03117c656cf7804319fee1342d9a5c9cf09d034838bd1bd2692fad7a51a6",
"AssetType":"loadboard.Cargo",
"BookingState":"ASSIGNED",
"CapacityAssetId":"Capacity_lb-test_2d5b03117c656cf7804319fee1342d9a5c9cf09d034838bd1bd2692fad7a51a6",
"CargoId":"124237902668023382001",
"CreationDateTime":"2024-06-04T09:51:38Z",
"CreationTimeZone":"UTC",
"CreatorInfo":{"ClientTMAID":"1553db7d-c7b5-4f8e-a7f5-631083ec2797",
"ServiceProviderMSPID":"MMN1NonProd"},
"LegType":"PCT",
"PaymentTxId":"otransaction~12cb62c49ab4cd3bd6513901be7dc74f13ec28a01c86a74668817d6c3a2f6034",
"PlannedCost":{},
"PlannedVehicleDetails":{},
"RecipientInfo":{"ClientTMAID":"1553db7d-c7b5-4f8e-a7f5-631083ec2797",
"ServiceProviderMSPID":"MMN1NonProd"},
"ShipmentId":"124237902668023382000",
"ShipmentType":"Planned",
"SourceAssetId":"",
"SourceChannelName":"",
"StructVersion":"1.0.6",
"SystemOfRecordCargoId":"B22225834313_0940_1",
"TransportExecutionState":"NOT STARTED",
"TransportOrder":
[{"AssetId":"TransportOrder_lb-test_2d5b03117c656cf7804319fee1342d9a5c9cf09d034838bd1bd2692fad7a51a6_1",
"ShipFrom":{"Position":{}},
"ShipTo":{"Position":{}},
"SourceAssetId":"",
"SourceChannelName":""},
{"AssetId":"TransportOrder_lb-test_2d5b03117c656cf7804319fee1342d9a5c9cf09d034838bd1bd2692fad7a51a6_2",
"ShipFrom":{"Position":{}},
"ShipTo":{"Position":{}},
"SourceAssetId":"","SourceChannelName":""}],
"VehicleDetails":{}}}}
Step 3 - Delete already existing subscription to Public Events
Please refer to Logivity API - Delete my subscriptions documentation for information on how to do this.
Contact for support
If you have any questions or require support please raise a ticket to our support team by clicking here.
Comments
0 comments
Please sign in to leave a comment.