SAP Connector

Verwendung

Der SAP Connector verbindet sich zu einem SAP-System und bietet folgende Kommunikationsarten mit dem SAP-System:

  • BAPIs/RFCs

    Der SAP Connector kann BAPIs und RFCs im SAP aufrufen bzw. von BAPIs/RFCs aufgerufen werden.

  • IDocs

    IDocs sind ASCII-Dokumente in einem XML-Format mit zusätzlichen Statusinformationen. Der SAP Connector nutzt IDocs, um Daten mit dem SAP System auszutauschen.

Voraussetzungen

  • Um die Kommunikation zwischen der INUBIT Process Engine und dem SAP-System zu ermöglichen, müssen Sie den SAP Java Connector (JCo) installieren.
    Siehe SAP Java Connector - JCo - installieren.

  • Der Benutzer, mit dem sich der SAP Connector via JCo mit dem SAP-System verbindet, muss auf dem SAP-System erstellt und eingerichtet sein.

  • Die Gateways zur Verbindung mit dem SAP-System sind als Netzwerk-Services in der Datei /etc/services (Linux) bzw. C:\Windows\System32\drivers\etc\services (Windows) eingetragen. Je nach Gateway-Bezeichnung müssen die Einträge wie folgt heißen:

    • sapgw00 3300/tcp

    • sapgw01 3301/tcp

SAP Java Connector - JCo - installieren

Voraussetzungen

  • Eine aktuelle Kompatibilitätsliste für den INUBIT und der passenden SAP Version finden Sie im Virtimo Support-Portal.

  • Sie benötigen einen Zugang für SAP Marketplace, um die Installationsdateien herunterzuladen.

  • In der Installationsbeschreibung von SAP wird darauf hingewiesen, dass ein JDK 8, 11 oder 17 benötigt wird.

So gehen Sie vor

  1. Öffnen Sie einen Browser und laden Sie URL https://support.sap.com/en/product/connectors/jco.html.

  2. Laden Sie die aktuelle Version 3.1 der folgenden Bibliotheken herunter und entpacken Sie diese:

    • SAP IDOC Class Library, z.B. sapidoc3_3.1.x.zip

      Enthält sapidoc3.jar

    • SAP Java Connector (passend zu Ihrem Betriebssystem), z.B. sapjco3-NTintel-3.1.x.zip

      Enthält

      • sapjco3.jar

      • abhängig von Ihrer Auswahl z.B. sapjco3.dll (Windows) oder libsapjco3.so (Linux)

  3. Kopieren Sie die Dateien sapidoc3.jar und sapjco3.jar in das Verzeichnis <inubit-installdir>/inubit/server/process_engine/webapps/ibis/WEB-INF/lib.

    Falls Sie eine Fehlermeldung erhalten, die auf das Fehlen der Middleware-Schicht hinweist, lesen Sie die SAP-Note 684106 (zu finden im SAP Marketplace) und wenden Sie die dort beschriebene Lösung an.

  4. Abhängig von Ihrem Betriebssystem kopieren Sie die *.dll/so-Dateien in eines der folgenden Verzeichnisse:

    • Windows:

      • Bei Start der INUBIT Process Engine über das Startmenü: <inubit-installdir>/_jvm\bin

      • Bei Einsatz der INUBIT Process Engine als Dienst unter Tomcat: <inubit-installdir>\server\process_engine\bin

    • Linux 64-Bit

      <inubit-installdir>/_jvm/lib

      Unter Umständen müssen Sie zusätzlich das Verzeichnis in die Umgebungsvariable PATH aufnehmen.

  5. Starten Sie die INUBIT Process Engine neu.

Probleme mit JCO unter Windows

Das passende Microsoft Visual C++ Redistributable Paket muss installiert sein.

SAP Cryptographic Library für SNC installieren

Wenn Sie die sichere Netzwerkverbindung mit SNC (Secure Network Communication) bei RFC-Kommunikation einsetzen wollen, müssen Sie das SAP Cryptographic Library Installationspaket haben. Das Paket enthält:

  • die SAP Cryptographic Library (sapcrypto.dll für Microsoft Windows oder libsapcrypto.<ext> für UNIX),

  • eine entsprechende Berechtigungs-Lizenz

  • und die Datei sapgenpse.exe für Microsoft Windows oder sapgenpse für UNIX zur Konfiguration.

Zur Konfiguration öffnen Sie die Datei `sapgenpse.exe `.

So gehen Sie vor

  1. Legen Sie eine PSE (Personal Security Environment) und ein selbstsigniertes Public-Key-Zertifikat an.

  2. Legen Sie die Credentials des Servers an.

  3. Tauschen Sie PSE und Zertifikat mit dem Kommunikationspartner aus.

  4. Nehmen Sie alle verbindungsspezifischen SNC-Konfigurationen vor und aktivieren Sie SNC.

Die genaue Konfigurationsanleitung siehe SAP Holfe.

Funktionsprinzip

Typ Modus Funktion

Input Connector (Listener)

BAPI/RFC synchron

Der SAP Connector wird von einer Funktion im SAP-System aufgerufen. Die Funktion wird vom SAP Connector und den nachfolgenden Modulen ausgeführt. Danach werden die Rückgabewerte in Form einer BAPI- konformen XML-Response an die aufrufende Funktion zurückgegeben.

Zum Erstellen der XML-Response wird ein XSLT Converter Modul und darin der SAP Explorer verwendet.

BAPI/RFC asynchron

Der SAP Connector wird von einer Funktion im SAP-System aufgerufen. Die Funktion wird vom SAP Connector und den nachfolgenden Modulen ausgeführt. Die Verbindung wird direkt nach dem Aufruf beendet, daher können eventuell vorhandene Rückgabewerte des Workflows nicht an das SAP zurückgegeben werden.

IDoc

Der SAP Connector wird vom SAP System aufgerufen und erhält von diesem ein IDoc; das IDoc wird von nachfolgenden Modulen im Workflow verarbeitet.

Bei der Verwendung als Input Connector muss das Feld "Partner" in den SNC Einstellungen gesetzt sein!

Medium/Output Connector

BAPI/RFC

Der SAP Connector ruft eine Funktion auf dem SAP-System auf.

Mit einem XSLT Converter Modul und dem SAP-Explorer wird der XML- Request erstellt, den das vom SAP Connector anzusprechende BAPI erwartet. Der XML-Request enthält den Namen der aufzurufenden Funktion sowie Parameter und Werte.

Der XSLT Converter übergibt den XML-Request an den Connector, der SAP Connector ruft damit die Funktion auf dem SAP System auf, dann wird die Funktion dort ausgeführt. Das Ergebnis erhält der SAP Connector und gibt es an das nachfolgende Modul weiter.

IDoc

Der SAP Connector erhält als Eingangsnachricht ein oder mehrere IDocs. Der SAP Connector verbindet sich mit dem SAP System und sendet die IDocs.

Wurde SAP-seitig eine Erweiterung an der Rückgabestruktur einer Funktion vorgenommen, so zeigt der SAP Explorer weiterhin die alte Struktur an. Um die Änderungen auf der INUBIT-Seite zu erhalten, ist ein Neustart erforderlich.

XML-Request/Response für den SAP Connector erstellen

Wenn Sie den SAP Connector mit einer der Kommunikationsarten BAPI/RFC oder IDoc verwenden, benötigen Sie eine konforme XML-Response bzw. einen entsprechenden XML-Request. Zum Erstellen verwenden Sie einen XSLT Converter und den SAP Explorer.

Erzeugen und publizieren Sie zuerst den SAP Connector, damit dessen Verbindungsdaten zum SAP System automatisch übernommen werden können. Andernfalls müssen Sie die Verbindungsdaten manuell eingeben.

So gehen Sie vor

  1. Erzeugen Sie einen XSLT Converter.

  2. Öffnen Sie das Modul im lokalen Arbeitsverzeichnis zum Bearbeiten. Das Register XSLT Converter wird angezeigt.

  3. Klicken Sie im Bereich XML Zieldatei auf das Icon module guide 1178 1.

  4. Wählen Sie Öffnen > SAP Explorer:

    Der folgende Dialog öffnet sich:

    module guide 1179 0

    In diesem Dialog werden die Verbindungsdaten zum SAP System angezeigt.
    Wählen Sie aus der Liste Modul das SAP-Modul mit den passenden Verbindungsdaten oder geben Sie die Verbindungsdaten manuell ein.

  5. Klicken Sie auf Weiter. Der folgende Dialog wird angezeigt:

    module guide 1179 1

    Markieren Sie eine der Optionen.

  6. Klicken Sie auf Weiter. Die folgenden Dialoge sind abhängig von der Art des ausgewählten Templates:

    • Bei Auswahl RFC/BAPI:

      module guide 1180 0

      Dieser Dialog unterstützt Sie bei der Auswahl der Funktion, für die Sie einen Request bzw. eine Response benötigen.

      Geben Sie den Funktionsnamen oder die Funktionsgruppe bzw. Teile davon ein. Sie können den Asterisk (*) als Wildcard verwenden. Klicken Sie auf Suchen, um eine Liste mit passenden Funktionen angezeigt zu bekommen.

      Wenn Ihre Suche ein Ergebnis geliefert hat, markieren Sie in der Tabelle die Funktion, die Sie benutzen möchten.

      Dann legen Sie fest, welche Art von XML-Template erzeugt werden soll:

      • Response: Wenn Sie den SAP Connector als synchronen Input Listener verwenden

      • Request: Beim Einsatz als Medium oder Output Connector

        Klicken Sie auf Weiter. Fahren Sie fort mit Schritt 7.

    • Bei Auswahl IDoc:

      module guide 1181 0

      Dieser Dialog unterstützt Sie bei der Auswahl des Nachrichtentyps, für den das Template erstellt wird.

      Geben Sie den Namen des IDocs oder Teile davon ein. Sie können den Asterisk () als Wildcard verwenden. Klicken Sie auf *Suchen, um eine Liste mit passenden IDocs angezeigt zu bekommen.

      Wenn Ihre Suche ein Ergebnis geliefert hat, markieren Sie in der Tabelle das IDoc, welches Sie benutzen möchten. Legen Sie dann fest, welche Art von XML-Template erzeugt werden soll: Single IDoc oder Multi IDoc.

      Klicken Sie auf Fertigstellen. Der Dialog schließt sich und das Template wird im Bereich XML-Ziel angezeigt.

      Fahren Sie fort mit Schritt 8.

  7. Bei Auswahl BAPI öffnet sich der folgende Dialog:

    module guide 1182 0

    Markieren Sie die Checkboxen der Parameter, die als Elemente in das XML-Template übernommen werden sollen. Wenn ein Parameter nicht im Template berücksichtigt werden soll, entfernen Sie die Markierung der Checkbox vor dem Parameter.

    Geben Sie an, ob die Werte aus den Spalten neben den Funktionen/Parametern als Attribute in das XML-Template übernommen werden sollen.

    Klicken Sie auf Fertig stellen. Der Dialog schließt sich und das Template wird im Bereich XML-Ziel angezeigt.

  8. Für die weitere Bearbeitung des Requests bzw. der Response ziehen Sie den Wurzelknoten des Nachrichten- Templates aus dem Reiter Zielstruktur auf das XSLT-Element` xsl:template`.

    Danach sieht das Stylesheet folgendermaßen aus:

    module guide 1183 1
  9. Um die Parameter mit Werten zu belegen, geben Sie die Werte auf der linken Seite (XML-Quelle) ein. Beachten Sie dabei die Beschränkungen, die durch die Attribute vorgegeben sind (Typ/Länge).

→ Damit haben Sie ein Stylesheet erstellt, das eine konforme XML-Response bzw. einen entsprechenden XML-Request erzeugt.

Dialog SAP Connector Eigenschaften

Die Optionen in diesem Dialog sind abhängig vom Konnektortyp und dem Kommunikationsmodus.

Kommunikationsmodus

  • BAPI/RFC

    Zur Kommunikation mit BAPIs und RFCs. Wenn Sie diese Kommunikationsart in Kombination mit einem Input Listener wählen, dann müssen Sie zusätzlich angeben, ob die Kommunikation synchron oder asynchron stattfinden soll (Option Modus).

  • IDoc

    Zur Kommunikation über IDocs.

    Der SAP Connector verarbeitet XML IDoc. Wenn Sie EDI-Nachrichten einlesen lassen möchten, müssen Sie diese erst mit einem EDI-XML Adapter nach XML konvertieren. Analog dazu können Sie die XML-IDoc-Ausgangsnachrichten des SAP Connectors mit einem XML-EDI Adapter nach EDI konvertieren.

System-Informationen

  • Hostname: Name des Rechners, auf dem Ihr SAP System läuft.

  • Systemnummer: Systemnummer (zweistellig).

  • SAP Router

    Geben Sie den/die Router zwischen der Process Engine und dem SAP-Server-Host im SAP-Connection-String-Format ein, z.B.:

    /H/10.4.12.12/S/3299/H/192.168.1.10/S/3299

    Nach /H/ geben Sie die IP-Adresse ein, und nach /S/ geben Sie die Portnummer ein.

  • Kodierung (nur bei Kommunikationsart BAPI/RFC): Geben Sie die Zeichenkodierung für die zu kommunizierenden Daten an.

  • Sichere Netzwerkverbindung:

    Die sichere Netzwerkverbindung wird bei RFC-Kommunikation eingesetzt und sichert durch SNC (Secure Network Communication) den Datenstrom.

    1. Aktivieren Sie die Checkbox Sichere Netzwerkverbindung.

    2. Klicken Sie den Button SNC konfigurieren.

    3. Tragen Sie in das Dialogfenster unter Name Ihre eigene PSE (Personal Security Environment) ein. Die PSE haben Sie bei der SNC-Konfiguration angelegt.

    4. Tragen Sie in das Feld Partner die PSE Ihres Kommunikationspartners ein.

    5. Wählen Sie ein Sicherheitslevel. Diese sind in der SAP Cryptographic Library vorkonfiguriert.

    6. Tragen Sie den Bibliothekspfad der SAP Cryptographic Library ein.

    7. Wenn die Checkbox SSO aktivieren aktiviert ist (Default), ist Single Sign-on aktiv. Deaktivieren Sie die Checkbox, um Single Sign-on zu deaktivieren.

      Um SSO zu benutzen, muss der SNC-Nutzer mit einer existierenden Nutzer-ID im SAP-System verknüpft sein.

    8. Das X.509-Zertifikat haben Sie bei der Erzeugung der PSE angelegt. Der Eintrag ist optional.

      Bei der Verwendung als Input Connector muss das Feld "Partner" in den SNC Einstellungen gesetzt sein!

Login Informationen

Ab Version 2.1.6 des SAP Connectors wird bei dem Login (Benutzer/Passwort) Groß- und Kleinschreibung unterschieden!

  • Client: Dreistellige Clientnummer.

  • Benutzer: Name des Benutzers, mit dem Sie Zugriff auf das SAP System haben.

  • Passwort: Zum Benutzernamen passendes Passwort.

  • Sprache: Sprache, in der die SAP-Systemdialoge angezeigt werden sollen, Eingabe als zweistellige Buchstabenfolge in Großschreibung, z.B. DE, EN oder FR. Angabe ist optional.

Listener-Einstellungen

(Nur bei Input Listener)

Die Gateway-Einstellungen sind notwendig, weil das SAP System nicht direkt, sondern über ein Gateway mit der INUBIT Process Engine kommuniziert:

  • Gateway Hostname

    Name des Gateway-Servers.

  • Gateway Servicenummer

    Da es mehrere Gateway-Hosts geben kann, sind diese nummeriert. Fragen Sie Ihren SAP-Administrator nach dieser Nummer, diese kann z.B. so aussehen sapgw00.

  • Programm-ID

    Vor dem Erstellen eines Input Listener Connectors muss im SAP System eine RFC-Destination angelegt werden. Diese hat eine Programm-ID, die hier angegeben werden muss. Fragen Sie Ihren SAP-Administrator nach dieser Programm-ID.

Wenn die INUBIT Process Engine das Gateway nicht erreichen kann, versucht diese in 660-Sekunden-Intervallen, die Verbindung wieder herzustellen. Sie können dieses Standardintervall in der SAP Connector-Eigenschaftentabelle ändern (Moduleigenschaft RetryInterval, Angabe in Sekunden).

Modus

Synchron/Asynchron

(nur bei Einsatz als Input Listener und BAPI/RFC-Kommunikation):

Legen Sie fest, ob die Rückgabewerte an SAP zurückgegeben werden (synchron) oder nicht (asynchron).

Weitere Einstellungen

  • Transaktionshandling (nur bei BAPI/RFC als Medium/Output Connector):

    • Mit Transaktionshandling

      Der SAP Connector setzt explizit ein Rollback bzw. Commit ab.

    • Ohne Transaktionshandling

      Der SAP Connector setzt kein explizites Rollback bzw. Commit ab.

Aufruffehlerbehandlung:

  • Exception werfen: Bei einem Fehler wird eine Exception geworfen und die Ausführung des Workflows abgebrochen.

  • In den Ausgabestrom schreiben: Bei einem Fehler wird die Fehlermeldung als XML-Datei ausgegeben und die Ausführung des Workflows fortgesetzt. Die Fehlermeldung kann von einem nachfolgenden Modul behandelt werden.

Multi IDoc Verarbeitung

(nur bei Kommunikationsart IDoc)

Aktivieren Sie diese Option, wenn bei der Ausführung eines Workflows mehr als ein IDoc verarbeitet werden soll. Normalerweise wird in einem Workflow genau ein IDoc verarbeitet. Dazu wird über den SAP Connector eine Verbindung zum SAP System aufgebaut, die Nachricht wird verschickt und die Verbindung geschlossen. Wenn man sehr viele IDocs in kurzer Zeit verarbeiten möchte, ist es sinnvoll, die Verbindung zum SAP System aufzubauen und alle Nachrichten auf einmal zu senden.

Die zu sendenden IDocs müssen zu einer Nachricht zusammengefügt sein (Multi IDoc), der Beginn jedes IDoc muss durch ein XML-Element eindeutig gekennzeichnet sein. Das SAP Connector Modul trennt das Multi IDoc am Trennelement und schickt die einzelnen IDocs nacheinander über denselben Verbindungsaufbau.

XML IDoc Trennelement

Geben Sie das XML-Element (inkl. Pfad) ein, welches den Beginn einer IDoc-Nachricht signalisiert. Die Trennung erfolgt inkl. Trennelement, d.h. aus einer XML-Struktur /Root/ADRMAS02/IDOC und dem Trennelement /Root/ADRMAS02 wird ein IDoc mit der Struktur /ADRMAS02/IDOC.

module guide 1186 0

Connection Pool

(nur bei Verwendung als Medium/Output Connector, unabhängig von Kommunikationsart)

  • Max. Anzahl von Verbindungen

    Max. Anzahl von Verbindungen im Connection Pool. Beachten Sie die OSS Notes 314530 und 316877 zum Einrichten externer Verbindungen im SAP System und/oder SAP Gateway.

  • Max. Verbindungswartezeit

    Legt die max. Wartezeit auf eine verfügbare Verbindung fest (in Millisekunden). Wenn nach der angegebenen Zeit keine Verbindung verfügbar ist, wird eine JCo-Exception mit dem Key JCO_ERROR_RESSOURCE geworfen. Standard sind 30000 Millisekunden (30 Sekunden).

  • Verbindungs-Timeout

    Dieses Timeout betrifft nur pooled connections, Verbindungen, die im Connection Pool freigegeben sind und zur Wiederverwendung offen gehalten werden. Es betrifft keine Verbindungen, die aktuell verwendet werden. Eine pooled connection wird geschlossen, wenn sie nach Ablauf der angegebenen Zeit nicht aktiviert wurde. Angabe in Millisekunden, Standard sind 600000 Millisekunden (10 Min.).

Verbindungstest

  • Verbindung testen

    Zum Testen, ob die Verbindung mit Ihren Angaben erfolgreich aufgebaut werden kann.

Metadaten-Cache

  • Aktualisieren

    Zum Aktualisieren des Metadaten-Cache (inklusive aller BAPI- und IDoc-Strukturen).

    Wird der Metadaten-Cache aktualisiert, sind alle SAP-Systemkonnektoren betroffen, die das gleiche Gateway verwenden.