Managing memberships

URL to service

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

This service contains the following functions:

createMembership
createMemberships
updateMembership
updateMemberships
deleteMembership
deleteMemberships
replaceMembership
replaceMemberships
changeMembershipIdentifier
changeMembershipsIdentifier
readMembership
readMemberships
readMembershipsForPerson
readMembershipsForGroup

WSDL file for MembershipManagement
https://enterprise.itslearning.com/WCFServiceLibrary/MembershipManagementServiceSync.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/imsmembership_bindv1p0.html
http://www.imsglobal.org/es/esv1p0/imsmembership_infov1p0.html

The membership object

IMS ES Field	Mandatory	Itslearning field	Comment
SourcedId/Identifier	X	Person_Hierarchy.SyncPersonHierarchyId	*SyncID*
groupSourcedId/Identifier	X	Group.SyncLocationId
memberSourcedId/Identifier	X	Person.SyncLocatinId
Role	X	PersonProfile	Role in hierarchy. See transformation table below
Extensions ExtensionField			Allows you to mark an organisation as home organisation.

Extensions

The below example describes the usage of extensions for memberships to set "HomeOrganisation" for a group of users.

Please see Marking an organisation as a user's "home organisation" for further details.

<ims3:member>
   <ims3:memberSourcedId>
      <ims2:identifier>99998888</ims2:identifier>
   </ims3:memberSourcedId>
   <ims3:role>
      <ims3:roleType>01</ims3:roleType>
      <extension>
         <extensionField>
            <fieldName>HomeOrganisation</fieldName>
            <fieldType>bool</fieldType>
            <fieldValue>1</fieldValue>
         </extensionField>
      </extension>
   </ims3:role>
</ims3:member>

Transformation of IMS ES RoleTypes into itslearning hierarchy roles

The following transformation table is used to convert IMS ES <role> type into Itslearning role in hierarchy.

We recommend you use only those roles highlighted in either numeric or literal form.

IMS ES RoleType	IMS ES Numeric value	itslearning Role in hierarchy
Learner	01	Student
Instructor	02	Teacher
ContentDeveloper	03	Guest
Member	04	Guest
Manager	05	Guest
Mentor	06	¹
Administrator	07	Administrator
TeachingAssistant	08	Guest

¹ See section Mentor role below

Mentor role in itslearning

Having a Mentor role in a hierarchy is not a normal membership in a hierarchy, but a functionality added on top of that.

This means that a user can have membership to a hierarchy (with e.g. role = Teacher), but in addition have a Mentor role in the same hierarchy.

How to give a user Mentor role with IMS ES

To give a user Mentor role in a hierarchy is done the same way as adding a membership to a user, see CreateMembership request example:

CreateMembership request to give 'UserX' Mentor role in hierarchy 'SchoolA'

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ims="http://www.imsglobal.org/services/common/imsMessBindSchema_v1p0" xmlns:ims1="http://www.imsglobal.org/services/mms/xsd/imsMemberManMessSchema_v1p0" xmlns:ims2="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0" xmlns:ims3="http://www.imsglobal.org/services/mms/xsd/imsMemberManDataSchema_v1p0">
  <soapenv:Header>
    <ims:syncRequestHeaderInfo>
      <ims:messageIdentifier>1</ims:messageIdentifier>
    </ims:syncRequestHeaderInfo>
  </soapenv:Header>
  <soapenv:Body>
    <ims1:createMembershipRequest>
      <ims1:sourcedId>
        <ims2:identifier>SchoolA_UserX</ims2:identifier>
      </ims1:sourcedId>
      <ims1:membership>
        <ims3:groupSourcedId>
          <ims2:identifier>SchoolA</ims2:identifier>
        </ims3:groupSourcedId>
        <ims3:member>
          <ims3:memberSourcedId>
            <ims2:identifier>UserX</ims2:identifier>
          </ims3:memberSourcedId>
          <ims3:role>
            <ims3:roleType>Mentor</ims3:roleType>
          </ims3:role>
        </ims3:member>
      </ims1:membership>
    </ims1:createMembershipRequest>
  </soapenv:Body>
</soapenv:Envelope>

This request will only give UserX Mentor role in hierarchy SchoolA. It will not give UserX any membership to hierarchy SchoolA.

With IMS ES, it is possible to give a user Mentor role in a hierarchy, even if the user does not have a membership to the same hierarchy.

How to see a user's role in itslearning

As an administrator, you can see a user's memberships and role in hierarchies if you go to Admin - User and Access rights - choose Edit for a user and then select the Hierarchy tab:

Note: Here you will not see a user's Mentor role

As an administrator, you can see a user's Mentor role if you go to Admin - Supervisor:

As a user, if you have a Mentor role in a hierarchy, you will have a new tab named Mentor:

You cannot change a user's Mentor role in hierarchy to be a normal membership in the same hierarchy.

Example:

User is Mentor in School A.
User should not longer be Mentor in School A
User should be teacher in School A

You will have to - first remove the user's Mentor role in School A - then add the user's membership to School A