API: Profilfelder anpassen

Du kannst die Haiilo-API verwenden, um Profilfelder anzupassen. Im Folgenden zeigen wir dir ein Beispiel, wie du mit Postman in nur wenigen Schritten ein Profilfeld hinzufügen oder ändern kannst.

Um Anfragen an die Haiilo-API zu stellen, musst du dich zuerst authentifizieren. Detaillierte Informationen zur Authentifizierung und Verwendung der API findest du hier.

Schritt 1: Profilfelder auflisten

  1. Stelle eine GET-Anfrage an den Endpunkt /api/users/profile/groups, um eine Liste aller Profilgruppen und ihrer Felder zu erhalten.

Verstehe die Antwort

Du kannst unten ein Beispiel sehen, wie die Antwort aussehen könnte:

  • [
    {
    "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
    },
    ...
    ],
    "modifiable": true
    },
    ]

Die JSON-Antwort entspricht den Profilfeldern, die du im Profil eines Nutzers auf der Plattform sehen kannst. Die Profilfelder sind standardmäßig in drei Gruppen unterteilt:

  • contact
  • basicInformation
  • work

Der Parameter sortOrder bestimmt die Reihenfolge der Gruppen.

Übersicht der Registerkarte Benutzerprofilinformationen.png

Verstehe die Parameter

Für jedes Profilfeld gibt es Parameter. Standardmäßig sind die meisten Parameter - außer order - deaktiviert, d.h. auf false gesetzt. Folgende Anpassungen sind möglich:

Parameter Beschreibung und Hinweise
overview Wenn true, wird der Inhalt in der Benutzerprofilkarte angezeigt und für die Kollegenliste indiziert
important Wenn true, wird der Inhalt in der linken Box im Benutzerprofil im Tab Aktivität angezeigt
userChooser Wenn true, wird der Inhalt in dem Popup angezeigt, das beim Erwähnen eines Benutzers erscheint
immutable Wenn true, kann der Inhalt nicht bearbeitet werden
searchAggregation Wenn true, wird der Inhalt als Filter in der Kollegenliste hinzugefügt
searchAggregationOrder Definiert die Reihenfolge der angezeigten Filteroptionen in der Kollegenliste
order Reihenfolge der angezeigten Profilfelder innerhalb der Profilgruppe
name Der Sprachschlüssel, der für Haiilo-Übersetzungen erforderlich ist.
  • Wenn der Name mit einem Unterstrich beginnt, wird das Feld ausgeblendet und du musst keine Übersetzung angeben. Ein ausgeblendetes Feld erfordert, dass der Parameter hidden auf true gesetzt wurde.
  • Um die Anzeigenamen der Profilfelder anzupassen, musst du die Sprachschlüssel-Übersetzungen anpassen. Neue Übersetzungen müssen mit einem REST-API-Befehl hinzugefügt werden.
hidden Wenn true, wird das Feld ausgeblendet und ist nicht sichtbar. Erfordert auch, dass der Parameter Name mit einem Unterstrich beginnt.
type Bestimmt den Formatierungstyp des Inhalts:
  • TEXT: Reiner Text
  • EMAIL: Der Inhalt wird als E-Mail-Link /"mailto:" angezeigt
  • LINK: Der Inhalt wird als Hyperlink angezeigt
  • PHONE: Der Inhalt wird automatisch auf Gültigkeit überprüft
  • BIRTHDAY: Datumsanzeige
  • OPTIONS: Dropdown-Menü*
  • TIMESTAMP: ISO 8601 formatierter Zeitstempel mit Datum, Uhrzeit und Offset-Informationen, z.B. 2023-08-02T12:00:05+02:00

*Wenn type als OPTIONS ausgewählt ist, muss ein Dropdown-Menü als Array angezeigt werden:

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

Schritt 2: Ein neues Profilfeld hinzufügen oder ein bestehendes Profilfeld bearbeiten

Du kannst Änderungen an Profilgruppen und -feldern wie folgt vornehmen:

  1. Kopiere eine komplette Profilfeldgruppe aus der Antwort, beginnend mit der ersten { bis zur letzten } für diese Gruppe. Zum Beispiel:
       { 
        "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": "department",
                "type": "TEXT",
                "order": 2,
                "overview": true,
                "important": false,
                "userChooser": true,
                "searchAggregation": true,
                "searchAggregationOrder": 1
            },
            {
                "name": "office",
                "type": "TEXT",
                "order": 3,
                "overview": true,
                "important": false,
                "userChooser": true,
                "searchAggregation": true,
                "searchAggregationOrder": 2
            },
            {
                "name": "location",
                "type": "TEXT",
                "order": 4,
                "overview": false,
                "important": true,
                "userChooser": false,
                "searchAggregation": true,
                "searchAggregationOrder": 3
            },
            {
                "name": "education",
                "type": "TEXT",
                "order": 5,
                "overview": false,
                "important": false,
                "userChooser": false,
                "searchAggregation": false
            }
        ],
        "modifiable": true
    } 
    
  2. Gib die gesamte kopierte Profilfeldgruppe im Anfrage-Body ein. Auch wenn du nur ein Feld bearbeitest, muss die gesamte Gruppe als PUT-Anfrage enthalten sein, da der aktuelle Zustand überschrieben wird.
  3. Nimm die gewünschten Änderungen an einem Profilfeld vor oder füge ein neues hinzu.
    • In unserem Beispiel fügen wir das Feld room_number hinzu und ändern die Reihenfolge der Felder so, dass das neue Feld über dem Feld company in der Gruppe work 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": "room_number",
                  "type": "TEXT",
                  "order": 1,
                  "overview": false,
                  "important": false,
                  "userChooser": false,
                  "searchAggregation": false
              },
              { 
                  "name": "company", 
                  "type": "TEXT", 
                  "order": 2, 
                  "overview": false, 
                  "important": false,
                  "userChooser": false, 
                  "searchAggregation": false 
              },
              {
                  "name": "department",
                  "type": "TEXT",
                  "order": 3,
                  "overview": true,
                  "important": false,
                  "userChooser": true,
                  "searchAggregation": true,
                  "searchAggregationOrder": 1
              },
              {
                  "name": "office",
                  "type": "TEXT",
                  "order": 4,
                  "overview": true,
                  "important": false,
                  "userChooser": true,
                  "searchAggregation": true,
                  "searchAggregationOrder": 2
              },
              {
                  "name": "location",
                  "type": "TEXT",
                  "order": 5,
                  "overview": false,
                  "important": true,
                  "userChooser": false,
                  "searchAggregation": true,
                  "searchAggregationOrder": 3
              },
              {
                  "name": "education",
                  "type": "TEXT",
                  "order": 6,
                  "overview": false,
                  "important": false,
                  "userChooser": false,
                  "searchAggregation": false
              }
          ],
          "modifiable": true
      }          
              
  4. Führe einen PUT-Request an den Endpunkt /api/users/profile/groups/<group_id> aus. Die <group_id> befindet sich oben in der Antwort der Gruppe nach "id" (fett markiert im obigen Beispiel)

Du solltest eine Antwort erhalten, die die Profilgruppe mit deinen Änderungen enthält. Überprüfe die Plattform, um zu sehen, ob deine Änderungen angewendet wurden.

Screenshot 2023-11-21 at 16.55.57.png

Wenn du beim Aufrufen der API auf Fehler stößt, ist eine häufige Fehlerquelle die Syntax des Body. Stelle bitte sicher, dass alle Klammern geschlossen sind, alle Parameter in Anführungszeichen stehen und dass zwischen den einzelnen Feldern in der Liste Kommas vorhanden sind.

Schritt 3: Sprachschlüssel hinzufügen oder bearbeiten

Beispiel-Feld: Pronomen

Ein weiteres Beispiel für ein neues Profilfeld ist das Hinzufügen eines Pronomen-Feldes. Dafür kannst du die folgende Anfrage verwenden:

 {
     "name": "haiilo_pronouns",
     "type": "TEXT",
     "order": 1,
     "overview": true,
     "important": false,
     "userChooser": false,
      "searchAggregation": false
 }      

Solange der Name als haiilo_pronouns eingegeben wird, werden die Pronomen nach dem Anzeigenamen des Nutzers in der Profilkarte hinzugefügt (siehe Bild oben).

Wenn du deine Haiilo-Plattform nach Version 45.0.90 eingerichtet hast, ist das Pronomen-Feld automatisch für deine Nutzer enthalten und du musst es nicht hinzufügen.

War dieser Beitrag hilfreich?