Inkrementeller Benutzerbericht (Job-API)

Übersicht

Der inkrementelle Benutzerbericht von Adobe Learning Manager ist eine neue Job-API-Funktion, mit der Administratoren und Integrationsentwickler nur die Benutzer exportieren können, deren Daten sich in einem bestimmten Datum- und Uhrzeitfenster geändert haben. Anstatt jedes Mal die vollständige Benutzerliste abzurufen, können Sie ein gezieltes Slice anfordern, das nur neue oder geänderte Benutzer abdeckt.

Dieses Dokument behandelt Folgendes:

Gründe für die Verwendung von inkrementellen Berichten

Dieser Abschnitt erläutert die Motivation für die Funktion und sollte Ihnen bei der Entscheidung helfen, ob inkrementelle oder vollständige Exporte am besten zu Ihrer Integration passen.

Das Problem mit Vollbenutzer-Exporten

Der aktuelle Vollbenutzerexport (generateUsers-Auftragstyp) gibt bei jeder Ausführung jeden Benutzer in einem Konto zurück. Bei Großunternehmen führt dies zu zwei erheblichen Problemen:

​* Bei diesen Größenordnungen läuft die Export-Pipeline bei einer CPU-Auslastung von ca. 90 %, während Daten abgerufen, verarbeitet und gespeichert werden.
​* Nachgeschaltete Dashboards (PowerBI, Salesforce, benutzerdefinierte Integrationen) führen bei jedem Durchlauf unveränderte Benutzerdatensätze ein, wodurch Bandbreite und Verarbeitungszeit verschwendet werden.
​* Es gibt keine Möglichkeit zu fragen, “welche Benutzer sich seit meinem letzten Export geändert haben?” mit der aktuellen API verwenden.

Verwendung von inkrementellen Berichten

Verwenden Sie den inkrementellen Export, wenn ein externes System mit den Adobe Learning Manager-Benutzerdaten synchronisiert bleiben muss. Typische Anwendungsfälle:

​* Aktualisieren eines Unternehmens-Dashboards (PowerBI, Tableau, SFDC) mit Änderungen an Benutzerprofilen
​* Einspeisung nachgelagerter Identitätsverwaltungssysteme mit Rollen-, Status- oder Metadatenänderungen.
​* Delta-Sync-Pipelines werden nachts oder stündlich ausgeführt, anstatt vollständige Neuladungen vorzunehmen.
​* Reduzierung der Kosten für API-Laden und -Datenübertragung für Konten mit Millionen von Benutzern.

Verwenden Sie den vollständigen Export (generateUsers), wenn Sie eine autoritative Grundlinie benötigen, z. B. bei der ersten Einrichtung oder nach einer langen Lücke zwischen den Synchronisationen.

Aktueller vollständiger Benutzerbericht

(generateUsers) Dieser Abschnitt dokumentiert den vorhandenen Bericht des Job-API-Benutzers als Referenz. Wenn Sie bereits damit vertraut sind, fahren Sie mit dem nächsten Abschnitt fort.

Funktionsweise

Der aktuelle CSV-Benutzerbericht wird als Auftrag über die Jobs-API gesendet. Eine Snaplogic-Pipeline nimmt den Task auf, führt eine MySQL-Abfrage für die CAPTIVATE-Datenbank aus (user, usergroup, usergroup_user-Tabellen) und generiert eine CSV-Datei.

Verfügbare Filter

Die Nutzlast unterstützt drei optionale Filter:

​* expandMetadata - Übergeben Sie true, um Metadaten als separate Spalte zu exportieren.
​* fetchActiveUsers - Übergeben Sie true, um nur aktive Benutzer zu exportieren.
​* peerAccountId - So generieren Sie den Benutzerbericht für ein Peer-Konto.

CSV-Spalten

Die exportierte CSV-Datei enthält die folgenden Spalten:

internalUserID, userEmail, customerDefinedUniqueUserId, name, managerEmail,

userType, state, excludedFromGamification, pointsEarned, profile, roles,

dateCreated, lastLoginDate, dateDeleted, uiLocale, contentLocale,

timeZoneCode, userSource, group, AF_location, AF_login, AF_externalaf,

lastSocialActivityDate

Nutzlast anfordern

Jobtyp: generateUsers an. Nur Administratorrolle.

{

  "data": {

    "type": "job",

    "attributes": {

      "description": "<description of your choice>",

      "jobType": "generateUsers",

      "payload": {

        "expandMetadata": "<true to export metadata as separate column>",

        "fetchActiveUsers": "<true to export ACTIVE users only>",

        "peerAccountId": "<peerAccountId for peer account report>"

      }

    }

  }

}

Einschränkungen

​* Keine datumsbasierte Filterung - jede Ausführung exportiert alle Benutzer.
​* Bei großen Konten nicht möglich - Pipeline-Ressourcenauslastung über ~1 Million Benutzer.
​* Keine inkrementelle oder Delta-Funktion.

Inkrementeller Benutzerbericht (generateUserIncrementalReport)

Dieser Abschnitt dokumentiert die neu eingeführte Funktion “Inkrementeller Benutzerbericht”.

Was ist ein inkrementeller Export?

Ein inkrementeller Export gibt nur Benutzer zurück, deren verfolgte Daten sich in einem angegebenen Start- und Enddatum-Zeit-Fenster geändert haben. Das Backend speichert einen Zeitstempel der letzten Änderung für die verfolgten Felder jedes Benutzers. Wenn Sie einen Bericht für ein bestimmtes Fenster anfordern, werden nur Benutzer einbezogen, deren letzte Änderung in dieses Fenster fällt.

Funktionsweise des Änderungsverfolgungsmodells

Adobe Learning Manager behält einen Zeitstempel der letzten Änderung bei, der aktualisiert wird, wenn sich ein nachverfolgtes Feld für einen Benutzer ändert.

Wenn Sie einen inkrementellen Bericht mit einem start_date_time und end_date_time anfordern, gibt das System Benutzer zurück, deren Zeitstempel der letzten Änderung innerhalb von [start_date_time, end_date_time] liegt. Wenn ein Benutzer sowohl innerhalb als auch nach dem Fenster geändert wurde (d. h. wenn er nach end_date_time erneut geändert wurde), wird dieser Benutzer nicht in den Bericht aufgenommen, da sein Zeitstempel der letzten Änderung jetzt außerhalb des Fensters liegt.

Für Änderungen verfolgte Felder

Ein Benutzer wird in einen inkrementellen Bericht aufgenommen, wenn eines der folgenden Felder geändert wurde:

Felder, die für Änderungen NICHT verfolgt werden

Die folgenden Felder werden in der CSV-Ausgabe angezeigt, lösen aber keine Aufnahme in einen inkrementellen Export aus, wenn sie sich ändern:

​* excludedFromGamification
​* pointsEarned
​* lastLoginDate
​* dateDeleted
​* dateCreated
​* userSource
​* lastSocialActivityDate

Ausgabeformat

Der inkrementelle CSV-Bericht hat dieselben Spalten und dasselbe Format wie der vollständige Benutzer-CSV-Bericht. Alle Spalten werden in derselben Reihenfolge angezeigt, einschließlich aller aktiven Feld- und Metadatenspalten - unabhängig davon, welche Felder für die exportierten Benutzer geändert wurden.

Neue Job-API für inkrementellen Benutzerbericht

Der inkrementelle Benutzerbericht verwendet die Job-API zum Generieren einer CSV-Datei, die Benutzer enthält, deren verfolgte Daten im angegebenen Datum- und Uhrzeitfenster geändert wurden. Verwenden Sie für große Resultsets dasselbe Paginierungsmodell, das weiter unten in diesem Dokument beschrieben wird: reichen Sie in jeder Anforderung dasselbe Datumsfenster ein und übergeben Sie die letzte in der vorherigen Antwort erhaltene Benutzer-ID als fromUserId, um den nächsten Textbaustein abzurufen.

Arbeitstyp

Jobtyp: generateUserIncrementalReport

Nutzlast anfordern

{

    "data": {

        "type": "job",

        "attributes": {

            "description": "description of your choice",

            "jobType": "generateUserIncrementalReport",

            "payload":{

                 "fullExport": <Pass true to export all users. If fullExport is true, fromDate and toDate are ignored>,

                 "expandMetadata": <Pass true to export metadata as separate columns>,

                 "fromDate": <Start of the change window in ISO format, for example 2020-01-01T18:30:00.000Z>,

                 "toDate": <End of the change window in ISO format, for example 2020-01-31T18:30:00.000Z>,

                 "fromUserId": <For paginated requests, pass the last userId received in the previous response>

            }

        }

   }

}

Nutzlastparameter

Übergeben Sie für den inkrementellen Export fromDate und toDate, um das Änderungsfenster zu definieren. Wenn die Ergebnismenge größer als ein Textbaustein ist, setzen Sie den Paginierungsvorgang fort, indem Sie dieselben fromDate und toDate senden und die letzten userId aus der vorherigen Antwort als fromUserId übergeben. Wenn fullExport auf “true” gesetzt ist, wird das Datumsfenster ignoriert und die API generiert einen Export für den gesamten Benutzer.

Verarbeitung großer Konten (500 KB+ Benutzer)

Benutzerberichte werden mithilfe einer Datenplattform-Pipeline generiert und die Ausgabe wird in Blöcken zurückgegeben, um große Konten zu unterstützen. Wenn ein inkrementeller Export mehr als 500.000 Benutzer umfasst, wird der Bericht umbrochen.

Seitenumbruchmodell

Um alle Seiten für einen großen inkrementellen Export abzurufen, übergeben Sie in jeder Anforderung die gleiche startDateTime und endDateTime und übergeben Sie außerdem die Benutzer-ID des letzten im vorherigen Textbaustein empfangenen Benutzers als fromUserId. Die API gibt die nächste Gruppe von bis zu 500.000 Benutzern zurück, deren Benutzer-ID größer ist als die übergebene fromUserId.

Paginierungsarbeitsablauf

Schritt 1: Senden Sie die erste Anforderung ohne fromUserId.

// First request – no fromUserId

{

  "payload": {

    "startDateTime": "2026-05-01T00:00:00Z",

    "endDateTime": "2026-05-31T23:59:59Z"

  }

}

Schritt 2: Erhalten Sie den ersten Block (bis zu 500.000 Benutzer). Notieren Sie sich die letzte Benutzer-ID in der Antwort.

Schritt 3: Senden Sie die nächste Anforderung, wobei Sie dasselbe Datumsfenster und die letzte Benutzer-ID aus der vorherigen Antwort als fromUserId übergeben.

// Subsequent request – pass last userId from previous response as fromUserId

{

  "payload": {

    "startDateTime": "2026-05-01T00:00:00Z",

    "endDateTime": "2026-05-31T23:59:59Z",

    "fromUserId": "<last userId from previous response>"

  }

}

Schritt 4: Wiederholen Sie diesen Vorgang so lange, bis eine Antwort weniger als 500.000 Datensätze zurückgibt. Dies weist darauf hin, dass Sie die letzte Seite erreicht haben.

Einschränkungen

Der inkrementelle Benutzerbericht ist absichtlich bereichsspezifisch. Die folgenden Funktionen befinden sich außerhalb des Anwendungsbereichs:

​* Kein Benutzerprüfungsbericht: Es wird nicht aufgeführt, welche spezifischen Felder geändert wurden.
​* Kein Vergleich alter/neuer Werte - der Bericht zeigt nur die aktuellen Feldwerte an.
​* Keine Zeitstempel pro Änderung - der Zeitpunkt einzelner Feldänderungen wird nicht angezeigt.
​* Keine Angabe der Anzahl der Änderungen - ein Benutzer, der einmal und ein Benutzer, der zehnmal geändert wurde, werden beim Export identisch angezeigt.
​* Das vorhandene Berichtsformat bleibt unverändert - die CSV-Spaltenstruktur ist mit dem vollständigen Benutzerbericht identisch.

Connector-Integration

Der inkrementelle Benutzerbericht wurde für die Verwendung in Adobe Learning Manager-Connectors (PowerBI, Salesforce und andere) als Dropdown-Ersatz für den vollständigen Benutzerbericht in regulären Synchronisierungs-Pipelines entwickelt. Auf diese Weise können Connectors, die heute generateUsers verwenden, zum inkrementellen Modell migrieren, ohne Änderungen am Downstream-Datenschema vorzunehmen.

Connectors können den inkrementellen Bericht für Delta-Sync verwenden und für Bootstrap oder Recovery auf den vollständigen Bericht zurückgreifen.