3 Configuring Oracle Application Adapter for SAP R/3

This chapter describes how to use Oracle Adapter Application Explorer (Application Explorer) to define a target to connect to a SAP system, view system objects, and create XML schemas and Web services. This chapter also explains how to configure an event adapter.

This chapter discusses the following topics:

Starting Application Explorer
Configuring Repository Settings
Creating a Repository Configuration
Establishing a Connection (Target) for SAP R/3
Viewing Application System Objects
Creating XML Schemas
Generating WSDL (J2CA Configurations Only)
Creating and Testing a Web Service (BSE Configurations Only)
Configuring an Event Adapter

Starting Application Explorer

To start Application Explorer:

Ensure that Oracle WebLogic Server is started, which is where Application Explorer is deployed.
Start Application Explorer by clicking the Windows Start menu, selecting All Programs, Oracle Application Adapters, and clicking Application Explorer.

Description of the illustration start_app_explorer.gif

You can also start Application Explorer by executing the ae.bat file, which is located in the following directory:
```
C:\oracle\Middleware\home_0309\Oracle_SOA1\soa\thirdparty\ApplicationAdapters\tools\iwae\bin\ae.bat
```
It is a good practice to create a shortcut for the ae.bat file on your desktop.

If you are using a UNIX or Linux platform you can start Application Explorer by executing the iwae.sh file.

Application Explorer starts. You are ready to define new targets to your SAP R/3 system.

Configuring Repository Settings

You need not configure BSE for a file-based repository because it is configured during the Oracle installation.

Configuring the Database Repository for BSE

After BSE is deployed to Oracle WebLogic Server, you can configure it through the BSE configuration page. This configuration is required only when using a database repository with BSE.

Note:

Do not use a file repository for BSE in production environments.

To configure BSE:

Execute the iwse.ora SQL script on the system where the database is installed.

The iwse.ora SQL script is located in the following directory:
```
C:\oracle\Middleware\Oracle_SOA1\soa\thirdparty\ApplicationAdapters\etc
```
This script creates the required tables that are used to store the adapter configuration information in the database. These tables are used by Application Explorer and by adapters during design time and run time. It is recommended that you use the same credentials to create the database repository and also in the web.xml file for database user credentials.
```
C:\oracle\Middleware\Oracle_SOA1\soa\thirdparty\ApplicationAdapters\etc>sqlplus SQL*Plus: Release 10.1.0.2.0 - Production on Tue Dec 27 18:10:44 2005Copyright (c) 1982, 2004, Oracle.  All rights reserved. Enter user-name: scott Enter password: scott1 Connected to: Oracle Database 11g Enterprise Edition Release 11.1.1.2.0 - Production With the Partitioning, OLAP and Data Mining options SQL>@ iwse.ora
```
Open the following page in your browser:
```
http://host name:port/ibse
```
Where host name is the system where BSE is installed and port is the HTTP port for Oracle WebLogic Server.

For example,
```
http://localhost:8001/ibse
```
Note:
If you are accessing this page for the first time, it may take longer to load.
Log on when prompted.

Enter the user ID and password, for example:
- User name: weblogic
- Password: welcome1
The BSE configuration page is displayed.

Description of the illustration bse_config_11g.gif

The ojdbc14.jar file must be copied to the following directory:

C:\oracle\Middleware\Oracle_SOA1\soa\thirdparty\ApplicationAdapters\lib

Ensure that the Adapter Lib Directory parameter specifies the path to the lib directory, for example:
```
C:\oracle\Middleware\Oracle_SOA1\soa\thirdparty\ApplicationAdapters\lib
```
After you specify the path, adapters in the lib directory are available to BSE.

Note:
The Repository URL field specifies where the file system repository is located. To use a database repository, you must enter the repository connection information. For the initial verification, use a file system repository.
Click Save.

Configuring BSE System Settings

To configure BSE system settings:

Display the BSE configuration page in a browser:
```
http://host name:port/ibse/IBSEConfig
```
Where host name is the system where BSE is installed and port is the port number on which BSE is listening.

Note:
The server to which BSE is deployed must be running.

The BSE settings pane is displayed, as shown in the following image.

Description of the illustration ibse_config_page11g.gif

Configure the system settings.

The following table lists the parameters with descriptions of the information to provide.

Parameter	Description
Language	Specify the required language.
Adapter Lib Directory	Enter the full path to the directory where the adapter jar files reside.
Encoding	Only UTF-8 is supported.
Debug Level	Specify the debug level from the following options: None Fatal Error Warning Info Debug
Number of Async. Processors	Select the number of asynchronous processors.

The following image shows all fields and check boxes for the Repository pane.

Description of the illustration ibse_config_repos_loc11g.gif

Configure the repository settings.

BSE requires a repository to store transactions and metadata required for the delivery of Web services.

See "Configuring a File System Repository" for more information.

The following table lists the parameters with descriptions of the information to provide.

Parameter	Description
Repository Type	Select a repository from the list: Oracle File (Do not use for BSE in production environments.)
Repository URL	Enter the JDBC URL to use when opening a connection to the database. For example, the following repository URL format is used when connecting to Oracle: jdbc:oracle:thin:@host name:port;SID
Repository Driver	Provide the JDBC driver class to use when opening a connection to the database (optional). For example, the following repository driver format is used when connecting to Oracle: oracle.jdbc.driver.OracleDriver
Repository User	Enter a valid user ID to use when opening a connection to the database.
Repository Password	Enter a valid password that is associated with the user ID.
Repository Pooling	If selected, repository pooling is used. This option is disabled by default.

Click Save.

Configuring a File System Repository

If you do not have access to a database for the repository, you can store repository information in an XML file on your local system. However, a file system repository is less secure and efficient than a database repository. When BSE is first installed, it is automatically configured to use a file system repository.

Note:

Do not use a file repository for BSE in production environments.

The default location for the repository on Windows is:

C:\oracle\Middleware\user_projects\domains\base_domain\servers\soa_server1\stage\ibse\ibse.war

On other platforms, use the corresponding location.

If you are using a file system repository, you are not required to configure any additional BSE components.

Configuring the Database Repository for J2CA

This section describes how to configure the database repository for J2CA.

Execute the iwse.ora SQL script on the system where the database is installed.

The iwse.ora SQL script is located in the following directory:
```
C:\oracle\Middleware\Oracle_SOA1\soa\thirdparty\ApplicationAdapters\etc
```
This script creates the required tables that are used to store the adapter configuration information in the database. These tables are used by Application Explorer and by adapters during design time and run time. It is recommended that you use the same credentials to create the database repository and also in the ra.xml file for database user credentials.
```
C:\oracle\Middleware\Oracle_SOA1\soa\thirdparty\ApplicationAdapters\etc>sqlplus SQL*Plus: Release 10.1.0.2.0 - Production on Tue Dec 27 18:10:44 2005Copyright (c) 1982, 2004, Oracle.  All rights reserved. Enter user-name: scott Enter password: scott1 Connected to: Oracle Database 11g Enterprise Edition Release 11.1.1.2.0 - Production With the Partitioning, OLAP and Data Mining options SQL>@ iwse.ora
```
Create the jcatransport.properties file and save it in the following directory:
```
C:\oracle\Middleware\Oracle_SOA1\soa\thirdparty\ApplicationAdapters\config\J2CA_SampleConfig
```
Note:
The jcatransport.properties file is required for each J2CA configuration that is created using Application Explorer. The J2CA configuration folder, for example, J2CA_SampleConfig, is named according to the configuration name that is specified in Application Explorer.

Enter values for iwafjca.repo.url, iwafjca.repo.user and iwafjca.repo.password fields in the newly created jcatransport.properties file, as shown in the following example:

iwafjca.repo.url=jdbc:oracle:thin:@90.0.0.51:1521:orcl

iwafjca.repo.user=scott

iwafjca.repo.password=scott1

The following table lists the parameters with descriptions of the information to provide.

Parameter	Description
iwafjca.repo.url	Specify the JDBC URL to use when opening a connection to the database. For example, the following repository URL format is used when connecting to Oracle: jdbc:oracle:thin:@host name:port;SID
iwafjca.repo.user	Specify a valid user ID to use when opening a connection to the database.
iwafjca.repo.password	Specify a valid password that is associated with the user ID.

The ojdbc14.jar file must be copied to the following directory:

C:\oracle\Middleware\Oracle_SOA1\soa\thirdparty\ApplicationAdapters\lib

Navigate to the following directory:

C:\oracle\Middleware\Oracle_SOA1\soa\thirdparty\ApplicationAdapters\iwafjca.rar\META-INF

Open the ra.xml file in a text editor.
Provide the JDBC connection information as a value for the IWAYRepo_URL property.
Provide a valid user name for the IWAYRepo_User property.
Provide a valid password for the IWAYRepo_Password property.
Save your changes to the ra.xml file.

Password Encryption

When creating J2CA configurations, you can also encrypt a password using Application Explorer and use this value in the jcatransport.properties and ra.xml files for added security.

Configuring Password Encryption

To encrypt a password:

Open Application Explorer.
Click Help and select Encryption.

The Encryption dialog is displayed.
Type a password in the Password field and click OK.

An encrypted version of the password displays in the Encryption field.
Copy the password.
In the jcatransport.properties file, which is used during design time, replace the existing password with the encrypted value only if you are using a database repository.

The following is a sample of the jcatransport.properties file where the password is replaced:
```
iwafjca.log.level=DEBUGiwafjca.repo.url=jdbc:oracle:thin:@172.30.166.100:1521:orcliwafjca.repo.user=scottiwafjca.repo.password=ENCR (318931973183297321831293164323332123227)
```
In the ra.xml file, which is used during run time, replace the existing password with the encrypted value for the IWayRepoPassword element. This is applicable for file system and database repositories.
Restart the Oracle WebLogic Server.

Creating a Repository Configuration

Before you use Application Explorer with Oracle Application Adapter for SAP R/3, you must create a repository configuration. You can create two kinds of repository configurations, Web services and J2CA, depending on the container to which the adapter is deployed.

During design time, the repository is used to store metadata created when using Application Explorer to configure adapter connections, browse EIS objects, configure services, and configure listeners to listen for EIS events. The information in the repository is also referenced at run-time.

Web services and BSE refer to the same type of deployment. See "Adapter Features" for more information.

Creating a Configuration for BSE

To create a configuration for BSE using Application Explorer, you must first define a new configuration.

Defining a New Configuration for BSE

To define a new configuration for BSE:

Start the Application Explorer.
Right-click Configurations and select New.

The New Configuration dialog is displayed.
Enter a name for the new configuration, for example, SampleConfig, and click OK.

Description of the illustration app_exp_new_config_type.gif
From the Service Provider list, select iBSE.
In the iBSE URL field, accept the default URL or replace it with a different URL with the following format:
```
http://host name:port/ibse/IBSEServlet
```
Where host name is the system on which Oracle WebLogic Server resides and port is the HTTP port number of the managed Oracle WebLogic server (for example, soa_server1).
Click OK.

A node representing the new configuration appears beneath the root Configurations node.

Description of the illustration sampleconfig.gif

Creating a Configuration for J2CA

To create a configuration for Oracle Adapter J2CA using Application Explorer, you must first define a new configuration.

Defining a New Configuration for J2CA

To define a new configuration for J2CA:

Start the Application Explorer.
Right-click Configurations and select New.

The New Configuration dialog is displayed.
Enter a name for the new configuration, for example, SampleConfig, and click OK.

Description of the illustration jcaconfig_11g.gif
From the Service Provider list, select JCA.
Click OK.

A node representing the new configuration appears beneath the root Configurations node.

Description of the illustration sampleconfig.gif

The Oracle Adapter J2CA configuration file is stored in:
```
C:\oracle\Middleware\Oracle_SOA1\soa\thirdparty\ApplicationAdapters\config\configuration_name
```
Where configuration_name is the name of the configuration you created (for example, SampleConfig).

HTTP Repository Connection

J2CA users can create an HTTP repository connection, which enables them to generate and store WSDL documents remotely. Perform the following steps to create an HTTP repository connection in Application Explorer. To use the HTTP repository, ensure that the iwjcaivp test tool(jca-app-adapter-test) is successfully deployed and running.

Start the Application Explorer.
Right-click the Configurations node in the left pane and select New.

The New Configuration dialog opens.
Type a name for the configuration and click OK.
Select JCA from the Service Provider list box and enter an HTTP target value in the Home field.

Use the following format for the HTTP target value:
```
http://host name:port/iwafjca/JCAServlet
```
For example:
```
http://iwserv14:7777/iwafjca/JCAServlet
```
Click OK.

The new HTTP repository connection is added to the Configurations node.

Once you connect to the remote server, you can create new Adapter targets, generate WSDL documents, and store them in the remote server.

Note: When you configure an Adapter target with the J2CA HTTP repository, you are not required to restart the Oracle WebLogic Server for run time purposes.

Connecting to a BSE or J2CA Configuration

To connect to a new configuration:

Right-click the configuration to which you want to connect, for example, SampleConfig.
Select Connect.

Nodes appear for Adapters, Events, and Business Services (also known as Web services). The Business Services node is only available for BSE configurations. If you are connected to a J2CA configuration, the Business Services node is not shown.

Events are not applicable when using a BSE configuration. You can configure events using a J2CA configuration only. As a result, you can disregard the Events node that appears for a BSE configuration.

The following is an example of a BSE configuration named SampleConfig:

Description of the illustration new_config.gif

Use the Adapters folder to create inbound interaction with SAP R/3. For example, you use the SAP node in the Adapters folder to configure a service that updates SAP R/3.
Use the Events folder to configure listeners that listen for events in SAP R/3.
Use the Business Services folder (available for BSE configurations only) to test Web services created in the Adapters folder. You can also control security settings for the Web services by using the security features of the Business Services folder.

You can now define new targets to SAP R/3.

Establishing a Connection (Target) for SAP R/3

Defining the application includes adding a target for Oracle Application Adapter for SAP R/3. Setting up the target in Application Explorer requires information that is specific to the target.

To browse the available business functions, you must first define a target to SAP R/3. After you define the target, it is automatically saved. You must connect to the SAP R/3 system every time you start Application Explorer or after you disconnect.

When you launch Application Explorer, the left pane displays (as nodes) the application systems supported by Application Explorer, based on the adapters that are installed.

Defining a Target to SAP R/3

To connect to SAP R/3 for the first time, you must define a new target. Oracle Application Adapter for SAP R/3 supports SAP R/3 standard security and the additional protocol of SNC. Once connected to the SAP R/3 application server, application security is managed by user ID, roles and profiles. For more information on SAP application security, see the appropriate SAP documentation.

When you are working with a J2CA configuration, creating, updating, and deleting a target requires you to restart the application server. The application server must also be restarted after you create a target, connect to a target, and generate a WSDL for a SAP R/3 business object. In addition, ensure to close Application Explorer before you restart the application server.

To define a target:

In the left pane, expand the Adapters node.

The application systems supported by Application Explorer appear as nodes based on the adapters that are installed.

Description of the illustration adapterexpandedpartial.gif
Right-click the MySAP node and select Add Target.

Description of the illustration addtarget.gif

The Add Target dialog is displayed. Provide the following information:
1. In the Name field, enter a descriptive name, for example, SAPTarget.
2. In the Description field, enter a description for the target (optional).
3. From the Type list, select the type of target you are connecting to. The supported target types include Message Server or Application Server (default).
  
  Note:
  For load balancing purposes, application servers from one SAP R/3 system are usually configured in logon groups, where each group serves a particular kind of user. The application servers in each group are assigned to users by a least-heavily-loaded strategy. This load balancing is done by message servers. Each SAP R/3 system has exactly one message server, which can be reached through TCP on a specific message server port.
Click OK.

The Application Server dialog is displayed.

Description of the illustration addtarget_dialogbox.gif

The following tabs are available:
- User (Required)
- System (Required)
- Advanced
- Security

For the User tab (required), enter the appropriate information for your SAP R/3 target based on the information in the following table.

Table 3-1 User Tab Parameters

Target Parameter	Description
Client	The client number defined for the SAP R/3 application for client communications.
User	A valid user ID for the SAP R/3 application.
Password	A valid password for the SAP R/3 application.
Language	A language key. EN (English) is the default.
Codepage	A character code page value.
Authentication Mode	The authentication mode you want to use when connecting to your SAP R/3 system. By default, Password is selected from the drop-down list.

For more information, see your SAP R/3 system documentation.

For the System tab (required), enter the appropriate information for your SAP R/3 target based on the information in this section.

Description of the illustration system_tab.gif

The System tab enables you to provide the application server name, system number, and connection pooling information for the SAP R/3 system to which you are connecting.

Table 3-2 System Tab Parameters

Target Parameter	Description
Application Server	The host name or IP address for the system that is hosting the SAP R/3 application.
System number	The system number defined to SAP R/3 for client communications.
Connection pool name	The name of your SAP R/3 connection pool. A default value, p1, is provided.
Connection pool size	The number of client connections in a pool you want to make available to SAP R/3 for Web service calls. A default connection pool size of 2 is available by default. Important: The default value of 1 does not create a connection pool. Instead, a single SAP R/3connection with sequential processing is shared. A pooled connection invokes multiple connections to SAP R/3 with parallel processing. If you are using Application Explorer to create Web services, the connection pool size value is used by your Web service during run-time. As a result, ensure that the connection pool size is sufficient for your purposes.
Connection timeout(min)	The timeout value for your connection pool in minutes. The default value is 10 minutes.
Connection wait time(sec)	The wait time for your connection poolin seconds. The default value is 30 seconds. Connections to an ERP server take up valuable resources on both the client and the remote server. You can create a pool of connections to minimize the resource and time constraints. In estimating the size of the pool, you may calculate pool size by the amount of server resources to be consumed, the number and size of the documents to be received, and the size of your Java Virtual Machine. The section of SAP documentation “Memory Management (BC-CST-MM)” explains in detail the resources required on the SAP R/3 system.

For the Advanced tab (optional), enter the appropriate information for your SAP R/3 target based on the information in this section.

The Advanced tab enables you to specify your EDI and IDoc versions, and configure error handling.

Description of the illustration advanced_tab.gif

Table 3-3 Advanced Tab Parameters

Target Parameter	Description
Edi version	The Electronic Data Interchange (EDI) document version you are using with the adapter. Version 3 is the default value.
IDOC release	The IDOC versioning you want to use for your connection.
IDOC release provider	The IDOC release provider for your connection. Select IDOC DOCREL field (default), SAP release, or user input from the drop-down list.
Error Handling	From the list In the event of an exception, you can select Creates Error Document or Throws Exception. To receive more detailed error messages, select Creates Error Document. As a rule: If your application is Java centric, select Throws Exception so that code components can catch the exception and react accordingly. If your application is document based, select Creates Document to create an XML document that contains the Java exception. It is up to your application to read the XML document and obtain the error.
Commit with Wait	If a high degree of accuracy is required in your application, select the Commit with Wait check box. The adapter waits until all records are physically written to the database before returning from the function call. The “Commit With Wait” has a performance impact on adapter performance, so consider carefully before selecting it. For more information about the commit behavior of BAPIs, see the SAP documentation under “BAPI Programming Guide and Reference (CA-BFA).” All SAP Business Objects that change data must commit work to the database. Some BAPIs developed in version 3.1 of the R/3 system use an internal commit behavior, and their commit behavior cannot be changed by the adapter. As soon as they are called, they commit the work they did. BAPIs developed since release 3.1 use the external commit method. The adapter issues a commit command, and the commit is put in the database queue. If there is an application error in the first part of the commit, the error message “Posting could not be carried out” is returned, and the adapter rolls back the transaction. If in writing to the database, a database error occurs, a short dump is issued in the database records of SAP, but no message is returned to the adapter about the failure. This option is disabled by default.
SAP trace	Select this option to enable SAP traces. The SAP traces are stored in the following locations during design time and run time: Design Time: C:\oracle\Middleware\home_GA\Oracle_SOA1\soa\thirdparty\ApplicationAdapters\tools\iwae\bin Run Time: C:\oracle\Middleware\home_GA\user_projects\domains\base_domain The file name formats that are used for the SAP traces are as follows (for design time and run time): rfc02664_04332.trc JCO100226_043846994.trc

For the Security tab (optional), enter the appropriate information for your SAP R/3 target based on the information in this section.

Description of the illustration security_tab.gif

The Security tab enables you to specify Secure Network Communication (SNC) information for the SAP R/3 system to which you are connecting.

Table 3-4 Security Tab Parameters

Target Parameter	Description
SNC mode	By default, SNC is disabled. To enable SNC, select 1 from the list.
SNC partner	Enter the name of the RFC server or message server (load balancing) that provides the SNC services.
SNC level	From the list select the version of the SNC library.
SNC name	Enter the name of the SNC library you are using.
SNC library path	Enter the path to the SNC library.

SNC provides protection for the communication links between the distributed components of an SAP R/3 system. Using SNC, SAP R/3 can support products that adhere to the GSS-API Version 2 standard. SNC supports application level (end-to-end security), Smartcard authentication, and single sign-on.

If you are using SAP Enterprise Portal, the J2EE engine generates the SAP logon ticket automatically. A possible SNC scenario would be from SAP Enterprise Portal to Oracle Application Adapter for SAP R/3.

If you want to use SAP logon tickets to enable single sign-on to non-SAP components, consult the SAP documentation regarding Pluggable Authentication Services. A possible SNC scenario in this case would be from a non-SAP Enterprise Portal to Oracle Application Adapter for SAP R/3.

When you have provided all the required information for your target, click OK.

After the extraction finishes, the new target, SAPTarget, appears under the MySAP adapter node.

Description of the illustration connect1.gif

You can now connect to your SAP R/3 target.

See "Creating XML Schemas" for information on how to create schemas for the adapter.

Connecting to a Defined SAP R/3 Target

To connect to an existing target:

In the left pane, expand the Adapters node.
Expand the MySAP node.
Click the target name under the MySAP node (for example, SAPTarget).

The Connection dialog displays the values you entered for connection parameters.
Verify your connection parameters.
Provide the correct password.
Right-click the target name and select Connect.

The x icon disappears, indicating that the node is connected.

Description of the illustration saptarget2.gif

Managing a Connection to SAP R/3

To manage SAP R/3 connections, you can:

Disconnect from a connection that is not currently in use.

Although you can maintain multiple open connections to different transaction processing systems, it is recommended to disconnect from connections not in use.
Edit a target.

You can modify the connection parameters when your system properties change. After you disconnect, you can modify an existing target.
Delete a connection that is no longer needed.

Disconnecting from a Connection to SAP R/3

To disconnect a target:

Expand the Adapters node.
Expand the MySAP node.
Right-click the target to which you are connected, for example, SAPTarget, and select Disconnect.

Description of the illustration disconnecting_fromtarget.gif

Disconnecting from the SAP R/3 target drops the connection with SAP R/3, but the node remains.The x icon appears, indicating that the node is disconnected.

Description of the illustration disconnected_target.gif

Modifying Connection Parameters

After you create a target for SAP R/3 using Application Explorer, you can edit any of the information that you provided previously.

To edit a target:

Verify that the target you want to edit is disconnected.
Right-click the target and select Edit.

Description of the illustration edit_target.gif

The Application Server dialog displays the target connection information.
Change the properties in the dialog as required and click OK.

Deleting a Connection to SAP R/3

You can delete a connection, rather than just disconnecting and closing it. When you delete the connection, the node disappears from the list of SAP R/3 connections in the left pane of Application Explorer.

When you delete a connection, you must restart the Oracle WebLogic Server to update the repository for run time purposes.

To delete a connection to SAP R/3:

Locate the target you want to delete.
Right-click the target (for example, SAPTarget), and select Delete.

Description of the illustration deleting_target.gif

The node disappears from the list of available connections.

Viewing Application System Objects

As you connect to SAP R/3, Application Explorer enables you to explore and browse SAP R/3 business objects that are used to support existing business processes.

Note:

Depending on the release or service pack installed, certain RFCs, for example, RFC_CUSTOMER_GET, may not exist in your particular SAP R/3 system. Therefore, the examples included in this documentation may not be relevant to your system. If this is the case, you should use the examples as a general reference for adapter functionality and choose an RFC that exists within your SAP R/3 application environment.As described in SAP Release Note 109533, SAP Function Modules (RFCs) can be delivered with different release statuses. SAP supports only RFCs that are awarded the Released for Customer status. There is no claim to the release independencies of the interfaces and the continued existence/functionality of the modules. For more information on the status of a specific function module, consult your SAP Service Marketplace.

See the SAP R/3 User's Guide for more information.

Creating XML Schemas

After you explore the SAP R/3 business function library and select an object, you can use Application Explorer to create the XML request schema and the XML response schema for that function.

To create request and response schemas for a SAP R/3 business function.

Connect to a SAP R/3 target as described in "Connecting to a Defined SAP R/3 Target".
Expand the Business Object Repository node.
Click the icon to the left of the Financial Accounting node.
Scroll down and click the icon to the left of the CompanyCode business object.
Scroll down and select the BAPI named GetDetail.

The following screen appears on the right.

Description of the illustration schema1.gif
To view the XML for each schema type, click the appropriate tab.

Generating WSDL (J2CA Configurations Only)

The Web Service Definition Language (WSDL) description of a service enables you to make the service available to other services within a host server. You use Application Explorer to create both request-response (outbound) and event notification (inbound) J2CA services of the adapter.

Note:

The Create Inbound JCA Service (Event) option is only available when the selected node supports events.

To generate a WSDL file for request-response service:

After you create a schema, right-click the respective object.

The following menu is displayed:

Description of the illustration bpel_40_11g.gif
Select Create Outbound JCA Service (Request/Response).

The Export WSDL dialog is displayed.

Description of the illustration bpel_41_11g.gif
Accept the default name for the file.

The .wsdl file extension is added automatically. By default, the names of WSDL files generated for request-response services end with _invoke, while those generated for event notification end with _receive.
Click OK.

The WSDL file is saved in the specified location.

The procedure for generating WSDL for event notification is similar to request-response. To generate WSDL for event notification, you must first create a channel for every event. See "Generating WSDL for Event Integration" for a detailed example.

Creating and Testing a Web Service (BSE Configurations Only)

Using Application Explorer, you can explore the business function repository and generate Web services (also known as a business service) for the SAP R/3 functions you want to use with the adapter. The following procedure uses the SAP R/3 BAPI method called BAPI_MATERIAL_GETLIST as an example and returns a list of materials from SAP R/3.

Note:

In a J2EE Connector Architecture (J2CA) implementation of the adapter, Web services are not available. When the adapter is deployed to use the Oracle Adapter J2CA, the Common Client Interface provides integration services using the adapter.

Creating a Web Service

To create a Web service for a SAP R/3 business function:

Connect to your SAP R/3 target and expand the Business Object Repository node.
Select the BAPI_MATERIAL_GETLIST method from the Business Object Repository.
Right-click the node from which you want to create a business service and select Create Web Service.

The Create Web Service dialog is displayed. You can add the business function as a method for a new Web service or as a method for an existing one.

Description of the illustration create_webservice_2.gif

Perform the following steps:
- 1. From the Existing Service Names list, select either <new service> or an existing service.
  2. If you are creating a new service, specify a service name. This name identifies the Web service in the list of services under the Business Services node.
  3. Enter a brief description for the service (optional).
Click Next.

The License and Method dialog is displayed.

Provide the following information:
1. In the License Name field, select one or more license codes to assign to the Web service. To make multiple selections, press the Ctrl key and click the licenses.
2. In the Method Name field, enter a descriptive name for the method.
3. In the Method Description field, enter a brief description of the method.
4. In the DTD Directory field, specify the location of the DTD you want to use.
Click OK.

Application Explorer switches the view to the Business Services node, and the new Web service appears in the left pane.

Testing a Web Service

After a Web service is created, you can test it to ensure it functions properly. A test tool is provided for testing the Web service.

To test a Web service:

Click the Business Services node to access your Web services.
Expand the Services node.
Select the name of the business service you want to test.

The business service name appears as a link in the right pane.
In the right pane, click the named business services link.

The test option appears in a separate BSE Servlet page. If you are testing a Web service that requires XML input, an input field appears.
Enter the appropriate input.
Click Invoke.

The BSE Servlet page displays the results.

Identity Propagation

If you test or run a Web service using a third party XML editor, the Username and Password values that you specify in the SOAP header must be valid and are used to connect to SAP R/3. The user name and password values that you provided for SAP R/3 during target creation using Application Explorer are overwritten for this Web service request. The following is a sample SOAP header that is included in the WSDL file for a Web service:

<SOAP-ENV:Header>
  <m:ibsinfo xmlns:m="urn:schemas-iwaysoftware-com:iwse">
    <m:service>String</m:service>
    <m:method>String</m:method>
    <m:license>String</m:license>
    <m:disposition>String</m:disposition>
    <m:Username>String</m:Username>
    <m:Password>String</m:Password>
    <m:language>String</m:language>
  </m:ibsinfo>
</SOAP-ENV:Header>

You can remove the <m:disposition> and <m:language> tags from the SOAP header, since they are not required.

Oracle ERP Adapter WSDL Definition Limitations

This section describes certain limitations with WSDL definitions that are generated by Oracle ERP Adapters, and provides workarounds where applicable.

Qualified/Unqualified Options

The qualified and unqualified options are not enforced by the Oracle ERP Adapter when WSDL definition are generated. For example:

Export a WSDL with the qualified option specified.
Create a Web service based on this WSDL.
Send XML data that contains unqualified elements to this Web service.

A correct response document is received.

Namespaces

Namespaces that are defined in the generated WSDL definition are not enforced by the Oracle ERP Adapter. For example:

Create a Web service based on a generated WSDL.
Send XML data where all namespaces have been removed to this Web service.

A correct response document is received.

Unchecked Data

The Oracle ERP Adapter does not verify if XML data conforms to the generated WSDL definition. For demonstration purposes only, the following example uses SAP R/3:

Create a Web service for the RFC_SYSTEM_INFO function module.
Invoke this Web service (RFC_SYSTEM_INFO) with XML data pertaining to BAPI_COMPANYCODE_GETLIST.

A response document is received with data for BAPI_COMPANYCODE_GETLIST.

This behavior should be taken into consideration when designing an application using Oracle ERP Adapters. As a best practice, always validate the XML data that is received according to the WSDL definition before a Web service is invoked. Otherwise, all functions can be exposed on a system (for example, SAP R/3) if only one function is called. In this example, only the RFC_SYSTEM_INFO function module was called, but an end-user could have invoked any function on SAP R/3 using this function. Only a valid XML document that is recognized by the Oracle ERP Adapter for a given function is required.

Configuring an Event Adapter

Events are generated by activity in a database or in an application system. You can use events to trigger an action in your application. For example, an update to a database can reflect an update to customer information. If your application must perform when this happens, your application is a consumer of this event.After you create a connection to your application system, you can add events using Application Explorer. To create an event, you must create a channel.

Note:

If you are using a J2CA configuration, you must create a new channel for every different event object and select this channel when creating an inbound service. Creating a channel is required for J2CA configurations only. In addition, each channel must be associated with a unique SAP R/3 Program ID. For example, if you are working with MATMAS and DEBMAS, then two separate channels are required for each object and two unique SAP R/3 Program IDs.

A channel represents configured connections to particular instances of back-end systems. See "Creating and Editing a Channel" for more information.

Creating and Editing a Channel

The following procedure describes how to create a channel for your event. All defined event ports must be associated with a channel.

When you create, modify, or delete a channel, you must restart the Oracle WebLogic Server to recognize the change and update the repository for run time purposes.

Note:

Channels can be configured and started only on the system where the Oracle Application Adapter for SAP R/3 is installed. Configuring and starting a channel for a remote host is not supported.

Events are not applicable when using a BSE configuration. You can configure events using a J2CA configuration only.

Creating and updating a channel requires you to restart the application server. The application server must also be restarted after you create a channel and generate an inbound WSDL. In addition, ensure to close Application Explorer before you restart the application server.

Creating a Channel

To create a channel:

Click the Events node.

Description of the illustration adapterexpandedpartial2.gif
Expand the MySAP node.

The ports and channels nodes appear in the left pane.
Right-click Channels and select Add Channel.

The Add Channel dialog is displayed.

Description of the illustration addchanneldialog2.gif

Perform the following steps:
1. 1. Enter a name for the channel, for example, TEST_CHANNEL.
  2. Enter a brief description.
  3. From the Protocol list, select Application Server - mySAP or Message Server - mySAP.
Click Next.

The Message Server dialog is displayed. The following tabs are available:
- User (Required)
- System (Required)
- Security
- Advanced

For the User tab, enter the appropriate information for your SAP R/3 channel based on the information in the following table.

Table 3-5 User Tab Parameters

Target Parameter	Description
Client	The client number defined for the SAP application for client communications.
User	A valid user ID for the SAP application.
Password	A valid password for the SAP application.
Authentication Mode	The authentication mode you want to use when connecting to your SAP R/3 system. By default, Password is selected from the drop-down list.

For the System tab, enter the appropriate information for your SAP R/3 channel based on the information in the following table.

Table 3-6 System Tab Parameters

Target Parameter	Description
Gateway host	A host name for the SAP R/3 Gateway.
Gateway service	A service for the SAP R/3 Gateway.
Program ID of the server	A SAP R/3 program ID you want to use for this channel.
Application Server	A host name for the application server.
System Number	The system number defined to SAP R/3 for client communications.

For the Security tab (optional), enter the appropriate information for your SAP R/3 channel based on the information in the following table.

Table 3-7 Security Tab Parameters

Target Parameter	Description
SNC mode	By default, SNC is disabled. To enable SNC, select 1 from the list.
SNC partner	Enter the name of the RFC server or message server (load balancing) that provides the SNC services.
SNC level	From the list select the version of the SNC library.
SNC name	Enter the name of the SNC library you are using.
SNC library path	Enter the path to the SNC library.

For the Advanced tab (optional), enter the appropriate information for your SAP R/3 channel based on the information in the following table.

Table 3-8 Advanced Tab Parameters

Target Parameter	Description
IDOC Format	Select an IDOC type from the list: XML (default) XML-CDATA-ENVELOPED NATIVE IDOC
IDOC release	The IDOC versioning you want to use for your connection.
IDOC release provider	The IDOC release provider for your connection. Select IDOC DOCREL field (default), SAP release, or user input from the drop-down list.
SAP trace	Select this option to enable SAP traces. The SAP traces are stored in the following locations during design time and run time: Design Time: C:\oracle\Middleware\home_GA\Oracle_SOA1\soa\thirdparty\ApplicationAdapters\tools\iwae\bin Run Time: C:\oracle\Middleware\home_GA\user_projects\domains\base_domain The file name formats that are used for the SAP traces are as follows (for design time and run time): rfc02664_04332.trc JCO100226_043846994.trc
Processing Mode	Select the type of synchronous processing from the list. Possible values include REQUEST and REQUEST_RESPONSE.

Click OK.

The channel appears under the channels node in the left pane.

Description of the illustration sapchannel4.gif

An X over the icon indicates that the channel is currently disconnected. You must start the channel to activate your event configuration.

Note:
If you are planning to integrate Oracle Application Adapter for SAP R/3 with BPEL inbound or Mediator inbound process components, do not start the channel. The channel is managed by the run-time server after the BPEL or Mediator process component is deployed. If you start the channel from Application Explorer for testing and debugging purposes, stop it before run-time (when working with BPEL or Mediator process components).
Right-click the channels node and select Start.

The channel you created becomes active.

Description of the illustration sapchannel5.gif

The X over the icon disappears.
To stop the channel, right-click the connected channel node and select Stop.

The channel becomes inactive and an X appears over the icon.

Editing a Channel

To edit a channel:

In the left pane, locate the channel you want to edit.
Right-click the channel and select Edit.

The Edit Channel pane is displayed.
Make the required changes to the channel configuration and click Finish.

When you edit a channel, you must restart the Oracle WebLogic Server to recognize the change and update the repository for run time purposes.

Deleting a Channel

To delete a channel:

In the left pane, locate the channel you want to delete.
Right-click the channel and select Delete.

The channel disappears from the list in the left pane.

When you delete a channel, you must restart the Oracle WebLogic Server to recognize the change and update the repository for run time purposes.

Schema Validation

Root validation, namespace validation, and schema validation for inbound processing (events) are supported for the Oracle Application Adapter for SAP R/3 with BPEL 11.1.1.

To validate inbound processing using the Oracle Application Adapter for SAP R/3, perform the following steps. This procedure uses MATMAS (Material Master) as an example for inbound processing.

Start Application Explorer.
Connect to the MySAP target.
Expand the IDOCs node.
Verify that you created a channel for the MySAP adapter.
Select and expand the MATMAS – Material Master node.
Right-click MATMAS01 select Create Inbound JCA Service (event).

The Export WSDL dialog opens and includes three check boxes for Root, Namespace, and Schema validation.

Description of the illustration export_wsdl_inbound.gif
- Selection of multiple validation options is allowed.
- Root validation is used to validate the root element in the inbound XML document.
- Namespace validation is used to validate the namespace in the inbound XML document.
- Schema validation is used to validate the inbound XML document with the schema in the WSDL document.
- During run time, validation is processed based on the validation options that are selected.
- If multiple validation option is selected, during run time if the first validation option fails, the remaining validation options are not processed.
- Root and namespace validations are considered modest levels of validation. Schema validation is a stricter validation level.
- It is recommended to use root and namespace validation options, unless the root element and namespace are different between the IDOCs in the SAP environment.
Generate the WSDL document and create the BPEL process.
Trigger the transactions (IDOCs) from the SAP GUI.

Inbound transactions that fail for the validation are shown in the SAP Transaction Monitor (SM58).

The status text field shows "java.lang.exception" for the documents that have failed the validation process.