Managing groups

URL to service

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

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

This service contains the following functions:

createGroup
createGroups
updateGroup
updateGroups
deleteGroup
deleteGroups
replaceGroup
replaceGroups
changeGroupsIdentifier
readGroup
readGroups
readGroupsForPerson

WSDL file for GroupManagement
https://enterprise.itslearning.com/WCFServiceLibrary/GroupManagementServiceSync.svc?wsdl

IMS Enterprise Service 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/imsgroup_bindv1p0.html
http://www.imsglobal.org/es/esv1p0/imsgroup_infov1p0.html

The group object and its mapping to itslearning

IMS ES Field	Mandatory	Itslearning field	Comment
SourcedId	X	Hierarchy.syncLocationId	*SyncID*
groupType/scheme			Should be set to ItslearningOrganisationTypes if you want to be able to set the organisation type. Examples can be found in Creating organisations and Creating courses and course groups
groupType/typeValue/type		Hierarchy.OrganisationType	Set to School to create an organisation of type school. See Creating organisations Set to Course to create a hierarchy connected to a course. See Creating courses and course groups. Set to CourseGroup to create a hierarchy connected to a course group. See Creating courses and course groups
groupType/typeValue/level		Hierarchy.OrganisationType	Alternative method to set the organisation type. You can either set the level, or the type, or both. If you set both then the type and level must match, so if you set type to School, then level must be 1. Set to 1 to create an organisation of type school. See Creating organisations Set to 2 to create a hierarchy connected to a course. See Creating courses and course groups Set to 3 to create a hierarchy connected to a course group. See Creating courses and course groups
Relationship/relation	X		NB! itslearning only supports Parent
Relationship/sourceId/identifier	X	Hierarchy.syncRelationId	syncID of the parent of this hierarchy. If you are creating a hierarchy with OrganisationType CourseGroup, then the parent must be a course. See Creating courses and course groups for more information on this.
Description/descShort	X	Hierarchy.Title
Description/descLong		Hierarchy.Description
Extensions ExtensionField			Additional group information that can be imported. If you are creating a hierarchy with OrganisationType Course, then extension data is mandatory. See Creating courses and course groups for more information on this. A list of supported extensions can be found below.

Group request and <Relationship> element

The releationship element will tell you where to insert the hierarchy group in the itslearning hierarchy structure.

For group A you specify <relationship><sourcedId><identifier> = X
A hierarchy group with syncID = X already exists in itslearning
Group A will be placed as child of group X in itslearning
For group A you specify <relationship><sourcedId><identifier> = <sourcedId><identifier>
Group A will be placed as child of the root hierarchy of the site

Extensions

Some additional group information:

visibleinsearch
allowconnectiontocourse
XitiEstablishmentId
XitiCollectiviteId
course
course/code
course/credit
LegalId - an external identifier of an organisation. Can be sets only for hierarchies with the type 'School' or 'Site'. Max length is 50.

Course template can be specified for a course:

course/template/synckey
course/template/coursecreatorsynckey

Course template can contain terms. The collection of terms to be replaced should be specified one by one. Each term should have some unique ID and specified as {termId}.

course/template/terms/{termId}/sourcetermsynckey
course/template/terms/{termId}/newtermsynckey

External course template can be specified for a course:

course/template/externaltemplateid

For details about using course templates please use this link Working with course templates in IMS-ES.

Note: "course" extension field is mandatory to create/update any course information.

Example of usage:

<extension xmlns="http://www.imsglobal.org/services/gms/xsd/imsGroupManDataSchema_v1p0">
    <!--// set if the hierarchy group should be visible in search or not. Default value = True.-->
    <extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
        <fieldName>visibleinsearch</fieldName>
        <fieldType>Boolean</fieldType>
        <fieldValue>True</fieldValue>
    </extensionField>
    <!--// set if the hierarchy group should allow relationship to course or not. Default value = 1.-->
    <extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
        <fieldName>allowconnectiontocourse</fieldName>
        <fieldType>Boolean</fieldType>
        <fieldValue>1</fieldValue>
    </extensionField> 
    <!--// set the xiti establishment Id of the hierarchy group-->
    <extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
        <fieldName>XitiEstablishmentId</fieldName>
        <fieldType>int</fieldType>
        <fieldValue>121</fieldValue>
    </extensionField>
    <!--// set the xiti establishment Id of the hierarchy group-->
    <extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
        <fieldName>XitiCollectiviteId</fieldName>
        <fieldType>int</fieldType>
        <fieldValue>343</fieldValue>
    </extensionField>
    <!--// set the external identifier (Legal Id) of the hierarchy group-->
    <extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
        <fieldName>LegalId</fieldName>
        <fieldType>String</fieldType>
        <fieldValue>School_123</fieldValue>
    </extensionField>
  <!--// course created with this course title-->
    <extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
        <fieldName>course</fieldName>
        <fieldType>String</fieldType>
        <fieldValue>English course (4)</fieldValue>
    </extensionField>
    <!--// course created with this course code-->
    <extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
        <fieldName>course/code</fieldName>
        <fieldType>String</fieldType>
        <fieldValue>ENG13/18</fieldValue>
    </extensionField>
    <!--// course created with this course credits-->
    <extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
        <fieldName>course/credits</fieldName>
        <fieldType>String</fieldType>
        <fieldValue/>
    </extensionField>
    <!--// course external template id-->
    <extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
        <fieldName>course/template/externaltemplateid</fieldName>
        <fieldType>Int</fieldType>
        <fieldValue>ExternalTemplateId</fieldValue>
    </extensionField>
    <!--// course template sync key-->
    <extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
        <fieldName>course/template/synckey</fieldName>
        <fieldType>String</fieldType>
        <fieldValue>CourseTemplateSyncKey</fieldValue>
    </extensionField>
    <!--// course creator sync key-->
    <extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
        <fieldName>course/template/coursecreatorsynckey</fieldName>
        <fieldType>String</fieldType>
        <fieldValue>CourseCreatorSyncKey</fieldValue>
    </extensionField>
    <!--// term #1 source sync key-->
    <extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
        <fieldName>course/template/terms/1/SourceTermSyncKey</fieldName>
        <fieldType>String</fieldType>
        <fieldValue>Term1SourceTermSyncKey</fieldValue>
    </extensionField>
    <!--// term #1 new sync key-->
    <extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
        <fieldName>course/template/terms/1/NewTermSyncKey</fieldName>
        <fieldType>String</fieldType>
        <fieldValue>Term1NewTermSyncKey</fieldValue>
    </extensionField>
    <!--// term #2 source sync key-->
    <extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
        <fieldName>course/template/terms/2/SourceTermSyncKey</fieldName>
        <fieldType>String</fieldType>
        <fieldValue>Term2SourceTermSyncKey</fieldValue>
    </extensionField>
    <!--// term #2 new sync key-->
    <extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
        <fieldName>course/template/terms/2/NewTermSyncKey</fieldName>
        <fieldType>String</fieldType>
        <fieldValue>Term2NewTermSyncKey</fieldValue>
    </extensionField>
</extension>

Creating courses and course groups