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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.enlyze.com/integrations/sap/sap-integration-suite-open-connectors-einrichtung-and-tests.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.