# SAP-Konnektor

Der Workist SAP-Konnektor für SAP R/3, SAP ECC und SAP S/4HANA ist ein ABAP-Entwicklungspaket, das unser Partner **Syncwork AG** im Auftrag von Workist in Ihrem SAP-System installiert und einrichtet. Er überträgt die benötigten Stammdaten aus SAP an Workist und legt in der Workbench abgeschlossene Bestellungen als Kundenaufträge in SAP an.

Für SAP Business One gibt es einen eigenen Konnektor ohne Installation in SAP, siehe [SAP Business One](/docs/data-exchange/connectors/sap-business-one.md).

## Überblick

**Anforderungen an Ihr SAP**

- SAP R/3, SAP ECC oder SAP S/4HANA (On-Premise oder Private Cloud Edition), in dem eigene ABAP-Entwicklungen installiert werden können. SAP S/4HANA Cloud Public Edition wird nicht unterstützt. Bei SAP R/3 klären Sie vor Projektstart mit Syncwork, ob Kernel und Kryptobibliothek Ihres Systems TLS 1.2 und SNI unterstützen.
- Ausgehende HTTPS-Verbindungen mit TLS 1.2 oder höher und Server Name Indication (SNI), siehe [Kommunikation](#kommunikation).

**Was Sie bereitstellen**

| Angabe | Wofür |
| --- | --- |
| [Zugang für Syncwork](#zugang-für-syncwork) zu Entwicklungs- und Testsystem | Installation, Einrichtung und Wartung |
| [Freigabe ausgehender HTTPS-Verbindungen](#kommunikation) zu `api.workist.com` und `documents.workist.com` | Datenaustausch mit Workist |
| [Werte für die Auftragsanlage](#customizing-der-auftragsanlage) | Verkaufsbelegart, Verkaufsorganisation, Vertriebsweg, Sparte und weitere |
| [Technischer Benutzer für die Hintergrundjobs](#hintergrundjobs) | Anlage der Kundenaufträge |
| [Häufigkeit der Übertragung](#hintergrundjobs) | Einplanung der Hintergrundjobs |
| Technischer Ansprechpartner | Hinweise zur Erneuerung der [Zertifikate](#zertifikate-strust) |

**Was in Ihrem SAP eingerichtet wird**

| Schritt | Transaktion |
| --- | --- |
| Entwicklungspaket installieren und transportieren | SE80, SE01, STMS |
| Workist-Zertifikate importieren | STRUST |
| Verbindungen zu Workist anlegen | SM59 |
| Customizing der Auftragsanlage pflegen | SM30 |
| Hintergrundjobs einplanen | SM36, SM37 |

## Funktionsweise

Die beiden Programme des Pakets laufen als Hintergrundjobs in Ihrem SAP-System und bauen jede Verbindung selbst auf. Die Workist-Plattform verbindet sich nie mit Ihrem SAP. Workist und Syncwork arbeiten in Ihrem SAP nur über den Zugang, den Sie für Installation, Einrichtung und Wartung bereitstellen, siehe [Zugang für Syncwork](#zugang-für-syncwork).

![Architektur: Der Workist SAP-Konnektor in Ihrem SAP-System liest Stammdaten und legt Kundenaufträge an; alle Verbindungen zu api.workist.com und documents.workist.com gehen per HTTPS ausgehend von Ihrem SAP aus](/img/sap/architecture-de.png)

- **Stammdaten:** Der Stammdatenversand liest die Stammdaten aus SAP und sendet sie über die Workist REST-API an Workist. Jeder Lauf überträgt die vollständige Auswahl. Preise werden nicht übertragen.
- **Bestellungen:** Die Auftragsanlage ruft die in der Workbench abgeschlossenen Bestellungen ab und legt daraus Kundenaufträge an. Sofern nicht anders vereinbart, verwendet sie dafür den SAP-Baustein `BAPI_SALESORDER_CREATEFROMDAT2` und schreibt den Kundenauftrag nicht direkt in SAP-Standardtabellen. Der Kundenauftrag durchläuft damit die Standardverarbeitung von SAP wie bei der Erfassung in VA01, einschließlich Nummernvergabe und Unvollständigkeitsprüfung. Ihre eigenen Erweiterungen der Auftragsbearbeitung greifen, soweit sie auch ohne Dialog laufen.
- **Dokumente:** Das Bestelldokument (PDF) und die Original-E-Mail werden an den Kundenauftrag angehängt. Wo die Anlagen in SAP abgelegt werden, stimmt Syncwork bei der Einrichtung mit Ihnen ab.
- **Rückmeldung:** Nach der Anlage markiert der Konnektor die Bestellung in Workist als übertragen. Lehnt SAP den Auftrag ab, erscheint die Bestellung wieder in der Workbench, in der Regel mit der Meldung aus SAP, siehe [Meldungen aus SAP](#meldungen-aus-sap).

Bei einigen Installationen stellt Workist die Bestellung zusätzlich als [SAP IDoc ORDERS05](/docs/output-formats/orders.md#sap-idoc) bereit, und der Konnektor verarbeitet sie in dieser Form. Welche Variante eingesetzt wird, stimmen Workist und Syncwork bei der Einrichtung mit Ihnen ab.

## Was wir aus SAP lesen

| Stammdaten | Wofür in Workist |
| --- | --- |
| Auftraggeber | Kunden erkennen |
| Warenempfänger | Lieferadresse zuordnen |
| Rechnungsempfänger | Rechnungsadresse zuordnen |
| Ansprechpartner (nach Absprache) | Besteller zuordnen |
| Material | Artikel erkennen und zuordnen |
| Kunden-Material-Infosatz | Artikelnummern Ihrer Kunden übersetzen |
| Alternative Mengeneinheiten | Bestelleinheiten in Verkaufseinheiten umrechnen |

Welche Datensätze übertragen werden, zum Beispiel nur bestimmte Verkaufsorganisationen oder Materialarten, und ob Ansprechpartner übertragen werden, legt Syncwork bei der Einrichtung mit Ihnen fest. Die Auswahl lässt sich später [anpassen](#anpassungen). Neu angelegte Kunden und Materialien kennt Workist ab dem nächsten Stammdatenlauf.

## Was wir in SAP schreiben

| Objekt | Inhalt |
| --- | --- |
| Kundenauftrag | Kopfdaten, Partner und Positionen aus der verarbeiteten Bestellung; Vertriebsdaten aus dem [Customizing](#customizing-der-auftragsanlage) |
| Anlagen am Kundenauftrag | Bestelldokument (PDF) und Original-E-Mail |
| Protokolltabelle `ZWI_ORDER_DOC` | je angelegtem Auftrag: Debitor, Workist-Kanal, Workist-ID der Bestellung, Verkaufsbeleg, Datum, Uhrzeit, Benutzer |

Der Konnektor legt nur neue Kundenaufträge an. Änderungen und Stornierungen bestehender Bestellungen überträgt er nicht: Wird eine Änderung als Bestellung abgeschlossen, von Hand oder automatisch, entsteht ein weiterer Kundenauftrag. Verwerfen Sie Änderungen und Stornierungen deshalb in der Workbench und bearbeiten Sie sie direkt in SAP. Ist bereits ein weiterer Kundenauftrag entstanden, stornieren Sie ihn dort.

## Was die Installation anlegt

Syncwork installiert ein eigenes Entwicklungspaket im Kundennamensraum. Es enthält im Standard:

- zwei Programme, eines für den Stammdatenversand und eines für die Auftragsanlage
- eine Klasse mit der Logik zur Auftragsanlage und zum Anhängen der Dokumente
- die Customizing-Tabelle `ZWI_SALES_ORDER`
- die Protokolltabelle `ZWI_ORDER_DOC` mit den angelegten Aufträgen
- die zugehörigen Dictionary-Objekte

Je nach Projekt kommen weitere Customizing-Tabellen hinzu, etwa für die Stammdatenauswahl. Das Paket wird im Entwicklungssystem angelegt und über Ihre Transportlandschaft in Test- und Produktivsystem übernommen.

## Einrichtung

Syncwork richtet den Konnektor im Entwicklungs- und Testsystem ein. Schritte, für die Syncwork keine Berechtigung erhält, zum Beispiel in STRUST oder SM59, übernimmt Ihre SAP-Basis. Wer das Produktivsystem einrichtet, stimmen Sie im Projekt ab.

Zertifikate und Verbindungen gelten mandantenübergreifend und werden in jedem System eingerichtet. Customizing und Hintergrundjobs gelten je Mandant.

:::warning Eigene Workist-Kanäle je System und Mandant
Jedes SAP-System und jeder Mandant, der Bestellungen abruft, braucht eigene Workist-Kanäle. Rufen zwei Systeme denselben Kanal ab, landen Produktivaufträge im Testsystem oder werden doppelt angelegt. Senden zwei Systeme Stammdaten an dieselben Stammdaten-IDs, ersetzt jeder Lauf die Stammdaten des anderen. Passen Sie nach einer Kopie des Produktivsystems die Kanal-IDs und Stammdaten-IDs in der Kopie an, bevor die Jobs dort wieder laufen.
:::

### Zugang für Syncwork

Für Installation und Einrichtung, später auch für Wartung und Anpassungen, benötigen die Syncwork-Berater:

- VPN-Zugang zu Ihrem Entwicklungs- und Testsystem oder einen bereitgestellten Rechner mit diesem Zugang
- je einen SAP-Benutzer mit Entwicklungsberechtigung, in SAP R/3 und ECC zusätzlich mit Entwicklerschlüssel
- Zugriff auf diese Transaktionen:

| Transaktion | Zweck | Bedarf |
| --- | --- | --- |
| SE80 | Entwicklung | erforderlich |
| SE16 | Tabelleninhalte prüfen | erforderlich |
| SM59 | Verbindungen anlegen | empfohlen |
| SE01 | Transportaufträge anlegen | empfohlen |
| STMS | Transport vom Entwicklungs- ins Testsystem | empfohlen |
| STRUST | Zertifikate importieren | empfohlen |
| SM30 | Customizing der Auftragsanlage pflegen | empfohlen |
| SM36, SM37 | Hintergrundjobs einplanen und prüfen | empfohlen |
| VA05 | angelegte Kundenaufträge prüfen | empfohlen |

Im Testsystem benötigen die Syncwork-Berater zusätzlich eine Debugger-Berechtigung, nach Möglichkeit mit der Berechtigung, Feldwerte zu ändern. Übernimmt Syncwork die Einrichtung im Produktivsystem, braucht Syncwork auch dort einen Zugang. Für Einrichtung und Support erhalten die Syncwork-Berater außerdem einen Benutzer in Ihrem Workist-Konto. Die Namen der Berater nennen wir Ihnen im Kick-off.

### Kommunikation

Der Konnektor verbindet sich ausschließlich ausgehend per HTTPS:

| Host | Port | Wofür |
| --- | --- | --- |
| `api.workist.com` | 443 | Stammdaten senden, Bestellungen abrufen und zurückmelden |
| `documents.workist.com` | 443 | Bestelldokument, E-Mail und gegebenenfalls IDoc abrufen |

- Für den Datenaustausch sind keine eingehenden Verbindungen zu Ihrem SAP nötig.
- Geben Sie die Hosts über den Namen frei, nicht über IP-Adressen, weil sich diese ändern können. Die Freigabe gilt für alle Anwendungsserver, auf denen die Hintergrundjobs laufen können. Ohne Proxy müssen diese die Namen per DNS auflösen können.
- Geht Ihr SAP nur über einen Proxy ins Internet, wird dieser in den Verbindungen oder zentral über **Globale Konfiguration** in SM59 hinterlegt. Bricht Ihr Proxy TLS-Verbindungen zur Prüfung auf, nehmen Sie die beiden Workist-Hosts davon aus.
- Beide Hosts setzen TLS 1.2 oder höher und Server Name Indication (SNI) voraus. Ohne SNI liefert `documents.workist.com` ein fremdes Zertifikat, und `api.workist.com` nimmt die Verbindung nicht an. Ab Kernel-Release 7.77 ist SNI im Standard aktiv. Bei älteren Kernels schaltet Ihre SAP-Basis es ein, in der Regel mit dem Profilparameter `icm/HTTPS/client_sni_enabled = TRUE` (SAP-Hinweis 2124480), bei Kernel 7.21 und 7.22 gegebenenfalls mit `ssl/client_sni_enabled = TRUE` (SAP-Hinweis 2384290). Welcher Parameter und welcher Patch-Stand nötig sind, nennen die beiden Hinweise.
- Ältere Systeme brauchen für TLS 1.2 gegebenenfalls eine aktuelle CommonCryptoLib und angepasste Werte im Profilparameter `ssl/client_ciphersuites` (SAP-Hinweis 510007). `documents.workist.com` nimmt nur Cipher-Suites mit ECDHE an.

### Zertifikate (STRUST)

Damit SAP den Workist-Servern vertraut, werden in der Transaktion STRUST die Zertifikate beider Workist-Hosts in die Zertifikatsliste der PSE **SSL-Client (Standard)** aufgenommen: den Knoten der PSE selbst wählen, nicht einen einzelnen Anwendungsserver, dann **Zertifikat importieren**, **In Zert.-Liste aufnehmen** und **Sichern**. Bis SAP NetWeaver 7.01 wird die Änderung erst nach einem Neustart des ICM (SMICM) wirksam.

| Zertifikat | Gültig bis |
| --- | --- |
| [api.workist.com](/files/sap/api-workist-com.crt) | 28.03.2027 |
| [documents.workist.com](/files/sap/documents-workist-com.crt) | 28.03.2027 |

SHA-256-Fingerabdrücke zum Abgleich:

```text
api.workist.com        1A:51:8E:DD:1E:20:1D:1C:1F:21:1D:F7:29:34:6A:10:38:C8:EB:54:31:EE:5E:59:7B:B0:42:74:40:A2:4E:3A
documents.workist.com  F0:A3:10:E7:E6:C1:4A:B8:F1:6D:88:A6:40:69:54:D1:B3:DB:E9:E8:C2:C0:3D:A6:19:A2:77:FE:5B:0C:5C:0A
```

:::warning Zertifikate rechtzeitig erneuern
Die Serverzertifikate sind nur wenige Monate gültig, und ihre Laufzeit sinkt bis 2029 schrittweise auf 47 Tage. Vor jeder geplanten Erneuerung informieren wir den technischen Ansprechpartner, den Sie uns im Projekt nennen, und stellen die neuen Zertifikate bereit. Widerruft die Zertifizierungsstelle ein Zertifikat vorzeitig, kann die Frist kurz sein. Importieren Sie die neuen Zertifikate vor der angekündigten Umstellung und behalten Sie die bisherigen bis dahin in der Liste, sonst kann Ihr SAP keine Verbindung zu Workist aufbauen.
:::

### Verbindungen (SM59)

Unter **HTTP-Verbindungen zu ext. Server** werden die Verbindungen zu beiden Workist-Hosts mit diesen Einstellungen angelegt:

| Einstellung | Wert |
| --- | --- |
| Verbindungstyp | G – HTTP-Verbindung zu ext. Server |
| Host | `api.workist.com` bzw. `documents.workist.com` |
| Port | 443 |
| Anmeldung mit Benutzer | Keinen Benutzer verwenden |
| SSL | aktiv, SSL-Zertifikat **DFAULT SSL-Client (Standard)** |
| HTTP-Version | HTTP 1.1 |

Prüfen Sie jede Verbindung mit **Verbindungstest**. Jeder HTTP-Statuscode von Workist, auch 400 oder 404, zeigt, dass Zertifikat und TLS stimmen. Läuft die Verbindung über einen Proxy, kann der Statuscode auch vom Proxy stammen, zum Beispiel 407, wenn die Anmeldung am Proxy fehlt. Eine SSL-Fehlermeldung weist auf ein fehlendes Zertifikat, fehlendes SNI, fehlende Unterstützung für TLS 1.2 oder die nötigen Cipher-Suites oder einen Proxy hin, der TLS-Verbindungen aufbricht.

### API-Schlüssel

Der Konnektor authentifiziert sich an `api.workist.com` mit einem API-Schlüssel, den er bei jeder Anfrage mitsendet. Dokumente ruft er über zeitlich begrenzte, signierte Links von `documents.workist.com` ab. In den Verbindungen wird deshalb kein Benutzer hinterlegt.

Der Schlüssel gehört zu Ihrem Workist-Konto. In der Workbench unter **API-Integrationen** sehen Benutzer mit Berechtigung für Integrationen die Integration des Konnektors. Ist sie auf einzelne Kanäle beschränkt, ruft der Konnektor nur deren Bestellungen ab. Wird dort der Schlüssel erneuert oder die Integration gelöscht, überträgt der Konnektor nichts mehr, bis ein neuer Schlüssel im Konnektor hinterlegt ist. Stimmen Sie beides deshalb vorab mit Workist ab. Legen Sie für diese Integration kein Ablaufdatum fest, sonst stoppt die Übertragung an diesem Tag.

### Customizing der Auftragsanlage

In der Tabelle `ZWI_SALES_ORDER` (Pflege über SM30) wird festgelegt, mit welchen Vertriebsdaten die Kundenaufträge angelegt werden. Die Werte liefern Sie, die Einträge legt Syncwork bei der Einrichtung an. Schlüssel eines Eintrags sind der Auftraggeber und der Workist-Kanal. Ein Kanal entspricht in der Regel einer Verkaufsorganisation.

| Feld | Bedeutung | Hinweis |
| --- | --- | --- |
| `KUNNR` | Debitor | Schlüssel, Debitorennummer des Auftraggebers |
| `CHANNEL` | Workist-Kanal | Schlüssel, Kanal-ID aus Workist |
| `AUART` | Verkaufsbelegart | für jeden Auftrag erforderlich |
| `VKORG` | Verkaufsorganisation | für jeden Auftrag erforderlich |
| `VTWEG` | Vertriebsweg | für jeden Auftrag erforderlich |
| `SPART` | Sparte | für jeden Auftrag erforderlich |
| `WAERS` | Währung | |
| `ISOCD` | ISO-Code der Währung | |
| `WERKS` | Werk | nach Möglichkeit pflegen, damit der Auftrag in sich konsistent ist |
| `PROFIT_CTR` | Profitcenter | |
| `LIFSK` | Liefersperre | |

`ZWI_SALES_ORDER` ist eine mandantenabhängige Customizing-Tabelle. Ob die Einträge per Customizing-Auftrag übernommen oder in jedem System direkt gepflegt werden, legt Syncwork bei der Einrichtung mit Ihnen fest. In jedem Mandanten stehen dort die Workist-Kanäle, die dieser Mandant abruft.

### Hintergrundjobs

Die beiden Programme laufen als Hintergrundjobs mit Programmvarianten, die Syncwork bei der Einrichtung anlegt. Eingeplant werden sie in SM36, die Läufe sehen Sie in SM37.

Die Jobs laufen unter dem SAP-Benutzer, der beim Einplanen im Jobschritt eingetragen wird. Dafür stellen Sie in der Regel einen technischen Benutzer (Benutzertyp System) bereit. Er legt die Kundenaufträge an, erscheint darin als Erfasser und braucht deshalb die Berechtigung, Kundenaufträge für die hinterlegten Verkaufsbelegarten und Verkaufsbereiche (Verkaufsorganisation, Vertriebsweg, Sparte) anzulegen. Die weiteren Berechtigungen stimmt Syncwork bei der Einrichtung mit Ihrer SAP-Basis ab.

Wie oft Stammdaten und Bestellungen übertragen werden, legen Sie fest. Bewährt haben sich ein täglicher Stammdatenlauf und ein Auftragslauf alle 5 bis 15 Minuten. SM36 verhindert nicht von selbst, dass ein periodischer Job startet, während der vorige Lauf noch aktiv ist. Wählen Sie den Abstand deshalb deutlich größer als die Laufzeiten, die SM37 für den Auftragsjob zeigt.

## Betrieb

### Meldungen aus SAP

Kann SAP einen Auftrag nicht anlegen, meldet der Konnektor das an Workist zurück. Die Bestellung erscheint dann wieder unter den offenen Bestellungen in der Workbench, in der Regel mit der Meldung aus SAP, und wird nicht automatisch erneut übertragen. Liegt die Ursache in SAP, zum Beispiel in den Stammdaten, beheben Sie sie dort. Öffnen Sie die Bestellung anschließend erneut zur Bearbeitung, korrigieren Sie sie bei Bedarf und schließen Sie sie wieder ab. Der nächste Lauf überträgt sie neu. Wird der Auftrag nicht mehr benötigt, verwerfen Sie die Bestellung.

Die Meldungen stammen aus Ihrem SAP-System: aus dem SAP-Standard oder aus Prüfungen, die Ihre IT eingerichtet hat. Erster Ansprechpartner ist deshalb Ihre SAP-IT. Lässt sich eine Meldung nicht einordnen, schreiben Sie an [support@workist.com](mailto:support@workist.com). Wir ziehen Syncwork hinzu.

Kommen abgeschlossene Bestellungen nicht in SAP an und zeigt die Workbench keine Meldung, prüfen Sie die Jobläufe in SM37. Mögliche Ursachen sind ein Job, der nicht läuft, oder eine Verbindung, die scheitert, zum Beispiel wegen eines Zertifikats oder eines ungültigen API-Schlüssels.

### Wartung

Das Paket wird von Syncwork im Auftrag von Workist gewartet. Neue Workist-Serverzertifikate importieren Sie selbst vor der angekündigten Umstellung, siehe [Zertifikate (STRUST)](#zertifikate-strust). Planen Sie ein Upgrade Ihres SAP-Systems oder eine Umstellung auf SAP S/4HANA, informieren Sie Ihren Workist-Ansprechpartner rechtzeitig, damit Syncwork das Paket vorab prüfen kann.

Für einen weiteren Workist-Kanal legt Workist den Kanal an, gibt ihn für die API-Integration des Konnektors frei und nennt Ihnen die Kanal-ID. Hinterlegen Sie sie in Ihrem SAP selbst oder mit Syncwork.

### Anpassungen

Zusätzliche Felder oder abweichende Logik bei der Auftragsanlage sind möglich. Je nach Anforderung passt Workist die Verarbeitung in Workist an oder Syncwork das Paket in Ihrem SAP, oft beides. Auch Änderungen an den Feldern eines Workist-Kanals stimmen Sie vorab mit Workist ab, weil der Konnektor die Bestelldaten in einer festen Struktur erwartet. Sprechen Sie dafür Ihren Workist-Ansprechpartner an oder schreiben Sie an [support@workist.com](mailto:support@workist.com). Wir klären mit Ihnen Umsetzung und Aufwand.