New Vessel Report API

From 6.29

Short Description

Inserting a position into Dataloy VMS updates the schedule, bunkers etc. The new Vessel Report API requires a proper internet connection. See /wiki/spaces/VMSINT/pages/923414876 for the documentation about Dataloy Vessel Report System which does not require proper internet connection.

Chapter Contents:

Long Description

All fields will get inserted to a Position Report.

Position Report API Process

~~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	E-mail address list separated by semicolon. The e-mail address owners will receive an e-mail if a vessel report is failing. The Voyage Operator will also receive a message if the User has registered relevant e-mail address.
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 Position Report URL:

Base URL + ws/rest/PositionReport

Noon report

JSON Field Name	Description	Affects Dataloy VMS	Mandatory	Type	Length
portCall	A port call object		Yes
reportTypeCode	Vessel Report Type Value = NOON for Noon Report			String	4
reportDateLocal	Report Date Local Time		Yes	Date
latitude	Position Latitude (Decimal Degrees)			Double	5
longitude	Position Longitude (Decimal Degress)			Double	5
eta	Estimated Time of Arrival	Updates ETA in Schedule.	Yes	Date
eventLogs	Array of EventLog Add Departure Time as an Event Log with "DEP" event code, Add Berthed Time as an Event Log with "BRT" event code	Updates ETD and ETB in Schedule		Date
trueCourse	True Course			Integer	38
distanceSailed	Distance Sailed Since Last Report			Double
hoursInService	Hours in Service Since Last Report			Double
distanceToNextPort	Distance To Go			Double
speedMadeGood	Speed Made Good			Double
windDirection	Wind Direction (924581992)			Integer	38
averageWindForce	Wind Force. Beaufort.			Integer	38
seaDirection	Sea Direction (924581992)			Integer	38
averageSeaState	Sea State. Integer from 0 - 9.			Integer	38
bhpMainEngineIndicatedRpm	Main Engine RPM Since Last Report			Double
dailyFo	Daily Fuel Oil Consumption			Double
dailyDo	Daily Diesel Oil Consumption			Double
dailyFl	Daily Fuel Oil Low Sulphur Consumption			Double
dailyDl	Daily Diesel Oil Low Sulphur Consumption			Double
dailyFw	Daily Net Fresh Water Consumption			Double
robFo	Fuel Oil Remaining on Board (FO RoB)	Updates FO arrival RoB of the Port Call		Double
robDo	Diesel Oil Remaining on Board (DO RoB)	Updates DO arrival RoB of the Port Call		Double
robFl	Fuel Oil Low Sulphur Remaining on Board (FO LS RoB)	Updates FO LS arrival RoB of the Port Call		Double
robDl	Diesel Oil Low Sulphur Remaining on Board (DO LS RoB)	Updates DO LS arrival RoB of the Port Call		Double
robFw	Fresh Water Remaining on Board			Double
genericRemark???	Remark	Not handled via API how ???		String	Unlimited

Arrival report

JSON Field Name	Description	Affects Dataloy VMS	Mandatory	Type	Length
portCall	A port call id		Yes?	Integer
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
reportDateLocal	Report Date Local Time		Yes	Date
eta	Time of Arrival	Updates ETA in Schedule	Yes	Date
eventLogs	Array of EventLog Add Departure Time as an Event Log with "DEP" event code, Add Berthed Time as an Event Log with "BRT" event code	Updates ETB and/or ETD in Schedule	Yes	Array of EventLogs
distanceSailedSinceDeparture	Total Distance Sailed Since Departure	Updates Miles in Schedule.		Double
distanceSailed	Distance Sailed Since Last Report			Double
hoursStoppages	Hours Stoppages	Updates Days Stoppages (see the Perfomance tab in Booking and Operations).		Double
hoursInService	Hours in Service			Double
speedMadeGood	Speed Made Good Since Last Report			Double
draftAft	Draft Aft			Double
draftForward	Draft Forward			Double
dailyFo	Daily Fuel Oil Consumption			Double
dailyDo	Daily Diesel Oil Consumption			Double
dailyFl	Daily Fuel Oil Low Sulphur Consumption			Double
dailyDl	Daily Diesel Oil Low Sulphur Consumption			Double
dailyFw	Daily Net Fresh Water consumption			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			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
portCall	A port call id		Yes	Integer
reportTypeCode	Vessel Report Type Value = PORT for In Port Report.	Used to insert the correct type of Position Report and to locate the correct port call.	Yes	String	4
reportDateLocal	Report Date Local Time		Yes	Date
eventLogs	Array of EventLog Add Estimated Departure Time as an Event Log with "DEP" event code, Add Estimated Berthed Time as an Event Log with "BRT" event code	Updates ETB and/or ETD in Schedule		Date
hoursInService	Hours in Service			Double
weather	Weather. 924581992			Integer	38
windDirection	Wind Direction. 924581992			Integer	38
averageWindForce	Average Wind Force. Beaufort.			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
portCall	A port call id
reportTypeCode	Vessel Report Type. Value = DEP for Departure Report.		Yes	String	4
reportDateLocal	Report Date Local Time		Yes	Date
eventLogs	Array of EventLog Add Departure Time as an Event Log with "DEP" event code	Updates Estimated Time of Departure (ETD) in Schedule.	Yes	Date
eta	Estimated Time of Arrival	Updates Estimate Time of Arrival (ETA) for next Arrival Port.		Date
distanceToNextPort	Distance To Next Port			Double
draftAft	Draft Aft			Double
draftForward	Draft Forward			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			Double
foBunkered???	Bunkered Fuel Oil Input Exact Figure According to BDR	Updates Fuel Oil bunkered for departure port call.		Double
flBunkered	Bunkered Fuel Oil Low Sulphur Input exact figure according to the BDR	Updates Fuel Oil Low Sulphur bunkered for departure port call.		Double
doBunkered	Bunkered Diesel Oil Input exact figure according to the BDR	Updates Diesel Oil bunkered for departure port call.		Double
dlBunkered????	Bunkered Diesel Oil Low Sulphur Input exact figure according to the BDR	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

{
	"reportTypeCode":"ARR",
	"portCall":{"key": 1009999},
	"reportDateLocal":"2013-12-24T00:00:00",
	"eventLogs": [{"eventLogDate":"2013-12-24T00:00:00", "event":{"ARR"}}, 
			{"eventLogDate":"2013-12-24T00:00:00", "event":{"BRT"}}, {"eventLogDate":"2013-12-24T00:00:00", "event":{"DEP"}}],
	"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

 {
	"reportTypeCode":"DEP",
	"portCall":{"key": 1009999},
	"reportDateLocal":"2013-12-24T00:00:00",
	"eventLogs": [{"eventLogDate":"2013-12-24T00:00:00", "event":{"DEP"}}, {"eventLogDate":"2013-12-24T00:00:00", "event":{"ARR"}}],
	"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

{
	"reportTypeCode":"NOON",
	"portCall":{"key": 1009999},
	"latitude":10.17,
	"longitude":10.17,
	"reportDateLocal":"2013-12-24T00:00:00",
	"eventLogs": [{"eventLogDate":"2013-12-24T00:00:00", "eventCode":{"ARR"}}, 
			{"eventLogDate":"2013-12-24T00:00:00", "event":{"BRT"}}, {"eventLogDate":"2013-12-24T00:00:00", "event":{"DEP"}}],
	"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

{
	"reportTypeCode":"PORT",
	"portCall":{"key": 1009999},
	"reportDateLocal":"2013-12-24T00:00:00",
	"eventLogs": [{"eventLogDate":"2013-12-24T00:00:00", "event":{"BRT"}}, {"eventLogDate":"2013-12-24T00:00:00", "event":{"DEP"}}],
	"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 Event Code

Dataloy Events can be found by using the Event Resource.

Dataloy Port ID

Dataloy Port ID's can be found be using the Port Resource.

924581992 Back