SAP Integration Suite - Open Connectors Einrichtung & Tests

Erstellen und Testen eines Connectors in der SAP Integration Suite für die ENLYZE Platform API

Erstelle und teste einen Custom Connector in der SAP Integration Suite → Open Connectors für die ENLYZE REST API, indem du einen API-Key und einen PreRequest Hook verwendest, um den Upstream-Header Authorization: Bearer <api-key> einzusetzen. Anschließend überprüfen wir den Connector mit Abfragen über die API Docs.

Architektur in 90 Sekunden

Open Connectors trennt zwei Authentifizierungsebenen, die sowohl in der UI als auch in cURL sichtbar sind:

1. SAP Open Connectors Auth (Plattform) — in API Docs als Header Authorization: User <…>, Organization <…>, Element <…>. Das authentifiziert dich gegenüber Open Connectors.

2. Vendor (ENLYZE) Auth — fügen wir per PreRequest Hook als Authorization: Bearer <ENLYZE_API_KEY> hinzu.

Wichtig: Beides strikt trennen. Kein Bearer‑Token in das API Docs Authorization‑Feld eintragen. Dieses Feld ist für Open Connectors. Den ENLYZE‑Header setzt der Hook automatisch.

Voraussetzungen

• Einen ENLYZE API-Key für das Ziel-Tenant. Wie du einen anlegst, erfährst du unter API-Keys verwalten. Für produktive Integrationen wird ein Organisations-API-Key empfohlen.

• Zugriff auf SAP Integration Suite → Open Connectors mit Rechten für den Connector Builder.

• Zugang zur SAP Integration Suite → Open Connectors mit Connector Builder-Berechtigungen. Das Tutorial Set Up Integration Suite Trial ist ein guter Einstieg, um mit der SAP Integration Suite loszulegen. Achte darauf, dass in der Integration Suite die richtigen Capabilities aktiviert sind. Du benötigst:

  • Build Integration Scenarios

  • Manage APIs

  • Extend Non-SAP Connectivity

  Mit Extend Non-SAP Connectivity kannst du neue Connectoren erstellen.

Schritt 1: ENLYZE OpenAPI importieren

1. In Open Connectors → Connectors klicke auf Build New Connector

   

   Nutze die Import-Option, um den neuen Konnektor zu erstellen:

   
2. Wähle Swagger aus und importiere die API-Spezifikation von folgender URL: https://app.enlyze.com/api/v2/openapi.json

   

   Klicke Continue Import.

3. Wähle die benötigten Ressourcen (Endpunkte) aus. Eine gute Basis sind:

   • GET /v2/machines, /v2/sites, /v2/variables, /v2/production-runs, /v2/downtimes, /v2/products, /v2/data-sources

   • POST /v2/timeseries (read time series) und POST /v2/machines/{uuid}/productivity-metrics

   

Der Element Key muss im Tenant eindeutig sein.

Schritt 2: Properties

Nachdem die Ressourcen importiert sind, musst du den Authentifizierungsmechanismus konfigurieren. Wir verwenden eine Custom Authentication, bei der das Token zu Beginn des Connector-Setups bereitgestellt und anschließend bei jeder Anfrage über einen PreRequest Hook mitgegeben wird.

In Setup → Properties:

• Base URL: https://app.enlyze.com/api/

• Pagination Type: cursor

• Accept/Content-Type: application/json

• Authentication type: custom

Schritt 3: Configuration (Token speichern)

In Setup → Configurations hinzufügen:

• Name: API Token

• Key: api.token (auto)

• Type: text 128

• Required: ON

• Description: ENLYZE API Token (or a more detailed description)

Wir legen keinen globalen Authorization Parameter an. Der Hook setzt den Vendor‑Header für jeden Request.

Schritt 4: PreRequest Hook

In Setup → Hooks → PreRequest Hook einfügen:

let token = configuration['api.token'];
request_vendor_headers.Authorization = `Bearer ${token}`;
done({"request_vendor_headers":request_vendor_headers,      
      "contintue":true});

Warum das funktioniert

• configuration['api.token'] liest den Instanz‑Token.

• request_vendor_headers adressiert die provider‑seitigen Header (geht an ENLYZE).

• Durch done({ request_vendor_headers }) wird der Header für den Outbound‑Call gesetzt.

Hierdruch wird {“Authorization”:”Bearer XXXXX”} im Header für jede Abfrage gesetzt.

Klicke Save.

Schritt 5: Testen des Konnektors - Instanz erstellen

Aus Resources (oder Instances) Authenticate instance wählen:

• Name: free text (e.g., Test Instance)

• API Token: nur den Token einfügen (ohne Bearer )

Konfiguration der Instanz:

Klicke Create Instance.

Schritt 6: Testen des Konnektors - über die API docs

Im Instance → API Docs eine einfache Resource öffnen, z. B. GET /v2/machines.

1. Das Authorization Feld mit dem vorausgefüllten Open Connectors Wert (User/Organization/Element) unverändert lassen.

2. Execute klicken.

3. Es sollte eine 200 Antwort mit JSON geben. Das generierte cURL nutzt i. d. R. einen Pfad wie:

https://api.openconnectors.<region>.ondemand.com/elements/api-v2/v2/machines
# Header sent to OC (platform auth):
-H "Authorization: User <…>, Organization <…>, Element <…>"

Open Connectors forwardet unseren Hook‑Header an ENLYZE:

Authorization: Bearer <your ENLYZE API key>

Tipps: Für erste Tests /v2/sites oder /v2/machines. Bei zeitbasierten Endpoints sinnvolle start/end oder cursor Parameter setzen.

Ausführen eines Endpunkt-Tests über die UI:

Erfolgreiche Antwort:

Fehlerbehebung

401 "User is not authorized" in den API Docs

• Du authentifizierst nicht gegenüber Open Connectors: Das API Docs Authorization Feld muss User…, Organization…, Element… enthalten (normalerweise vorausgefüllt). Kein Bearer dort eintragen.

401 von ENLYZE (vendor)

• Der Upstream‑Header wurde nicht gesetzt. PreRequest Hook prüfen, speichern und Instance neu erstellen/reauthorisieren. Token prüfen (ohne Bearer).

Interner Fehler / Timeouts bei Aufrufen gegen /elements/api-v2/...

• Pfad exakt wie in API Docs verwenden. Bei Swagger‑Import ist es typischerweise /elements/api-v2/v2/...

Doppeltes /v2 oder falsche Base

• Base URL https://app.enlyze.com/api/ beibehalten und Resource Paths /v2/... (wie im Swagger Import).

Appendix - Beispiele

Beispiel: cURL über Open Connectors Instance (API Docs‑Stil)

curl -X GET \
  "https://api.openconnectors.<region>.ondemand.com/elements/api-v2/v2/machines"  \
  -H "Accept: application/json" \
  -H "Authorization: User <USER_SECRET>, Organization <ORG_SECRET>, Element <ELEMENT_TOKEN>"

Beispiel: Direkter ENLYZE cURL (ohne Open Connectors)

curl -X GET "https://app.enlyze.com/api/v2/machines" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <YOUR_ENLYZE_API_KEY>"

Direktaufrufe nur für lokales Debugging. In SAP immer über die Connector Instance aufrufen, damit Logging, Throttling und Mappings greifen.