Approvisionnement via API
Qu’est-ce que l'approvisionnement de membres ?
On appelle approvisionnement l’action de créer des comptes utilisateurs dans Steeple. La création d’un compte utilisateur est systématiquement associée à au moins une communauté, l’utilisateur devient donc un membre invité dans une communauté.
L’approvisionnement peut être manuel, unitairement depuis l’administration ou en groupe par import manuel de fichier. Il peut également être automatisé avec des synchronisations basées sur le protocole SCIM ou par import automatique de fichiers via API.
Important : la création des utilisateurs par l’API d’import de fichiers permet de créer des utilisateurs et de les associer à des communautés. En revanche, aucune invitation n’est envoyée aux utilisateurs créés à l’issue du traitement. Les utilisateurs sont créés dans Steeple et les invitations associées sont en attente d’envoi. Seule une action manuelle de l’administrateur de la communauté peut déclencher les invitations.
Intégrer un fichier de membres
Pourquoi un fichier de membres ?
L’import des membres par fichier est une fonctionnalité éprouvée dans Steeple, elle permet un formalisme standardisé dans les données nécessaires à la création de membres dans les communautés. C’est un moyen simple d’automatiser une tâche récurrente manuelle par API sans revoir complètement les contrats d’interfaces et les données échangées. Une fois un premier fichier de membres constitué et validé par un import manuel, le passage par l’automatisation via API est grandement facilité.
Comment construire un fichier de membres ?
Avec un rôle Administrateur, depuis l’interface d’administration de la communauté, la fonctionner d’import de fichier est disponible sur l’écran de gestion des membres :
En choisissant un mode d’import, vous rendrez accessible un modèle de document vide utilisable pour importer les membres de vos communautés.
Information à propos des modes :
Miroir : Dans ce mode, le fichier importé fait foi. L’opération d’import créera tous les membres présents dans le fichier et absents de vos communautés. Elle mettra à jour les informations des membres présents à la fois dans le fichier et dans vos communautés. L’API propose deux opérations répondant à ce mode :
- MIRROR_LENIENT : avec cette opération, Steeple tiendra compte des lignes présentes dans le fichier pour réaliser les créations et les modifications (y compris suppression d’affectation à une communauté) et ne réalisera aucune opération pour tous les autres membres absents du fichier.
- MIRROR_STRICT : avec cette opération, Steeple tiendra compte de tout le fichier. Tous membres présents dans l’organisation et absents du fichier sera simplement supprimé de l’organisation. Les autres membres, présent dans le fichier, seront créés ou mis à jour pour se conformer au fichier.
Insertion : Dans ce mode, l’opération d’import n’effectue aucune suppression. Elle se charge d’ajouter les nouveaux membres et de mettre à jour les membres existants, si besoin. Deux opérations distinctes :
- INSERT : Steeple n’opère que les création de membre et ignore toutes les modifications
- UPSERT : Steeple opère à la fois les créations et les mises à jour. Les suppressions d’affectation à une communauté sont ignorées.
Suppression : Dans ce mode, tous les membres du fichier sont supprimés de vos communautés. Aucun ajout ni aucune modification ne sera effectuée. Une seule opération pour ce mode via API :
- DELETE: Steeple opère la suppression de tous les membres présents dans le fichier .
Pour plus de détails sur l’import de fichier, consultez la FAQ.
Comment traiter un fichier de membres ?
Le traitement d’un fichier de membres passe par 4 étapes :
- Import du fichier sur l’espace de stockage temporaire Steeple
- Démarrage du traitement d’import des membres
- Suivi régulier du traitement d’import
- Récupération du rapport de traitement du fichier
- Récupération des messages d’avertissement et d’erreurs
Transférer le fichier
Préparer un transfert de fichier
Préparer le transfert un fichier d’import sur Steeple avec : (GET) /blob
Requête :
|
curl 'https://api.steeple.com/v1/blobs?user_id=895ef75e-b7bf-4e18-a145-xxx4a2a24e41' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2ODMyXXX2MTYsInN1YiI6ImYzNjU0ODgwLTM0YzAtNGQ4Yi04OWU4LWEzNGU2MTE1YTM3NSJ9.eOpVocgU1Pzapnj3iFc6RzqWi3V63_xnXEb_AwDF-dx' \ --data '{ "blob": { "filename": "members_import.xlsx", "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "byte_size": 8908, "checksum": "+KdZiXF2rluobZ73VcHFzgx=" } } ' |
Description du bloc blob :
|
Clé |
Description |
|
filename |
nom du fichier. |
|
content_file |
Fichier CSV : text/csv Fichier XLSX : application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
|
byte_size |
Taille du fichier, en octet. |
|
checksum |
Signature de vérification d’intégrité du fichier, garantit l’intégrité du fichier pendant son transfert, son stockage et son affichage. Empreinte MD5 codée en base64. |
Note : Comment je peux connaître le checksum de mon fichier ?
Sur PowerShell (Windows), avec la série de commandes suivante :
|
$myFile=’./monfichier.csv’ $hashString = Get-FileHash $myFile -Algorithm MD5 | select -ExpandProperty Hash $hashByteArray = [byte[]] ($hashString -replace '..', '0x$&,' -split ',' -ne '') $ContentMD5 = [System.Convert]::ToBase64String($hashByteArray) Echo $ContentMD5 |
Exemple de réponse :
|
{ "signed_id": "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBc1FCIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--3cdf2cfdd7dd593c8fecb208d668cc6cbcc09bxx", "direct_upload": { "url_for_direct_upload": "<url>", "headers_for_direct_upload": { "Content-Type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "Content-MD5": "+KdZiXF2rluobZ73VcHFzgx=", "Content-Disposition": "inline; filename=\"members_import.xlsx\"; filename*=UTF-8''members_import.xlsx" } } } |
|
Clé |
Description |
|
signed_id |
Identifiant technique du fichier à transférer |
|
direct_upload.url_for_direct_upload |
URL de transfert du fichier sur l’espace de stockage de steeple |
|
direct_upload.headers_for_direct_upload |
Paramètres nécessaires pour le transfert de fichier : Content-Type : type MIME du fichier à transférer Content-MD5 : Signature du fichier à transférer Content-Disposition : compléments d’information sur le fichier à transférer |
Cette action prépare le transfert de fichier sur l’espace de stockage Steeple. Celui-ci autorise alors le dépôt du fichier spécifique.
Attention : l’URL de transfert fourni n’est valable que 5 minutes. Passé ce délai, il est nécessaire de préparer un nouveau transfert.
Transférer le fichier
En utilisant l’URL fournie lors de la création du blob. Il est nécessaire de positionner les bons en-têtes HTTP pour sécuriser l’upload.
Exemple d’appel :
|
curl --request PUT '<url>' \ --header 'Content-MD5: +KdZiXF2rluobZ73VcHFzgx=' \ --header 'Content-Disposition: null' \ --header 'Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' \ --data '@members_import.xlsx' |
Le fichier transféré doit respecter le même nom, la même taille et le même contenu que celui déclaré précédemment dans le blob.
Le hash du fichier est également contrôlé lors du transfert.
Lancer le traitement
Lancer le traitement du fichier d’import sur Steeple avec : (POST) /member_provisionnings
Requête :
|
curl --request POST 'https://api.steeple.com/v1/member_provisionings?signed_id=eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBc1FCIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--3cdf2cfdd7dd593c8fecb208d668cc6cbcc09bxx&user_id=895ef75e-b7bf-4e18-a145-xxx4a2a24e41&operation=UPSERT' \ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2ODMyXXX2MTYsInN1YiI6ImYzNjU0ODgwLTM0YzAtNGQ4Yi04OWU4LWEzNGU2MTE1YTM3NSJ9.eOpVocgU1Pzapnj3iFc6RzqWi3V63_xnXEb_AwDF-dx' |
Description des paramètres :
|
Clé |
Description |
|
signed_id |
Identifiant technique du fichier transféré |
|
user_id |
Identifiant de l’utilisateur |
|
operation |
Mode de chargement du fichier parmi :
|
Exemple de réponse :
|
{ "id": 2c8365df-6e7a-4d46-8dxx-882da8cc7b52 } |
Avec :
|
Clé |
Description |
|
id |
Identifiant du traitement d’import du fichier |
Suivre l’avancement du traitement
Lancer le traitement du fichier d’import sur Steeple avec : (GET) /member_provisionnings/{id}
Requête :
|
curl 'https://api.steeple.com/v1/member_provisionings/12c8365df-6e7a-4d46-8dxx-882da8cc7b52?user_id=895ef75e-b7bf-4e18-a145-xxx4a2a24e41' \ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2ODMyXXX2MTYsInN1YiI6ImYzNjU0ODgwLTM0YzAtNGQ4Yi04OWU4LWEzNGU2MTE1YTM3NSJ9.eOpVocgU1Pzapnj3iFc6RzqWi3V63_xnXEb_AwDF-dx' |
Description des paramètres :
|
Clé |
Description |
|
id |
Identifiant du traitement d’import du fichier |
|
user_id |
Identifiant de l’utilisateur |
Exemple de réponse :
|
{ "id": 2c8365df-6e7a-4d46-8dxx-882da8cc7b52, "state": "succeeded" } |
Avec :
|
Clé |
Description |
|
id |
Identifiant du traitement d’import du fichier |
|
state |
État du traitement du fichier : Created : le traitement est créé mais pas encore exécuté Loading : le traitement est lancé, le fichier est en chargement Checking : le fichier est en validation Syncing : les opérations sur les membres sont en cours Succeeded : le traitement est terminé avec succès Failed : le traitement est terminé |
Consulter la synthèse des opérations
Récupérer les opérations liées au traitement avec : (GET) /member provisionnings/{id}/reports
Requête :
|
curl 'https://api.steeple.com/v1/member_provisionings/12c8365df-6e7a-4d46-8dxx-882da8cc7b52/reports?user_id=895ef75e-b7bf-4e18-a145-xxx4a2a24e41' \ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2ODMyXXX2MTYsInN1YiI6ImYzNjU0ODgwLTM0YzAtNGQ4Yi04OWU4LWEzNGU2MTE1YTM3NSJ9.eOpVocgU1Pzapnj3iFc6RzqWi3V63_xnXEb_AwDF-dx' |
Description des paramètres :
|
Clé |
Description |
|
id |
Identifiant du traitement d’import du fichier |
|
user_id |
Identifiant de l’utilisateur |
|
page |
Permets de naviguer dans les éléments (par défaut, page=1) |
|
per_page |
Modifie le nombre d'éléments retournées par page (par défaut, per_page=20) |
Exemple de réponse :
|
{ "data": [ { "id": 4, "code": "CREATE_MEMBER", "created_at": 1685111972179, "operation_data": { "name": "Test Nico Matricule (II)", "value": 3 } }, { "id": 5, "code": "CREATE_MEMBER", "created_at": 1685111972179, "operation_data": { "name": "Test Nico 2 Communauté 2", "value": 0 } } ], "meta": { "pagination": { "total": 2, "page": 1, "per_page": 20 } } } |
Avec dans le bloc data
|
Clé |
Description |
|
id |
Identifiant du traitement d’import du fichier |
|
code |
Code d’opération réalisée sur la communauté : CREATE_MEMBER : création de membres UPDATE_MEMBER : mise à jour de membres DELETE_MEMBER : suppression de membres |
|
created_at |
Timestamp de création de l’opération |
|
operation_data.name |
Nom de la communauté de l’organisation |
|
operation_data.value |
Nombre d’opérations réalisées sur la communauté |
Le bloc meta est composé de :
|
clé |
Description |
|
pagination.total |
nombre total d’éléments répondant aux critères de la requête |
|
pagination.page |
page courante des éléments retournées dans la réponse |
|
pagination.per_page |
nombre d’éléments retournées par page |
Consulter les erreurs et les avertissements du traitement
Récupérer les messages lié au traitement : (GET) /member provisionnings/{id}/messages
Requête :
|
curl 'https://api.steeple.com/v1/member_provisionings/12c8365df-6e7a-4d46-8dxx-882da8cc7b52/messages?user_id=895ef75e-b7bf-4e18-a145-xxx4a2a24e41' \ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2ODMyXXX2MTYsInN1YiI6ImYzNjU0ODgwLTM0YzAtNGQ4Yi04OWU4LWEzNGU2MTE1YTM3NSJ9.eOpVocgU1Pzapnj3iFc6RzqWi3V63_xnXEb_AwDF-dx' |
Description des paramètres :
|
Clé |
Description |
|
user_id |
Identifiant de l’utilisateur |
|
page |
Permets de naviguer dans les éléments retournés (par défaut, page=1) |
|
per_page |
Modifie le nombre d’éléments retournés par page (par défaut, per_page=20) |
Exemple de réponse :
|
{ "data": [ { "severity": "ERROR", "error_code": "must_exist", "error_data": null, "scope": "CELL", "scope_data": { "col": "B", "row": 4 }, "created_at": 1692624066922 }, { "severity": "WARN", "error_code": "root_community_ignored", "error_data": null, "scope": "CELL", "scope_data": { "col": "K", "row": 26 }, "created_at": 1692624066922 } ], "meta": { "pagination": { "total": 2, "page": 1, "per_page": 20 } } } |
Avec, pour chaque message, dans le bloc data
|
Clé |
Description |
|
severity |
ERROR pour une erreur (le fichier est rejeté) WARNING pour un avertissement (le champ est ignoré) |
|
error_code |
Type d’erreur |
|
error_data |
Précision sur l’erreur rencontrée |
|
scope |
SHEET : concerne tout le fichier CELL : concerne une cellule |
|
scope_data |
Précision sur le scope |
|
created_at |
Date de création du message |
Le bloc meta est composé de :
|
clé |
Description |
|
pagination.total |
nombre total d’éléments répondant aux critères de la requête |
|
pagination.page |
page courante des éléments retournées dans la réponse |
|
pagination.per_page |
nombre d’éléments retournées par page |
Valider les invitations
Avec un profil administrateur, se connecter à l’administration de la communauté et naviguer jusqu’à la liste des membres de la communauté, des invitations sont en attente :
Il est possible d’envoyer toutes les invitations en une seule fois en sélectionnant toutes les invitations en attente et en utilisant l’action globale “inviter” :
