How to create parent/child relationship using IMS ES (from June 2011)

Brief description:

You can add parent/child relationship as extension to the person object.

You will need to have site setting 'Enable parent portal' and global setting 'Parent portal' are enabled in itslearning to be able to insert/update/replace or read relationships with IMS ES.
If you trying to import parental relationships when site setting "Enable parent portal" is disabled, you will get warning message "Parent portal is disabled for the customer, a new Child relationship could not be created."

Preconditions:

You will need to know the syncID(s) of the child/children you want to add.

Events to set relationships:

IMS ES Request

createPerson
createPersons
updatePerson
updatePersons

Comments

When adding extension with relationship(s) to the request

  • new relationships will be added to the person

  • no existing relationships for the person will be deleted.

IMS ES Request

replacePersons
replacePerson

Comments

When adding extension with relationship(s) to the request

  • all existing relationship for the person will be deleted

  • releationship(s) in the request will be added

Events to get relationships

IMS ES Request

readPerson
readPersonsForGroups
readAllPerson

Comments

If person has any relationships they will be returned as part of the response.

Input parameters:

<relation> - type of relationship. Itslearning only supports type = 'Child'
<sourceId><identifier> - the syncID of the child to be inserted

Example in itslearning:

Example 1:
I want to add a person with relationship to 3 children:

  1. syncID = Child1

  2. syncID = Child2

  3. syncID = Child3.


    Result: Child3 does not exist in itslearning, only Child1 and Child2 will be created.

    Example 2:
    I want to read person with syncID = Parent0001 + all it's relationships (if any).

    Result: Parent0001 has 2 childen.

Example 1
Request to set relationship:

<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:createPersonRequest>
<ims1:sourcedId>
<ims2:identifier>999030</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>Parent0001</ims3:namePartValue>
</ims3:partName>
<ims3:partName>
<ims3:namePartType>Last</ims3:namePartType>
<ims3:namePartValue>Parent0001</ims3:namePartValue>
</ims3:partName>
<ims3:partName>
<ims3:namePartType>Nick</ims3:namePartType>
<ims3:namePartValue>Parent0001</ims3:namePartValue>
</ims3:partName>
</ims3:name>
<ims2:email>Parent0001@mail.com</ims2:email>
<ims3:userId>
<ims2:userIdValue>Parent0001</ims2:userIdValue>
<ims2:passWord>123</ims2:passWord>
</ims3:userId>
<ims3:address/>
<ims3:demographics>
<ims3:bday>1975-08-02</ims3:bday>
</ims3:demographics>
<ims3:institutionRole>
<ims3:institutionRoleType>Staff</ims3:institutionRoleType>
<ims3:primaryRoleType>true</ims3:primaryRoleType>
</ims3:institutionRole>
<ims3:tel>
<ims3:telType>Mobile</ims3:telType>
<ims3:telValue>887887</ims3:telValue>
</ims3:tel>
<ims3:tel>
<ims3:telType>Voice</ims3:telType>
<ims3:telValue>121212</ims3:telValue>
</ims3:tel>
<ims3:extension>
<ims2:relationship>
<ims2:relation>Child</ims2:relation>
<ims2:sourceId>
<ims2:identifier>Child1</ims2:identifier>
</ims2:sourceId>
</ims2:relationship>
<ims2:relationship>
<ims2:relation>Child</ims2:relation>
<ims2:sourceId>
<ims2:identifier>Child2</ims2:identifier>
</ims2:sourceId>
</ims2:relationship>
<ims2:relationship>
<ims2:relation>Child</ims2:relation>
<ims2:sourceId>
<ims2:identifier>Child3</ims2:identifier>
</ims2:sourceId>
</ims2:relationship>
</ims3:extension>
</ims1:person>
</ims1:createPersonRequest>
</soapenv:Body>
</soapenv:Envelope>

Example 1
Response:

<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>relationship:unknownidentifier</codeMinorValue>
</codeMinorField>
</codeMinor>
<messageIdRef>1234567890</messageIdRef>
<description>
<language >en-US</language>
<text> relationship/sourceId/identifier 'Child3' does not exist in itslearning </text>
</description>
</statusInfo>
</h:syncResponseHeaderInfo>
<o:Security s:mustUnderstand="1>
<u:Timestamp u:Id="_0">
<u:Created>2011-04-15T07:23:42.191Z</u:Created>
<u:Expires>2011-04-15T07:28:42.191Z</u:Expires>
</u:Timestamp>
</o:Security>
</s:Header>
<s:Body >
<createPersonResponse />
</s:Body>
</s:Envelope>

Example 1
Comments to request / response to set relationship:

If you in the <extension><relationship> have incorrect values for <relation> or if the <sourceId><identifier> does not exist in itslearning, you will have a warning in the response. Person and all correct relationship will still be created.

If you have a circular reference you will get an error saying "Parent cannot have the same synchronization key as child xxx, a new Child relationship could not be created".

Example 2:
Request to get relationship:

<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:readPersonRequest>
<ims1:sourcedId>
<ims2:identifier>Parent0001</ims2:identifier>
</ims1:sourcedId>
</ims1:readPersonRequest>
</soapenv:Body>
</soapenv:Envelope>

Example 2
Response:

<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>
<statusInfo>
<codeMajor>success</codeMajor>
<severity>status</severity>
<messageIdRef>1</messageIdRef>
</statusInfo>
</h:syncResponseHeaderInfo>
<o:Security s:mustUnderstand="1">
<u:Timestamp u:Id="_0">
<u:Created>2011-04-15T08:35:52.348Z</u:Created>
<u:Expires>2011-04-15T08:40:52.348Z</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">
<readPersonResponse>
<person>
<formatName xsi:nil="true" />
<name>
<partName>
<namePartType>First</namePartType>
<namePartValue>Parent0001</namePartValue>
</partName>
<partName>
<namePartType>Last</namePartType>
<namePartValue>Parent0001</namePartValue>
</partName>
<partName>
<namePartType>Nick</namePartType>
<namePartValue>Parent0001</namePartValue>
</partName>
</name>
<email xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0"/>
<URL xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0"/>
<userId xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManDataSchema_v1p0">
<userIdValue>parpar021</userIdValue>
</userId>
<address>
<extadd/>
<locality/>
<postcode/>
<street/>
</address>
<demographics >
<gender>Male</gender>
<bday>1975-08-02</bday>
</demographics>
<institutionRole >
<institutionRoleType>Staff</institutionRoleType>
<primaryRoleType>true</primaryRoleType>
</institutionRole>
<tel >
<telValue/>
</tel>
<tel >
<telValue/>
</tel>
<extension>
<relationship xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
<relation>Child</relation>
<sourceId>
<identifier>Child1</identifier>
</sourceId>
</relationship>
<relationship xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
<relation>Child</relation>
<sourceId>
<identifier>Child2</identifier>
</sourceId>
</relationship>
</extension>
</person>
</readPersonResponse>
</s:Body>
</s:Envelope>

Example 2
Comments to request / response to get relationship: