Page Comparison

Tip
Webhooks are available from version 3.3 of the Dataloy API

...

Note

Automatic Deactivation of subscription

If the subscribing system is unavailable or takes too long to respond, the server will deactivate the subscription after attempting 5 times (once a minute). The number of attempts and the interval between each attempt can be configured.

Deactivated subscriptions cannot be reactivated, a new subscription must be created if needed.

Email alert when a subscription is de-activated: Add the desired email address (e.g. to the IT ops team) to the API user (in User Administration) to receive an email notification if a subscription is de-activated.

The message sent to the subscribed endpoint is set in the body of the POST method. The message is a JSON object and has the following structure:

Code Block

language	js

{ "id": "1573335-244070007"

From, version 6.10, there is a possibility for the users to choose not to deactivate the subscription even after the max failed attempts.This is made possible through the checkbox "Do Not Unsubscribe" when creating a webhook subscription on VMS. Ticking the checkbox means that the subscription will not be unsubscribed and deactivated automatically after the max failed attempts. If using API endpoint to create/update subscription, the input curl should include the attribute and value as in

{

"doNotUnsubscribe": false/true

}

The message sent to the subscribed endpoint is set in the body of the POST method. The message is a JSON object and has the following structure:

Code Block

language	js

{
 "id": "1573335-244070007",
 "eventTime": "2016-09-14T13:37:26",
 "objectType": "PortCall",
 "eventType": "U",
 "dataloyObject":189126972,
 "dataloyObjectSelf":"http://localhost:8080/ws/rest/PortCall/7823672"
 "subscription":{
            "key":243885046,
            "self":"http://localhost:8080/ws/rest/WebhookSubscription/243885046"
            "objectType":"BunkerOrder",
            "dataloyObject":244070007,
            "eventType": "U",
		     "url":"http://test1.dataloy.com:8080/webhook/"
   }
"resource":{  
      "key":244070007,
      "self":"http://localhost:8080/ws/rest/BunkerOrder/244070007",
      "vessel":{  
         "vesselName":"VESSEL1",
         "key":188616815,
         "self":"http://localhost:8080/ws/rest/Vessel/188616815"
      },
      "currency":{  
         "currencyCode":"USD",
         "currencyName":"U.S. DOLLAR",
         "key":400132,
         "self":"http://localhost:8080/ws/rest/Currency/400132"
      },
      "exchangeRate":3.0,
      "modifiedDate":"2016-09-21T06:38:29",
      "portCall":{  
         "key":189126972,
         "self":"http://localhost:8080/ws/rest/PortCall/189126972",
         "eventLogs":[  
            {  
               "key":189126978,
               "self":"http://localhost:8080/ws/rest/EventLog/189126978",
               "event":{  
                  "key":1000052,
                  "self":"http://localhost:8080/ws/rest/Event/1000052",
                  "eventCode":"DEP",
                  "eventDesc":"Departed"
               },
               "eventLogDate":"2015-02-13T17:18:00"
            },
            {  
               "key":189126974,
               "self":"http://localhost:8080/ws/rest/EventLog/189126974",
               "event":{  
                  "key":1000050,
                  "self":"http://localhost:8080/ws/rest/Event/1000050",
                  "eventCode":"ARR",
                  "eventDesc":"Arrived"
               },
               "eventLogDate":"2015-02-06T20:18:00"
            },
            {  
               "key":189126976,
               "self":"http://localhost:8080/ws/rest/EventLog/189126976",
               "event":{  
                  "key":1000051,
                  "self":"http://localhost:8080/ws/rest/Event/1000051",
                  "eventCode":"BRT",
                  "eventDesc":"Berthed"
               },
               "eventLogDate":"2015-02-07T10:06:00"
            }
         ]
      },
      "extraCost":0.0,
      "bunkeredDate":"2016-01-01T00:00:00",
      "orderDate":"2016-09-06T10:16:36",
      "bunkerPaidBy":null,
      "createdDate":"2016-09-21T06:12:42",
      "createdById":999999,
      "bunkerOrderStatus":{  
         "key":243093653,
         "self":"http://localhost:8080/ws/rest/StatusType/243093653",
         "statusTypeDesc":"Requirement",
         "statusTypeCode":"REQBO"
      },
      "externalReferenceNo":null,
      "bunkerOrderLines":[  
         {  
            "key":244070009,
            "self":"http://localhost:8080/ws/rest/BunkerOrderLine/244070009",
            "minQuantity":50.0,
            "maxQuantity":100.0,
            "extraCost":0.0,
            "bunkeredQuantity":111.0,
            "unitPrice":100.0,
            "bunkerType":{  
               "key":73564540,
               "self":"http://localhost:8080/ws/rest/BunkerType/73564540",
               "isoCode":null,
               "isoYear":null,
               "bunkerTypeCode":"FO",
               "bunkerTypeDesc":"FO",
               "sulphurPercent":null
            }
         }
      ],
      "company":null,
      "bunkerBroker":{  
         "businessPartnerName":"BUSINESS PARTNER 1",
         "businessPartnerSort":"BUSINESS PARTNER 1",
         "businessPartnerCode":"1111",
         "businessPartnerType":{  
            "businessPartnerType":"BS",
            "businessPartnerTypeDesc":"Bunker Supplier",
            "key":1000034,
            "self":"http://localhost:8080/ws/rest/BusinessPartnerType/1000034"
         },
         "key":39697371,
         "self":"http://localhost:8080/ws/rest/BusinessPartner/39697371"
      },
      "bunkerAccountOf":null,
      "bunkerSupplier":{  
         "businessPartnerName":"BUSINESS PARTNER 2",
         "businessPartnerSort":"BUSINESS PARTNER 2",
         "businessPartnerCode":"22222",
         "businessPartnerType":{  
            "businessPartnerType":"BS",
            "businessPartnerTypeDesc":"Bunker Supplier",
            "key":1000034,
            "self":"http://localhost:8080/ws/rest/BusinessPartnerType/1000034"
         },
         "key":39697206,
         "self":"http://localhost:8080/ws/rest/BusinessPartner/39697206"
      },
      "remarks":[  

      ]
   } 
}

...

id

Unique identifier of the notification

eventTime

The time when the event occurred

objectType

Name of the changed Dataloy object

dataloyObject

The primary key of the changed Dataloy object (it can be different from the subscribed object, it can be an object in the hierarchy of the subscribed object )

eventType

C for creation, U for update, D for deletion

dataloyObjectSelf

the Dataloy URL of the changed object

subscription

Subscription data:

key	The primary key of the subscription
objectType	Name of the subscribed Dataloy object
self	API URL for the webhook subscription
dataloyObject	The primary key of the subscribed Dataloy object

resource

The JSON of the DataloyObject that the subscription refers to

New functionalities since version 3.9

With API 3.9 the following new functionalities have been introduced:

Possibility to be notified of changes via email
Possibility to customize the JSON pushed as Adjust Number of Fields to be Returned from a Request
Possibility to filter changes that have to be pushed via expressions
Possibility to filter changes that have to be pushed via scripts

Notifications via email

To be notified via email in the WebhookSubscription must be specified the channelInfo property with channelType EMAIL and the URL with the email address:

Code Block
{ "channelInfo": { "url": "info@dataloy.com", "channelType": "EMAIL" } }

channelType can be EMAIL or HTTP if HTTP is set the URL attribute must contain the endpoint where to push notifications.

Possibility to customize the JSON pushed

Through the attribute json of WebhookSubscription is possible to specify which attributes of the object must be pushed (see Adjust Number of Fields to be Returned from a Request). The value of json must be encoded with Base64.

For instance, if the subscription is for the object BunkerOrderLine a possible value for the json attribute could be:

Code Block
{"extraCost":"*"}

that encoded will be

Code Block
"json": "ew0KCSJleHRyYUNvc3QiOiIqIg0KfQ=="

In this way the sub-object in the attribute resource will be smaller:

Code Block

{  
   "id":"245-320996749",
   "eventTime":"2018-01-30T10:42:11",
   "eventType":"U",
   "objectType":"BunkerOrderLine",
   "dataloyObject":320996749,
   "dataloyObjectSelf":"http://platform-dev.dataloy.com:80/ws/rest/BunkerOrderLine/320996749",
   "subscription":{  
      "key":332501529,
      "self":"http://platform-dev.dataloy.com:80/ws/rest/WebhookSubscription/332501529",
      "isSubscriptionActive":true,
      "user":{  
         "key":999999,
         "self":"http://platform-dev.dataloy.com:80/ws/rest/User/999999",
         "userCode":"DATALOY",
         "userName":"dataloy"
      },
      "objectType":null,
      "dataloyObject":null,
      "url":null,
      "dlpAlertScript":{  
         "key":318269643,
         "self":"http://platform-dev.dataloy.com:80/ws/rest/DlpAlertScript/318269643",
         "scriptCode":"BUP",
         "scriptName":"Bunkered Unit Price updated"
      },
      "eventType":null,
      "unsubscriptionDate":null,
      "channelInfo":{  
         "key":332501528,
         "self":"http://platform-dev.dataloy.com:80/ws/rest/ChannelInfo/332501528",
         "channelType":{  
            "key":311504704,
            "self":"http://platform-dev.dataloy.com:80/ws/rest/ChannelType/311504704",
            "channelTypeCode":"EMAIL"
         },
         "url":"ab@dataloy.com"
      }
   },
   "resource":{  
      "key":320996749,
      "self":"http://platform-dev.dataloy.com:80/ws/rest/BunkerOrderLine/320996749",
      "extraCost":0.0
   }
}

Possibility to filter changes that have to be pushed via expressions

Through the attribute expression of WebhookSubscription is possible to write a Java expression against the object changed. At runtime If the expression return true the notification will be sent, otherwise no.

For instance, if the subscription is done for the object BunkerOrderLine a possible expression could be:

Code Block
dlpObject.getUnitPrice()!=null && ( dlpObject.getUnitPrice()>10 )

that for any changes at any BunkerOrderLine object will check if the unit price is not null and its value is between 10 and 100, if yes the notification will be sent.

In the expression must be used the variable dlpObject to refer to the changed object, the object will contain the new values. If the expression needs to check also the previous values of the object, the variable oldDlpObject can be used.

For instance:

Code Block
oldDlpObject.getExtraCost()!=null && dlpObject.getExtraCost()!=null && dlpObject.getExtraCost()> oldDlpObject.getExtraCost()

that will check if the new extra cost of a BunkerOrder is greater that the previous one.

If you want to be notified when an attribute change value from null to not null:

Code Block
oldDlpObject.getReferenceNo() == null && dlpObject.getReferenceNo() != null

The old values cannot be used for all object, please contact Dataloy support.

Easy way of writing expressions for webhook from version 6.9

The user need not know the attribute names in order to use an expression and will have the possibility to select an attribute from the list of attributes on the given objectType in the subscription and can chose the operators from the list of operators.

This is achieved by the use of special characters as listed below-

using . (Dot) in the expression field will list all the sub objects for the given object type. The list of attributes will be filtered based on the characters typed
$(dollar) will list the operators that can be used
using old or ,(comma) will enable the use of oldDlpObject in the expression

For example, instead of using this in an expression

Code Block
dlpObject.getInvoicingStatus() != null && dlpObject.getInvoicingStatus().getStatusTypeCode().equals(“RFP”) && (dlpObject.getDocumentType().getDocumentType().equals(“ACP”)

a simple of achieving this would be to use

Code Block
.invoicingStatus.statusTypeCode = RFP && .documentType.documentType = ACP OR .documentType.documentType = ACP

Image RemovedImage RemovedImage Removed

The need for the user to create expressions with null checks for the objects is also removed and will be taken care by the platform. Expressions will work the same way if the object is checked for null or not. For example both of the below shall work the same.

Code Block.invoicingStatus.statusTypeCode = RFP && .documentType.documentType = ACP OR .documentType.documentType = ACP .invoicingStatus != null && invoicingStatus.statusTypeCode = RFP && .documentType.documentType = ACP OR .documentType.documentType = ACP

object changed. At runtime If the expression return true the notification will be sent, otherwise no.

For instance, if the subscription is done for the object BunkerOrderLine a possible expression could be:

Code Block
dlpObject.getUnitPrice()!=null && ( dlpObject.getUnitPrice()>10 )

that for any changes at any BunkerOrderLine object will check if the unit price is not null and its value is between 10 and 100, if yes the notification will be sent.

In the expression must be used the variable dlpObject to refer to the changed object, the object will contain the new values. If the expression needs to check also the previous values of the object, the variable oldDlpObject can be used.

For instance:

Code Block
oldDlpObject.getExtraCost()!=null && dlpObject.getExtraCost()!=null && dlpObject.getExtraCost()> oldDlpObject.getExtraCost()

that will check if the new extra cost of a BunkerOrder is greater that the previous one.

If you want to be notified when an attribute change value from null to not null:

Code Block
oldDlpObject.getReferenceNo() == null && dlpObject.getReferenceNo() != null

The old values cannot be used for all object, please contact Dataloy support.

Possibility to filter changes that have to be pushed via scripts

Contact Dataloy to have info regarding scripts.

...

A new attribute xsl has been added which allows you to store an XSL stylesheet to transform the subscribed object to XML. The value of the field must be encoded with Base64. This is part only of Enterprise API.

New functionality since version 6.10.0

A new attribute, called doNotUnsubscribe (type boolean), has been added to prevent that the subscription will get unsubscribed, also if the endpoint is not reachable for more time of the max time of attempts set for the given server.

Supported Methods

GET /WebhookSubscription

...

Versions Compared

Old Version 73

New Version Current

Key

New functionalities since version 3.9

Notifications via email

Possibility to customize the JSON pushed

Possibility to filter changes that have to be pushed via expressions

Easy way of writing expressions for webhook from version 6.9

Possibility to filter changes that have to be pushed via scripts

New functionality since version 6.10.0

Supported Methods