IMS Enterprise 1.1 XML-based imports

Synopsis

This document provides a short summary and examples of how IMS Enterprise 1.1 is used by itslearning for provisioning users, groups and courses, including extensions and limitations.
For the full standard and data model, see https://www.imsglobal.org/enterprise/index.html

Person


IMS Enterprise 1.1 element

Simple description

Additional information

Mandatory in import file?

Can be autogenerated?

Can be created by user after import?

<person>

Person / user data





<sourcedid><id><../>

PersonID

User's unique ID, usually national identity number

Y

N

N

<userid><../>

Username

Username for login. If not present and the person does not exist, itslearning will generate a username

N

Y

N

<userid password=""><../>

Password

Password for login (clear text).
If not present and the person does not exist, itslearning will generate a password

N

Y

N/Y

<name><nickname><../>

Nickname

For use in chat module

N

N

Y

<name><n><given><../>

First name

User's first name

Y

N

N

<name><n><family><../>

Surname

User's surname

Y

N

N







<demogaphics><bday><../>

Birthday

YYYY-MM-DD

N

N

Y

<email><../>

Email address

Users email address

N

N

Y

<url><../>

url

User's home URL

N

N

Y

<adr><street><../>

Address 1


N

N

Y

<adr><extadd><../>

Address 2


N

N

Y

<adr><pcode><../>

Post code


N

N

Y

<adr><locality><../>

City


N

N

Y

<tel><tel ><../>

Phone

@teltype values: «Voice» or «Mobile»

N

N

Y

<institutionrole primaryrole="Yes" institutionroletype=" "/>

Profile

The itslearning profile which will be assigned to the user:
Default values: "Administrator","Staff","Student",
"Guest","AICC".
Custom profiles must match the text field "Compare to following IMS InstitutionRoleType" in profile setup.

Y

Y (default:Student)

N

<extension>
<emailserver>
<email>[email protected]</email>
<userid
password="clearpassword"
pwencryptiontype="none"
authenticationtype="">
</userid>
<server>mail.domain.tld</server>
<type>IMAP</type>
</emailserver>
</extension>

Email server configuration

Data about IMAP server connections for use with itslearning's embedded email client.
More information on request

N

N

Y

<extension>
<relationship recstatus="1"> <relationshiptype>child</relationshiptype>
<sourcedid>
<id>123456789</id>
<source>sys</source>
</sourcedid>
</relationship>
<relationship recstatus="1">
</extension>

Example of parent/child relationships

Connects parents / carers to their child(ren).
More information on request

N

N

Y

<extension><customstring1> <../>

Example of custom strings (custom user data)

CustomString1 is typically used for National Identity Numbers.
CustomString 2 – 5 are also available.

N

N

Y

<extension>
<privacyprotection>1</privacyprotection>
</extension>

Example of privacy protection

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.


Xml file

Value imported to field

Person.EnablePrivacyProtection

element <privacyprotection> missing

no value imported

<privacyprotection></privacyprotection>

no value imported

<privacyprotection/>

no value imported

<privacyprotection>0</privacyprotection>

0

<privacyprotection>1</privacyprotection>

1

N

N

N

<extension>
<cloudaccount>
<login> [email protected] </login>
<accounttype>GSuite</accounttype>
</cloudaccount>
</extension>

<login>: cloudaccount id / login to the cloud service

<accounttype>: cloud service type. Currently we only support GSuite.

Cloud account is used for pre-connecting a users' cloud account, e.g. the users' G Suite account, as part of user provisioning. When the accounts are pre-connected the users do not need to manually connect their accounts in itslearning anymore. Currently we only support G Suite as account type.

How does the import work:

Xml file

Value imported

element <cloudaccount> missing

no value imported.
If user already has cloud account imported, cloud account will be deleted (regardless of type)

< cloudaccount ><cloudaccount>

no value imported.
If user already has cloud account imported, cloud account will be deleted (regardless of type)

<cloudaccount>

no value imported.
If user already has cloud account imported, cloud account will be deleted (regardless of type)

<cloudaccount>
<login></login>
</cloudaccount>

Invalid xml.
Both < login > and < accounttype > needs to be specified

<cloudaccount>
<login></login>
<accounttype></accounttype>
</cloudaccount>

Invalid xml.
< accounttype > cannot be empty
no value imported/nor deleted.

<cloudaccount>
<login</login>
< accounttype >GSuite</ accounttype >
</cloudaccount>

no value imported.
If user already has cloud account imported, cloud account will be deleted (if < accounttype> = GSuite)

<cloudaccount>
<login>xxx</login>
<accounttype>GSuite</accounttype>
</cloudaccount>

Value imported / updated if already exists

Note: More than one <extension><cloudaccount> for a user is not supported. If you have more than one, the first one is imported.

N

N

Y

<extension> <eckid>https://id.school/LL_123467890abcdefghijklmnopqrstuvwxzABCDEF</eckid>
<digideliveryid>13842706-2082-465B-BA07-9AEDD3A62F08</digideliveryid>
</extension>

Example of Entree information: eckId and digiDeloveryId

EckId is unique identity for daily use of digital teaching material.
DigiDeliveryId is ECK digital delivery address.

When EckId and/or DigiDeliveryId are missing in the request the stored values don't removed from db.

N

N

N

<extension>
<anonymousid>Some-Unique-Student-Identifier</anonymousid>
</extension>

Anonymous Id

It can be used as Exam Candidate Number.

When AnonymousId is missing in the request, the stored value will be removed from db.

AnonymousId is case-insensitive and unique.

N

N

N

<extension>
<expires>2022-11-03</expires>
</extension>

Expiry date

When user account expires.
User account never expires if left empty.

When expires is missing in the request or its value is empty, the stored value will be removed from db.

Expected format: YYYY-MM-DD

N

N

N


Person XML examples:

<!--
Comments 1:
1) recstatus="1" --Recstatus identifies what type of transactions to run. 1=Add, 2=Update,3=Delete. Not used by itslearning.
2)
<sourcedid><id>12345678911</id></sourcedid> -
This field describes the unique identifier for a person.
In itslearning, this saved as the field "Synchronization Key"
3) <userid>030042</userid> --This field decides the username of the Person in itslearning
4) password="W3e2gj" - The Password is an attribute in the <userid> field
5) <institutionrole> is the tag that decides which profile the person will be granted in itslearning.
Mandatory fields for person:
- sourcedid/source
- sourcedid/id
- name/n/family
- name/n/given
- institutionrole
-->
 
<!-- PERSON -->
<person recstatus="1">
<sourcedid>
<source>SHS</source>
<id>12345678911</id>
</sourcedid>
<userid password="W3e2gj">030042</userid>
<name>
<fn>Janne Evensen</fn>
<n>
<family>Evensen</family>
<given>Janne</given>
</n>
</name>
<demographics>
<bday>1957-03-12</bday>
</demographics>
<email/>
<tel teltype="Voice">37007121</tel>
<tel teltype="Mobile">91055049</tel>
<adr>
<street>Lillevikvegen 5</street>
<locality>MOLDE</locality>
<pcode>6412</pcode>
</adr>
<institutionrole institutionroletype="Student" primaryrole="Yes"/>
</person>
 
 
<!--
Comments 2:
It is optional whether to send username and password in the sync process
or not. If you don't itslearning will automatically create it's own
username and password for the Persons
Below we can see an example of a person object without a username or password.
-->
 
<person recstatus="2">
<sourcedid>
<source>NO-FS</source>
<id>12345678969</id>
</sourcedid>
<userid/>
<name>
<fn>Anne Siqveland</fn>
<sort>Siqveland Anne</sort>
<n>
<family>Siqveland</family>
<given>Anne</given>
</n>
</name>
<demographics>
<gender>1</gender>
<bday>1969-01-04</bday>
</demographics>
<adr>
<extadd/>
<street>P.B 5190 Majorstua</street>
<locality>0302 OSLO</locality>
<pcode>0302</pcode>
<country/>
</adr>
<institutionrole primaryrole="Yes" institutionroletype="Staff"/>
</person>
 
<!--
Comments 3:
Below we can see an example of a person object with some extension fields.
-->
 
<person recstatus="1">
<sourcedid>
<source>SHS</source>
<id>12345678911</id>
</sourcedid>
<userid password="W3e2gj">030042</userid>
<name>
<fn>Janne Evensen</fn>
<n>
<family>Evensen</family>
<given>Janne</given>
</n>
</name>
<demographics>
<bday>1957-03-12</bday>
</demographics>
<email/>
<tel teltype="Voice">37007121</tel>
<tel teltype="Mobile">91055049</tel>
<adr>
<street>Lillevikvegen 5</street>
<locality>MOLDE</locality>
<pcode>6412</pcode>
</adr>
<institutionrole institutionroletype="Student" primaryrole="Yes"/>
<extension>
  <customstring1>123</customstring1>
  <customstring2>ABC</customstring2>
      <privacyprotection>1</privacyprotection>
<eckid>https://id.school/LL_123467890abcdefghijklmnopqrstuvwxzABCDEFGHIJKLMNOPQRSTUV4W</eckid>
<digideliveryid>13842706-2082-465B-BA07-1AEDD1A62F09</digideliveryid>
    <anonymousid>Some-Student-Anonymous-Identifier</anonymousid>
    <expires>2022-11-03</expires>
   </extension>
</person>


Group

IMS Enterprise 1.1 elements and attributes

Simple description

Additional information

Mandatory in import file?

Can be auto- generated?

Can be created by user after import?

<group>

Group data

Generic groups that can be organized in a hierarchy, e.g School -> Schoolyear -> Class

Y



<sourcedid><id><../>

GroupID

The unique ID for the group.

Y

N

N

<sourcedid><source><../>

Group name

Mandatory, but not used by itslearning

Y

N

N

<description><short><../>

Title

The group's title shown in listings within itslearning

Y

N

N

<description><long><../>

Long title


N

N

N

<relationship relation = "1">
<sourcedid><id><../>
<../>

Parent GroupID

Relation to a parent groupID in a hierarchy. (Note: For root groups / top level groups in a hierarchy, the group must have a relationship to itself)

Y

N

N

<relationship relation = "1">
<sourcedid><source><../>
<../>

Name of source

Mandatory, but not used by itslearning

Y

N

N

<relationship relation = "1">
<label><../>
<../>


Mandatory, but not used by itslearning

Y

N

N

<typevalue> </typevalue>

Categorization / differentiation of groups

Pre-defined values that allow the import application to differentiate between types of groups
When importing, the groups can have the following properties specific properties set:

  • Auto generate a course from this group?

  • Visible in navigation tree?

  • Visible in search results?

  • Allow «news» / bulletins for this group?

    These values must be defined by the customer and communicated to itslearning during the implementation phase.
    In particular, It is recommended that level 2 groups (usually departments / schools) are clearly identifiable, so they can be automatically set as "organisations" within itslearning.

N

N

N

<relationship><sourcedid><source><../>

Name of parent group

Mandatory, but not used by itslearning

Y

N

N

<extension><course><code><../>

Course code

If group is of type "course", this can be used to define the course code (if different from any of the description fields)

N

N

N

<extension><course><credits><../>

Course credits

If group is of type "course", this can be used to define the numbers of credits

N

N

N

<extension>

<course>

<coursetemplate>

<coursetemplatesynckey>CourseSyncKey</coursetemplatesynckey>

<coursecreatorsynckey>PersonSyncKeyXYZ</coursecreatorsynckey>

<terms>

<term sourcetermsynckey1="Term1_2011" newtermsynckey1="Term1_2013" />

<term sourcetermsynckey2="Term2_2011" newtermsynckey2="Term2_2013" />

<term sourcetermsynckey3="Term3_2011" newtermsynckey3="Term3_2013" />

<term sourcetermsynckey4="Term4_2011" newtermsynckey4="Term4_2013" />

<term sourcetermsynckey5="Term5_2011" newtermsynckey5="Term5_2013" />

<term sourcetermsynckey6="Term6_2011" newtermsynckey6="Term6_2013" />

</terms>

</coursetemplate>

</course>

</extension>


coursetemplate:

  • coursetemplatesynckey

  • coursecreatorsynckey

terms:

  • sourcetermsynckey1

  • newtermsynckey1

  • sourcetermsynckey2

  • newtermsynckey2

  • sourcetermsynckey3

  • newtermsynckey3

  • sourcetermsynckey4

  • newtermsynckey4

  • sourcetermsynckey5

  • newtermsynckey5

  • sourcetermsynckey6

  • newtermsynckey6

Both coursetemplatesynckey and coursecreatorsynckey needs to be specified in order to create the course based on a template.

The Creator needs to be a member of the organisation where the template course is shared and the organisation where the created course will be located.

sourcetermsynckey and newtermsynckey from 1 to 6. Means that a maximum of 6 terms from the template course can be defined as replaced with a new term based on term's SyncKey.

If template course only have two terms it will be enough to send this:

<coursetemplate>

<terms>

<term sourcetermsynckey1="Fall_2011" newtermsynckey1="Fall_2012" />

<term sourcetermsynckey1="Spring_2012" newtermsynckey1="Spring_2013" />

</terms>

</coursetemplate>

N

N


<extension>
<xitiCollectiviteId>365101</xitiCollectiviteId>
<xitiEstablishmentId>1</xitiEstablishmentId>
</extension>

Xiti settings:
XitiCollectiviteId
xitiEstablishmentId

Xiti is the 3rdParty web trafficing tool. Optional.
If group is of type of "school", this can be used to define the xiti settings

  • XitiCollectiviteId must be populated with a numeric identifier of 6 characters.This identifier corresponds to the region connecting a high school or department affiliation of a college.

  • xitiEstablishmentId must be filled with a numeric identifier (increment from 1 )

N

N



Group XML example:

<!-- GROUP -->
<!-- All groups are connected to a hierarchic structure through the relationship-tag -->
<!--
1) <sourcedid><id>SHS</id></sourcedid> - This field describes the unique identifier of the group
2) <relationship><sourcedid><id>SHS</id></sourcedid></relationship> - This field describes the ID to the parent group
3) <grouptype><typevalue>SCHOOL</typevalue></grouptype> - This filed describes what kind of group this is. We can define our own categories.
4) <description><short>SHS</short></description> - This field describes the title of the group. (As default <short> is used as grouptitle in it's learning, but <full> can also be used.)
-->
<group recstatus="1">
<!-- This group has a relationship to itself, and therefore it is the topnode of the hierarchy (relationship/sourcedid/id = sourcedid/id) -->
<sourcedid>
<source>Sommartoppen Høgskole</source>
<id>SHS</id>
</sourcedid>
<grouptype>
<scheme>SHS</scheme>
<typevalue level="1">SITE</typevalue>
</grouptype>
<description>
<short>SHS</short>
<full>Sommartoppen Høgskole</full>
</description>
<relationship relation="1">
<sourcedid>
<source>Sommartoppen Høgskole</source>
<id>SHS</id>
</sourcedid>
</relationship>
</group>
 
<!-- This is a subgroup of the topnode -->
<group recstatus="1">
<sourcedid>
<source>Sommartoppen Høgskole</source>
<id>420000</id>
</sourcedid>
<grouptype>
<scheme>SHS</scheme>
<typevalue level="2">DEPARTMENT</typevalue>
</grouptype>
<description>
<short>Avd. for sosionomutd.</short>
<full>Avdeling for sosionomutdanning</full>
</description>
<relationship relation="1">
<sourcedid>
<source>Sommartoppen Høgskole</source>
<id>SHS</id>
<!-- This group points to the topnode and therefore is a child of the topnode -->
</sourcedid>
<label>Dummy text - required by DTD</label>
</relationship>
<extension>
<xitiCollectiviteId>365101</xitiCollectiviteId>
<xitiEstabIishmentId>1</xitiEstabIishmentId>
</extension>
</group>
 
<!-- This is a subgroup of the previous subgroup -->
<group recstatus="1">
<sourcedid>
<source>Sommartoppen Høgskole</source>
<id>420000-BA</id>
</sourcedid>
<grouptype>
<scheme>SHS</scheme>
<typevalue level="3">EDUCATIONLEVEL</typevalue>
</grouptype>
<description>
<short>Bachelorutdanning</short>
<full>Bachelorutdanning ved sosionomstudiumet</full>
</description>
<relationship relation="1">
<sourcedid>
<source>Sommartoppen Høgskole</source>
<id>420000</id>
<!-- This group points to the group "Avd. for sosionomutd." and therefore is a child of this -->
</sourcedid>
<label>Dummy text - required by DTD</label>
</relationship>
</group>
 
<!-- This a group that we wish to create a course from-->
<group recstatus="1">
<sourcedid>
<source>Sommartoppen Høgskole</source>
<id>SOS100</id>
</sourcedid>
<grouptype>
<scheme>SHS</scheme>
<typevalue level="3">COURSE</typevalue>
</grouptype>
<description>
<short>SOS100 Sosialt arbeid</short>
<full>SOS100 Sosialt arbeid</full>
</description>
<relationship relation="1">
<sourcedid>
<source>Sommartoppen Høgskole</source>
<id>420000-BA</id>
<!-- This group points to the group "Bachelorutdanning" and therefore is a child of this-->
</sourcedid>
<label>Dummy text - required by DTD</label>
</relationship>
<extension>
<course>
<code>SOS100_HT11</code>
<credits>10</credits>
<coursetemplate>
<coursetemplatesynckey>CourseX_SyncKey</coursetemplatesynckey>
<coursecreatorsynckey>PersonX_SyncKey</coursecreatorsynckey>
<terms>
<term sourcetermsynckey1="Term1_2011" newtermsynckey1="Term1_2013" />
<term sourcetermsynckey2="Term2_2011" newtermsynckey2="Term2_2013" />
</terms>
 </coursetemplate>
</course>
</extension>
</group>


Membership

IMS Enterprise 1.1 element

Simple description

Additional information

Mandatory in import file?

Can be auto-generated?

Can be created by user after import?

<membership>

Membership

Relations between a group and one or more persons

Y



<sourcedid><id><../>

GroupID

Points to the groupID having members.

Y



<sourcedid><source><../>

Name of source system

Mandatory, but not used by itslearning

Y

N

N

<member><sourcedid><id><../>

PersonID

Points to the person which is a member

Y



<member><sourcedid><source><../>

Name of source system

Mandatory, but not used by itslearning

N



<member><role roletype="[value] "><../>


The person's role within the group.
Learner (01), Instructor (02), Mentor (06) and Guest (04) roles are supported by itslearning

Y (or pre-defined)



<extension><homeorganisation>[value]</homeorganisation><extension>

Home organisation

Value to indicate if this is the home organisation for the member in the group.

1 will set this hierarchy group to be home organisation for this member *

0 will un-set this hierarchy group to be home organisation, and set the root hierarchy to be home organisation for this member **

See more info in IMS E - Parent/child, organisation and home organisation import

N




Membership XML example

<!-- MEMBERSHIP -->
<!--
A membership contains a group and multiple members. The id of the group and the id of persons are used to define the membership.
This membership connects four persons to the group "Bachelorutdanning". Since this is a subgroup to the groups "SHS" and "Avd. for sosionomutd." the persons will automatically be members of this group as well, i.e. memberships are inherited from the root group.
The best practice regarding memberships in itslearning is to NOT rely on inheritance. Each <group> element on every level should include explicit memberships for each member.
-->
<!-- One membership = one group and X persons -->
<membership>
<sourcedid>
<source>Sommartoppen Høgskole</source>
<id>420000-BA</id>
</sourcedid>
<member>
<sourcedid>
<source>Sommartoppen Høgskole</source>
<id>12345678911</id>
</sourcedid>
<idtype>1</idtype>
<role recstatus="1" roletype="02">
<!-- Roletype 02 = Staff -->
<status>1</status>
</role>
</member>
<member>
<sourcedid>
<source>Sommartoppen Høgskole</source>
<id>12345678969</id>
</sourcedid>
<idtype>1</idtype>
<role recstatus="1" roletype="01">
<!-- Roletype 01 = Student -->
<status>1</status>
</role>
</member>
<member>
<sourcedid>
<source>Sommartoppen Høgskole</source>
<id>60245145874</id>
</sourcedid>
<idtype>1</idtype>
<role recstatus="1" roletype="01">
<status>1</status>
</role>
</member>
<member>
<sourcedid>
<source>Sommartoppen Høgskole</source>
<id>11111060233</id>
</sourcedid>
<idtype>1</idtype>
<role recstatus="1" roletype="01">
<status>1</status>
</role>
</member>
</membership>
<!--
Mandatory fields for membership:
- sourcedid/source
- sourcedid/id
- member/sourcedid/source
- member/sourcedid/id
- member/idtype
- member/role
- member/role/status
-->


General


<!--
All files have to start and end with an enterprise-tag + contain a properties-tag:
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE enterprise PUBLIC "IMS Enterprise/LMS Interoperability DTD" "http://www.fs.usit.uio.no/DTD/ims_epv1p1.dtd">
<enterprise>
<properties lang="NO">
<datasource>NO-FS</datasource>
<datetime>2006-05-04</datetime>
</properties>
...XML...
</enterprise>
-->

Membership best practice:

Although itslearning employs an inheritance regime, it is a best practice to explicitly define memberships at each and every hierarchy level where the person should be a member.
This is to ensure a proper cleanup when the user is deleted.