This topic describes the SAP extension.
- 1.0 Installation notes
- 2.0 Configuration Requirements
- 3.0 Getting started and using the object browser
- 4.0 Communicating with an SAP system
- 5.0 Extension Points
The SAP Extension provides IBM® WebSphere® Portlet Factory users with the following important features.
Use of SAP JCo to connect to SAP
The SAP JCo interface supports connection pooling and oversees the management of portlet-to-SAP communications.Single-Sign-On capabilities
Note: For information about the versions of the SAP JCo that WebSphere Portlet Factory supports, refer to the detailed system requirements in the release notes topic.
Using IBM WebSphere Portal Server credential vault.Automation of portlet code
Including a method to get the SAP data, a schema to describe the data returned by the function, and variables (typed with the schema) to hold the Tables, Imports, and Exports.Seamless integration with other builders
To create robust, highly customized portlets, including custom look-and-feel and even access to custom BAPIs.
1.0 Installation notes
The components in the SAP Extension support the following SAP product version.
Table 1. SAP product version
|SAP Product||Versions Supported|
|R3||See the detailed system requirements in the WebSphere Portlet Factory release notes topic for the versions supported.|
Install the SAP Extension:
- In the project right-click menu, select Properties. Expand the WebSphere Portlet Factory category and select Feature Info.
- In the Feature Info screen, select the SAP Extension and click Apply. Click OK to add the feature set. Do not publish the project when prompted. The project will be deployed in a later step.
For Windows® systems
On Linux®, UNIX®, and z/OS® Platforms
Move the sapjco3.jar
files into a directory from which your application server loads shared JAR files. WPF_JCo3Common.jar
contains SAP access classes common to all Portlet Factory projects deployed to an application server. There must be only one copy of this JAR loaded by the application server. If the server loads more than one copy, then you will receive errors at runtime. If you have already completed this step for another Portlet Factory project, then you may simply remove WEB-INF/lib/WPF_JCo3Common.jar
from your project.
Also copy the sapjco3.dll
file into the system32
directory of your Windows operating system. (For example, on Windows XP systems, C:\Windows\system32
\WebSphere\AppServer\lib\extIBM WebSphere Application Server Community Edition
WebSphere Application Server Community Edition requires that you deploy any JAR files to be shared among two or more Web applications as Common Libs. Each Web application references this deployed common lib in its geronimo-web.xml
file in the <dependencies />
node. WebSphere Portlet Factory populates the geronimo-web.xml
file with commented references to sample Common Lib deployments for the sapjco3.jar
file (as well as references to JAR files for other WebSphere Portlet Factory integration builders.)
The values for the Group, Artifact, Version, and Type are largely arbitrary. Choose values that correspond to any naming conventions that you have or any other considerations. Clicking install results in the JAR files being placed in the <WASCE>/repository/Group/Artifact/Version/Type
directory and they are loaded by the WebSphere Application Server Community Edition server-wide class loader.
- Open the WebSphere Application Server Community Edition server console.
- Select Common Libs link under Services.
- Using the Browse option select and add these SAP jar files.
- Enter Group, Artifact, Version, and Type using your naming conventions.
- Click install to add the JAR files.
Refer to the SAP Java™ Connector installation documentation for instructions specific for your operating system.
If you are running WebSphere Portlet Factory on a Linux system, set the following permissions on the sapjco3.jar
and the WPF_JCo3Common.jar
The owner should be root and the group should be set to the group to which your WebSphere Portlet Factory user belongs. If your WebSphere Portlet Factory user is different than the WebSphere Application Server user, you must set up that user's environment as indicated in the SAP Java Connector installation documentation, so that users can access the SAP libraries.
The SAP library files required in this step are available to SAP customers at http://service.sap.com
- Redeploy the project.
- The WPF_JCo3Common.jar and sapjco3.jar files must be made available to your IDE plugin for Eclipse. To make this JAR file available:
- Locate your WebSphere Portlet Factory Designer core plugin folder. For example,
C:\Program Files\IBM\WebSphere Portlet Factory\Designer\eclipse\plugins\com.bowstreet.designer.core_latest version
- Copy the WPF_JCo3Common.jar and sapjco3.jar files into the \lib folder in the plug-in folder you just located.
Note: Do not rename these JAR files; the core plugin is configured to look specifically for JARs with these names. If you rename these files, then WebSphere Portlet Factory Designer will not be able to load their classes and will not be able to communicate with the SAP server. Depending on your server settings, your application server and Designer may need to be restarted to correctly register all Feature Set files.
- Referencing Common Libs from WebSphere Portlet Factory applications (For WebSphere Application Server Community Edition usage only)
file in the WebSphere Portlet Factory project contains a list of commented out dependencies for the sapjco3.jar
files. You must replace the Group, ArtifactID, and Version values with those you defined in the Common Lib deployment for the sapjco3.jar
<?xml version="1.0" encoding="UTF-8"?>
1.1 Verify Installation
To confirm correct installation of the builders and JCo, follow these steps.
- Configure your default_sap_server.properties file for the SAP server you are using (as described under Configuration Requirements below).
- Restart the IDE or WebSphere Portlet Factory Designer environment to complete the installation process.
- Open the SAP object browser model in WebSphere Portlet Factory Designer and ensure that you do not see errors in the Task View. (This model is located in the WEB-INF/models/samples/SAP folder accessible from the Eclipse Navigator.)
- Run the model. Confirm that the model runs correctly and that you are able to drill down into the returned SAP data.
In an IBM WebSphere Portal server environment, you must set the class loading order such that third-party JAR files are loaded before other JAR files and classes. This loading order insures that WebSphere Portal can access and use these third-party files. See your IBM Installation Guide for the steps required to establish this setting in WebSphere Portal server.
2.0 Configuration Requirements
The first step in using the SAP builder is establishing a destination properties file. This file is located in the project WEB-INF/config/sap_config/
The properties file is used to specify SAP connection properties such as the name of the SAP server and a valid SAP user name and password. A typical SAP properties file might be named my_sap.properties
and would contain the following properties:
# SAP application server
# Logon user
# Logon password
# SAP client
# Logon language
# SAP system number
A default SAP server.properties
file is installed with the SAP Builder. This properties file is located in the WEB-INF/config/sap_config
directory. You can use the file to establish your basic SAP settings and view examples of valid property values. As configured at installation, this file is applicable to a MiniSAP server running on the local host.
3.0 Getting started and using the object browser
After you install and configure the SAP Extension, run the object browser model. You can use this model to explore the objects in an SAP system. Use the following steps.
- Run the model and view the initial screen. A table is displayed that contains information about the objects in the system. Columns list object type, object names and descriptive text for each object.
- Click on a link in the OBJNAME column. A new table is displayed. This table lists on each row the set of methods (BAPIs) associated with the object. Click on a link in the Method column.
- Another table is displayed that contains all of the parameters for that method. Information about the parameter (for example, Description and Short text) is also provided.
- Click on a parameter in the table and the fields of the parameter are listed. Here you can view field names and allowable lengths, data types and field text.
4.0 Communicating with an SAP system
The SAP Builder use the SAP JCo interface (available with your SAP system) to connect to SAP. This interface allows a Java application to communicate with any SAP System. The SAP JCo interface supports connection pooling and oversees the management of portlet-to-SAP communications.
4.1 Connection pool size
The JCo inteface defines several new properties used to enable and configure destination pooling. From the client's perspective a destination is a set of connection properties used by the JCo interface to establish communication with an SAP server. These pooling properties can be added to the property files stored under WEB-INF/config/SAP_config/.
The peak limit defines the maximum number of connections active at one time for a destination. The pool capacity defines the number of idle connections to be maintained in the destination's pool; a value of zero disables the use of pooling. The expiration time, specified in milliseconds, defines the maximum time an idle connection will sit in the destination's connection pool before being closed and removed.
A default value of 5 for the peak limit has been found to provide adequate number of connections and good performance.
5.0 Extension Points
This section pertains to deployed WARs that access SAP that are implemented using WebSphere Portlet Factory. If you have a mixed environment, then you may need to write a small amount of custom code to have WebSphere Portlet Factory and non- WebSphere Portlet Factory WARs coordinate their configuration and access to SAP through the JCo interface.
Ignore this section if you have implemented all of the deployed WARs that access SAP using WebSphere Portlet Factory.
5.1 Custom Destination Data Providers
The SAP JCo interface uses the concept of a destination to define how clients access a server. From a client's perspective a destination is a named set of connection properties that the JCo interface uses to create connections to the server specified in the properties. These connections are not exposed to clients therefore all clients are required to communicate with the SAP server by passing a destination name to JCo methods.
WebSphere Portlet Factory implements a registry, also known as called a destination data provider, that is responsible for managing destination property sets. This registry assigns each property set a unique destination name and then provides the appropriate set of properties to JCo when a client references a destination name in a JCo method.
Only one destination data provider can be configured for the JCo runtime, using the JCo interface. All WARs accessing SAP through the JCo interface must use the same destination data provider. The destination data provider registry is located in the WPF_JCo3Common.jar
file. By placing this JAR in a directory from which your application server loads shared JAR files you have made the WebSphere Portlet Factory destination data provider implementation available to all WARs whether or not it was built with WebSphere Portlet Factory or otherwise. If all of the WARs accessing SAP have been built with WebSphere Portlet Factory, then no additional steps are required. However, if there are non- WebSphere Portlet Factory WARs deployed and these WARs access SAP through the JCo interface, then it will be necessary to either have those non- WebSphere Portlet Factory WARs use WebSphere Portlet Factory's registry or have WebSphere Portlet Factory use the destination data provider supporting the other WARs.
WebSphere Portlet Factory contains an extension point that allows you to use a destination data provider implemented by a third party. The destination data provider must implement the com.bowstreet.builders.webapp.methods.JCo3Common.DestinationRegistry
interface located in the WPF_JCo3Common.jar
file. This interface lets WebSphere Portlet Factory register the destination property sets used by the SAP builders. WebSphere Portlet Factory is configured to use a third party's destination data provider by setting the property bowstreet.sap.destinationRegistry
to the fully qualified name of the class implementing the DestinationRegistry
interface. At runtime the SAP builders in a WAR instantiates a single instance of this class and uses that single instance to register all required destinations.
5.2 Custom Session Reference Providers
The JCo interface uses a session reference provider to generate session IDs to support calling multiple SAP functions as pat of a single transaction that spans multiple threads. WebSphere Portlet Factory implements and uses a session reference provider as part of the SAP builder runtime. The JCo interface only uses one session reference provider when be configured for the JCo runtime. All WARs accessing SAP through the JCo interface must use the same session reference provider.
WebSphere Portlet Factory 's session reference provider is contained in the WPF_JCo3Common.jar file. By placing this file in a directory from which your application server loads shared JARs you have made the WebSphere Portlet Factory provider implementation available to all WARs (built with WebSphere Portlet Factory or otherwise). If all of the WARs accessing SAP are built with WebSphere Portlet Factory , then no additional steps are required. However, if there are non- WebSphere Portlet Factory WARs deployed and these WARs access SAP through the JCo interface, then it may be necessary to either have those non- WebSphere Portlet Factory WARs use WebSphere Portlet Factory 's provider or have WebSphere Portlet Factory use the provider supporting the other WARs.
WebSphere Portlet Factory contains an extension point that allows you to use a session reference provider implemented by a third party. The provider must implement the com.bowstreet.builders.webapp.methods.JCo3Common.SessionProvider
interface located in WPF_JCo3Common.jar
. With this interface WebSphere Portlet Factory demarcatse the beginning and end of a transaction performed by the SAP builders. WebSphere Portlet Factory is configured to use a third party's provider by setting the property bowstreet.sap.sessionProvider
to the fully qualified name of the class implementing the SessionProvider
interface. At runtime the SAP builders in a WAR instantiate a single instance of this class and use that single instance to demarcate all transactions.
Parent topic: Getting started with integration extensions
Files that are excluded from source control
Release notes - IBM WebSphere Portlet Factory Version 7.0.1