1 of 55

API Release 8.11

Dataloy VMS API

The Dataloy VMS API documentation is intended as the main source of information and answers to queries and issues regarding integration with Dataloy VMS. It provides an overview of how integration with Dataloy VMS may be accomplished and detailed information about each type of integration.

High focus has been placed on quality of standard, substance and user-friendliness. The API knowledge base is kept continuously up-to-date. There is also a questions & answers section and a troubleshooting article section..

To search/navigate either click the links below or use the left-hand navigation panel to search by keyword, category or hierarchy.

API:

What is it?

Questions & Answers, Troubleshooting Articles:

Dataloy Rest API

Authentication / Authorization

Authentication and authorization is done through OAuth 2.

To get access to the protected resources OAuth 2.0 uses Access Tokens. An Access Token is a string representing the granted permissions.

To access to Dataloy API, you must request an Access Token.

To obtain an access token you need to do a POST request, to the provided URL, passing the client id and client secret in the payload

Example of POST payload to token URL

Parameters

Parameter Name

Description

Response

If all goes well, you'll receive an HTTP 200 response with a payload containing access_token, token_type, and expires_in values:

Call API endpoint

To call an API endpoint you must pass the retrieved Access Token as a Bearer token in the Authorization header of your HTTP request.

curl https://{URL}/ws/rest/{Resource}-H "Authorization: Bearer eyJ.........qLbZQ"

When an endpoint is invoked with an expired token the server sends a HTTP 401 response with the following payload:

The client should not ask for a new token for each call but use the same token as long as it is valid.

Data Model

Filtering

Dataloy REST API uses a generic search/filtering functionality. In general, all resources supports filtering on all properties of that resource and linked resources (for exceptions, see Limitations).

Syntax

The filter query parameter has the following format:

<Base URL>/<Resource>?filter=<json property>(OPERATOR)<value>

Example that will return currency information for USD:

Syntax Breakdown <Base URL>

For more information see

<Resource>

Can be any of the available in the Dataloy API.

<json property>

Can be any json property of the (for exceptions, see ).

<OPERATOR>

The operator is always:

surrounded by parenthesis
is always upper case

List of Operators

Operator

Description

API Version

Example

<value>

Numeric Values are straight forward. Can be integers or decimal numbers using a dot as decimal point.
Dates must be specified in the format: yyyy-MM-ddTHH:mm:ss
Strings can be surrounded by double quotes, but it is generally not necessary. Even if the string has spaces.

Combining Filters

The filter URL parameter can be added multiple times to filter on multiple properties in one request. To do so, add a new filter parameter to the end of the URL

Syntax for Combining Filters

Example:

Properties for Sub Objects

Filters can be used for sub objects by using a "dot path". Example of a sub object is commodity on Cargo:

To search for cargoes with commodity steel:

Limitations

The following properties are currently not possible for filtering:

self
remarks

A few other properties are unsupported, these are documented for each resource.

Examples

Cargo

Get Cargo with freight more than 1000000 and freightCurrency USD or EUR:

Document

Get Documents with documentType "INV" and invoicingStatus "PEN"

Voyage

Get Voyages for the vessel with vessel code ABRA

Get Voyage with reference number VES100

Get Voyage with start date > 01.01.2016 and operator is user with userCode "BAK"

Get Voyages that are operational for vessel ABRA

Get all Voyages that has Oslo as Load Port in 2015

Pagination

To return a defined number of objects for any Dataloy resource it has to be specified in the URL the page number, pageNumber parameter, and the number of objects that the page has to contain, limit parameter. For example:

/ws/rest/Document?pageNumber=1&limit=10&filter=documentAmount(GT)100000

it will return the first page containing at max 10 Document objects having the property documentAmount greater than 100000. In the response will be added an header parameter called totalObjectsNumber that indicates the total number of objects of the endpoint.

From API 5.18 is possible to avoid to get totalObjectsNumber sending the HTTP header parameter noCount = YES, this will allow a bit better performance.

Another example:

it will return the fourth page containing at max 10 Vessels objects having the countryCode property equals to EQ.

Adjust Number of Fields to be Returned from a Request

It is possible to adjust the number of fields that have to be returned from a resource. It's possible to both increase and decreases the number of fields from the default view. So if only field A and B from a resource is needed and the other X number of fields can be ignored, it can be specified in the header of the request. This will reduce the overhead of data transferred and improve performance. If more fields are needed in one request, to avoid making a second request to get all the data that is needed, this can also be done. So if fields A, B and C are returned in the default view, but also field D is needed, this can be specified in the header.

Customize the Number of Fields returned

Retrieving data from a resource may provide more information than needed. Fields with data to be returned can be specified by first adding a header field and then specifying the fields to be returned in the header field value. The header field value is specified as a JSON message following the same structure as the resource structure that is used when making the request. This enables fields to be specified in main- and sub-objects.

The examples listed illustrate how it is used for a business partner. The procedure is, however, the same for all resources. The key and self attribute will always be returned, but the number of displayed/hidden fields can be customized.

Business Partner without any field restriction will result in ( view example):

Examples

1. Return Business Partner name only:

fields: {"businessPartnerName":"*"}

2. Return address1 only:

fields: {"addresses": {"address1":"*"}}

Note that addresses is an array, but for the fields value it should be treated as a field, so do not include [ ]

3. Return Business Partner name and address1:

fields: {"businessPartnerName":"*", "addresses":{"address1":"*"}}

Expressions Made Easy

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

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 for more details about creating an expression subscription in vms

Webhooks - New functionalities

Do Not Unsubscribe

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.

User Guides

Voyages

Prerequisites

No prerequisites.

Bunker Transactions

Prerequisites

Before setting up and testing a bunker transaction integration other integrations need to be in place.

Transfer of voyage related data to the accounting system.

Integration Set-Up

When a bunker transaction is posted in Dataloy VMS, the document status is set to Ready-for-Posting. Set up a scheduled task and use the request under Data Transaction to extract bunker transactions that are ready for posting. When a bunker transaction is transferred to accounting, update the status to Posted.

Test Data

Test data for bunker transactions can be generated in Booking and Operations > Bunkers-FO tab > Bunker Transactions.

Data Transaction

To get bunker transactions that are ready for posting in the following subscription can be created:

Alternatively a scheduled job can be setup to use the following request:

Get bunker transactions that are ready for posting to accounting

Post Transaction

When an invoice is successfully transferred to the accounting system, the document status has to be updated to Posted in Dataloy VMS. This is done in a PUT request:

Update status to posted for a specific invoice

Actuals

Prerequisites

Ineeds to be in place before setting up and testing actuals integration.

Integration Set-Up

Autopost Invoices

When inserting data that in the end will result in an account payable, you might want to post the invoice directly. This can be done with a couple of API calls.

Generate Invoice Lines

To generate invoice lines you need to know the key of the voyage that your data relates to. If you dont have the voyage key already you need to get it from the API either by getting it at an earlier stage in your integration or with a separate call in this stage. If you for instance already have the port call key you can get the voyage key by doing a GET request on PortCall.

To generate invoice lines post the below request, where key is the voyage key. For multiple voyages, add multiple keys.

Then get the new invoice lines, called document lines in the API

Bunker Order Integration API

Service Order Integration API

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:

Enterprise functionality

Data access control via target object

Through DataControl objects is possible control the access to data of the logged user for a given object connected to the target.

For instance if we want to give access only to voyages connected with the business units that the user belong to, a DataControl object like this has to be posted:


{
    "matcherTarget": "BusinessUnit",
    "matcherAttributeTarget": "users.key",
    "objectName": "Voyage",
    "attribute": "voyageHeader.businessUnit"
}

matcherTarget defines the Dataloy object that has to be used as target object
matherAttributeTarget defines the attribute in the object target that links the object with the user
objectName the Dataloy object that has to be applied the access control
attribute the attribute name that link the Dataloy object with the target object

Data access control via target object and security role

Through the DataControl object it is possible to control data access for a target user(s) for a given object connected to the target by checking if the user(s) belongs to a given role.

For example, if we want to limit access for the captain of a vessel to only be able to view voyages of their vessel, a DataControl object like this has to be posted:

matcherTarget defines the Dataloy object that has to be used as target object
matcherAttributeTarget defines the attribute in the matcherTarget object that has to be used against the attribute of the object (objectName)

Fields access control

It is possible to create SecurityRole that remove the access to a set of fields of a given resource, both in read and write mode.

For example it is possible to create a role that remove the access to the voyageResult field of the Voyage resource

All the users that will have such role, in the response of the Voyage resource, the field voyageResult will be not present.

POST: http://dataloy.com/ws/rest/SecurityRole

{
    "roleName": "VoyageResult",
    "attributeForbiddens": [
        {
            "objectName": "Voyage",
            "attributeName": "voyageResult",
            "read": true,
            "write": true
             
        }
  ]
}

Bulk Deletion

It is possible to delete multiple objects, of a given resource, sending as URL parameters the list of keys:

DELETE: http://{host}/ws/rest/{Resource name}/delete?key={key 1}&key={key 2}&key={key 3}...

All the objects will be deleted in the same transaction

Furthermore, Bulk Delete supports object resequencing. This is useful in cases where the order of the objects is crucial and has to be precise, but also it's required to delete several objects at once. For instance, BunkerCategories on Vessel are following strict priority order, thus upon deletion, the order should be re-aligned.

Re-sequencing is active ONLY when at least a valid 'resequenceBy' string is passed.

DELETE: http://{host}/ws/rest/{ResourceName}/delete?resequenceBy={sequence field}&parentProperty={parent property}&key={key1}&key={key2}...
- Sequence field - is a string identifying the 'sequence property'. For example, it would be portCallSequence for ResourceName = PortCall.
- Parent property - Optionally filter by the parent group using a string specifying the parent field. For example, if ResourceName is PortCall, pass the field ownedByVoyage to re-sequence only PortCalls belonging to the same voyage.

Sub queries

API 5.21 supports sub-queries during any API query.

The syntax is:

filter=attributeName(OPERATOR){ResourceName.attributeName[filter_1],[filter_2],[filter_n]}

en-capsuling sub-queries between {} and the filters inside the sub-queries as list inside [ ]

Here an example to get the ongoing cargoes of a list of business partners:

http://dataloy.com/ws/rest/Cargo?filter=charterer.businessPartnerCode(IN)(133105,105882,123125,136200)&filter=key(IN)({Cargo.key[cargoPorts.portCall.eventLogs.event.eventCode(EQ)ARR][cargoPorts.portCall.eventLogs.eventLogDate(GT)2020-06-18T17:02:21][cargoPorts.cargoPortSequence(EQ)1],[cargoPorts.reasonForCall.reasonForCall(EQ)D]})&filter=key(IN)({Cargo.key[cargoPorts.portCall.eventLogs.event.eventCode(EQ)DEP][cargoPorts.portCall.eventLogs.eventLogDate(LT)2020-06-18T17:02:21][cargoPorts.cargoPortSequence(EQ)1],[cargoPorts.reasonForCall.reasonForCall(EQ)L]})

][cargoPorts.portCall.eventLogs.eventLogDate(GT)2020-06-18T17:02:21][cargoPorts.cargoPortSequence(EQ)1],[cargoPorts.reasonForCall.reasonForCall(EQ)D]%7D)&filter=key(IN)(%7BCargo.key[cargoPorts.portCall.eventLogs.event.eventCode(EQ)DEP][cargoPorts.portCall.eventLogs.eventLogDate(LT)2020-06-18T17:02:21][cargoPorts.cargoPortSequence(EQ)1],[cargoPorts.reasonForCall.reasonForCall(EQ)L]%7D)

The character { must be encoded with %7B and } with %7D

XML Transformation

API 5.24 offers support for XML transformations for any of the resource of the data model.

Using XSLT 3.0 is possible inject XSL strings to any GET request to translate the default JSON response in a XML string based on the XSL in input.

To achieve this the URLs to use are

/ws/rest/{ResourceName}/xml
/ws/rest/{ResourceName}/xml/{key}

the XSL must be set as HTTP header parameter with the name xsl.

Example of Cargo transformation:

XSL:

URL:

Output:

Webhooks

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.

Subscription

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:

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:

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:

New functionalities since

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
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:

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 ). 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:

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:

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:

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:

The old values will be accessible only for those Dataloy object changed via Dataloy API.

Possibility to filter changes that have to be pushed via scripts

Contact Dataloy to have info regarding scripts.

New functionalities since

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.

New functionalities since version 5.23

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.

New functionalities since version 5.24

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 functionalities since version6.44

In order to not get notified by the changes done by the user of the subscription the attribute notSendMyChanges can be set to true.

Supported Methods

GET /WebhookSubscription

Get a list of WebhookSubscription objects. Filter to avoid huge amounts of data (see 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

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.

Overview

PositionReport is used to update the status of an ongoing voyage's port calls.

Overview

Position reports update a port call's sailing, arrival, in port, and departure status. Most fields in the PositionReport object will only provide information, while a few affect the port call's results.

The following fields will affect the port call's results:

eventLogs
- An captures port events along with their dates and times. The port events include ARRIVAL, BERTHED, UNBERTHED, and DEPARTURE. To record the arrival date of a port call, an event log entry should include the ARRIVAL event along with the corresponding date.
- A records the remaining bunkers on board for a specific bunker category

Fields impacting the port call's results will have Major Change Factor marked as yes, along with a description, on the .

PositionReport can be one of these types:

Noon Report
- logs the ship's status at sea, updating the estimated arrival date and ROB info
Arrival Report
- logs when the ship arrives in the port, fixing the arrival date and ROB info

In order to include a on the position report, a separate API request must be made after the report is created. See for an example.

Details

Noon Report

Field Name

Json Attribute

Description

Mandatory

Major Change Factor

Data type

Notes

Noon report example

Noon Report sailing to a port

Assuming the voyage key, and port call sequence are known, get the PortCall key with this query and headers:

An example of the response could be found

Generate a Noon Report for the vessel that has sailed 3150 nm to the queried PortCall, with South/West wind direction and partly cloudy weather. Arrival LS MGO robs are also updated to 250

Arrival Report

Field Name

Json Attribute

Description

Mandatory

Major Change Factor

Data Type

Notes

Arrival report example

Arrival report on port call

Assuming the voyage key, and port call sequence are known, get the PortCall key with this query:

Example of the response can be found

Generate a report for arrival at 2nd August 2024 03:00 with arrival FO ROB at 225.85 mt and arrival LS MGO ROB at 235 mt

Berth Report

Field Name

Json Attribute

Description

Mandatory

Major Change Factor

Data Type

Notes

Berth report example

Berth report on a port call

Assuming the voyage key, and port call sequence are known, get the PortCall key with this query:

Generate a report that has berthed 3rd August 2024 08:00 with berth FO rob at 225 mt and DL rob at 220 mt

Unberth Report

Field Name

Json Attribute

Description

Mandatory

Major Change Factor

Data Type

Notes

Unberth report example

Unberth report on a port call

Assuming the voyage key, and port call sequence are known, get the PortCall key with this query:

Example response can be found

Generate a report that has unberthed 5th August 2024 08:00, FO unberth ROB at 225 mt, DL unberth at 218.5 mt

In Port Report

Field Name

Json Attribute

Description

Mandatory

Major Change Factor

Data Type

Notes

In port report example

In port report on a port call

Assuming the voyage key, and port call sequence are known, get the PortCall key with this query:

Generate a report to log sunny weather, East wind direction, hours in service, average wind force status in port

Departure Report

Field Name

Json Attribute

Description

Mandatory

Major Change Factor

Data Type

Notes

Departure Report example

Departure report on a port call

Assuming the voyage key, and port call sequence are known, get the PortCall key with this query:

Example of the response can be found

Generate a report that has fixes the departure date to 5th August 2024 08:30, departure FO rob at 225 mt and departure DL rob at 215 mt

More examples

PortCall query with "eventLogs" fields response

Arrival report with Remark

Send first this request

Example: Arrival vessel report to register arrival date at 8th August 2024 02:58, with remaining 98 MT of FO on board

The response of the query above returns the PositionReport key. Generate a Remark on the arrival position report that says "Arrival on the port remark":

Arrival report where port call key and voyage key are not known, using voyage.referenceNo and port name

Fetch the port call key

Generate arrival report