IMS ES Template

IMS ES is a standard framework, it is much more general than most users need. It is also not always clear how to make a change in Itslearning, as IMS ES provides multiple ways to implement certain changes. Therefore an IMS ES Template was created, to be used as wrapper between the much more general IMS ES and the users needs. This template is written in C#, and wraps around IMS-ES, only using the parts that are actually used in Itslearning. The template can be downloaded from Downloads

Structure of the Template

The IMS-ES Template is a C# project, and can be referenced as such. It has two important sections:

Model
Data Access

Model

In the Model section the different objects are given: User, Hierarchy and Course. All three inherit from a singe BaseClass, which mainly holds code for validation purposes. These objects are documented in more detail in this documentation, in their own sections.

Aside from the three objects, there is also a file containing all the enumerations that are used in the template.

Data Access

In the Data Access section the ImsEsClient is implemented. This client handles all interactions between the user and IMS-ES, and through IMS-ES of course Itslearning. This client therefore holds all functions that are described in the sections below, concerning the Users, Hierarchies, Courses and Memberships.

The ImsEsClient has to be set up before use, and is of type IDisposable, so the best way to use it is in a using statement:

using(var client = new ImsEsClient(username, password, server))
{
    // code to be executed
}

When setting up an ImsEsClient, you will need the username and password of IMS-ES in the site that you use, as well as the address of the IMS-ES server. This can be either be a choice of standard servers (production, beta or test), or you can specify your own address, for example "http://localhost/ImsEnterpriseServicesPort.svc". It is also possible to define a Message identifier, this identifier will be sent with the headers of all IMS-ES requests. This will make logging easier if there are multiple parties using IMS-ES on a particular site. An identifier can be set in the following way:

using(var client = new ImsEsClient(username, password, server) { MessageIdentifier = "identifier"})
{
    // code to be executed
}

Almost all of the functions in the ImsEsClient will have a batch variant, for example CreateUser and CreateUsers. The single functiona will return a single OperationResult, with a status (Error, warning or Success), the identifier of the object, and the generated message. The batch function will return a BatchOperationResult, also with a status, a list with error messages and a list with warnings (both of which are OperationResults). These warnings are the warnings that Itslearning encountered during processing the request, and returned through IMS-ES. If instead of a warning an error was generated by Itslearning, the ImsEsClient will generate an ImsEsException (or ImsEsBatchException), with the OperationResult (or BatchOperationResult) attached. In for example the function ReadUsers, where the list of retrieved Users is defined as an out parameter, this list is assigned before the exception is thrown, so that the user will receive the Users that were requested successfully.

Using the Example

Together with the IMS-ES Template also an Example has been given. This example gives a small introduction into the functionality of the Template. The example is split up into two parts: a simple example, and an somewhat more advanced example. Before you can use these examples, first IMS-ES will have to be set up on the used Itslearning site, in Test or possibly on a local host. Then the username / password of IMS-ES has to be filled in into the example, so it can actually access Itslearning. The advanced example also needs the synchronisation id of the main site, this should be automatically generated when IMS-ES is set up. Other than that the examples just have to be run. Note that these examples can only be run once, after that the results might be different.

Difference between Update and Replace

As the difference between the Update functions and Replace functions are not always clear, there will be a small explanation here. An update command only updates the properties that are set, all other properties are ignored. Therefore the object that you will update does not have to be complete, i.e. not all the required fields have to be filled in. You can for example update the phone number of an User A with the following code:

var newUser = new User("A")
{
    Phone = "12345"
}
 
using(var client = new ImsEsClient(username, password, server))
{
    client.UpdateUser(newUser);
}

Now a replace command is more far-reaching, as not only updates it the given properties, it also deletes all the other properties. You can see it as deleting the old object, and then creating a new one. This also means that all the required fields have to be filled in. So updating the phone number of a User will take the following code:

var newUser = new User("A")
{
    FirstName = firstname,
    Lastname = lastname,
    UserName = username,
    Profile = profile,
    Phone = "12345"
}
 
using(var client = new ImsEsClient(username, password, server))
{
    client.ReplaceUser(newUser);
}