SAP Event Listener Get Started Guide¶

Introduction¶

This guide summarizes the configuration steps that are needed to start using the SAP Event Listener and describes how Harmony and the SAP Event Listener process IDoc events.

Get Started Steps¶

Use the steps below as a guide to the recommended order in which to complete the setup of the SAP Event Listener. These steps include links to other pages within the SAP Event Listener section of documentation that provide additional details and instructions.

1. Configuring the SAP System¶

An SAP administrator must configure the SAP system as described in SAP Event Listener SAP System Configuration. As part of this process, they will configure the Jitterbit RFC destination, create a tRFC port (the tRFC port is used for both tRFC and qRFC function calls), and set up Jitterbit as an SAP partner.

At this stage in the configuration process, an SAP administrator will not be able to successfully test the connection within the SAP system, as additional configuration is necessary outside of the SAP system to establish connectivity.

2. Downloading the SAP JCo SDK Files¶

An SAP user must download the SAP Java Connector (SAP JCo) 3.1 SDK files from the SAP page SAP Java Connector under the section Download Java Connector 3.1 SDK (login to SAP required). These files are needed during the installation of the SAP Event Listener application, as described in Downloading Required Components in SAP Event Listener Installation.

3. Installing the SAP JCo SDK Files¶

A user with access to each machine where the SAP Event Listener is to be installed must install the relevant JCo SDK files as described in Install Required Components in SAP Event Listener Installation.

4. Downloading the SAP Event Listener¶

A Harmony user must download the SAP Event Listener from the Harmony Portal Downloads page as described in Downloading the SAP Event Listener in SAP Event Listener Installation.

5. Installing the SAP Event Listener¶

A user with access to each machine where the SAP Event Listener is to be installed must install the SAP Event Listener application as described in SAP Event Listener Installation. During the installation process, you are prompted to configure the SAP Event Listener, as described in the next step.

6. Configuring the SAP Event Listener¶

A user with access to each SAP Event Listener machine must configure the SAP Event Listener application as described in SAP Event Listener Configuration.

At this stage in the configuration process, the Event Details portion of the SAP Event Listener configuration cannot be completed, as additional configuration outside of the SAP Event Listener configuration is required to obtain the input for this field. Leave the Event Details portion of the configuration empty until directed in a later step.

You must also add the SAP gateway port to the operating system's services file, if not already present.

You can then test the connection within the SAP Event Listener configuration and verify that the SAP Event Listener service is running. The service should be running even though event details have not yet been entered.

7. Enabling SAP IDoc Events in Design Studio¶

A Harmony user who is designing the integration project must enable a setting in the Design Studio application that allows configuration of SAP IDoc Events as described in Enabling SAP IDoc Events in SAP Event Listener Design Studio Configuration and Use.

8. Obtaining Event Details¶

A Harmony user who is designing the integration project must create an SAP IDoc Event operation for each event in Design Studio to obtain the event configuration needed to complete the SAP Event Listener configuration. This is described in Creating an SAP IDoc Event Operation and Obtaining Event Details in SAP Event Listener Design Studio Configuration and Use.

9. Finishing Configuration of the SAP Event Listener¶

A user with access to each SAP Event Listener machine must finish configuring the SAP Event Listener application by entering the event configurations obtained in the previous step into the Event Details field of the SAP Event Listener configuration. The Event Details are entered in the SAP Event Connection Properties section of the SAP Event Listener configuration.

10. Restarting the SAP Event Listener Service¶

A user with access to each SAP Event Listener machine must restart the SAP Event Listener service after configuration changes, as described in Restarting the SAP Event Listener Service in SAP Event Listener Installation.

11. Verifying Connectivity with the SAP Event Listener¶

An SAP administrator should verify connectivity between the SAP gateway and the SAP Event Listener by testing the connection of the configured RFC destination. This is described in Verifying Connectivity with the SAP Event Listener in SAP Event Listener SAP System Configuration.

Understanding IDoc Event Processing¶

This section describes how Harmony and the SAP Event Listener process each IDoc event, depending on whether the queued RFC (qRFC) protocol or transactional RFC (tRFC) protocol is used. The program ID configured in the SAP RFC destination is used by Harmony and the SAP Event Listener to receive the IDoc event.

Processing of qRFC IDoc Events¶

At any point in time when qRFC IDocs are sent from SAP to a registered server program ID, the Harmony operations receive the IDocs in sequence for that particular queue. The Harmony operations also complete processing of qRFC IDocs in the same sequence order the IDocs were received.

Processing of qRFC IDoc events occurs in this order:

SAP sends the first qRFC IDoc for a program ID through the SAP Event Listener. Harmony blocks SAP from sending another qRFC IDoc until the operation has successfully completed processing the current qRFC IDoc.
Harmony sends a success message only after the operation has successfully completed. The success message is sent through the SAP Event Listener to SAP.
Once a success message for the first qRFC IDoc is received by SAP, the next qRFC IDoc in the sequence for the program ID is sent to the SAP Event Listener.
If the operation fails to successfully process the qRFC IDoc, Harmony sends a failure message through the SAP Event Listener to SAP. SAP resends/retries the qRFC IDoc until a success message is received from the SAP Event Listener.
The SAP Event Listener receives the next qRFC IDoc related to the queue / program ID from SAP only after the previous IDoc is successfully processed. However, the SAP Event Listener does receive other messages for processing that belong to a different queue / program ID.

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. You can verify in the log files if the last qRFC IDoc was successfully processed:

If the qRFC IDoc was successfully processed by Harmony, make sure any failed message for that qRFC IDoc are deleted from SAP prior to restarting the SAP Event Listener.
If 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.

Processing of tRFC IDoc Events¶

At any point in time when tRFC IDocs are pushed from SAP to a registered server program ID, Harmony operations complete processing of the tRFC IDocs in any order. The tRFC IDocs are 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 Private Agent can complete the process.

At any point in time, the SAP Event Listener ensures failed tRFC IDocs are stored within SAP.

If the SAP Event Listener is configured on multiple Private Agents in a Private Agent Group, and one tRFC IDoc is sent by SAP to any registered program ID, only one of the SAP Event Listener instances receives the IDoc.

For example, if five tRFC IDocs are pushed from SAP, all five IDocs can be received by the same SAP Event Listener, or the five IDocs can be distributed across a number of SAP Event Listener instances.