Method description
readPersonsForGroup is a method to read one or several persons who are members of a given group.
Preconditions for use
You will need to know the syncIDs of the group you want to read.
Message Schema
Input parameters / request message elements
Name | Description | Data type | Allowed values | M/O |
---|---|---|---|---|
<groupSourcedId><identifier> | The syncID of the person to be inserted | Text | Max 64 chars | M |
Response message elements
Name | Description | Data type |
---|---|---|
<personIdPairSet> | Wrapper for a list of PersonIdPair elements | |
<PersonIdPair> | Wrapper for one <sourcedid><identifier> and one <person> element | |
<sourcedid><identifier> | The SyncID of the person retrieved | Text |
<person> | The person object retrieved. Refer to Managing persons for full details on the person object | Object |
The <ExtensionField> 'IsExternalUser' will be returned with <fieldValue> 'True' in the response if the user was created externally, i.e. the user is from another site and participating in a community course.
This is in addition to the <Extension> that can be inserted/updated using create/update/replacePerson(s) (CustomString fields, email information, relationship, see description under createPerson').
Example
Description
I want to read all persons that are members of the group 'HHH':
Example request message
<
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/pms/xsd/imsPersonManMessSchema_v1p0"
xmlns:ims2
=
"http://www.imsglobal.org/services/common/imsCommonSchema_v1p0"
>
<
soapenv
:Header>
<
ims
:syncRequestHeaderInfo>
<
ims
:messageIdentifier>1</
ims
:messageIdentifier>
</
ims
:syncRequestHeaderInfo>
</
soapenv
:Header>
<
soapenv
:Body>
<
ims1
:readPersonsForGroupRequest>
<
ims1
:groupSourcedId>
<
ims2
:identifier>root</
ims2
:identifier>
</
ims1
:groupSourcedId>
</
ims1
:readPersonsForGroupRequest>
</
soapenv
:Body>
</
soapenv
:Envelope>
Example response message
In this example, some users are returned with the default profile in <institutionrole><institutionroletype> because they have profiles that are not mapped to an a valid InstitutionRoleType. Please see Managing persons for details on the mapping.
<
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>
<
h
:syncResponseHeaderInfo
xmlns:h
=
"http://www.imsglobal.org/services/common/imsMessBindSchema_v1p0"
xmlns
=
"http://www.imsglobal.org/services/common/imsMessBindSchema_v1p0"
xmlns:xsi
=
"http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd
=
"http://www.w3.org/2001/XMLSchema"
>
<
messageIdentifier
>1</
messageIdentifier
>
<
statusInfoSet
>
<
statusInfo
>
<
codeMajor
>success</
codeMajor
>
<
severity
>warning</
severity
>
<
codeMinor
>
<
codeMinorField
>
<
codeMinorName
>personmanagement</
codeMinorName
>
<
codeMinorValue
>userswithnotvalidprofiles</
codeMinorValue
>
</
codeMinorField
>
</
codeMinor
>
<
messageIdRef
>1</
messageIdRef
>
<
description
>
<
language
xmlns
=
"http://www.imsglobal.org/services/common/imsCommonSchema_v1p0"
>en-US</
language
>
<
text
xmlns
=
"http://www.imsglobal.org/services/common/imsCommonSchema_v1p0"
>Some persons related to that group are returned with default profile because they are connected to not valid profiles (deleted, not used for synchronization). Please contact administrator to solve that issue.</
text
>
</
description
>
</
statusInfo
>
</
statusInfoSet
>
</
h
:syncResponseHeaderInfo>
<
o
:Security
s:mustUnderstand
=
"1"
xmlns:o
=
"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
>
<
u
:Timestamp
u:Id
=
"_0"
>
<
u
:Created>2013-07-25T09:22:56.058Z</
u
:Created>
<
u
:Expires>2013-07-25T09:27:56.058Z</
u
:Expires>
</
u
:Timestamp>
</
o
:Security>
</
s
:Header>
<
s
:Body
xmlns:xsi
=
"http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd
=
"http://www.w3.org/2001/XMLSchema"
>
<
readPersonsForGroupResponse
xmlns
=
"http://www.imsglobal.org/services/pms/xsd/imsPersonManMessSchema_v1p0"
>
<
personIdPairSet
>
<
personIdPair
>
<
sourcedId
>
<
identifier
xmlns
=
"http://www.imsglobal.org/services/common/imsCommonSchema_v1p0"
/>
</
sourcedId
>
<
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
>Jon</
namePartValue
>
</
partName
>
<
partName
>
<
namePartType
>Last</
namePartType
>
<
namePartValue
>.</
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"
>
http://www.its-learning.com/data/demo/5155/
</
URL
>
<
userId
xmlns
=
"http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0"
>
<
userIdValue
xmlns
=
"http://www.imsglobal.org/services/common/imsCommonSchema_v1p0"
>jo.</
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
>
</
person
>
</
personIdPair
>
<
personIdPair
>
<
sourcedId
>
<
identifier
xmlns
=
"http://www.imsglobal.org/services/common/imsCommonSchema_v1p0"
/>
</
sourcedId
>
<
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
>Marian</
namePartValue
>
</
partName
>
<
partName
>
<
namePartType
>Last</
namePartType
>
<
namePartValue
>.</
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"
>
http://www.its-learning.com/data/demo/1506/
</
URL
>
<
userId
xmlns
=
"http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0"
>
<
userIdValue
xmlns
=
"http://www.imsglobal.org/services/common/imsCommonSchema_v1p0"
>ma.</
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
>Learner</
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"
>
<
extensionField
xmlns
=
"http://www.imsglobal.org/services/common/imsCommonSchema_v1p0"
>
<
fieldName
>nationalidentitynumber</
fieldName
>
<
fieldType
>String</
fieldType
>
<
fieldValue
>Organ Urbrella School</
fieldValue
>
</
extensionField
>
</
extension
>
</
person
>
</
personIdPair
>
</
personIdPair
>
</
personIdPairSet
>
</
readPersonsForGroupResponse
>
</
s
:Body>
</
s
:Envelope>