> For the complete documentation index, see [llms.txt](https://docs.enlyze.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enlyze.com/integrations/sap/sap-integration-suite-open-connectors-einrichtung-and-tests.md).

# SAP Integration Suite - Open Connectors Einrichtung & Tests

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](/administration/api-keys.md). 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](https://developers.sap.com/tutorials/cp-starter-isuite-onboard-subscribe.html) 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.

<figure><img src="/files/Xwbp7TNMJRVkBF37GcuZ" alt=""><figcaption></figcaption></figure>

### Schritt 1: ENLYZE OpenAPI importieren

1. In **Open Connectors → Connectors** klicke auf **Build New Connector**<br>

   <figure><img src="/files/pg0nR1s74mGPhILI04vy" alt=""><figcaption></figcaption></figure>

   \
   Nutze die **Import-Option,** um den neuen Konnektor zu erstellen:<br>

   <figure><img src="/files/4u5rhlUCloxiYjeeCPu5" alt=""><figcaption></figcaption></figure>
2. Wähle **Swagger** aus und importiere die API-Spezifikation von folgender URL: [https://app.enlyze.com/api/v2/openapi.json<br>](https://app.enlyze.com/api/v2/openapi.json)

   <figure><img src="/files/j3p93MfEqIQ7Rr9EyxpZ" alt=""><figcaption></figcaption></figure>

   \
   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`

   <figure><img src="/files/ursgxIz7nERTAeHQHH7V" alt=""><figcaption></figcaption></figure>

> 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`

<figure><img src="/files/CaT5hEsWsu6i5bpJyTnr" alt=""><figcaption></figcaption></figure>

### 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.

<figure><img src="/files/16oaMPWXXT4X0rFaILGd" alt=""><figcaption></figcaption></figure>

### Schritt 4: PreRequest Hook

In **Setup → Hooks → PreRequest Hook** einfügen:

```javascript
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**.

<figure><img src="/files/0chmeghLBHD5SjKsPISm" alt=""><figcaption></figcaption></figure>

### Schritt 5: Testen des Konnektors - Instanz erstellen

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

<figure><img src="/files/yjWHsq4evV4A7TwTfTXg" alt=""><figcaption></figcaption></figure>

* **Name**: free text (e.g., `Test Instance`)
* **API Token**: **nur den Token** einfügen (ohne `Bearer` )

Konfiguration der Instanz:

<figure><img src="/files/pfWsrjOR8JkLMqsCrZTI" alt=""><figcaption></figcaption></figure>

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:

```shell
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:

<figure><img src="/files/gTCTEnYn2SJu5GWKbuJO" alt=""><figcaption></figcaption></figure>

Erfolgreiche Antwort:

<figure><img src="/files/IVCLTw3U7qzGX1qfHj6P" alt=""><figcaption></figcaption></figure>

### 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)

```bash
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)

```bash
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.