HelloID-Conn-Prov-Target-Visma-Raet-Youforce-Person-Extensions

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-Visma-Raet-Youforce-Person-Extensions
  • Table of contents
  • Introduction
  • Supported features
  • Getting started
    • HelloID Icon URL
    • Requirements
    • Connection settings
    • Correlation configuration
    • Field mapping
    • Account Reference
  • Remarks
    • No Delete
  • Development resources
    • API endpoints
    • API documentation
  • Getting help
  • HelloID docs

Introduction

HelloID-Conn-Prov-Target-Visma-Raet-Youforce-Person-Extensions is a target connector. Visma-Raet-Youforce-Person-Extensions provides a set of REST API's that allow you to programmatically interact with its data.

Supported features

The following features are available:

Feature	Supported	Actions	Remarks
Account Lifecycle	✅	Create, Update, Delete	Delete uses "-" (empty values not supported)
Permissions	❌
Resources	❌	-
Entitlement Import: Accounts	✅	Import	Imports persons with extension data
Entitlement Import: Permissions	❌	-
Governance Reconciliation Resolutions	✅	Delete (skip)	Delete not supported with reconciliation

Getting started

HelloID Icon URL

URL of the icon used for the HelloID Provisioning target system.

https://raw.githubusercontent.com/Tools4everBV/HelloID-Conn-Prov-Target-Visma-Raet-Youforce-Person-Extensions/refs/heads/main/Icon.png

Requirements

To use this connector, you must meet all of the following requirements:

1. Visma Developer Portal Account & App Registration

• You must have an authorized Visma Developers account. Register and log in at the Visma Developer portal.
• Create a new App in the portal. Follow the Visma documentation for step-by-step instructions.
• After creating the App, link it to your client (organization) and accept the invitation if required.

2. API Credentials

• Obtain the following credentials from the Visma Developer portal after App registration and client linking:
  • clientId: The Client ID for API authentication
  • clientSecret: The Client Secret for API authentication
  • tenantId: The Tenant ID for your Visma Raet environment

3. Required Scopes

• The following scopes must be enabled and assigned to your App in the Visma Developer portal:
  • Youforce-IAM:Get_Basic
  • Youforce-Extensions:Get_Basic
  • Youforce-Extensions:Write_Data
• If you need help setting up scopes, consult your Visma contact.

4. Youforce Import Process Configuration

• Mutations are submitted to Youforce through the API using the fixed process codes IDA and XGA.
• The application administrator must configure the import process in Youforce:
  • Navigate to the configuration import process screen in Youforce.
  • For process code IDA, ensure the options Auto Import and Auto verwerken (automatic processing) are checked (the green checkboxes). See the screenshot below for reference.
  • The same configuration must also be applied for process code XGA.
• This step is essential for the connector to function correctly and for mutations to be handled without manual intervention.

Connection settings

The following settings are required to connect to the API (see configuration.json):

Setting	Description	Mandatory
Client ID	The Client ID to connect with the IAM API (created when registering the App in in the Visma Developer portal).	Yes
Client Secret	The Client Secret to connect with the IAM API (created when registering the App in in the Visma Developer portal).	Yes
Tenant ID	The Tenant ID to specify to which Raet tenant to connect with the IAM API (available in the Visma Developer portal after the invitation code has been accepted).	Yes
Only update on correlate	When enabled, the Raet Youforce employee will only be updated when the account is correlated	No

Correlation configuration

The correlation configuration is used to specify which properties will be used to match an existing account within Visma-Raet-Youforce-Person-Extensions to a person in HelloID.

Setting	Value
Enable correlation	True
Person correlation field	ExternalId
Account correlation field	personCode

Tip

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

Field mapping

Field mapping is managed via the fieldMapping.json file. Ensure all required fields for Person Extensions are mapped. Some fields may have specific requirements depending on your use case. See the file for examples and mapping logic.

Important

Delete action field mapping: The Visma Raet Youforce API does not support setting person extension fields to empty/null values. When mapping fields for the delete action, you must use the fixed value "-" (a single dash) instead of an empty string. This ensures that the fields are cleared according to API requirements. All person extension fields mapped for the delete action should use "-" as their value.

Account Reference

The account reference is typically set to the unique identifier (personCode) returned by the API after account creation or correlation.

Remarks

No Delete

The delete script does not actually remove the Person in Visma Raet Youforce. Instead, the script will update the mapped fields according to your fieldMapping configuration.

During reconciliation:
Delete operations are not supported during reconciliation. When reconciliation tries to delete an account, the connector will skip the delete and log that delete is not supported with reconciliation.

Best practice:
Configure your fieldMapping for the delete action so that all sensitive or identifying fields are set to "-" (a single dash) when an account is deleted in HelloID. Since the API does not support empty values, using "-" as the fixed value ensures that no personal data remains in the target system, and the account is effectively anonymized according to your compliance requirements.

Development resources

API endpoints

The following endpoints are used by the connector scripts:

Endpoint	Description
POST /connect/token	Retrieve access token
GET /iam/v1.0/persons	List all persons (for import)
GET /iam/v1.0/persons/{personCode}	Get person details
GET /extensions/v1.0/iam/persons/{personCode} {extension}	Get person extension
PATCH /extensions/v1.0/iam/persons/{personCode}	Update person extension

API documentation

Consult the official Visma Raet Youforce API documentation for details on endpoints and data structures.

Swagger UI

Getting help

Tip

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

HelloID docs

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