readPersonsForGroup

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>