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'
  • global setting 'Parent portal'

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 and get relationships:

IMS ES Request 

Comments

  • createPerson
  • createPersons
  • updatePerson
  • updatePersons

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.

<relation> - type of relationship. Itslearning only supports type = 'Child' when creating/updating/replacing relationships
<sourceId><identifier> - the syncID of the child to be inserted

  • replacePersons
  • replacePerson

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

<relation> - type of relationship. Itslearning only supports type = 'Child'   when creating/updating/replacing relationships
<sourceId><identifier> - the syncID of the child to be inserted

  • readPerson
  • readPersons
  • readPersonsForGroups
  • readAllPerson

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

<relation> - type of relationship. Itslearning supports both type = 'Child'  and 'Parent' when reading relationships
<sourceId><identifier> - the syncID of the child / parent

Note

If child or parent does not have a synID, relationship with empty <sourceId> will be returned:

 <relationship xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
        <relation>Child</relation>
        <sourceId/>
 </relationship>


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 xmlns:h="http://www.imsglobal.org/services/common/imsMessBindSchema_v1p0"
xmlns="http://www.imsglobal.org/services/common/imsMessBindSchema_v1p0"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<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 xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">en-US</language>
<text xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
relationship/sourceId/identifier 'Child3' does not exist in itslearning</text>
</description>
</statusInfo>
</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>2019-09-03T12:29:15.844Z</u:Created>
<u:Expires>2019-09-03T12:34:15.844Z</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">
<createPersonResponse xmlns="http://www.imsglobal.org/services/pms/xsd/imsPersonManMessSchema_v1p0"/>
</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:

A person's children will be returned with <relation>Child</relation>

<extension> 
 <relationship xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
 <relation>Child</relation>
 <sourceId>
 <identifier>Student4</identifier>
 </sourceId>
 </relationship>
</extension>

A person's parents will be returned with <relation>Parent</relation>

<extension> 
 <relationship xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
 <relation>Parent</relation>
 <sourceId>
 <identifier>Parent4</identifier>
 </sourceId>
 </relationship>
</extension>