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.'




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 Amazon EU1 (European and international customers):

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. Please contact your local itslearning representative for details.

https://migra.itslintegrations.com/FileService.svc
https://migra.itslintegrations.com/ReadDataService.svc
https://migra.itslintegrations.com/DataService.svc

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.


Service versioning


We follow the best practices for versioning for WCF web services from Microsoft, read more about them here https://learn.microsoft.com/en-us/dotnet/framework/wcf/service-versioning

It is expected that API clients implement lax versioning, meaning that clients of the service are designed to handle changes in data contracts in a backwards-compatible manner.

Specifically, when new data members are added to the service, clients that use lax versioning will not encounter exceptions due to these additions.

This approach ensures backward compatibility, allowing older clients to continue functioning seamlessly with the updated service. 

Available messages / methods:

ReadDataService

DataService.svc