Haiilo API: Profilfelder bearbeiten und konfigurieren – Haiilo Knowledge Base

Hinweis: 
Aufgrund des technischen Inhalts sind viele Begriffe und Befehle weiterhin auf Englisch.

In Haiilo könnt ihr Profilfelder mit der REST-API anpassen.  Detaillierten Einblick in die technische Dokumentation zur REST-API bekommt ihr hier.

Wir empfehlen das Programm Postman für die Anbindung an Haiilo zu nutzen. Eine Alternative wäre das Programm cURL.

Hier zeigen wir euch anhand eines Beispiels, wie ihr mit wenigen Schritten Änderungen vornehmt.  Alle Screenshots, die ihr in diesem Artikel seht, stammen aus dem Programm Postman.

Hinweis:
Um Anpassungen über API vorzunehmen, müsst ihr euch als Superadmin anmelden und den Moderator-Modus einschalten. Ihr könnt den Moderator-Modus auch direkt via API Befehl aktivieren, sofern ihr das Recht dazu habt:

PUT /api/users/<id>/moderatorMode

Schritt 1: Authentifiziert euch

Parameter

Als Erstes benötigt ihr euren sogenannten bearer_token. Dieser dient zur Authentifizierung eurer späteren Anfragen und Befehle. Um diesen zu erhalten, identifiziert ihr euch über die OAuth2-Schnittstelle mit eurem Haiilo-Account.

Bitte beachtet, dass ihr mit API-Zugriff auf Haiilo die gleichen Rechte habt, wie in eurer Haiilo Web-Umgebung. Es macht also einen Unterschied, ob ihr den Moderator-Modus aktiviert habt oder euch als Superadmin anmeldet.

curl -x POST  https://<eure-coyo-domain>/api/oauth/token?grant_type=password&username=<loginName>&password=<password>

1.1.jpg

Autorisierung

Im zweiten Reiter „Authorization“ wählt ihr als Typ „Basic Auth“ und tragt in die Felder eure Haiilo API-Client ID ein. Diese findet ihr in eurer Haiilo Administration unter API-Clients.

Wenn ihr nun auf "Send" klickt, sollte die Antwort in etwa so aussehen.

{ 
  "access_token": "d3cd7b86-234b-4037-9f9f-6083b4df355e", 
  "token_type": "bearer", 
  "refresh_token": "aa2c35f7-4448-46af-94d5-6427d777ada7", 
  "expires_in": 3599, 
  "scope": "read write" 
}

Kopiert euch hier den access-token ohne die Anführungszeichen.

Schritt 2: Profilfelder-Abfrage senden

Öffnet euch einen neuen, übergeordneten Reiter und wählt einen "GET" Befehl im Drop-Down aus, tragt folgenden Befehl ein und fügt euren kopierten Token ein.

curl -x GET https://<eure-coyo-domain>/api/users/profile/groups

Im Reiter “Authorization” wählt ihr dazu den Typ Bearer Token aus und fügt in das entsprechende Feld euren Schlüssel ein.

Die Antwort, die ihr von Haiilo bekommt, sollte in etwa so aussehen:

[
  { 
    "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 
  } 
]

In dieser JSON sind alle Profilfelder aufgelistet, die ihr als Nutzer auch in eurer Haiilo Umgebung seht.  Als Standardeinstellung sind die Profilfelder in drei Gruppen eingeteilt:

"contact“
"basicInformation“
"work“

 Die Anordnung der Gruppen sind bestimmt durch den Parameter „sortOrder“.  

Im folgenden Screenshot seht ihr, wie die JSON in Haiilo aussieht.

Unsere „fields“ Parameter

Wie ihr in der Beispielausgabe der JSON sehen könnt, gibt es wesentlich mehr Parameter als nur den Namen des Feldes.
Im Folgenden erklären wir euch die möglichen Anpassungen:

In den Standardeinstellungen sind alle Parameter - außer die Reihenfolge („order“) - auf false gesetzt, also deaktiviert.

overview: Inhalt wird in der Übersicht der Kollegenliste angezeigt und für die Suche in der Kollegenliste indiziert (ab v25)
important: Inhalt wird im Benutzerprofil, Reiter „Aktivitäten“ angezeigt
userChooser: Inhalt wird bei @mention eines Nutzers angezeigt
immutable: Inhalt ist nicht editierbar
searchAggregation: Inhalt ist als Filter in der Kollegenliste setzbar
searchAggregationOrder: Reihenfolge der angezeigten Filtermöglichkeiten in der Kollegenliste
order: Reihenfolge der angezeigten Profilfelder
name: Der Sprach-Key den ihr für Haiilo Übersetzungen benötigt

Hinweis:
Um den Anzeigenamen der Profilfelder anzupassen, müsst ihr die Sprachschlüssel in der Administration anpassen: "Administration" > "Sprachen" > "Übersetzungen"

Neue Übersetzungen müssen mit einem REST API Befehl eingepflegt werden.

type: Formatierungsart des Inhalts. z. B. Hyperlink bekommen somit eine Verlinkung
- TEXT: Reiner Text
- EMAIL: Inhalt bekommt eine Mailverlinkung /“mailto:“
- LINK: Inhalt wird als Hyperlink dargestellt
- PHONE: Inhalt wird automatisch auf Gültigkeit überprüft
- BIRTHDAY: Datumsanzeige
- OPTIONS: Drop-Down Menu

Hinweis:
Ein Drop-Down Menu muss als Array dargestellt werden.

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

Schritt 3: Anpassung der Profilfelder

Um jetzt die gewünschten Änderungen vorzunehmen, kopiert ihr euch die entsprechende Profilfeldgruppe, öffnet einen neuen Reiter und fügt alle Parameter in den "body" ein. Nehmt die gewünschten Änderungen vor und führt anschließend einen sogenannten "PUT" Befehl aus.

Hier ein Beispiel, wie eine Anpassung in der Profilfeldgruppe "work" aussähe. Wir möchten gerne anzeigen lassen, in welchem Zimmer die Kollegen sitzen.

Ihr habt jetzt zwei Optionen:  Entweder benennt ihr ein Feld, welches ihr nicht benötigt um, oder erstellt ein Neues. In beiden Fällen, ist es wichtig, dass ihr die gesamte Gruppe aus dem "body" in Schritt 2 heraus kopiert.  Angefangen mit der geschweiften Klammer:

{
  "id“: “xxxxx“,
  …

und endend mit der geschlossenen, geschweiften Klammer

  "modifiable": true
}

Ein komplettes einzelnes Profilfeld sieht so aus:

{
  "name": "about",
  "type": "TEXTAREA",
  "order": 3,
  "overview": false,
  "important": false,
  "userChooser": false,
  "searchAggregation": false
}

Hinweis:
Häufige Fehlerquelle ist die Syntax. Lieber einmal mehr kontrollieren:

Sind alle Klammern geschlossen?
Sind die Parameter in Anführungszeichen?
Stehen zwischen der Auflistung der einzelnen Felder Kommata?

Nehmt im HTML nun die gewünschten Änderungen oder Erweiterungen vor und tragt in der URL-Leiste folgenden Befehl ein. Bitte beachtet, dass ihr die ID der zu ändernden Gruppe am Ende einfügt.

curl -x PUT https://<eure-coyo-domain>/api/users/profile/groups/<group-id>

In unserem Beispiel fügen wir das Feld “Raumnummer“ hinzu und passen gleichzeitig die Reihenfolge der Felder an, damit das neue Feld „Raumnummer“ über dem Feld „Firma“ steht.

{ 
  "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 
}

Schritt 4: Feld füllen

Um das neue Feld direkt zu füllen, öffnet ihr einen erneuten "POST" Befehl und fügt den Wert, den "value", im "body" ein.

curl -x POST https://<eure-coyo-domain>/api/users/<user-ID>/profile/fields

{ 
  "roomnumber" : "2.OG, R2.123" 
}

Das Ergebnis sieht dann wie folgt aus:

Wie ihr seht, hat das Feld jetzt den Namen "Büro" (Sprachschlüssel "USER.ROOMNUMBER"). Das liegt an dem Multi-Language Feature von Haiilo, welches mit Sprachschlüsseln arbeitet. Dieser Sprachschlüssel wurde durch uns neu hinzugefügt und jetzt geben wir ihm in jeder Sprache einen klaren Namen.

Schritt 5: Sprachschlüssel hinzufügen

Für das Hinzufügen eines Sprachschlüssel haben wir hier eine Anleitung:

Haiilo API: Übersetzungen importieren

Tipp:
Wenn ihr mehr zu unseren Sprachschlüsseln erfahren möchtet, klickt hier.

Profilfelder in der Kollegensuche durchsuchbar machen

Seit der Cloud Version 25 könnt ihr mit der Suche in der Kollegenübersicht auch nach Expertise suchen. Voraussetzung dafür ist, dass ihr bei den via API konfigurierten Felder das Feld "overview" auf "true" setzt.

{
 "name": "about",
 "type": "TEXTAREA",
 "order": 3,
 "overview": true,
 "important": false,
 "userChooser": false,
 "searchAggregation": false
}

Hinweis zum Benutzerprofil-Widget:

Beim Benutzerprofil-Widget können nur die Haiilo Standard-Felder: E-Mail, Telefonnummer (phone) und Job Titel (jobTitle) angezeigt werden. Sobald ihr diese Namen der Profilfelder ändert oder ersetzt, können diese nicht mehr im Widget angezeigt werden.