replacePerson
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>
<
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