Appointment API

Short Description

The objective of appointment integration is to automate the creation and flow of port call appointments between the Dataloy VMS and an agency system. When the appointment has been created and handled in the agency system, a Disbursement Account (DA) is transferred back to the Dataloy VMS.

Chapter Contents:

[ 1 Appointment Integration Transactions ] [ 2 Appointing a Port Call ] [ 3 Updating a Port Call ] [ 4 Cancelling a Port Call ] [ 5 Properties ] [ 6 ] [ 7 Business Partners ] [ 8 Additional Information ]

Long Description

Appointment Integration Transactions

Transactions from Dataloy VMS to Agency System Follow Two Steps:

Port Call data is ready to be transferred from Dataloy VMS to agency system as soon as port call status changes to Sent or Updated
Appointment API allows applicable agency system to collect data such as Agent, Cargo etc. information from Dataloy VMS (data usually required by the agency system).

Transactions from Agency System to Dataloy VMS:

Disbursement Accounts (DAs), either as Proforma, Revised or Final, can be transferred from an agency system to Dataloy VMS. The transaction is pushed by applicable agency system into the Dataloy VMS via the Disbursement Account Integration API.

Prerequisites

Before setting up and testing a DA integration the following is required:

Mapping of port cost codes between Dataloy VMS and the agency system (Dataloy VMS: Modules - Master Data - General Master Data Administration - Port Cost Code).
Mapping of handling cost codes between Dataloy VMS and the agency system. (Dataloy VMS: Modules - Master Data - General Master Data Administration - Handling Cost Code).
Mapping of various text codes between Dataloy VMS and the agency system. (Dataloy VMS: Modules - Master Data - General Master Data Administration - Various Text).
Synchronization of business partners between Dataloy VMS and the agency system. (Dataloy VMS: Modules - Master Data - General Master Data Administration - Business Partners).

Appointing a Port Call

Integration Set-Up

Each time a port call is appointed in Dataloy VMS, the port call status is set to Sent. A scheduled task can be used to extract the port calls with status Sent (see Data Transaction, below). Once a port call appointment has been transferred the agency system must then update the status to Appointed in Dataloy VMS.

Data Transaction

To extract all port calls (appointments) that have the status Sent in Dataloy VMS use the blow request in conjunction with the base URL:

Get port calls ready to be sent to an agency system

GET /PortCall?filter=agencyAppointmentStatus.statusTypeCode(EQ)SNT

More information:/PortCall.

Post Transaction

When a port call is successfully transferred to an agency system, the port call status must be updated to Appointed in Dataloy VMS. This is done in a PUT request:

Update status of port call to Appointed for a specific port call

PUT request on /PortCall/{key}
 
{
    "agencyAppointmentStatus": "APP"
}

Updating a Port Call

Integration Set-Up

When a port call is updated by the user in Dataloy VMS, the port call status is set to Update Sent. A scheduled task can then be used to extract port calls that have the status Update Sent (see below under Data Transaction on how to do this). When a port call (appointment) update has been handled by the agency system, the agency system must update the status to Updated Dataloy VMS.

Data Transaction

To extract all port calls (appointments) that have the status Update Sent in Dataloy VMS use the following requests in conjunction with the base URL:

Get port calls that are ready to be updated in the agency system

GET /PortCall?filter=agencyAppointmentStatus.statusTypeCode(EQ)UPSNT

More information:/PortCall.

Post Transaction

When an updated port call has been successfully handled in the agency system, the port call status must be updated to Updated in Dataloy VMS. This is done in a PUT request:

Update status of port call to Updated for a specific port call

PUT request on /PortCall/{key}
 
{
    "agencyAppointmentStatus": "UPD"
}

Cancelling a Port Call

Integration Set-Up

When a port call is cancelled by the user in Dataloy VMS, the port call status is set to Cancellation Sent. A scheduled task can then be used to extract port calls that have the status Cancellation Sent (see below under Data Transaction on how to do this). When a port call (appointment) cancellation has been successfully handled by the agency system, the agency system must update the status to Cancelled in Dataloy VMS.

Data Transaction

To extract all port calls (appointments) with the status Cancellation Sent in Dataloy VMS use the below requests in conjunction with the base URL:

Get port calls that are ready to be cancelled in the agency system

GET /PortCall?filter=agencyAppointmentStatus.statusTypeCode(EQ)CASNT

More information:/PortCall.

Post Transaction

When a cancelled port call has been successfully handled in the agency system, the port call status mus to be updated to Cancelled in Dataloy VMS. This is done in a PUT request:

Update status of port call to Cancelled for a specific port call

PUT request on /PortCall/{key}
 
{
    "agencyAppointmentStatus": "CAN"
}

Properties

The listed properties (but not limited to) can be retireved by first performing a GET request on /PortCall/{key} in conjunction with the base URL. This will return a JSON message containing fields and links to the different resources below. The listed properties have been highlighted as they are of typical interest for an agency system when creating an appointment.

Property	Type	Description	Comments

Property	Type	Description	Comments
portCall	/PortCall	Identifies Port Call	If a disbursement account (DA) is inserted into Dataloy at a later stage, the port call identifier is necessary to identify which port call to insert the DA on.
agent	/BusinessPartner	Agent of the Port Call	Dataloy VMS agent codes are to be retrieved from Dataloy VMS and can be retrieved through the BusinessPartner resource: BusinessPartner?filter=businessPartnerType.businessPartnerType(EQ)A
voyage	/Voyage	The Voyage the Port Call Belongs to
vessel	/Vessel	The Vessel the voyage Belongs to
company	/Company	The Company of Responsible for the Voyage
port	/Port	Port of the Port Call
reasonForCall	/ReasonForCall	Reason for Call
cargos	/Cargo	Cargoes on the Voyage
commodity	/Commodity	Commodity of the Cargo
eventLogs	/EventLog	Information when the Vessel Arrived, Berthed and Departed from the port