Skip to end of metadata
Go to start of metadata

NOTE: 

  • The Jitterbit Harmony SAP Event Listener is a separate module that requires installation on a private agent. Please contact your Customer Success Manager for access to the installation file.
  • The SAP Event Listener is compatible with either SAP ECC version 6 and above or SAP S/4HANA on-premises. Version 8.29.2.3 of SAP Event Listener is required to connect to SAP S/4HANA on-premises.
  • Jitterbit Harmony Private Agent version 8.29.2.5 or higher is required to connect to SAP Event Listener Version 8.29.2.3.
  • The SAP Event Listener is currently available only for Windows 64-bit machines. The SAP Event Listener requires Windows Server 2012 R2 or higher, or a desktop with Windows 8 or higher.

  • The SAP Event Listener installs and runs as a service.

  • Please see Private Agent System Requirements for all operating system requirements.

Introduction and Objective

This document outlines the steps to install and configure the SAP Event Listener. Using this document, a Jitterbit user can configure the SAP Event Listener and communicate with an SAP system. This document assumes that the SAP system has already been customized for external communication and all required settings such as the RFC destination, communication port and partner profiles are maintained in SAP. The SAP configuration steps are detailed in a separate document, SAP Configuration for Communication with Jitterbit.

Configuration

The SAP Event Listener is an application that should be installed with a Jitterbit Harmony Private Agent.  It uses a set of SAP libraries that requires Windows Server 2012 R2 or higher, or a desktop with Windows 8 or higher. Technically, it is possible to install the SAP Event Listener on a different machine than the private agent machine.  However, to prevent licensing issues and other communication issues, it is recommended that the SAP Event Listener is installed on the same machine as the private agent. It is also possible that Jitterbit may not allow the separate configuration of the event listener and the private agent in the future.

The SAP Event Listener is currently available only for Windows 64-bit machines. The SAP Event Listener installs and runs as a service.

NOTECheck that the SAP system is configured to establish communication with Jitterbit before attempting to configure the SAP Event Listener. See SAP Configuration for Communication with Jitterbit.

SAP Ports

SAP ports all begin with 31, 32, or 33 followed by the two digit system number.  The default is 3300.

The SAP gateway generally begins with 33 followed by the gateway number.  If the gateway is 17, the gateway port is 3317. The Jitterbit SAP Event Listener also requires the gateway port to be added to the services file.

Configuration Steps

Preparation

  • Organize and collect the SAP configuration parameters. You will need:
    1. SAP connection information such as SAP hostname, username, password, system number, SAP client, language, SAP gateway host and the SAP Gateway service are required.
    2. Parameter values from the SAP customization steps for communication with Jitterbit such as SAP RFC destination name, IDoc type name and IDoc message type are also required.

NOTE: Check that all ports that are related to the gateway for tRFC and qRFC are identified and specified in the C:\Windows\System32\drivers\etc\services file.  The SAP Event Listener will not communicate if all of the necessary ports are not listed.

Installation - Upgrade to SAP Event Listener 8.29.2.3

  • Uninstall any prior version of SAP Event Listener.
  • Download and install Jitterbit Design Studio 8.29.2.8 or higher.
  • Download and install Windows Private Agent version 8.29.2.5 or higher. 
  • Download and install SAP Event Listener version 8.29.2.3 on the same machine as the Private Agent.
  • During the installation process, the SAP Event Configurations screen displays as shown in the image below. 

  • SAP Version: Select either ECC or S4HANA (S/4HANA) as the version of your SAP system.

  • UserName: Enter the username for logging in to the SAP system.

  • Password: Enter the password for logging in to the SAP system.

  • Client: Enter the numeric client ID associated with the SAP system. The organization's SAP administrator can supply this information.

  • Language: Enter the language in which SAP messages should be sent. The default language is English.

  • Router: If the SAP system is protected by a firewall, enter the router string required to connect to it.

Configuring for a Direct SAP Connection

  • Complete these fields if the SAP connection is a direct server connection (default).
  • Application Host: Enter the SAP Application Server Host Name.

  • System Number: Enter the SAP System Number.

Configuring for a Load Balanced SAP Connection

  • Complete these fields if the SAP connection processes requests through a load balancer.

  • 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

  • GatewayHost: Enter the Gateway Host.
  • GatewayService: Enter the Gateway Service.
  • Listener Count: You can enter the number of listener threads that you want to run as part of this listener service, depending on your throughput requirements. 
  • Event Details: Leave the event details without changes for the moment. 
  • You can perform a test of this connection to validate the inbound communication with SAP by clicking the Test Connection button.

Services File

  • After configuring the SAP Event Listener, verify the services file (C:\Windows\system32\drivers\etc\services) contains this entry:

    sapgw00  3300/tcp
  • If this entry is not in the file, manually add the entry and restart the SAP Event Listener agent services.
  • The default gateway address is sapgw00 (3300). If the SAP system uses a different gateway number, such as '17', add these entries:

    sapgw00  3300/tcp
    sapgw17  3317/tcp

    NOTE: When running a connection test, in case of failure, one of the Error Details will be the LOCATION, as in "LOCATION" SAP-Gateway on hostxxxx/sapgw##. This will give you the SAP gateway number.

  • Save the configuration and complete the next installation steps.

SAP Event Listener High Availability

  • SAP Event Listener functionality is now extended to support installing on multiple servers and running in multi-server mode, supporting High Availability for both qRFC and tRFC protocols.

  • Install Windows Private Agent version 8.29.2.5  or higher on multiple servers.
  • Install SAP Event Listener version 8.29.2.3 on multiple servers following the installation steps above.
  • Follow the installation steps above to complete the SAP Connection Properties for each separate installation of the SAP Event Listener.
  • Follow the instructions below to copy the Event Configuration for each IDoc Event ( such as qRFC, tRFC, multiples of each) to each SAP Event Listener Configurations file.

NOTE: Check that that there is the same number of SAP Event Listeners as Private Agent installations, so that each SAP Event Listener has an Agent installed on the same server.

qRFC Processing

  • At any point in time when qRFC IDocs are sent from SAP to a qRFC ProgramID, the Jitterbit operations will receive the IDocs in sequence for that particular queue. The Jitterbit operations will also complete processing of qRFC IDocs in the same sequence order the IDocs were received.
  • SAP will send the first qRFC IDoc for a ProgramID through the SAP Event Listener.
  • Jitterbit will block SAP from sending another qRFC IDoc until the operation has successfully completed processing the current qRFC IDoc.
  • Jitterbit will send the success message only after the operation has successfully completed. The success message will be sent through the SAP Event Listener to SAP.
  • Once the success message for the first qRFC IDoc is received by SAP, the next qRFC IDoc in the sequence for the ProgramID will be sent to the SAP Event Listener.
  • If the operation fails to successfully process the qRFC IDoc, Jitterbit will send a failure message through the SAP Event Listener to SAP.
  • SAP will resend/retry the qRFC IDoc until a success message is received from the SAP Event Listener. 
  • The SAP Event Listener will receive the next qRFC IDoc related to the queue/ProgramID from SAP only after the previous IDoc is successfully processed, however, it will receive other messages for processing that belong to a different queue/ProgramID.

NOTE:

  • If the SAP Event Listener goes down or is stopped while processing a qRFC IDoc, the SAP Event Listener will not receive a success or failure message. It will be necessary to verify in the log files if the last qRFC IDoc was successfully processed or not. If the qRFC IDoc was successfully processed by Jitterbit, it will be necessary to make sure any failed message for that qRFC IDoc is deleted from SAP prior to restarting the SAP Event Listener. If the log indicates the qRFC IDoc operation did not complete successfully, SAP will already be waiting in a failed state. In that case, restart the SAP Event Listener, and SAP will resend/retry to process the previous qRFC IDoc.
  • The SAP EVENT configuration properties for each IDoc Event must be the same across all SAP Event Listener instances. See Event Configuration.

tRFC Processing

  • At any point in time when tRFC IDocs are pushed from SAP to a tRFC ProgramdID, Jitterbit operations will complete processing of the tRFC IDocs in any order. The tRFC IDocs will be processed in parallel across all available SAP Event Listener and Private Agent installations.
  • If any tRFC operation fails to complete processing, the SAP Event Listener can still receive other tRFC IDocs from SAP and the Jitterbit Agent can complete the process.
  • At any point in time, the SAP Event Listener will ensure failed tRFC IDocs are stored within SAP. 

NOTE:

  • If the SAP Event Listener is specifically set up for High Availability, and one tRFC IDoc is sent by SAP to any registered ProgramID, only one of the SAP Event Listener instances should receive the IDoc.
  • If 5 tRFC IDocs are pushed from SAP, all 5 IDocs can be received by the same SAP Event Listener, or the 5 IDocs can be distributed across all SAP Event Listener instances.
  • The SAP EVENT configuration properties for each IDoc Event must be the same across all SAP Event Listener instances. See Event Configuration.

Configuring SAP Event Listener Scenarios for tRFC and qRFC in Jitterbit

  • Once the basic configuration of the SAP Event Listener is complete, you can start configuring the various scenarios for the use cases in Design Studio.
  • Enable the SAP Event Listener in Design Studio Preferences. Select Edit > Preferences in the main menu in Design Studio to display the preferences page as shown in the image below.
  • Click on the navigation pane on the left side of the screen and select Connectors > SAP IDOC Events
  • Select the Enable SAP IDOC Events in the UI checkbox. 
  • Click OK to save the preferences.
  • This will enable the SAP IDoc Events. You should now be able to see an additional entry called SAP IDOC Events in the navigation pane under Connectors > SAP.
  • Create an operation with the SAP Event Listener in the project.
    • Right-click on SAP IDOC Events and select New IDOC Event
    • Select the SAP Endpoint from the dropdown list. Select Test Connection button.
    • The Connection Successful message will display. Click the Next button.
    • Enter the IDOC Message Type (DEBMAS, MATMAS, etc.).
    • Select the IDOC Type from the list displayed.

    • Enter the Program ID (e.g. KUB_IDOC_RFC).
    • Select the tRFC or qRFC radio button as shown in image below. Click the Finish button.

NOTE:

  • The default RFC Type is tRFC. After installing Jitterbit SAP Event Listener 8.29.2.3, all existing operations will automatically default to tRFC and be processed as tRFC.
  • There is not an option to change the protocol from tRFC to qRFC or from qRFC to tRFC.
  • Any qRFC IDoc Events/Operations will need to be created from scratch after upgrading to SAP Event Listener 8.29.2.3.
    • Create the Transformation.
    • Complete mapping the Source to the Target.

Event Configuration

    • Once the operation is complete, you can right-click on the Operation and select View SAP Event Listener Configuration from the context menu. The Event Configuration dialog window displays as shown in the images below.

       tRFC Event Configuration

  

  qRFC Event Configuration

 

    • Click on the Copy to Clipboard button to save the Event Configuration on the Clipboard.
    • Start Configure Jitterbit SAP Listener from the Start Menu.

    • Paste the contents of the Clipboard into the Event Details field as shown in the image above. 
    • Verify the contents of the clipboard are within a set of <event> and </event> XML tags.
    • If you have more than one IDoc being sent from SAP (e.g. tRFC, qRFC, multiples of each type), copy each Event Configuration into the Event Details field within the SAP Event Configurations window. Each set of event configurations must be within <event> and </event> XML tags.
    • Click the Save button to save the configuration and close the UI.
    • Restart the SAP Event Listener service from the Start Menu or from the Services Control Panel.

      WARNING: The RFC Destination should NOT be tested in SAP until after the Event Details have been entered and saved in the SAP Event Listener and the SAP Event Listener service has been restarted. Testing the RFC Destination in SAP prior to saving the Event Details in the SAP Event Listener will result in an error due to a missing profile name.

Troubleshooting

Validating the Event Listener communication

  1. Once the configurations are complete, scenarios are established in Jitterbit and the listener service is running, you can validate the connection from SAP.
  2. Log in to the SAP GUI.
  3. Navigate to transaction code ‘SM59’.
  4. Select the RFC destination configured for communication with Jitterbit.
  5. Press the connection test button from the toolbar to perform a connection test from the SAP system to the Jitterbit SAP Event Listener.
  6. A successful connection test result confirms the configuration.

NOTE:

  • In some cases, it is observed that this test fails if the Unicode settings on the RFC destination are not set properly. Correct the settings on the RFC destination, restart the Jitterbit SAP Event Listener service and perform the test again.
  • When doing a connection test, in case of failure, one of the Error Details will be the LOCATION, as in "LOCATION" SAP-Gateway on hostxxxx/sapgw##. This will give you the SAP gateway number.

Editing Ports in Services File

  • As an Administrator, open Notepad.
  • Open the C:\windows\System32\drivers\etc\services file.
  • Add all ports that are related to the gateway for tRFC and qRFC at the end of the file.
  • Save the file and restart the SAP Event Listener.

Known Issues

Invalid ProgramID

  • In the case of an invalid ProgramID being added into the SAP Event Listener configuration file, the SAP Event Listener will start with no errors. Since SAP does not have this invalid ProgramID, no message will be triggered for that ProgramID and no message will be sent to the SAP Event Listener. 
  • If messages are not being received by SAP Event Listener from SAP, and/or SAP is not receiving success/failure messages from SAP Event Listener, make sure the ProgramID and IDoc Type are specified correctly in the SAP Event Configuration.
  • Eventually SAP will throw an error on invalid ProgramIDs, which can be seen in the logs (see example below).
Jul 27, 2017 1:53:59 AM org.apache.catalina.startup.Catalina start
INFO: Server startup in 10084 ms
Jul 27, 2017 5:21:23 AM com.ubs.core.adapter.sap.idoc.event.DefaultErrorListener serverExceptionOccurred
INFO: ServerException occured on TEST_KUB_IDOC1 connection 3-ecc35.sapaccess.com|sapgw00|TEST_KUB_IDOC1
Jul 27, 2017 5:21:23 AM com.ubs.core.adapter.sap.idoc.event.DefaultErrorListener serverExceptionOccurred
INFO: TID is null
Jul 27, 2017 5:21:23 AM com.ubs.core.adapter.sap.idoc.event.DefaultErrorListener serverExceptionOccurred
INFO: Session is null
Jul 27, 2017 5:21:23 AM com.ubs.core.adapter.sap.idoc.event.DefaultErrorListener serverExceptionOccurred
INFO: CallType is 
Jul 27, 2017 5:21:23 AM com.ubs.core.adapter.sap.idoc.event.DefaultErrorListener serverExceptionOccurred
INFO: ServerException occured on TEST_KUB_IDOC1 connection 3-ecc35.sapaccess.com|sapgw00|TEST_KUB_IDOC1
Jul 27, 2017 5:21:24 AM com.ubs.core.adapter.sap.idoc.event.DefaultErrorListener serverExceptionOccurred
INFO: ServerException occured on TEST_KUB_IDOC1 connection null

SAP Will Send an IDoc Type to an SAP Event Listener Configured for the Opposite Type

Issue 1

  • SAP Event Listener is configured for DEBMAS
  • RFC Type = tRFC 
  • ProgramID is for tRFC
  • SAP sends a MATMAS IDoc (opposite type)
  • If SAP sends a MATMAS IDoc to the SAP Event Listener, the SAP Event Listener gets triggered, but the operation does not execute.
  • By reviewing the log file, you can see the Event Listener is committing and confirming the same TID it received.

Issue 2

  • SAP Event Listener is configured for MATMAS
  • RFC Type = tRFC
  • ProgramID is for tRFC
  • SAP sends a DEBMAS IDoc (opposite type)
  • If SAP sends a DEBMAS IDoc to the SAP Event Listener, the SAP Event Listener gets triggered, but the operation does not execute.
  • By reviewing the log file, you can see the Listener is committing and confirming the same TID it received.
On This Page

Related Topics

Last updated:  Sep 23, 2020