Haiilo API: Edit and configure profile fields

You can customize profile fields in Haiilo using the REST API. You can get a detailed insight into the technical documentation for the REST API here. 

We recommend the program Postman for the connection to Haiilo. Another alternative would be the program cURL.

We use an example here to show you how you can make changes in just a few steps. All of the screenshots that you can see in this article come from the program Postman.

Note:
To make changes via API, you need to log in as a super-admin and activate moderator mode. You can also activate moderator directly via API command if you have the permission for this:

PUT /api/users/<id>/moderatorMode

Step 1: Authenticate yourself

Parameter

First of all, you need what’s known as your 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. 

Please note that 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 your 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 here without quotation marks.

Step 2: Send profile fields query

Open a new, overarching 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 
      } 
    ],
    "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. 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 how what the JSON looks like in Haiilo.

"options": {
"location01": "Atlanta",
"location02": "Basel",
"location03": "Boston"
},

Step 3: Customization of the profile fields

To now make the desired changes, copy the corresponding profile field group, open a new tab and paste all of the parameters into the "body" . Make the desired changes and then execute what’s known as a "PUT" command.
 
Here’s an example of what customization in the profile field group "work" would look like. We want to display in which rooms colleagues can be found.
 
You now have two options: Either rename a field that 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 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

We have one instruction here for adding a language key:

Haiilo API: Import translations

Tip:
If you want to find out more about our language keys, click here. 

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 you to set 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.