Method description


replacePerson is the method used to create or replace a single person in itslearning. This is a destructive write-over of all of the original information. See more info below.

Preconditions for use

None.

Message Schema

Input parameters / request message elements

Name

Description

Data type

Allowed values

M/O

sourceId/identifier

The syncID of the person to be replaced

Text

Max 64 chars

M

person

The Person data to be stored in the new record. See docs full details on the person object

Object


M

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

Response message elements


Name

Description

Data type

replacePersonResponse

Empty response element

Empty

Comments

You must provide the request with all mandatory fields for a person, not only the fields you want to update, as the method will overwrite all of the fields that can be provided with a replacePerson request. See list below of fields that will be overwritten and fields that will be kept if the user already exists.
If the syncID does not exist in itslearning, the person with the syncId will be created instead.

Example

Description

I want to insert or update a person in itslearning - I have not kept track of whether it already exists or not.

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" xmlns:ims3="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
<soapenv:Header>
<ims:syncRequestHeaderInfo>
<ims:messageIdentifier>1234567890</ims:messageIdentifier>
</ims:syncRequestHeaderInfo>
</soapenv:Header>
<soapenv:Body>
<ims1:replacePersonRequest>
<ims1:sourcedId>
<ims2:identifier>1111</ims2:identifier>
</ims1:sourcedId>
<ims1:person>
<ims3:formatName xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
<ims3:name>
<ims3:partName>
<ims3:namePartType>First</ims3:namePartType>
<ims3:namePartValue>James</ims3:namePartValue>
</ims3:partName>
<ims3:partName>
<ims3:namePartType>Last</ims3:namePartType>
<ims3:namePartValue>Dean</ims3:namePartValue>
</ims3:partName>
<ims3:partName>
<ims3:namePartType>Nick</ims3:namePartType>
<ims3:namePartValue>jamie</ims3:namePartValue>
</ims3:partName>
</ims3:name>
<ims2:email>james@mail.com</ims2:email>
<ims3:userId>
<ims2:userIdValue>janmden</ims2:userIdValue>
<ims2:passWord>123</ims2:passWord>
</ims3:userId>
<ims3:address>
<ims3:street>First street3</ims3:street>
<ims3:street>Second street3</ims3:street>
</ims3:address>
<ims3:demographics>
<ims3:bday>1926-07-03</ims3:bday>
</ims3:demographics>
<ims3:institutionRole>
<ims3:institutionRoleType>Student</ims3:institutionRoleType>
<ims3:primaryRoleType>true</ims3:primaryRoleType>
</ims3:institutionRole>
<ims3:tel>
<ims3:telType>Mobile</ims3:telType>
<ims3:telValue>876987</ims3:telValue>
</ims3:tel>
<ims3:tel>
<ims3:telType>Voice</ims3:telType>
<ims3:telValue>12774</ims3:telValue>
</ims3:tel>
</ims1:person>
</ims1:replacePersonRequest>
</soapenv:Body>
</soapenv:Envelope>


Example response message

<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>
<messageIdentifier>1234567890</messageIdentifier>
<statusInfo>
<codeMajor>success</codeMajor>
<severity>warning</severity>
<codeMinor>
<codeMinorField>
<codeMinorName>personmanagement</codeMinorName>
<codeMinorValue>unknownobjinsertinstead</codeMinorValue>
</codeMinorField>
</codeMinor>
<messageIdRef>1234567890</messageIdRef>
<description>
<language>en-US</language>
<text>Object did not exist, has been inserted instead</text>
</description>
</statusInfo>
</h:syncResponseHeaderInfo>
<o:Security s:mustUnderstand="1">
<u:Timestamp u:Id="_0">
<u:Created>2011-02-02T14:23:09.653Z</u:Created>
<u:Expires>2011-02-02T14:28:09.653Z</u:Expires>
</u:Timestamp>
</o:Security>
</s:Header>
<s:Body>
<replacePersonResponse/>
</s:Body>
</s:Envelope>

Fields that will be overwritten

If user exists and following fields are not provided in the replacePerson request, fields will be set to 0/NULL/Empty.

  • Prefix
  • Voice
  • Mobil
  • Street[0]
  • Street[1]
  • Postcode
  • Locality
  • BDay
  • Extension fields
    • CustomString fields
    • Email account information
    • Cloud account information (cloud account will be disabled if cloud account was imported)
    • IsExternalUser
    • PrivacyProtection
    • Relationships (relationships of type 'Child' will be deleted, new relationships in the request of type 'Child' will be created. See more info about relationships: Creating parent/child relationships (itslearning.com))


NOTE: See list of mandatory fields that always needs to be provided in the createPerson/updatePerson/replacePerson request:  Managing persons (itslearning.com)

Fields that will be kept

Field that cannot be provided through the replacePerson request will be kept.

Fields like

  • Profile picture
  • Alert settings
  • Language
  • Account setting
  • Created date - Date the user was initially created