Getting started with IMS ES

Set up a site to use IMS ES integration in itslearning.

In itslearning you can set up a site to use IMS ES integration. To be able to do this, your site and the profile for your user account must have

  • Manage API turned ON

  • Manage Enterprise web services turned ON

IMS ES is a licensed service, so if in any doubt, contact your local itslearning services team.

images/download/attachments/18251830/IMSE-API-management-activated.png

In addition, you user must have access right to the page \Administration\Manage IMS Enterprise\Web services in itslearning.
When this is in place, you can set up a new integration:

images/download/attachments/18251830/IMSES-setup.png
For more info on how to do this, see online help:

https://www.itslearning.com/help/en-GB/Content/Integrations/manage_enterprise_web_services.htm?SearchType=Stem&Highlight=IMS

How to connect to itslearning IMS ES

Only secure SSL connections can be used for IMS ES services. This means that each function call to IMS ES should contain username and password for authentication.
The username and password credential information are used to authorize the customer and determine the destination site and hierarchy in itslearning.
The following default settings are used:

  • WCF binding type – basicHttpBinding (is compatible with WSE and java binding)

  • Security mode - TransportWithMessageCredential

  • Client credential type – UserName

The endpoint URL, username and password to be used for your site, is autogenerated by itslearning when you create a new integration.
See the previous section on how to set up a site to use IMS ES integration.

images/download/attachments/18251830/IMSES-endpoint.png

A code example in C#

A small code example on how to connect to IMS ES and create a new person:

namespace TestClientApplication
{
class Program
{
private const string URL = "https://a1enterprise.itslearning.com/WCFServiceLibrary/ImsEnterpriseServicesPort.svc";
private const string Username = "username7075";
private const string Password = " 9nQa8v";
// Function to create the client instance for PersonManagement service
private static PersonManagementServiceSyncClient CreatePersonManagementService()
{
PersonManagementServiceSyncClient service = new PersonManagementServiceSyncClient();
service.ClientCredentials.UserName.UserName = Username;
service.ClientCredentials.UserName.Password = Password;
service.Endpoint.Address = new System.ServiceModel.EndpointAddress(URL);
service.Endpoint.Binding.SendTimeout = new TimeSpan(0, 5, 0);
service.Endpoint.Binding.ReceiveTimeout = new TimeSpan(0, 5, 0);
service.Endpoint.Binding.OpenTimeout = new TimeSpan(0, 1, 0);
service.Endpoint.Binding.CloseTimeout = new TimeSpan(0, 1, 0);
service.InnerChannel.OperationTimeout = new TimeSpan(0, 5, 0);
return service;
}
// Functin to create a person object
private static person CreatePersonObject(string firstName, string lastName, string username, string password)
{
person person = new person();
person.userId = new UserIdDType();
person.name = new NameDType();
person.name.partName = new NameDTypePartName[2];
person.name.partName[0] = new NameDTypePartName();
person.name.partName[0].namePartType = "First";
person.name.partName[0].namePartValue = firstName;
person.name.partName[1] = new NameDTypePartName();
person.name.partName[1].namePartType = "Last";
person.name.partName[1].namePartValue = lastName;
person.institutionRole = new InstitutionRoleDType[1];
person.institutionRole[0] = new InstitutionRoleDType();
person.institutionRole[0].primaryRoleType = true;
person.institutionRole[0].institutionRoleType = InstitutionRoleDTypeInstitutionRoleType.Student;
person.userId.userIdValue = username;
person.userId.passWord = password;
person.demographics = new DemographicsDType();
person.demographics.bday = DateTime.Today;
person.demographics.bdaySpecified = true;
return person;
}
private static syncResponseHeaderInfo CreatePerson(string syncKey, string firstName, string lastName, string username, string password)
{
try
{
createPersonRequest request = new createPersonRequest();
request.sourcedId = new createPersonRequestSourcedId();
request.sourcedId.identifier = syncKey;
request.person = CreatePersonObject(firstName, lastName, username, password);
PersonManagementServiceSyncClient service = CreatePersonManagementService();
syncRequestHeaderInfo headerRequest = new syncRequestHeaderInfo();
headerRequest.messageIdentifier = "1234567890";
createPersonResponse response = new createPersonResponse();
syncResponseHeaderInfo headerResponse = service.createPerson(headerRequest, request, out response);
return headerResponse;
}
catch (Exception e)
{
return null;
}
}
static void Main(string[] args)
{
string syncKey = "TestUserSyncKey";
string firstName = "TestUserFirstName";
string lastName = "TestUserLastName";
string username = "TestUserUsername";
string password = "TestUserPassword";
syncResponseHeaderInfo response = CreatePerson(syncKey, firstName, lastName, username, password);
if (response != null)
{
if (response.statusInfo.codeMajor == StatusInfoDTypeCodeMajor.success)
{
Console.WriteLine(string.Format("User {0} {1} was sucessfully create.", firstName, lastName));
}
else
{
Console.WriteLine(string.Format("User {0} {1} can not be created. The Import application returned error: {2}", firstName, lastName, response.statusInfo.description.text));
}
}
Console.WriteLine();
}
}
}