SAP Connector

Usage

The SAP Connector connects to an SAP system and offers the following modes of communication with the SAP system:

  • BAPIs/RFCs

    The SAP connector can call BAPIs and RFCs in the SAP system or can be called by BAPIs/RFCs.

  • IDocs

    IDocs are ASCII documents in an XML format that contain additional status information. The SAP connector uses IDocs to exchange data with the SAP system.

Prerequisites

  • To enable the communication between the INUBIT Process Engine and the SAP system you must install the SAP Java Connector (JCo).

    Refer to Installing the SAP Java Connector - JCo.

  • The user which the SAP Connector uses to connect itself via JCo with the SAP system must be created and set up on the SAP system.

  • The gateways used to connect to the SAP system are entered as network services in the /etc/services file (Linux) or in the C:\Windows\System32\drivers\etc\services file (Windows). Depending on the gateway, the following entries are added:

    • sapgw00 3300/tcp

    • sapgw01 3301/tcp

Installing the SAP Java Connector - JCo

Prerequisites

  • A current compatibility list for the INUBIT and the appropriate SAP version can be found in the Virtimo support portal.

  • For downloading the installation files, you need a username and a password for the SAP Marketplace.

  • The SAP installation instructions state that a JDK 8, 11 or 17 is required.

  • Windows only: Microsoft Visual C++ 2013 Redistributable Package must be installed

Proceed as follows

  1. In a browser, open the URL https://support.sap.com/en/product/connectors/jco.html.

  2. Download the latest 3.1 version of the following libraries and decompress them:

    • SAP IDOC Class Library, e.g., sapidoc3_3.1.x.zip

      Contains sapidoc3.jar

    • SAP Java Connector (suitable for your operating system), e.g., sapjco3-NTintel-3.1.x.zip

      Contains

      • sapjco3.jar

      • depending on your choice e.g. sapjco3.dll (Windows) or libsapjco3.so (Linux)

  3. Copy the files sapidoc3.jar and sapjco3.jar to the directory <inubit-installdir>/server/ process_engine/webapps/ibis/WEB-INF/lib.

    If you get an error message referring to the missing middleware layer, read the SAP note 684106 (which you find in the SAP Marketplace) and apply the solution suggested there.

  4. Depending on your operating system, copy the .dll/`.so `files into one of the following directories:

    • Windows

      • When starting the INUBIT Process Engine via the Start menu: <java-installdir>\bin

      • When using the INUBIT Process Engine as a service under tomcat: <inubit-installdir>server\process_engine\bin

    • Linux 64-Bit

      <java-installdir>/lib

      You must possibly add the directory to the PATH environment variable.

  5. Restart the INUBIT Process Engine.

Installing the SAP Cryptographic Library for SNC

If you want to use the secure network communication (SNC) for RFC communication, you will need the Cryptographic Library Installation Package. The package contains:

  • The SAP Cryptographic Library (sapcrypto.dll for Windows or libsapcrypto.<ext> for UNIX)

  • A corresponding license ticket

  • The configuration tool sapgenpse.exe for Microsoft Windows or sapgenpse for UNIX

For the configuration open the `sapgenpse.exe `and proceed as follows

  1. Create a PSE (Personal Security Environment) and a selfsigned public-key-certificate.

  2. Create the credentials of your server.

  3. Exchange the PSE and certificate with the one’s of your communication partner.

  4. Make the specific SNC configurations and activate SNC.

For detailed information about the installation refer see SAP help.

Principles

Type Mode Function

Input Connector (Listener)

BAPI/RFC synchronous

The SAP connector is called by a function in the SAP system. The function is executed by the SAP connector and the downstream modules. After execution, the required values are returned to the calling function in the form of a BAPI-compliant XML response.

The XML response is created using an XSLT converter module and its SAP Explorer.

BAPI/RFC asynchronous

The SAP connector is called by a function in the SAP system. The function is executed by the SAP connector and the downstream modules. The connection is terminated right after the call, so any generated return values will not be returned to the SAP system.

IDoc

The SAP connector is called by the SAP system from which it receives an IDoc; the IDoc is processed by modules downstream in the workflow.

As Input Connector the field "Partner" must be set in the SNC settings for proper operation!

Medium/Output Connector

BAPI/RFC

The SAP connector calls a function on the SAP system.

An XSLT convertor module and the SAP Explorer are used to create the XML request that is expected by the BAPI that is to be accessed by the SAP connector. The XML request contains the name of the function to be called as well as parameters and values.

The XSLT converter passes the XML request to the connector which then calls the function on the SAP system. The function is then executed on the SAP system. The result is received back by the SAP connector, which passes it to the next module downstream.

IDoc

The SAP connector receives one or more IDocs as input. The SAP connector connects to the SAP system and transfers the IDocs.

If the return message structure of a function has been modified in SAP, the SAP Explorer still displays the old structure. A restart is required to obtain the changes on INUBIT side.

Creating XML Request/Response Using an SAP Connector

If you are using the SAP connector in a BAPI/RFC or IDoc communication mode, you need a compliant XML response or an appropriate XML request. To create these, you use an XSLT Converter module and the SAP Explorer.

First, create and publish the SAP Connector in order to make sure that its connection data to the SAP system are automatically imported. Otherwise, you must enter the connection data manually.

Proceed as follows

  1. Create an XSLT converter module.

  2. Open the module for editing in the local working directory. The XSLT Converter tab is displayed.

  3. Click the module guide 1144 1 button in the XML target file area. A menu opens.

  4. Select Open > SAP Explorer. A dialog opens and shows the connection data to the SAP system.

    module guide 1145 0

    In the Module drop-down list, select the SAP module with the appropriate connection data or enter these connection data manually.

  5. Click Next. The next dialog is displayed. Select one of the options.

    module guide 1145 1

  6. Click Next. The following dialogs depend on the type of template selected.

    • If RFC/BAPI is selected:

      module guide 1146 0

      The dialog for Search and select helps you with the selection of the function for which you require a request or response.

      Enter the function name or the function group or parts thereof. You can use the asterisk (*) as a wildcard.

      Click Search to display a list of appropriate functions.

      If your search returns a result, mark the function that you want to use in the table. Then indicate which type of XML template is to be created:

      • Response: If you are using the SAP connector as a synchronous listener

      • Request: When used as a medium or output connector

        Click Next. Continue with step 7.

    • If IDoc is selected:

      module guide 1147 0

      The dialog for IDoc Search helps you with the selection of the message type for which the template is being created.

      Enter the name of the IDoc or parts thereof. You can use the asterisk (*) as a wildcard.

      Click Search to display a list of appropriate IDocs.

      If your search returns a result, mark the IDoc that you want to use in the table. Then indicate which type of XML template is to be created: Single IDoc or Multi IDoc.

      Click Finish. The dialog closes and the template is displayed in the XML target area. Continue with step 8.

  7. If you have selected BAPI the following dialog opens:

    module guide 1148 0

    Select the checkboxes for the parameters that are to be used as elements in the XML template.

    If a parameter is not to be used in the template, clear the checkbox for that parameter.

    Indicate whether the values from the columns are to be used as attributes in the XML template in addition to the functions/parameters.

    Click Finish. The dialog closes and the template is displayed in the XML target area.

  8. To further edit the XML template, drag the root node of the message onto the xsl:template element.

    When you have done this, the stylesheet looks as follows:

    module guide 1149 1

  9. To attach values to the parameters, enter the values on the left-hand side (XML source). In doing this, observe the limitations defined for the attributes (type/length).

→ Now you have created a stylesheet, which generates a conform XML response resp. an XML request.

Dialog SAP Connector Properties

The dialog offers different controls depending on the connector type and communication mode selected:

Communication mode

  • BAPI/RFC

    For communication using BAPIs and RFCs. If you select this communication mode in combination with an input listener, you must additionally specify whether the communication is to be synchronous or asynchronous (mode option).

  • IDoc

    For communication using IDocs.

    The SAP Connector processes XML IDoc. If you want to let EDI messages read, you first must convert them using an EDI-XML Adapter to XML. Analogously, you can convert the XML IDoc output messages of the SAP Connector to EDI by using an XML-EDI Adapter.

System information

  • hostname

    Name of the computer on which your SAP system runs.

  • System number

    (2-digit) system number.

  • SAP router

    Specify the router(s) between the Process Engine and the SAP server host using the SAP connection string format, for example: /H/10.4.12.12/S/3299/H/192.168.1.10/S/3299 After /H/ add the IP address, and after /S/ add the port number.

  • Encoding (only for the BAPI/RFC communication mode)

    Specify the character encoding for the data that is to be communicated.

  • Secure network connection (SNC):

    SNC is used with RFC communication.

    1. Activate the checkbox Secure network connection.

    2. Click the button Configure SNC.

    3. Enter your own PSE (Personal Security Environment) into the field Name. You have created the PSE with the SNC configuration.

    4. Enter the PSE of your communication partner into the field Partner.

    5. Choose a Security level. Those are pre-configured in the SAP Cryptographic Library.

    6. Enter the Library path of the SAP Cryptographic Library.

    7. When Enable SSO is activated (default), single sign-on is enabled. Deactivate the checkbox to disable single sign- on.

      To use SSO, the SNC user identity must be mapped to a valid user ID in the SAP system.

    8. The X.509 certificate has been set with the creation of the PSE. The entry is optional.

      As Input Connector the field "Partner" must be set in the SNC settings for proper operation!

Login information

As of version 2.1.6 of the SAP connector, the login information (username/password) is case-sensitive!

  • Client

    (3-digit) Client number.

  • User

    Username you use to access the SAP system.

  • Password

    The password associated with the username.

  • Language

    The language in which the SAP system dialog is to be displayed. Enter as a 2-digit, upper-case alphabetic string; for example, DE, EN or FR. This field is optional.

Listener settings

The gateway settings are needed as the SAP system communicates with the INUBIT Process Engine via a gateway rather than directly.

  • Gateway hostname

    Name of the gateway server.

  • Gateway service number

    Since more than one gateway host may be present, they are numbered. Ask your SAP administrator for this number; it may, for example, take the form sapgw00.

  • Program ID

    Before creating an input listener connector, an RFC destination must have been set up in the SAP system. This has a program ID, which must be entered here. Ask your SAP administrator for this program ID.

    If the INUBIT Process Engine cannot reach the gateway, it attempts to re-connect at 660 second intervals. This default interval can be changed in the SAP connector property table (RetryInterval property, defined in seconds).

Mode

Synchronous/Asynchronous (only when used as an input listener and BAPI/RFC communication mode):

Specify whether the return values are returned to SAP (synchronous) or not (asynchronous).

Additional settings

  • Transaction handling (only with BAPI/RFC as medium/output connector):

    • With transaction handling

      The SAP connector explicitly issues a Rollback or Commit.

    • Without transaction handling

      The SAP connector doesn’t issue an explicit Rollback or Commit.

  • Error handling:

    • Throw exception

      When an error occurs an exception is thrown and the execution of the workflow is aborted.

    • Write to output stream

      When an error occurs the error message is issued as an XML file and the execution of the workflow continues. The error message can be handled by a downstream module.

Multi IDoc processing

(only for the IDoc communication mode)

Activate this option if more than one IDoc is to be processed during the execution of a workflow. Normally, a single IDoc is processed in a workflow. In that situation, a connection to the SAP system is established via the SAP connector, the message is sent and the connection is closed. If you want to process a very large number of IDocs in a short time, it makes sense to establish the connection to the SAP system and send all the messages in one go.

The IDocs that are to be sent must be gathered into a single message (Multi IDoc) with the start of each IDoc being clearly indicated by an XML element. The SAP connector splits up the Multi IDoc at this element and sends the individual IDocs, one after the other, over the same connection.

XML IDoc splitting element

Enter the XML element (incl. path) that indicates the start of an IDoc message. The split includes the splitting element: e.g. an XML structure /Root/ADRMAS02/IDOC and the splitting element /Root/ADRMAS02 becomes an IDoc with the structure /ADRMAS02/IDOC.

module guide 1152 0

The figure shows elements in a Multi IDoc (left) and elements in an IDoc (right).

Connection Pool

(only when used as a medium/output connector, independent of communication mode)

  • Max. number of connections

    Maximum number of connections in the connection pool. Take note of OSS notes 314530 and 316877 on setting up external connections in the SAP system and/or SAP gateway.

  • Max. waiting time for connection

    Specifies the maximum time (in milliseconds) to wait for an available connection. If no connection is available after the specified time period has elapsed, a JCo exception is thrown with the key JCO_ERROR_RESSOURCE. The default is 30000 milliseconds (30 seconds).

  • Connection timeout

    This timeout relates only to connections that are released in the connection pool and are kept open for re-use (pooled connections). It does not relate to connections that are currently in use. A pooled connection is closed if it has not been activated when the specified time period expires. The period is specified in milliseconds; default is 600000 milliseconds (10 minutes).

Connection test

  • Test connection

    For testing whether the connection can be successfully established using your configuration.

Metadata cache

  • Refresh

    For updating the metadata cache (including all BAPI and IDoc structures).

    Refreshing the metadata cache will affect all SAP system connectors using the same gateway.

Press Esc to exit full screen
Modal image placeholder
Press Esc to exit full screen