Service Order Integration

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 internally assigned to the correct port call, vessel and voyage and processed further inside the VMS.

Description

Note: Recommended before proceeding - read: Getting Started with Dataloy REST API.

The endpoints for the Port Service Order process are:

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:

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:

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:

where “dataloyObject“: 3644213 is the PortCall key.

The integration can change an existing Service Order through HTTP PUT, see ServiceOrder, ServiceOrderLine.

Service Order status transitions (since 6.4.0)

When a Service Order is created it get the status Draft. The status transitions workflow is the following: