How to create an organisation (release #40)

Brief description:

You can set and change the organisation type of a hierarchy from release #40 onwards. It is possible to create organisations with type school and it is possible to change a school to a normal hierarchy and vise versa.

Creating or updating organisations of type site is not supported.

Preconditions:

You will need to know the syncID(s) of the parent hierarchy and there can be no ancestor with organisation type school when creating or updating a school.

Events to set organisation type:

IMS ES Request

Comments

createGroup
createGroups
updateGroup
updateGroups
replaceGroup
replaceGroups


Events to get organisation type:

readGroup
readGroups
readGroupsForPerson


Input parameters:

<groupType><scheme> - always needs to be set to = ‘ItslearningOrganisationTypes

<groupType><typeValue><type> - the organisation type. This can be ‘Unspecified’, ‘Site’ or ‘School

<groupType><typeValue><level> - alternative method for setting the organisation type. This can be ‘-1’ for Unspecified, ‘0’ for Site or ‘1’for School.

Example in itslearning:

Example 1:

I want to add three hierarchies:

  1. syncID = School1 with type ‘School

  2. syncID = School2 with type ‘School

  3. syncID = Group1 with type ‘Unspecified

Result: School2 will be added to a hierarchy which belongs to another organization and will thus fail. Only School1 and Group1 will be created.


Example 2:

I want to read all the hierarchies and organization types for person with syncID = User1.

Result: User1 has 4 hierarchies:

  1. syncID = Root with type ‘Site

  2. syncID = ExistingSchool with type ‘School

  3. syncID = School2 with type ‘School

  4. syncID = Group1 with type ‘Unspecified

Example 1

Request to set organisation type:

                  1234567890                                                                        School1                                                                     ItslearningOrganisationTypes                                             School                        1                                                                              Parent                                             ExistingSchool                                                                              School 1                                                                                          School2                                                                     ItslearningOrganisationTypes                                             School                        1                                                                              Parent                                             Root                                                                              School 2                                                                                          Group1                                                                     ItslearningOrganisationTypes                                             Unspecified                        -1                                                                              Parent                                             ExistingSchool                                                                              Group 1                                                               

Example 1

Response:

                  1234567890                                    failure               error                                                      groupmanagement                     failedtocreateorupdatehierarchy                                                1234567890                                 en-US                  Schools are not allowed below another hierarchy with organisation type school                                                      success               status               1234567890                                       success               status               1234567890                                                      2012-11-22T08:21:26.564Z            2012-11-22T08:26:26.564Z                              

Example 1

Comments to request / response to set organisation type:

If creating or updating the group fails for whatever reason, an error will be returned with one of the following codeMinorValues:

  • SchoolUnderSchool ("You are trying to add a school under an existing school. A school can only be added below site.")

  • CannotCreateSite ("Only one hierarchy with organisation type site is allowed")

  • CannotChangeOrganisationType ("Hierarchy cannot be changed to organisationType {0}")

  • CannotMoveSite ("Cannot move root hierarchy")

  • CircularReferenceInHierarchy ("Circular reference detected. You cannot move a hierarchy into one of its descendents or itself." )

  • SystemFault (any other error)

N.B. Both type and level map to the same field in itslearning. It is allowed to only use one of the two or you can also specify both at the same time. If you do specify both at the same time, type and level will have to match. So if type is "School" and level is "0" an error will be returned.

Example 2:

Request to get organisation type:

                  1234567890                                       User1                  

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 xmlns:h="http://www.imsglobal.org/services/common/imsMessBindSchema_v1p0" xmlns="http://www.imsglobal.org/services/common/imsMessBindSchema_v1p0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<messageIdentifier>1234567890</messageIdentifier>
<statusInfoSet>
<statusInfo>
<codeMajor>success</codeMajor>
<severity>status</severity>
<messageIdRef>1234567890</messageIdRef>
</statusInfo>
</statusInfoSet>
</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>2012-11-22T08:25:53.457Z</u:Created>
<u:Expires>2012-11-22T08:30:53.457Z</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">
<readGroupsForPersonResponse xmlns="http://www.imsglobal.org/services/gms/xsd/imsGroupManMessSchema_v1p0">
<groupSet>
<group>
<sourcedId>
<identifier xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">Root</identifier>
</sourcedId>
<group>
<groupType xmlns="http://www.imsglobal.org/services/gms/xsd/imsGroupManDataSchema_v1p0">
<scheme>ItslearningOrganisationTypes</scheme>
<typeValue>
<type>Site</type>
<level>0</level>
</typeValue>
</groupType>
<relationship xmlns="http://www.imsglobal.org/services/gms/xsd/imsGroupManDataSchema_v1p0">
<relation>Parent</relation>
<sourceId>
<identifier xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">Root</identifier>
</sourceId>
<label>Is parent of</label>
</relationship>
<description xmlns="http://www.imsglobal.org/services/gms/xsd/imsGroupManDataSchema_v1p0">
<descShort>Root</descShort>
<descFull/>
</description>
<extension xmlns="http://www.imsglobal.org/services/gms/xsd/imsGroupManDataSchema_v1p0">
<extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
<fieldName>visibleinsearch</fieldName>
<fieldType>Boolean</fieldType>
<fieldValue>True</fieldValue>
</extensionField>
</extension>
</group>
</group>
<group>
<sourcedId>
<identifier xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">ExistingSchool</identifier>
</sourcedId>
<group>
<groupType xmlns="http://www.imsglobal.org/services/gms/xsd/imsGroupManDataSchema_v1p0">
<scheme>ItslearningOrganisationTypes</scheme>
<typeValue>
<type>School</type>
<level>1</level>
</typeValue>
</groupType>
<relationship xmlns="http://www.imsglobal.org/services/gms/xsd/imsGroupManDataSchema_v1p0">
<relation>Parent</relation>
<sourceId>
<identifier xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">Root</identifier>
</sourceId>
<label>Is parent of</label>
</relationship>
<description xmlns="http://www.imsglobal.org/services/gms/xsd/imsGroupManDataSchema_v1p0">
<descShort>Existing School</descShort>
<descFull/>
</description>
<extension xmlns="http://www.imsglobal.org/services/gms/xsd/imsGroupManDataSchema_v1p0">
<extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
<fieldName>visibleinsearch</fieldName>
<fieldType>Boolean</fieldType>
<fieldValue>True</fieldValue>
</extensionField>
</extension>
</group>
</group>
<group>
<sourcedId>
<identifier xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">School2</identifier>
</sourcedId>
<group>
<groupType xmlns="http://www.imsglobal.org/services/gms/xsd/imsGroupManDataSchema_v1p0">
<scheme>ItslearningOrganisationTypes</scheme>
<typeValue>
<type>School</type>
<level>1</level>
</typeValue>
</groupType>
<relationship xmlns="http://www.imsglobal.org/services/gms/xsd/imsGroupManDataSchema_v1p0">
<relation>Parent</relation>
<sourceId>
<identifier xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">Root</identifier>
</sourceId>
<label>Is parent of</label>
</relationship>
<description xmlns="http://www.imsglobal.org/services/gms/xsd/imsGroupManDataSchema_v1p0">
<descShort>School 2</descShort>
<descFull/>
</description>
<extension xmlns="http://www.imsglobal.org/services/gms/xsd/imsGroupManDataSchema_v1p0">
<extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
<fieldName>visibleinsearch</fieldName>
<fieldType>Boolean</fieldType>
<fieldValue>True</fieldValue>
</extensionField>
</extension>
</group>
</group>
<group>
<sourcedId>
<identifier xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">Group1</identifier>
</sourcedId>
<group>
<groupType xmlns="http://www.imsglobal.org/services/gms/xsd/imsGroupManDataSchema_v1p0">
<scheme>ItslearningOrganisationTypes</scheme>
<typeValue>
<type>Unspecified</type>
<level>-1</level>
</typeValue>
</groupType>
<relationship xmlns="http://www.imsglobal.org/services/gms/xsd/imsGroupManDataSchema_v1p0">
<relation>Parent</relation>
<sourceId>
<identifier xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">ExistingSchool</identifier>
</sourceId>
<label>Is parent of</label>
</relationship>
<description xmlns="http://www.imsglobal.org/services/gms/xsd/imsGroupManDataSchema_v1p0">
<descShort>Group 1</descShort>
<descFull/>
</description>
<extension xmlns="http://www.imsglobal.org/services/gms/xsd/imsGroupManDataSchema_v1p0">
<extensionField xmlns="http://www.imsglobal.org/services/common/imsCommonSchema_v1p0">
<fieldName>visibleinsearch</fieldName>
<fieldType>Boolean</fieldType>
<fieldValue>True</fieldValue>
</extensionField>
</extension>
</group>
</group>
</groupSet>
</readGroupsForPersonResponse>
</s:Body>
</s:Envelope>