Creating parent/child relationships

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

syncID = Child1
syncID = Child2
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>[email protected]</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>