| Live Search | ||||||||
|---|---|---|---|---|---|---|---|---|
|
This guide has been produced for the purpose of providing information on how you can utilise the accessplanit course XML in order to integrate your Course Management System into a website.
Why Integrate?
The two main reasons that organisations choose to integrate Course Manager into their website are:
- To be able to show up to date course availability on their website such as which courses are running on what dates, what locations those courses are being run at, and if there are still places left.
- To allow people to directly book course places online and pay there and then (if applicable). This means you can be taking bookings 24 hours a day, 7 days a week.
Why XML?
There is a simpler methodology for integrating accessplanit into your website, which is via a simple plugin table which we recommend you consider first. However, there are benefits to using the full which XML which are:
- Your web developer will have complete freedom about how they choose to display the information on your website, which opens up unlimited design opportunities.
- There are more fields you can pull from the XML than within the Plugin Table, so you can integrate more data.
Caveats to use of the XML Feeds
- You will need to have the expertise in-house, or be willing to employ an external web developer capable to interpreting the XML feed and performing the actual integration work. This can be time consuming, and if you outsource this work you’ll need to factor in the associated costs.
- If you run sessional courses and want to show the child sessions linked to the head course on your website then this is very difficult to achieve using the XML.
What is available in the XML?
We offer three XML feeds which all return slightly different data sets. A brief description of what is within each feed is shown within the screenshot below:
To access these feeds, use the following URL, replacing 'coursemanagerdemo' with your system's config:
http://coursemanagerdemo.accessplanit.com/accessplan/services/WebIntegration.asmx
It should be noted that all data contained within the GetCourses feed is also contained within the GetCoursesPackage and GetCoursesPackageWithCourseDateText feeds. Likewise, all the data contained within the GetCoursesPackage feed is contained with the GetCoursesPackageWithCourseDateText feed.
Which courses won't show in the feeds?
There are a few reasons why a course might not show in the XML feed:
- Exclusivity - By default, if a course template or date is exclusive to a certain account or account group, this won't show in the XML feeds. There is a setting that accessplanit can change to allow exclusive course to show, please get in contact with the Helpdesk team if you would like this changed.
- Advertising - If both the course template and course date have the "Advertise" field ticked, and the current date is within the "Advertise Start/End Dates" date range, then the course will show in the feed.
- Dates - By default, only future courses will show, however there is a setting that accessplanit can change to allow courses for a certain number of days in the past to appear in the feed. Please get in contact with the Helpdesk team if you would like this changed.
What data is returned within each feed?
Listed below are all the fields which are contained within each of the three feeds with a description of what each of these fields relates to with the accessplanit system. They are as follows:
All three feeds
Course ID: This pertains to the course template ID in Course Manager. If system generated it will be a series of alphanumeric characters or the client can provide their own Course IDs if they prefer – up to 10 characters in length, with no special characters allowed.
Label: This is the course title. It can be any length.
Text1: This corresponds to an area within Course Manager where users can input “Objectives”. This is input within a full HTML editor and the feed will provide the full HTML input within this text field. Website developers would typically ignore everything apart from the text as they would wish to apply their own fonts and formatting.
Text2: As per above, but instead refers to the course “Aims” area.
Text3: As per above, but instead refers to the course “Summary” area.
Cost: The course fee – this will always be a number.
Cost Type: There are five options here depending on how the training business charges for their courses. This would either say “candidate”, “hour”, “session”, “day” or “candidateday”. In the vast majority of cases where public courses are being run the cost type is per “candidate”.
Type: Course Manager supports different types of courses – the six options that could be listed here are “Unknown”, “Class”, “E Learning”, “Module”, “Audio Video”, “Documents” or “Web”. In the majority of cases only class, e learning or web are utilised in the system.
Duration: This is the course length – this will always be a number.
Duration Type: This gives meaning to the number above – e.g. is the course one minute, one hour or one day. Note that a number will be produced, so you will need to use the following key to decode this:
- The number 2 denotes “minutes”
- The number 1 denotes “hours”
- The number 0 denotes “days”
Currency: This will be a three letter reference such as “GBP” which is used to denote which currency this course is being charged in. The three letter references we use comply with the ISO 4217 currency standards. This is used for scenarios whereby the Training Provider may charge clients in different currencies. This would usually be the case if they operate out of multiple countries.
CurrencySymbol: This will be the currency symbol associated with the currency given above. For example, GBP would have the associated symbol of “£”.
CategoryIDs: This will be one or more numbers which directly relates to what Category or Categories (if more than one) this course belongs. During the setup of the system Category IDs can either be imported or the system will create its own Category IDs when the Categories are created.
GetCourses feed only
WICategory: This contains the Category ID and Label of a category that the course relates to. One course may have multiple WICategory sections.
ImageURL: This is the image that is stored against the Course Template in accessplanit.
GetCoursesPackage and GetCoursesPackageWithCourseDateText feed only
CourseDateID: This is the ID number which is unique to this individual occurrence of this course. These IDs are system generated.
CourseID: This is the Course Template ID provided again. Remember that this is the ID for the Course Template, not for this specific occurrence of the course.
StartDate: This is the start date and time of this occurrence of the course and is provided in the format YYYY-MM-DDT09:00:00. The “T” separates the date and time. A 24 clock time format is presented.
EndDate: As per above, this denotes the end date and end time of the course (data provided in format above).
VenueIDs: This displays one or more Venue IDs which pertain to where this occurrence of the course is taking place. Venue IDs can either be imported at system setup or can be automatically generated by the system as Venues are created. As a web developer you have the option of either using a mapped table of Venue IDs to Venues, but it’s simpler to just use the Venue details which are also parsed in the feed.
TrainerIDs: This displays one or more Trainer IDs which pertain to who is teaching the course. Trainer IDs can either be imported at system setup or can be automatically generated by the system. The feed also includes their forename and surname so the ID would not usually be utilised by a web developer.
SpacesAvailable: This displays the number of available spaces left on the course. Most commercial Training Providers do not display the actual number of spaces left, but the ability to do so is there.
MaxPlaces: This displays the total number of spaces on the course date before bookings are made. This allows you to create availability warnings based on the size of the course.
Status: This will display the course status and will contain one of the following statuses: “Available”, “Cancelled”, “Completed”, “InProgress”, “OnHold”, “FullyBooked” “Unknown” or “Provisional”.
BookNowURL: This is the crucial and unique Booking URL which relates only to this occurrence of the course and so is a unique URL. The URL contained will launch the accessplanit Course Booker/Shopping Basket. See below - “implementing online booking” for more information on this. The Booking Link will only be returned from the XML feed if the Course's Status is in Available or Fully Booked. If the course is in any other status, it will not pull through to the website.
EnquireURL: This is a unique URL for this occurrence of the course which can be used to direct prospective customers to a form they can fill in to express an interest in a course (rather than making a firm booking). From a web developer's perspective, you may choose to have this URL open in a pop-up page once the link is clicked.
Cost: This is the cost for this one off occurrence of the course. It could be different from the usual course cost gained from the GetCourses XML.
Private: This will either be “true” or “false”. Most organisations would choose to NOT display any “true” courses on the website as this denotes courses that are private, and not open to the general public.
Currency: As mentioned earlier this will be a three letter reference such as “GBP” which is used to denote which currency this course is being charged in. This could be different to the currency passed in the GetCourses XML as the system does support multiple currencies – so this would display the currency that this occurrence of the course is being charged in.
CurrencySymbol: This will be the currency symbol associated with the currency given above. For example GBP would have the associated symbol of “£”.
TrainingPoints: Displays the number of training/CPD Points stored for a Course Template
ExternalID: Displays the external ID of the Course Template and the Course Date separately.
PublishDate: Displays the publish date stored for a Course Template.
DeliveryMethodID: Displays the ID of the delivery method.
Sessional: This displays true or false to indicate if the course is sessional or not.
VenueID: This displays the Venue ID which pertains to where this occurrence of the course is taking place. If more than one Venue is being used then the next ID will be listed below in the feed. Venue IDs can either be imported at system setup or can be automatically generated by the system as Venues are created. As a web developer you have the option of either using a mapped table of Venue IDs to Venues but it’s simpler to just use the Venue details below.
Label: This is the Venue label – it’s a free text field which supports up to 80 characters.
Address: This is the building name/number and street part of the Venue address.
Town: This is the town the Venue is within.
County: This is the county the Venue is within.
Country: This is the country the Venue is within.
Postcode: This is the Venue postcode.
Longitude: This is the approximate longitude based on the postcode supplied of the Venue.
Latitude: This is the approximate latitude based on the postcode supplied of the Venue.
TrainerID: This displays the Trainer ID which pertains to who is teaching the course. If more than one Trainer is teaching then the next ID will be listed below in the feed. Trainer IDs can either be imported at system setup or can be automatically generated by the system. The feed also includes their forename and surname so the ID would not usually be utilised by a web developer.
Forenames: This is the Trainer's forename.
Surname: This is the Trainer's surname..
Category ID: This displays the Category ID. The feed also includes the Category label which would not usually be utilised by a web developer.
Label: This displays the label of the Category.
GetCoursesPackageWithCourseDateText feed only
AdditionalInformation: This pulls information from a HTML editor which is stored against that particular Course Date and is used to store extra details which only pertain to that specific occurrence of a course.
JoiningInstructions: As above, this pulls information from a HTML editor which is stored against that particular Course Date and is used to store extra joining instruction information which only pertains to that specific occurrence of a course.
| Info |
|---|
The URLs that need access the feed must be whitelisted by accessplanit. These are typically provided by the customer ahead of the website development, but if you have trouble loading courses this may be the cause. |
What parameters can be used to filter the XML feeds?
GetCourses
The minimum information that needs to be provided in order to return course data is a CompanyID. This will be the accessplanit ID for the Training Provider who is providing the courses. Note that if a company has multiple Training Providers (such as where they operate in multiple countries) then you would need to ensure that the correct Company ID is used when requesting the data.
There are then two further options to filter down the data – this can either be done by including a query on a particular course Category (via the Category ID), or by choosing a particular course (via the Course ID).
GetCoursePackage
The minimum information that needs to be provided in order to return course data is a CompanyID. This will be the accessplanit ID for the Training Provider who is providing the courses. Note that if a company has multiple Training Providers (such as where they operate in multiple countries) then you would need to ensure that the correct Company ID is used when requesting the data.
There are then three further options to filter down the data – this can either be done by including a query on a particular course Category (via the Category ID), by choosing a particular course (via the Course ID), or by choosing a particular Venue (via the Venue ID). This last option is useful where a customer has a website which lists courses by Venue.
GetCoursesPackageWithCourseDateText
As per the GetCoursesPackage, the minimum information that needs to be provided in order to return course data is a CompanyID. This will be the accessplanit ID for the Training Provider who is providing the courses. Note that if a company has multiple Training Providers (such as where they operate in multiple countries) then you would need to ensure that the correct Company ID is used when requesting the data.
There are then three further options to filter down the data – this can either be done by including a query on a particular course Category (via the Category ID) or by choosing a particular course (via the Course ID) or by choosing a particular Venue (via the Venue ID).
How to filter the XML feeds
In the previous section, the screenshots were from an information web page which all customers have access to. Each customer will have a standard system URL which takes the form customername.accessplanit.com.
An example URL for the Web Integration information page is below:
http://coursemanagerdemo.accessplanit.com/accessplan/services/WebIntegration.asmx
As per the screenshot above, by selecting either the GetCourses, GetCoursesPackage or GetCoursesPackageWithCourseDateText you will then be able to query the date, applying whichever filters are applicable.
However! – when using the XML feeds in practice the filtering options can be applied by altering the URL of the request.
For the GetCourses feed, the URL below will provide all course information.
The bold text is where relevant filtering IDs are placed. If this is OPTIONAL, then the field still needs to be in the request URL, but there doesn't need to be a value after the equals sign. If this is MANDATORY, then there must be a value (in this case, the ID of the system's training provider) for that field in the request itself.
Multiple Category IDs or multiple Course IDs can be supplied by separating them by a pipe (e.g. 87|88|89).
For the GetCoursesPackage and GetCoursesPackageWithCourseDateText the URLS below will provide all course and course date information:
Implementing Online Booking
Once you have chosen what course information to display on the website the next step in most cases is to choose how to implement the ability for people to book (and pay, if applicable) for courses.
The only piece of data required from within the XML feed to allow online booking is the BookNowURL which is within the GetCoursesPackage and GetCoursesPackageWithCourseDateText feeds.
This URL can simply be embedded behind a “book now” piece of text or image and will launch the accessplanit Shopping Basket. The URL will look like this as below. You'll need to change the bolded text to the relevant information for your system:
The Shopping Basket looks like this when launched:
From here, the person booking the course will simply follow the onscreen instructions to complete their booking.
Our recommendation is that the “book now URL” opens in a separate blank browser window. You are able to brand your Shopping Basket to match your website look and feel.
If your "Continue Shopping" button is not visible, please contact the Helpdesk team.
Example XML Data
Included below are two examples of the actual XML returned from a test system – one for the GetCourses feed and one for the GetCoursesPackage feed:
Example of GetCourses XML
Filtered to provide details on just one course
<ArrayOfWICourse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="AccessPlanIT.Accessplan.Web.Services">
<WICourse>
<CourseID>ADVANCVHiA</CourseID>
<Label>Advanced Excel</Label>
<Text1>Objectives Text Box</Text1>
<Text2>
<br><span class="Apple-style-span" style="font-family: Verdana, Arial, Helvetica, sans-serif; ">At the end of this course, as well as consolidating your understanding of Excel's fundamentals, you will be able to perform the most complex calculations and functions, manipulate data using pivot tables and advanced analysis, record macros and integrate with other office applications. Your level of proficiency should enable you to confidently take up our VBA course for Excel.</span><br>
</Text2>
<Text3>Summary Text Box</Text3>
<Cost>55</Cost>
<CostType>Candidate</CostType>
<Type>Class</Type>
<Duration>20.00</Duration>
<DurationType>2</DurationType>
<Currency>GBP</Currency>
<CurrencySymbol>£</CurrencySymbol>
<PublishDate/>
<TrainingPoints/>
<ExternalID>IS4009</ExternalID>
<DeliveryMethodID>2</DeliveryMethodID>
<ImageURL/>
<Categories>
<WICategory>
<CategoryID>164</CategoryID>
<Label>CourseCat1</Label>
</WICategory>
<WICategory>
<CategoryID>169</CategoryID>
<Label>CourseCat2</Label>
</WICategory>
</Categories>
</WICourse>
</ArrayOfWICourse>
Example of GetCoursesPackage XML
Filtered to provide details on just one course
<WICoursesPackage xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="AccessPlanIT.Accessplan.Web.Services">
<Courses>
<WICourse>
<CourseID>ADVANCVHiA</CourseID>
<Label>Advanced Excel</Label>
<Text1>Objectives Text Box</Text1>
<Text2>
<br><span class="Apple-style-span" style="font-family: Verdana, Arial, Helvetica, sans-serif; ">At the end of this course, as well as consolidating your understanding of Excel's fundamentals, you will be able to perform the most complex calculations and functions, manipulate data using pivot tables and advanced analysis, record macros and integrate with other office applications. Your level of proficiency should enable you to confidently take up our VBA course for Excel.</span><br>
</Text2>
<Text3>Summary Text Box</Text3>
<Cost>55</Cost>
<CostType>Candidate</CostType>
<Type>Class</Type>
<Duration>20.00</Duration>
<DurationType>2</DurationType>
<Currency>GBP</Currency>
<CurrencySymbol>£</CurrencySymbol>
<CategoryIDs>34</CategoryIDs>
</WICourse>
</Courses>
<Dates>
<WICourseDate>
<CourseDateID>12328</CourseDateID>
<CourseID>ADVANCVHiA</CourseID>
<StartDate>2014-12-10T09:00:00</StartDate>
<EndDate>2014-12-10T15:00:00</EndDate>
<VenueIDs>
<string>TRAINI04Y6</string>
</VenueIDs>
<TrainerIDs>
<string>clalle3</string>
</TrainerIDs>
<SpacesAvailable>10</SpacesAvailable>
<Status>Available</Status>
<BookNowURL>
</BookNowURL>
<EnquireURL>
</EnquireURL>
<Cost>55</Cost>
<Private>false</Private>
<Currency>GBP</Currency>
<CurrencySymbol>£</CurrencySymbol>
</WICourseDate>
</Dates>
<Venues>
<WIVenue>
<VenueID>TRAINI04Y6</VenueID>
<Label>Training Room 1</Label>
<Address>12 Spring Garden Street</Address>
<Town>Lancaster</Town>
<County>Lancashire</County>
<Country>United Kingdom</Country>
<Postcode>LA1 1RQ</Postcode>
<Longitude>-2.800413</Longitude>
<Latitude>54.046914</Latitude>
</WIVenue>
</Venues>
<Trainers>
<WITrainer>
<TrainerID>clalle3</TrainerID>
<Forenames>Clayton</Forenames>
<Surname>Allen</Surname>
</WITrainer>
</Trainers>
</WICoursesPackage>
Cookies
The accessplanit system uses cookies to store the content of Users' Shopping Baskets, so that the information is remembered as they navigate around your website and through the basket.
Once a customer clicks to add a course to their basket, we will store a cookie recording this.
If you do not yet have a cookie policy available on your website, we encourage adding one to inform your customers that cookies will be recorded.