Configuration of Jitterbit Design Studio SAP Event Listener

Introduction

During the SAP Event Listener installation process, you are prompted to configure the SAP Event Listener.

You can also reconfigure the SAP Event Listener after the installation process is complete. When reconfiguring the SAP Event Listener, it is recommended to restart the service after configuration (see Restarting the SAP event listener service in SAP event listener installation).

These activities related to configuring the SAP Event Listener are detailed on this page:

Accessing the SAP event listener configuration
Entering input into the SAP event listener configuration
Adding the gateway port to the services file
Testing the connection and verifying the service is running

As described later on this page, when configuring the SAP Event Listener for the first time, you will not yet be able to complete the Event Details portion of the configuration. Instead, you can leave this portion of the configuration empty until you have obtained the necessary input for this field. The necessary input is generated as described in Creating an SAP IDoc event operation and obtaining event details in SAP event listener Design Studio configuration and use.

For the recommended order of all steps required to configure and use the SAP Event Listener, see the SAP event listener get started guide.

Accessing the SAP event listener configuration

The method by which you access the SAP Event Listener configuration depends on whether the SAP Event Listener is installed on Windows or Linux. As the configuration fields are similar for both Windows and Linux, they are described together in the next section, Entering input into the SAP event listener configuration.

Windows

Configuration of the SAP Event Listener is done through the SAP Event Listener configuration screen.

To return to the configuration screen after initial configuration, use the Windows start menu to locate the Jitterbit SAP Event Listener and select Configure Jitterbit SAP Listener:

attachment

The SAP Event Configurations screen is displayed:

attachment

As an alternative to entering the configuration graphically, you can manually edit the SAP Event Listener configuration file at this location:

C:\ProgramData\JitterbitSAPEventListener\conf\sapeventconfig.xml

Linux

Configuration of the SAP Event Listener using a direct connection is done by executing a shell script on the command line. Change directories to the appropriate location and then run the script:

# cd /opt/jitterbitsap/bin

# ./runconfig.sh

The script steps through the initial configuration fields where you provide input to configure the SAP Event Listener:

*SAP Event Configurations*
Sap Connection Properties
    UserName [] : wxyz
    Password [] :
    Application Host [] : ecc99.sapaccess.com
    System Number [] : 00
    Client [] : 800
    Language [en] : en

SAP Event Connection Properties
    GateWay Host [] : ecc99.sapaccess.com
    GateWay Service [] : sapgw00
    Listener Count [1] : 1

URL [https://127.0.0.1:46908/jitterbit_sap_destination] : http://127.0.0.1:46908/jitterbit_sap_destination

To configure the SAP Event Listener to use a load balancer connection, you must manually edit the SAP Event Listener configuration file at this location:

/opt/jitterbitsap/data/JitterbitSAPEventListener/conf/sapeventconfig.xml

In the <connection> section, add these properties:

<eventconfiguration>
    <connection>
        . . .
        <mshost></mshost>
        <mspost></mspost>
        <groupname></groupname>
        <systemid></systemid>
    </connection>
   . . .
</eventconfiguration>

Entering input into the SAP event listener configuration

This section provides definitions of the SAP Event Listener configuration fields for Windows or Linux.

SAP connection properties

These fields are used to supply basic properties of the SAP endpoint:

SAP Version: Select ECC or S4 HANA as the version of the SAP system. Though this setting is unavailable in the Linux version, both ECC and S4 HANA are supported without needing to specify the version.
Username: Enter the username for the SAP system.
Password: Enter the password for the SAP system.
Client: Enter the numeric client ID associated with the SAP system.
Language: Enter the language code for the language in which SAP messages should be sent, such as en for English.
Router: If the SAP system is protected by a firewall, enter the router string required to connect to it. This setting is not supported in the Linux version.

Direct connection

Complete these fields if the SAP endpoint has a direct server connection. As settings for only either a direct connection or a load balancer connection can be configured, these fields are not used if the fields as listed under Load balancer connection below are also completed.

Application Host: Enter the SAP application server host name.
System Number: Enter the SAP system number.

Load balancer connection

Supply values for these fields if the SAP endpoint processes requests through a load balancer. As settings for only either a direction connection or a load balancer connection can be configured, these fields are not used if the fields listed under Direct connection above are also completed.

Note

For Linux, values for these fields must be manually defined in the Linux SAP Event Listener configuration file rather than the through the configuration script, as described in the previous section.

MSHost: Enter the SAP message server host name.
MSPort: Enter the SAP message server port.
Group Name: Enter the SAP group name of the application servers.
System ID: Enter the SAP system ID.

SAP event connection properties

These fields are used to configure the SAP Event Listener connection:

Gateway Host: Enter the gateway host.
Gateway Service: Enter the gateway service.
Listener Count: Enter the number of listener threads that you want to run as part of this listener service, depending on your throughput requirements. The default is 1.
Event Details: Enter the details of each IDoc event (tRFC and qRFC). Note, depending on whether you are using the Windows or Linux version of the SAP Event Listener:
- Windows: During the initial SAP Event Listener configuration, you can leave the Event Details empty if you have not generated these details yet.
- Linux: During the initial SAP Event Listener configuration, the shell script does not prompt you to provide event details. Instead, once you have generated the event details, you must manually add them to the configuration XML file, located at:
```
/opt/jitterbitsap/data/JitterbitSAPEventListener/conf/sapeventconfig.xml
```
These details must be generated for each SAP IDoc Event operation created in Jitterbit Design Studio. After completing Creating an SAP IDoc event operation and obtaining event details in SAP event listener Design Studio configuration and use, enter the details of each IDoc event here. When entering the details, note:
- The entire input of this field must be enclosed within a set of outer <events> and </events> XML tags.
- Within that outer set of tags, each event must be enclosed within a set of <event> and </event> XML tags.
- You can enter both tRFC and qRFC events.
For example:
```
<events>
<event>
    <program_id>JITTERBIT</program_id>
    <idoctype>DEBMAS06</idoctype>
    <rfctype>tRFC</rfctype>
    <environment_id>447551</environment_id>
    <operation_guid>ec557feb-b220-400e-9987-fe5d063b7057</operation_guid>
</event>
<event>
    <program_id>JITTERBIT</program_id>
    <idoctype>MATMAS05</idoctype>
    <rfctype>qRFC</rfctype>
    <environment_id>447551</environment_id>
    <operation_guid>bd557feb-b220-400e-9987-fe5d063b7066</operation_guid>
</event>
</events>
```
Tip

If adding event details after the initial configuration, restart the SAP Event Listener in order for the configuration changes to take effect (see Restarting the SAP event listener service in SAP event listener installation).
Caution

The Event Details field currently has this known issue:
- SAP Event Listener: The Windows configuration UI cannot be opened
  - Summary: On attempting to open the Windows SAP Event Listener configuration through the UI, an exception occurs.
  - Additional Information: This issue occurs when a previously saved configuration that includes the required outer set of <events> and </events> tags in the Event Details field has since been inadvertently saved without those tags.
  - Recovery: Manually edit the configuration file at C:\ProgramData\JitterbitSAPEventListener\conf\sapeventconfig.xml to replace the required outer tags. The Windows configuration UI can again be opened.
  - URL: The prepopulated SAP Event Listener URL. If following our recommendation to install the SAP Event Listener on each private agent in a private agent group, the input in this field does not need to be modified. If installing the SAP Event Listener on a machine different from that where the private agent is installed, contact Jitterbit support.
Tip

For temporary troubleshooting purposes in non-production environments, you can intentionally enter an invalid URL in the configuration. This will cause the SAP Event Listener to fail to send the payload to the agent and instead write the payload to the operation log.

Adding the gateway port to the services file

On each machine where the SAP Event Listener is installed, the SAP gateway port must be present in the operating system's services file. If using the default SAP gateway port (3300), the port may or may not already be present in the services file.

The services file is located at these directory paths:

Windows: C:\Windows\System32\drivers\etc\services
Linux: /etc/services

SAP ports begin with 31, 32, or 33, followed by a two-digit system number.

The default SAP gateway port begins with 33, followed by 00 as the gateway number. That is, the default SAP gateway port is 3300. If present, the default SAP gateway port is represented in the services file by this entry:

sapgw00  3300/tcp

If the default gateway port entry is missing from the services file, or if the gateway port is different from the default, you must add it to the services file. For example, if the gateway number is 17, then add a gateway port of 3317 to the services file:

sapgw17  3317/tcp

After adding an entry to the services file, restart the SAP Event Listener service as described in Restarting the SAP event listener service in SAP event listener installation.

Testing the connection and verifying the service is running

After confirming that the gateway port has been added to the operating system's services file, perform a test of the connection to validate the inbound communication with SAP and verify that the SAP Event Listener service is running. The service should be running even if the Event Details portion of the SAP Event Listener configuration has not yet been completed.

Windows

On Windows, in the SAP Event Listener configuration screen, click the Test Connection button. A dialog should indicate that the connection was successful:

attachment

Check that the Jitterbit SAP Event Listener service is running in Windows Services:

attachment

Linux

On Linux, testing the connection is the last step of the configuration script. When prompted to test the connection, enter y:

Perform test connection [y/n]?y

Output similar to this for a successful connection test is displayed:

KFile is ../data/JitterbitSAPEventListener/conf/.pk is exist false

. . .

Test connection to SAP is success.

Check that the SAP Event Listener service is running using ps -ef :

# ps -ef | grep -v grep | grep 'jitterbitsap'

Output similar to this is displayed:

Djava.util.logging.config.file=/opt/jitterbitsap/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Xms512m -Xmx1024m -Djava.endorsed.dirs= -classpath /opt/jitterbitsap/bin/bootstrap.jar:/opt/jitterbitsap/bin/tomcat-juli.jar -Dcatalina.base=/opt/jitterbitsap -Dcatalina.home=/opt/jitterbitsap -Djava.io.tmpdir=/opt/jitterbitsap/temp org.apache.catalina.startup.Bootstrap start

You can also troubleshoot by tailing the catalina.out log file:

# tail ../logs/catalina.out

Output similar to this is displayed:

05-Feb-2021 22:18:13.534 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployDirectory Deploying web application directory [/opt/jitterbitsap/webapps/manager]
05-Feb-2021 22:18:13.561 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployDirectory Deployment of web application directory [/opt/jitterbitsap/webapps/manager] has finished in [27] ms
05-Feb-2021 22:18:13.562 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployDirectory Deploying web application directory [/opt/jitterbitsap/webapps/ROOT]
05-Feb-2021 22:18:13.572 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployDirectory Deployment of web application directory [/opt/jitterbitsap/webapps/ROOT] has finished in [10] ms
05-Feb-2021 22:18:13.572 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployDirectory Deploying web application directory [/opt/jitterbitsap/webapps/examples]
05-Feb-2021 22:18:13.750 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployDirectory Deployment of web application directory [/opt/jitterbitsap/webapps/examples] has finished in [178] ms
05-Feb-2021 22:18:13.751 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployDirectory Deploying web application directory [/opt/jitterbitsap/webapps/host-manager]
05-Feb-2021 22:18:13.762 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployDirectory Deployment of web application directory [/opt/jitterbitsap/webapps/host-manager] has finished in [11] ms
05-Feb-2021 22:18:13.766 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["http-nio-8080"]
05-Feb-2021 22:18:13.787 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in 1647 ms