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.

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

Was Sie bereitstellen

Angabe	Wofür
Zugang für Syncwork zu Entwicklungs- und Testsystem	Installation, Einrichtung und Wartung
Freigabe ausgehender HTTPS-Verbindungen zu api.workist.com und documents.workist.com	Datenaustausch mit Workist
Werte für die Auftragsanlage	Verkaufsbelegart, Verkaufsorganisation, Vertriebsweg, Sparte und weitere
Technischer Benutzer für die Hintergrundjobs	Anlage der Kundenaufträge
Häufigkeit der Übertragung	Einplanung der Hintergrundjobs
Technischer Ansprechpartner	Hinweise zur Erneuerung der Zertifikate

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.

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

Bei einigen Installationen stellt Workist die Bestellung zusätzlich als SAP IDoc ORDERS05 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. 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
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.

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	28.03.2027
documents.workist.com	28.03.2027

SHA-256-Fingerabdrücke zum Abgleich:

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

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. 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). 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. Wir klären mit Ihnen Umsetzung und Aufwand.