HelloID-Conn-Prov-Target-Zermelo

Important

This repository contains the connector and configuration code only. The implementer is responsible to acquire the connection details such as username, password, certificate, etc. You might even need to sign a contract or agreement with the supplier before implementing this connector. Please contact the client's application manager to coordinate the connector requirements.

Table of contents

• HelloID-Conn-Prov-Target-Zermelo
  • Table of contents
  • Introduction
  • API Documentation
  • Getting started
    • Provisioning PowerShell V2 connector
      • Correlation configuration
      • Field mapping
    • Configuration settings
    • Remarks
      • Important changes in version 1.1.0
        • Create a user (and student) account without assigning a department/school
        • School or classroom changes
      • Creating user and student accounts
      • Only the user account is managed
      • Dynamic calculation of school year
      • Setting classroom information
      • Delete user
  • Getting help
  • HelloID docs

Introduction

HelloID-Conn-Prov-Target-Zermelo is a Target connector. Zermelo is an LMS and provides a set of REST API's that allow you to programmatically interact with its data. The HelloID connector uses the API endpoints listed in the table below.

Endpoint	Description
/users	Create and manage user and student accounts
/departmentOfBranches	Retrieve information about the classroom and school year information
/studentInDepartments	Manage student departmentOfBranch information

API Documentation

The API documentation can be found on: https://support.zermelo.nl/guides/developers-api/examples/synchronizing-students#synchronizing-students_creating-students A swagger interface can be found on: https://{customer}.zportal.nl/static/swagger

Getting started

Important

The initial release of our connector, version 1.0.0, is built upon several fundamental assumptions. Make sure to verify if these assumptions apply to your environment and make changes accordingly See also: Underlying assumptions

The following lifecycle actions are available:

Action	Description
create.ps1	PowerShell create lifecycle action
delete.ps1	PowerShell delete lifecycle action
update.ps1	PowerShell update lifecycle action
configuration.json	-
fieldMapping.json	-

Provisioning PowerShell V2 connector

Correlation configuration

The correlation configuration is used to specify which properties will be used to match an existing account within Zermelo to a person in HelloID.

To properly setup the correlation:

1. Open the Correlation tab.

2. Specify the following configuration:

   Setting	Value
   Enable correlation	True
   Person correlation field	PersonContext.Person.ExternalId
   Account correlation field	code

Tip

For more information on correlation, please refer to our correlation documentation pages.

Field mapping

The field mapping can be imported by using the fieldMapping.json file.

Configuration settings

The following settings are required in order to use this connector:

Setting	Description	Mandatory	Default value
Token	The ApiToken to authorize against the Zermelo API	Yes	-
BaseUrl	The URL of the Zermelo environment	Yes	-
SchoolNameField	Mapping field name for the school or organization from the primary contract.	Yes	"Organization.Name"
ClassroomField	Mapping field name for the classroom or department from the primary contract.	Yes	"Department.DisplayName"

Remarks

Important changes in version 1.1.0

Create a user (and student) account without assigning a department/school

From version 1.1.0 its possible to create a user (and student) account without assigning a department/school. This means that; if a person within HelloID does not have a school / classRoom available, its still possible to create a Zermelo account.

To accommodate this change the following changes have been made:

• The department assignment has been moved to the update lifecycle action.
• A conditional if ($actionContext.AccountCorrelated) statement is added to the update lifecycle action that will execute directly after correlation.
  • Note that this will only assign the department and will not update the user account.
• The participationWeight field is added to the fieldMapping with a default value of 1.00. This field is used within the JSON payload to update -or assign- a 'departmentOfBranch'.

School or classroom changes

Starting from version 1.1.0, we've introduced additional logic to ensure that if either the school or classroom changes, the 'departmentOfBranch' will be updated accordingly. See also: Setting classroom information

To accommodate this change the following changes have been made:

• To update the school or classroom, a comparison is made using $personContext.PersonDifferences.PrimaryContract.
• The fields used for comparison are configurable via the configuration. Ensure these fields align with the fieldMapping.

Creating user and student accounts

According to the official documentation of the Zermelo API, the procedure for creating a user account and a student account consists of two separate steps. Initially, the user account is created using the /users endpoint. Subsequently, the student account is created using the /students endpoint. However, contrary to the information provided in the official documentation, the process appears to be slightly different, and it seems that, creating a user account through the /users endpoint, while including the attribute isStudent = true, is sufficient to create a student account.

Important

For the initial 1.0.0 release of the connector, we based our implementation on the assumption that, creating a user while including the attribute isStudent = true, is sufficient to create a student account.

Only the user account is managed

In the create lifecycle action, we have made the assumption that we only need to handle the correlation of the user account. This is because, by creating the user account with the attribute isStudent = true, we are able to -simultaneously- create the student account.

Important

Modifications to attributes associated with the student account should be made by updating the corresponding attributes in the user account. This means that, from the perspective of HelloID, only the user account is managed and considered the primary entity.

Dynamic calculation of school year

The schoolYear is calculated dynamically based on the StartDate of the primary contract.

This means that; if a student commences on the: 1st of March 2023, and the PrimaryContract.StartDate is set to the: 1st of March 2023, the current school year should be: 2022-2023.

Note

Prior to the end of July, the ongoing school year is identified as 2022/2023. Starting from the 1st of August, the current school year transitions to 2023/2024

This mechanism ensures that the SchoolYear property accurately reflects the academic period during which the student accounts are created.

Translated to PowerShell, this will appear as follows:

function Get-CurrentSchoolYear {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [DateTime]
        $StartDate
    )

    $currentDate = Get-Date
    $year = $currentDate.Year

    # Determine the start and end dates of the current school year
    if ($currentDate.Month -lt 8) {
        $startYear = $year - 1
        $endYear = $year
    } else {
        $startYear = $year
        $endYear = $year + 1
    }

    Write-Output "$startYear-$endYear"
}

Setting classroom information

Our initial 1.0.0 release of the connector is based on the following assumptions:

• The PrimaryContract.Department.DisplayName corresponds to the assigned classroom for the student.
• The PrimaryContract.Organization.Name corresponds to the name of the school.
• The PrimaryContract.StartDate represents the date when the school year is scheduled to commence.

Important

In the Netherlands, the date when the school year is scheduled to commence typically is on the 1st of August of the current year.

We have learned that, by creating the user account with the attribute isStudent = true, we are able to -simultaneously- create the student account. See also: Creating user and student accounts

Subsequently, a student account can be assigned a studentInDepartments entity, which contains information about the classroom and, by extension, the school and school year. This assignment can only be achieved by performing a lookup and matching equivalent data.

The following data is available to us in HelloID:

Name	Description	Where to find in Zermelo	Value
Person.ExternalId	Student number	/Student userCode	0000001
PrimaryContract.Department.DisplayName	Classroom	/StudentInDepartment departmentOfBranchCode	e2
PrimaryContract.StartDate	School year	/DepartmentOfBranch schoolInSchoolYearName	Tavu 2023-2024
PrimaryContract.Organization.Name	School name	/SchoolInYear schoolName	Tavu

To assign the studentInDepartment entity, the following data is required:

Attribute	Description
student	The unique identifier of the student
departmentOfBranch	The unique identifier of a DepartmentOfBranch entity
participationWeight	The portion of a student's grade based on their class involvement. This value must be a decimal and has a default value of: 1.00.

To obtain the departmentOfBranch information, it is necessary to perform a lookup in the departmentOfBranch endpoint. The matching criteria involve making the following comparisons:

• departmentOfBranchCode with the PrimaryContract.Department.DisplayName
• schoolInSchoolYearName with the PrimaryContract.StartDate and PrimaryContract.Organization.Name

For a visual representation of the relationships between the different entities, refer to the UML diagram below:

Delete user

Currently the delete lifecycle action is set to archive the user account using a PUT method.

Getting help

Tip

For more information on how to configure a HelloID PowerShell connector, please refer to our documentation pages.

Tip

If you need help, feel free to ask questions on our forum.

HelloID docs

The official HelloID documentation can be found at: https://docs.helloid.com/