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:

Example 1

Response:

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:

Example 2

Response: