Membership provisioning through API
What is Membership provisioning?
We call provisioning the action of creating user accounts in Steeple. The creation of a user account is systematically associated with at least one community, the user therefore becomes an invited member in a community.
Provisioning can be manual, individually from the administration or in groups by manual file import. It can also be automated with synchronizations based on the SCIM protocol or by automatic file import via API.
Important : the creation of users by the file import API allows you to create users and associate them with communities. On the other hand, no invitation is sent to users created at the end of the processing. Users are created in Steeple and associated invitations are waiting to be sent. Only a manual action from the community administrator can trigger the invitations.
Note : the creation of users by the file import API is only operational for organizations whose access method is set to “Matricule”. Imports for organizations based on a classic access method will be available very soon.
.
Integrate a member file
Why a membership file?
The import of members by file is a proven feature in Steeple, it allows a standardized formalism in the data necessary for the creation of members in the communities. It is a simple way to automate a manual recurring task by API without completely reviewing the interface contracts and the data exchanged. Once a first member file has been compiled and validated by manual import, automation via API is greatly facilitated.
How to build a members file?
With an Administrator role, from the community administration interface,work it file import is available on the member management screen:
By choosing an import mode, you will make available an empty document template that can be used to import the members of your communities.
Information about modes:
Mirror (MIRROR): In this mode, the imported file prevails. The import operation will create all the members present in the file and absent from your communities. It will update the information of the members present both in the file and in your communities. And, importantly, the import operation will delete the members who are in your communities but absent from the file.
Insertion (UPSERT) : In this mode, the import operation does not perform any deletion. She is responsible for adding new members and updating existing members, if necessary.
Suppression (DELETE) : In this mode, all members of the file are removed from your communities. No additions or changes will be made.
Each mode has its file model.
For more details on file import, see the FAQ.
How to process a member file?
The processing of a member file goes through 4 steps:
- Importing the file to the Steeple temporary storage space
- Starting member import processing
- Regular monitoring of import processing
- File processing report retrieval
Transfer file
Prepare a file transfer
Prepare the transfer of an import file on Steeple with: (GET)/blob
Query :
|
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 of the block blob :
|
Key |
Description |
|
filename |
file name. |
|
content_file |
CSV file: text/csv Fichier XLSX : application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
|
byte_size |
File size, in bytes. |
|
checksum |
File integrity verification signature, ensures file integrity during transfer, storage and viewing. Base64-encoded MD5 fingerprint. |
Note : How can I know the checksum of my file?
On PowerShell (Windows), with the following series of commands:
|
$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 |
Example answer:
|
{ "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" } } } |
|
Key |
Description |
|
signed_id |
Technical identifier of the file to transfer |
|
direct_upload.url_for_direct_upload |
URL for transferring the file to the steeple storage space |
|
direct_upload.headers_for_direct_upload |
Parameters required for file transfer: Content-Type : MIME type of file to transfer Content-MD5 : Signature of the file to transfer Content-Disposition : additional information on the file to be transferred |
This action prepares the file transfer on the Steeple storage space. This then authorizes the deposit of the specific file.
Please note: The transfer URL provided is only valid for 5 minutes. After this time, it is necessary to prepare a new transfer.
Transfer file
Using the URL provided when creating the blob. It is necessary to position the correct HTTP headers to secure the upload.
Call example:
|
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' |
The transferred file must respect the same name, the same size and the same content as the one declared previously in the blob.
The file hash is also checked during the transfer.
Start processing
Start processing the import file on Steeple with: (POST)/member_provisionnings
Query :
|
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 of parameters:
|
Key |
Description |
|
signed_id |
Technical identifier of the transferred file |
|
user_id |
User ID |
|
operation |
File loading mode |
Example answer:
|
{ "id": 1 } |
With :
|
Key |
Description |
|
id |
File import processing identifier |
Follow the progress of the treatment
Start processing the import file on Steeple with: (GET)/member_provisionnings
Query :
|
curl 'https://api.steeple.com/v1/member_provisionings?id=1&user_id=895ef75e-b7bf-4e18-a145-xxx4a2a24e41' \ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2ODMyXXX2MTYsInN1YiI6ImYzNjU0ODgwLTM0YzAtNGQ4Yi04OWU4LWEzNGU2MTE1YTM3NSJ9.eOpVocgU1Pzapnj3iFc6RzqWi3V63_xnXEb_AwDF-dx' |
Description of parameters:
|
Key |
Description |
|
id |
File import processing identifier |
|
user_id |
User ID |
Example answer:
|
{ "id": 1, "state": "succeeded" } |
With :
|
Key |
Description |
|
id |
File import processing identifier |
|
state |
File processing status: Created : the process is created but not yet run Loading : processing is launched, the file is being loaded Checking : the file is in validation Syncing : operations on members are in progress Succeeded : the processing is completed successfully Failed : processing is finished |
Retrieve the summary of operations
Start processing the import file on Steeple with: (GET)/member_provisionnings/reports
Query :
|
curl 'https://api.steeple.com/v1/member_provisionings/reports?id=1&user_id=895ef75e-b7bf-4e18-a145-xxx4a2a24e41' \ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2ODMyXXX2MTYsInN1YiI6ImYzNjU0ODgwLTM0YzAtNGQ4Yi04OWU4LWEzNGU2MTE1YTM3NSJ9.eOpVocgU1Pzapnj3iFc6RzqWi3V63_xnXEb_AwDF-dx' |
Description of parameters:
|
Key |
Description |
|
id |
File import processing identifier |
|
user_id |
User ID |
|
page |
Allows to navigate in previous publications (by default, page=1) |
|
per_page |
Changes the number of posts returned per page (default per_page=20) |
Example answer:
|
{ "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 Community 2", "value": 0 } } ], "meta": { "pagination": { "total": 2, "page": 1, "per_page": 20 } } } |
With in the blockdata
|
Key |
Description |
|
id |
File import processing identifier |
|
code |
Code of operation carried out on the community: CREATE_MEMBER : creation of members UPDATE_MEMBER : member update DELETE_MEMBER : deletion of members |
|
created_at |
Operation creation timestamp |
|
operation_data.name |
Organization community name |
|
operation_data.value |
Number of operations carried out on the community |
The blockmeta is composed of:
|
key |
Description |
|
pagination.total |
total number of items meeting the query criteria |
|
pagination.page |
current page of elements returned in response |
|
pagination.per_page |
number of items returned per page |
Validate invitations
With an administrator profile, login to the community administration and navigate to the list of community members, invitations are pending:
It is possible to send all invitations at once by selecting all pending invitations and using the “invite” global action:
