{"id":19504488,"url":"https://github.com/tools4everbv/helloid-conn-prov-target-facilitor","last_synced_at":"2025-06-23T03:44:12.798Z","repository":{"id":239586553,"uuid":"799949962","full_name":"Tools4everBV/HelloID-Conn-Prov-Target-Facilitor","owner":"Tools4everBV","description":null,"archived":false,"fork":false,"pushed_at":"2024-07-29T09:35:19.000Z","size":137,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-01-08T10:44:48.504Z","etag":null,"topics":["fmis"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tools4everBV.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-13T12:19:01.000Z","updated_at":"2024-07-29T09:35:22.000Z","dependencies_parsed_at":"2024-06-03T14:20:49.498Z","dependency_job_id":"88d052d4-d153-4f94-bbf4-246550d4faba","html_url":"https://github.com/Tools4everBV/HelloID-Conn-Prov-Target-Facilitor","commit_stats":null,"previous_names":["tools4everbv/helloid-conn-prov-target-facilitor"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tools4everBV%2FHelloID-Conn-Prov-Target-Facilitor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tools4everBV%2FHelloID-Conn-Prov-Target-Facilitor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tools4everBV%2FHelloID-Conn-Prov-Target-Facilitor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tools4everBV%2FHelloID-Conn-Prov-Target-Facilitor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tools4everBV","download_url":"https://codeload.github.com/Tools4everBV/HelloID-Conn-Prov-Target-Facilitor/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240754371,"owners_count":19852189,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fmis"],"created_at":"2024-11-10T22:25:59.138Z","updated_at":"2025-02-25T22:11:08.932Z","avatar_url":"https://github.com/Tools4everBV.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HelloID-Conn-Prov-Target-Facilitor\n\n\u003e [!IMPORTANT]\n\u003e 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.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/Tools4everBV/HelloID-Conn-Prov-Target-Facilitor/blob/main/Logo.png?raw=true\"\u003e\n\u003c/p\u003e\n\n## Table of contents\n\n- [HelloID-Conn-Prov-Target-Facilitor](#helloid-conn-prov-target-facilitor)\n  - [Table of contents](#table-of-contents)\n  - [Introduction](#introduction)\n  - [Getting started](#getting-started)\n    - [Functional description](#functional-description)\n    - [Connection settings](#connection-settings)\n    - [Field mapping](#field-mapping)\n      - [Correlation configuration](#correlation-configuration)\n    - [Remarks](#remarks)\n      - [Concurrent actions](#concurrent-actions)\n      - [Custom field](#custom-field)\n      - [Cost centre, department and location](#cost-centre-department-and-location)\n      - [Functions](#functions)\n      - [Enable / Disable](#enable--disable)\n      - [Updating using a _HTTP.PUT_](#updating-using-a-httpput)\n  - [Getting help](#getting-help)\n  - [HelloID docs](#helloid-docs)\n\n## Introduction\n\n_HelloID-Conn-Prov-Target-Facilitor_ is a target connector. _Facilitor_ provides a set of REST APIs that allow you to programmatically interact with its data. The HelloID connector uses the API endpoints listed in the table below.\n\n| Endpoint             | Description                                                                |\n| -------------------- | -------------------------------------------------------------------------- |\n| /persons             | `GET / POST` actions to read and write the user in Facilitor               |\n| /authorizationgroups | `GET` actions to read authorization groups from Facilitor                  |\n| /costcentres         | `GET` actions to read cost centers from Facilitor                          |\n| /departments         | `GET` actions to read departments from Facilitor                           |\n| /locations           | `GET` actions to read locations from Facilitor                             |\n| /employeefunctions   | `GET / POST` actions to read and write the employee functions in Facilitor |\n\nThe following lifecycle events are available:\n\n| Event                                   | Description                                                     |\n| --------------------------------------- | --------------------------------------------------------------- |\n| create.ps1                              | Create and/or correlate the Account                             |\n| update.ps1                              | Update the Account                                              |\n| enable.ps1                              | Enable the Account                                              |\n| disable.ps1                             | Disable the Account                                             |\n| delete.ps1                              | Only disables the account. Deleting an account is not supported |\n| permissions/groups/permissions.ps1      | Retrieve the permissions                                        |\n| permissions/groups/grantPermission.ps1  | Grant permission                                                |\n| permissions/groups/revokePermission.ps1 | Revoke permission                                               |\n| resources/functions/resource.ps1        | create function resources                                       |\n| configuration.json                      | Default _configuration.json_                                    |\n| fieldMapping.json                       | Default _fieldMapping.json_                                     |\n\n## Getting started\n\n### Functional description\n\nThe purpose of this connector is to _manage user account provisioning_ within Facilitor.\n\nIn addition, the connector manages permissions\n\n### Connection settings\n\nThe following settings are required to connect to the API.\n\n| Setting | Description                        | Mandatory |\n| ------- | ---------------------------------- | --------- |\n| APIKey  | The _APIKey_ to connect to the API | Yes       |\n| BaseUrl | The URL to the API                 | Yes       |\n\n### Field mapping\n\nThe field mapping can be imported by using the [_fieldMapping.json_](./fieldMapping.json) file.\n\n#### Correlation configuration\n\nThe correlation configuration is used to specify which properties will be used to match an existing account within _Facilitor_ to a person in _HelloID_.\n\nTo properly set up the correlation:\n\n1. Open the `Correlation` tab.\n\n2. Specify the following configuration:\n\n | Setting                   | Value               |\n | ------------------------- | ------------------- |\n | Enable correlation        | `True`              |\n | Person correlation field  | `Person.ExternalId` |\n | Account correlation field | `employeeNumber`    |\n\n\u003e [!TIP]\n\u003e _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_.\n\n### Remarks\n\n#### Concurrent actions\n\n\u003e [!IMPORTANT]\n\u003e Granting and revoking groups is done by editing Facilitor persons after receiving the groups. For this reason, the concurrent actions need to be set to `1`.\n\n#### Custom field\n\nThe connector uses a custom field for populating the location field, the custom field used for this is identified by the ID `1060` and labeled `Locatie ID`. This is because the existing location field for the person corresponds to the preferred location of that person, not the location where the person works. Facilitor uses a daily running script that reads the custom field to fill the location where the person works.\n\n\u003e [!IMPORTANT]\n\u003e `custom_fields` are mapped in the powershell `create.ps1` and `update.ps1` script. Make sure you get the right `propertyid` from Facilitor. In the current script `1060` is used.\n\n#### Cost centre, department and location\n\nThe field mapping contains a mapping object where the cost centre, department and location are populated with either the ID or the name of the corresponding object in the primary contract. This mapping object is used in the create and update lifecycle for validation.\n\nThe validation process works as follows: the value from the mapping object is looked up in Faciltor and retrieves the corresponding ID of the object in Facilitor. By default on `name` or `visitzipcode`. If something goes wrong during validation, the connector will return a validation error. You can edit the `SearchProperty` in the  `create.ps1` and `update.ps1` script. Example:\n\n```Powershell\n$splatGetDepartments = @{\n    Url = \"$($actionContext.Configuration.BaseUrl)/api2/departments?name=$($actionContext.Data.mapping.departmentId)\"\n    Property = 'departments'\n    PropertyId = $actionContext.Data.mapping.departmentId\n    SearchProperty = 'name'\n}\n```\n\n\u003e [!TIP]\n\u003e Optionally you can use a .csv file and retrieve the corresponding IDs. Please check out the [_examples folder_](./examples) to get you started\n\n#### Functions\nThe resource script creates all the values needed for the function field. The functions are mapped by name but must exist in Facilitor.\n\n#### Enable / Disable\n\nBoth the _enable_ and _disable_ lifecycle actions, will set the `deactivated` property. The value of this property is a `[DateTime]` string in the format: `yyyy-MM-ddTHH:mm:ssZ`.\n\n- ℹ️ Within the _disable_ lifecycle action, the value will be set to the current date.\n\n\u003e [!IMPORTANT]\n\u003e The `enable.ps1` and `disable.ps1` are only needed if Facilitor doesn't delete the person when `deactivated` is filled. If used please also test if `deactivated` is overridden when updating the account. This could still be a problem in Facilitor.\n\n#### Updating using a _HTTP.PUT_\n\nUpdating the account is based on a _HTTP.PUT_. A partial _PUT_ is supported within _Facilitor_. Meaning; that only the properties that have changed will be updated.\n\n## Getting help\n\n\u003e ℹ️ _For more information on how to configure a HelloID PowerShell V2 connector, please refer to our [documentation](https://docs.helloid.com/en/provisioning/target-systems/powershell-v2-target-systems.html) pages_\n\n\u003e ℹ️ _If you need help, feel free to ask questions on our [forum](https://forum.helloid.com)_\n\n## HelloID docs\n\nThe official HelloID documentation can be found at: https://docs.helloid.com/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftools4everbv%2Fhelloid-conn-prov-target-facilitor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftools4everbv%2Fhelloid-conn-prov-target-facilitor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftools4everbv%2Fhelloid-conn-prov-target-facilitor/lists"}