https://github.com/tools4everbv/helloid-conn-prov-target-canvas
HelloID-Conn-Prov-Target-Canvas
https://github.com/tools4everbv/helloid-conn-prov-target-canvas
edu lms provisioning target
Last synced: 4 months ago
JSON representation
HelloID-Conn-Prov-Target-Canvas
- Host: GitHub
- URL: https://github.com/tools4everbv/helloid-conn-prov-target-canvas
- Owner: Tools4everBV
- Created: 2022-07-21T08:42:34.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-04-04T10:09:04.000Z (7 months ago)
- Last Synced: 2025-04-04T11:23:15.473Z (7 months ago)
- Topics: edu, lms, provisioning, target
- Language: PowerShell
- Homepage:
- Size: 277 KB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# HelloID-Conn-Prov-Target-Canvas
> [!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-Canvas](#helloid-conn-prov-target-Canvas)
- [Table of contents](#table-of-contents)
- [Introduction](#introduction)
- [Getting started](#getting-started)
- [Prerequisites](#prerequisites)
- [Connection settings](#connection-settings)
- [Correlation configuration](#correlation-configuration)
- [Available lifecycle actions](#available-lifecycle-actions)
- [Field mapping](#field-mapping)
- [Remarks](#remarks)
- [Development resources](#development-resources)
- [API endpoints](#api-endpoints)
- [API documentation](#api-documentation)
- [Getting help](#getting-help)
- [HelloID docs](#helloid-docs)
## Introduction
_HelloID-Conn-Prov-Target-Canvas_ is a _target_ connector. _Canvas_ provides a set of REST API's that allow you to programmatically interact with its data.
## Getting started
### Prerequisites
- An Access Token to connect to the API
- Obtain the AccountId of the customer. You can use the following code.
```Powershell
$accessToken = ''
$baseUrl = '' # Example 'https://tools.test.instructure.com/'
$headers = New-Object 'System.Collections.Generic.Dictionary[[String],[String]]'
$headers.Add('Authorization', "Bearer $accessToken")
$response = Invoke-RestMethod "$baseUrl/api/v1/accounts" -Method 'GET' -Headers $headers
$response | ConvertTo-Json
```
### Connection settings
The following settings are required to connect to the API.
| Setting | Description | Mandatory |
| ------------ | ----------- | ----------- |
| Access Token | The Access Token to connect to the API | Yes |
| BaseUrl | The URL to the API | Yes |
| AccountId | The AccountId under which the user objects are created (Id of the company) | Yes |
### Correlation configuration
The correlation configuration is used to specify which properties will be used to match an existing account within _Canvas_ to a person in _HelloID_.
| Setting | Value |
| ------------------------- | --------------------------------- |
| Enable correlation | `True` |
| Person correlation field | `Accounts.MicrosoftActiveDirectory.mail` |
| Account correlation field | `email` |
> [!TIP]
> _For more information on correlation, please refer to our correlation [documentation](https://docs.helloid.com/en/provisioning/target-systems/powershell-v2-target-systems/correlation.html) pages_.
### Available lifecycle actions
The following lifecycle actions are available:
| Action | Description |
| --------------------------------------- | ------------------------------------------------------------------------------------------- |
| create.ps1 | Creates a new account. |
| delete.ps1 | Removes an existing user account or entity from the customer account. |
| disable.ps1 | Disables an account, preventing access without permanent removal. |
| enable.ps1 | Enables an account, granting access. |
| update.ps1 | Updates the attributes of an account. |
| configuration.json | Contains the connection settings and general configuration for the connector. |
| fieldMapping.json | Defines mappings between person fields and target system person account fields. |
### Field mapping
The field mapping can be imported by using the _fieldMapping.json_ file.
## Remarks
- > The delete process might lead to some unexpected behavior.
Please verify the delete process. So it matches the customer's requirements. This because we create users to an Account (company), but the action Delete User, removes the user from that Account, but it is still accessible from the user endpoint. It behaves like a Disable action.
- The user object used in the update has fewer properties than the original user object that is created. Therefore, the account object in the `Create.ps1` differs from the one in `Update.ps1`.
## Development resources
### API endpoints
The following endpoints are used by the connector
| Endpoint | Description |
| -------- | ------------------------- |
| /api/v1/accounts[/]/users[/] | The endpoints for all user related actions |
|
### API documentation
## Getting help
> [!TIP]
> _For more information on how to configure a HelloID PowerShell connector, please refer to our [documentation](https://docs.helloid.com/en/provisioning/target-systems/powershell-v2-target-systems.html) pages_.
> [!TIP]
> _If you need help, feel free to ask questions on our [forum](https://forum.helloid.com)_.
## HelloID docs
The official HelloID documentation can be found at: https://docs.helloid.com/