changePersonsIdentifier

Method description

changePersonsIdentifier is the method used to change the syncID of several existing persons in itslearning

Preconditions for use

Make sure that the user you are trying to update has an <institutionRoleType> recognized by IMS ES. See transformation table in the general PersonManagement service description for how itslearning profiles are converted to IMS ES <institutionRoleType>.

Message Schema

Input parameters / request message elements

Name	Description	Data type	Allowed values	M/O
sourcedIdSet	Wrapper for a list of identifierPair elements			M
identifierPair	Wrapper for one <firstId> and one <secondID> element			M
identifierPair/firstId	the old *syncID* of the person to be updated	Text	Valid SyncID	M
identifierPair/secondId	the new *syncID* of the person to be updated	Text	Valid SyncID	M

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

Response message elements

Name	Description	Data type
changePersonsIdentifierResponse	Empty response element, status conveyed in SOAP header	Empty

Comments

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

Example

Description

I want to change the synchronization key / syncID of 3 persons in itslearning:

syncID 333 to 33333
syncID 666 to 66666
syncID 999 to 99999 syncID 999 does not exist in itslearning

Example request message

The following example attempts to change the IDs of person 333, 666 and 999 by adding two digits to the ID.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ims2="http://www.imsglobal.org/services/common/imsMessBindSchema_v1p0" xmlns:ims="http://www.imsglobal.org/services/pms/xsd/imsPersonManMessSchema_v1p0" xmlns:ims1="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
    <soapenv:Header>
        <ims2:syncRequestHeaderInfo>
            <ims2:messageIdentifier>1</ims2:messageIdentifier>
        </ims2:syncRequestHeaderInfo>
    </soapenv:Header>
    <soapenv:Body>
        <ims:changePersonsIdentifierRequest>
            <ims:pairSourcedIdSet>
                <ims1:identifierPair>
                    <ims1:firstId>333</ims1:firstId>
                    <ims1:secondId>33333</ims1:secondId>
                </ims1:identifierPair>
                <ims1:identifierPair>
                    <ims1:firstId>666</ims1:firstId>
                    <ims1:secondId>66666</ims1:secondId>
                </ims1:identifierPair>
                <ims1:identifierPair>
                    <ims1:firstId>999</ims1:firstId>
                    <ims1:secondId>99999</ims1:secondId>
                </ims1:identifierPair>
            </ims:pairSourcedIdSet>
        </ims:changePersonsIdentifierRequest>
    </soapenv:Body>
</soapenv:Envelope>

Example response message

In the example above, the third <identifierPair> does not exists in itslearning. Hence statusinfoSet/status> returns "Failure". The first and second <identifierPair> exist.

<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>1</messageIdentifier>
            <statusInfoSet>
                <statusInfo>
                    <codeMajor>success</codeMajor>
                    <severity>status</severity>
                    <messageIdRef>1</messageIdRef>
                </statusInfo>
                <statusInfo>
                    <codeMajor>success</codeMajor>
                    <severity>status</severity>
                    <messageIdRef>1</messageIdRef>
                </statusInfo>
                <statusInfo>
                    <codeMajor>failure</codeMajor>
                    <severity>error</severity>
                    <codeMinor>
                        <codeMinorField>
                            <codeMinorName>personmanagement</codeMinorName>
                            <codeMinorValue>unknownobject</codeMinorValue>
                        </codeMinorField>
                    </codeMinor>
                    <messageIdRef>1</messageIdRef>
                    <description>
                        <language>en-US</language>
                        <text>The 'sourcedId' identifier is unknown in the target system</text>
                    </description>
                </statusInfo>
            </statusInfoSet>
        </h:syncResponseHeaderInfo>
        <o:Security s:mustUnderstand="1">
            <u:Timestamp u:Id="_0">
                <u:Created>2011-02-01T15:54:34.094Z</u:Created>
                <u:Expires>2011-02-01T15:59:34.094Z</u:Expires>
            </u:Timestamp>
        </o:Security>
    </s:Header>
    <s:Body>
        <changePersonsIdentifierResponse/>
    </s:Body>
</s:Envelope>

Troubleshooting and error codes

Error messages

Error message	Cause	Resolution