Organisation API

The Organisation API is a series of web services designed to move large quantities of user content from external systems to itslearning. The most common use for the API is to “migrate” user data such as files, and course specific data such as IMS Packages, tests, links, assignments from a legacy platform to itslearning.

For the bulk of content this is a one-way migration - once the data is migrated to itslearning it cannot be accessed or amended through the API.

However, for some applications, including timetable, assessment and archival systems, the same API can be used to read from and/or update the data in itslearning; synchronising it over time and keeping it up to date.

Obtaining access to the Organisation API

Common

Access to the organisation API is through the Local and Global Services Team. They work with partners to provide access.

Please see http://www.itslearning.eu/ for the latest contact information.

  1. Agree which methods (organisation services) are required. Some partners may only want, for example, to migrate user files. Access to the organisation API can be filtered on a message by message level.

  2. The services team member completes an authorisation form for access to be set-up.

  3. The services team member provides back to the partner their unique username and password for WS-Security.

  4. Organisation partner now is able to access specified services in organisation toolkit based on provided credentials.

  5. At any time the partner can use the get message types service to retrieve the set of methods/message types they have access to.

Access to specific Site

  1. Agree which itslearning sites the partner needs access to. The Organisation API is scoped to the specific site access only.

  2. Each couple of username and password is unique for the each partner and the site it's accessing. If a partner has access to two sites, they will have two sets of username and password.

Access to all sites

  1. Access is granted for all sites. Sites administrators can allow or disallow access for partner.

  2. Partner can have only one site access (user + password pair) with permissions to all sites.

  3. For each method Organisation API client should provide SiteId parameter, which define site where action will be executed. Note: partner should be allowed on defined Site (SiteId).

Service overview

The Organisation supports both synchronous and asynchronous processing of messages. Many of the message types are asynchronous - processed in the order they arrive, but not necessarily instantly. The use of an asynchronous job processor allows us to handle multiple migrations without the need for scheduling. The organisation system is nominally open for business 24/7, other than planned outages. The main elements of organisation toolkit are:

  1. organisation services – WCF services exposing main functionality, does schema and security validation.

  2. organisation processor – Windows service which process messages added by partners, validates message content values, and creates content elements within itslearning system.

  3. Itslearning UI administration section – allows setting security access and browsing messages and logs.'

images/download/attachments/3801600/contentimport.png

Web services in the API

DataService.svc

The main service with which to interact with itslearning. It contains four different methods:

  1. AddMessage with which you can add messages to the message queue of the Organisation API. All asynchronous messages are handled through this method.

  2. GetMessageTypes which returns all the message types that are available to you.

  3. GetMessageResult which can be used to determine the status of a message previously added to the queue using the AddMessage method.

  4. GetExtensions which returns a list of all extensions supported by the Organisation API.

ReadDataService.svc

All Read messages are processed synchronously in the ReadDataService service.

While almost all Create, Update and Delete messages are processed asynchronously through AddMessage method of the DataService service, this is not convenient for Read messages, which are used to read data from itslearning in real-time.

FileService.svc

This service allows uploading single file into content import temporary storage area. It returns unique identifier which can be used within AddMessage service to refer to the uploaded file for further processing.

Service URLs / WSDLs:

Production USIT:

https://migra.itslearning.com/ContentImport/FileService.svc?wsdl
https://migra.itslearning.com/ContentImport/DataService.svc?wsdl
https://migra.itslearning.com/ContentImport/ReadDataService.svc?wsdl

Production Amazon US1:

https://us1migra.itslearning.com/FileService.svc?wsdl
https://us1migra.itslearning.com/DataService.svc?wsdl
https://us1migra.itslearning.com/ReadDataService.svc?wsdl

Production Amazon EU1:

https://eu1migra.itslearning.com/FileService.svc?wsdl
https://eu1migra.itslearning.com/DataService.svc?wsdl
https://eu1migra.itslearning.com/ReadDataService.svc?wsdl


Customer test environment:

Access to this environment requires the assistance of an itslearning consultant. Contact your local itslearning office for details.

https://migra.itsltest.com/FileService.svc?wsdl
https://migra.itsltest.com/DataService.svc?wsdl
https://migra.itsltest.com/ReadDataService.svc?wsdl


Others:

Other environments are available to internal stakeholders and strategic partners upon request.

Credentials:

Credentials for the services will be provided to you by an itslearning representative.

Message types and validation

The type of message defines the content of the message, how to validate message content and values as well as what action processor will perform when receives that message type.

The GetMessageTypes method of the DataService service returns all the message types currently available to you, based on you the level of access you have to a given site.

The result from this method contains an identifier, name, xsd schema and processing type for all message types.

Common validation rules

Every message uses some common logic both for processing and validating.

User

  1. User must exist.

  2. User must not be external. Check the flag (external_user_id and external_customer_id for user created AICC).

  3. User must not be deleted.

  4. User does not need to belong to a course referenced by a message

SiteId

  1. SiteId should be specified to perform the action.

  2. Your security settings don't allow you to perform that operation. Please contact administration to grant you an access.

  3. SiteId='[SiteId]' is not valid.

  4. Your security settings don't allow you to perform that operation. SiteId can't be specified because you have an access to specific site.

  5. Your security settings don't allow you to perform that operation. Please contact administration to grant you an access to site with SiteId='[SiteId]'.

VendorId

  1. Vendor with specified VendorId is not a content vendor.

  2. Vendor with specified VendorId does not exist.

Change and release history

Doc version

Release

Date

By

Changes

0.5

36

09.01.2012

Krzysztof Kordyga

Initial version

0.6

36

13.02.2012

Jan Willem Buiten

Added Create.Folder.Element section

0.7

36

24.02.2012

Simon Riley

Added Create.MyFiles.File section

0.8

36

12.03.2012

Yaroslav Kulik

Added Create.Course.Planner section

0.9

36

13.03.2012

Simon Riley

Added Create.Course.File section

0.10

36

16.03.2012

Jasraj Atwal

Added Create.Course.Test section

0.11

36

22.03.2012

Jan Willem Buiten

Added Create.Course.IMSPackage section

0.12

37

20.04.2012

Martha Solsvik

Added endpoint to services

0.13

37

10.05.2012

Yaroslav Kulik

Added section about duplicated sync keys for messages, read message types, ReadCalendarEvent method. Added Create.Calendar.Event, Update.Calendar.Event, Delete.Calendar.Event and Read.Calendar.Event

0.14

37

28.05.2012

Jasraj Atwal

Added Create.Resource section

0.15

37

01.06.2012

Simon Riley

Adder Create.Dashboard.LinkBlock section

0.16

40

05.11.2012

Malgorzata Strzepek

Changing name from migration toolkit to organisation toolkit

0.17

40

07.11.2012

Mikael Karlsson

Added Read.WarningLetter, Update.WarningLetter

0.18

40

07.12.2012

Luuk Weltevreden

Added Read.Terms

0.19

40

9.12.2012

Piotr Jagielski

Added Read.Course.Files

0.20

40

10.12.2012

Martha Solsvik

Added Read.Course.Gradebook.Categories

0.21

40

12.12.2012

Jasraj Atwal

Added Read.AssessmentScales

0.22

40

13.12.2012

Simon Riley

Added Read.Course.Elements

0.23

40

20.12.2012

Luuk Weltevreden

Added Read.Course.Planner.Lessons

0.24

40

21.12.2012

Luuk Weltevreden

Added Read.Course.Gradebook.Assessments

0.25

40

26.12.2012

Irina Zabotlina

Added support score as assessment alternative for Create.Course.Element.Assignment and Create.Course.Element.Test

0.26

40

13.02.2012

Anders Mydland

Moved the individual methods to subpages, as the large monolithic document caused rendering problems in IE and Chrome. Also renamed "Toolkit" to "API".

0.27

40

15.02.2012

Anders Mydland

Added URLs to WSDLs

0.28

43

01.07.2013

Pavel Shastov

Added Read.AssessmentRecord.Summary

0.29

43

10.07.2013

Pavel Shastov

Updated Read.Course.Elements. (added additional information about learning objectives assigned to elements)

0.30

43

11.07.2013

Pavel Shastov

Added Read.Course.Element

0.31

43

15.07.2013

Maxim Tkachenko

Added Read.LearningObjectives

0.32

43

19.07.2013

Maxim Tkachenko

Added Update.Course.Element.CustomActivity

0.33

43

03.08.2013

Pavel Shastov

Added Update.Course.Element

0.34

43

07.08.2013

Andrey Chaykin

Added Update.Course.Element.LearningObjective.Assessment

0.35

44

02.04.2014

Amund Trovåg

Modified URLs to test environment after domain name change

0.36

49

28.08.2015

Ivar Brådland

Updated URLs for USIT and Amazon