Wie schlägt man viele Fliegen mit einer Klappe? – Automatisierte Anpassung von hunderten von Adobe Analysis Workspace-Projekten

on 28.07.2021 by FELD M Data Product Team

Vor einiger Zeit hatten wir aufgrund der Entscheidung der Rechtsabteilung eines unserer Kunden die Aufgabe, einen wichtigen Hinweis zur Weitergabe der Daten in hunderte von Adobe Analysis Workspace-Projekten hinzuzufügen. Die folgenden Anforderungen galt es zu erfüllen:

  • Jedes Projekt sollte ein neues Panel mit dem Disclaimer an erster Stelle vor allen anderen Elementen innerhalb des Reports enthalten.
  • Die Report Suite im ersten (=Disclaimer-) Panel sollte dieselbe Report Suite sein wie im dann zweiten Panel der Workspace Projekte.
  • Der Zeitraum für das Reporting im ersten (=Disclaimer-) Panel sollte derselbe Zeitraum sein wie im dann zweiten Panel der Workspace Projekte.
  • Alle Workspace Projekte sollten mit einem Tag gekennzeichnet werden, das besagt, dass ein Panel mit dem Hinweis zur Weitergabe der Daten enthalten ist.

Da eine manuelle Anpassung aller Projekte einen enormen Zeitaufwand und gleichzeitig ein großes Fehlerpotenzial mit sich gebracht hätte, suchten wir nach einer Möglichkeit, die Reports über eine API anzupassen.

 

Die Lösung

Voraussetzungen

Wir sind sowohl mit der Adobe Analytics API 1.4 als auch mit der Adobe Analytics API 2.0 bestens vertraut und haben sie bereits in mehreren Projekten genutzt. Allerdings bietet keine dieser Schnittstellen die Möglichkeit, Workspaces zu erstellen oder anzupassen. Wir waren kurz davor, in den sauren Apfel zu beißen und alle Workspace Projekte manuell anzupassen, als wir auf ein Repository mit der Methode „updateProject“ gestoßen sind, die unsere Aufmerksamkeit erregte. Der Autor dieser Library (falls du diesen Artikel liest, Julien Piccini: vielen Dank für deine großartige Arbeit!) hat dem Project-Endpunkt besondere Aufmerksamkeit gewidmet und eine separate readme verfasst.

Die wichtigsten Erkenntnisse für unseren Anwendungsfall waren folgende:

  • Die Methoden `getProject` und `getProjects` sind BETA und können jederzeit aufhören zu funktionieren
  • Die Library funktioniert nicht für alle Workspaces, da sich die interne Struktur der Workspaces im Laufe der Zeit weiterentwickelt hat
  • Die Methode `updateProject` erwartet die gesamte Definition des Workspaces und führt eine PUT-Operation durch, d. h. sie ersetzt den vorhandenen Inhalt vollständig

 

Erste Schritte – ein Netz mit doppeltem Boden

Nachdem wir die oben beschriebenen Methoden entdeckt hatten, starteten wir umgehend mit ersten Experimenten in unserer Adobe Analytics Sandbox, um herauszufinden, ob die Methoden für unseren Anwendungsfall geeignet wären. Um erste Tests durchzuführen, begannen wir mit dem Bau eines eigenen Python-Clients mit Fokus auf den Endpunkt `project` und mit einer OAuth-Integration. Wir entschieden uns gegen eine JWT-Integration, da dies zusätzliche Abstimmungen mit unserem Kunden erfordert hätte. Nach etwas programmieren war alles bereit: Wir konnten einige Beispiel-Workspace Projekte abrufen und deren Struktur tiefergehend untersuchen.

Die Library hat eine eigene Representation der Workspaces wofür die heruntergeladenen Daten geparsed werden müssen. Da sich wie eingangs erwähnt die interne Struktur geändert hat, funktioniert dies nur mit relativ aktuellen Workspaces. In unserem Fall reichte es jedoch, die plain JSON Daten zu verwenden, sodass wir in gewissen Grenzen trotzdem mit den Daten arbeiten konnten.

Untersuchen wir nun die Struktur eines einfachen Workspaces, der ausschließlich unsere gewünschte Information zur Weitergabe der Daten enthält:

{
    'accessLevel': 'edit',
    'approved': False,
    'companyTemplate': False,
    'created': '2021-05-21T10:00:00Z',
    'definition': {
        // We'll have a look into this later
    },
    'description': '<PROJECT DESCRIPTION>',
    'favorite': False,
    'id': '<PROJECT ID>',
    'modified': '2021-05-21T11:00:00Z',
    'name': '<PROJECT NAME>',
    'owner': {
        'id': -1,
        'login': 'XXX',
        'name': 'XXX'
    },
    'reportSuiteName': '<REPORTSUITE NAME>',
    'rsid': '<REPORTSUITE ID>',
    'shares': [{
        'accessLevel': 'edit',
        'componentId': '<PROJECT ID>',
        'componentType': 'project',
        'shareId': -1,
        'shareToDisplayName': 'Firstname Lastname',
        'shareToId': -1,
        'shareToLogin': 'firstname.lastname@example.com',
        'shareToType': 'user'
    }],
    'siteTitle': '<SITE TITLE>',
    'tags': [],
    'type': 'project'
}

 

Definition und Version

Beim Durchsuchen der Root-Struktur unseres Testprojekts konnten wir unsere beiden Anknüpfungspunkte identifizieren: `definition` und `tags`. `definition` enthält die Definition über den Aufbau und Inhalt des Workspaces, wohingegen `tags` eine Liste an zugewiesenen Tags enthält. Letzteres wollten wir nutzen, um zu verfolgen, welche Reports bereits mit der Information zur Weitergabe der Daten versehen wurden.

Werfen wir nun einen genaueren Blick auf die `definition` des Projekts:

'definition': {
    'additionalCuratedComponents': [],
    'countRepeatInstances': True,
    'currentWorkspaceIndex': 0,
    'customColorSchemes': [],
    'isCurated': False,
    'version': '28',
    'viewDensity': 'expanded',
    'workspaces': []
}

Ein wichtiger Aspekt innerhalb der ‚definition‘ ist das Attribut `version`, dass die Adobe-interne Version des Workspaces angibt. Unsere Tests ließen darauf schließen, dass sich die intene Struktur zwischen den Versionen 20 und 21 verändert hat. Nach unseren Erkenntnissen ist diese Veränderung der Grund für „The definitions are not consistent over time, therefore the Project class may not work on old projects“ [Quelle], wie vom Autor der Library angegeben. Um auf Nummer sicher zu gehen, haben wir uns auf Projekte mit einer `version` größer oder gleich 21 konzentriert. In unserem Fall waren das glücklicherweise die meisten Projekte, die wir modifizieren mussten.

Eine (für uns) unerwartete Tatsache ist, dass der Datentyp von `workspaces` ein Array ist, da wir eine 1:1 Beziehung erwartet hätten. In allen zu modifizierenden Projekten sind wir auf keinen einzigen Fall gestoßen, in dem die Länge des Arrays `workspaces` ungleich 1 war. Um unerwartetes Verhalten zu vermeiden, fügten wir unserem Code dennoch Prüfungen hinzu, die die Ausführung stoppen würden, sollte unsere Annahme von genau einem Workspace nicht erfüllt sein.

Das Element `panels` innerhalb von `workspace` enthält die eigentlichen Elemente des Projekts.

Der untenstehende Code zeigt den Code des Beispielpanels mit dem Hinweis zur Weitergabe der Daten, das wir hinzufügen sollten:

{
    'annotations': [],
    'collapsed': False,
    'dateRange': {
        'id': 'thisMonth',
        '__entity__': True,
        'type': 'DateRange',
        '__metaData__': {
            'name': 'This month'
        }
    },
    'description': '',
    'id': 'BBBBBBBB-BBBB-BBBB-BBBB-BBBBBBBBBBBB',
    'name': '<PANEL NAME>',
    'position': {
        'autoHeight': 200,
        'autoSize': True,
        'width': 100,
        'x': 0,
        'y': 0
    },
    'reportSuite': {
        'id': '<REPORTSUITE ID>',
        '__entity__': True,
        'type': 'ReportSuite',
        '__metaData__': {
            'name': '<REPORTSUITE NAME>',
            'rsid': '<REPORTSUITE ID>'
        }
    },
    'segmentGroups': [],
    'subPanels': [
        {
            'collapsed': False,
            'description': '<SUBPANEL DESCRIPTION>',
            'id': 'CCCCCCCC-CCCC-CCCC-CCCC-CCCCCCCCCCCC',
            'isQuickInsightsSubPanel': False,
            'linkedSourceId': '',
            'name': '<SUBPANEL NAME>',
            'position': {
                'autoHeight': 127,
                'autoSize': True,
                'width': 100,
                'x': 0,
                'y': 0},
            'reportlet': {
                'isConfigVisible': True,
                'name': '<REPORTLET NAME>',
                'showVizSelectorOnSubPanel': False,
                'textContent': '{"ops":[{"insert":"<HERE GOES OUR DISCLAIMER>.\\n"}]}',
                'type': 'TextReportlet',
                'useRowBasedPercentages': False
            },
            'swatchColor': '#BB0A30',
            'type': 'genericSubPanel',
            'visible': True,
            'visualizationIndex': 1
        }
    ],
    'type': 'panel'
}

 

Es geht los: Wir fügen Panels automatisiert zu diversen Workspace Projekten hinzu!

Da sich die Daten recht einfach auf die in der Benutzeroberfläche angezeigten Informationen abbilden lassen (Report Suite-Informationen, Panel-Namen usw.), fühlten wir uns zuversichtlich genug, unsere Strategie zur Anpassung der Workspaces über die API weiter zu verfolgen. In einem ersten Test begannen wir damit, das Panel mit dem Hinweis zur Weitergabe der Daten zu einem Test-Workspace hinzuzufügen (indem wir einfach die oben gezeigten Daten zur Liste `panels` hinzufügten), um die Auswirkungen auf die Struktur weiter zu untersuchen. Dieser erste Schritt führte zu folgenden Erkenntnissen:

  • Es scheint so, als ob Adobe-seitig keine umfangreiche Validierung stattfindet, da die `id`s exakt so übernommen wurden, wie sie sind (was zu Duplikaten führt).
  • Die Positionierung im Workspace UI sieht gut aus, auch wenn die Positionen mehrere Panels rechnerisch kollidieren würden.

Da diese Attribute einfach berechnet werden können, beschlossen wir, diese zu ändern, indem wir die Positionen dynamisch berechnen (indem wir die Größe des Disclaimers zur `y`-Koordinate der folgenden Panels addieren/UUIDs für den Disclaimer generieren).

Nachdem diese Anpassungen kodiert waren, starteten wir einen neuen Versuch. Wie bereits erwähnt, mussten die folgenden Anforderungen erfüllt werden:

  • Jedes Projekt sollte ein neues Panel mit dem Disclaimer an erster Stelle vor allen anderen Elementen innerhalb des Reports enthalten.
  • Die Report Suite im ersten (=Disclaimer-) Panel sollte dieselbe Report Suite sein wie im dann zweiten Panel der Workspace Projekte.
  • Der Zeitraum für das Reporting im ersten (=Disclaimer-) Panel sollte derselbe Zeitraum sein wie im dann zweiten Panel der Workspace Projekte.
  • Alle Workspace Projekte mussten mit einem Tag gekennzeichnet werden, das besagt, dass ein Panel mit dem Hinweis zur Weitergabe der Daten enthalten ist.

Glücklicherweise funktionierte die Anpassung problemlos – mit einer Ausnahme:

Wir stellten fest, dass unsere zugewiesenen Tags nicht angehängt wurden (wir probierten verschiedene Kombinationen aus, wie man Tags zum Projekt hinzufügen kann, aber leider ohne Erfolg). Ein Blick auf andere vorhandene (nicht BETA-) API-Endpunkte zeigt, dass die Methode `PUT` beispielsweise für Segmente angibt, dass Tags nicht verarbeitet werden. Daher nahmen wir an, dass dies auch für den Project-Endpunkt der Fall sein könnte.

Aufgrund dieses Verhaltens wurde ein weiterer Schritt notwendig, in dem die Tags zugewiesen wurden, nachdem der Workspace selbst aktualisiert worden war. Da das Tagging von Adobe gut dokumentiert ist, war dies jedoch glücklicherweise kein Showstopper und funktionierte problemlos.

 

Auf den Punkt gebracht: Welche Schritte müssen unternommen werden?

Im Folgenden stellen wir noch einmal unser Vorgehen im Überblick dar:

  1. Erstellung eines Workspace Projekts, das ein Panel mit dem Hinweis zur Weitergabe der Daten enthält. Dieses Projekt dient als Vorlage und wird den zu modifizierenden Workspace Projekten hinzugefügt.
  2. Iteration durch die Projekte, die aktualisiert werden sollen
    1. Speichern aller Informationen, die über die API für das Projekt gesammelt werden können
    2. Prüfung der Vorbedingungen (Tag bereits vorhanden, Disclaimer bereits vorhanden, Workspace-Version, …)
    3. Generierung der UUIDs für den Hinweis zur Weitergabe der Daten
    4. Erstellung einer Liste von Panels mit dem Hinweis zur Weitergabe der Daten an der ersten Position, gefolgt von allen vorhandenen Panels und Zuweisung dieser entsprechend der Definition
    5. Anpassung der Koordinaten für die vorhandenen Bereiche
    6. Ausführung der PUT-Operation am Project-Endpunkt
    7. Speichern der modifizierten Workspace Projekte die an den Project-Endpunkt gesendet wurden
    8. Zuweisung eines Tags zum aktualisierten Projekt

Alles in allem verlief der Prozess sehr reibungslos und ohne einen einzigen von Adobe ausgelösten Fehler. Eine stichprobenartige manuelle Prüfung einiger modifizierter Workspace Projekte zeigte, dass die Disclaimer korrekt entsprechend der Anforderungen hinzugefügt wurden.

 

Unsere wichtigsten Erkenntnisse

  • Es gibt einen inoffiziellen Project-Endpunkt in den Adobe 2.0 APIs, mit dem es relativ einfach möglich ist, Änderungen an Workspace-Projekten vorzunehmen (in unserem Falle das Hinzufügen von zusätzlichen Panels mit einem Hinweis zur Weitergabe der Daten).
  • Nicht alle Workspaces sind geeignet, um über die API modifiziert zu werden (nach unseren Erkenntnissen müssen Workspaces mindestens die Version 21 aufweisen).
  • On the fly tagging ist nicht möglich, daher mussten Tags über einen weiteren Request hinzugefügt werden.
  • Es findet keine umfangreiche Validierung auf Adobe-Seite statt (doppelte IDs, kollidierende Koordinaten etc.).

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert