Short Description
Dataloy Vessel Report System (Dataloy VRS) enables vessels to send vessel reports without proper internet connection. The server side of Dataloy VRS is exposed in the Dataloy API for inserting vessel reports into Dataloy VMS. When Dataloy VRS is in use, the client side of the Vessel Report API system can be ignored - the message sent by e-mail to the VRS is identical to what can be posted in the Vessel Report API (with minor adjustments). Inserting a vessel report into Dataloy VMS not only inserts a position report, but also the schedule, bunkers etc. There is also a functionality available for locating correct port call based on vessel code and report date.
Chapter Contents:
Long Description
Vessel Report API Process
Custom Fields
Custom fields can be added
- using Events (if there is an event code and date).
- or added as a Remark (text field).
Events are added and retrieved from Master Data and can be used in a JSON message. Event fields in the JSON message is shortened:
- ed = event date
- ec = event code.
Remarks will be connected to the Position Report. To send remarks requires:
- the set-up of a remark template in the database with a title and the extraction of the remark_id.
Note: This construction is usually met with various various challenges with e-mail based vessel reporting (more information: contact Dataloy).
IMPORTANT: This type of construction causes various challenges with e-mail based vessel reporting (more information: contact contact Dataloy).
Alerts
Alerts can be triggered either:
- when reports are inserted to Dataloy VMS
- or a report is failing.
IMPORTANT: Property Settings is handled in: Master Data > Dataloy Properties.
Properties
| Property | Description |
|---|---|
| com.dataloy.integration.vessel.voyageNoAndRFC | When set to true: referenceNo and reasonForCall can be added to the json message. This makes it easier for VRS to locate the correct port call and will reduce errors. |
| com.dataloy.integration.vessel.reportMailRecipients | List of email addresses separated by semicolon. A vessel report successfully inserted into Dataloy VMS results in a report being sent to the addresses in this property value. The report will list all values sent from the vessel. |
| com.dataloy.integration.vessel.errormail.recipient |
|
| com.dataloy.integration.vessel.errormail.sender | An e-mail address will be the sender of the Error Mail. |
| com.dataloy.integration.vessel.sendReportMailToOperator | When set to true: A vessel report successfully inserted into Dataloy VMS results in a report being sent to the Voyage Operator, listing all values sent from the vessel. |
com.dataloy.mail.smtp | smtp must be setup for e-mail alerts to function. |
Base URL
The Vessel Report URL:
Base URL + ws/rest/VesselReport
Noon report
| JSON Field Name | Description | Affects Dataloy VMS | Mandatory | Type | Length |
|---|---|---|---|---|---|
| portCallId | A port call id | If the port call id is available, use this to avoid VRS trying to locate the correct port call. | |||
| referenceNo | Voyage reference number | Makes it easier for VRS to locate correct port call which results in less errors. Requires a 924581992924581992. | |||
| reasonForCall | 924581992 | Makes it easier for VRS to locate correct port call which results in less errors. Requires a 924581992924581992. | |||
reportTypeCode |
| Used to insert correct type of Position Report and to locate correct port call. | Yes | String | 4 |
vesselCode | 924581992 | Used in combination with report date local time to locate the port call in Dataloy VMS. | Yes | String | 6 |
reportDateLocal | Report Date Local Time | Used in combination with vessel code to locate the port call in Dataloy VMS. Inserted in the Postition Report. | Yes | Date | |
latitude | Position Latitude (Decimal Degrees) | Inserted in Position Report. | Double | 5 | |
longitude | Position Longitude (Decimal Degress) | Inserted in Position Report. | Double | 5 | |
portId | Arrival Port, 924581992 | When a port call is located based on vessel and report date, Dataloy VMS checks the reported port against the port in Dataloy VMS. | Yes | Integer | 38 |
arrival | Estimated Time of Arrival | Updates ETA in Schedule. | Yes | Date | |
berthed | Estimated Time of Berthing | Updates ETB in Schedule. | Date | ||
departure | Estimated Time of Departure | Updates ETD in Schedule. | Date | ||
trueCourse | True Course | Inserted in Position Report. | Integer | 38 | |
distanceSailed | Distance Sailed Since Last Report | Inserted in Position Report. | Double | ||
hoursInService | Hours in Service Since Last Report | Inserted in Position Report. | Double | ||
distanceToNextPort | Distance To Go | Inserted in Position Report. | Double | ||
speedMadeGood | Speed Made Good | Inserted in Position Report. | Double | ||
windDirectionId | Wind Direction (924581992) | Inserted in Position Report. | Integer | 38 | |
averageWindForce | Wind Force. Beaufort. | Inserted in Position Report. | Integer | 38 | |
seaDirectionId | Sea Direction (924581992) | Inserted in Position Report. | Integer | 38 | |
averageSeaState | Sea State. Integer from 0 - 9. | Inserted in Position Report. | Integer | 38 | |
bhpMainEngineIndicatedRpm | Main Engine RPM Since Last Report | Inserted in Position Report. | Double | ||
dailyFo | Daily Fuel Oil Consumption | Inserted in Position Report. | Double | ||
dailyDo | Daily Diesel Oil Consumption | Inserted in Position Report. | Double | ||
dailyFl | Daily Fuel Oil Low Sulphur Consumption | Inserted in Position Report. | Double | ||
dailyDl | Daily Diesel Oil Low Sulphur Consumption | Inserted in Position Report. | Double | ||
dailyFw | Daily Net Fresh Water Consumption | Inserted in Position Report. | Double | ||
robFo | Fuel Oil Remaining on Board (FO RoB) | Inserted in Position Report. | Double | ||
robDo | Diesel Oil Remaining on Board (DO RoB) | Inserted in Position Report. | Double | ||
robFl | Fuel Oil Low Sulphur Remaining on Board (FO LS RoB) | Inserted in Position Report. | Double | ||
robDl | Diesel Oil Low Sulphur Remaining on Board (DO LS RoB) | Inserted in Position Report. | Double | ||
robFw | Fresh Water Remaining on Board | Inserted in Position Report. | Double | ||
genericRemark | Remark | Inserted as a Remark to the Position Report. | String | Unlimited |
Arrival report
| JSON Field Name | Description | Affets Dataloy VMS | Mandatory | Type | Length |
|---|---|---|---|---|---|
| portCallId | A port call id | If the port call id is available, use this to avoid VRS trying to locate the correct port call. | |||
| referenceNo | Voyage reference number | Makes it easier for VRS to locate correct port call which results in less errors. Requires a 924581992924581992. | |||
| reasonForCall | 924581992 | Makes it easier for VRS to locate correct port call which results in less errors. Requires a 924581992924581992. | |||
reportTypeCode | Vessel Report Type Value = ARR for Arrival Report. | Used to insert the correct type of Position Report and to locate the correct port call. | Yes | String | 4 |
vesselCode | 924581992 | Used in combination with report date local time to locate the port call in Dataloy VMS. | Yes | String | 6 |
portId | Arrival Port, 924581992 | When a port call is located based on vessel and report date, Dataloy VMS checks the reported port against the port in Dataloy VMS. | Yes | Integer | 38 |
reportDateLocal | Report Date Local Time | Used in combination with vessel code to locate the port call in Dataloy VMS. | Yes | Date | |
arrival | Time of Arrival | Updates ETA in Schedule. | Yes | Date | |
berthed | Time of Berthing (Estimated if Anchoring) | Updates ETB in Schedule | Yes | Date | |
departure | Estimated Time of Departure | Updates ETD in Schedule. | Yes | Date | |
distanceSailedSinceDeparture | Total Distance Sailed Since Departure | Updates Miles in Schedule. | Double | ||
distanceSailed | Distance Sailed Since Last Report | Inserted in Postion Report. | Double | ||
hoursStoppages | Hours Stoppages | Updates Days Stoppages (see the Perfomance tab in Booking and Operations). | Double | ||
hoursInService | Hours in Service | Inserted in Postion Report. | Double | ||
speedMadeGood | Speed Made Good Since Last Report | Inserted in Postion Report. | Double | ||
draftAft | Draft Aft | Inserted in Postion Report. | Double | ||
draftForward | Draft Forward | Inserted in Postion Report. | Double | ||
dailyFo | Daily Fuel Oil Consumption | Inserted in Postion Report. | Double | ||
dailyDo | Daily Diesel Oil Consumption | Inserted in Postion Report. | Double | ||
dailyFl | Daily Fuel Oil Low Sulphur Consumption | Inserted in Postion Report. | Double | ||
dailyDl | Daily Diesel Oil Low Sulphur Consumption | Inserted in Postion Report. | Double | ||
dailyFw | Daily Net Fresh Water consumption | Inserted in Postion Report. | Double | ||
robFo | Fuel Oil Remaining on Board (FO RoB) | Updates Fuel Oil Remaining on Board (FO RoB) Arrival. | Double | ||
robDo | Diesel Oil Remaining on Board (DO RoB) | Updates Diesel Oil Remaining on Board (DO RoB) Arrival. | Double | ||
robFl | Fuel Oil Low Sulphur Remaining on Board (FO LS RoB) | Updates Fuel Oil Low Sulphur Remaining on Board (FO LS RoB) Arrival. | Double | ||
robDl | Diesel Oil Low Sulphur Remaining on Board (DO LS RoB) | Updates Diesel Oil Low Sulphur Remaining on Board (DO LS RoB) Arrival. | Double | ||
robFw | Fresh Water remaining on board | Inserted in Postion Report. | Double | ||
genericRemark | Remark | Inserted as a Remark to the Position Report. | String | Unlimited |
In Port Report
| JSON Field Name | Description | Affects Dataloy VMS | Mandatory | Type | Length |
|---|---|---|---|---|---|
| portCallId | A port call id | If the port call id is available, use this to avoid VRS trying to locate the correct port call. | |||
| referenceNo | Voyage reference number | Makes it easier for VRS to locate correct port call which results in less errors. Requires a 924581992924581992. | |||
| reasonForCall | 924581992 | Makes it easier for VRS to locate correct port call which results in less errors. Requires a 924581992924581992. | |||
reportTypeCode | Vessel Report Type | Used to insert the correct type of Position Report and to locate the correct port call. | Yes | String | 4 |
vesselCode | 924581992 | Used in combination with report date local time to locate the port call in Dataloy VMS. | Yes | String | 6 |
portId | Port, 924581992 | When a port call is located based on vessel and report date, Dataloy VMS checks the reported port against the port in Dataloy VMS. | Yes | Integer | 38 |
reportDateLocal | Report Date Local Time | Used in combination with vessel code to locate the port call in Dataloy. | Yes | Date | |
berthed | Estimated Time of Berthing | Updates ETB in Schedule | Date | ||
departure | Estimated Time of Departure | Updates ETD in Schedule. | Yes | Date | |
hoursInService | Hours in Service | Inserted in Postion Report. | Double | ||
weatherId | Weather. 924581992 | Inserted in Postion Report. | Integer | 38 | |
windDirectionId | Wind Direction. 924581992 | Inserted in Postion Report. | Integer | 38 | |
averageWindForce | Average Wind Force. Beaufort. | Inserted in Postion Report. | Integer | 38 | |
genericRemark | Remark | Inserted as a Remark to the Position Report. | String | Unlimited |
Departure Report
| JSON Field Name | Description | Affects Dataloy VMS | Mandatory | Type | Length |
|---|---|---|---|---|---|
| portCallId | A port call id | If the port call id is available, use this to avoid VRS trying to locate the correct port call. | |||
| referenceNo | Voyage reference number | Makes it easier for VRS to locate correct port call which results in less errors. Requires a 924581992924581992. | |||
| reasonForCall | 924581992 | Makes it easier for VRS to locate correct port call which results in less errors. Requires a 924581992924581992. | |||
reportTypeCode | Vessel Report Type. Value = DEP for Departure Report. | Used to insert the correct type of position report and to locate the correct port call. | Yes | String | 4 |
vesselCode | 924581992 | Used in combination with report date local time to locate the port call in Dataloy VMS. | Yes | String | 6 |
portId | Departure Port, 924581992 | When a port call is located based on vessel and report date, Dataloy VMS checks the reported port against the port in Dataloy VMS. | Yes | Integer | 38 |
reportDateLocal | Report Date Local Time | Used in combination with vessel code to locate the port call in Dataloy VMS. | Yes | Date | |
departure | Departure Time | Updates Estimated Time of Departure (ETD) in Schedule. | Yes | Date | |
nextPortId | Next Arrival Port, 924581992 | When a port call is located based on vessel and report date, Dataloy VMS checks the reported port against the port in Dataloy VMS. | Integer | 38 | |
arrival | Estimated Time of Arrival | Updates Estimate Time of Arrival (ETA) for next Arrival Port. | Date | ||
distanceToNextPort | Distance To Next Port | Inserted in Postion Report. | Double | ||
draftAft | Draft Aft | Inserted in Postion Report. | Double | ||
draftForward | Draft Forward | Inserted in Postion Report. | Double | ||
robFo | Fuel Oil Remaining on Board (FO RoB) | Updates Fuel Oil Remaining on Board (FO RoB) departure. | Double | ||
robDo | Diesel Oil Remaining on Board (DO RoB) | Updates Diesel Oil Remaining on Board (DO RoB) departure. | Double | ||
robFl | Fuel Oil Low Sulphur Remaining on Board (FO LS RoB) | Updates Fuel Oil Low Sulphur Remaining on Board (FO LS RoB) departure. | Double | ||
robDl | Diesel Oil Low Sulphur Remaining on Board (DO LS RoB) | Updates Diesel Oil Low Sulphur Remaining on Board (FO LS RoB) departure. | Double | ||
robFw | Fresh Water Remaining on Board | Inserted in Postion Report. | Double | ||
foBunkered | Bunkered Fuel Oil | Updates Fuel Oil bunkered for departure port call. | Double | ||
flBunkered | Bunkered Fuel Oil Low Sulphur | Updates Fuel Oil Low Sulphur bunkered for departure port call. | Double | ||
doBunkered | Bunkered Diesel Oil | Updates Diesel Oil bunkered for departure port call. | Double | ||
dlBunkered | Bunkered Diesel Oil Low Sulphur | Updates Diesel Oil Low Sulphur bunkered for departure port call. | Double | ||
genericRemark | Remark | Inserted as remark to position report. | String | Unlimited |
Example Messages
Updated for API version 2.0.0 using the new required date format yyyy-dd-MMThh:mi:ss to conform ISO 8601, (prior version has date format: yyyy-dd-MM hh:mi:ss)
Arrival
{
"remarks":[
],
"events":[
{
"ed":"2013-12-24T00:00:00",
"ec":"VR05"
},
{
"ed":"2013-12-24T00:00:00",
"ec":"VR10"
}
],
"reportTypeCode":"ARR",
"vesselCode":"14",
"portId":"104419",
"reportDateLocal":"2013-12-24T00:00:00",
"arrival":"2013-12-24T00:00:00",
"berthed":"2013-12-24T00:00:00",
"departure":"2013-12-24T00:00:00",
"distanceSailed":"10",
"distanceSailedSinceDeparture":"10",
"hoursInService":"10",
"hoursStoppages":"10",
"speedMadeGood":"10",
"draftAft":"10",
"draftForward":"10",
"dailyFo":"10",
"dailyDo":"10",
"dailyFl":"10",
"dailyDl":"10",
"dailyFw":"10",
"robFo":"10",
"robDo":"10",
"robFl":"10",
"robDl":"10",
"robFw":"10",
"genericRemark":"Remark"
}
Departure
{
"remarks":[
{
"id":"70495513",
"r":"10"
},
{
"id":"70495512",
"r":"10"
},
{
"id":"70495511",
"r":"10"
},
{
"id":"70495510",
"r":"10"
},
{
"id":"70495509",
"r":"10"
},
{
"id":"70495514",
"r":"10"
},
{
"id":"70495515",
"r":"10"
},
{
"id":"70495516",
"r":"10"
},
{
"id":"70495517",
"r":"10"
},
{
"id":"70495518",
"r":"10"
},
{
"id":"70495519",
"r":"10"
}
],
"events":[
{
"ed":"2013-12-24T00:00:00",
"ec":"VR15"
},
{
"ed":"2013-12-24T00:00:00",
"ec":"VR20"
},
{
"ed":"2013-12-24T00:00:00",
"ec":"VR25"
},
{
"ed":"2013-12-24T00:00:00",
"ec":"VR30"
},
{
"ed":"2013-12-24T00:00:00",
"ec":"VR40"
},
{
"ed":"2013-12-24T00:00:00",
"ec":"VR45"
},
{
"ed":"2013-12-24T00:00:00",
"ec":"VR50"
},
{
"ed":"2013-12-24T00:00:00",
"ec":"VR55"
}
],
"reportTypeCode":"DEP",
"vesselCode":"14",
"portId":"104419",
"reportDateLocal":"2013-12-24T00:00:00",
"departure":"2013-12-24T00:00:00",
"nextPortId":"104419",
"arrival":"2013-12-24T00:00:00",
"distanceToNextPort":"10",
"draftAft":"10",
"draftForward":"10",
"robFo":"10",
"robDo":"10",
"robFl":"10",
"robDl":"10",
"robFw":"10",
"foBunkered":"10",
"flBunkered":"10",
"doBunkered":"10",
"dlBunkered":"10",
"genericRemark":"Remark"
}
Noon
{
"remarks":[
],
"events":[
],
"reportTypeCode":"NOON",
"vesselCode":"14",
"latitude":10.17,
"longitude":10.17,
"portId":"104419",
"reportDateLocal":"2013-12-24T00:00:00",
"arrival":"2013-12-24T00:00:00",
"berthed":"2013-12-24T00:00:00",
"departure":"2013-12-24T00:00:00",
"trueCourse":"10",
"distanceSailed":"10",
"hoursInService":"10",
"distanceToNextPort":"10",
"speedMadeGood":"10",
"windDirectionId":"911638",
"averageWindForce":"0",
"seaDirectionId":"911638",
"averageSeaState":"1",
"bhpMainEngineIndicatedRpm":"10",
"dailyFo":"10",
"dailyDo":"10",
"dailyFl":"10",
"dailyDl":"10",
"dailyFw":"10",
"robFo":"10",
"robDo":"10",
"robFl":"10",
"robDl":"10",
"robFw":"10",
"genericRemark":""
}
Port
{
"remarks":[
{
"id":"70495526",
"r":"100"
},
{
"id":"70495527",
"r":"100"
},
{
"id":"70495528",
"r":"100"
}
],
"events":[
{
"ed":"2013-12-24T00:00:00",
"ec":"VR60"
}
],
"reportTypeCode":"PORT",
"vesselCode":"14",
"portId":"104419",
"reportDateLocal":"2013-12-24T00:00:00",
"berthed":"2013-12-24T00:00:00",
"departure":"2013-12-24T00:00:00",
"hoursInService":"20",
"weatherId":"950936",
"windDirectionId":"913903",
"averageWindForce":"1",
"genericRemark":"Remark"
}
Consumption Breakdown
The following fields can be added for consumption breakdown
| Main Engine - Fuel Oil | Inserted to position report. |
| Main Engine - Fuel Oil Low Sulphur | Inserted to position report. |
| Main Engine - Diesel Oil | Inserted to position report. |
| Main Engine - Diesel Oil Low Sulphur | Inserted to position report. |
| Auxiliary - Fuel Oil At Sea | Inserted to position report. |
| Auxiliary - Fuel Oil Low Sulphur At Sea | Inserted to position report. |
| Auxiliary - Diesel Oil At Sea | Inserted to position report. |
| Auxiliary - Diesel Oil Low Sulphur At SeaInserted to position report. | Inserted to position report. |
| Boilers - Fuel Oil Idle | Inserted to position report. |
| Boilers - Fuel Oil Low Sulphur Idle | Inserted to position report. |
| Boilers - Diesel Oil Idle | Inserted to position report. |
| Boilers - Diesel Oil Low Sulphur Idle | Inserted to position report. |
| Boilers - Fuel Oil Working | Inserted to position report. |
| Boilers - Fuel Oil Low Sulphur Working | Inserted to position report. |
| Boilers - Diesel Oil Working | Inserted to position report. |
| Boilers - Diesel Oil Low Sulphur Working | Inserted to position report. |
| Generators - Fuel Oil At Sea | Inserted to position report. |
| Generators - Fuel Oil Low Sulphur At Sea | Inserted to position report. |
| Generators - Diesel Oil At Sea | Inserted to position report. |
| Generators - Diesel Oil Low Sulphur At Sea | Inserted to position report. |
| Cleaning - Fuel Oil | Inserted to position report. |
| Cleaning - Fuel Oil Low Sulphur | Inserted to position report. |
| Cleaning - Diesel Oil | Inserted to position report. |
| Cleaning - Diesel Oil Low Sulphur | Inserted to position report. |
| Heating - Fuel Oil Consumption | Inserted to position report. |
| Heating - Fuel Oil Low Sulphur | Inserted to position report. |
| Heating - Diesel Oil | Inserted to position report. |
| Heating - Diesel Oil Low Sulphur | Inserted to position report. |
Weather Data
When inserting weather data, use the ID from the Weather Data table:
| Weather ID | Weather Description |
|---|---|
950926 | Clear Sky |
950927 | Sunny Day |
950928 | Partly Cloudy |
950929 | Sunny Intervals |
950930 | Dust |
950931 | Mist |
950932 | Fog |
950933 | Medium-Level Cloud |
950934 | Low-Level Cloud |
950935 | Light Rain Shower |
950936 | Drizzle |
950937 | Light Rain |
950938 | Heavy Rain Shower |
950939 | Heavy Rain |
950940 | Sleet Shower |
950941 | Sleet |
950942 | Hail Shower |
950943 | Hail |
950944 | Light Snow Shower |
950945 | Light Snow |
950946 | Heavy Snow Shower |
950947 | Heavy Snow |
950948 | Thundery Shower |
950949 | Thunder Storm |
950950 | Tropical Storm |
950951 | Haze |
Direction
When inserting direction, use the ID from the Direction Table:
| Direction id | Direction Description |
|---|---|
911636 | North |
911637 | South |
911638 | East |
911639 | West |
911640 | North/East |
911641 | North/West |
911642 | South/East |
911643 | South/West |
913753 | Various |
913902 | North/North/East |
913903 | East/North/East |
913904 | East/South/East |
913905 | South/South/East |
913906 | South/South/West |
913907 | West/South/West |
913908 | West/North/West |
913909 | North/North/West |
916765 | East/by/North |
916766 | East/by/South |
916767 | North/by/East |
916768 | North/by/West |
916769 | NE/by/East |
916770 | NE/by/north |
916771 | NW/by/North |
916772 | NW/by/West |
916773 | SE/by/East |
916774 | SE/by/South |
916775 | SW/by/South |
916776 | SW/by/West |
916777 | South/by/East |
916778 | South/by/West |
916779 | West/by/North |
916780 | West/by/South |
Reason For Call
| Code | Description |
|---|---|
| L | Loading |
| D | Discharging |
| C | Canal Passage |
| E | Extra Port |
| DD | Dry Dock |
| DEL | Delivery |
| RED | Redelivery |
| B | Bunkering |
| R | Repair |
| CL | Tank / Hold Cleaning |
| STS | Ship to Ship |
| W | Waiting |
| CC | Customs Clearance |
Dataloy Vessel Code
Dataloy Vessel Codes can be found by using the Vessel Code Resource.
Dataloy Port ID
Dataloy Port ID's can be found be using the Port Resource.