Show TOC

InstallationLocate this document in the navigation structure

Purpose

You install the Adapter Engine , including available adapters, so that you can then configure and use them to convert the respective message formats. You can install adapters individually or together as required, but always separately for inbound processing (sender adapter) and outbound processing (receiver adapter) by the Integration Engine.

Prerequisites

To install adapters, you require the following:

  • A Java Runtime of 6.0 or higher.
  • The optional package Java Servlet Version 2.3 or higher (servlet.jar). This can be located, for example, on the SAP Web Application Server or directly on the Internet at
    http://java.sun.com/products/servlet/index.html
    (download from servlet.jar). You can copy the package directly to the adapter installation directory (tech_adapter); otherwise it must be located in the Java CLASSPATH.
  • Additionally for the JMS adapter
    • The optional package Java Messaging Service (jms.jar). This can be located, for example, on the SAP Web Application Server or directly on the Internet at
      http://java.sun.com/products/jms/index.html
      (download from jms.jar).
    • A JMS driver installation for the queue system to be connected to (for example, WebSphereMQ). The required Java libraries are product-specific and can be obtained from either the product vendor or other providers. The Java libraries must be located in the Java CLASSPATH following installation so that the JMS adapter can access the required Java classes at runtime.
  • Additionally for the JDBC adapter

    A JDBC driver installation (version 2.0) for the database product to be connected to. The required Java libraries are product-specific and can be obtained from either the database vendor or other providers. The Java libraries must be located in the Java CLASSPATH following installation so that the JDBC adapter can access the required Java classes at runtime.

  • Additionally for HTTPS protocol
    If the adapters are to communicate using HTTPS, additional libraries to implement the SSL protocol are required. You can download the Java libraries iaik_jce.jar and iaik_ssl.jar from SAP Service Marketplace (
    service.sap.com
    ) Software Distribution Center, under SAP Cryptographic Software, but ensure that you follow the regulations outlined there.

    You must include both libraries in the Java CLASSPATH after installation.

    • If the sender adapter is to communicate with the Integration Server using HTTPS, you can use the HTTPS protocol instead of HTTP for XI.TargetURL (
      https://http://
      instead of ).
    • If the Integration Server is to communicate with the receiver adapters using HTTPS protocol, you must configure the HTTP server correspondingly for the adapters. This is achieved using the HttpServer service.
    • If the browser is to be connected to the Adapter Engine configuration screen using HTTPS protocol, you must configure the GuiBrowserEngine service correspondingly.
  • Additionally for UNIX operating systems

    In UNIX operating systems, a bash shell must be installed to enable the run_adapter.sh script to be used. Otherwise, the run_adapter.cmd script can be used to start the Adapter Engine (Java SE).

The Java runtime (java.exe) is located in the search path, if installation was performed correctly.

The packed adapter-installation file has been unpacked in a directory of your choice and you have retained the path structure.

Process Flow

New Installation

Within the directory you used to unpack the installation file you will find the subdirectory tech_adapter with further subdirectories such as Administration, Configuration, and LogFiles. All configuration data for the Adapter Engine is stored in the tech_adapter directory or in sub directories of tech_adapter.

To install an adapter, switch to the directory tech_adapter.

  • To install the file/FTP adapter, execute the following:
    • Microsoft Windows:install_fileadapter.bat
    • UNIX: install_fileadapter.cmd
  • To install the JDBC adapter, execute the following:
    • Microsoft Windows: install_jdbcadapter.bat
    • UNIX:install_jdbcadapter.cmd
  • To install the JMS adapter, execute the following:
    • Microsoft Windows: install_jmsadapter.bat
    • UNIX:install_jmsadapter.cmd
  • To install the SOAP adapter, execute the following:
    • Microsoft Windows: install_soapadapter.bat
    • UNIX:install_soapadapter.cmd

These scripts generate the default configuration in the adapter menu for the respective adapter type. If you do not call any of the scripts then the default configurations for all adapters are found in the adapter menu. However, you can modify the configuration of the adapter menu in each case by using the functions available there.

After the Adapter Engine is installed, the x-bits for scripts such as install_fileadapter.cmd, run_adapter.sh, and run_adapter.cmd are not set. Change these using the following commands:

chmod 755 *.cmd

chmod 755 *.sh

  • To start the Adapter Engine, execute the following:
    • Microsoft Windows:run_adapter.bat
    • UNIX: run_adapter.cmd or run_adapter.sh
When you have executed run_adapter.bat or run_adapter.cmd, you can call the Adapter Engine using a browser. The corresponding default address is
http://<hostname>:8200SAPinit
; when logging on for the first time, enter the user and the password . You must delete these initial users after you have created new users .

If the standard port 8200 of the Adapter Engine is already in use, you must enter a free port under port= in the file GuiBrowserEngine.properties.

Note

If this port is also already being used, the Adapter Engine displays the following error message in the window in which it was started and then it closes itself.

ERROR starting Adapter engine base service ´GUI´

Installation is now complete. On the Adapter Engine configuration screen you find two adapters (sender and receiver) for each of the installed adapter types (or one SOAP adapter) that you can configure there.

Note

You define the difference between sender and receiver for the SOAP adapter during configuration. This means that following installation, there is only one SOAP adapter for which you must then configure two different instances, if necessary.

To run multiple adapters of the same adapter type or different adapter types simultaneously, or to start adapters automatically, go to the configuration screen of the Adapter Engine.

Upgrading the Installation

If you want to install a more recent adapter version, or want to repeat the installation, you have two options:

  • The existing adapter configuration is not to be saved

    In this case, delete the existing installation beneath the installation directory completely and install the adapter as described above; the Adapter Engine does not contain any other data apart from this directory structure.

  • The existing adapter configuration and user management are to be saved
    1. Shut down the Adapter Engine (Java SE) (source release).
    2. Unpack the SAPXICONSnn_m.sca archive (from software component version XI CONNECTIVITY SE <target release>) to a temporary installation directory.

      Use a tool that can work with ZIP files for this.

    3. Switch to the directory tech_adapter beneath the installation directory and execute the following file:

      Microsoft Windows:save_configuration.bat

      UNIX: save_configuration.cmd

      Besides the directory tech_adapter, the system creates a new directory adapter_configuration.backup that contains all relevant files for adapter configuration and user management.

      If you have also changed the configuration of services and if these configurations also need to be saved, execute the following file as well:

      Microsoft Windows:save_baseconfiguration.bat

      UNIX: save_baseconfiguration.cmd

      If the backup of a component or configuration is not available because it has never been used or configured, you get a notification that the corresponding file or configuration is missing. The system proceeds with the back up of the pending configuration.

    4. Delete the directory tech_adapter beneath the installation directory.
    5. Unpack the TechnicalAdapters.sda archive from the temporary installation directory to the installation directory of the Adapter Engine (Java SE). Ensure that the path structure of the archive is maintained.
    6. Install the adapter as described above. Instead of the installation script, execute the following file in the directory tech_adapter:

      Microsoft Windows:restore_configuration.bat

      UNIX: restore_configuration.cmd

    This file reproduces the adapter configurations, including user management. The service configurations are also reproduced if you have also saved them. Otherwise the services are available in their original configuration, as is the case following a new installation.

Upgrading the Installation of an XI 2.0 Adapter Engine

If you want to apply the XI 2.0 adapter configuration to an XI 3.0 Adapter Engine, note that the XI 3.0 Adapter Engine recognizes configurations of the XI 2.0 Adapter Engine and handles them as follows:

  • Parameters with the same name are interpreted identically.
  • Parameters with the namespace XMB no longer exist in the XI 3.0 Adapter Engine. They are interpreted in the same way as parameters with the same name and the namespace XI.
  • The parameters
    XMB.SenderBusinessSystemXMB.ReceiverBusinessSystemXI.SenderServiceXI.ReceiverService
    and are interpreted as and, respectively.
  • The parameters XMB.SenderInterfaceNamespace and XMB.SenderInterfaceName are interpreted as
    XI.InterfaceNamespaceXI.Interface
    and , respectively.
  • The parameters
    XMB.SenderAdapterForBusinessSystemXMB.ReceiverAdapterForBusinessSystemXI.SenderAdapterForServiceXI.ReceiverAdapterForService
    and are interpreted as and , respectively.
  • There are no corresponding parameters for the parameters
    XMB.ContentTypeXMB.ContentKindfile.typeXMB.ContentKindfile type
    and , and they are ignored. The sender file/FTP adapter uses the parameter instead. Accordingly, is interpreted as a file.type binary or text . The same applies to the specifications for additional files in a message (for more information, see the description of XI.AdditionalPayloads in Configuring the Sender File/FTP Adapter ).

Continuous Operation

The following operating system-specific installation options are available to enable continuous operation of the Adapter Engine:

  • WindowsNT

    The program SAPAdapterService.exe, located in the directory tech_adapter in the Adapter Engine installation directory, is used to start the Adapter Engine as an NTService. To install or de-install the NTService, use the script install_service.bat or uninstall_service.bat. The call conventions are as follows:

    • install_service.bat [ServiceName] [JavaVM]
    • uninstall_service.bat [ServiceName]

    The [ServiceName] is a logical name that the service is created under, and [JavaVM] is the name of the DLL of the Java Virtual Machine with a complete path specification. Corresponding examples can be found in the script.

    All jar files (for example the JDBC or JMS driver) that may additionally be required by the adapters must be located in the Java classpath when install_service.bat is called. Subsequent changes to the classpath have no effect on the created NTService.

    Once installation is complete, you must start the Adapter Engine as an NTService in the Windows services menu or configure it the same as each NTService (startup type, logon information, and so on).

    The Windows results display displays information and error messages of the service under the corresponding service names in the application log. Adapter Engine console and error output is placed in the files stdout.log or stderr.logrespectively in the subdirectory LogFiles.

  • UNIX

    The script run_adapter.sh is located in directory tech_adapter for Unix operating systems. You must adjust the variable ADAPTER_HOME to the installation path in this script. In the variable EXTLIBS you can specify all Jar files that are additionally required by the Adapter Engine, for example to be able to load a JDBC or a JMS driver. For more information, refer to the USAGE section of the script. You can then insert the script in the boot procedure of the operating system.

Accessing the SAP System Landscape Directory

You can access the SAP System Landscape Directory (SLD) from the Adapter Engine. When the Adapter Engine starts, it can log on to the SLD, whereby the Runtime Workbench recognizes it as an SAP Exchange Infrastructure component, thus making it globally accessible.

Optionally, associations can also be created between individual receiver adapters and business systems if a business system is specified in the configuration of a receiver adapter. The addresses of the associated adapters are then automatically adopted as default values by the Integration Directory when end points are created for the business system.

Moreover, this enables information connected with business systems to be exported. For more information about configuring this service, see the section SLDaccessor in Services .

Note that this service is not mandatory and the Adapter Engine can function without being connected to the SLD.

Monitoring with the Runtime Workbench

The Runtime Workbench can access the Adapter Engine for monitoring purposes. The same HTTP port as for configuration is used for this purpose. To log on you require the technical user XIRWBUSER and the password
XIPASS
, but no other authorizations. This user is created automatically when the Adapter Engine is installed. The user must have the same password as in ExchangeProfile and in ABAP.

If this user is deleted (for example, when an older configuration is implemented following installation), or if the Runtime Workbench requires another user, you must create this user manually. The user to be created only requires the authorization group Locked. For more information about creating users, see User Management .