The objective of the Service Order integration is to trigger the ordering of port related services and receive updates on estimated, revised and actual cost from parties handling the orders. The costs are in turn internally assigned to the correct port call, vessel and voyage and processed further inside the VMS.
Description
The Service Order Process Consists of Two Steps:
Appointment of port calls in Dataloy VMS following the step-by-step instructions at Appointment API.
Receive Service Order data from applicable agency system and ensure that Dataloy VMS automatically updates the total cost of the port, voyage and results with the most updated data.
Prerequisites
Before setting up and testing a DA integration the following is required:
Mapping of port cost codes between Dataloy VMS and the agency system (Dataloy VMS: Modules - Master Data - General Master Data Administration - Port Cost Code).
Mapping of handling cost codes between Dataloy VMS and the agency system. (Dataloy VMS: Modules - Master Data - General Master Data Administration - Handling Cost Code).
Mapping of various text codes between Dataloy VMS and the agency system. (Dataloy VMS: Modules - Master Data - General Master Data Administration - Various Text).
Synchronization of business partners between Dataloy VMS and the agency system. (Dataloy VMS: Modules - Master Data - General Master Data Administration - Business Partners).
Note: Recommended before proceeding - read: Getting Started with Dataloy REST API.
These are the endpoints for the Port Service Order process:
ServiceOrder objects are created by Dataloy VMS with the status Estimate, EST.
The integration should use Webhooks to be notified when a new ServiceOrder object is created.
POST.WebhookSubscription:
{ "user": 12345679, "channelInfo": { "url": "https://push.here.com", "channelType": "HTTP" }, "eventType": "C", "objectType": "ServiceOrder" }
The JSON sent will have this structure:
{ "id":"51296956-36704502", "eventTime":"2020-09-13T10:23:00", "eventType":"C", "objectType":"ServiceOrder", "dataloyObject":36704502, "dataloyObjectSelf":"http://platform-dev.dataloy.com:80/ws/rest/ServiceOrder/36704502", "subscription":{ "key":36704493, "self":"http://platform-dev.dataloy.com:80/ws/rest/WebhookSubscription/36704493", "isSubscriptionActive":true, "user":{ "key":12345679, "self":"http://platform-dev.dataloy.com:80/ws/rest/User/12345679", "userCode":"TEST", "userName":"test" }, "url":null, "dataloyObject":null, "channelInfo":{ "key":36704492, "self":"http://platform-dev.dataloy.com:80/ws/rest/ChannelInfo/36704492", "url":"https://push.here.com", "channelType":{ "key":22696460, "self":"http://platform-dev.dataloy.com:80/ws/rest/ChannelType/22696460", "channelTypeCode":"HTTP" } }, "eventType":"C", "dlpAlertScript":null, "unsubscriptionDate":null, "objectType":"ServiceOrder" }, "resource":{ "key":36704502, "self":"http://platform-dev.dataloy.com:80/ws/rest/ServiceOrder/36704502", "businessPartner":{ "businessPartnerName":"Westcon Yards AS", "businessPartnerSort":"WESTCON YARDS AS", "businessPartnerCode":"100131", "portAgentType":null, "businessPartnerType":{ "businessPartnerType":"SU", "businessPartnerTypeDesc":"Supplier", "key":1668676, "self":"http://platform-dev.dataloy.com:80/ws/rest/BusinessPartnerType/1668676" }, "key":20798543, "self":"http://platform-dev.dataloy.com:80/ws/rest/BusinessPartner/20798543" }, "createdDate":"2020-09-13T10:23:00", "modifiedDate":"2020-09-13T10:23:00", "createdById":35637975, "exchangeRate":1.2345, "portCall":{ "key":36344213, "self":"http://platform-dev.dataloy.com:80/ws/rest/PortCall/36344213", "eventLogs":[ { "key":36344209, "self":"http://platform-dev.dataloy.com:80/ws/rest/EventLog/36344209", "event":{ "key":1000052, "self":"http://platform-dev.dataloy.com:80/ws/rest/Event/1000052", "eventCode":"DEP", "eventDesc":"Departed" }, "eventLogDate":"2020-12-06T18:00:19" }, { "key":36344210, "self":"http://platform-dev.dataloy.com:80/ws/rest/EventLog/36344210", "event":{ "key":1000051, "self":"http://platform-dev.dataloy.com:80/ws/rest/Event/1000051", "eventCode":"BRT", "eventDesc":"Berthed" }, "eventLogDate":"2020-12-06T18:00:19" }, { "key":36344211, "self":"http://platform-dev.dataloy.com:80/ws/rest/EventLog/36344211", "event":{ "key":1000050, "self":"http://platform-dev.dataloy.com:80/ws/rest/Event/1000050", "eventCode":"ARR", "eventDesc":"Arrived" }, "eventLogDate":"2020-12-05T18:00:19" } ] }, "orderDate":"2020-10-01T00:00:00", "externalReferenceNo":"DA1234", "currency":{ "currencyCode":"USD", "currencyName":"U.S. Dollar", "key":400132, "self":"http://platform-dev.dataloy.com:80/ws/rest/Currency/400132" }, "status":{ "key":1000131, "self":"http://platform-dev.dataloy.com:80/ws/rest/StatusType/1000131", "statusTypeDesc":"Estimate", "statusTypeCode":"EST" }, "serviceOrderLines":[ { "key":36704503, "self":"http://platform-dev.dataloy.com:80/ws/rest/ServiceOrderLine/36704503" } ], "amountAdvanced":10000.0, "amountAdvancedCurrency":{ "currencyCode":"EUR", "currencyName":"Euro", "key":400008, "self":"http://platform-dev.dataloy.com:80/ws/rest/Currency/400008" }, "remarks":[ ], "isObjectActive":true } }
It is possible to be notified only by the raw object, in this case the WebhookSubscription has to have the following property:
"rawObject" : true
In this case the JSON sent will be like this:
{ "key":36704513, "self":"http://platform-dev.dataloy.com:80/ws/rest/ServiceOrder/36704513", "businessPartner":"100131", "createdDate":"2020-09-13T10:26:50", "modifiedDate":"2020-09-13T10:26:50", "exchangeRate":1.2345, "portCall":{ "key":36344213, "self":"http://platform-dev.dataloy.com:80/ws/rest/PortCall/36344213", "eventLogs":[ { "key":36344209, "self":"http://platform-dev.dataloy.com:80/ws/rest/EventLog/36344209", "event":{ "key":1000052, "self":"http://platform-dev.dataloy.com:80/ws/rest/Event/1000052", "eventCode":"DEP", "eventDesc":"Departed" }, "eventLogDate":"2020-12-06T18:00:19" }, { "key":36344210, "self":"http://platform-dev.dataloy.com:80/ws/rest/EventLog/36344210", "event":{ "key":1000051, "self":"http://platform-dev.dataloy.com:80/ws/rest/Event/1000051", "eventCode":"BRT", "eventDesc":"Berthed" }, "eventLogDate":"2020-12-06T18:00:19" }, { "key":36344211, "self":"http://platform-dev.dataloy.com:80/ws/rest/EventLog/36344211", "event":{ "key":1000050, "self":"http://platform-dev.dataloy.com:80/ws/rest/Event/1000050", "eventCode":"ARR", "eventDesc":"Arrived" }, "eventLogDate":"2020-12-05T18:00:19" } ] }, "orderDate":"2020-10-01T00:00:00", "externalReferenceNo":"DA1234", "currency":"USD", "status":"EST", "serviceOrderLines":[ { "key":36704514, "self":"http://platform-dev.dataloy.com:80/ws/rest/ServiceOrderLine/36704514" } ], "amountAdvanced":10000.0, "amountAdvancedCurrency":"EUR", "remarks":[ ], "isObjectActive":true }
Where all the objects identified by code will get code and not the key.
It is possible to customize the JSON sent by Dataloy:
Adjust Number of Fields to be Returned from a Request.
The fields property to customize the messages must be encoded with Base64 and set in attribute json of the WebhookSubscription
The integration should subscribe for changes to any ServiceOrder objects, POST a WebhookSubscription like this:
{ "user": 12345679, "channelInfo": { "url": "https://push.here.com", "channelType": "HTTP" }, "eventType": "U", "objectType": "ServiceOrder" }
If the integration want to be notified also when there are changes to the PortCall connected with the ServiceOrder, a WebhookSubscription like this should be POST:
{ "user": 12345679, "channelInfo": { "url": "https://push.here.com", "channelType": "HTTP" }, "eventType": "U", "objectType": "PortCall", "dataloyObject": 36344213 }
where “dataloyObject“: 3644213 is the PortCall key.