You can customize profile fields in Haiilo using the REST API. The technical documentation for the Haiilo REST API can be found here. Below, we'll show an example of how you can make changes to the profile fields with Postma in just a few steps.
To make changes via API, you need to log in as a super-admin and activate moderator mode. You can also activate moderator mode via an API command if you have permission: PUT /api/users/<id>/moderatorMode
Step 1: Authenticate yourself
Parameter
First of all, you need a bearer_token. This is used to authenticate your subsequent queries and commands. To obtain this, identify yourself via the OAuth2 interface using your Haiilo account. You have the same permissions as in your Haiilo Web environment with API access to Haiilo. So, it makes a difference whether you have activated moderator mode or are logged in as a super-admin.
curl -x POST https://<your-coyo-domain>/api/oauth/token?grant_type=password&username=<loginName>&password=<password>
Authorization
On the second tab, "Authorization", select the type "Basic Auth" and enter your Haiilo API client ID in the fields. You can find this in the Haiilo Administration under API Clients.
If you now click on "Send", the answer should look something like this.
{
"access_token": "d3cd7b86-234b-4037-9f9f-6083b4df355e",
"token_type": "bearer",
"refresh_token": "aa2c35f7-4448-46af-94d5-6427d777ada7",
"expires_in": 3599,
"scope": "read write"
}
Copy the access token from the response without quotation marks.
Step 2: Send profile fields query
Open a new tab and select a "GET" command in the drop-down menu, enter the following command, and paste your copied token.
curl -x GET https://<your-coyo-domain>/api/users/profile/groups
On the "Authorization" tab, select the type Bearer Token and paste your key in the corresponding field. The response that you get from Haiilo should look something like this:
[
{
"id": "93977140-cf43-490d-b754-e9dca5cda06c",
"name": "basicInformation",
"sortOrder": 1,
"fields": [
{
"name": "birthday",
"type": "BIRTHDAY",
"order": 0,
"overview": false,
"important": false,
"userChooser": false,
"searchAggregation": false
},
{
"name": "languages",
"type": "TEXT",
"order": 1,
"overview": false,
"important": false,
"userChooser": false,
"searchAggregation": false
},
{
"name": "homeTown",
"type": "TEXT",
"order": 2,
"overview": false,
"important": false,
"userChooser": false,
"searchAggregation": false
}
],
"modifiable": true
},
{
"id": "183c5478-4cd3-49d4-bd2e-322d66116cef",
"name": "contact",
"sortOrder": 0,
"fields": [
{
"name": "phone",
"type": "PHONE",
"order": 0,
"overview": true,
"important": true,
"userChooser": false,
"searchAggregation": false
},
{
"name": "mobile",
"type": "PHONE",
"order": 1,
"overview": false,
"important": false,
"userChooser": false,
"searchAggregation": false
},
{
"name": "website",
"type": "LINK",
"order": 7,
"overview": false,
"important": false,
"userChooser": false,
"searchAggregation": false
}
],
"modifiable": false
},
{
"id": "79b14834-c6c9-4447-bf34-146ef3475592",
"name": "work",
"sortOrder": 2,
"fields": [
{
"name": "jobTitle",
"type": "TEXT",
"order": 0,
"overview": false,
"important": false,
"userChooser": true,
"searchAggregation": false
},
{
"name": "company",
"type": "TEXT",
"order": 1,
"overview": false,
"important": false,
"userChooser": false,
"searchAggregation": false
},
{
"name": "_employedSince",
"type": "DATE",
"order": 2,
"overview": false,
"important": false,
"userChooser": false,
"searchAggregation": false,
"hidden": true
}
],
"modifiable": true
}
]
This JSON contains a list of all of the profile fields that you can also see in your Haiilo environment as a user. Profile fields marked as "hidden" will not be shown. The profile fields are divided into three groups as a default setting:
- "contact"
- "basicInformation"
- "work"
The order of the groups is determined by the parameter "sortOrder".
In the following screenshot, you can see what the JSON looks like in Haiilo.
Our "fields" parametersAs you can see in the example output from the JSON, here are many more parameters than just the name of the field. We explain the possible customizations to you below: By default, all of the parameters - except for the order ("order") - are set to false, i.e., deactivated.
Note: New translations must be added with a REST API command.
Note: "options": { |
Step 3: Customization of the profile fields
To make the desired changes, copy the corresponding profile field group, open a new tab, and paste all parameters into the "body". Make the desired changes and then execute what's known as a "PUT" command.
Below is an example of what customization in the profile field group "work" would look like if we want to display in which rooms colleagues can be found. You have two options: Either rename a field you don't need or create a new one. In both cases, it's important that you copy the entire group from "body" in step 2. Starting with the curly bracket:
{
"id": "xxxxx",
…
and ending with the closing curly bracket:
"modifiable": true
}
A complete individual profile field looks like this:
{
"name": "about",
"type": "TEXTAREA",
"order": 3,
"overview": false,
"important": false,
"userChooser": false,
"searchAggregation": false
}
Note:
One frequent source of error is the syntax. It's best to check one more time:
- Are all of the brackets closed?
- Are the parameters in quotation marks?
- Are there commas between the individual fields in the list?
Now make the desired changes or expansions in the HTML and enter the following command in the URL bar. Please note that you add the ID of the group to be changed at the end.
curl -x PUT https://<your-coyo-domain>/api/users/profile/groups/<group-id>
In our example, we add the field "Room number" and also change the order of the fields so that the new field "Room number" is above the field "Company".
{
"id": "79b14834-c6c9-4447-bf34-146ef3475592",
"name": "work",
"sortOrder": 2,
"fields": [
{
"name": "jobTitle",
"type": "TEXT",
"order": 0,
"overview": false,
"important": false,
"userChooser": true,
"searchAggregation": false
},
{
"name": "company",
"type": "TEXT",
"order": 2,
"overview": false,
"important": false,
"userChooser": false,
"searchAggregation": false
},
{
"name": "roomnumber",
"type": "TEXT",
"order": 1,
"overview": false,
"important": false,
"userChooser": false,
"searchAggregation": false
}
],
"modifiable": true
}
Step 4: Complete the field
To complete the new field straight away, open another "POST" command and add the "value" in the "body".
curl -x POST https://<your-coyo-domain>/api/users/<user-ID>/profile/fields
{
"roomnumber" : "41"
}
The result then looks as follows:
As you can see, the field now has the name "USER.ROOMNUMBER". This is due to the Multi-Language feature in Haiilo, which works using language keys. This new language key has now been added by us, and we will now give it a distinct name in every language.
Step 5: Add language key
Review the below instructions for adding a language key:
Make profile fields searchable in the colleague search
From Cloud version 25, you can use the search in the colleague overview to also search for expertise. This requires setting the field "overview" to "true" in the fields configured via API.
{
"name": "about",
"type": "TEXTAREA",
"order": 3,
"overview": true,
"important": false,
"userChooser": false,
"searchAggregation": false
}
Note about the user profile widget
In the user profile widget, only the standard Haiilo fields can be displayed: Email, Phone number (phone) and Job title (jobTitle). As soon as you change or replace these profile fields, they cannot be displayed in the widget anymore.