HelloID-Conn-Prov-Source-Topicus-Somtoday-ConnectAPI-Students-readme

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

ℹ️ Contact
Please contact your local Tools4ever sales representative for further information and details about the implementation of this connector

Table of contents

• HelloID-Conn-Prov-Source-Topicus-Somtoday-Students
  • Table of contents
  • Introduction
  • Getting started
    • Connection settings
    • Prerequisites
    • Remarks
  • Getting help
  • HelloID docs

Introduction

HelloID-Conn-Prov-Source-Topicus-Somtoday-Students is a source connector. Topicus-Somtoday-Students provides a set of REST APIs that allow you to programmatically interact with its data. The connector retrieves the students from SOMToday. Because working with students and not with employees. There is no such thing as Employments and Positions. The connector formats the "subject choice", "class group", and placements (vakkeuzes, lesgroepen, plaatsingen) to HelloId contracts. This results in three different types of HelloID objects. During implementation, there must choose between those. Or make a combination of multiple, which represents a contract in HelloID. This connector is built with active data and only example future data from a Test environment.

Getting started

Connection settings

The following settings are required to connect to the API.

Setting	Description	Mandatory
ClientID	The ClientID to connect to the API	Yes
ClientSecret	The Password to connect to the API	Yes
BaseUrl	The URL to the API	Yes
Instelling	The Name of the organization	Yes
CollectCardInfo	Collect access card Information (switch)	no
CollectSafeInfo	Collect Safe Info (switch)	no
SchoolYear	Specify the period to received students (VORIG,HUIDIG and/or VOLGEND)	No

Prerequisites

• As implementer, you need your own set of credentials before you can implement this connector. Therefore you need to sign a contract with the supplier.

Remarks

• Not each object in (Vakkeuzes) contains a UUID, which seem to be the unique ID. These (Vakkeuzes) do not have a unique id, what results in blocked contracts in HelloID. (This might be a issue of Test data in the Test environment).
• There is no calculation of the manager. Due to there being no manager relationship between students and a manager
• The "Vakkeuzes" object for each student contains a lot of data, which may be too much for processing around 3000 students and above, which results in a System.OutOfMemoryException. Therefore, if you do not require certain fields, please exclude it from the response. This can be done in the loop at row number 128. If you still require particular properties of (vakkeuzes) or a different Sub-object please use calculated property and specify only the field(s) required.

See the following Example of an exclusion:

$responseStudents = [array](Invoke-TopicusStudentsRestMethod @splatRestParams -ResultCollectionName 'Leerlingen') | Select-Object * , @{Name = 'vakkeuzesUuid'; Expression = { $_.vakkeuzes.uuid } }  -ExcludeProperty adres, plaatsingen, vestiging, lesgroepen, verzorgers, vakkeuzes

Calculated property:

Select-Object *, @{Name = 'vakkeuzesUuid'; Expression = { $_.vakkeuzes.uuid } }

• [november 2024] The connector has been extended with the options to collect access card ("toegangspas") information, and Safe ("kluis") information. These are stored as custom properties on the person. You may need to manually add these custom properties to the custom properties list of the connector in HelloID before the Personmapping can be imported. If there are more than one access card or safe number associated with a student, the result is stored as a (;-separated) text string.

The custom text properties that need to be added when using the supplied personmapping are :

• CardLocationName
• CardNumber
• CardReturned
• CardValidFrom
• CardValidUntil
• SafeLocationName
• SafeKeyNumber
• SafeKeyReturned
• SafeNumber
• SafeValidFrom
• SafeValidUntil

For more information how to add custom fields see https://docs.helloid.com/en/provisioning/persons/person-schema/add-a-custom-person-or-contract-field.html

Getting help

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

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/