readPersons

Method description

readPersons is the method used to read one or more new persons from itslearning

Preconditions for use

You will need to know the syncIDs of the persons you want to read.

Message Schema

Input parameters / request message elements

Name	Description	Data type	Allowed values	M/O
<sourcedIdSet>	Wrapper for a list of <identifier> elements			M
<identifier>	The *syncID* of the person to be inserted	Text	Max 64 chars	M

Please refer to the WSDL for the full element structure, only key elements are described here

Response message elements

Name	Description	Data type
<personSet>	Wrapper containing a list of <person> elements
<person>	The Person data to be stored in the new record. 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 person data from persons with

syncID = 1234567 -> Does not exist in itslearning
syncID = 333222

from itslearning.

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>123495665</ims:messageIdentifier>
      </ims:syncRequestHeaderInfo>
   </soapenv:Header>
   <soapenv:Body>
      <ims1:readPersonsRequest>
         <ims1:sourcedIdSet>
            <ims2:identifier>333222</ims2:identifier>
            <ims2:identifier>1234567</ims2:identifier>
         </ims1:sourcedIdSet>
      </ims1:readPersonsRequest>
   </soapenv:Body>
</soapenv:Envelope>

Example response message

For each <sourcedIdSet><identifier> in the request you will get a status in the <statusinfoSet><status> in the response. The order of the <statusInfoset><status> corresponds to the the order of the <sourcedIdset><idendifier> in the request.

In the example below, the first <sourcedIdset><identifier> does not exist in itslearning -> <statusinfoSet><status> = failure (1). The second <sourcedIdset><idendifier> exists and data is returned successfully (2).

<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>123495665</messageIdentifier>
         <statusInfoSet>
            <statusInfo>
               <codeMajor>success</codeMajor>
               <severity>status</severity>
               <messageIdRef>123495665</messageIdRef>
            </statusInfo>
            <statusInfo>
               <codeMajor>failure</codeMajor>
               <severity>error</severity>
               <codeMinor>
                  <codeMinorField>
                     <codeMinorName>personmanagement</codeMinorName>
                     <codeMinorValue>unknownobject</codeMinorValue>
                  </codeMinorField>
               </codeMinor>
               <messageIdRef>123495665</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">The 'sourcedId' identifier is unknown in the target system</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-25T07:25:59.951Z</u:Created>
            <u:Expires>2013-07-25T07:30:59.951Z</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">
      <readPersonsResponse xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManMessSchema_v1p0">
         <personSet>
            <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>Marilyn</namePartValue>
                  </partName>
                  <partName>
                     <namePartType>Last</namePartType>
                     <namePartValue>Monroe</namePartValue>
                  </partName>
                  <partName>
                     <namePartType>Nick</namePartType>
                     <namePartValue>The Blonde Bombshell</namePartValue>
                  </partName>
               </name>
               <email xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">marilyn@mail.com</email>
               <URL xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0"/>
               <userId xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
                  <userIdValue xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">marmon</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>
                  <bday>1926-06-01</bday>
               </demographics>
               <institutionRole xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
                  <institutionRoleType>Student</institutionRoleType>
                  <primaryRoleType>true</primaryRoleType>
               </institutionRole>
               <tel xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
                  <telType>Voice</telType>
                  <telValue>55567645</telValue>
               </tel>
               <tel xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
                  <telType>Mobile</telType>
                  <telValue>7412689</telValue>
               </tel>
            </person>
         </personSet>
      </readPersonsResponse>
   </s:Body>
</s:Envelope>