Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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 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
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
From version 2.10 it is possible to have multiple versions of Dataloy API deployed on an application server. New API functionalities can be utilized for certain clients while at the same time continue to use older API versions for other clients. This usage of the system can remain until all clients are tested and working with the latest Dataloy API version. The API version is specified in the URL.
Latest Version
The latest version of Dataly API deployed at a customer's application server remains available at:
http://[ip]:[port]/ws/rest
Older versions can be located at ws/rest/version-number. For example, if version 2.10.0 is deployed it will be found at:
http://[ip]:[port]/ws/rest/6.38.0
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)
objectName the Dataloy object that has to be applied the access control
attribute the attribute name that links the Dataloy object with the target object
dataControlRoleValues list of SecurityRole that the DataControl will be applied
In the above example if an User that belong to the SecurityRole "MATER_ONLINE_VESSEL" make a query to the endpoint Voyage, the server will return only the voyages that has voyageHeader.vesselCodes.masterUser = {the user that made the query}
Is possible restrict access to any endpoint.
In order for a user to get access to a given API Endpoint, the user must belong to a SecurityRole that has a SecurityPermission for the API Endpoint.
he endpoint access control is done also against the objects requested using the fields JSON in the HTTP Header. So for instance if the endpoint Vessel.GET is present and the user does not belong to a SecurityRole that has a SecurityPermission for the Vessel.GET endpoint, requesting the Voyage resource specifying the following JSON in the fields parameter will get unauthorized (HTTP 401):
If the same user requests with the following JSON, it will get access because vesselName attribute is part of the minimal view of Vessel resource:
The same access control is performed when a WebhookSubscription is requested. If the user tries to subscribe for an object that has an Endpoint in the system, the subscription will be created only if the user can access to the Endpoint, otherwise Bad request (HTTP 400) exception will be thrown.
To create a new Endpoint it has to be used the endpoint /ws/rest/Endpoint posting a JSON like this:
To create a new SecurityPermission it has to be used the endpoint /ws/rest/SecurityPermission posting a JSON like this:
To create a new SecurityRole. Post the following JSON to /ws/rest/SecurityRole:
To add a SecurityPermission to a SecurityRole. Post the following JSON to /ws/rest/SecurityRole:
To add a SecurityRole to a User. Post the following JSON to /ws/rest/SecurityRole:
Build interactive HTML 5 application using Dataloy Websockets.
It is possible to open a Websocket to get notified when there are changes in Dataloy data model.
The concept is very similar to Webhooks, it is possible open a socket to be notified for Creation, Update and Deletion of any of object type of the data model.
The endpoint syntax is:
ws://{url}/ws/rest/WebSocketObjectSubscription/{objectType}/{eventType}/{key}/{token}
The JSON pushed will have the same structure of the one pushed by Webhooks.
It is possible to customize the JSON sent from the Server to the Client using Adjust Number of Fields to be Returned from a Request.
(The JSON fields can be sent through the open Websocket by the Client to the Server)
(To get back to the standard fields list a empty JSON ( {} ) can be sent from the client to the server)
It is possible to open a Websocket linked to an Alert Script to be notified when the script is fired and returns true.
The endpoint to use is:
ws://{url}/ws/rest/WebSocketAlertScript/{scriptCode}/{token}
Passing the script code.
It is possible copy any object of any resource with the following endpoint:
It will create a new object in the data model, copying also the sub-objects, and will return it as response.
It is possible override attributes passing a JSON in the body (passing an attribute with null value will have no effect. Only simple types in the first level of the JSON will be used to override).
It is possible copy multiple objects, of a give resource, sending as URL parameters the list of keys:
POST: http://{host}/ws/rest/{Resource name}/copy?key={key 1}&key={key 2}&key={key 3}...
it will create a new object for all the specified keys and returns am array of the created objects.
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]})
http://dataloy.com/ws/rest/Cargo?filter=charterer.businessPartnerCode(IN)(133105,105882,123125,136200)&filter=key(IN)(%7BCargo.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]%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
Is possible to use both OR and AND operators in API queries. The two new operators syntax are:
(OR)
(AND)
Set of filters can be separated by OR and AND operators, the filters within a single set of filter will be put in AND.
Some examples:
Cargo?filter=charterer.businessPartnerType.businessPartnerType(EQ)&filter=(OR)&filter=weight(GT)400000
CargoPort?filter=cargo.charterer.key(EQ)1001845&filter=cargo.voyage.voyageStatus(EQ)%20&filter=port.portName(IN)(OSLO)&filter=reasonForCall.reasonForCall(EQ)L&filter=(OR)&filter=cargo.voyage.voyageStatus(EQ)%20&filter=port.portName(IN)(GAETA)&filter=reasonForCall.reasonForCall(EQ)D&filter=(OR)&filter=reasonForCall.reasonForCall(EQ)E
Limitations:
It is not possible use calculated fields with AND and/or OR.
Parenthesis are not supported
Through DataControl and DataControlRoleValue is possible to give access only to some specific objects.
For instance if we want that the users that belong to the security role with key 59552772 can have access only to the documents connected with the business partner with key 20867070 and 22210381, a DataContol object like this has to be posted:
objectName the Dataloy object that has to be applied the access control
attribute the attribute name to be used to restrict the access
role the security role that will use the access control (use the key, as role names containing spaces might not work)
value the value to use as filter to restrict data
valueType the type of the value (Integer, String)
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.
With expressions is possible to use logical syntax, like we do in SQL, to filter any resource response.
One easy example could be (assuming that we are querying Voyage endpoint):
voyageResult > 1000 and voyageHeader.voyageStatus.statusTypeCode= 'FIN'
Bit more complex one could be:
vessel.vesselName ='Borg 1' and (voyageHeader.operator = 999999 or voyageHeader.charteringResponsible = 999999 or voyageHeader.accountantResponsible= 999999)
That introduce a completely new possibility, the usage of parenthesis.
It is possible to have any level of nested parenthesis:
(voyageHeader.operator != 999999 and ((voyageResult > 10000 and voyageHeader.voyageStatus.statusTypeCode= 'FIN') or (voyageResult < 10000 and voyageHeader.voyageStatus.statusTypeCode= 'NOM')))
Support for between operator:
voyageResult between 1000 and 2000
The dates in the expression must be preceded by the character $
voyageHeader.voyageStartDate > $2020-12-29T17:02:21
To get all the voyages of the master scenario:
(voyageHeader.voyageStartDate>=$2021-01-14T17:02:21 and fleetPlanVoyages.fleetPlan.fleetPlanCode='MASTER') or (scenarios.scenarioCode='MASTER' and voyageHeader.voyageStatus.statusTypeCode= 'SCU')
Supported Operators (all the operator are case sensitive):
Operator
=
equal to
!=
not equal to
>
greater than
>=
greater than equal to
<
less than
<=
less than equal to
between
between
not between
not between
in
in
not in
not in
like
like
% must be encode with %25
not like
not like
likeIgnoreCase
like ignore case
not likeIgnoreCase
not like ignore case
!
negation
on Vessel resource: ! (hasGrabsOnboard = false and iceClass = null)
The expressions can be used in any resource of the data model.
The expression can be passed or through the URL query parameter called expression (remember to encode):
ws/rest/Voyage?expression=vessel.vesselName='Borg 1' or voyageResult between 10 and 10000
or through the HTTP header parameter called expression.
The expression can be used in combination with sorting and pagination through URL query parameters.
Calculated fields cannot be used within the expressions.
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: http://platform-dev.dataloy.com/ws/rest/Cargo/xml/1225540
Output:
The Bulk Update can be used to any object of the data model.
The endpoint to use is:
PUT: key={key 1}&key={key 2}&key={key 3}...
passing ,to the specified resource, a list of key that have to be changed by the input body.
The endpoint returns 204 with no content if succeeded.
Bulk Update can also be used with :
For example
It is possible to create scripts, written in pseudo Java, that can be injected at runtime and used by Webhooks and Websockets.
An Alert Script can be very simple or very complex, their scope is to evaluate conditions and return true or false. If the script returns true the message is sent.
Alerts can be created and installed at run-time into the system. These are the predefined alerts available: