Skip to content
BranchesTags

Repository files navigation

HelloID-Conn-Prov-Target-Visma-Raet-Youserve-User

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

Introduction

HelloID-Conn-Prov-Target-Visma-Raet-Youserve-User is a target connector. Visma Raet Youserve provides a set of REST API's that allow you to programmatically interact with its data. This connector specifically manages User accounts in the Youserve IAM system.

Supported features

The following features are available:

Feature Supported Description Notes
Account Lifecycle ✅ Create, Update, Delete Delete clears mapped fields (account not removed)
Permissions ❌ - -
Resources ❌ - -
Entitlement Import: Accounts ❌ - No "get all users" endpoint available
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-Youserve-User/refs/heads/main/Icon.png

Note

You may need to create an Icon.png file in the repository root if one doesn't exist yet.

Requirements

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

  1. Youserve Developer Portal Account & Application

  2. API Credentials

    • After creating your application in the developer portal, you will receive:
      • Client ID: The API Key for your application
      • Client Secret: The Secret Key for your application
      • Tenant ID (optional): Required for multi-tenant applications
    • For authentication details, see How to connect to an API

  3. API Access

    • Ensure your application has access to the IAM User API endpoints (v3.0)
    • Contact your Youserve administrator or support if you need assistance with API access configuration

  4. Network Access

    • Ensure your HelloID environment can reach the Youserve API endpoints:
      • Authentication: https://api.youserve.nl/authentication/token
      • IAM User API (v3): https://api.youserve.nl/iam/v3.0/users
    • Note: The Youserve API enforces rate limiting of 100 requests per minute

Connection settings

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

Setting Description Mandatory
Client ID The API Key (Client ID) from your Youserve Developer portal application. Yes
Client Secret The Secret Key (Client Secret) from your Youserve Developer portal application. Yes
Tenant ID The Tenant ID to specify which Youserve tenant to connect to (sent via X-Raet-Tenant-Id header). Only required for multi-tenant applications. No
Only update on correlate When enabled, the Youserve user will only be updated when the account is correlated. No

Note

The connector uses OAuth 2.0 Client Credentials flow for authentication. The X-Client-Id header is automatically included in all API requests.

Correlation configuration

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

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

Important

Correlation only works using the personCode field. The Youserve IAM User API v3 supports querying users only by personCode or employee ID (mutkey), not by other fields.

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 User management are mapped according to your requirements.

Note

The IAM User API v3 currently supports updating only the following fields:

  • businessEmailAddress - Business email address (Element: 7212)
  • privateEmailAddress - Private email address (Element: 7213)

For complete field documentation, see the IAM User endpoint v3 documentation.

Important

businessEmailAddress cannot be cleared: The Youserve API requires the businessEmailAddress field to contain a valid email address format. Empty values or null are not accepted and will result in an API error.

Workaround for delete action: When deleting a user account, the connector generates a placeholder email address using the person's ExternalId (or current date if ExternalId is not available) combined with a designated domain (e.g., {ExternalId}@domain.com). This ensures the field is cleared of actual user data while maintaining a valid email format as required by the API. Adjust the domain in your fieldMapping.json delete mapping according to your organization's requirements.

Tip

Delete action field mapping: Configure your fieldMapping.json delete action to properly anonymize or clear sensitive data according to your organization's data retention and privacy requirements. Since the API doesn't actually delete the user record, all mapped fields should be handled appropriately.

Account Reference

The account reference is set to the personCode value used for correlation. The personCode corresponds to the "Uniek Persoonlijk ID (UPI)" field (Element 7014) in HR Core.

Important Notes:

  • The personCode is used throughout the connector lifecycle for all operations (create, update, delete)
  • When querying users via the API, you can use:
    • GET /iam/v3.0/users?personCode={personCode} - Query by personCode
    • GET /iam/v3.0/users/{id} - Query by employee mutkey (ID)
  • The personCode must match the personCode field in the Employees and Employments endpoints

Remarks

No Import Script

This connector does not include an import script because the Youserve IAM API does not provide an endpoint to retrieve all users in a single operation.

Technical Limitation:

  • The User endpoint (v3) only supports querying specific users by:
    • personCode parameter: /iam/v3.0/users?personcode={personCode}
    • Employee ID (mutkey): /iam/v3.0/users/{id}
  • There is no "list all users" or paginated users endpoint available in the IAM API v3.0

Implications:

  • Accounts cannot be pre-imported into HelloID from Youserve
  • The connector relies entirely on correlation during the create action to match existing accounts
  • Ensure your correlation configuration is properly set up to match accounts using personCode

Alternative Approach:

  • If you need to import users, consider using the Employees endpoint (/iam/v1.0/employees) from a source connector
  • The Employees endpoint supports listing all employees and includes the personCode field that can be used for correlation

No Delete

The delete script does not actually remove the User from Visma Raet Youserve. 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.

Development resources

API endpoints

The following endpoints are used by the connector scripts:

Endpoint Description Documentation
POST /authentication/token Retrieve OAuth2 access token (expires in 7199 seconds) How to connect
GET /iam/v3.0/users?personCode={personCode} Query user by personCode (used for correlation) IAM User endpoint v3
GET /iam/v3.0/users/{id} Query user by employee ID (mutkey) IAM User endpoint v3
PATCH /iam/v3.0/users?personCode={personCode} Update user by personCode IAM User endpoint v3

Request Headers:

  • Authorization: Bearer {access_token} - OAuth2 access token
  • X-Client-Id: {client_id} - Client ID for request identification
  • X-Raet-Tenant-Id: {tenant_id} - (Optional) Tenant ID for multi-tenant applications
  • Content-Type: application/json - For request payloads

Rate Limiting:

  • Maximum of 100 requests per minute
  • The connector implements a 601ms delay between requests to comply with this limit

API documentation

The official Visma Raet Youserve API documentation can be found at the following locations:

General Documentation:

IAM API Specific:

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/

About

Visma Raet Youserve - Target - User

Topics

businesshr-corehr-core-businesshrmiam-apiprovisioningraettargetvismayouserve

Resources

Readme

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Contributors

Languages