Adapter JSON für das Jitterbit Connector SDK

Die Benutzeroberfläche des Integration Studio für einen mit dem Jitterbit Connector SDK erstellten Connector wird durch eine JSON-Datei definiert, die in der JAR-Datei enthalten ist, die den Connector paketiert. Üblicherweise und standardmäßig heißt diese Datei adapter.json.

Der Name dieser Datei kann unterschiedlich sein, da der verwendete Name der ist, der im Jitterbit-Connector-UI-Eintrag der MANIFEST-MF-Datei angegeben ist:

Jitterbit-Connector-UI: adapter.json

Siehe Connector-Registrierung: Connector-Manifest für Details zur MANIFEST.MF-Datei.

Adapter JSON-Datei

Der Entwickler eines Connectors definiert alle UI-Komponenten in der adapter.json-Datei. Diese Komponenten werden angezeigt, wenn der Benutzer den Connector und seine Aktivitäten konfiguriert, und die eingegebenen Werte können vom Connector-Code abgerufen werden.

Struktur der Adapter JSON-Datei

Hier ist ein allgemeines Schema der JSON-Datei, die eine Connector-UI definiert, mit Platzhalterwerten, die als "<name>" angezeigt werden. Die verwendeten Begriffe und ihre Bedeutungen werden nach diesem Beispiel erläutert:

{
  "name": "<name>",
  "version": "1.0.0",
  "sandbox": true,
  "defaultActivityIcon": "<path-to-SVG-file>",
  "endpoint": {
    "displayName": "<display-name>",
    "icon": "<path-to-SVG-file>",
    "properties": [ "<properties>" ]
  },
  "activities": {
    "activity-1": {
      "displayName": "<display-name-1>",
      "icon": "<path-to-SVG-file>",
      "properties": [ "<properties>" ]
    },
    "activity-2": {
      "displayName": "<display-name-2>",
      "properties": [ "<properties>" ]
    },
    . . .
  }
}

In diesem Schema wurde ein Connector mit Eigenschaften für den Endpunkt und seine ersten beiden Aktivitäten definiert. Zusätzliche Aktivitäten können nach Bedarf hinzugefügt werden.

Für die Verbindung (die erscheint, wenn ein Endbenutzer den Connector im Integration Studio UI zum ersten Mal konfiguriert) kann eine Reihe von Eigenschaften definiert werden, die verwendet werden, um einen oder mehrere Schritte zu generieren, die der Endbenutzer abschließt, um die Verbindung zum Endpunkt zu konfigurieren.

Beachten Sie, dass der verwendete name und version der gleiche name und version sein müssen, unter dem der Connector registriert ist (siehe Connector-Registrierung).

Die sandbox-Eigenschaft kann auf true oder false gesetzt werden. Auf true gesetzt bedeutet, dass sich der Connector in der Entwicklung befindet und nicht von Harmony zwischengespeichert wird. Stattdessen wird bei jedem Aufruf der Connector vom Jitterbit-Privatagenten neu geladen. Sobald Sie eine Produktionsversion haben, können Sie dies auf false setzen, damit Caching verwendet werden kann, um die Nutzung zu beschleunigen.

Ein Satz von Eigenschaften wird für jede Aktivität definiert, um Schritte zur Konfiguration der Aktivität zu generieren, nachdem sie zu einem Vorgang im Integration Studio hinzugefügt wurde.

Endpoint-Icons

Wie im obigen Schema zu sehen ist, können Sie Icons für die Verbindung und jede der Aktivitäten definieren (gemeinsam als Endpoint bezeichnet). Icons werden mit SVG definiert und als Pfad zu einer SVG-Datei bereitgestellt.

Diese Schlüssel können in der adapter.json angegeben werden:

Im obigen schematischen Beispiel wurde ein Standard-Icon definiert, wobei die Verbindung und die erste Aktivität andere—vielleicht unterschiedliche—Icons verwenden. Die zweite Aktivität hat kein definiertes Icon und verwendet stattdessen das Standard-Icon.

Dieser Screenshot des Dropbox-Connectors zeigt, wie unterschiedliche Icons verwendet werden können:

Ein Icon (ein Ordner) wird für die Verbindung verwendet, während ein anderes Icon für die Aktivitäten verwendet wird. Es ist möglich, für jede Aktivität ein anderes Icon zu haben, obwohl ein gemeinsames Thema von Farben und Formen für einen Endpoint empfohlen wird. Beachten Sie, dass der Text, der die Aktivität beschreibt, über dem Icon liegt. Es ist am besten, die untere Hälfte des Icons in einer einheitlichen Farbe zu belassen, damit der weiße Text einen Hintergrund hat, gegen den er erscheinen kann.

Für Details zur Erstellung der SVG-Dateien, einschließlich Vorlagen und einer Schritt-für-Schritt-Anleitung, siehe Connector SDK UI Endpoint-Icons.

Aktivitäts- und Icon-Reihenfolge

Die Reihenfolge der Symbole in der Benutzeroberfläche sollte der Reihenfolge der Aktivitäten im JSON folgen. Wenn die Anzahl der Aktivitäten drei überschreitet, werden zusätzliche Zeilen von Aktivitäten in der Benutzeroberfläche unter der ursprünglichen Zeile hinzugefügt.

Unsere Empfehlung für die Reihenfolge der Aktivitäten ist, diesen gängigen Mustern zu folgen:

• Lesen, Schreiben
• Abfragen (oder Suchen), Erstellen, Aktualisieren, Upsert, Löschen
• Holen, Posten, Setzen, Löschen
• Anfrage, Antwort
• Herunterladen, Hochladen

Wenn es benutzerdefinierte, spezielle oder entitätsspezifische Aktivitäten außerhalb der obigen Beispiele gibt (wie z.B. Liste abrufen), sollten diese an den Anfang der Reihenfolge gesetzt werden, wenn sie dazu gedacht sind, Daten als Quelle in einer Operation bereitzustellen, und an das Ende, wenn sie dazu gedacht sind, Daten als Ziel in einer Operation zu empfangen.

Pagination

Für die Verbindung und jede Aktivität werden Eigenschaften in einer JSON-Struktur definiert. Diese erstellen die Konfigurationsschritte (Seiten), die ein Endbenutzer durchläuft, um die Verbindung und jede der spezifischen Aktivitäten, die er verwenden möchte, zu konfigurieren.

Default pagination

Verbindungen haben standardmäßig keine Paginierung. Für Verbindungen gibt es oft nur einen Schritt, obwohl der Entwickler so viele hinzufügen kann, wie benötigt werden.

Für Aktivitäten gibt es mindestens zwei Schritte: eine Anfangsseite mit einem Namensfeld und eine Endseite, die die Datenschemas zur Überprüfung anzeigt. Beide Seiten werden automatisch von der Infrastruktur erstellt und sind nicht im JSON-Dokument enthalten oder definiert.

In diesem Beispiel sind die Anfangs- (Seite 1) und End- (Seite 2) Schritte:

Single page

Wenn die Verbindung oder Aktivität auf einer einzigen Seite konfiguriert werden kann und keine Paginierung erforderlich ist, kann eine einfache Struktur verwendet werden:

. . .
"properties": [
  {
    "name": "<name-1>",
    "displayName": "<display-name-1>",
    "type": "string",
    "validators": [
      {
        "name": "required"
      }
    ]
  },
  {
    "name": "<name-2>",
    "displayName": "<display-name-2>",
    "type": "string",
    "validators": [
      {
        "name": "required"
      }
    ]
  }
]
. . .

Multiple pages

Wenn die Konfiguration jedoch länger ist, mit mehreren Werten, die festgelegt oder überprüft werden müssen, wird Paginierung empfohlen, um die Ansichten kleiner in der Tiefe zu halten:

. . .
"properties": [
  {
    "name": "page1",
    "displayName": "<display-name-page-1>",
    "type": "pagination",
    "children": [
      {
        "name": "<name-1-1>",
        "displayName": "<display-name-1-1>",
        . . .
      },
      . . .
    ]
  },
  {
    "name": "page2",
    "displayName": "<display-name-page-2>",
    "type": "pagination",
    "children": [
      {
        "name": "<name-2-1>",
        "displayName": "<display-name-2-1>",
        . . .
      },
      . . .
    ]
  }
]
. . .