Plain J2SE Adapter EngineRelease 640 HELP.XI SAP Online Help 24.02.2004 Copyright © Copyright 2004 SAP AG. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. Microsoft®, WINDOWS®, NT®, EXCEL®, Word®, PowerPoint® and SQL Server® are registered trademarks of Microsoft Corporation. IBM®, DB2®, DB2 Universal Database, OS/2®, Parallel Sysplex®, MVS/ESA, AIX®, S/390®, AS/400®, OS/390®, OS/400®, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere®, Netfinity®, Tivoli®, Informix and Informix® Dynamic ServerTM are trademarks of IBM Corporation in USA and/or other countries. ORACLE® is a registered trademark of ORACLE Corporation. UNIX®, X/Open®, OSF/1®, and Motif® are registered trademarks of the Open Group. Citrix®, the Citrix logo, ICA®, Program Neighborhood®, MetaFrame®, WinFrame®, VideoFrame®, MultiWin® and other Citrix product names referenced herein are trademarks of Citrix Systems, Inc. HTML, DHTML, XML, XHTML are trademarks or registered trademarks of W3C®, World Wide Web Consortium, Massachusetts Institute of Technology. JAVA® is a registered trademark of Sun Microsystems, Inc. JAVASCRIPT® is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape. MarketSet and Enterprise Buyer are jointly owned trademarks of SAP AG and Commerce One. SAP, SAP Logo, R/2, R/3, mySAP, mySAP.com and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other product and service names mentioned are trademarks of their respective companies. Plain J2SE Adapter Engine 640 2 SAP Online Help 24.02.2004 Icons in Body Text Icon Meaning Caution Example Note Recommendation Syntax Additional icons are used in SAP Library documentation to help you identify different types of information at a glance. For more information, see Help on Help → General Information Classes and Information Classes for Business Information Warehouse on the first page of any version of SAP Library. Typographic Conventions Type Style Example text Description Words or characters quoted from the screen. These include field names, screen titles, pushbuttons labels, menu names, menu paths, and menu options. Cross-references to other documentation. Example text EXAMPLE TEXT Emphasized words or phrases in body text, graphic titles, and table titles. Technical names of system objects. These include report names, program names, transaction codes, table names, and key concepts of a programming language when they are surrounded by body text, for example, SELECT and INCLUDE. Output on the screen. This includes file and directory names and their paths, messages, names of variables and parameters, source text, and names of installation, upgrade and database tools. Exact user entry. These are words or characters that you enter in the system exactly as they appear in the documentation. Variable user entry. Angle brackets indicate that you replace these words and characters with appropriate entries to make entries in the system. Keys on the keyboard, for example, F2 or ENTER. Example text Example text <Example text> EXAMPLE TEXT Plain J2SE Adapter Engine 640 3 SAP Online Help 24.02.2004 Plain J2SE Adapter Engine ....................................................................................................... 5 Installation .............................................................................................................................. 6 Configuration........................................................................................................................ 10 Adapter Menu ................................................................................................................... 12 User Management............................................................................................................ 16 Password Management.................................................................................................... 18 Services............................................................................................................................ 19 Test Environment ............................................................................................................. 23 Configuring the File/FTP Sender Adapter............................................................................ 26 Configuring the Receiver File/FTP Adapter ......................................................................... 39 Configuring the Sender JDBC Adapter................................................................................ 47 Configuring the Receiver JDBC Adapter ............................................................................. 53 Document Format for the Receiver JDBC Adapter .......................................................... 57 Configuring the Sender JMS Adapter .................................................................................. 65 Configuring the Receiver JMS Adapter ............................................................................... 73 Settings for the JMS Provider .............................................................................................. 80 Configuring the SOAP Adapter ............................................................................................ 82 Using the Dispatcher: Example............................................................................................ 86 Plain J2SE Adapter Engine 640 4 To begin functioning. and then started. Its features are the same as those of the Adapter Engine shipped with SAP XI 2. You install [Seite 6] the individual adapters either separately or together. In principle. For this purpose.1 or higher. and the other way around. Introductory Notes The plain J2SE Adapter Engine (referred to below as the Adapter Engine) is a separate software component that you must install later. The plain J2SE Adapter Engine provides some of these adapters as a standalone version with restricted functions for operating systems that do not support the SAP J2EE server. you should only use the plain J2SE Adapter Engine if the platform prerequisites do not allow you to use the J2EE-based Adapter Engine. However. Therefore. XML and HTTP-based messages can be converted to the specific protocol and format required by such systems.0 Adapter Engine to the XI 3. You can use different adapters simultaneously or different configurations of the same adapter. in order to be able to use all the XI 3. it may be necessary for you to change the installation parameters to enhance the installation [Seite 6]. the adapters can be used to do the following: • • • • Exchange data with external systems using a file interface or an FTP server (file/FTP adapter) Communicate with messaging systems using the JMS API (JMS adapter) Access databases using JDBC (JDBC adapter) Communicate with clients and providers of Web Services using SOAP (SOAP adapter) An important distinction to be made here is whether an adapter is a sender adapter (converts data from external systems) or an receiver adapter (converts data from the Integration Engine). You can copy the adapter configurations of the XI 2. You configure this centrally by using the Integration Directory [Extern].02.0 Adapter Engine in Installation [Seite 6]). you connect external systems to SAP XI using the adapters that are installed centrally or locally in the Adapter Engine (J2EE) [Extern].0. each sender or receiver adapter must be appropriately installed and configured. you must change the address parameters in the sender adapter configurations as described below.3. but that do have JDK 1. Features Depending on the configuration.0 adapter configurations (see the section Upgrading the Installation of an XI 2.0 message format options. You then copy the XI 2. Plain J2SE Adapter Engine 640 5 .2004 Plain J2SE Adapter Engine Purpose You use the plain J2SE Adapter Engine to connect SAP Exchange Infrastructure [Extern] (XI) to external systems. and then configure [Seite 10] them using their own configuration interface.SAP Online Help 24. Additional functions include an enhanced monitoring and increased downtime security due to the J2EE-based cluster operation of the Adapter Engine. Using the various adapters in the Adapter Engine.0 Adapter Engine without changes. This is achieved using the HttpServer [Seite 19] service.jar). but always separately for inbound processing (sender adapter) and outbound processing (receiver adapter) by the Integration Engine [Extern]. You can configure adapters individually or together as required. • Additionally for the JDBC adapter A JDBC driver installation (version 2. The required Java libraries are product-specific and can be obtained from either the database vendor or other providers. Additionally for the JMS adapter The optional package Java Messaging Service (jms. for example.com/products/jms/index.html (download from servlet. you require the following: • • A Java development kit (JDK) 1.3 The optional package Java Servlet Version 2.sun. You must copy both libraries to the Java CLASSPATH after installation.0) for the database product to be connected to.jar). If the sender adapter is to communicate with the Integration Server using HTTPS.html (download from jms. otherwise it must be located in the Java CLASSPATH. 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. If the browser is to be connected to the Adapter Engine configuration screen using HTTPS protocol. additional libraries to implement the SSL protocol are required.com) Software Distribution Center. so that you can then configure [Seite 10] and use them to convert the respective message formats. on the SAP Web Application Server or directly on the Internet at http://java. on the SAP Web Application Server or directly on the Internet at http://java. Prerequisites To install adapters. you must configure the GuiBrowserEngine service [Seite 19] correspondingly.sun.3 or higher (servlet. If the receiver adapters from the Integration Server are to be communicated with using HTTPS protocol. under SAP Cryptographic Software. • Plain J2SE Adapter Engine 640 6 . but ensure that you follow the regulations outlined there.SAP Online Help 24.jar). You can copy the package directly to the adapter installation directory (tech_adapter). This can be located. 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.jar and iaik_ssl.com/products/servlet/index.2004 Installation Purpose You install the Adapter Engine [Seite 1]. including available adapters. You can download the Java libraries iaik_jce. you must configure the HTTP server correspondingly for the adapters. This can be located.sap.02.TargetURL (https:// instead of http://). for example. WebSphereMQ).jar). you can use the HTTPS protocol instead of HTTP for XI. A JMS driver installation for the queue system to be connected to (for example.jar from the SAP Service Marketplace (http://service. The required Java libraries are product-specific and can be obtained from either the product vendor or other providers. • Additionally for HTTPS protocol If the adapters are to communicate using HTTPS. properties. when logging on for the first time. execute the following: Windows: install_soapadapter. you must delete this initial user as soon as possible.cmd • To install the SOAP adapter.bat or run_adapter. • To start the Adapter Engine. To install an adapter. The packed adapter-installation file has been unpacked in a directory of your choice and you have retained the path structure. • To install the file/FTP adapter. execute the following: Windows: install_jmsadapter.2004 The Java runtime (java.cmd These scripts generate the default configuration in the adapter menu [Seite 12] for the respective adapter type. the Adapter Engine displays the following error message in the window in which it was started and then it closes itself.cmd • To install the JDBC adapter. Configuration and LogFiles. you can call the Adapter Engine using a browser. execute the following: Windows: run_adapter. When you have created new users [Seite 16].bat UNIX: install_jdbcadapter.bat UNIX: install_soapadapter.cmd. Plain J2SE Adapter Engine 640 7 .bat UNIX: run_adapter. ERROR starting Adapter engine base service ´GUI´ Installation is now complete.sh When you have executed run_adapter. The corresponding default address is http://<hostname>:81. if installation was performed correctly. execute the following: Windows: install_jdbcadapter. enter the user SAP and the password init.bat UNIX: install_jmsadapter. execute the following: Windows: install_fileadapter.cmd or run_adapter. However.SAP Online Help 24. If the standard port 8200 of the Adapter Engine is already in use. 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.bat UNIX: install_fileadapter. If you do not call any of the scripts then the default configurations for all adapters are found in the adapter menu.02. Process Flow New Installation Within the directory you used to unpack the installation file you will find the sub-directory tech_adapter with further sub-directories such as Administration. you can modify the configuration of the adapter menu in each case by using the functions available there. If this port is also already being used.cmd • To install the JMS adapter.exe) is located in the search path. you must enter a free port under port= in the file GuiBrowserEngine. switch to the directory tech_adapter. 0 Adapter Engine.0 Adapter Engine If you want to copy the XI 2. This means that following installation. To run multiple adapters of the same adapter type or different adapter types simultaneously. the Adapter Engine does not contain any other data apart from this directory structure. or want to repeat the installation. go to the configuration screen [Seite 10] of the Adapter Engine.0 Adapter Engine.backup that contains all relevant files for adapter configuration and user management.bat UNIX: save_configuration. They are interpreted in the same way as parameters with the same name and the namespace XI. including user management.. Upgrading the Installation of an XI 2. execute the following file in the directory tech_adapter: Windows: restore_configuration.0 Adapter Engine recognizes configurations of the XI 2. Parameters with the namespace XMB no longer exist in the XI 3.0 Adapter Engine and handles them as follows: • • Parameters with the same name are interpreted identically. c. if necessary. Switch to the directory tech_adapter beneath the installation directory and execute the following file: Windows: save_configuration. If you have also changed the configuration of services and if these configurations also need to be saved. Upgrading the Installation If you want to install a more recent adapter version.cmd Besides the directory tech_adapter. note that the XI 3. Instead of the installation script. • .cmd This file reproduces the adapter configurations. Plain J2SE Adapter Engine 640 8 . The services configurations are also reproduced if you have also saved them. The existing adapter configuration and user management are not to be saved a. there is only one SOAP adapter for which you must then configure two different instances. Delete the directory tech_adapter beneath the installation directory. you have two options: • The existing adapter configuration is not to be saved In this case..SAP Online Help 24.bat UNIX: restore_configuration. the system creates a new directory adapter_configuration. execute the following file as well: Windows: save_baseconfiguration.2004 You define the difference between sender and receiver for the SOAP adapter during configuration.02.cmd b. Otherwise the services are available in their original configuration. Install the adapter as described above. delete the existing installation beneath the installation directory completely and install the adapter as described above. or to start adapters automatically. as is the case following a new installation.bat UNIX: save_baseconfiguration.0 adapter configuration to an XI 3. SenderInterfaceName are interpreted as XI. You can then insert the script in the boot procedure of the operating system.SenderService and XI.type instead. use the script install_service. For further details. The parameters XMB. The call conventions are as follows: install_service.02. see the description of XI.bat [ServiceName] [JavaVM] uninstall_service. and [JavaVM] is the name of the DLL of the Java Virtual Machine with a complete path specification. In the variable EXTLIBS you can specify all Jar files that are actually required by the Adapter Engine. The sender file/FTP adapter uses the parameter file. The Windows results-display displays information and error messages of the service under the corresponding service names in the application log.log or stderr.type binary or text file type. respectively. Accordingly.bat is called.SenderAdapterForBusinessSystem and XMB. Plain J2SE Adapter Engine 640 9 . and they are ignored.bat or uninstall_service.ContentType and XMB.Interface. logon information. Once installation is complete.AdditionalPayloads in Configuring the Sender File/FTP Adapter [Seite 26]).sh is located in directory tech_adapter for Unix operating systems. for example to be able to load a JDBC or a JMS driver. Subsequent changes to the classpath have no affect on the created NTService.bat.bat [ServiceName] The [ServiceName] is a logical name that the service is created under.SAP Online Help • 24.SenderInterfaceNamespace and XMB. Adapter Engine console and error output is placed in the files stdout.log respectively in the sub directory LogFiles. To install or de-install the NTService. XMB. The parameters XMB. Corresponding examples can be found in the script.SenderBusinessSystem and XMB.exe.ReceiverBusinessSystem are interpreted as XI. is used to start the Adapter Engine as an NTService. • UNIX The script run_adapter. There are no corresponding parameters for the parameters XMB. refer to the USAGE section of the script.2004 The parameters XMB. located in the directory tech_adapter in the Adapter Engine installation directory. and so on).ContentKind is interpreted as a file.InterfaceNamespace and XI. respectively.ReceiverService. • • • Continuous Operation The following operating system-specific installation options are available to enable continuous operation of the Adapter Engine: • WindowsNT The program SAPAdapterService. The same applies to the specifications for additional files in a message (for more information.SenderAdapterForService and XI. 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.ReceiverAdapterForService.ContentKind. you must start the Adapter Engine as an NTService in the Windows services menu or configure it the same as each NTService (startup type.ReceiverAdapterForBusinessSystem are interpreted as XI. You must adjust the variable ADAPTER_HOME to the installation path in this script. respectively. whereby the Runtime Workbench [Extern] recognizes it as an SAP Exchange Infrastructure component. To be able to do so. see the section SLDaccessor in Services [Seite 19]. you can configure adapters individually or together as required. Note that this service is not mandatory and the Adapter Engine can function without being connected to the SLD. see the Runtime Workbench [Extern] documentation. both administration and monitoring settings must be maintained in the SAP System Landscape Directory. The same HTTP port as for configuration is used for this purpose.2004 You can access the SAP System Landscape Directory [Extern] (SLD) from the Adapter Engine. it can log on to the SLD. but no other authorizations. For more information about configuring this service. see user management [Seite 16]. For more information. You can configure the following adapters: • • • • • • • Sender File/FTP adapter [Seite 26] Receiver File/FTP adapter [Seite 39] Sender JDBC adapter [Seite 47] Receiver JDBC adapter [Seite 53] Sender JMS adapter [Seite 65] Receiver JMS adapter [Seite 73] SOAP adapter [Seite 82] (sender or receiver) The Adapter Engine also provides you with services [Seite 19] that can be used by all adapters and that are also partially configurable. You can also call the Adapter Engine administration screen from the Runtime Workbench. Optionally. To log on you require the technical user XIRWBUSER and the password XIPASS. This user is created automatically when the Adapter Engine is installed. or if the Runtime Workbench requires another user. For more information about creating users. Configuration Purpose You need to configure the available adapters so that you can use them to convert the respective message formats. this enables information connected with business systems to be exported. thus making it globally accessible. when an older configuration is implemented following installation). The user to be created only requires the authorization group Locked.SAP Online Help Accessing the SAP System Landscape Directory 24. you must create this user manually. 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. If this user is deleted (for example. The addresses of the associated adapters are then automatically adopted as default values by the Integration Directory [Extern] when end points are created for the business system.02. Using the intended Adapter Engine [Seite 1]. When the Adapter Engine starts. Monitoring with the Runtime Workbench The Runtime Workbench can access the Adapter Engine for monitoring purposes. This includes the following: Plain J2SE Adapter Engine 640 10 . Moreover. but always separately for inbound processing (sender adapter) and outbound processing (receiver adapter) by the Integration Engine [Extern]. To open a document. Process Flow The Main Menu of the Adapter Engine configuration screen comprises the following menu options that you can call with a single mouse-click: • • • • • • • • • • Adapters [Seite 12] Documentation (see below) User Management [Seite 16] Password Management [Seite 18] Services [Seite 19] Traces (see below) Test environment [Seite 23] About the Adapter Engine Log Off Current User (see below) Shutdown Adapter Engine (see below) Documentation Here you find the available language versions of the Adapter Engine documentation in PDF format. click the file name. five files are written.properties in the directory tech_adapter. depending on the configuration of the browser.SAP Online Help • • • • • • • An HTTP(S) server for browser-based configuration Central user management [Seite 16] 24. The file is displayed as a Text/Plain document.2004 A central storage location for passwords [Seite 18] that are required in adapter configurations Option of displaying additional log data when searching for errors A test environment [Seite 23] Access to the SAP System Landscape Directory [Extern] An HTTP(S) server for the receiver adapter Prerequisites You have successfully installed [Seite 6] the Adapter Engine and the required adapters . You must only change this file if requested to do so by the SAP Hotline. started the Adapter Engine and called it using you web browser and are now in the Overview section of the Adapter Engine configuration screen. The contents of these files are essentially only required by the SAP Hotline for the detailed analysis of problems and are not necessary for the day-to-day operation of the Adapter Engine.02. In the standard configuration. this section is not documented. Traces This menu option is only available for users with the Administrator role. each 2MB in size. The current file can be identified from the time stamp. ensure that you have a suitable viewer installed then click the mouse button once. Plain J2SE Adapter Engine 640 11 . It is displayed in a text viewer or directly in the browser. If required. Choose Traces to display the internal traces of the adapter engine. To display a trace file. The size or number of these files and the scope of the information is controlled by the file logging. the most recent 10 MB of trace information for the Adapter Engine is available here. For this reason. Changes to the graphical user interface take immediate effect. Choose this menu option to shutdown the Adapter Engine completely. Users with the role Administrator can set the default setting for the way that the graphical user interface of the Adapter Engine is displayed. To use the existing test environment [Seite 23] to test the conversion of the respective message formats. Once you have shutdown the Adapter Engine. To restart the Adapter Engine you must run the script run_adapter. and reactivate or remove deactivated adapters. depending on the browser cache settings. You can choose between SAP Web and SAP GUI. Log Off Current User Choose this menu option to log off the current user. you can no longer perform any actions in the menu options because the respective HTTP server no longer exists. Adapter Menu Use The Adapters menu of the Adapter Engine [Seite 1] enables you to add new adapters.2004 Here information about the installed version of the Adapter Engine and the Java runtime environment used is displayed. To confirm that the Adapter Engine has been shutdown. started the Adapter Engine and called it using your web browser. choose Test Environment in the Overview screen. However. restart with script XXX XXX is the script name including the complete path. the system displays the following text: Adapter Engine shutdown. deactivate existing adapters. Prerequisites You have installed [Seite 6] the Adapter Engine and the adapters you require.02. as described in the installation [Seite 6] procedure. The setting you make here becomes the standard view for all other users provided that a different user interface has not been selected in the user settings. certain parts of the old display may remain visible until they are loaded again.SAP Online Help About the Adapter Engine 24. Plain J2SE Adapter Engine 640 12 . Since you need to log on to the Adapter Engine host locally to do this. Any attempt to do so triggers the following HTTP error: The page cannot be displayed Result You have configured the selected adapters. or until the browser is restarted. you can manage existing adapters in the detailed view. the adapter status remains unchanged. you can only shutdown the Adapter Engine from a browser started on the same host. Furthermore. Note that this action merely logs the user off the configuration screen. Shutdown Adapter Engine This menu option is only available for users with the Administrator role. h.2004 Features The Adapters menu is displayed on the right-hand side when you call the configuration screen [Seite 10]. The configuration is now displayed under the new name in the selection list of the adapters menu and can be edited there to adjust the settings copied. If you do not check the checkbox. It displays the available (installed) adapters with their current status. You have the following options from the menu: • Rename Adapter Use this function to rename an existing adapter. To create an adapter configuration under the new name that has the same settings as the adapter configuration that you used as a template. g. • Add New Adapter Choose this function to generate a new adapter configuration from an existing adapter. i. it is possible and can lead to unexpected results with messages being duplicated or lost. j. l. k. red means errors have occurred. e. If you do not check the checkbox. You must not activate identical adapter configurations under different names. If you want the adapter to be started automatically when the Adapter Engine is started. Select an adapter from the list. Select an adapter from the list.. Choose Rename to complete the renaming process. A selection list appears containing all the adapters that are currently activated. Choose the function by clicking it. This is usually not technically possible and leads to an error message when you attempt to initialize the new adapter.. and amber means that the condition of the status is unknown. choose Create. proceed as follows: . A green traffic light means that the adapter is free of errors. In isolated cases however. Enter a new name for the adapter. Enter a name for the new adapter.. m. check the checkbox Automatic Startup. the configuration is displayed in the selection list of the adapter menu under its new name. proceed as follows: . To do so..02. A selection list appears containing all the adapters that are currently activated. Once the adapter has been renamed. d. as well as a traffic light that displays the condition of this status. f. If you want the adapter to be started automatically when the Adapter Engine is started. check the checkbox Automatic Startup. the adapter remains in the status INITIALIZED following a restart and must be started manually from the adapters menu. • Deactivate Adapters Plain J2SE Adapter Engine 640 13 . Choose the function by clicking it.SAP Online Help 24. the adapter remains in the status INITIALIZED following a restart and must be started manually from the adapters menu. To do so. However.properties from the directory . t. the adapters remains in the status INITIALIZED following a restart and must be started manually from the adapters menu. Select one or more adapters from the list. q. If you do not check the checkbox. Copying Adapter Configurations from Other Installations Since the name of a deactivated adapter is no longer managed by the Adapter Engine. Select one or more adapters from the list. A selection list appears containing all the adapters that are currently deactivated. Proceed as follows: . choose Deactivate. To do so. • Remove Deactivated Adapters Choose this function to delete existing deactivated adapters. Once you have deleted an adapter configuration it can no longer be reactivated. Proceed as follows: . n. u.. r. be reincluded (reactivated) in the adapters menu. you can use this function to copy adapter configurations from other installations of the Adapter Engine. but a properties file with the same name still exists in the configuration directory of the Adapter Engine.. copy the source file <AdapterName>. A selection list appears containing all the adapters that are currently activated. Changing the Start Mode for an Adapter If you have defined an adapter so that it starts automatically.SAP Online Help 24. • Reactivate Deactivated Adapter Choose this function to re-include existing. To do so. choose Reactivate. first deactivate the adapter(s) in question and the reactivate it/them again with the start mode required.. but deactivated adapters in the adapters menu. s. Choose the function by clicking it. To remove the selected adapter(s) from the adapters menu. Choose the function by clicking it.. check the checkbox Automatic Startup. the adapter configurations are not deleted and can.. Proceed as follows: .2004 Choose this function to remove (deactivate) existing adapters from the adapters menu. Plain J2SE Adapter Engine 640 14 ./tech_adapter/Configuration to the same directory in the target installation. It is then automatically displayed in the list of deactivated adapters and can be reactivated correspondingly. p. o. A selection list appears containing all the adapters that are currently deactivated.. To re-include the selected adapters in the adapters menu. if required.. you can change the start mode by choosing the function Deactivate Adapters.02. Choose the function by clicking it. If you want all the adapters selected to be started automatically when the Adapter Engine is started. create. choose Refresh to reload the adapter menu. To delete any changes made in change mode that have not yet been saved. a traffic light specifies the condition of the current status. by choosing one of the buttons on the left of the detailed view). choose Configure. STOPPED. Essentially. • Refresh 24. To save configuration data modified in change mode. type. double-click it. choose Edit/View. choose either Terminate and Create or Restart. choose Cancel. It then appears in a window in the Configuration area.02. start. red means errors have occurred. and Start. and status of the adapter. The following options are available to those users with the user role Administrator or Configurator: To switch between edit and view mode.2004 To update the displayed status and condition of all adapters. INITIALIZED. As in the adapter menu. changes made to the configuration are only adopted when you choose Store Configuration Data. To activate an adapter configuration that you have changed. choose Remove. the status displayed might also just be an intermediate status. • Configure. A green traffic light means that the adapter is free of errors. The system displays the name of the configuration underneath the window. In this case. which is the same as the button sequence Terminate. Due to the partly asynchronous processing of the corresponding actions described below. To do so. then the original configuration is maintained and is displayed again when you next call the configuration. or TERMINATED). choose Store Configuration Data. Plain J2SE Adapter Engine 640 15 . TERMINATED. stop. To delete the selected adapter(s).SAP Online Help v. The detailed view displays the name. Activities To display details about the displayed adapter. This is particularly true for Restart. which involves the statuses STOPPED. you can update the display by choosing Reload. restart. Select one or more adapters from the list. The Log area displays an adapter-specific log if one exists. terminate the adapter Configure To call the configuration that you require to configure an adapter. From the detailed view you can do the following: • • Return to the Main Menu Update the contents currently displayed. by choosing Reload The current status of the adapter is displayed in each case (INITIALIZED. Create. you must always reinitialize the adapter first. and amber means that the condition of the status is unknown. STARTED. If you exit the configuration screen by using any other means (for example. and STARTED. w. version. This action is the same as the button sequence Terminate. This is necessary if you have changed the configuration data or have deleted the current instance of the adapter using Terminate. nor can his or her role be changed. you must have already created and configured the adapter. Adapters that were stopped by choosing Stop can also be restarted again by choosing Start. • Display and delete the adapter-specific log User Management Use Using the user management function of the Adapter Engine [Seite 1] you can define various users whose authorizations are based on different roles. choose Start.2004 It is not sufficient to simply choose Stop and Start since this combination does not reinitialize the adapter and therefore the modified configuration data is not recognized. you have chosen the menu option User Management and the system now displays the menu with the same name. Stop To stop a running adapter. choose Stop. Features The role-based user concept of the Adapter Engine has the following roles: • Adapter Engine Administrator Users with this role can display and change all configurations. if you no longer require it. or it can be stopped completely by choosing Terminate. Terminate To end an adapter instance. Restart To restart the adapter. To do so. started the Adapter Engine and called it using your web browser. Only this role has the authorization to perform the following: Create and delete users and to change their roles and passwords Plain J2SE Adapter Engine 640 16 . The adapter has now been stopped can either be restarted by choosing Start. Prerequisites You have installed [Seite 6] the Adapter Engine and the adapter you require.02. Create.SAP Online Help 24. regardless of its status. This means that the last user with this authorization cannot be deleted. choose Terminate. for example. User management ensures that at least one user has this role. has this role. This is necessary if you have changed its configuration. Start To start an adapter. choose Restart. On the configuration screen [Seite 10]. created initially during the installation. for example. The user SAP. Create To regenerate and initialize the adapter. choose Create. and Start. or if it is not functioning as you want it to. in other words. Change Password Once you have changed the password. without being deleted. This function can only be executed by Adapter Engine administrators. The last Adapter Engine administrator cannot be deleted. • HTTP Server User Users can be assigned the role HTTP Service User in addition to any other role they have. or to change the password or the role of an existing user.2004 Shut down [Seite 10]the operating system process of the Adapter Engine • Adapter Configurator This role has all authorizations except those of the administrator mentioned above. Any functions not specifically mentioned here can be used by all roles. This function can only be executed by Adapter Engine administrators. or they can be assigned this role only. You cannot assign any other role to the last Adapter Engine administrator. • Adapter User This role only has the authorization to use existing adapter configurations.02. all the functions available in the detailed view screen except that for changing the configuration. • Delete User Choose this function to delete an existing user. or both. This also includes the authorization for storing passwords [Seite 18]. Activities User management provides various functions that you can execute by using the following menu options: • Display Users Displays all users and the roles they have been assigned. you do not need to create them again when you unlock them. This status means that users are temporarily locked. This function can only be executed by Adapter Engine administrators. All users can be assigned the status Locked. Change Graphical User Interface Style Plain J2SE Adapter Engine 640 17 . • Change Current User Settings Here the user who is currently logged on can change both his password and the way that the graphical user interface (GUI) is displayed. a user with this role can configure adapters displayed in the adapters menu [Seite 12]. • Create User/Change User Settings Choose this function to create a new user and to assign him or her a role. These users are required for authentication for the receiver adapter if the authentication mode is activated on the HTTP server. As a result. In particular.SAP Online Help Call the configuration of the services [Seite 19] Display the internal trace files [Seite 10] of the Adapter Engine 24. you must log on to the Adapter Engine using the new password. 02. On the configuration screen [Seite 10]. You can override this default settings by selecting either SAP Web or SAP GUI. Plain J2SE Adapter Engine 640 18 . or until the browser is restarted. • Delete Tokens Choose this option to delete a token.SAP Online Help You can choose from the following: Default SAP Web SAP GUI 24. To save adapter configuration passwords so that they are concealed. In the Tokens menu you have the following options: • • Display Tokens Choose this option to display all tokens currently registered. started the Adapter Engine and called it using your web browser. However. those for logging on to the database. Password Management Use The password management function of the Adapter Engine [Seite 1] enables you to protect saved passwords that are used in the adapter configurations (for example. or Integration Server). Changes to the graphical user interface take immediate effect. FTP server. depending on the browser cache settings. you must activate password management by entering the following: PWD. Prerequisites You have installed [Seite 6] the Adapter Engine and the adapter you require.2004 The default setting is that which was selected as the default setting for the Adapter Engine. queue system.tokenHandler=PWtokens You must replace the password with the token and place it between the separators <!% and %!>. Create/Change Tokens Choose this option to create a password for a registered token or to change a password. Features This menu option is available for users with the Adapter Engine Administrator or Adapter Configurator role. certain parts of the old display may remain visible until they are loaded again. you have chosen the menu option Password Management and the system now displays the menu Password Management: Tokens. If a token is found that does not exist. It is not sufficient to simply restart the services (unlike with configuration changes to adapters). initialization is terminated and a corresponding error message displayed. This menu option is only available for users with the Adapter Engine Administrator role.02. or you did not activate password management.tokenHandler=PWtokens The password is then replaced by the token: XI. Plain J2SE Adapter Engine 640 19 .SAP Online Help 24. You configure these parameters using the same screen as for the adapters. Any changes made to the configuration of the services are only activated when the Adapter Engine is restarted. then you either placed the separators incorrectly and therefore the token was not recognized. If the file/FTP adapter is reinitialized.2004 If the separators <!% and %!> conflict with other parameter values in the adapter configurations they can be configured using the services [Seite 19]. If the properties are not shown. a token is created with the name myPassword. although you specified a token.Password=<!%myPassword%!> The separators <!% and %!> are required to identify the token. The password hugo is then saved under the name myPassword in the token menu (without the separators). The corresponding password is saved in the Tokens menu on the password management screen. Services Use This menu option contains the services of the Adapter Engine [Seite 1] that contain configurable parameters. the properties whose values contain a token are shown. In the file/FTP adapter configuration the following two parameters are required: • • XI.Password=hugo To protect the password. Password management is activated by entering the following in the configuration of the file/FTP adapter: • • PWD. During the initialization of the adapter.User=XIUSER XI. a message appears in the file/FTP adapter log stating that the token was identified and replaced at runtime. Example In the sender file/FTP adapter [Seite 26] you require the user XIUSER with the password hugo to log on to the Integration Server. These IAIK libraries must be located in the Java CLASSPATH. The following additional specifications are required for SSL: SSLcertificate=<p12-certificate name> SSLcertificatePassword=<p12-certificate password> SSLcertificate specifies the complete file name of a password-protected certificate and SSLcertificatePassword specifies the corresponding password (the password can be protected by using the token concept. HTTP.transmission=plain|SSL Defines whether the browser and the Adapter Engine are to communicate using HTTP (plain) or HTTPS (SSL). In the setting none. The default is plain. no authentication takes place. • HttpServer The HTTP server is used by the receiver adapters. started the Adapter Engine and called it using your web browser.com). In the basic setting.SAP Online Help 24. the HTTP client of the Integration Server must log on to the Adapter Engine with a valid user that has been assigned the role HTTP Server User.02. The default value is 8200 and must not be changed unless it has already been reserved. You have the option of making the following settings during the configuration of the HTTP server: http. you have chosen the menu option Services and the system now displays the menu with the same name. The following settings must not be changed under any circumstances: zones=root rootDirectory=Administration HTTP.sap.2004 Prerequisites You have installed [Seite 6] the Adapter Engine and the adapter you require. Features You have the following choice of services: • GUIBrowserEngine The GUI browser engine represents a separate HTTP server with a configurable port: port=<portNo> This is the HTTP port that the browser can log on to. described above). To make the installation HTTPS-enabled you must install additional Java libraries that are available from the SAP Service Marketplace (http://service. On the configuration screen [Seite 10]. The following additional specifications are required for SSL: HTTP. The default is plain. The default is none.transmission=plain|SSL Defines whether the Integration Server and the HTTP server of the Adapter Engine are to communicate using HTTP (plain) or HTTPS (SSL).SSLcertificate=<p12-certificate name> Plain J2SE Adapter Engine 640 20 .authentication=none|basic Define whether user-authentication is performed. maxFileSize=<sizeKBytes> This parameter (default: 0) controls the maximum size (in KB) of the log file for each adapter instance.2004 HTTP. the system displays the message <VIEW LENGTH RESTRICTION: SKIP nnn BYTES>… in the browser display.02.com). • InfoLogger The InfoLogger provides the service functions for writing and displaying the specific logs for an adapter instance. you can change the beginning and end characters of the tokens centrally here. If the parameter is set to 0. The parameter refers to the representation of the log file. the file is deleted each time the Adapter Engine is restarted and written during the Adapter Engine runtime without limit. Since this usually contains keys. described above). This corresponds to the standard procedure.log) is not deleted when the upper limit specified for maxFileSize is reached. the amount of data actually transferred is generally significantly larger than defined here (by a factor of between 3 and 5). If the amount of log information saved is greater than 100.SAP Online Help 24. the parameter archiveFiles has no function.log in the directory LogFiles. the respective log file (<adaptername>. • SLDaccessor Plain J2SE Adapter Engine 640 21 . depending on the setting for the parameter archiveFiles. archiveFiles=<anyValue> If this parameter contains a value. If required. Existing replacements of tokens in the adapter configurations must then be adjusted correspondingly. To make the installation HTTPS-enabled you must install additional Java libraries that are available from the SAP Service Marketplace (http://service. If maxFileSize is set to 0. but is archived with a time stamp under the name <adaptername>_<yyyMMdd-HHmmss>. which are not replaced with text until the log is called. You use the following parameters to configure the display and save logic of the log files for all adapter instances: maxViewSize=<sizeKBytes> This parameter (default: 100) controls the amount of data transferred to the browser when the display of the adapter-specific log is called on the configuration and monitoring screen of the adapter.SSLcertificatePassword=<p12-certificate password> SSLcertificate specifies the complete file name of a password-protected certificate and SSLcertificatePassword specifies the corresponding password (the password can be protected by using the token concept.endSeparator=<endSign> beginSign and endSign can be any character string. PWD.sap. These IAIK libraries must be located in the Java CLASSPATH.beginSeparator=<beginSign> PWD. • PWtokens This is the service for replacing the password tokens in the adapter configurations. If the specified size is reached. the file is deleted or archived. where nnn is the number of skipped bytes in the log file. SenderService is read from the SLD and used instead of the value specified under XI.TargetURL (which describes the address of the Integration Server) dynamically using the parameter XI.password= Valid logon data for the System Landscape Directory installation (the password can be protected by using tokens. Plain J2SE Adapter Engine 640 22 . These error messages do not affect the other functions and can be ignored if access to the System Landscape Directory is not required. the corresponding association must be maintained in the System Landscape Directory and the latter must be accessible. to establish a connection to the monitoring and configuration functions of the Adapter Engine.TargetURL=<fromSLD> If the System Landscape Directory logon data is not maintained correctly.SenderService. Therefore. SLD.user= SLD.host=<SLDhostname> Name of the server on which the System Landscape Directory is running. SLD. This information is then accessed by the Runtime Workbench [Extern] for example. its current configuration is transferred to the System Landscape Directory. as described above). specify the following: XI. You configure the HTTP connection required to access the System Landscape Directory by using the following parameters: SLD. Read access to the System Landscape Directory can be activated in the sender adapters by adding the following entry to the configuration: XI.2004 This service enables you to log on to the SAP System Landscape Directory and supports the following functions: Write access: When the Adapter Engine is started. Read access: Configuration data can be accessed centrally for each adapter instance at runtime. when the Adapter Engine is started).02. or it is accessed by the Integration Directory [Extern] to determine default values when creating end points for business systems if these are associated with an adapter. To do so.SAP Online Help 24.TargetURL.SLDConfiguration=SLDaccessor In this case the URL of the corresponding Integration Server for the system specified with XI. corresponding error messages can occur in the Adapter Engine console output when the service is initialized (for example.port= Port number under which the System Landscape Directory can be reached. This service can be activated by the sender adapters to determine the parameter XI. The user must have the authorizations of group SAP_XI_APPL_SERV_USER on the Integration Server. The payload and the body of the HTTP request are identical.2004 Test Environment Use The main function of the test environment of the Adapter Engine [Seite 1] is to test the settings of the individual adapters (JMS. It is possible to create test variants and to save these in the Adapter Engine. specify the sender payload you want to send. enter the data that you want to put in the message header. It comprises two input areas: In the first input window. Prerequisites You have installed [Seite 6] the Adapter Engine and the adapter you require. enter the data that you want to put in the HTTP header. With this test. you can easily either send a message to the Integration Engine. The test interface receives a single part MIME message in text format and sends it to a specified address on the Internet. The test interface receives messages of this type with a text payload. Features There are three ways of sending client-side messages using HTTP in the test environment. to test the configuration of an adapter). enter the parameters for the HTTP header in the same way that you entered the adapter parameters. SOAP).TargetURL=http://p35841:3333/JMS In the second input window. for example: WS. JDBC. with the JMS adapter. It comprises two input areas: In the first input field.SAP Online Help 24. you can set the values for WS. In the second input field.SOAPAction. In particular. It comprises two input areas. you can easily generate JMS text messages using the mode JMSTunneling. for example.TargetURL. The test interface receives messages of this type with a text payload. you can set the value for XI. In particular. • The third message type is simple Web Service or SOAP messages. • The second message type is Integration Engine messages. In the first input field.SOAPAction=testservice In the second input field. or simulate a sending Integration Engine (for example. specify the payload you want to send. for example. started the Adapter Engine and called it using your web browser. you have chosen the menu option Test Environment and the system now displays the menu with the same name. • The first message type is general MIME messages. With this test.02.targetURL and WS. for example: XI. Plain J2SE Adapter Engine 640 23 . File/FTP. You set the parameters of the header data in the same way you set the parameters of the JMS file/FTP adapter or JDBC adapter. On the configuration screen [Seite 10]. specify the text payload you want to send.targetURL=http://p35841:4040/WS WS. for example. the lower output field contains the received data or a specific error text. If you attempt to save sap_default the system creates a new variant with the name default. The system then sends you a review of the send procedure (Send Review).com/xi/xidemo XI.SenderInterfaceNamespace=http://sap. choose Load variant.0" SOAP:mustUnderstand="1"> <sap:From> <sap:Name>ExtAdapterSender</sap:Name> Plain J2SE Adapter Engine 640 24 .org/soap/envelope/"> <SOAP:Header> <sap:MessageHeader xmlns:sap="http://sap. in the case of an error.com/exchange/MessageFormat" version="1. choose Save variant as.SenderService=ExtAdapterSender XI. To load or delete a test variant.xmlsoap.02.SenderInterface=ExtAdapterSenderIF XI. To save a test variant as a default variant. Activities If you have set the data correctly. a message for the Integration Engine is generated from the following header data and payload and sent to the following address: http://pwdf0436:8082/sap/xi/engine?type=entry Header Data XI. boundary=4859e1d0-1ef1-11d6-a1c4-6fda44caeb12 Content length: 1495 --4859e1d0-1ef1-11d6-a1c4-6fda44caeb12 Content type: text/xml Content length: 1189 <SOAP:Envelope xmlns:SOAP="http://schemas.SAP Online Help 24.ReceiverParty=Receiver XI. Example As an example of the second message type.SenderParty=Sender XI. The upper output field contains the generated and sent data. choose Send Message to generate and send the message for all three text variants.2004 Using this test it is very easy to send a Web Service message to a SOAP adapter (for example to test the configuration of the adapter).TargetURL=http://pwdf0436:8082/sap/xi/engine?type=entry XI.ReceiverService=ExtAdapterReceiver Payload <test>Payload</test> Message Content type: Multipart/Related. The variant sap_default is shipped by SAP and cannot be deleted or saved under the same name. 0"> <sap:Payload xlink:type="simple" xlink:href="cid:
[email protected]">1</sap:TraceLevel> <sap:Logging file="mylog.2004 Result The system displays the sent and the received message in the screen Send Review.com/exchange/MessageFormat" xmlns:xlink="http://www.SAP Online Help <sap:Interface namespace="http://sap.com/xi/xidemo">ExtAd apterReceiverIF</sap:Interface> </sap:To> <sap:MessageId>48585b30-1ef1-11d6-87266fda44caeb12</sap:MessageId> <sap:QualityOfService>BestEffort</sap:QualityOfService> <sap:TimeSent>2002-02-11T13:14:30Z</sap:TimeSent> <sap:Direction>Request</sap:Direction> <sap:TraceLevel file="mytrace.com/xi/xidemo">ExtAd apterSenderIF</sap:Interface> </sap:From> <sap:To> <sap:Name>ExtAdapterReceiver</sap:Name> <sap:Interface namespace="http://sap.log">1</sap:Logging> <sap:Document>MainDocument</sap:Document> </sap:MessageHeader> </SOAP:Header> <SOAP:Body> <sap:Manifest xmlns:sap="http://sap.w3.02.com"> <sap:Document>MainDocument</sap:Document> </sap:Payload> </sap:Manifest> </SOAP:Body> </SOAP:Envelope> --4859e1d0-1ef1-11d6-a1c4-6fda44caeb12 Content type: text/plain Content length: 22 Content ID:
[email protected]/1999/xlink" version="1.com <test>Payload</test> --4859e1d0-1ef1-11d6-a1c4-6fda44caeb12-- 24. Plain J2SE Adapter Engine 640 25 . 02. Called the adapter configuration by choosing Configure. If no specification is entered.aii. Procedure The configuration of the sender file/FTP adapter comprises five functional sub areas: . 1...sap.. mode=FILE2XMBWITHSTRUCTURECONVERSION Plain J2SE Adapter Engine 640 26 . mode=FILE2XMBWITHROWCONVERSION The system expects a text file that contains identically structured rows that can be converted into an XML document. or both) to an XML document (these specifications are optional). Installed [Seite 6] the corresponding adapter. you must make the necessary specifications in step 5. 3. To configure the adapter you must specify the following: • • • A directory and file name with a placeholder (*) to select the files A processing rule for successfully sent data Simple routines to convert a text file (with columns of fixed length or columns that are separated by particular characters. 1. 3.0 adapter configuration.SAP Online Help 24.messaging. File/FTP adapter mode Specify the mode of the sender file/FTP adapter. the configuration is interpreted as an XI 2.2004 Configuring the File/FTP Sender Adapter Use You need to configure the sender file/FTP adapter to send file contents to the Integration Engine [Extern].adapter. Selected [Seite 10] the adapter on the configuration screen.ModuleFile2XMB This specification is mandatory. The following values are permitted: mode=FILE2XMB The content of the file is sent directly to the Integration Engine. To make this type of conversion. 2. The Java class name for the sender file/FTP adapter Specify the class name as follows: classname=com. A dispatcher class (optional) with the corresponding settings and the user exits and their settings that are to be called by the dispatcher Sender and receiver data required by the Integration Engine for routing and mapping • • Prerequisites You have: . Other values are not permitted and trigger an error.. The version specification for the configuration version=30 This specification is mandatory. 2. The Integration Engine address can also be accessed dynamically from the SAP System Landscape Directory.User.Client.User=<user-name> XI. Therefore. The default value is FILE2XMB. including all Integration Engine-specific parameters as described under point 3. 8080). mode=FILE2XMBSTREAM A special file format is expected here that represents a completely serialized Integration Engine message. This file format can be generated from the receiver file/FTP adapter [Seite 39] in the mode XMBSTREAM2FILE. If the Integration Server is accessed by means of an HTTP proxy server rather than directly. XI. Therefore.TargetURL=http://IntegrationEngineHost:port/pipelinearguments This specification is mandatory. the following parameters must be set: XI. The following entry is added to the configuration for this purpose: XI. specify the following: XI.SenderService is read from the SLD and used instead of the value specified under XI. XI. To make this type of conversion.Language) are evaluated from the configuration. and XI.proxyPort=<proxyPortnumber> <proxyHostname> is the host name of the proxy and <proxyPortnumber> is the port where the proxy receives HTTP requests (for example.TargetURL. The dispatcher class and the user exits to be called by the dispatcher (optional) The sender file/FTP adapter provides you with a dispatcher that you can use to convert messages before they are sent.proxyHost=<proxyHostname> XI. 5.TargetURL=<fromSLD> To be able to access the System Landscape Directory. If an authentication was specified for the specified URL (HTTP service) in the Integration Engine. Specifications for the Integration Engine Enter the complete address (URL) of the Integration Engine that you want to send the message to: XI. the following specifications are mandatory: XI. This format can therefore be used to temporarily save complete Integration Engine messages.SLDConfiguration=SLDaccessor In this case the URL of the corresponding Integration Server for the system specified with XI.2004 The system expects a text file with more complex file structures that can be converted into an XML document. you must make the necessary specifications in step 6. if necessary XI. the SLDaccessor [Seite 19] service must be configured correspondingly and the respective entries must be maintained in the System Landscape Directory.SAP Online Help 24.Password. The settings required for the dispatcher are explained in the example [Seite 86]. XI.TargetURL.Password=<password> Plain J2SE Adapter Engine 640 27 . 4. A file of this type contains various row formats in logical structures. in this mode only the parameters for logging on to the Integration Engine (that is.02. QualityOfService=EOIO (Exactly Once in Order: means asynchronous processing using queues.Interface. If you want to use a different client or language to the default setting in the Integration Engine when logging on.02.SAP Online Help 24. The user must have the authorizations of group SAP_XI_APPL_SERV_USER on the Integration Server.Client=<client-no> XI.ReceiverService=<receiver service name> You must set at least XI. The receiver is generally determined by routing in the Integration Engine.SenderInterface=<name> XI.2004 The specifications must match those that you made in transaction SICF in the Integration Engine.ReceiverParty=<receiver party name> XI. XI.SenderInterfaceNamespace=<namespace URI> XI. You can also find an explanation about each argument there.SenderService and XI. The following values are permitted: XI. XI.QualityOfService=<QualityOfService> Specifies how the Integration Engine should process a message. If you do not specify a user and password combination. or the combination is invalid.SenderService=<sender service name> XI.QualityOfService=EO (Exactly Once: means asynchronous processing with guaranteed execution exactly once) XI. you can also set the following parameters: XI.QueueId=<QueueName> This queue name is used in the Integration Engine to process messages in the same sequence that they arrived in.type=BIN|TXT Plain J2SE Adapter Engine 640 28 . Specifications for file selection and processing mode The following specifications are mandatory: file. This means guaranteed execution exactly once following the sequence of successive messages) You must also define a queue name for EOIO: XI.SenderParty=<sender party name> XI.Language=<language-id> You can set the following arguments (except in mode FILE2XMBSTREAM) and use them to identify the adapter configuration during routing [Extern] and mapping [Extern] in the Integration Engine pipeline [Extern].QualityOfService=BE (Best Effort: means synchronous processing) XI. the system will terminate each attempt to access the Integration Engine with the message Transport Exception: http-Error 401 – Unauthorized. This specification is not mandatory. 6. pollIntervalMsecs= If file.txt my*. file. file.02. file. With a binary file.pollInterval= Specify the number of seconds that the adapter must wait if no files for processing can be found. The default setting is the code page of the host on which the Adapter Engine is running. The value from file. the data are transferred unchanged.sourceDir=<directory_name> Specify the directory where the files to be processed are located. use a forward slash (/) to separate directory names in accordance with Java specification.txt *. then the adapter is terminated if an error occurs. In this case the adapter status remains as STARTED.pollIntervalMsecs). If the call is not to be repeated then you must set both parameters to 0 (or just the parameter file. If this value is 0 (the file is not processed again). You can either specify the entire path name or a name relative to the working directory of the Adapter Engine.pollInterval if you have not specified a value for parameter file. so as to be able to select a list of files for processing. and with a text file you can define a code page by using the parameter file. then files processed with errors are not processed again.pollInterval is set to 0.txt *File. choose Stop/Start or Restart to restart the adapter. even when a value greater than 0 was specified for Plain J2SE Adapter Engine 640 29 .retryInterval is also 0.SAP Online Help 24.retryInterval= Specify the number of seconds that the adapter is to wait before a file processed with errors is processed again.* *File*. then very short. The following are valid examples for filename: myFile.* Names that comprise more than two parts are also permitted. To initiate a new call. file.encoding (see below). You can also specify the following parameters so as to specify an additional waiting time in milliseconds: file. If file. The name can contain a placeholder (*) at any point. The default value for this parameter is 0. In all platforms (including Windows). almost real time processing times can be achieved.2004 Use this parameter to specify whether the file is to be read as a text file or a binary file.* my*le.pollInterval is adopted as the default value.sourceFileName=<filename> Specify the name of the file that you want to process. this can lead to a lot of entries in the log. archive and archiveWithTimestamp mean that successfully processed files are moved to an archive directory. files received from the FTP servers). the log output (but not the loop itself) can be deactivated by using file. As a result. setAttribute means that successfully processed files are given the attribute read only. For loops that last 5 seconds or less.checkModificationInterval=<msecs> Use this parameter to define a length of time (default value: 0) for the file/FTP adapter to wait after the file has been read to see if the file length changes. the file name is copied unchanged. This is useful if the files to be imported by the adapter are generated dynamically without being locked on the operating system level (for example. To process the file again.processingMode=<processingMode> Once the files’ contents have been sent to the Integration Engine. files can be sorted according to the time they entered the archive directory. it is overwritten. This means that files are sent again as a new message if the file/FTP adapter is restarted or if the time period specified in file. the system repeats the read procedure. delete means that successfully processed files should be deleted.SAP Online Help 24. This means that only files you can write to are processed. file.logPollInterval=YES. The format of the time stamp is yyyyMMddhhMMss-SSS_. the output can be activated with file. and not for production operation. setAttribute or test. As a result. The following specifications are not mandatory: Plain J2SE Adapter Engine 640 30 .logPollInterval=NO|YES All entries to loops that last longer than 5 seconds are shown in the adapter log by default. file. file. test means that successfully sent files will not be processed. In the archiveWithTimestamp mode. the file/FTP adapter cannot recognize whether the generation of the file is complete in such applications with operating system functions. the archive directory must be specified using the following parameters: file. irrespective of the file name. where yyyy specifies a year and SSS the number of milliseconds.logPollInterval=NO. If this is the case. In this case the adapter status remains as STARTED.archiveDir=<archiveDir> This parameter is mandatory for these processing types. In such instances. This mode is exclusively of use when testing the configuration of the file/FTP adapter or the Integration Engine. If a file with the same name already exists in the archive directory. archiveWithTimestamp.pollInterval is exceeded. archive. a time stamp including the date and time is added to the file name. This also stops files with the same name being overwritten. In archive mode. specify how you want them to be processed. choose Stop/Start or Restart to restart the adapter.02. There are five possible processing types for processingMode: delete.2004 file. In the case of both processing types. Without this workaround.pollInterval. encoding in the general system information of the About Adapter Engine [Seite 10] menu option. In this case. file.processingOrder. file. The specifications file. files are processed according to their time stamp in the file system. Alternatively. byDate for parameter file.host=<ftp-server> The host name or IP address of the FTP server. You can also enter the currently processed file name with the placeholder %f (file name) or %F (absolute filename including path) in the operating system command. You must specify the value UTF 8 for XML text documents that are coded in UTF 8.processingOrder=<processingOrder>=byDate|byName Specify here the sequence in which files are to be processed if you used placeholders when you specified file. file. This value means that files are processed in alphabetical order. and the system found multiple files to be processed.sourceDir and file. The default value is an empty character string (no command). You can find the system code page under file. it is assumed that you are accessing an FTP server.execute=<operating system command> An operating system command specified here is executed after a file has been successfully processed. ftp. It is not obligatory that you specify the port number here. you need to make the following additional specifications: ftp. file. meaning that only files that are not locked are transferred. The default setting is NO. If this specification is available.processingMode. starting with the oldest file. Text files that are neither in the system code page nor are coded in UTF 8 can only be read if the corresponding code page is available in the Java runtime environment.encoding=<codepage> This parameter is used to import text files. If you select files from an FTP server and not from the file system. The default is the standard port for the FTP server (21).sourceFileName refer to the FTP server.2004 Specify here whether files that are locked by other applications are to be transferred or not. you can specify byDate. The default setting is to use the system code page that is specific to the configuration of the installed operating system.SAP Online Help file.port=<port-no. The default value is an empty character string (no command).processingLocked=YES|NO 24.> The port number of the FTP server.user=<user name> Plain J2SE Adapter Engine 640 31 . In particular. The following are then not possible specifications: setAttribute for parameter file. this ensures that the adapter does not transfer incomplete files that are generated or transferred by other applications.02. The default value is byName. Only change the setting to YES if you can guarantee that such data loses will not occur.executeAfterAll=<operating system command> An operating system command specified here is executed once all files have been successfully processed that were found in a run.sourceFileName. ftp. a text file with identical structures of a type is expected that is arranged line-by-line by default.1. fromFile means that the field name information is located in the header line of the file to be converted. It is not obligatory that you specify a user name. or both. or have columns of fixed length. When the sender file/FTP adapter converts non-XML to XML format.02. The default value is the payload type of the received document from the Integration Server. but it will be delivered by the present configuration. fromConfiguration means that no header information exits in the file to be converted. the columns in the XML document are identified using a simple counter tag (<columnX> . or whether a permanent connection should be used (value permanently).connection=perFileTransfer|permanently Use this specification to define whether a new connection needs to be established each time a file is transferred to the FTP server (value perFileTransfer). Specifications for the conversion to an XML document in mode FILE2XMBWITHROWCONVERSION) If you set the sender file/FTP adapter mode to FILE2XMBWITHROWCONVERSION.2…). X=0. The default user is anonymous with the password anonymous.processFieldNames= Specify the field names. You cannot specify any additional metadata (such as column types or conversion rules for columns). fromFileWithBlankLine corresponds to fromFile. only an XML document for the mapping in the Integration Engine should be created. 7.SAP Online Help ftp. In this case. Make the following specifications: xml.fieldNames= correspondingly for this (see below). or they can be read as header lines from the file itself. In mode FILE2XMB. Information of this type must be made available during mapping in the Integration Engine pipeline. This conversion occurs in addition to all other processing described in previous sections. existing arguments are ignored. The rows of the text file must either contain separators. The following mandatory arguments refer to the mode FILE2XMBWITHROWCONVERSION. due to a timeout). none of the following arguments should be set. it is possible to specify other separators to separate structures. the connection is re-established automatically if it closed on the server side (for example. In this case.2004 A valid user name for the FTP server. notAvailable means that no field name information is assumed to be in the configuration or in the file to be converted.password=<password> 24. The default value is permanently. The structure can be converted to an XML document and sent to the Integration Engine in place of the original file. ftp. Plain J2SE Adapter Engine 640 32 . You must set the value for xml. After the header line there also follows a blank line or separator that is skipped. However. The following are possible specifications: notAvailable means that no field name information is available. You can either specify column names explicitly in this segment.mode=<Binary|Text> This specification enables you to set the transfer mode of the FTP connection to either text or data transfer. ftp. enclosureSign. If you also specify a separator for the columns. here you can specify the text delimiter for the end of the text. If you do not enter a value. Plain J2SE Adapter Engine 640 33 . the extra length of the separator is taken into account. The default setting is an empty value (no text delimiter).fieldFixedLengths= 24.fieldFixedLengths or xml.fieldSeparator=. If you do not make any specifications for xml. the default value is NO. xml. xml. You must specify at least either xml.2004 If you make a specification here. xml.enclosureSignEscape= Here you can specify a string that replaces the text delimiter if it occurs within a text that it delimits. The default setting is no value.fieldSeparator= If you make a specification here.enclosureSignEnd. xml. if you change the setting to NO. the system expects that the file contains the specified character string (one or more characters) as a separator between the individual columns. Separators within such texts are ignored. If you made a specification for fieldFixedLengths=. all characters are transferred unchanged. the system expects a character string that contains the lengths of the file columns as arguments separated by commas. The default setting is YES. but no further consistency checks are performed. When the text is transferred the string is replaced by the value specified in xml.lastFieldsOptional=YES|NO This parameter specifies whether the last fields can be omitted (YES) or not (NO) in a CSV structure. this is the only specification to identify the individual columns in a row. xml. you must not add its length to the length of the columns. This parameter is optional. If you made no specification for fieldFixedLengths=. the specification xml.enclosureSignEnd= If there are different text delimiters for the beginning and the end of a text. If you do not make a specification. the value from xml.02.enclosureConversione=YES|NO This value specifies whether the text delimiter is to be removed or whether the escape character is to be replaced when the files are transferred.enclosureSignEndEscape= Here you can specify a string that replaces the text delimiter for the end of the text if it occurs within a text that it delimits.fieldSeparator.SAP Online Help This specification is mandatory. xml. Text enclosed by such delimiters is transferred to the target structure unmodified although the default setting is to remove all text delimiters.enclosureSign is used instead. When the text is transferred the string is replaced by the value specified in xml. The default setting is no value. xml.fieldFixedLengths= is mandatory. xml.enclosureSign= You can specify a string here that acts as a text delimiter. xml.beginSeparator and xml. the structures are arranged line-by-line.02. this specification is mandatory. The default value is a line break (no explicit separator after the last column).2004 If you specify xml. xml.fieldSeparator. specify field names with the following specifications: xml. xml. text enclosed in quotation marks is transferred unchanged and the quotation marks are removed.addEndSeparatorAsField=<fieldname> The strings. Instead.endSeparator).endSeparator= If you want to define an additional character string as a separator after the last column in a row.endSeparator can also be inserted as fields in the structure of the generated XML document.beginSeparator= If you want to define an additional character string as a separator before the first column in a row. Special characters cannot be converted since characters of this type are not permitted in XML documents. xml. The system expects a list of the column names. together with the specified field name. make a specification here. These characters can be each be inserted individually in the string in the form ´0xHH´ (including the quotation mark). The format of these column names varies depending on the following specifications: Plain J2SE Adapter Engine 640 34 .enclosureSignEsc=““. The definition of special characters also needs to be included.addBeginSeparatorAsField=<fieldname> and/or xml. as they were specified in xml.beginSeparator and xml. you can specify non-printable ASCII characters. Special Characters in the String for Separators: In all strings for separators (xml.SAP Online Help 24. The default value is an empty character string (no separator before the first column). The system skips this separator when it processes the last column (otherwise the system would treat it as part of the last column).beginSeparator and xml. The system skips this separator when it processes this column (otherwise the system would treat it as part of the first column).enclosureSign=“ and xml. are then inserted either at the start or the end of the structure. If the escape character for a quotation mark (““) itself occurs in the text it is replaced by the quotation mark during the transfer.endSeparator.fieldNames= If you specified fromConfiguration for processFieldNames=. Inserting Strings for Separators in the XML Document: The separators specified with xml. where HH represents the character coded as a hexadecimal value. To do so. make a specification here. The system expects a file with one or more logical structures (Recordsets). The default is row. The files contain various row formats in logical structures.fieldSeparator=. xml.fieldContentFormatting=trim|nothing If you specify trim (the default setting). the value remains unchanged. the namespace is added to the name of the document. The format of a substructure of this type is fixed and corresponds to the description of the line format in step 5. the system expects a string that contains the names of the file columns in the same format as the file rows. The document constructed from the specifications described looks as follows: <documentName> <structureTitle> <field-name1>field-value</field-name1> <field-name2>field-value</field-name2> <field-name3>field-value</field-name3> </structureTitle> <structureTitle> <field-name1>field-value</field-name1> <field-name2>field-value</field-name2> <field-name3>field-value</field-name3> </structureTitle> </documentName> A document of this type cannot be processed further by the Integration Engine.endSeparator and/or xml.SAP Online Help 24. An unlimited number of recordsets (from one to all recordsets in the file) can be sent to the Integration Engine as separate messages.structureTitle=<anyName> The value you specify here is used as the name of the structure in the XML schema. This means that the same separator string and any additional strings you specify for xml. There can be a fixed or variable number of substructures in a recordset. it is inserted in the message as the main XML tag. A recordset can contain multiple types of substructures identified by logical names. Plain J2SE Adapter Engine 640 35 .02. xml. Specifications for the conversion to an XML document in mode FILE2XMBWITHSTRUCTURECONVERSION) In this mode. A substructure must always be represented in exactly one line of the text document. you can convert text files with more complex file structures to an XML output format.fieldFixedLengths=. The default setting is resultset.beginSeparator are expected. all blanks that proceed and follow a found value are removed. If you specify nothing.documentNamespace=<namespace> If specified. xml. the system expects a string that contains the names of the file columns as arguments separated by commas (this is also true if you specify a value for xml. xml. If you only specify a value for xml. 8.2004 If you specify a value for xml.documentName=<name> If you specify a document name.comlumnSeparator=). each part of a document from which a message is created) is sent to the Integration Engine exactly once. xml. Any outstanding Exactly Once messages can no longer be sent for this file. the adapter creates multiple messages from a document. the file is treated as new. If you specify Exactly Once as the Quality-of-Service. This is also true if the application is interrupted while creating the messages and restarted again later. xml. then this specification is mandatory since an XML document must contain exactly one main tag.recordsetsPerMessage=<noOfRecordsets> 1.nA.recordsetStructure (at least one substructure with a the number ‘*’ ). This means that a key field must be set with different constants for the different substructures.… or * (for a variable.recordsetName=<tagName> The value you specify here is used as the name of the structure in the XML schema. The default is Recordset. xml.keyFieldName=<fieldname> If you specified a variable number of substructures for xml. xml.documentName=<name> This specification is mandatory if you set recordsetsPerMessage to a value greater than 1 or *. xml. Specifies the number of recordsets to be grouped together for one message.3. the substructures must be identified by the parser from their content.2004 This string specifies the sequence and number of substructures (identified by logical names). xml. If the number of recordsets in a document is greater than the number specified.SAP Online Help Specifications for Recordsets: xml. The same is the case for nB. and so on.documentNamespace=<namespace> If specified.recordsetNamespace=uri If specified. * for an entire document in a message.….02. If you change the file containing the document before the application is restarted. unlimited number. The default is 0.recordsetStructure=<NameA. each of these messages (that is to say. this is added to the name of the recordset. Plain J2SE Adapter Engine 640 36 .2. xml.nameB.nB. it is inserted in the message as the main XML tag. The last of these messages might then contain fewer recordsets than specified.…> 24. the namespace is added to the name of the document. Therefore. If you specify a document name. If the generated message comprises more than one recordset. nA=1. including 0).documentSkipFirstRows=<noOfRows> Specifies how many rows are to be skipped at the start of the document. So the default is NameA. The default is add. No structure information can be transferred in the file itself.fieldNames=<listOfFieldnames> This specification is mandatory for the aforementioned reasons. xml.NameA.processFieldNames= You do not need to make any specifications here since this property is defined by fromConfiguration in this mode. Specifications for Substructures: Use the same specifications you made in step 5 and add the name of the substructure to the name of the respective property.keyFieldType=CaseSensitiveString|CaseInsensitveStr ing|Integer|Float If you specify a key field. The comparison with the specified values is based on this key field type (see xml. then you must also specify its type. If all structures are defined as variable (*).NameA. A new recordset is started as soon as an earlier structure occurs. Plain J2SE Adapter Engine 640 37 . If the value is var (variable). xml. The default value is asc. the order is not assumed to be fixed. A new recordset is only started when another structure occurs that is defined with a fixed number.02. Changes to the properties in step 5: xml.2004 In this case.recordsetStructure.NameA.NameA.structureTitle=<anyName> The default is not row here. the system interprets the entire document as a single recordset. This means that the definition of the substructure must be contained in the configuration file.fieldNames to specify the field names of substructure NameA. you must specify a key field and the field name must occur in all substructures.NameA. xml.keyFieldValue=<valueInSubstructureName> This specification is also mandatory if you set xml.NameA.NameA. xml.SAP Online Help 24. If a structure has a fixed number of substructures.recordsetStructureOrder=asc|var The start and end of recordsets containing a variable number and arrangement of structures are determined as follows: If the value is asc (ascending).keyFieldValue= below). xml. xml.keyFieldName= in the recordset definition.fieldNames instead of xml. but the structure name from xml. this specification is ignored. xml. separated by a period after the XML prefix. the order of the recordset structures is assumed to be fixed.keyFieldInStructure=add|ignore Here you can specify whether the key field of the substructure should be added to the XML document (add) or ignored (ignore). this specification is mandatory.. the suffix).02. Additional file contents can only be transported unchanged.namePart=<”Main-NamePart”=”Additional-NamePart”> Plain J2SE Adapter Engine 640 38 .documentName=. </recordset> </documentName>.sourceDir.. Transport of further documents within a message to the Integration Engine You have the option of transporting additional file contents within a message to the Integration Engine. which must be identical except for one defined part (for example..endSeparator= 24.. To add additional file contents.. in other words.. file.SAP Online Help xml. The following rules apply for this procedure: The files must all be in the same directory that is defined in file.recordsetsPerMessage.. without the conversion options described in points 5 and 6. <recordset> <NameA> <field-nameA1>field-value</field-nameA1> <field-nameA2>field-value</field-nameA2> <field-nameA3>field-value</field-nameA3> </NameA> <NameB> <field-nameB1>column-value</field-nameB1> <field-nameB2>column-value</field-nameB2> <field-nameB3>column-value</field-nameB3> </NameB> </recordset> . If the message contains more than one recordset.AdditionalPayloads=<NameA. The document constructed from the specifications described looks as follows: <documentName>. The files that are to be transported are grouped together using their file name. NameB. you must make the following specifications: XI..NameA. 9. A document of this type cannot be processed further by the Integration Engine. a line break must follow since substructures are always expected as a line of the document. The tag <documentName> is completed if you made a specification for xml. The number of recordsets is in turn dependent on the specification made for xml. Messages of this type with multiple payloads require a corresponding receiver that can process them. …> This specification defines a logical name for each additional file that is then used in the subsequent parameters.2004 Even if no specification is made here. <recordset> .NameA. Rules to convert an XML text file that represents a simple table structure. the specification is ignored and the message sent to the Integration Engine without the additional file contents. For YES.NameA. the action is terminated with an error message.namePart=”.namePart=”.optional=YES|NO Specify here whether the additional file is required or whether it is optional. to a text document with columns of fixed length or columns that are separated by particular characters.SAP Online Help 24. pdf and doc are included in a message: file.doc are searched for and processed like file x2.txt The files x1. To configure the adapter you must specify the following: • • • • A directory and rule to determine the file names under which inbound messages are saved.doc” The files x1.pdf” file. file. the files x2. A dispatcher class (optional) with the corresponding settings and the user exits and their settings that are to be called by the dispatcher The address (HTTP port and URL) where the adapter can be contacted from the Integration Engine. Configuring the Receiver File/FTP Adapter Use You need to configure the receiver file/FTP adapter to save XML messages from the Integration Engine [Extern] in files.txt”=”.type=<type> Specifies the document data type.txt.02. Likewise.sourceFileName=x*.pdf and x2. or both (these specifications are optional). The default is YES. XI. file. The following values are permitted: type=BIN (binary data type) type=TXT (text data type) The default value is BIN.doc were also searched for in the same directory as the file x1.addaDOC.txt and x2.AdditionalPayloads=addaPDF. The contents of these three files are included in a message to the Integration Engine.txt were found in the specified directory following this specification.NameA.pdf and x1.2004 This specification specifies which part of the original file name is to be replaced to create the name of the additional file. If the file is not found for NO.txt”=”. Plain J2SE Adapter Engine 640 39 .txt.addaPDF. The following example explains how three files of type text. addaDOC file. adapter.. Selected [Seite 10] the adapter on the configuration screen. Procedure The configuration of the receiver file/FTP adapter comprises five functional sub areas: .. XI.SAP Online Help 24. Installed [Seite 6] the corresponding adapter. The expected XML format corresponds to the result of the conversion of the sender JDBC or file/FTP adapter. 3. The settings required for the dispatcher are explained in the example [Seite 86].0 adapter configuration. with elements separated by commas or with fixed column lengths. 2. You must make the necessary specifications for the conversion in step 5. Specifications for addressing by the Integration Engine XI. This file format can be processed by the sender file/FTP adapter [Seite 26] in the mode FILE2XMBSTREAM.aii. If no specification is entered.httpPort=<port_no> <port_no> specifies the HTTP server port that receives the messages from the Integration Engine.. mode=XMB2FILEWITHCONVERSION A text file is expected that contains an XML document that represents a table. Called the adapter configuration by choosing Configure.. The Java class name for the receiver file/FTP adapter Specify the class name as follows: classname=com. This document can be converted to a text file that stores the contents of the document as a list. Other values are not permitted and trigger an error. including all Integration Engine-specific parameters that then no longer need to be specified in the sender file/FTP adapter. the configuration is interpreted as an XI 2. The default value is XMB2FILE. 5.messaging. 3. 1. The version specification for the configuration version=30 This specification is mandatory. 4. mode=XMBSTREAM2FILE A special file format is generated here that represents a completely serialized Integration Engine message. The following values are permitted: mode=XMB2FILE The system saves the document sent from the Integration Engine as a file. 2. The dispatcher class and the user exits to be called by the dispatcher (optional) The receiver file/FTP adapter provides you with a dispatcher that you can use to convert messages after they have been received. This format can be used to temporarily save complete Integration Engine messages.02.httpService=<service> Plain J2SE Adapter Engine 640 40 . File/FTP adapter mode Specify the mode of the receiver file/FTP adapter. 1.sap.ModuleXMB2FILE This specification is mandatory.2004 Prerequisites You have: . or if the business system does not exist in the SLD. If. an association for the receiver file/FTP adapter is created for this business system.httpPort=1234 and XI.0: http://<fileadapterhost>:1234/file/Receiver?action=execute& pipelineid=Receiver If the Integration Engine message is sent to a non-specified adapter service. the specification is meaningless. These specifications are mandatory. the system displays the following error message: No registered listener for <Service> found The system displays the same message if the adapter is initialized.createDir=<n> Specify whether a target directory (targetDir) should be created (1) or not (0). If no connection can be established with the SLD. if one does not already exist. Specifications for file processing: file. you have specified XI. but has not been started (status STOPPED or INITIALIZED).ReceiverAdapterForService=<Service> This specification is optional.targetFilename. The default value is 1 (create directory).2004 <service> describes the service part of the address where the Integration Engine must send its messages. <Service> is the logical name of a business system in the System Landscape Directory (SLD). XI.writeMode=overwrite Plain J2SE Adapter Engine 640 41 .SAP Online Help 24.writeMode=<mode> Specify whether the system is to save all inbound documents under the file name that you specified in file.02. the address of the adapter is determined from this association as the default value. 6. The following specifications are mandatory: file. for example. file.createDir. The system creates this directory automatically if you do not make any specifications for file.targetDir=<directoryName> Specify the target directory where incoming documents are to be saved. The following values are permitted: file.targetFilename=<fileName> Specify the file name where the system is to save the first incoming document. If the Adapter Engine connection to the SLD is configured.httpService=/file/Receiver. When you create an end point for this business system in the Integration Directory [Extern]. file. the end point address of the file/FTP adapter in the Integration Engine must be specified as follows: http://<fileadapterhost>:1234/file/Receiver The end point address must be extended as follows for the Integration Engine in Release 1. targetFilename and the message ID (GUID) used by the Integration Server in the format xxxxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx. in each case extended by a time stamp in the format yyyyMMdd-HHmmss-SSS. The default value is 000. the file is overwritten so that the system always only saves the last received document. though leading zeros are permitted. file. which is inserted before the file name extension. The default value is 1.targetFilename. The mode addCounter guarantees that no data is overwritten. The default value is an empty character sequence (that is. It must be a valid integer number. default002. The file name comprises the name specified under file. If necessary.counterMode=<counterMode> Plain J2SE Adapter Engine 640 42 . no SeparatorString). files that originate from the same adapter configuration can simply be sorted according to the date that they entered processing file. The file name comprises the name specified under file. file. The counter is constructed from the subsequent specifications. This mode guarantees that no data is overwritten. file. This corresponds to the time that the document was processed.file). The file name comprises the name specified in file. The length of the FormatString is used for all counters (including existing leading zeros) until overflow forces the format to be enlarged. the system finds the next free counter from which it can construct a new file name. from the year (yyyy) to the millisecond (– SSS). This mode guarantees that no data is overwritten. file. file. extended by one counter that is added before the file name extension (for example.writeMode=addTimeStamp In mode addTimestamp the system generates a new file for each document.writeMode=append In append mode the file is updated by appending the incoming documents.targetFilename. In this way. In mode addCounter the exact format of the file name can be controlled using the following parameters.writeMode=addMessageId In mode addMessageId the system generates a new file for each document.2004 In mode overwrite. each parameter has a default setting.counterFormat=<FormatString> Specify the first counter to be used. file.counterSeparator=<SeparatorString> Specify one or more characters that you want to add before the numerator in the file name. file.writeMode=addCounter In mode addCounter the system generates a new file for each document.SAP Online Help 24.02.counterStep=<StepNo> Enter a number that specifies the increment of the counter that successive counters are to be increased by. test_00009.targetFilename=test. The default value is an empty character string (no command). <default000.dat. This list is also continued once the adapter has been stopped and restarted.exactlyOnceHandlingIDsExpiration=<n Days> Specify the number of days that the management information for received messages with the service attribute Exactly Once (In Order) should be kept.counterFormat=00005 file.file>. If you do not set a parameter. <default002. If file. the data is saved without being changed). The following values are permitted: file. you set the following explicit values file.targetFilename was used unaltered. You can also enter the currently processed file name with the placeholder %f (file name) or %F (absolute filename including path) in the operating system command. if when handling an error the Integration Engine sends the same message to an adapter more than once.counterStep=2 the system generates the file names test_00005.encoding is specified and the Integration Server sends binary data.2004 Specify when a counter is to be added.file> from the specified default values for incoming documents. the text data coded by the Integration Server in UTF-8 is converted accordingly). without overwriting existing files. This information is required to avoid messages being duplicated.encoding=<codepage> This parameter is optional.file>. Plain J2SE Adapter Engine 640 43 .counterMode=afterFirst Only add the counter after the file name specified under file. <default001.dat. The default value is afterFirst. The default value for binary data is the code page used by the Integration Server (that is.counterMode=immediately file. the system generates the file names <default.counterMode=immediately The counter should be added after the first incoming document.dat file. If instead of the default values.execute=<operating system command> An operating system command specified here is executed after a file has been successfully processed. file. file.dat and so on. The default value for text data is the system code page of the Adapter Engine (that is. file. this is interpreted as text coded in UTF-8. test_00007.02. file.SAP Online Help 24.file>.counterSeparator=_ file. The default value is 60 days. This file is then automatically renamed during the Exactly Once handling. this problem is avoided because the file only becomes visible with the search name when the transfer is complete. It is not obligatory that you specify the port number here. the document format must be the same as that which is generated by the sender file/FTP adapter in mode Plain J2SE Adapter Engine 640 44 . The default user is anonymous with the password anonymous.SAP Online Help 24.02. It must not be renamed or edited manually in any way. If you specify YES.connection=perFileTransfer|permanently Use this specification to define whether a new connection needs to be established each time a file is transferred to the FTP server (value perFileTransfer). all management information is deleted each time the adapter is initialized. The default value is NO. or whether a permanent connection should be used (value permanently). ftp.putSafe=YES|NO Use this specification to define whether a transferred file is first created with a temporary name and only renamed once the transfer is complete (YES).targetFileName refer to the FTP server. ftp. Specifications to convert an XML document (mode XMB2FILEWITHCONVERSION) The following arguments refer to the mode XMB2FILEWITHCONVERSION.targetDir and file.port=<port-no. In another mode the arguments subsequently executed are ignored. due to a timeout). or whether it is created with its final name at the start of the transfer (NO). The default is the standard port for the FTP server (21). It is not obligatory that you specify a user name. The specifications file. 7. ftp.2004 If the value is set to 0 or to a negative value. you need to make the following additional specifications: In the FTP client mode. To convert a table in XML format to pure text format. The latter case can lead to problems if an application on the FTP server accesses the file before the transfer is complete. the value addCounter is not permitted for the parameter file.password=<password> A valid user name for the FTP server. ftp. If you want to save files on an FTP server and not in the file system. a temporary file with the name of the adapter configuration is generated first in the target directory. the connection is re-established automatically if it closed on the server side (for example.user=<user name> ftp. In this case.> The port number of the FTP server. If a message is received with the service attribute Exactly Once. This can be useful for test purposes but must not be used for production operation. or deleted since this can lead to the message being lost. The default value is permanently. If this specification is available.host=<ftp-server> The host name or IP address of the FTP server.writeMode. it is assumed that you are accessing an FTP server. ftp. If you do not make any specifications for xml. the specification xml.fieldFixedLengths=<String> Specify a character string that contains a list of fixed column widths that are separated by commas and which determine the number and the length of columns generated in the text file. Using the following specifications. followed by a blank line 3 – Header line is stored as xml. of course. The XML elements in italics can be defined by the user and the elements of a line must be grouped within an element of type <row> … </row>.fieldSeparator. xml.fieldFixedLengths is mandatory.fieldFixedLengths. followed by a blank line This specification is mandatory.02.addHeaderLine has the value 3 or 4. Plain J2SE Adapter Engine 640 45 .headerLine in the configuration and is copied 4 – as for 3. This means that the document structure looks like this: <resultset> <row> <column-name1>column-value</ column-name1> <column-name2>column-value</ column-name2> <column-name3>column-value</ column-name3> </row> <row> <column-name1>column-value</ column-name1> <column-name2>column-value</ column-name2> <column-name3>column-value</ column-name3> </row> </resultset> This is an example for 3 columns and 2 lines. The number of lines and columns is. xml. the system constructs a text file from this XML document. xml. unlimited.addHeaderLine=<n> Specify whether the text file should have a header line with columns names.fixedLengthTooShortHandling=Error Error means that processing of the document is terminated.2004 FILE2XMBWITHROWCONVERSION (with the default value <row> for the structure) and the sender JDBC adapter.headerLine=<headerLineString> Specify the header line that is generated in the text file if xml. The following values are permitted: xml. xml.fixedLengthTooShortHandling=<handling> Specify how you want the system to respond when column widths in the actual document exceed those defined in xml. This specification is mandatory. The following values are permitted: 0 – No header line 1 – Header line with column names from the XML document 2 – as for 1.SAP Online Help 24. this specification is obsolete.SAP Online Help xml. this is the only specification to identify the individual columns in a row.endSeparator=<lastSeparatorString> If you enter a character string here. The default value is an empty character string (no separator before the first column). xml.2004 Cut means that a value is shortened to the maximum permitted length. These characters can be each be inserted individually in the string in the form ´0xHH´ (including the quotation mark). the system places it before the first column. xml.02. You must specify at least either xml.fieldSeparator . You can also specify this string in addition to xml. instead the structures are arranged line-by-line). xml. you can specify non-printable ASCII characters. Subsequent columns are moved correspondingly.fieldFixedLengths. the system adds it to the last column as a closing character.beginSeparator=<firstSeparatorString> If you specify a character string here. If you made a specification for xml.fieldFixedLengths. regardless of it being too long.fieldSeparator=<SeparatorString> If you specify a character string here. To include a line break following the closing character. The default value is a line break (no explicit separator after the last column. A line break can be entered using the character ´nl´ (including the quotation marks).fixedLengthTooShortHandling=Ignore Ignore means that the system copies the value completely.fieldFixedLengths. If you specify xml. where HH represents the character coded as a hexadecimal value. Plain J2SE Adapter Engine 640 46 .fieldSeparator. The default value is Error. You can also make this specification in addition to xml.fieldFixedLengths.beginSeparator and xml. If you made no specification for xml. You can also make this specification in addition to xml.fieldFixedLengths. If you do not specify xml. it is added as a separator to all columns except the last. Special Characters in the String for Separators: In all strings for separators (xml. the length of the separator is not taken into account. nl stands for new line here. the structures of the XML document can have differing numbers of elements that are added to each other separately in the text file by the value from xml. you must explicitly define it by attaching ´nl´ (including the quotation marks) to the string.fieldSeparator.fieldSeparator.endSeparator).fieldFixedLengths. xml.fieldFixedLenghts this is not possible since the number of columns is defined when the column widths are given.fixedLengthTooShortHandling=Cut 24. If you have only specified xml.fieldFixedLengths or xml. xml. . To restrict the width of the text. Java class name for the sender JDBC adapter Specify the class name as follows: classname=com.. Procedure The configuration of the sender JDBC adapter comprises four functional subareas: .2004 Fixed Column Width of the Text Document xml. The version specification for the configuration Plain J2SE Adapter Engine 640 47 .ModuleDB2XMB This specification is mandatory.aii. Installed a JDBC driver (Version 2.. 2. 4. To configure the adapter you must specify the following: • A JDBC database driver to access the database This driver is not supplied with the adapter but must be supplied by the database provider or third-parties. Selected [Seite 10] the adapter on the configuration screen. 2. This value requires xml. 3. This parameter also functions together with the specification of a line break for xml.02..SAP Online Help 24.absoluteRowWidth=<noOfColumns> If the separators do not contain any line breaks. Configuring the Sender JDBC Adapter Use You need to configure the sender JDBC adapter to send database contents to the Integration Engine [Extern]. use this parameter. Installed [Seite 6] the corresponding adapter. 1. the text document is generated as a single line text.0) for the database.sap.messaging.addHeaderLine=0 to be specified. <noOfColumns> represents the maximum number of columns in this case.endSeparator.adapter. • • • • • Logon data for the database to be read from An SQL statement to determine the table contents you want to read An SQL statement to process successfully sent table contents A dispatcher class (optional) with the corresponding settings and the user exits and their settings that are to be called by the dispatcher Sender and receiver data required by the Integration Engine for routing and mapping Prerequisites You have: . Called the adapter configuration by choosing Configure. 1. The dispatcher class and the user exits to be called by the dispatcher (optional) The sender JDBC adapter provides you with a dispatcher that you can use to convert messages before they are sent.proxyPort=<proxyPortnumber> <proxyHostname> is the host name of the proxy and <proxyPortnumber> is the port where the proxy receives HTTP requests (for example.02.2004 This specification is mandatory. If an authentication was specified for the specified URL (HTTP service) in the Integration Engine.proxyHost=<proxyHostname> XI. The following entry is added to the configuration for this purpose: XI.SenderService is read from the SLD and used instead of the value specified under XI. 8080). the SLDaccessor [Seite 19] service must be configured correspondingly and the respective entries must be maintained in the System Landscape Directory. specify the following: XI. 5. The settings required for the dispatcher are explained in the example [Seite 86]. Specifications for the Integration Engine Enter the complete address (URL) of the Integration Engine that you want to send the message to: XI. JDBC adapter mode Specify the mode of the sender JDBC adapter. the configuration is interpreted as an XI 2. Other values are not permitted and trigger an error.SAP Online Help version=30 24.Password=<password> Plain J2SE Adapter Engine 640 48 .SLDConfiguration=SLDaccessor In this case the URL of the corresponding Integration Server for the system specified with XI. The Integration Engine address can also be accessed dynamically from the SAP System Landscape Directory. If no specification is entered.TargetURL=<fromSLD> To be able to access the System Landscape Directory. Therefore. 4.TargetURL=http://IntegrationEngineHost:port/pipelinearguments This specification is mandatory. The following is the only permitted value: mode=DB2XMB Subsequent versions may permit additional values. the following specifications are mandatory: XI.0 adapter configuration. If the Integration Server is accessed by means of an HTTP proxy server rather than directly. the following parameters must be set: XI. 3.TargetURL.User=<user-name> XI. jdbcDriver=<java_class_of_jdbcdriver> Specify the Java class of the JDBC driver that the JDBC adapter must load to be able to access the driver. the system will terminate each attempt to access the Integration Engine with the message Transport Exception: http-Error 401 – Unauthorized. The following values are permitted: XI.SenderInterfaceNamespace=<namespace URI> XI.QualityOfService=<QualityOfService> Specifies how the Integration Engine should process a message.Client=<client-no> XI. or the combination is invalid.qualityOfService=BE (Best Effort. means synchronous processing) XI.SenderInterface=<name> XI.SenderParty=<sender party name> XI.SenderService. The exact specification varies according to the JDBC Plain J2SE Adapter Engine 640 49 .ReceiverParty=<receiver party name> XI. Specification of the receiver is only mandatory if no receiver is determined during routing.SenderService=<sender service name> XI. You can also find an explanation about each argument there.InterfaceNamespace. If you want to use a different client or language to the default setting in the Integration Engine when logging on. in other words guaranteed execution exactly once and maintaining the sequence of successive messages) You must also define a queue name for EOIO: XI. 6.ReceiverService=<receiver service name> You must set at least XI.qualityOfService=EO (Exactly Once. you can also set the following parameters: XI. and XI. If you do not specify a user and password combination. The user must have the authorizations of group SAP_XI_APPL_SERV_USER on the Integration Server.02.Language=<language-id> The following address arguments for the sender system (the JDBC adapter) are mandatory: They are used to identify the adapter configuration in routing [Extern] and in mapping [Extern] in the Integration Engine pipeline [Extern].QueueId=<QueueName> This queue name is used in the Integration Engine to process messages in the same sequence that they arrived in.qualityOfService=EOIO (Exactly Once in Order.2004 The specifications must match those that you made in transaction SICF in the Integration Engine. Specifications for database access db. XI. XI.SAP Online Help 24. XI. means asynchronous processing using queues. means asynchronous processing with guaranteed execution exactly once) XI.Interface. The exact format of the address can vary. This means that instead of the JDBC call getConnection(url). the data has not only been read by a stored procedure defined in the statement db. If you specify NO. once the data has been successfully sent. UPDATE. the call (url.password)is executed in the JDBC adapter. see material from the respective provider for exact details. The default setting is YES.user.processDBSQLStatement. when an error occurs the JDBC adapter terminates the connection to the database and it must then be restarted from the administration screen. The expression only needs to correspond to the SQL variant supported by the respective JDBC driver. This must be an INSERT. the system does not execute a database operation and the data remains unaltered in the database. for example.password=<password> Instead of using the database logon in the string specified by the parameter db. so it can also contain table JOINs. This specification is mandatory.processDBSQLStatement) has been successfully sent to the Integration Engine.reconnect=YES|NO When a database connection error occurs.SAP Online Help 24. The default value is <TEST>. db. Examples of typical scenarios would be deleting the sent data from the database with a DELETE statement or selecting the data with an UPDATE statement. This mode is exclusively of use when testing the configuration of the adapter or the Integration Engine. db.confirmDBSQLStatement. and this call is expected or handled differently by some database systems.user=<username> db. This means that data is sent again as a new message if the adapter is restarted or if the time period specified in de. db. as well as the formatting of the message are all performed within one database transaction. you could also specify <TEST> (including the pointed parenthesis). In this case. In Exactly Once mode. Instead of the SQL statement. The message is then sent afterwards.02.2004 driver. This specification is mandatory. this parameter enables you to specify whether you want reconnect to the database via the JDBC driver each time the database is accessed. db. or specify an SQL EXECUTE statement to execute a stored procedure that contains exactly one SELECT statement. Until the message has been Plain J2SE Adapter Engine 640 50 .processDBSQLStatement=<SQL-Select-Statement> Either specify a valid SQL SELECT statement to select the data to be sent from the specified database.connectionURL. and is not for production operation. This specification is mandatory. specify the database logon explicitly with user and password. for example. or DELETE statement.processDBSQLStatement and db. This may be useful (except for test purposes) when.pollInterval is exceeded. but has already been changed. db. see material from the respective provider for more details.connectionURL=<jdbc_driver_connection_url> Specify the address with which you can establish a database connection using the JDBC driver.confirmDBSQLStatement=<SQL-Update-Statement> Specify a valid SQL statement that can be applied to the database once the data (determined with db. the statements specified under db. logPollInterval=NO|YES All entries to loops that last longer than 5 seconds are shown in the adapter log by default.execute=<operating system command> If you specify an operation system command here.disconnect=NO|YES The database connection is released and then reestablished before each poll interval. even when a value greater than 0 was specified for db. db.pollIntervalMsecs). choose Stop/Start or Restart to restart the adapter. it is temporarily persisted as a file in the Adapter Engine directory /Data. If this value is 0 (processing is not repeated). Plain J2SE Adapter Engine 640 51 . To process the file again. the output can be activated with db. then very short. To avoid data inconsistencies in the database when the logical unit of work is deactivated. the log output (but not the loop itself) can be deactivated by using db.SAP Online Help 24.logPollInterval=NO. If db. choose Stop/Start or Restart to restart the adapter.02. The value from db. The default value for this parameter is 0. You can also specify the following parameters so as to specify an additional waiting time in milliseconds: db. db.autoCommit=NO|YES Use this parameter to deactivate the logical unit of work required by the JDBC adapter to guarantee that the data in the database is consistent. db.logPollInterval=YES. db.retryInterval is also 0. then SQL statements processed with errors are not processed again. In this case the adapter status remains as STARTED. For loops that last 5 seconds or less. the system executes it following successful database operations (PROCESS and CONFIRM statements). if you do not want to repeat the call.pollInterval if you have not specified a value for parameter db. then the adapter is terminated if an error occurs. To initiate a new call. You can set the value to 0.retryInterval= Specify the number of seconds that the adapter is to wait before a SQL statement processed with errors is processed again.pollInterval is adopted as the default value. The default value is NO. this can lead to a lot of entries in the log. This option is required for JDBC drivers that do not support transactions. db.pollInterval= Specify the number of seconds that the adapter must wait before it calls the db. almost real time processing times can be achieved.pollInterval.pollIntervalMsecs= If db. db. This specification is mandatory. The default value is an empty character string (no command). In such instances. As a result. In this case the adapter status remains as STOPPED.pollInterval is set to 0.2004 sent successfully to the Integration Server.processDBSQLStatement again. If the call is not to be repeated then you must set both parameters to 0 (or just the parameter db. db.transactionIsolation=0|1|2|4|8 There are different levels of database transactions known as isolation levels.02. however. The JDBC adapter uses the highest isolation level by default to avoid database inconsistencies arising from parallel database transactions. db. only do this when necessary. that lowering the isolation level can have an adverse effect on transaction security. if the system does not display a corresponding error message during normal operation. Some JDBC drivers or database products do not support this isolation level and it may therefore be necessary to lower it accordingly. Therefore. Result The system converts the table resulting from the db.processDBSQLStatement into a valid XML document and sends it to the Integration Engine. To avoid data inconsistencies in the database when the isolation level is lowered. The values listed above correspond to the following JDBC constants: 0 – TRANSACTION_NONE 1 – TRANSACTION_READ_UNCOMMITED 2 – TRANSACTION_READ_COMMITED 4 – TRANSACTION_REPEATABLE_READ 8 – TRANSACTION_SERIALIZABLE The default value is 8.documentName=<name> If you specify a document name.2004 ensure that multiple database transactions cannot access the database simultaneously. You must only lower the isolation level where necessary and as far as necessary. Do not set this parameter to YES if the JDBC driver supports transactions. db. The default value is NO.documentNamespace=<namespace> If specified. that is. ensure that multiple database transactions cannot access the database simultaneously. Note. the namespace is added to the name of the document.SAP Online Help 24. it is inserted in the message as the main XML tag. The default setting is resultset (see below). The document looks as follows: <resultset> <row> <column-name1>column-value</ column-name1> <column-name2>column-value</ column-name2> <column-name3>column-value</ column-name3> </row> <row> <column-name1>column-value</ column-name1> <column-name2>column-value</ column-name2> Plain J2SE Adapter Engine 640 52 . 0) for the database. 4. The version specification for the configuration version=30 This specification is mandatory. Procedure The configuration of the receiver JDBC adapter comprises five functional subareas: . To configure the adapter you must specify the following: • A JDBC database driver to access the database This driver is not supplied with the adapter but must be supplied by the database provider or third-parties.. If no specification is entered.02. 1.. JDBC adapter mode Specify the mode of the receiver JDBC adapter.sap. Other values are not permitted and trigger an error. Installed [Seite 6] the corresponding adapter. 1.. 2. Selected [Seite 10] the adapter on the configuration screen.. Chosen Configure to call the configuration of the adapter module.2004 Configuring the Receiver JDBC Adapter Use You need to configure the receiver JDBC adapter so that you can convert XML messages from the Integration Engine [Extern] into the contents of database tables. 3.ModuleXMB2DB This specification is mandatory. • • Logon data for the database to be written to The address (HTTP port and URL) where the adapter can be contacted from the Integration Engine. 3. Prerequisites You have: .aii. Java class name for the receiver JDBC adapter Specify the class name as follows: classname=com. Installed a JDBC driver (Version 2. the configuration is interpreted as an XI 2.adapter.0 adapter configuration. 2. 24.SAP Online Help <column-name3>column-value</ column-name3> </row> </resultset> This document can then be processed further by the Integration Engine. The following values are permitted: mode=XMB2DB mode=XMB2DB_XML Plain J2SE Adapter Engine 640 53 .messaging. stored procedures in the database can be called using transfer parameters. XI. Furthermore. you have specified XI. the end point address of the JDBC adapter in the Integration Engine must be specified as follows: http://<Datenbankadapterhost>:1234/db/Receiver The end point address must be extended as follows for the Integration Engine in Release 1.0: http://<Datenbankadapterhost>:1234/db/Receiver?action=execu te&pipelineid=Receiver If the Integration Engine message is sent to a non-specified adapter service. an Plain J2SE Adapter Engine 640 54 . Subsequent versions may permit additional processing modes. but has not been started (status STOPPED or INITIALIZED). Note the following: In mode XMB2DB. results from database queries or return values of stored procedures can also be transferred. This mode has been kept for reasons of compatibility with older versions of the JDBC adapter. Specifications for addressing by the Integration Engine XI.2004 Depending on the mode you select. XI. 4. If. the system displays the following error message: No registered listener for <Service> found The system displays the same message if the adapter is initialized. httpPort=<port_no> <port_no> specifies the HTTP server port that receives the messages from the Integration Engine. an SQL statement is expected that is transferred to the database for processing unchanged. table values can be inserted. or deleted in one or more tables. <Service> is the logical name of a business system in the System Landscape Directory (SLD). In mode XMB2DB_XML.SAP Online Help mode=XMB2DB_RAWSQL 24. In mode XMB2DB_RAWSQL. This mode is primarily for test purposes only. which is explained in more detail below. the adapter has different functions and expects the message received from the Integration Server to have a particular document format in each case.httpPort=1234 and XI. In the case of synchronous queries. for example.httpService=/db/Receiver. All actions are then executed within a database transaction – either completely or not at all. This function is described by the transmission of predefined XML schema. If the Adapter Engine connection to the SLD is configured. These specifications are mandatory. updated. but should principally no longer be used.ReceiverAdapterForService=<Service> This specification is optional. httpService=<service> <service> describes the service part of the address where the Integration Engine must send its messages. table values are inserted in a table that is specified in the adapter configuration.02. The type and number of actions that can be bundled in a message is not restricted. jdbcDriver=<java_class_of_jdbcdriver> Specify the Java class of the JDBC driver that the JDBC adapter must load to be able to access the driver. the address of the adapter is determined from this association as the default value. The JDBC adapter automatically reconnects to the database when a database connection error occurs.02. db. db. If the number of retries is reached. The exact format of the address can vary. The default value is NO. When you create an end point for this business system in the Integration Directory [Extern]. Plain J2SE Adapter Engine 640 55 . the last status is returned to the sender Integration Server. The default value is NO. db. Specifications for database access These specifications are mandatory and have no default values. see material from the respective provider for exact details. The default value is 0. see material from the respective provider for more details. In the case of an error. The default value is an empty character string (no command). db. Do not set this parameter to YES if the JDBC driver supports transactions. The exact specification varies according to the JDBC driver. This option is required for JDBC drivers that do not support transactions. db.SAP Online Help 24.2004 association for the receiver JDBC adapter is created for this business system. that is.connectionURL=<jdbc_driver_connection_url> Specify the address with which you can establish a database connection using the JDBC driver.autoCommit=NO|YES Use this parameter to deactivate the logical unit of work required by the JDBC adapter to guarantee that the data in the database is consistent. the specification is meaningless.disconnect=NO|YES The database is closed after each database transaction and the database connection is disconnected (YES) or maintained (NO). 5. To avoid data inconsistencies in the database when the logical unit of work is deactivated. if the system does not display a corresponding error message during normal operation.execute=<operating system command> An operating system command specified here is executed following successful database operations. the message is therefore only processed again when it is resent by the Integration Server. If no connection can be established with the SLD.noOfRetries=<n> Specifies how often the system attempts to re-establish the database connection and access the database following an SQL exception. ensure that multiple database transactions cannot access the database simultaneously. db. or if the business system does not exist in the SLD. this kind of situation is identified when the application is started and editing of the message terminated during processing can be controlled using db. However. ensure that multiple database transactions cannot access the database simultaneously. 6. Additional specifications to handle messages with Quality of Service = Exactly Once (In Order) db. if the error occurs because the message was saved in the database when it was first processed and it is still located there. Note. This problem can only be Plain J2SE Adapter Engine 640 56 . All adapter error statutes and program terminations initialized externally (shutdown of the adapter operating system process) are also handled in this mode. To avoid data inconsistencies in the database when the isolation level is lowered. However. Nevertheless.exactlyOnceErrorInPendingState.2004 There are different levels of database transactions known as isolation levels. For example. it is possible that a message can become duplicated during Exactly Once handling. processing can be completed for the sender system using the value IGNORE (note that the database interface normally triggers the error duplicate insert if at least one of the table fields was defined as a primary key). However. Some JDBC drivers or database products do not support this isolation level and it may therefore be necessary to lower it accordingly. The JDBC adapter uses the highest isolation level by default to avoid database inconsistencies arising from parallel database transactions. this does not include external program terminations during a database commit. This specification is only effective for handling errors that occur when a message is being processed for a second time after initial processing remained in the unclear status described above. however.02.transactionIsolation=0|1|2|4|8 24.SAP Online Help db. Otherwise the sender system will continue to send the message and the error will continue to occur. if there is no primary key field in the database table or if the data is already being processed by another application and it is then deleted.exactlyOnceErrorInPendingState=IGNORE|ERROR As in the other adapters. when the first attempt at message processing is interrupted by an external termination of the adapter process immediately after the database commit. that lowering the isolation level can have an adverse effect on transaction security. Exactly Once messages are handled by default using status information in the file system. In this case. Therefore. The values listed above correspond to the following JDBC constants: 0 – TRANSACTION_NONE 1 – TRANSACTION_READ_UNCOMMITED 2 – TRANSACTION_READ_COMMITED 4 – TRANSACTION_REPEATABLE_READ 8 – TRANSACTION_SERIALIZABLE You must only lower the isolation level where necessary and as far as necessary. only do this when necessary. a message can be duplicated. If an error now occurs during this second processing attempt. this is returned by default to the sender system as an error (or if the value ERROR is set explicitly). the status of message processing is unclear since it can only be changed in the management file once the database commit has been completed. 02. you can specify this value for the type integer) column.tableForExactlyOnceHandling. Document Format for the Receiver JDBC Adapter Depending on the processing mode selected for the receiver JDBC adapter [Seite 53]. The default value is 60 days. db.SAP Online Help 24.2004 solved if message processing and status information management take place in the same database so that the processing steps have the same commit cycle. because you want to use a table that already exists). because you want to use a table that already exists). 7. The required XML document format [Seite 57] As already explained. the adapter expects particular XML document formats in the message received from the Integration Server. This value applies to both file-based and database-based status management. However. the minimum field length is 36. This table is made known to the adapter as follows: db. Column 2 must be of type integer and have the name XIMessage_Ts.tableEOColumnNameTs=<column name> If you use a different column name to XIMessage_Is (for example. If the value is set to 0 or to a negative value. This value is only evaluated if you set db.exactlyOnceHandlingIDsExpiration=<n Days> Specify the number of days that the management information for received messages with the service attribute Exactly Once (In Order) should be kept.tableForExactlyOnceHandling=<table name> Set this value to use the specified database table instead of file-based ExactlyOnce processing. you can specify this value for the type char(36) column. then a corresponding error is triggered and the adapter will not be started. This information is required to avoid messages being duplicated.tableForExactlyOnceHandling. db. db. If a greater field length is specified the table can nevertheless be used.tableEOColumnNameId=<column name> If you use a different column name to XIMessage_Id (for example. In the database where the write-to tables are located you must create an additional table with two columns for this purpose. This can be useful for test purposes but must not be used for production operation. the XML document format depends on the mode of the JDBC adapter. if when handling an error the Integration Engine sends the same message to an adapter more than once. all management information is deleted each time the adapter is initialized. If the table does not exist or the columns cannot be found or are of the wrong type. This value is only evaluated if you set db. The following processing types are possible: • • XMB2DB XMB2DB_XML Plain J2SE Adapter Engine 640 57 . Column 1 must be type character with length 36 (or more) and have the name XIMessage_ID. Plain J2SE Adapter Engine 640 58 . If a character occurs that is invalid for the database being used.columnNameDelimiter=<DelimiterSign> Depending on the database being used. This character can be specified at this point. The default setting is no delimiter character.apostropheEsc=<apostropheEscapeString> The apostrophe character (‘) is a reserved character in SQL syntax and is therefore replaced by an escape character if it occurs within value strings. the adapter triggers an error message (an SQL exception) concerning the SQL syntax that is generated by the database. column-name3). column-name2. for example. column names can be enclosed by a special delimiter character.2004 Additional processing modes may be possible with future versions of the receiver JDBC adapter. Typical replacement characters are \’ or ’’. This means that the document looks as follows: <resultset> <row> <column-name1>column-value</ column-name1> <column-name2>column-value</ column-name2> <column-name3>column-value</ column-name3> </row> <row> <column-name1>column-value</ column-name1> <column-name2>column-value</ column-name2> <column-name3>column-value</ column-name3> </row> </resultset> This is an example for 3 columns and 2 lines. The incoming message must represent a table in XML format. unlimited. The column names of the database tables are taken from the element names in the XML document (for example. if the names can contain special characters (such as a “).02.SAP Online Help • XMB2DB_RAWSQL 24.table. XML Document Format for the Mode XMB2DB An additional parameter is required in this mode: • db. db. This replacement character can be database-specific. You can also specify the following parameters: db. its contents are written to the database table specified in db. The default setting is ’’. column-name1. In mode XMB2DB of the JDBC adapter it is not possible to distribute the contents of an incoming document to different database tables. of course. The same document format is required as is generated by the sender file/FTP and JDBC adapters.table=<tablename> Specify the database table where the incoming data is to be written to. and the corresponding values are inserted for each line. The number of lines and columns is. If a character occurs that is invalid for the database being used. the adapter triggers an error message (an SQL exception) concerning the SQL syntax that is generated by the database. you can either insert (INSERT). The XML document must have the following schema in this case: <root> <StatementName1> <dbTableName action=”UPDATE” | “UPDATE_INSERT”> <table>realDbTableName</table> <access> <col1>val1</col1> <col2>val2new</col2> </access> <key1> <col2>val2old</col2> <col4>val4</col4> </key1> <key2> <col2>val2old2</col2> </key2> </dbTableName> </StatementName1> <StatementName2> <table>realDbTableName</table> <dbTableName action=”INSERT”> <access> <col1>val1</col1> <col2>val2</col2> </access> <access> <col1>val11</col1> </access> </dbTableName> </StatementName2> <StatementName3> Plain J2SE Adapter Engine 640 59 . Results from queries (SELECT) can also be included in the response in XML format for synchronous messages. Depending on the content of the message.2004 The document does not have to contain all columns of a database table as long as the database definition accepts a null value in place of the missing columns. update (UPDATE) or delete (DELETE) the data. Element names of the XML document that do not exist as table column names are ignored. XML Document Format for the Mode XMB2DB_XML In this mode you can modify one or more database tables by means of a message.SAP Online Help 24.02. SAP Online Help <dbTableName action=”DELETE”> <key1> <col2>val2old</col2> <col4>val4</col4> </key1> <key2> <col2>val2old2</col2> </key2> </dbTableName> </StatementName3> <StatementName4> <dbTableName action=”SELECT”> <table>realDbTableName</table> <access> <col1/> <col2/> <col3/> </access> <key1> <col2>val2old</col2> <col4>val4</col4> </key1> <key2> <col2>val2old2</col2> </key2> </dbTableName> </StatementName4> <StatementName5> <storedProcedureName action=” EXECUTE”> <table>realStoredProcedureeName</table> <param1 [isInput=”true”] [isOutput=true] type=SQLDatatype>val1</param1> </storedProcedureName > </StatementName5> </root> 8.2004 The document contain a tag with the arbitrary name <root>. Within this tag there are one or more statement elements that also have arbitrary names. Each of these 640 60 Plain J2SE Adapter Engine . Comments: • 24.02. The corresponding SQL statement for StatementName1 in the example above is as follows: “ UPDATE dbTableName SET col1=’val1’. all statements have the same structure: The name of the element beneath the statement element specifies the name of the database table and contains the attribute action with the value INSERT. If specified. to define table names. then no condition is specified and the entire table is to be updated. UPDATE_INSERT.conditionRequired=YES The response document described below can only be evaluated by the Integration Server if the call is synchronous because the content of the response document is not accessible if the call is asynchronous. Within this element there is (except for DELETE) an element with the name access and one or more elements with the name key. or if there is a <key> element but it is empty. The number of <key> elements with arbitrary names is not restricted. for example. including 0. this can lead to the entire table being updated and deleted respectively. UPDATE. which contain non-XML-compatible characters or characters that stop them from being used in interface definitions in the Integration Builder. If no such elements are specified. The block <access> contains the new column values and a <key> element contains the columns whose values must be identical with the specified value to get the new column values. The character “ may be missing in other column types. <table> must be the first element in the block within <dbTableName>. DELETE or SELECT. Such consequences can be avoided by setting the following parameter: db. access contains the table columns that are to be accessed and must be specified as the first element. the value specified is used as a database table name. different <key> elements are combined with a logical OR. col2=’val2new’ WHERE ((col2=’val2old’ AND col4=’val4’) OR (col2=’val2old2’)) “ As in the remaining examples. Column values within a <key> element are combined with a logical AND. key describes a condition for access. the column type String is used for all columns.2004 statements contains the description of a database action.SAP Online Help 24. the statement corresponds to an SQL UPDATE statement. • action=UPDATE Statements with this action cause existing table values to be updated. Both have arbitrary names. This may not be permitted Plain J2SE Adapter Engine 640 61 . With the exception of the execute description for a stored procedure (shown in the example under the element <StatementName5>). The response is put in a separate element <StatementName_response> for each statement element.02. The name of the <key> element is arbitrary. A statement with the action UPDATE must have exactly one <access> element. Therefore. <update_count>count</update_count> If there is no <key> element. access proceeds without any conditions. If you use the optional <table> element. In the case of UPDATE and DELETE. This enables you. The response document contains the following element as well as the number of updated table lines. SAP Online Help 24. ‘val2’) (col1) VALUES(‘val11’) Plain J2SE Adapter Engine 640 62 . <key> elements are ignored in this case.2004 by the configuration of the JDBC adapter for security reasons and will therefore result in an error during message processing and an appropriate error message. One or more <key> elements formulate the condition that deletes the table values. • action=SELECT WHERE ((col2=’val2old’ AND col4=’val4’) (col1. The corresponding SQL statement for StatementName3 in the example above is as follows: “ DELETE FROM dbTableName OR (col2=’val2old2’)) “ The response document contains the following element: <delete_count>count</delete_count> If there is no <key> element. the statement corresponds to an SQL INSERT statement. values of the table described in the <access> element are inserted in accordance with the description of the action INSERT. The names of <key> elements are arbitrary. then no condition is specified and the entire table is to be deleted. different <key> elements are combined with a logical OR. The corresponding SQL statement for StatementName2 in the example above is as follows: “ INSERT INTO dbTableName INSERT INTO dbTableName “ The response document contains the following element as well as the number of inserted table lines. including 0. If no update to the database table can be made for this action (the condition does not apply to any table entry).02. or if there is a <key> element but it is empty. The response document has the following format. the same action is executed as for UPDATE. Column values within a <key> element are combined with a logical AND. one of the two values is 0 because either an UPDATE or an INSERT action is always executed: <update_count>count</update_count> <insert_count>count</insert_count> • action=DELETE Statements with this action cause existing table values to be deleted. Initially. • action=INSERT Statements with this action cause existing table values to be inserted. col2) VALUES(‘val1’. The block <access> contains the new column values. Therefore. This may not be permitted by the configuration of the JDBC adapter for security reasons and will therefore result in an error during message processing and an appropriate error message. <insert_count>count</insert_count> • action=UPDATE_INSERT The statement has the same format as for the UPDATE action. A statement with the action INSERT must have exactly one <access> element. It cannot have a <key> element. then no condition is specified and the entire table is to be selected. The elements within the stored procedure are interpreted as parameters. This may not be permitted by the configuration of the JDBC adapter for security reasons and will therefore result in an error during message processing and an appropriate error message. or if there is a <key> element but it is empty. The corresponding SQL statement for StatementName4 in the example above is as follows: “ SELECT col1. </row> “ • action=EXECUTE Statements with this action result in a stored procedure being executed. The name of the element is interpreted as the name of the stored procedure in the database.2004 Statements with this action cause existing table values to be selected. They can optionally have the attribute isInput=“1“ (input parameter) or isOutput=“1“ (output parameter) or both (INOUT parameter). If you use the optional <table> element. Therefore. Column values within a <key> element are combined with a logical AND.col2. different <key> elements are combined with a logical OR. The number of <key> elements with arbitrary names is not restricted. for example. a <key> element contains the columns whose values must be identical with the specified value to get the new column values. The block <access> contains the column names to be selected. the statement corresponds to an SQL SELECT statement.. <table> must be the first element in the block within <dbTableName>.. <row> <column1>valueN1</column1> <column2>valueN2</column2> . the value specified is used as the name of the stored procedure. which contain non-XML-compatible characters or characters that stop them from being used in interface definitions in the Integration Builder. the WHERE ((col2=’val2old’ Plain J2SE Adapter Engine 640 63 . </row> .. The response document contains the result of the action in XML format as follows: “ <row> <column1>value11</column1> <column2>value12</column2> ..col3 FROM dbTableName AND col4=’val4’) OR (col2=’val2old2’)) “ If there is no <key> element... If both attributes are missing. This enables you. The name of the <key> element is arbitrary. to define names for stored procedures.02. If specified.SAP Online Help 24. A statement with the action SELECT must have exactly one <access> element. SMALLINT.2004 element is interpreted as an input parameter. which describes the valid SQL data type. Instead of an XML document format. REAL. TIMESTAMP. the adapter triggers an error message (an SQL exception) concerning the SQL syntax that is generated by the database. Additionally. if the names can contain special characters (such as a “). The results within the stored procedure are returned either as a table or as the element <update_count>. STRING. TINYINT. FLOAT. TIME or TIMESTAMP. DECIMAL. DOUBLE. • db. LONGVARCHAR. INOUT).CLOB (output only). a text is expected that represents any valid SQL statement. DATE. is mandatory for all parameter types (IN. The default setting is NULL. This replacement character may be database-specific. OUT. If a character occurs that is invalid for the database being used. When inserting a line into a table the corresponding document looks as follows: „ INSERT INTO tableName (column-name1. NUMERIC. BIGINT. The return parameters of a stored procedure are attached in a separate structure. for example. All return values are returned in an XML structure.emptyStringValue=NULL|EMPTY In database fields of type STRING. this parameter defines whether empty values in the XML structure are to be interpreted as empty values (EMPTY . BINARY. BIT. CHAR.apostropheEsc=<apostropheEscapeString> The apostrophe character (‘) is a reserved character in SQL syntax and is therefore replaced by an escape character if it occurs within value strings. column-name2. The attribute type=<SQL-Datatype> .02. column names can be enclosed by a special delimiter character. ‘column-value2’. TIME.SAP Online Help 24. BLOB (output only). DATE. The parameter names must be identical to the stored procedure definition. Empty values are always interpreted as NULL values in all other parameter types. This character can be specified at this point. The default setting is no delimiter character. This depends on the SQL statements executed within the stored procedure.columnNameDelimiter=<DelimiterSign> Depending on the database being used. • db. XML Document Format for the Mode XMB2DB_RAWSQL This mode is primarily for test purposes only. If a character occurs that is invalid for the database being used. the following parameters can be specified for the SQL syntax that are used for all actions: • db. ‘column-value3’) “ Plain J2SE Adapter Engine 640 64 . The following SQL data types are supported: INTEGER. Typical characters are \’ or ’’. The default character is ’’. column-name3) VALUES(‘column-value1’. VARCHAR. the adapter triggers an error message (an SQL exception) concerning the SQL syntax that is generated by the database.a database field with length null) or as NULL values (NULL – the database field is not set). LONGVARBINARY. VARBINARY. Following processing of a message.ModuleJMS2Transport This specification is mandatory.. To configure the adapter you must specify the following: • • • • • • • The corresponding Java class General adapter settings The message type to be received The transformation class and the bindings implemented in the transformation class A dispatcher class (optional) with the corresponding settings and the user exits and their settings that are to be called by the dispatcher How to address the Integration Engine Settings specific for the respective JMS provider [Seite 80] Prerequisites You have: .2004 Configuring the Sender JMS Adapter Use You need to configure the sender JMS adapter to send JMS messages to the Integration Engine [Extern].messaging. The version specification for the configuration version=30 This specification is mandatory. Called the adapter configuration by choosing Configure. with a ROLLBACK. errorDelay The default value for this parameter is 0. Other values are not permitted and trigger an error.SAP Online Help 24. Installed [Seite 6] the corresponding adapter. If no specification is entered. This parameter determines whether a transactional JMS session should be used or not. the configuration is interpreted as an XI 2.0 adapter configuration. or in the case of an error. 1.. 3.aii.02. Procedure The configuration of the sender JMS adapter comprises six functional sub areas: . a transactional session ends either with a COMMIT. 3.. 2.. 2.sap. Java class name for the sender JMS adapter Specify the class name as follows: classname=com. 1. General adapter settings You can set the following general parameters for the sender JMS adapter: JMSSession. Plain J2SE Adapter Engine 640 65 . Selected [Seite 10] the adapter on the configuration screen.sessionTransacted=true or false The default value is true.adapter. for example. In the configuration.messaging. it can make sense to specify a certain time period. The architecture of the JMS adapter is designed so that every JMS message can be mapped to a HTTP message. XMBMessage This is an SAP-defined SOAP message with attachments that is logically based on a multipart-MIME message.sap. 4. Your JMS provider must support the registration of an ExceptionListener for this. reconnectDelay The default value for this parameter is -1. The time period must be specified in milliseconds. and the definition of the particular bindings for the message formats.sap.JMSSinglePayloadBinding Plain J2SE Adapter Engine 640 66 . On the HTTP side.adapter. specify which message type you want to send: TransportMessage. The message type to be received or sent On the JMS side.type 5.trans. the JMS adapter knows the following message types: TransportMessage This is essentially a (single or multipart) MIME message with a connection to the transport protocol (HTTP).02. The following parameter is set at runtime: JMSMessage. the JMS adapter knows the following messages: JMSMessage JMSTextMessage JMSBytesMessage JMSObjectMessage JMSStreamMessage JMSMapMessage See the corresponding documentation on JMS for more information.type=TransportMessage or XMBMessage The default value is XMBMessage.JMSTunneling com. In the configuration.SAP Online Help 24.aii. It transports an XMBMessage.adapter. This parameter controls whether and after what time period an attempt is made to reestablish the connection following a connection error on the JMS side. In transactional processing. The transformation class in which the bindings for the conversion of different message formats are implemented. because messages with errors remain in the queue following a ROLLBACK.2004 This parameter determines how long the system waits before processing further messages if an error occurs.aii. No attempt is made if the value is set to -1.messaging.trans. The following classes are supplied: com. specify the transformation class to be used under transformClass. bindings in the class JMSSinglePayloadBinding are much more specific.2004 You can define your own bindings at any point and apply them to the JMS adapter by implementing a class that enhances the class com.trans.adapter.messaging. While JMS is used by the bindings in the class JMSTunneling as a kind of means of transport. The HTTP content type is determined from the value of the parameter XI.Transform and entering this class as the transformation class.02. for example: XI.com/xi/xidemo XI. The header data of the XMBMessage is taken from the configuration.ReceiverParty=<Receiver> XI.sap.trans.aii. The HTTP content type is determined from the value of the parameter XI. The dispatcher class and the user exits to be called by the dispatcher (optional) Plain J2SE Adapter Engine 640 67 .trans. You can also specify the receiver system by using the following parameter.adapter. The message types specified in step 3 control which binding is used at runtime. They are used to identify the adapter configuration in routing [Extern] and in mapping [Extern] in the Integration Engine pipeline [Extern]. Use the classes JMSTunneling or JMSSinglePayloadBinding as templates.SAP Online Help 24. The header data of the XMBMessage is taken from the configuration.messaging.ContentType (default value: text/plain).aii. JMSBytesMessage TransportMessage The payload of a JMSBytesMessage is used as the payload of a TransportMessage.SenderInterfaceNamespace=http://sap. JMSBytesMessage XMBMessage The payload of a JMSBytesMessage is used as the payload of a XMBMessage. You can also find an explanation about each argument there.ContentType (default value: application/octet-stream).sap.messaging.adapter. XI. JMSTextMessage XMBMessage The payload of a JMSTextMessage is used as the payload of a XMBMessage. a binding is implemented for each of the following cases: JMSTextMessage JMSBytesMessage TransportMessage TransportMessage As you can see from the class name. their functions are explained in the following step: In the class com.sap. each binding is a kind of JMS tunneling.SenderParty=<Sender> XI. a binding is implemented for each of the following cases: JMSTextMessage TransportMessage The payload of a JMSTextMessage is used as the payload of a TransportMessage.JMSTunneling. In the class com.SenderService=ExtAdapterSender XI.aii.ReceiverService=ExtAdapterReceiver In this case you do not need to determine the receiver in routing. 6.JMSSinglePayloadBinding. This means that the transport message is transported to the JMS payload.SenderInterface=ExtAdapterSenderIF This address argument for the sender system is mandatory. the system will terminate each attempt to access the Integration Engine with the message Transport Exception: http-Error 401 – Unauthorized. 7. The user must have the authorizations of group SAP_XI_APPL_SERV_USER on the Integration Server. you can also set the following parameters: XI. How to address the Integration Engine Enter the complete address (URL) of the Integration Engine that you want to send the message to: XI.Language=<language-id> 8.proxyHost=<proxyHostname> XI.Client=<client-no> XI. If you do not specify a user and password combination.2004 The sender JMS adapter provides you with a dispatcher that you can use to convert messages before they are sent. If the Integration Server is accessed by means of an HTTP proxy server rather than directly.TargetURL=<fromSLD> To be able to access the System Landscape Directory. the following parameters must be set: XI.proxyPort=<proxyPortnumber> <proxyHostname> is the host name of the proxy and <proxyPortnumber> is the port where the proxy receives HTTP requests (for example. If an authentication was specified for the specified URL (HTTP service) in the Integration Engine. If you want to use a different client or language to the default setting in the Integration Engine when logging on. The settings required for the dispatcher are explained in the example [Seite 86]. Provider-specific settings Plain J2SE Adapter Engine 640 68 .Password=<password> The specifications must match those that you made in transaction SICF in the Integration Engine. specify the following: XI. 8080). Therefore.02. the following specifications are mandatory: XI.User=<user-name> XI.SLDConfiguration=SLDaccessor In this case the URL of the corresponding Integration Server for the system specified with XI.TargetURL. The Integration Engine address can also be accessed dynamically from the SAP System Landscape Directory. the SLDaccessor [Seite 19] service must be configured correspondingly and the respective entries must be maintained in the System Landscape Directory. or the combination is invalid.SAP Online Help 24.SenderService is read from the SLD and used instead of the value specified under XI.TargetURL=http://IntegrationEngineHost:port/pipelinearguments This specification is mandatory. The following entry is added to the configuration for this purpose: XI. aii.2004 For more information about provider-specific settings. This example is designed for XI 3. see Settings for the JMS Provider [Seite 80].adapter.sap.02. Uncomment for receiving JMS messages classname=com.sessionTransacted=false # # set delay in milliseconds before processing next message after an error # (default: 0) #errorDelay=10000 # # set delay in milliseconds before trying to reestablish the JMS connection # after a connection error (default: -1 (do not try to reconnect)) #reconnectDelay=10000 # #******************************************************************** ****** # # set the message formats you want to process # formats are only needed if they cannot be evaluated at runtime # Plain J2SE Adapter Engine 640 69 .ModuleJMS2Transport #******************************************************************** ****** # # set if a transacted JMS session should be used (default: true) #JMSSession. Example Below is an example configuration for the sender JMS adapter: +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ++++++ # JMS Adapter Configuration # # This configuration can be used as a template to configure the # JMS sender adapter # #******************************************************************** ****** # Set XI message protocol version.0 version=30 #******************************************************************** ****** # # JMS message receiver class.SAP Online Help 24.messaging. adapter.02.messaging.JMSSinglePayloadBi nding # # the following parameters are used in bindings that belong to # SinglePayloadBinding and require XMBHeader information # # uncomment and adjust parameters according to your requirements.SenderInterface=ExtAdapterSenderIF XI. Please # note that the Party identifier needs not to be configured in case of A2A # scenarios.trans.SenderParty=Sender XI. insert your class here for an # individual binding between JMS and TransportMessage # # uncomment the following line for using bindings that belong to Tunneling #transformClass=com.2004 # TransportMessage Type can be set to TransportMessage or XMBMessage # it is used for sending and receiving TransportMessages and XMBMessages #TransportMessage.SenderService=ExtAdapterSender # XI. # XI.com/xi/xidemo XI.LoggingLevel=1 XI.sap.SAP Online Help 24.JMSTunneling # uncomment the following line for using bindings that belong to # SinglePayloadBinding transformClass=com.QueueId=ABCDEFABCDEF XI.QualityOfService=EO XI.type=XMBMessage #******************************************************************** ****** # # uncomment and adjust parameters for Transformation Type # (binding of JMS TransportMessage).ReceiverService=ExtAdapterReceiver XI.TraceLevel=1 XI.sap.ContentType=text/xml #******************************************************************** ****** # # URL of Integration Server to send the messages to Plain J2SE Adapter Engine 640 70 .trans.ReceiverParty=Receiver XI.messaging.adapter.SenderInterfaceNamespace=http://sap.aii.aii.type=TransportMessage TransportMessage. 4=java.String #{javax.PROVIDER_URL}.services.String #{javax.InitialContext.engine.02.jclient.InitialContext.InitialContext.lang.naming.Que ueConnectionFactory JMS.Queue Plain J2SE Adapter Engine 640 71 .lang.jndi.lang.QueueConnectionFactoryImpl.classname=progress.property.INITIAL_CONTEXT_FACTORY}.2004 #******************************************************************** ****** # # uncomment and adjust parameters for loading JMS administrated objects via # JNDI # uncomment and adjust parameters if not the default context should be used #JNDI.InitialContext.property.lang.jclient. java.lang.lang.lang.String p49512:2506 JMS.classname=progress. java.String localhost:50004 #JNDI.sap.property.ser #JMS.User=XIAF XI.naming.ser #******************************************************************** ****** # # uncomment and adjust parameters for creating SonicMQ # JMS administrated objects JMS.naming.QueueConnectionFactoryImpl.FileNameQueue=SAPQueue.Context.lang.SECURITY_PRINCIPAL}.FileNameQueueConnectionFactory=SAPQueueConnectionFactory.TargetURL=http://<host>:<port>/sap/xi/engine?type=entry XI.QueueImpl.JNDILookupNameQueueConnectionFactory=jmsfactory/default/joetest #JMS.Context.InitialContextFactoryImpl #JNDI.Password=XIPASS 24.Context.String #{javax.String #{javax.JNDILookupNameQueue=jmsQueues/default/sapDemoQueue # #******************************************************************** ****** # # uncomment and adjust parameters for loading JMS administrated objects # from file system #JMS.String #com.String sap # set the Lookup Names #JMS.property.3=java.2=java. java.message.naming.String Administrator #JNDI.Context.SECURITY_CREDENTIALS}.message.lang.constructor=java.1=java.SAP Online Help XI. java. sap.logPayload=true #namespace1.processFieldNames=fromConfiguration #namespace1.ibm.CHANNEL #JMS.Service.2004 #******************************************************************** ****** # # uncomment and adjust parameters for creating WebSphereMQ # JMS administrated objects #JMS.lang.method.QueueImpl.MQQueueConne ctionFactory #JMS.QueueConnectionFactoryImpl.fieldNames=a.conversionType=SimplePlain2XML #namespace1.xml.method.lang.setTargetClient=java.MQJMS_TP_CLIENT_MQ_TCPIP} #JMS.class=com.setQueueManager=java.Plain2XMLService.ConversionDispatcher #Dispatcher.Plain2XMLService.XSLTConversion.adapter.mq.class=com.jms.constructor=java.QueueConnectionFactoryImpl.b.lang.Conv ersion #namespace1.ConversionDispatcher.adapter.1=Plain2XMLService #namespace1.QueueImpl.ibm.XSLTService.QueueImpl.2=XSLTService #namespace1.sap.method.XSLTConve rsion #namespace1.Plain2XMLService.jms.Stri ng QM_p24537 #JMS.fieldSeparator=.messaging.String SampleQ1 24.jms.namespace=namespace1 #namespace1.Plain2XMLService.mq.JMSC.adapter. #namespace1.JMSC.aii.classname=com.sap.String postcard #JMS.c #namespace1.Service.SAP Online Help JMS.aii.QueueConnectionFactoryImpl.String JAVA.xml.Integer {com.Int eger {com.QueueConnectionFactoryImpl.lang.02.constructor=java.QueueImpl.jms.xsl +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ++++++ Plain J2SE Adapter Engine 640 72 .String p24537 #JMS.XSLTFileName=Data/DemoConversi on.lang.messaging.ibm.MQQueue #JMS.lang.QueueConnectionFactoryImpl.classname= com.setTransportType=java.XSLTService.setChannel=java.messaging.class=com.setHostName=java.MQJMS_CLIENT_NONJMS_MQ} #******************************************************************** ****** # # uncomment and adjust the parameters for using a dispatcher #Dispatcher.ibm.xml.lang.Plain2XMLService.method.mq.method.xml.aii.mq. Plain J2SE Adapter Engine 640 73 .0 adapter configuration.aii. a transactional session ends either with a COMMIT. 3. Procedure The configuration of the receiver JMS adapter comprises six functional sub areas: . 1. Other values are not permitted and trigger an error. 1. 3. or in the case of an error. 2.messaging.sap.sessionTransacted=true or false The default value is true.02.ModuleTransport2JMS This specification is mandatory.2004 Configuring the Receiver JMS Adapter Use You need to configure the receiver JMS adapter to convert XML messages from the Integration Engine [Extern] into JMS messages. Chosen Configure to call the configuration of the adapter module. Selected [Seite 10] the adapter on the configuration screen.. JMS. This parameter determines whether a transactional JMS session should be used or not.adapter.MessageProducer... Installed [Seite 6] the corresponding adapter. with a ROLLBACK.DeliveryMode=PERSISTENT or NON_PERSISTENT The default value is PERSISTENT.SAP Online Help 24.. General adapter settings You can set the following general parameters for the receiver JMS adapter: JMSSession. If no specification is entered. Following processing of a message. the configuration is interpreted as an XI 2. Java class name for the receiver JMS adapter Specify the class name as follows: classname=com. To configure the adapter you must specify the following: • • • • • • • The corresponding Java class General adapter settings The message type to be received The transformation class and the bindings implemented in the transformation class A dispatcher class (optional) with the corresponding settings and the user exits and their settings that are to be called by the dispatcher How to address the Integration Engine Settings specific for the respective JMS provider [Seite 80] Prerequisites You have: . 2. The version specification for the configuration version=30 This specification is mandatory. In transactional processing. XMBMessage This is an SAP-defined SOAP message with attachments that is logically based on a multipart-MIME message. Once the period of time specified in the parameter reconnectDelay has passed. because messages with errors remain in the queue following a ROLLBACK. the free text contained there (provider-specific) is compared with the specified string. reconnectDelay The default value for this parameter is -1. On the JMS side. The architecture of the JMS adapter is designed so that every HTTP message can be mapped to a JMS message. In the configuration. it can make sense to specify a certain time period. Plain J2SE Adapter Engine 640 74 . an attempt is made to reestablish the connection. errorDelay The default value for this parameter is 0. specify which message type is to be received: TransportMessage.2004 This parameter controls the delivery mode of the JMS messages to be sent. 4. the JMS adapter knows the following message types: TransportMessage This is essentially a (single or multipart) MIME message with a connection to the transport protocol (HTTP). It transports an XMBMessage. This parameter determines how long the system waits before processing further messages if an error occurs. This parameter controls whether and after what time period an attempt is made to reestablish the connection following a connection error on the JMS side. No attempt is made if the value is set to -1. the JMS adapter knows the following messages: JMSMessage JMSTextMessage JMSBytesMessage JMSObjectMessage JMSStreamMessage JMSMapMessage See the corresponding documentation on JMS for more information. The message type to be received or sent On the HTTP side. The time period must be specified in milliseconds. If a JMSException is thrown when sending a message.SAP Online Help 24.type=TransportMessage or XMBMessage The default value is XMBMessage. for example. Your JMS provider must support the registration of an ExceptionListener for this. forceReconnectString=<string> This parameter gives you the option of forcing a reconnection if the JMS provider does not call the ExceptionListener registered by the JMS adapter when a connection error occurs in the outbound case.02. sap..02.aii. The following classes are supplied: com. In the class com. The transformation class in which the bindings for the conversion of different message formats are implemented.messaging. a binding is implemented for each of the following cases: TransportMessage TransportMessage XMBMessage XMBMessage JMSTextMessage JMSBytesMessage JMSTextMessage JMSBytesMessage As you can see from the class name.trans. This means that the TransportMessage or XMBMessage is transported in the JMS payload.messaging.aii..SAP Online Help Also specify the JMS message type to be sent: JMSMessage.Transform and entering this class as the transformation class.adapter. In the configuration.aii. Use the classes JMSTunneling or JMSSinglePayloadBinding as templates.type= TextMessage or BytesMessage The default value is JMSTextMessage.trans.messaging.messaging.adapter.aii.2004 5.adapter. Plain J2SE Adapter Engine 640 75 . The value in the HTTP header field is used to determine whether the payload of the TransportMessage is text-based: content-Type (= text/. each binding is a kind of JMS tunneling.JMSTunneling com.adapter.JMSSinglePayloadBinding. XMBMessage JMSBytesMessage The payload of a XMBMessage is used as the payload of a JMSBytesMessage.messaging. The value in the HTTP header field is used to determine whether the payload of the TransportMessage is not text-based: content-Type ( <> text/. The message types specified in step 3 control which binding is used at runtime.) TransportMessage JMSBytesMessage The payload of a TransportMessage is used as the payload of a JMSBytesMessage. their functions are explained briefly below: In the class com.. specify the transformation class to be used under transformClass. 24.adapter.JMSSinglePayloadBinding You can define your own binding at any point and apply it to the JMS adapter by implementing a class that enhances the class com. You do not need to set any further configuration parameters.trans.sap.) XMBMessage JMSTextMessage The payload of a XMBMessage is used as the payload of a JMSTextMessage. and the definition of the particular bindings for the message formats.sap. The payload type is used to determine whether the payload of the XMBMessage is text-based: The header data of the XMBMessage is ignored.aii.JMSTunneling.. The payload type is used to determine whether the payload of the XMBMessage is not text-based: The header data of the XMBMessage is ignored.sap. a binding is implemented for each of the following cases: TransportMessage JMSTextMessage The payload of a TransportMessage is used as the payload of a JMSTextMessage.trans.sap.trans. httpService=<service> <service> describes the service part of the address where the Integration Engine must send its messages.2004 While JMS is used by the bindings in the class JMSTunneling as a kind of means of transport.httpPort=1234 and XI. The dispatcher class and the user exits to be called by the dispatcher (optional) The receiver JMS adapter provides you with a dispatcher that you can use to convert messages before they are sent. 7.SAP Online Help 24. These specifications are mandatory. the end point address of the JMS adapter in the Integration Engine must be specified as follows: http://<JMSAdapterhost>:1234/JMS The end point address must be extended as follows for the Integration Engine in Release 1. XI. bindings in the class JMSSinglePayloadBinding are much more specific. Specifications for Integration Engine addressing XI. If. see Settings for the JMS Provider [Seite 80].httpPort=<port_no> <port_no> specifies the HTTP server port that receives the messages from the Integration Engine. The settings required for the dispatcher are explained in the example [Seite 86]. Example Below is an example configuration for the receiver JMS adapter: +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ++++++ # JMS Adapter Configuration # # This configuration can be used as a template to configure the # JMS receiver adapter # #******************************************************************** ****** Plain J2SE Adapter Engine 640 76 . 6. but has not been started (status STOPPED or INITIALIZED).02. 8. you have specified XI. Provider-specific settings For more information about provider-specific settings. for example. the system displays the following error message: No registered listener for <Service> found The system displays the same message if the adapter is initialized.httpService=/JMS.0: http://<JMSAdapterhost>:1234/JMS?action=execute&pipelineid= Receiver If the Integration Engine message is sent to a non-specified adapter service. 0 version=30 #******************************************************************** ****** # # JMS message sender class Uncomment for sending JMS messages classname=com.MessageProducer.aii.02.ModuleTransport2JMS #******************************************************************** ****** # # set if a transacted JMS Session should be used (default: true) #JMSSession.2004 # Set XI message protocol version.SAP Online Help 24.sessionTransacted=false # # set the delivery mode of the JMS MessageProducer (QueueSender.DeliveryMode=NON_PERSISTENT # # set delay in milliseconds before processing next message after an error # (default: 0) #errorDelay=10000 # # set delay in milliseconds before trying to reestablish the JMS connection # after a connection error (default: -1 (do not try to reconnect)) #reconnectDelay=10000 # # force reconnect (only to be used if the JMS Provider does not support the # JMSExceptionListener functionality) the reconnect is only attempted if # the JMSException message contains the forceReconnectString or if the # forceReconnectString is set to * (default: forceReconnectString is not # set -> no reconnect is attempted #forceReconnectString=MQJMS2007 #******************************************************************** ****** # # set the message formats you want to process # formats are only needed if they cannot be evaluated at runtime # Plain J2SE Adapter Engine 640 77 .adapter. This example is designed for XI 3. default: PERSISTENT) #JMS.messaging.sap. messaging.type=BytesMessage JMSMessage.type=XMBMessage #******************************************************************** ****** # # uncomment and adjust parameters for Transformation Type # (binding of JMS TransportMessage).trans.SAP Online Help # JMSMessage Type can be set to TextMessage or BytesMessage # it is only used for sending JMS messages #JMSMessage.JMSSinglePayloadBi nding # #******************************************************************** ****** # # uncomment and adjust parameters for the HTTP listener ports to wait for # XI messages XI. insert your class here for an # individual binding between JMS and TransportMessage # # uncomment the following line for using bindings that belong to Tunneling #transformClass=com.aii.messaging.02.httpPort=3333 XI.lang.adapter.String Plain J2SE Adapter Engine 640 78 .httpService=/JMS # #******************************************************************** ****** # # uncomment and adjust parameters for loading JMS administrated objects via # JNDI # uncomment and adjust parameters if not the default context should be used #JNDI.2004 # TransportMessage Type can be set to TransportMessage or XMBMessage # it is used for sending and receiving TransportMessages and XMBMessages #TransportMessage.JMSTunneling # uncomment the following line for using bindings that belong to # SinglePayloadBinding transformClass=com.sap.type=TextMessage # 24.sap.property.type=TransportMessage TransportMessage.InitialContext.aii.adapter.trans.1=java. 02.MQQueueConne ctionFactory #JMS.mq.String #{javax.constructor=java. java.constructor=java.lang.QueueImpl.lang.lang.Que ueConnectionFactory JMS.String sap # set the Lookup Names #JMS.PROVIDER_URL}.String #com.Context.setChannel=java.naming.QueueConnectionFactoryImpl.Queue JMS.jclient.Context.SECURITY_CREDENTIALS}.FileNameQueue=SAPQueue.InitialContextFactoryImpl #JNDI.INITIAL_CONTEXT_FACTORY}.String Administrator #JNDI.String JAVA.ser #JMS.lang.sap.String p24537 #JMS.String #{javax.services.classname=com. java.classname= progress.Context.method.QueueConnectionFactoryImpl. java.jndi.3=java.2004 #{javax.String localhost:50004 #JNDI.jclient.lang.lang.InitialContext.InitialContext.String #{javax.lang.String SampleQ1 #******************************************************************** ****** # # uncomment and adjust parameters for creating WebSphereMQ # JMS administrated objects #JMS.QueueImpl.SECURITY_PRINCIPAL}.setHostName=java.2=java.lang.naming.ibm. java.JNDILookupNameQueue=jmsQueues/default/sapDemoQueue #******************************************************************** ****** # # uncomment and adjust parameters for loading JMS administrated objects # from the file system #JMS.classname=progress.method.QueueConnectionFactoryImpl.engine.jms.4=java.QueueConnectionFactoryImpl.String p49512:2506 JMS.naming.message.lang.Context.property.InitialContext.FileNameQueueConnectionFactory=SAPQueueConnectionFactory.CHANNEL Plain J2SE Adapter Engine 640 79 .ser #******************************************************************** ****** # # uncomment and adjust parameters for creating SonicMQ # JMS administrated objects JMS.JNDILookupNameQueueConnectionFactory=jmsfactory/default/joetest #JMS.lang.property.property.lang.naming.QueueConnectionFactoryImpl.message.SAP Online Help 24. ibm.method.fieldNames=a.processFieldNames=fromConfiguration #namespace1.QueueImpl. provider-specific information is contained in administrated objects.xsl +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ++++++ Settings for the JMS Provider In JMS.lang.method.JMSC.MQQueue #JMS.xml.c #namespace1.method.Int eger {com. Administrated objects such as these are either loaded dynamically (for example.SAP Online Help 24. #namespace1.setTargetClient=java.FileNameQueueConnectionFactory=<path/filename> JMS.class=com.Plain2XMLService.fieldSeparator=.jms.String postcard #JMS.mq.XSLTService.setTransportType=java.messaging.mq.class=com.Plain2XMLService.aii.Plain2XMLService.lang.namespace=namespace1 #namespace1.constructor=java.adapter. Loading Objects Dynamically Existing administrable objects can be loaded from the local file system.class=com.Plain2XMLService.MQJMS_TP_CLIENT_MQ_TCPIP} #JMS.FileNameQueue=<path/filename> Plain J2SE Adapter Engine 640 80 .xml. QueueConnectionFactory and Queue are the objects relevant for the JMS adapter.QueueImpl.2004 #JMS.sap.ibm.aii.lang.ConversionDispatcher.classname= com.QueueConnectionFactoryImpl.xml.XSLTConve rsion #namespace1.XSLTFileName=Data/DemoConversi on.Service.xml.QueueImpl.JMSC.MQJMS_CLIENT_NONJMS_MQ} #******************************************************************** ****** # # uncomment and adjust parameters for using a dispatcher *** #Dispatcher.conversionType=SimplePlain2XML #namespace1.sap. The following two parameters can be used for this purpose: • • JMS.adapter.aii.Integer {com.ConversionDispatcher #Dispatcher.messaging.lang.setQueueManager=java.Plain2XMLService.QueueConnectionFactoryImpl. or generated directly .jms.b.02.ibm.sap.XSLTConversion.jms.2=XSLTService #namespace1.Conv ersion #namespace1.adapter.1=Plain2XMLService #namespace1. from the local file system or from LDAP servers by using JNDI).messaging.logPayload=true #namespace1.Service.XSLTService.mq.Stri ng QM_p24537 #JMS. QueueConnectionFactoryImpl.ibm.mq.QueueConnectionFactoryImpl. Below is a brief example of the general administration of QueueConnectionFactory and Queue using the example of SonicMQ and WebSphereMQ.constructor=java. then the following configuration entry is recommended: JMS. no provider-specific characteristics should exist in the adapter (JMS interfaces are providerindependent. for WebSphereMQ the information whether the provider should be contacted using JNI or TCP/IC (the former is the default setting.ibm.setHostName=java.Integer {com.method. but is only possible on local machines).setTransportType=java . and on the other. and how.jms.QueueImpl.MQJMS_CLIENT_NONJMS_MQ} See the documentation of your JMS provider for more information about mandatory/optional settings.QueueConnectionFactoryImpl.JMSC. for example: JMS.02.j client. you need to set a number of provider-dependent parameters or flags.lang.QueueConnectionFactoryImpl.ibm.mq.classname=com.jms.JMSC. simple way to specify provider-specific data in the configuration of the JMS adapter. if you want to send a JMS message using WebSphereMQ.Integer {com. but the receiver only supports native WebSphereMQ messages.lang. This makes the overall configuration easier and more flexible.message.method. You set the connection type TCPIP using a constant.String p49512:2506 (for WebSphereMQ) In addition.mq. administrable objects do not always already exist. while this is performed using a SetMethod for WebSphereMQ: JMS.MQQ ueueConnectionFactory (for WebSphereMQ) The provider determines which messaging parameter is set.lang . however.QueueConnectionFactory (for SonicMQ) JMS. Plain J2SE Adapter Engine 640 81 .String p49512:2506 (for SonicMQ) JMS. the provider address is set in the constructor of the QueueConnectionFactory for SonicMQ. For example.classname=progress.QueueConnectionFactoryImpl. For example. there is a additional.setTargetClient=java. For example. for example: JMS.lang.MQJMS_TP_CLIENT_MQ_TCPIP} For Queues the same applies as for QueueConnectionFactories. You select the JMS provider by specifying the implementing class of QueueConnectionFactory.jms.2004 Generating Objects Directly Since on the one hand. administrable objects are extremely provider-dependent).SAP Online Help 24.method. SAP Online Help 24.02.2004 Configuring the SOAP Adapter Use You need to configure the SOAP adapter so that you can exchange SOAP messages between the Integration Engine [Extern] and remote clients or servers of Web Services. The SOAP adapter provides a runtime environment that includes various SOAP components for the processing of SOAP messages. You can combine these SOAP components with separate components to satisfy your needs and requirements. The SOAP adapter uses a helper class to instantiate and control SOAP components. If you want to use your own SOAP processing logic you must make your helper class known to the SOAP adapter. To configure the SOAP adapter you must specify the following: • • The helper class that implements the following interface: com.sap.aii.messaging.adapter.ModuleBubbleHelper The parameter values for the specified helper class For example, you must specify the following parameters for the helper class ModuleBubbleHelperXMBWSImpl (instantiates a BubbleBag to integrate remote Web Services with the Integration Engine): Information about the Integration Engine destination (when the Integration Engine is acting as a service provider and therefore the SOAP adapter must be configured as an sender adapter). Information about the Web Service provider destination (when the Integration Engine is acting as a service client and therefore the SOAP adapter must be configured as an receiver adapter). Various options for controlling the conversion of multi-part Integration Engine SOAP messages and Web Service SOAP messages. Prerequisites You have: ... 1. Installed [Seite 6] the corresponding adapter. 2. Selected [Seite 10] the adapter on the configuration screen. 3. Called the adapter configuration by choosing Configure. Procedure The configuration of the SOAP adapter comprises two functional sub areas: ... 1. The version specification for the configuration version=30 This specification is mandatory. If no specification is entered, the configuration is interpreted as an XI 2.0 adapter configuration. Other values are not permitted and trigger an error. 2. The Java class name for the SOAP adapter Specify the class name as follows: classname=com.sap.aii.messaging.adapter.ModuleBubble This specification is mandatory. 3. The configuration parameters for the specified helper class Plain J2SE Adapter Engine 640 82 SAP Online Help 24.02.2004 Therefore, you must specify the following parameters for the shipped helper class ModuleBubbleHelperXMBWSImpl, for example: Specifications for the Integration Engine as a service provider for queries from Web Service clients (sender SOAP adapter). Specifications for the Web Service provider for queries from the Integration Engine as a Web Service client (SOAP receiver adapter). You can configure an sender adapter, or an receiver adapter, or both, if required. Configuring a Helper Class for Sender Processing ... 1. Enter the complete address (URL) of the Integration Engine that you want to send the message to: XI.TargetURL=http://IntegrationEngineHost:port/pipelinearguments This specification is mandatory when the Integration Engine is acting as a service provider. The Integration Engine address can also be accessed dynamically from the SAP System Landscape Directory. The following entry is added to the configuration for this purpose: XI.SLDConfiguration=SLDaccessor In this case the URL of the corresponding Server for the system specified with XI.SenderService is read from the SLD and used instead of the value specified under XI.TargetURL. Therefore, specify the following: XI.TargetURL=<fromSLD> To be able to access the System Landscape Directory, the SLDaccessor [Seite 19] service must be configured correspondingly and the respective entries must be maintained in the System Landscape Directory. If the Integration Server is accessed by means of an HTTP proxy server rather than directly, the following parameters must be set: XI.ProxyHost=<proxyHostname> XI.ProxyPort=<proxyPortnumber> <proxyHostname> is the host name of the proxy and <proxyPortnumber> is the port where the proxy receives HTTP requests (for example, 8080). If an authentication was specified for the URL (HTTP service) entered in the Integration Engine, use the following address: XI.TargetURL=http://<username>:<password>@IntegrationEngineHost:port/pipeline-arguments As an alternative, or if the URL is taken from the System Landscape Directory, you can also specify the logon parameters as follows: XI.User=<user-name> XI.Password=<password> The specifications must match those that you made in transaction SICF in the Integration Engine. If you do not specify a user and password combination, or the combination is invalid, the system will terminate each attempt to access the Plain J2SE Adapter Engine 640 83 SAP Online Help 24.02.2004 Integration Engine with the message Transport Exception: http-Error 401 – Unauthorized. The user must have the authorizations of group SAP_XI_APPL_SERV_USER on the Integration Server. If you want to use a different client or language to the default setting in the Integration Engine when logging on, you can also set the following parameters: XI.Client=<client-no> XI.Language=<language-id> The following address arguments are optional. If this information is not contained in the request message of a Web Service client, the specifications made here are used to identify the adapter configuration in routing [Extern] and mapping [Extern] in the Integration Engine pipeline [Extern]. You can also find an explanation about each argument there. XI.SenderParty=<sender party name> XI.SenderService=<sender service name> XI.SenderInterfaceNamespace=<namespace URI> XI.SenderInterface=<name> XI.ReceiverParty=<receiver party name> XI.ReceiverService=<receiver service name> If you specify this parameter you do not need to determine a receiver in routing. The following arguments are mandatory: XI.QualityOfService=<QualityOfService> Specifies how the Integration Engine should process a message. The following values are permitted: XI.QualityOfService=BE (Best Effort, means synchronous processing) XI.QualityOfService=EO (Exactly Once, means asynchronous processing) XI.QualityOfService=EOIO (Exactly Once in Order, means asynchronous processing using queues) You must also define a queue name for EOIO: XI.QueueId=<QueueName> This queue name is used in the Integration Engine to process messages in the same sequence that they arrived in. XI.XMLEncoding=<encoding> Specifies which XML code to use for the Integration Engine. The default value is UTF-8. 2. Specify the port number and the path for the adapter port for Web Service clients: XMBWS.WSPort=<port_no> The port number (<port_no>) specifies the HTTP server port of the adapter that contains Web Service messages. XMBWS.WSPath=<path> The path <path> describes the service part of the adapter URL that contains Web Service messages. Plain J2SE Adapter Engine 640 84 SAP Online Help 24.02.2004 Configuring a Helper Class for Receiver Processing ... 1. Enter the complete address (URL) of the Web Service provider that you want to send the message to: XMBWS.TargetURL=http://WebServiceHost:port/service-arguments This specification is mandatory when the Web Service provider is acting as a service provider. If an authentication was specified for the URL (HTTP service) entered in the Web Service provider, use the following address: XMBWS.TargetURL=http://<username>:<password>@WebServiceHost:port/ service–arguments If the Web Service provider is accessed by means of an HTTP proxy server rather than directly, the following parameters must be set: XMBWS.ProxyHost=<proxyHostname> XMBWS.ProxyPort=<proxyPortnumber> <proxyHostname> is the host name of the proxy and <proxyPortnumber> is the port where the proxy receives HTTP requests (for example, 8080). Alternatively, you can also specify the logon parameters as follows: XMBWS.User=<user-name> XMBWS.Password=<password> 2. Specify the value for SOAPAction: XMBWS.DefaultSOAPAction=<default_soap_action> <default_soap_action> species the default value for the SOAPAction in Web Service messages. XMBWS.UseSOAPAction=<use_soap_action_opt> <use_soap_action_opt> specifies the method with which the value of the SOAPAction is determined on the basis of the message instance. The only valid value is receiver. 3. Specify how the format of Web Service messages is to be controlled XMBWS.KeepHeaders=<boolean> If you specify true here, all Integration Engine message headers are copied to Web Service messages. Otherwise, all headers are deleted. Web Service message headers are always copied to Integration Engine messages. XMBWS.UseEncoded=<boolean> If you specify true here, Integration Engine message headers are coded in the http header X-XMB_WS_ENCODED. XMBWS.EncodingVersion=<2|3> Specifies which version of the XI message format to use to code the message header in the HTTP header (see XMBWS.UseEncoded). The value 2 stands for the XI 2.0 message format and the value 3 stands for the XI 3.0 message format. The default value is 3. 4. Specify the port number and the path for the adapter port for the Integration Engine: XMBWS.XMBPort=<port_no> Plain J2SE Adapter Engine 640 85 You can display the results of the individual conversion steps for test purposes by entering the following in the log file: • namespace1. • • Dispatcher. or combinations of all three. It is converted to an XML document in the JMS adapter using the functions already available and used in the file/FTP adapter. This XML document can then be processed further by an individual XSLT stylesheet. The data appears in a list separated by semi-colons.adapter. Enter the code for the Web service provider: XMBWS.class=com. Example A JMS message is sent to the Integration Server using the sender JMS adapter. or Java-based transformations either individually.02.XMLEncoding=<encoding> Specifies which XML code to use for the Web service provider.messaging.sap. The default value is UTF-8.sap. 5. This parameter is only required for the JMS adapter and is therefore specific to this example. XMBWS.ConversionDispatcher.XMBPath=<path> The path <path> describes the service part of the adapter URL that contains messages from the Integration Engine.JMSSinglePayl oadBinding You must specify this transformation class because the JMS payload only contains the data and no XI message. For example.adapter. Using the Dispatcher: Example Most of the adapters in the Adapter Engine include a dispatcher that can process a series of user exits for converting messages.ConversionDispatc her Dispatcher. The example below describes how the dispatcher can be used. this dispatcher enables you to carry out file/FTP adapter conversions.namespace=namespace1 Both these parameters activate the dispatcher function and set the namespace used to namespace1.logPayload=true namespace1 is the namespace specified above (the same applies for the parameters that follow) The file/FTP adapter conversion routines and their settings are used because of the following entries (for further information about the individual settings refer to Configuring the Sender File/FTP Adapter [Seite 26]): Plain J2SE Adapter Engine 640 86 .aii.trans. The following parameters must be set in the sender JMS adapter: • transformClass=com. XSLT transformations.messaging.SAP Online Help 24.2004 The port number (<port_no>) specifies the HTTP server port of the adapter that contains messages from the Integration Engine.aii. Plain2XMLService.fieldSeparator=.adapter. you can specify SimplePlain2XML.sap.adapter.sap.aii. • • 24.messaging. • • • • namespace1.XSLTC onversion namespace1.2=XSLTService XSLTService is also an arbitrary name.b.XSLTService. Plain J2SE Adapter Engine 640 87 .XSLTService.xml.xsl and that it is located in the subdirectory Data.class=com.SAP Online Help • namespace1. The following entries in the conversion file then produce the subsequent XSLT conversion: namespace1.2004 namespace1.xsl In this example it is assumed that the stylesheet to be used has the name DemoConversion.XSLTFileName=Data/DemoConv ersion.class=com. StructPlain2XML or SimpleXML2Plain as the value for this parameter.c namespace1.Service.XSLTConversion.processFieldNames=fromConfigurat ion namespace1.xml.02.Plain2XMLService.messaging.conversionType=SimplePlain2XML Depending on the processing mode.aii.Plain2XMLService.Service. Conversion namespace1.xml. • • namespace1.1=Plain2XMLService Plain2XMLService is an arbitrary name.xml.Plain2XMLService.fieldNames=a.Plain2XMLService.