In this article, we will go through all the steps needed to synchronise your users with Ermeo. Whether you use Azure Active Directory or something else, you may want to synchronise your users' roles and rights according to rules you have setup on your side.
This article assumes that you already know how to authenticate your requests. We also recommend you to take a look at the article about how to synchronise assets with Ermeo.
1. Teams vs. Roles
This section aims at understanding the difference between roles and teams. A team contains access rights. These access rights give the users in the team the ability to access documents, users, assets, and interventions according to certain parameters (folders, attributes, databases, ...). Roles only give users permission to see certain parts of the platform or the application. For instance, a role will give access to a user having this role to the map or the reports in the application.
A user can belong to several teams but can only have one role.
2. Retrieve roles and teams from Ermeo
Routes used in this part:
The very first thing to do when synchronizing users with Ermeo is to be aware of the roles and teams in your workspace. For this, we have requests in order to retrieve all the roles and teams in a workspace. In order to retrieve the roles of the workspace:
GEThttps://api.ermeo.com/api/v1/rolesHere is the response of the API:
{
"total_items": number_of_roles,
"total_pages": number_of_pages,
"items_per_page": number_of_items_per_page,
"next_page": url_of_the_next_page,
"previous_page": url_of_the_previous_page,
"items": [
{
"id": "the_id_of_the_role",
"name": "the_name_of_the_role",
"code": "the_code_of_the_role",
"enabled": true,
"platform_permission": [], //list of the permissions in the platform
"app_permission": [], //list of the permissions in the application
"created_by": {
"id": "id_of_the_person_who_created_the_role",
"code": "code_of_the_person_who_created_the_role"
},
"updated_by": {
"id": "id_of_the_person_who_updated_the_role",
"code": "code_of_the_person_who_updated_the_role"
},
"created_at": "date_of_creation",
"updated_at": "date_of_update"
}
]
}In order to retrieve the teams of the workspace:
GEThttps://api.ermeo.com/api/v1/teamsHere is the response of the API:
{
"total_items": number_of_teams,
"total_pages": number_of_teams,
"items_per_page": number_of_items_per_page,
"next_page": url_of_the_next_page,
"previous_page": url_of_the_previous_page,
"items": [
{
"id": "the_id_of_the_team",
"code": "the_code_of_the_team",
"name": "the_name_of_the_team",
"description": null,
"users": [], //The users in the team
"leaders": [], //Deprecated
"access_rights": [], //The access rights defined in the team
"created_by": {
"id": "id_of_the_person_who_created_the_team",
"code": "code_of_the_person_who_created_the_team"
},
"updated_by": {
"id": "id_of_the_person_who_updated_the_team",
"code": "code_of_the_person_who_updated_the_team"
},
"created_at": "date_of_creation",
"updated_at": "date_of_update"
}
]
}We now have all the teams and roles available in the workspace and therefore all the details to create or update a user.
3. Create or update a user
Routes used in this part:
In order to create a user in Ermeo, we need to send the following request:
POSThttps://api.ermeo.com/api/v1/usersHere is the body to send with the request:
{
"attributes": [], //The attributes you want to set a value to for this user
"first_name": "first_name",
"last_name": "last_name",
"username": "unique_username",
"email": "email_address",
"role": {
"id": "id_of_the_role_to_assign_to_the_user"
},
"teams": [
{
"id": "id_of_one_of_the_teams_the_user_should_belong_to"
}
],
"is_enabled": true, //This should always be true
"timezone": "Europe/Paris", //The timezone the user is in.
"new_password1": "password", //The password the user will have.
"new_password2": "password", //The password the user will have.
"send_email": false | true, //Wether the user should receive an invitation email
}Many things are interesting in this body:
- We can mention the id of the role you want to assign your user to. This is one of the roles we have retrieved from the GET https://api.ermeo.com/api/v1/roles request.
- We can mention one or several teams this user should belong to. This is one or several of the teams we have retrieved from the GET https://api.ermeo.com/api/v1/teams request.
- The is_enabled key should always be set to true.
- The timezone key corresponds to the timezone our user will work in.
- The keys new_password1 and new_password2 are not mandatory. They can only be used if we want to set our user's password ourselves.
- The send_email key corresponds to whether the user should receive an invitation email or not. If we decide to set this to true, a welcome email will be sent to the user asking him to set his password by himself.
The update of a user is exactly the same as the creation. Let's assume we have changed the role or the team of a specific user on our systems side (not Ermeo). We can first search this user by the username of email address with the following request
POSThttps://api.ermeo.com/api/v1/users/searchWhen the id of the user is retrieved, we can now send a request to update the user:
PUThttps://api.ermeo.com/api/v1/users/{id}The body is similar to what we have sent at the creation of the user.