> 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

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](/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="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2FCw5RaC7xfkxKZNImJpIz%2FBildschirmfoto%202025-08-21%20um%2014.37.54.png?alt=media&amp;token=7a440e47-85ff-481c-a4e5-3a3294173aa8" alt=""><figcaption></figcaption></figure>

### Schritt 1: ENLYZE OpenAPI importieren

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

   <figure><img src="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2FTJiJWbsbRRApbgg89MKd%2FBildschirmfoto_2025-08-21_um_08.44.42.png?alt=media&amp;token=479de1e4-0ef3-4b6f-b8f4-0aa9b75a07f4" alt=""><figcaption></figcaption></figure>

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

   <figure><img src="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2FBujpuZTJcSTJTGJ51ueI%2FBildschirmfoto_2025-08-21_um_08.44.52.png?alt=media&amp;token=a330119e-7cb1-49b9-80cb-c966e32c1895" 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="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2FMPKie39ttdKpAyktqHpE%2FBildschirmfoto_2025-08-21_um_08.46.29.png?alt=media&amp;token=5c803243-674c-4589-8238-7dd1b28d1aa1" 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="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2FHj1DirNWmKOkHs3Swhtg%2FBildschirmfoto_2025-08-21_um_08.47.35.png?alt=media&amp;token=4751f402-19ab-43d5-99dc-e08182fb5b93" 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="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2FkQzBtwXhgRFn6PXRbs5c%2FBildschirmfoto_2025-08-21_um_09.03.47.png?alt=media&amp;token=29345e9b-f932-4477-8263-a6dbf6dd1434" 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="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2FpmatG4258D8BUELHY0Q1%2FBildschirmfoto_2025-08-21_um_09.05.06.png?alt=media&amp;token=47e33bfd-cb45-413f-9f48-a36f761043a0" 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="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2FsMW8tki3AhrSnxvxoVQO%2FBildschirmfoto_2025-08-21_um_09.26.31.png?alt=media&amp;token=c1e2e82e-3a50-47a3-8168-d7aed7ce3f08" alt=""><figcaption></figcaption></figure>

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

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

<figure><img src="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2FSyYMA40AxbG9LnmIrMjQ%2FBildschirmfoto_2025-08-21_um_09.13.21.png?alt=media&amp;token=8117366f-fbbb-4a4e-bb47-35794fc60f41" 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="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2FdMvyNDvc70h7SYNxFvrE%2FBildschirmfoto_2025-08-21_um_09.15.04.png?alt=media&amp;token=7df24fb2-9080-463f-85c0-4f2b8e879a38" 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="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2FpEU9bwo1NkttITvUx7IC%2FBildschirmfoto_2025-08-21_um_10.10.47.png?alt=media&amp;token=b7a2211f-660c-4c17-bf8c-f34697e2e6bf" alt=""><figcaption></figcaption></figure>

Erfolgreiche Antwort:

<figure><img src="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2F5CZCwUh6JbLLoESE0i09%2FBildschirmfoto_2025-08-21_um_10.11.09.png?alt=media&amp;token=5d908662-6697-422f-b40c-9ead1c02410d" 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.