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: 

Long Description

Appointment Integration Transactions

Transactions from Dataloy VMS to Agency System Follow Two Steps:

1. 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
2. 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 /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:

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 /PortCall?filter=agencyAppointmentStatus.statusTypeCode(EQ)UPSNT

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:

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

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.

Business Partners

Prerequisites

Synchronization of business partners between Dataloy VMS and the applicable accounting system is required before transferring accounting related transactions. To synchronize business partner updates between systems, decide which system is to be the Master System (where the business partners will be updated). The Master System will then send updated business partner data to the other system.

Integration Set-Up

• Dataloy VMS used as master: Set up a scheduled task and use the request under Data Transaction (below) to gather all business partners data having been modified since the last time a scheduled task was run.
• Dataloy VMS is not used as master: Use the requests under Data Transaction (below) to insert and update the business partners in Dataloy VMS.

Data Transaction

• Dataloy VMS as a master for business partners

1. Extract the business partners whose data has been modified since a selected date from Dataloy VMS using the following request in conjunction with the base URL:

   Get business partner information

   GET /BusinessPartner?filter=modifiedDate(GTE)2014-01-01T12:30:00

2. Set up a scheduled task and gather all voyages that have been modified since the last time a scheduled task was run. 

• Other system as Master for Business Partners

1. Check if relevant business partner/s is/are already existing in Dataloy VMS by using the following request in conjunction with the base URL:

   Get business partner by key

   GET /BusinessPartner?filter=businessPartnerCode(EQ)99999

2. If the business partner is
   1.  already entered in Dataloy VMS. For versions prior to API 3.0:

      1. Update Business Partner:

         Update Business Partner

         PUT /BusinessPartner/{BusinessPartner key}
          
         {
         "businessPartnerName": "Updated Test Name"
         }

      2. Update Address:

         Update Address

         PUT /Address/{Address key}
          
         {
         "address1": "Updated address"
         }

      3. Update Bank:

         Update Bank

         PUT /Bank/{Bank key}
          
         {
         "swiftAddress": "Updated Swift address"
         }

      4. Update Bank Account:

         Update Bank Account

         PUT /BankAccount/{Bank account key}
          
         {
         "bankAccountNo": "UpdatedNumber"
         }

      5. Update Contact Information:

         Update Contact Info

         PUT /ContactInfo/{ContactInfo key}
          
         {
         "email": "updated@emailaddress.com"
         }

      6. Link an existing Bank Account to the Business Partner (new in API version 2.0.0).

         POST /BusinessPartner/{business partner key}/BankAccount/{bank account key}/link

      7. Unlink an existing Bank Account to a Business Partner (new in API version 2.0.0).

         POST /BusinessPartner/{business partner key}/BankAccount/{bank account key}/unlink

   2. already entered in Dataloy VMS. For versions from API 3.0:

      1. PUT the BusinessPartner object:

         put /BusinessPartner
          
         {
             "key":1111111,
         	"businessPartnerName": "Test Name",
             "businessPartnerCode": "123456789",
             "businessPartnerSort": "TESTNAME",
             "companyRegistrationNo": "123456789",  
             "businessPartnerType": "C",
          
             "bankAccounts":[
             {
               "key":222222,
         	  "iban":"9754",
               "bankAccountNo":"6523",
               "bank": 1033615,
               "currency": 400132
             }
             ],
           
             "addresses": [
         	{
         		"key":333333,
         	    "country": "NL",
         	    "address1": "Street Name 54",
         	    "address2": "5th floor",
         	    "address3": "",
         	    "city": "Amsterdam",
         	    "postalCode": "1000 AA"
         	}
             ],
             "contactInfo": [
                 {
                     "key":444444,
         			"email": "test@test.com",
                     "faxNo": "55555555",
                     "mobileNo": "66666666",
                     "phoneNo": "77777777",
                     "telexNo": "88888888"
                 }
             ]
         }

   3. not entered in Dataloy VMS: 

      1. POST the new business partner. Note: Required fields: businessPartnerName, businessPartnerCode, businessPartnerSort.

         Insert a new business partner

         POST /BusinessPartner
          
         {
             "businessPartnerName": "Test Name",
             "businessPartnerCode": "123456789",
             "businessPartnerSort": "TESTNAME",
             "companyRegistrationNo": "123456789",  
             "businessPartnerType": "C",
          
             "bankAccounts":[
             {
               "iban":"9754",
               "bankAccountNo":"6523",
               "bank": {
                 "bankName":"BP bank",
                 "abaNumber":"1111",   
                 "chip":"2222",
                 "swiftAddress":"42341"
                },
               "currency": 400132
             }
             ],
           
             "addresses": [
         	{
         	    "country": "NL",
         	    "address1": "Street Name 54",
         	    "address2": "5th floor",
         	    "address3": "",
         	    "city": "Amsterdam",
         	    "postalCode": "1000 AA"
         	}
             ],
             "contactInfo": [
                 {
                     "email": "test@test.com",
                     "faxNo": "55555555",
                     "mobileNo": "66666666",
                     "phoneNo": "77777777",
                     "telexNo": "88888888"
                 }
             ]
         }

         More Info: /BusinessPartner, /Address, /ContactInfo, /BankAccount, /Bank

Test Data

Create test data for transferring business partners from Dataloy VMS by updating Business Partners in Master Data.

Post Transaction 

No post transaction is required.

Additional Information

Port Call Status List in Dataloy VMS

Webhooks

To gather data from Dataloy, instead to polling, is possible to use Webhooks to get notifications when there are changes. To have more info regarding Webhooks

Top
Back

Related Content