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

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.

Ü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ü* `DATE`: ISO 8601 formatierter Zeitstempel mit Datum, Uhrzeit und Offset-Informationen, z.B. 2023-06-08T12:34:56Z *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:

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
}

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.

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
}

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

Für ein neues Feld musst du eine neue Übersetzung erstellen, um den Namen des Feldes auf der Plattform zu ändern. Lies Haiilo API: Übersetzungen importieren für Anweisungen.
Für ein vorhandenes Feld kannst du den vorhandenen Sprachschlüssel bearbeiten. Lies Anpassen von Interface-Texten für Anweisungen.

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.