Function description of the API

Introduction

This document describes the RESTful API for integration between Trainingportal and the course provider's booking system.

The course provider must implement support for the three different parts of the integration:

1. The course provider must use Trainingportal's methods for maintaining the course offering.
2. The course provider must provide simple URLs for bookings/cancellations. These URLs must be sent to the Trainingportal support team.
3. The course provider must use Trainingportal's methods for updating booking statuses.

The three different parts of the integration is desribed below.

For a technical description of the API, read this article.

Terminology

Trainingportal uses the following nouns in the integration

• A courseclass is the time and date specific implementation of a course. An example of a courseclass will be "Basic Safety Training, week 40 in Oslo".
• A course is the object grouping different courseclasses with the same curriculum. An example of a course will be "Basic Safety Training".
• A booking is the act of creating an enrollment for a student to a courseclass in the courseprovider's booking system

Maintenance of the course provider's course offering

The first part of an integration is making sure the course provider's catalogue is synchronized with Trainingportal. For this purpose, Trainingportal offers the following methods:

• getCourses - will return the courses in Trainingportal the course provider is registered as course provider for.
• getCourseClasses - will return the course classes in Trainingportal the course provider has created for a course.
• addClass / updateClass- will be used to add new class or update existing class. Will also be used to update the number of free seats on a class.
• cancelClass - will be used to delete a class
• restoreClass - will be used to restore a previously cancelled class (not yet deleted in the system)

In a normal usage scenario, the course provider will only have to use the three methods addClass/updateClass/cancelClass:

• addClass is called whenever a new class is created in the course provider's booking system
• cancelClass is called whenever a class is cancelled in the course provider's booking system
• updateClass is called whenever a class is changed in the course provider's booking system. This includes the number of available seats in the course class
  
  

Course bookings and cancellations

The second part of an integration handles course bookings and cancellations. From a user perspective, we want these processes to be synchronous processes, so these can't be implemented only with Trainingportal being the provider of methods.

Booking process

In order to make the calls to the course provider's system as small and uniform as possible, we will split the booking process into a two-step process:

1. Reservation of a seat in the course classTrainingportal "reserves" a seat in a class by doing a simple GET to the coures provider's system. The course provider must make available a URL for reserving a seat in their booking system. Trainingportal must pass the courseClass external ID as a parameter, and may pass the following parameters:
   
   • studentFirstName - first name of the student
   • studentLastName - last name of the student
   • studentEmailAddress - email address of the student
   • studentPhoneNumber - phone number of the student
   • studentBirthDate - birth date of the student
   • enrollerFirstName - first name of the enroller
   • enrollerLastName - last name of the enroller
   • enrollerEmailAddress - email address of the enroller
   • enrollerPhoneNumber - phone number of the enroller
   • company - name of the company paying for the enrollment
   
   The URL must return either XML or JSON with the following properties:
   
   • successful: true/false
   • bookingReference: a unique reference for the booking in the course provider's booking system
   • errorMesssage: In case of error, a human readable error message
   
   
   The URL may be protected by an IP filter. Any additional check for the validity of a reservation will be done by completing step 2 in the reservcation process.
   
   

   Example request

   URL	https://www.thebookingsystem.com/reserveSeat?courseClassId=abcd&studentFirstName=John&studentLastName=Doe&company=Mintra

   { "successful":"true", "bookingReference":"1234", "errorMessage":"" }

   
   
   
2. Confirmation of booking, retrievel of additional information
   Upon reservation of a seat in the booking system, the course provider must call our web service to confirm that the booking is valid and to get details about the enrollment. The method "getBookingInformation" must be used, with the booking reference as parameter. The method will return detailed information on the booking, including comments on the enrollment.
   Note: Since the reservation and confirmation methods are two independent operations, there may be situations where there is a small delay between the response is given to step 1 and the booking is available in step 2. The course provider should implement a mechanism for handling this scenario.

Cancellation process

For the cancellation process, a simple GET to a URL on the course provider side with enrollmentReference as part of URL is sufficient. The URL must return either XML or JSON with the following properties:

• cancelled: true/false
• errorMesssage: In case of error, a human readable error message

The URL may be protected by an IP filter.

Example request

Updating booking/enrollment status

The last part of the integration handles the status for bookings made in the course provider's system. It is the course provider's responsibility to update a booking with the appropriate completion status. For this purpase, Trainingportal will offer the following methods:

• UpdateBookingStatus. Will be used to update the status of the booking. Status can e.g. be "NO_SHOW" or "COMPLETED". In case of status "COMPLETED", a completion date must also be sent
• UploadDocumentation. Will be used to upload documentation related to the booking. Documentation will be course certificate or other documents.

In a normal usage scenario, the course provider will use these methods when a student has completed a course in the course provider's booking system. In such an event, the course provider will update the booking with status "COMPLETED" and a completion date, and upload a course certificate with the "uploadDocumentation" method.