Get updates for nominated and operational voyages in Master scenario:
Get notification when an invoice is posted and ready to be transferred to accounting. Set the status to Posted when it's transferred to accounting. For more information about accounting integration see: https://dataloy-cloud.atlassian.net/wiki/spaces/VMSINT/pages/923414837
Get notified when accruals are posted and and ready to be transferred to accounting. Set the status to Posted when it's transferred to accounting. For more information about accounting integration see: https://dataloy-cloud.atlassian.net/wiki/spaces/VMSINT/pages/923414837
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
a simple of achieving this would be to use
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.
Refer Create Expression Webhook Subscription for more details about creating an expression subscription in vms
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.
Webhooks is moved out from Setup to Alerts Menu Item on VMS web
Alert menu item has two inclusions - Webhooks and Notifications
Webhooks - shows the list of subscriptions made by the user if the user is a non-administrative role and shows all the subscriptions in the system for an administrator user
Notifications - shows the list of Notifications for all the subscriptions visible for the user.
Clicking one of the rows in webhooks, opens the webhook subscription drawer with three tabs - Overview, Notifications and Comments
While Overview has some new additions to it, Comments remain the same from before.
Notifications tab in the subscription drawer includes the list of notifications filtered for the selected subscription. From 6.10.0, this list is updated to be similar to the other lists on VMS web with enabled filters and sorting.
Further clicking on one of the rows in the notifications list on subscription drawer, we can see the details of the Notification Msg sent for the subscription along with the error msg if the msg sending failed.
Holds the list of notifications for those subscriptions which the user has access to.
Administrator can access all the notifications for all the subscriptions available in the system, while non admin users can access only the subscriptions for the given logged in user. For example,
The possibility for the user to define a message template that should be used when sending notifications for a webhook subscription is introduced.
In order to use this, the user when creating a webhook subscription should provide the necessary input to the field/attribute “templateMsg". Make sure the placeholders are indicated by a '?' followed by the field/attribute directly accessible from the root object type on which the subscription is being made.
For example, when creating a subscription on Bank object , the user can use template_msg like ‘Bank with Name ?bankName is changed by ?changedById’ .
This would result in the below notification for the user (example data, for reference only)
Webhooks are user-defined HTTP callbacks that receive events for the subscribed event types. Webhook notifications are asynchronous, the order is not guaranteed.
Events are categorised into event types. Events occur due to changes in the state of a resource, such as when a voyage is updated. When an event occurs, the registered applications are notified via HTTP POST. The POST contains the event details, including the event type that caused the event.
When an application receives the event, it must respond with a 200-level HTTP status code.
When a webhook subscription is made, through the resource WebhookSubscription, for a Dataloy object, BunkerOrder for instance, the subscribed webhook will be pushed with all the changes that occurred to the subscribed object and its object hierarchy. So if a PortCall of the subscribed BunkerOrder is updated the webhook will be notified.
The Remarks are not part of the webhook process. It is not possible to get notifications of changes in Remarks.
The Dataloy webhook event type is a concatenation of the following attributes:
Resource name (Document, Voyage, ..)
Operation type (C,U, D create, update, delete)
Object key
The user can subscribe to a webhook for a given event, for example:
Cargo.C
Notifies when a Cargo is created
Document.D
Notifies when a Document is deleted.
Voyage.U
Notifies when a Voyage is updated.
Voyage.U.793628
Will notify when voyage, having voyage.key = 793628, is updated.
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:
The attributes have the following meaning:
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:
resource
The JSON of the DataloyObject that the subscription refers to
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
To be notified via email in the WebhookSubscription must be specified the channelInfo property with channelType EMAIL and the URL with the email address:
channelType can be EMAIL or HTTP if HTTP is set the URL attribute must contain the endpoint where to push notifications.
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:
that encoded will be
In this way the sub-object in the attribute resource will be smaller:
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:
dlpObject.getUnitPrice()!=null && ( dlpObject.getUnitPrice()>10 || dlpObject.getUnitPrice()<100)
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:
oldDlpObject.getExtraCost()!=null && dlpObject.getExtraCost()!=null && dlpObject.getExtraCost()> oldDlpObject.getExtraCost()
that will check if the new extra cost of a BunkerOrder is greater than the previous one.
If you want to be notified when an attribute change value from null to not null:
oldDlpObject.getReferenceNo() == null && dlpObject.getReferenceNo() != null
The old values will be accessible only for those Dataloy object changed via Dataloy API.
Contact Dataloy to have info regarding scripts.
In version 3.16 (and later) it is possible to decide if a webhook subscription should only be notified on changes to the object subscribed. So for instance making a subscription for the Voyage object, the changes that will occur to linked objects, like PortCall, Cargo, etc, will be not notified. To achieve this behaviour a new boolean attribute called onlyMainObject in WebhookSubscription has been added, setting it to true only the changes for the subscribed will be sent.
A new endpoint in WebhookSubscription POST:sendFailedNotifications has been added to resend manually the failed webhook notification.
In version 5.23 (and later) it is possible to decide if a webhook subscription should only be notified with the raw object, without the envelope payload. To achieve this behavior a new boolean attribute called rawObject in WebhookSubscription has been added, setting it to true the raw object will be sent.
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.
In order to not get notified by the changes done by the user of the subscription the attribute notSendMyChanges can be set to true.
GET /WebhookSubscription
Get a list of WebhookSubscription objects. Filter to avoid huge amounts of data (see Filtering documentation for examples).
GET /WebhookSubscription/{key}
Get a single WebhookSubscription object.
Example GET Return Body
since API 3.9:
POST /WebhookSubscription
Create a new WebhookSubscription.
Examples
Create a subscription to get notifications when the BunkerOrder with primary key 243896793 is updated:
Create a subscription to get notifications when any BunkerOrder is updated:
Create a subscription to get notifications when a BunkerOrder is created:
Create a subscription to get notifications when the BunkerOrder with primary key 243896793 is deleted:
Create a subscription to get notifications when any BunkerOrder is deleted:
Create a subscription to get notifications when any BunkerOrder is updated via email, since API 3.9:
Create a subscription to get notifications only when a Voyage object is changed, since API 3.16:
PUT /WebhookSubscription/{key}
Only the following attributes can be updated:
unsubscribed
url
webhookUsername
webhookPassword
Since API 3.9 is possible to change also these other attributes:
channelInfo
json
expression
dlpAlertScript
scriptParameterValues
useMsg
To unsubscribe a subscription the following JSON must be sent. It is not possible to update the subscription if it has been unsubscribed:
DELETE /WebhookSubscription/{key}
To delete a WebhookSubscription first it has to be unsubscribed. It is not possible to delete WebhookSubscription that got Webhook notifications, regardless that it has been unsubscribed or not.
