API d’approvisionnement | Workleap Help Center

Utilisez l’API d’approvisionnement pour mettre à jour les membres, les équipes et les structures de gestion dans Workleap à l’aide d’un processus unique et sécurisé. L’API transmet des fichiers CSV à partir de votre SIRH via HTTPS afin d’automatiser les synchronisations récurrentes à l’échelle de l’organisation avec Workleap.

Préambule

Cette intégration nécessite des compétences en développement logiciel liées aux API.
Pour configurer une intégration, vous devez être administrateur Workleap.
Pour extraire les données d’engagement ou de feedback d’Officevibe, visitez api.officevibe.com.
Vous avez déjà une intégration personnalisée avec notre API héritée? Consultez ici comment mettre à jour vos fichiers de script.

Étape 1 : Activer l’API d’approvisionnement

Accédez à Paramètres > Approvisionnement.
Sélectionnez Connecter à côté de API d’approvisionnement.
Créez une clé API de gestion de l’organisation si elle n’existe pas déjà.
- Vous pouvez le faire depuis Paramètres > API ou l’écran de l’API d’approvisionnement.
Définissez un seuil de risque pour éviter les modifications indésirables à partir de fichiers CSV mal formatés.
Utilisez l’interrupteur pour activer ou désactiver l’invitation automatique afin d’inviter automatiquement les nouveaux utilisateurs.
Sélectionnez Activer l’intégration.
1. Un seul mode d’approvisionnement peut être actif à la fois.

Remarque : Vous pouvez configurer l’API d’approvisionnement sans l’activer. Si désactivée, les appels d’API de synchronisation échoueront.

Étape 2 : Configurer votre environnement

Utilisez un environnement Windows avec PowerShell pour accéder à api.workleap.com sur le port 443.
Téléchargez et extrayez provisioning.zip dans un dossier (par exemple : C:\Workleap_Sync).
Contenu des fichiers :

api-provisioning-script.ps1
SampleData/ (avec des exemples de fichiers CSV)
Modules/ (fichiers SDK PowerShell)
README.txt

Étape 3 : Préparer le script PowerShell

Exécutez api-provisioning-script.ps1 avec les paramètres obligatoires suivants :

apiKey — la clé API de l’étape 1.
membersCsvPath — chemin vers members.csv.
teamsCsvPath — chemin vers teams.csv.
teamsMappingsCsvPath — chemin vers teams-mappings.csv.

Étape 4 : Préparer les fichiers CSV

Préparez les fichiers CSV pour gérer et mettre à jour les utilisateurs, les équipes et les structures de gestion de votre organisation. À chaque synchronisation de l’API, Workleap utilise ces fichiers pour refléter la structure organisationnelle actuelle. Assurez-vous que les données sont correctement ajustées pour éviter des changements inattendus.

Attention : Vous devez enregistrer les fichiers en tant que CSV encodés en UTF-8, avec des virgules comme séparateurs et l’échappement des guillemets doubles. Tout autre format peut entraîner des erreurs de mise en forme.

Conseil : Utilisez les exemples du dossier SampleData (téléchargé à l’étape 2) pour les 3 types de fichiers suivants.

`members.csv`

Contient les données des membres.

Identifie les utilisateurs via externalMemberId.
- Utilise l’adresse courriel comme identifiant secondaire si externalMemberId ne correspond à aucun membre dans votre organisation Workleap.
Pour ajouter un membre :
- Ajoutez une ligne avec ses données.
Pour supprimer un membre :
- Supprimez la ligne correspondante.
Champs et valeurs optionnels :
- languagePreferences :
  - en
  - fr
- productAssignations :
  - Officevibe
  - Skills
  - LMS
  - Pingboard
  - Onboarding
  - Performance
  - Workleap AI
- Propriétés personnalisées :
  - Utilisez exactement les noms de propriétés configurés dans Workleap.

`teams.csv`

Crée des équipes à partir des valeurs externalTeamId et teamName.

Incluez tous les niveaux hiérarchiques (ex. : marques, unités commerciales, départements, sous-équipes).
Incluez les subordonnés directs et toute la hiérarchie.
- Ex. :
  - Petites équipes dirigées par un seul gestionnaire immédiat.
  - Grandes équipes composées de sous-équipes multiples.

`teams-mappings.csv`

Attribue les membres et gestionnaires aux équipes.

Pour assigner des membres :
Associez externalTeamId (depuis teams.csv) à externalMemberId (depuis members.csv).

Pour créer des structures de sous-équipes :
Associez externalSubteamId à externalTeamId (depuis teams.csv).

Construisez de bas en haut (commencez par les sous-équipes).
Les gestionnaires ont automatiquement accès à leurs sous-équipes.
En cas de gestionnaires multiples, les gestionnaires supérieurs voient les données de toute leur ligne hiérarchique.

Conseil : Utilisez des valeurs génériques pour externalTeamId au lieu des noms de gestionnaires pour éviter les interruptions en cas de changement.

Étape 5 : Exécuter le script

À chaque exécution du script, la synchronisation remplace la précédente.

Attention : Incluez toujours les 3 fichiers CSV. Sinon, l’opération échouera.

Effets des données manquantes

Si un membre ou une équipe de la synchronisation précédente est absent des fichiers CSV lors de l’exécution :

Membres absents de members.csv :
- S’ils étaient actifs : ils sont désactivés.
- S’ils étaient invités/créés : ils sont supprimés.
  - Exception : Les administrateurs ne sont jamais supprimés ou désactivés automatiquement.
Équipes absentes de teams.csv :
- Les équipes actives précédemment sont supprimées.

Exécution manuelle

Pour exécuter le script manuellement :

Ouvrez PowerShell dans le dossier du script.
Utilisez cette commande d’exemple :

./api-provisioning-script.ps1 -apiKey "{apiKey}" ` -membersCsvPath "./SampleData/members.csv" ` -teamsCsvPath "./SampleData/teams.csv" ` -teamsMappingsCsvPath "./SampleData/teams-mappings.csv" ` -Verbose

Ajoutez -Verbose pour afficher les informations de débogage.

Automatiser avec une tâche planifiée Windows

Programmez l’exécution automatique du script (quotidienne, hebdomadaire ou autre).

Heure recommandée : Du lundi au vendredi entre minuit et 5 h (EST), ou la fin de semaine.

Consulter l’historique des synchronisations

Pour voir l’historique des synchronisations :

Accédez à Paramètres > Approvisionnement.
Cliquez sur Voir l’historique des synchronisations.

Vous pouvez consulter la liste des synchronisations avec leur statut et leur source.

Remarque : Les synchronisations API ont toujours API d’approvisionnement comme valeur source.

Statuts de synchronisation

Voici les statuts possibles dans la page de l’historique :

En attente — La synchronisation est en cours.
En pause — Le seuil de risque a été dépassé. Approuvez ou rejetez les changements.
Rejetée — La synchronisation en pause a été rejetée.
Succès — La synchronisation s’est complétée (peut avoir été en pause).
Avertissement — Succès partiel; consultez le rapport pour les problèmes (doublons, etc.).
Échec — La synchronisation n’a pas été exécutée.

Besoin d’aide?

Consultez notre FAQ sur l’API d’approvisionnement pour des conseils de dépannage et des cas d’usage avancés.

Communiquez avec notre équipe de soutien à support@workleap.com pour une assistance personnalisée.