Profil-Import via REST API

Nutzer können auch via REST API in Just Social angelegt werden. Im Folgenden werden die nötigen Schritte dazu erläutert.

Login

Um die Profil-Import API benutzen zu können, muss zuerst ein OAuth Access Token abgefragt werden. Dazu muss folgender Request gestellt werden:

• URL: <JUST_URL>/toro/oauth/token
• http-Method: POST
• Parameter:
  • grant_type: client_credentials
  • client_id: profile-import
  • client_secret: Dieses wird dir mitgeteilt, sofern der Import via REST API eingerichtet werden soll

Ergebnis: JSON-Objekt das den Access Token im Feld access_token enthält.
Das Access Token muss in jedem weiteren Request im Authorization Header als Bearer-Token mitgeben werden (https://tools.ietf.org/id/draft-ietf-oauth-v2-bearer-20.html#authz-header).

Ist die Gültigkeit des Tokens abgelaufen, wird der http Status 401 (Unauthorized) zurückgegeben. Dann muss ein neuer Access Token angefordert werden.

Import

• URL: <JUST-URL>/toro/profile-migration/api/v1/import
• http-Method: POST
• Parameter: Der Parameter wird als Request Body in Form eines JSON Objekts übergeben. In dem folgenden Code-Snippet sind alle möglichen Felder mit ihren jeweiligen Typen aufgeführt. Am Ende der Seite befindet sich ein Beispiel mit den wichtigsten Feldern. Sofern optionale Werte nicht gefüllt werden sollen, können diese komplett weggelassen werden.

{
  "profile": {
    "externalId": "string",
    "baseAttributes": {},
    "profileAttributes": {},
    "blockUser": true,
    "roles": [
      "string"
    ]
  },
  "termsAccepted": true,
  "replaceExistingRoles": true,
  "sendMailToNewUser": true,
  "activateNewUser": true,
  "reimportDeletedUser": true,
  "importMode": "INSERT_ATTRIBUTES_ONLY",
  "addedUserGroupMemberships": [
    "string"
  ],
  "removedUserGroupMemberships": [
    "string"
  ]
}

Erklärung der Parameter:

• profile: enthält alle Personen-bezogenen Attribute:
  • externalId: eine pro Person eindeutige ID; muss für funktionierende Updates immer den jeweils gleichen Wert haben; Pflichtfeld. Für SSO mit AD FS muss hier die objectGUID verwendet werden (Benötigt, darf nicht leer sein)
  • baseAttributes: Plattform-unabhängige Basis-Attribute, wie z.B. firstname, lastname, email (s. Beispiel am Ende für mehr der möglichen Attribute);
    • firstname - String (benötigt)
    • lastname - String (benötigt)
    • email - String (benötigt)
    • active - true/false (optional, aktiviert/deaktiviert Nutzerprofile, beim Anlegen neuer Profile "activateNewUser" verwenden, siehe unten)
  • profileAttributes: Plattform-abhängige Profil-Attribute; die möglichen Attribute hängen von der Konfiguration deiner Just-Installation ab.
  • blockUser: Flag, ob die Person gesperrt (true) bzw. entsperrt (false) werden soll. Wenn das Flag weggelassen wird, wird der Blockiert-Status nicht verändert.
  • roles: Liste der Rollen die die jeweilige Person haben soll; muss die korrekten Wert haben, wie sie von Just erwartet werden; ggf. sind die Werte Plattform-spezifisch
• termsAccepted: ob bei Neuanlage einer Person diese den AGB schon zugestimmt haben soll oder nicht. (Standard: false)
• replaceExistingRoles: ob beim Update die ggf. spezifizierten Rollen die bestehenden überschreiben oder nur hinzugefügt werden sollen. (Standard: true, Rollen überschreiben)
• sendMailToNewUser: ob neuen Personen Begrüßungs-E-Mails zugeschickt werden sollen; Standard ist false; Hinweis: wird kein Passwort importiert, wird ein zufälliges vom System erzeugt; in diesem Falle sollten Begrüßungs-E-Mails unbedingt aktiviert werden! (Standard: false, keine Mail versenden)
• activateNewUser: ob neue Personen direkt aktiviert sind, oder dies erst noch erfolgen muss (Standard: true, User aktivieren)
• reimportDeletedUser: ob schon einmal gelöschte Personen wieder importiert werden sollen. Andernfalls werden sie übersprungen. (Standard: true, gelöschte Nutzer neu importieren)
• importMode: gibt an, wie die statischen und dynamischen Attribute gehandhabt werden. Es gibt drei verschiedene Möglichkeiten:
  • INSERT_ATTRIBUTES_ONLY: Attribute werden nur gespeichert, wenn die Person eingefügt wird, nicht aber wenn die Person aktualisiert wird.
  • UPDATE_NON_EMPTY_ATTRIBUTES: nur nicht leere Attribute werden gespeichert (egal ob die Person eingefügt oder aktualisiert wird)
  • (Standard) DELETE_ATTRIBUTES: leere Attribute werden gelöscht (leere Attribute müssen dann aber im Import weiterhin aufgeführt werden, z.B. “website”:””); Standardwert, wenn kein Mode angegeben wird
• addedUserGroupMemberships: IDs der Nutzergruppen, zu denen der Nutzer hinzugefügt werden soll.
• removedUserGroupMemberships: IDs der Nutzergruppen, aus denen der Nutzer entfernt werden soll.

Ergebnis: JSON-Objekt der Form:

{
  "resultType":"string",
  "reason":"string"
}

resultType kann die folgenden Werte haben:

• INSERTED: die Person wurde neu angelegt
• UPDATED: die Person wurde als schon mal importiert erkannt und entsprechend aktualisiert
• SKIPPED: die Person wurde übersprungen
• ERROR: es ist ein Fehler aufgetreten

Ist der resultType SKIPPED oder ERROR, wird in reason ein Grund angegeben. Das Feld kann folgende Werte haben: MISSING_EXTERNAL_ID, MISSING_EMAIL, MISSING_FIRSTNAME, MISSING_LASTNAME, INVALID_INTERNAL_ID, EXCEPTION, DELETED_IN_JUST, UNKNOWN

Und nun ein Beispiel:

{
  "profile": {
    "externalId": "1",
    "baseAttributes": {
      "firstname": "Lore",
      "lastname": "Schmidt",
      "title": "Doktor",
      "birthdayGerman": "10.02.1999",
      "email": "lore.schmidt@just.social"
    },
    "profileAttributes": {
      "UNTERNEHMEN": "Acme Inc.",
      "STRASSE": "Schöne Strasse 42",
      "PLZ": "22111",
      "ORT": "Hamburg",
      "EMAIL": "lore.schmidt@just.social",
      "INTERNET": "acme.com",
      "FAX": "0123456789",
      "TELEFON": "9876543210",
      "FUNKTION": "Bereichsleiterin",
      "Bereich": "Öffentlichkeitsarbeit",
      "Abteilung": "Social Media"
    },
    "blockUser": true,
    "roles": [
      "EHRENAMT"
    ]
  },
  "termsAccepted": false,
  "sendMailToNewUser": true,
  "activateNewUser": true,
  "reimportDeletedUser": true,
  "importMode": "DELETE_ATTRIBUTES",
  "addedUserGroupMemberships": [
    "62e1cb58-5e3e-4d5a-8562-266f04909a77"
  ],
  "removedUserGroupMemberships": [
    "7481fc04-1048-40cc-b515-7040ba3cefe1"
  ]
}