Managing persons

clPerson management with itslearning and IMS ES comprises two distinct services, the PersonManagement service and the ExtendedPersonManagement service.

The PersonManagement service contains the basic services defined by the IMS consortium.

The ExtendedPersonManagement service provides additional services to facilate simple extraction and consolidation of users that were created manually in itslearning.

Both work with the basic IMS Person object, with certain itslearning extensions.

Services

PersonManagement

Description

The PersonManagement service contains the basic services defined by the IMS consortium.

Service URL

https://enterprise.itslearning.com/WCFServiceLibrary/PersonManagementServiceSync.svc

Please note this URL applies to the USIT environment. See here.

WSDL URL

https://enterprise.itslearning.com/WCFServiceLibrary/PersonManagementServiceSync.svc?wsdl

IMS Enterprise Services online documentation

The function descriptions, original WSDL files, request/response examples can be found here:
http://www.imsglobal.org/es/index.html
http://www.imsglobal.org/es/esv1p0/imsperson_bindv1p0.html
http://www.imsglobal.org/es/esv1p0/imsperson_infov1p0.html

ExtendedPersonManagement

Description

This service implements some additional methods which are not defined in the IMS ES standard.

Service URL

https://enterprise.itslearning.com/WCFServiceLibrary/ExtendedPersonManagementServiceSync.svc

WSDL URL

https://enterprise.itslearning.com/WCFServiceLibrary/ExtendedPersonManagementServiceSync.svc?wsdl

Methods for person management

The Person object - mapping between IMS ES and itslearning

IMS ES Field	Mandatory	Itslearning field	Comment
SourcedId	X	syncPersonKey	SyncID / synchronization key
Prefix		Prefix	Max 32 characters
FirstName	X	Firstname
LastName	X	Lastname
Nick		Nickname
InstitutionRoleType	X	Profile	Important! See transformation table and detailed information in section 'How to give a person the correct profile in itslearning'.
UserIdValue		Username	Configuration can be made on its learning side to decide if the username should be imported from IMS ES or generated by its learning
Password		Password	Configuration can be made on its learning side to decide if the username should be imported from IMS ES or generated by its learning
Voice		Phone
Mobile		Cellular phone
Street[0]		Address (field1)
Street[1]		Address (field2)
Postcode		Post code / Zip code	Max 10 characters
Locality		Town / city
Extension ExtensionField		CustomString1 … CustomString5 or email information or PrivacyProtection	See below for more information.
Extension Relationship			A person's relationship to its child(s) can be added as extension. See chapter 'How to add parent/child relationship.

Extensions

Itslearning has defined a number of extensions to the standard IMS person object. Descriptions of these extensions are found below:

CustomString fields

Custom user information: Allows you to add custom information on profiles. The custom fields appear as an option when you add new users, and can be, for example, student or employee number, Skype address or similar.

Length of value stored in Customstring fields can be max 255 characters.

Example

<extension>
       <-- itslearning CustomString1 field (this and next can both be used for CustomString1 field) -->
    <extensionField>
        <fieldName>nationalidentitynumber</fieldName>
        <fieldType>string</fieldType>
        <fieldValue>ValueA</fieldValue>
    </extensionField>
    <-- itslearning CustomString1 field (this and previous can both be used for CustomString1 field)-->
    <extensionField>
        <fieldName>customstring0</fieldName>
        <fieldType>string</fieldType>
        <fieldValue>ValueB</fieldValue>
    </extensionField>
    <-- itslearning CustomString2 field -->
    <extensionField>
        <fieldName>customstring1</fieldName>
        <fieldType>string</fieldType>
        <fieldValue>ValueC</fieldValue>
    </extensionField>
    <-- itslearning CustomString3 field -->
    <extensionField>
        <fieldName>customstring2</fieldName>
        <fieldValue>ValueD</fieldValue>
    </extensionField>
    <-- itslearning CustomString4 field -->
    <extensionField>
        <fieldName>customstring3</fieldName>
        <fieldType>string</fieldType>
        <fieldValue>ValueE</fieldValue>
    </extensionField>
    <-- itslearning CustomString5 field -->
    <extensionField>
        <fieldName>customstring4</fieldName>
        <fieldType>string</fieldType>
        <fieldValue>ValueF</fieldValue>
    </extensionField>
</extension>

Email account information

You can use itslearning as a regular e-mail reader. This means that you can read your private e-mail in itslearning without having to leave itslearning. itslearning supports both POP3 and IMAP4. You can set an e-mail account as the default account instead of the internal messages in the Message settings.

Example

 <extension>
    <extensionField>
        <fieldName>emailserver/email</fieldName>
        <fieldType/>
        <fieldValue>[email protected]</fieldValue>
    </extensionField>
    <extensionField>
        <fieldName>emailserver/userid/@password</fieldName>
        <fieldType/>
        <fieldValue>password</fieldValue>
    </extensionField>
    <extensionField>
        <fieldName>emailserver/port</fieldName>
        <fieldType/>
        <fieldValue>110</fieldValue>
    </extensionField>
    <extensionField>
        <fieldName>emailserver/server</fieldName>
        <fieldType/>
        <fieldValue>mail2.ru</fieldValue>
    </extensionField>
    <extensionField>
        <fieldName>emailserver/type</fieldName>
        <fieldType/>
        <fieldValue>Imap</fieldValue>
    </extensionField>
    <extensionField>
        <fieldName>emailserver/userid</fieldName>
        <fieldType/>
        <fieldValue>userid</fieldValue>
    </extensionField>
</extension>

Cloud account information

Cloud account is used for pre-connecting a users' cloud account. This means that if a user's cloud account information is imported, the cloud account will be pre-connected during import and the users do not need to manually connect their cloud account in itslearning anymore.

Example of extension with cloud account information

 <extension>
    <extensionField>
        <fieldName>cloudaccount/login</fieldName>
        <fieldType>string</fieldType>
        <fieldValue>[email protected]</fieldValue>
    </extensionField>
    <extensionField>
        <fieldName>cloudaccount/accounttype</fieldName>
        <fieldType>string</fieldType>
        <fieldValue>GSuite</fieldValue>
    </extensionField>
</extension>

Currently we only support GSuite as account type (<fieldValue>GSuite</fieldValue>).
Only one cloudaccount for a user is supported

IsExternalUser

External user is a user who is not member of your site, but has joined your site through a community course.

The extension field IsExternalUser will return value True in the response, if the user is an external user. This value can only be returned in response, it cannot be set using createPerson/updatePerson/replacePerson methods.

Example of readPerson response returning IsExternalUser field:

 <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
   <s:Header>
     ...
   </s:Header>
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <readPersonResponse xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManMessSchema_v1p0">
         <person>
            <formatName xsi:nil="true" xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0"/>
            <name xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
               <partName>
                  <namePartType>First</namePartType>
                  <namePartValue>James</namePartValue>
               </partName>
               <partName>
                  <namePartType>Last</namePartType>
                  <namePartValue>Dean</namePartValue>
               </partName>
               <partName>
                  <namePartType>Nick</namePartType>
                  <namePartValue>jamie</namePartValue>
               </partName>
            </name>
            <email xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">[email protected]</email>
            <URL xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0"/>
            <userId xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
               <userIdValue xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">jamdea</userIdValue>
            </userId>
            <address xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
               <extadd/>
               <locality/>
               <postcode/>
               <street/>
            </address>
            <demographics xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
               <gender>Male</gender>
               <bday>1926-07-03</bday>
            </demographics>
            <institutionRole xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
               <institutionRoleType>Student</institutionRoleType>
               <primaryRoleType>true</primaryRoleType>
            </institutionRole>
            <tel xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
               <telType>Voice</telType>
               <telValue>12774</telValue>
            </tel>
            <tel xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
               <telType>Mobile</telType>
               <telValue>876987</telValue>
            </tel>
            <extension xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
               <extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
                  <fieldName>IsExternalUser</fieldName>
                  <fieldType>Bool</fieldType>
                  <fieldValue>True</fieldValue>
               </extensionField>
            </extension>
         </person>
      </readPersonResponse>
   </s:Body>
</s:Envelope>

PrivacyProtection

Indicates if a students personal information should be handled with care. If PrivacyProtection is enabled, teachers and administrators will see a padlock on the student's profile picture.

Example

 <extension>
 <extensionField>
  <fieldName>privacyprotection</fieldName>
  <fieldType>bool</fieldType>
  <fieldValue>1</fieldValue>
 </extensionField>
</extension> 

if privacyprotection element in not part of create/update/replace request -> existing privacyprotection value on Person in itslearning will not be changed
if privacyprotection value in create/update/replace request is different from 1 -> value privacyprotection on Person in itslearning is set to 0
if privacyprotection value in create/update/replace request is 1 -> value privacyprotection on Person in itslearning is set to 1

Relationship

A person's relationship to its children can be added as an extension.
A person's relationship to its children and parents can be returned as an extension.

Example of readPerson response returning parent/child relationship

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
  <s:Header>
    ...
   </s:Header>
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <readPersonResponse xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManMessSchema_v1p0">
      <person>
        <formatName xsi:nil="true" xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0"/>
        <name xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
          <partName>
            <namePartType>First</namePartType>
            <namePartValue>Parent1</namePartValue>
          </partName>
          <partName>
            <namePartType>Last</namePartType>
            <namePartValue>Parent1</namePartValue>
          </partName>
          <partName>
            <namePartType>Nick</namePartType>
            <namePartValue/>
          </partName>
        </name>
        <email xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">[email protected]</email>
        <URL xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0"/>
        <userId xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
          <userIdValue xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">Parent1</userIdValue>
        </userId>
        <address xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
          <extadd/>
          <locality/>
          <postcode/>
          <street/>
        </address>
        <demographics xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
          <gender>Male</gender>
        </demographics>
        <institutionRole xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
          <institutionRoleType>Guest</institutionRoleType>
          <primaryRoleType>true</primaryRoleType>
        </institutionRole>
        <tel xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
          <telType>Voice</telType>
          <telValue/>
        </tel>
        <tel xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
          <telType>Mobile</telType>
          <telValue/>
        </tel>
        <extension xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
          <relationship xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
            <relation>Child</relation>
            <sourceId>
              <identifier>Student4</identifier>
            </sourceId>
          </relationship>
          <relationship xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
            <relation>Parent</relation>
            <sourceId>
              <identifier>GrandParent1</identifier>
            </sourceId>
          </relationship>
        </extension>
      </person>
    </readPersonResponse>
  </s:Body>
</s:Envelope>

PasswordChange

Use this extension field to set rules for a person's settings to change the password, as long as the site settings allow password - some sites only rely on SSO.

Example

 <extension>
   <extensionField>
     <fieldName>passwordchange</fieldName>
     <fieldType>String</fieldType>
     <fieldValue>MustChangeOnNextLogin</fieldValue>
   </extensionField>
</extension>

Possible values (in fieldValue node):

Allowed
NotAllowed
MustChangeOnNextLogin

Allowed - The user can change his/her password

Not Allowed - The user cannot change his/her password

MustChangeOnNextLogin - The user must change password on next login, (setting will be changed to Allowed after first successful login)

IsHeadmaster (Specific customers with French calendar only)

Use this extension field to set a specific person to be a headmaster in terms of managing Calendar event approval page.

Example

 <extension>
   <extensionField>
     <fieldName>frenchcalendarmanagement/isheadmaster</fieldName>
     <fieldType>Bool</fieldType>
     <fieldValue>true</fieldValue>
   </extensionField>
</extension>

Possible values (in fieldValue node):

false
true

EckId (Unique identity for daily use of digital teaching material)

The following methods can be used to import eckId as the extension field EckId: createPerson, createPersons, updatePerson, updatePersons. The customer settings "Enable Eck id support" should be ON.

Example

 <ims3:extension>
   <ims2:extensionField>
      <ims2:fieldName>eckid</ims2:fieldName>
      <ims2:fieldType>String</ims2:fieldType>
      <ims2:fieldValue>https://ketenid.nl/pilot/8e0a9f57fc76854d3dd2d3c4fa732feaf7b7a2d5f549a5458ce</ims2:fieldValue>
   </ims2:extensionField>
 </ims3:extension>

DigiDeliveryId (ECK digital delivery address)

The following methods can be used to import DigiDeliveryId as the extension field digiDeliveryId: createPerson, createPersons, updatePerson, updatePersons. The customer settings "Enable DigiDeliveryId support" should be ON.

Example

<extension>
   <extensionField>
     <fieldName>digiDeliveryId</fieldName>
     <fieldType>String</fieldType>
     <fieldValue>13842706-2082-465B-BA07-9AEDD3A62FC9</fieldValue>
   </extensionField>
</extension>

AnonymousId (can be used for Exam Candidate Number)

Use this extension field to set AnonymousId for a person.

Max length: 64 characters
Unique values only: yes
Case sensitive: no

Example

<extension>
   <extensionField>
     <fieldName>anonymousid</fieldName>
     <fieldType>String</fieldType>
     <fieldValue>Some-Unique-Student-Identifier</fieldValue>
   </extensionField>
</extension>

Expiry date

Use this extension field to set when user account expires. User account never expires if left empty.

Expected format: YYYY-MM-DD

Example

<extension>
   <extensionField>
     <fieldName>expires</fieldName>
     <fieldType>date</fieldType>
     <fieldValue>2022-11-03</fieldValue>
   </extensionField>
</extension>