Profil-Import via REST API

Folgen

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: GET
  • 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 als Parameter access_token mitgegeben werden. 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",
   "subscriptions":[
      {
         "subscriptionType":"DEFAULT",
         "exclusive":true,
         "defaultEntityIds":[
            0
         ],
         "filterByEntityTypes":[
            "string"
         ]
      }
   ],
   "memberships":[
      {
         "defaultEntityIds":[
            0
         ],
         "replaceMembershipsForEntityTypes":[
            "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
  • subscriptions: Import von Abonnements; kann mehrere Blöcke beinhalten, um z.B. verschiedene Abo-Arten zu importieren; pro Block gibt es
    • subscriptionType:
      • RECOMMENDED: Benutzer kann Abo beenden, beim nächsten Import wird es auch nicht wieder hinzugefügt
      • PASSIVE: Benutzer kann Abo nicht beenden; Standardwert
    • exclusive: ob bestehende Abos durch die spezifizierten ersetzt werden sollen. Dabei werden nur Abos entfernt, die den Seitentypen der zu importierenden Seiten entsprechen. (Werden z.B. nur Organisationen abonniert, werden auch nur die bestehenden Abos von Organisationen ersetzt.) (Standard: false, bestehende Abos werden nicht ersetzt)
    • defaultEntityIds: die IDs der Seiten (als Zahl, z.B. 23) zu denen Abonnements erzeugt werden sollen
    • filterByEntityTypes: hier können Seitentypen angegeben werden; ist dieser Parameter gesetzt, werden alle IDs aus defaultEntityIds ausgefiltert, die nicht zu einem der Seitentypen gehören. Wenn diese Liste leer ist und exclusive auf true, dann werden alle Abos der Seitentypen gelöscht, von denen Instanzen in defaultEntityIds genannt werden (wenn z.B. Seite 1 und 2 WIKI sind und 3 und 4 GROUP und jemand darauf Abos hat, dann wird bei defaultEntityIds: 1 und exclusive=true und ohne Angabe der Seitentypen, das Abo zur Seite 2 (WIKI) gelöscht, 3 und 4 bleiben bestehen, da vom Typ GROUP keiner in den defaultEntityIds genannt wurde)
  • memberships: Import von Mitgliedschaften; kann mehrere Blöcke beinhalten; pro Block gibt es
    • defaultEntityIds: die IDs der Seiten (als Zahl, z.B. 23) zu denen Mitgliedschaften erzeugt werden sollen
    • replaceMembershipsForEntityTypes: Liste von Seitentypen; für Seiten dieser Typen werden beim Update die bestehenden Mitgliedschaften ersetzt, bei allen anderen den bestehenden hinzugefügt. In Just News lauten die technischen Bezeichnungen für die Seitentypen wie folgt: Organisation -> NETWORK, Newskanal -> GROUP

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",
   "subscriptions":[
      {
         "defaultEntityIds":[
            1,
            2,
            3
         ]
      },
      {
         "exclusive":true,
         "subscriptionType":"PASSIVE",
         "defaultEntityIds":[
            4,
            5,
            6
         ]
      }
   ],
   "memberships":[
      {
         "defaultEntityIds":[
            7,
            8,
            9
         ],
         "replaceMembershipsForEntityTypes":[
            "NETWORK",
            "GROUP"
         ]
      }
   ]
}
0 von 0 fanden dies hilfreich

Kommentare

0 Kommentare

Bitte melden Sie sich an, um einen Kommentar zu hinterlassen.