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.
- HelloID-Conn-Prov-Target-StudyTube
HelloID-Conn-Prov-Target-StudyTube is a target connector. StudyTube 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 |
|---|---|
| /api/v2/users | User related actions |
| /api/v2/academy-teams | Permission related actions |
| /gateway/oauth/token | Authentication |
The API documentation can be found on: https://public-api.studytube.nl/api/v2/docs#/
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 |
| \permissions\teams\grantPermission.ps1 | PowerShell grant lifecycle action |
| \permissions\teams\revokePermission.ps1 | PowerShell revoke lifecycle action |
| \permissions\teams\subPermissions.ps1 | PowerShell All-in-one lifecycle action |
| \permissions\teams\permissions.ps1 | PowerShell permissions lifecycle action |
| configuration.json | Default configuration.json |
| fieldMapping.json | Default fieldMapping.json |
| \resources\teams\create\resources.ps1 | Creates teams within StudyTube |
| \resources\teams\retrieve\resources.ps1 | Exports all active teams to a CSV file |
| \resources\user\resources.ps1 | Exports all users to a CSV file |
The correlation configuration is used to specify which properties will be used to match an existing account within StudyTube to a person in HelloID.
To properly setup the correlation:
-
Open the
Correlationtab. -
Specify the following configuration:
Setting Value Enable correlation TruePerson correlation field PersonContext.Person.ExternalIdAccount correlation field UID
Tip
For more information on correlation, please refer to our correlation documentation pages.
The field mapping can be imported by using the fieldMapping.json file.
The following settings are required to connect to the API.
| Setting | Description | Mandatory |
|---|---|---|
| ClientId | The ClientId to connect to StudyTube. | Yes |
| ClientSecret | The ClientSecret to connect to StudyTube. | Yes |
| BaseUrl | The URL to the StudyTube API. | Yes |
| TokenUrl | The URL to StudyTube for retrieving the accessToken. | Yes |
| ResourcePageSize | The number of records returned in a single request. The default value is 150. Can be increased when facing issues related to making too many requests. |
Yes |
| UsersCsvExportFileAndPath | Specifies the name and file path where the CSV teams export will be saved. | Yes |
| TeamsCsvExportFileAndPath | Specifies the name and file path where the CSV users export will be saved. | Yes |
- The HelloID on-premises agent must be installed.
Caution
Version 2.0.0 of the connector introduces significant changes and is no longer backwards compatible with previous versions. This update requires the use of the new resource scripts for teams and users, and older configurations require adjustments to function correctly with the latest updates.
The StudyTube API does not allow users to be retrieved based on employee_number or externalId. They can only be retrieved using their id. The only workaround is to retrieve all users within the create lifecyle action. However, since this is not considered a best practice and because StudyTube itself has an API throttle limit of 90 requests per minute, the connector uses a resources script to retrieve all users and export them to a CSV file. Within the create lifecycle action, this CSV is used to validate whether the user account exists.
The resource scripts to retrieve users and teams require pagination. The default page size is set to: 150. If you encounter problems with to many request, try a higher value, for example: 200, the maximum value is: 1000.
Tip
You can configure the pagesize for both resource scripts using the configuration setting: ResourcePageSize.
This connector allows for the assignment of academy-teams through separate grant/revoke/permissions lifecycle actions.
If a property in the person contract is directly linked to an academy team in StudyTube, you can use the _subPermissions_ script to assign permissions dynamically.
Because retrieving teams could result in too many requests being made, a separate resource script is provided to retrieve all teams and export them to a CSV.
If you use the _subPermissions_ script, this CSV file will be searched to look up the team name and ensure it matches a property from the person contract.
If you're using the separate grant/revoke scripts and still encounter the "too many requests" issue, you might also need the _/resources/teams/retrieve/resources.ps1_ to retrieve teams. In that case, the _permissions_ script will need to be modified to import teams from the CSV file.
If a property in the person contract is directly linked to an academy team in StudyTube, you can use the _/resources/teams/create/resources.ps1_ script to create teams within StudyTube. Additionally, archived teams will be unarchived.
Creating a new user with an email address that already exists will update the existing user instead of adding a new one. To avoid this issue, a validation step has been implemented to confirm the uniqueness of the email address. If the email is not unique, the create lifecycle action will return an error.
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.
The official HelloID documentation can be found at: https://docs.helloid.com/