An overview of the WebSphere adapter for SAP
SAP is an enterprise resource planning system (ERP) that combines financial, human resource, operations, and corporate service systems. From an integration perspective, what we are most interested in is what services we can access in the SAP system from our application. As you learned in the previous articles in this series, each adapter provides an enterprise service discovery wizard. The job of the discovery wizard is to determine what data or services are available in the backend system and how to best access them. The JDBC adapter looks at the tables in your database and determines what services it needs to access that data. The SAP adapter discovery wizard looks into your ERP and discovers the services that are available for accessing the applications that are in it.
As Figure 1 shows, the SAP resource adapter uses the SAP Java™ Connector (SAP JCo) API to communicate with SAP applications that run on a SAP server.
Figure 1: The SAP resource adapter architecture
When you begin using the enterprise service discovery wizard, you must first decide which SAP interface to use. So, to understand what services you can discover with the enterprise service discovery wizard when you use the SAP resource adapter, you need understand the three types of SAP interfaces:
- Business Applications Programming Interface (BAPI®)
- Application Link Enabling (ALE)
- SAP query interface (SQI)
To help you choose which one to use, we'll describe these interfaces next.
Business Applications Programming Interface (BAPI)
The most common interface to access with the SAP resource adapter is the Business Applications Programming Interface (BAPI). A SAP server contains a business object repository (BOR) that stores SAP business objects. In an object-oriented fashion, each business object has a set of methods (BAPIs) associated with it to manipulate the data in the business object and carry out business functions using that data. We will refer to business objects on the SAP server as SAP business objects as opposed to WebSphere Integration Developer business objects.
External applications use BAPIs to create, update, or retrieve data from SAP business objects. There are many standard BAPIs for common business functions in various types of industries, and an enterprise can modify existing BAPIs or add many of its own.
For example, the SAP server typically contains an employee address business object in the BOR. There is also a function in the BOR called BAPI_ADDRESSEMP_GETDETAIL that a client application would call with an employee number as input to retrieve data contained within the employee address business object.
The enterprise service discovery wizard lets you select which BAPIs to use in your application. Keep in mind that the SAP resource adapter supports outbound-only processing when using the BAPI interface.
Application Link Enabling (ALE)
Application Link Enabling is a feature of SAP that uses an intermediate document (IDoc) to pass business data to and from applications. When you use the ALE interface, the SAP resource adapter supports both inbound and outbound processing. For inbound processing, the SAP server can send events to an application, in this case, the resource adapter, using the ALE interface. An event results from a business object being created, updated, or deleted.
Business objects for ALE that the enterprise service discovery wizard creates represent IDocs. For outbound processing, the resource adapter uses the business object to create an IDoc when a service call is made to the SAP server. For inbound processing, the resource adapter populates the business object from an IDoc.
SAP query interface (SQI)
The SAP query interface lets you query the SAP tables directly to retrieve data or check for the existence of data on the SAP server. The adapter supports outbound mode only for this interface. The business objects that are created using enterprise service discovery have attributes that represent the columns in a table.
In the remainder of this article we focus on using the BAPI approach. Undoubtedly you were secretly wishing for ALE, but since this ALE is not a beverage hopefully you'll play along as we dive into the world of SAP adapters with BAPI.
Enterprise service discovery for BAPI
An application calls a BAPI using a remote function call (RFC). In Figure 1, we mentioned that SAP JCo enables the adapter to make remote functions calls to invoke BAPIs when you run your application. However, to make an RFC call from an application, you need to specify the name of the BAPI and the details of its interface including the import parameters (input) and the export parameters (output). With the enterprise service discovery wizard, you can select the BAPIs that your application will use, and the enterprise service discovery wizard will create the business objects that store the input and output parameters.
You run the enterprise service discovery wizard to create an EIS import that you use to access your backend system. The import requires an interface with operations that the components in you module can call, and operations require business objects to contain the business data the operation uses. Let's look at how you use the enterprise service discovery wizard for the SAP resource adapter to create those artifacts.
When you select BAPI as the SAP interface to create services from (Figure 2), you're presented with a list of BAPIs that exist on your SAP server (Figure 3). The wizard presents the BAPIs by name, by description, or by the business object that they are associated with. There are many BAPIs, so you'll appreciate the filter button.
Figure 2: Selecting the SAP interface
shows two different ways to list BAPIs so that you can
easily select them to import. Under RFC, you'll see a list
of BAPIs that start with
which was set with a filter. Under BOR, BAPIs
associated with the Employee Address business object are
listed. You select the BAPIs that your application
will call using the SAP EIS import option.
Figure 3: Discovered BAPIs
Importing and configuring BAPIs
Select each BAPI that you want to use, and then click Add to import list. The wizard creates a business object to contain the input and output for the BAPIs that you selected. As you add BAPIs to be imported, the Configuration Parameters dialog box opens (Figure 4), giving you the opportunity to select the attribute naming convention and optional BAPI parameters to include as part of the business object.
Figure 4: Configuring parameters for a BAPI
When you want to use the parameter name as it is shown in the SAP function builder, select Use Field Name to generate attributes (Figure 5). If you do not select this option, the short text is used for each attribute.
As Figure 5 shows, BAPI_ADDRESSEMP_CREATE has optional parameters, as indicated by the checkmarks under the Optional column, which you see in the Configuration Parameters dialog box. By default, all optional parameters for a BAPI are included in the generated business object attributes. If you want to omit some optional parameters, then select Check if you want to select optional parameters for this interface and then select No for the optional parameters that you want to omit.
Figure 5: BAPI parameters as shown in the SAP Function Builder
Creating the business object and interface
After you have selected one or more BAPIs, you need to
specify the name of the business object to
contain the BAPI parameters, and you need to specify
what type of operations (create, update, retrieve, or
delete) each BAPI will perform. For example, suppose you
want to import
BAPI_ADDRESSEMP_GETDETAIL. After you
close the Configuration Parameters dialog box, the
Configure Object page of the wizard opens. In this
example, we set the business object name to
EmployeeAddress and select Retrieve from the list of
operations (Figure 6).
Figure 6: Configuring the business object and operations
If you followed along with the previous articles, you
might be wondering what
means. This is a bit different than with the previous
resource adapters where you select an operation from
your EIS, and an operation with that name is created in
the interface. Keep in mind that SAP business objects
contain operations that work on that business object.
So, in the Configure Objects page, you give the
EmployeeAddress business object a retrieve operation
that will call
BAPI_ADDRESSEMP_GETDETAIL to get the
employee address details (the
object contains metadata that tells the SAP resource
adapter which BAPI to call when it calls the the retrieve operation
on the import).
When you finish with the last page of the wizard, where you create a module to hold the EIS import, the interface and business object is created. To put things in perspective, let's look at what gets created in our example.
Figure 7: The import interface for the EmployeeAddress retrieve operation
shows the interface that the enterprise service
discovery wizard created for the EIS import. Because we
specified that the BAPI is called with a retrieve
operation associated with
EmployeeAddress, the interface
retrieveSapEmployeeAddressWrapper operation. The
input is a
SapEmployeeAddressWrapperBG business graph
The business graph contains a verb, which you set to
"retrieve" when you call the operation in this case, and
SapEmployeeAddressWrapper business object, which has
the Wrapper suffix because it contains a business object
for both the BAPI input and metadata. An
interesting point here is that the operation name
doesn't indicate which BAPI gets called. That
information is encoded in the generated business graph. Let's look at the business graph now.
Figure 8: The EmployeeAddress business graph
SapEmployeeAddressWrapper business object contains
application-specific information that indicates to the
resource adapter that it is to call
BAPI_ADDRESSEMP_GETDETAIL for the
EmployeeAddress retrieve operation
(Figure 9, the second column under
ASI element properties).
Figure 9: Application specific information for EmployeeAddress
Along with the BAPI information,
SapEmployeeAddressWrapper contains the
SapBapiAddressempGetdetail business object, which has
the attributes that provide the input and output of the
BAPI call. So, when you call the retrieve operation with
an employee number in the
Employeenumber attribute, the
resource adapter populates the other attributes when the
BAPI call returns. When you call the retrieve operation,
SapReturn business object contains the BAPI messages
or error codes that result from the BAPI call.
Of course, you will often want to create, update, or
delete business objects in addition to retrieving data.
For example, you might also want to create or update the
EmployeeAddress business object in a module. In that
case, look back at Figure 3;
you can select multiple BAPIs and then specify which
BAPI creates the business object and which BAPI updates
the business object. When you have selected multiple
BAPIs, the Configure Objects page of the wizard opens
and you can select the BAPI that represents each type
of operation for a business object.
Figure 10: Creating a business object
When the wizard completes, it creates an import with an interface that contains create, update, retrieve, and delete operations, depending on what you specified. Note that many BAPIs cannot be called by themselves; they require other BAPIs to be called first. In that case, you use a BAPI transaction object.
Interactions with the SAP server always consist of logical units of work (transactions). A BAPI transaction might consist of a single BAPI call, as in our first example, after which the adapter calls a commit on the SAP server. A transaction might also consist of a sequence of BAPI calls followed by a commit call.
In Figure 10, notice the check box labeled Create a BAPI transaction Object from the selected BAPIs. Figure 3 showed you that you can select a number of BAPIs and add them to the Objects to be imported section in the wizard. When you do that, you can assign each BAPI as a particular create, update, delete or retrieve operation.
However, when you have some operations
that call multiple BAPIs, you might want
to specify a sequence of BAPIs that performs one logical
unit of work. In that case, you can select Create a
BAPI transaction Object from the selected BAPIs.
Then the sequence of BAPIs in the list
are treated as one transaction that performs
either a create, retrieve, update or delete operation on
the business object. The example in Figure 11,
calls the selected BAPIs, followed by a commit,
when it calls a create operation for the
EmployeeAddress business object.
Figure 11: Creating a BAPI transaction object
In the next example, we'll look at how you create a BAPI transaction object. We'll also show you how to set up the adapter and run the enterprise discovery wizard to create a BAPI transaction object for you.
Enterprise service discovery using the adapter for SAP
Now that we've covered the basics of the SAP resource adapter, let's look at a detailed example and put everything that you've learned together. In the following sections, we'll set up the SAP resource adapter and then run the enterprise discovery wizard. Your own SAP server might not have the same business objects and BAPIs as our example does, but you can follow along using BAPIs that you are familiar with on your own system.
We will create an EIS import that will use the SAP
resource adapter to call
creates an address record for an employee. However,
before you can call
BAPI_ADDRESSEMP_CREATE, you need to
lock the Employee record. After the call,
you release the lock. Therefore, creating an employee
address record requires the following BAPI call sequence
in a transaction object:
Before you can use the enterprise discovery wizard with your SAP adapter, you need to provide the libraries that the adapter requires. In Figure 1, you'll see a little box called Sap JCo between the SAP resource adapter and the SAP server. The sapjco.jar enables remote function calls from a Java application (in this case, the Java application is the SAP resource adapter) to the SAP server. The sapjco.jar requires sapjcorfc.dll and librfc32.dll, which both require msvcp71.dll and msvcr.dll. You might already have msvcp71.dll and msvcr.dll in your Windows installation. So, you need to do these first few steps before you get started with the enterprise service discovery wizard:
Obtain the following files from your SAP
administrator, or from the SAP support site:
Copy sapjcorfc.dll and librfc32.dll to two places:
- <WID>\eclipse\jre\bin. The enterprise service discovery wizard uses sapjco.jar, which in turn uses these DLLs to connect to the SAP server
- <WID>\runtimes\bi_v6\bin. The SAP resource adapter looks for the DLLs at this location when your application runs on WebSphere Process Server.
- Copy sapjco.jar to the <WID>\runtimes\bi_v6\lib directory.
- If they aren't already there, copy msvcp71.dll and msvcr71.dll to Windows\System32, so that they are installed on the Windows system path.
Well, that wasn't very exciting. Let's move on to where things get more fun.
Where is my adapter?
To use the SAP resource adapter, you need to do a little more rummaging in the file system to accomplish two things:
- Create a project using the RAR file of the SAP resource adapter. Your business modules and the enterprise service discovery wizard will use this resource adapter project.
- Configure the project to use the correct JAR files for the adapter.
In the next steps, you create the adapter project for the SAP resource adapter:
- Open the enterprise service discovery wizard by selecting File - Import - RAR file.
- For Connector file, browse to <WID>/Resource Adapters/SAP/deploy/CWYAP_SAPAdapter_Tx.rar.
Leave Connector project set to
- Clear Add module to an EAR project and then click Finish.
- When you have finished with the wizard, switch to the Resource perspective (Window - Open perspective - Other - Resource).
- In the file system, copy <WID>\runtimes\bi_v6\lib\sapjco.jar to the CWYAP_SAPAdapter project.
- Right-click your newly created adapter project, CWYAP_SAPAdapter, and select Properties - Java Build Path.
- On the Libraries tab, click Add Jars. Browse to the jar file you copied earlier, which is in the CWYAP_SAPAdapter project
- Switch back to the Business Integration perspective.
The adventure begins with discovery
Now the fun begins. In the next steps, you will use the enterprise service discovery wizard to select the BAPIs it calls during the create operation on the SAP EIS import.
- Select File - New - Enterprise Service Discovery.
Select IBM WebSphere Adapter for SAP Software
as Figure 12 shows, and
then click Next.
Figure 12: Importing the SAP resource adapter
In the first page of the wizard
complete the fields for your specific SAP server, and
choose which SAP interface you will use: BAPI, ALE, or
SQI. By default BAPI is chosen for you, and that's the
one you want for this example.
Figure 13: SAP adapter connection properties
- Enter your your UserName and Password for the SAP server
- Enter the applicable SAP Host Credentials that your administrator was kind enough to provide.
- Next to Select the SAP interface, choose one of BAPI, ALE, or SQI . By default BAPI is chosen for you, which is what you want for this example.
Maximum number of hits for the discovery
set to 100.
The maximum number of hits indicates how many BAPIs the adapter should return (it is also the number of IDOCs for the ALE interface, and the number of tables for the SQI interface). A typical SAP server can have numerous SAP business objects, but remember that a larger number of SAP business objects will require more time to retrieve the results. Later in this article, we'll show you how to filter the results to limit how many results appear in the enterprise service discovery wizard.
Click Next. On the next page in the wizard, the Find and
Discover Enterprise Services page
(Figure 14), click
A word of caution here: Don't expand either of the DiscoverByName or DiscoverByDescription categories, which are under RFC. Also don't expand BOR just yet. If you chose a high value for the maximum number of hits (Figure 13) but have not applied a filter, you'll find yourself waiting a long time until all of the results display.
Figure 14: Discovering BAPIs and SAP business objects
There are two ways to discover business objects on the SAP server: you can retrieve a list of BAPIs or a list of SAP business objects and their associated BAPIs. Under RFC, there are two categories: DiscoverByName and DiscoverByDescription. These categories list all of the BAPIs on the SAP server, showing either the BAPI name or BAPI description respectively.
Under BOR, there is a list of all of the SAP business objects. Under each business object, there is a list of each BAPI that is available for that business object.
Before you import BAPIs, let's get back to the filtering
that we previously mentioned. Because there are a lot
of BAPI objects in an SAP system, you can create a
filter for the Discover By Name,
Discover By Description, and BOR
categories to limit the returned results, which saves
time and makes it easier for you to select the BAPIs or
business objects that you are interested in. To create a
filter, select a category and then click Filter.
Enter a filter like
BAPI_ADDRESSEMP_* (to display only
BAPIs that have names beginning with BAPI_ADDRESSEMP),
the BAPI name or SAP business object name, or any part
of the name. You can even use a wildcard (*) to match
the rest of the name.
Next, you want to select the enqueue, dequeue, and create BAPIs for your transaction, so you'll set a filter and select them:
- Select RFC â DiscoverByName, and then click Filter.
In the Filter dialog box, enter
BAPI_EMPLOYEE_*QUEUEand then click OK.
Expand Discover By Name
and wait for the resource adapter to add the list of
BAPIs to that category
Figure 15: Adding a BAPI to the import list
- Under Discover By Name select BAPI_EMPLOYEE_ENQUEUE.
- Click Add to import list.
- When the Configuration Parameters dialog box opens, click OK because there are no optional attributes in this case.
To add BAPI_EMPLOYEE_DEQUEUE
to the import list, repeat the previous steps. The
wizard now looks like Figure 15.
Another word of caution here: When you select a filtered category, you can also click Clear Filter. However, if you click Clear Filter while the category is expanded, the adapter will repopulate the list with no filter applied, which could take some time.
- Select the Discover By Name category, and then click Filter.
In the Filter dialog box, enter
BAPI_ADDRESSEMP_CREATEand then click OK.
- Under the Discover By Name category, select BAPI_ADDRESSEMP_CREATE and then click Add to import list. The Configuration Parameters dialog box opens.
- To use the default name for the business object attributes and to not include optional attributes, click OK. The wizard is now at the Configure Objects page.
In the Configure Objects page, you define what operations will be available for the outbound interface based on the BAPIs that you chose, and you name the business graph that will be used as the input and output for each operation. You should name the business graph something similar to the SAP business object that the BAPIs are based on.
For Object Location, enter
EmployeeBOsand leave the default value for Namespace.
For Enter the name of the Business Object, enter
- Check Create a BAPI transaction Object from the selected BAPIs.
- For Choose the operation for this Transaction Business Object, select Create.
You just created an empty BAPI transaction that will create an employee address SAP business object. The next step is to add the BAPI calls in the order in which they will run as part of the transaction.
- Click Add.
- In the Add list, select BAPI_EMPLOYEE_ENQUEUE and click OK. This is the first BAPI that will be called in the create operation.
Repeat the above steps to add BAPI_ADDRESSEMP_CREATE,
BAPI_EMPLOYEE_DEQUEUE, and COMMIT,
in that order. The enterprise service discovery
wizard opens (Figure 16).
Figure 16: Configuring a BAPI transaction object
You have just defined a BAPI transaction that will:
BAPI_EMPLOYEE_ENQUEUE, to lock the table containing the
AddressEmpSAP business object.
BAPI_ADDRESSEMP_CREATEto create an AddressEmp object.
BAPI_EMPLOYEE_DEQUEUEto unlock the table.
- Commit the transaction.
The final step, as with the wizards for other resource adapters, is to tell the wizard which module to put the outbound import into, and then set the SAP connection information that you have just provided into the import:
- Click Next. The Generate Artifacts page opens.
- Click New. The New Integration Project wizard opens.
- In the New Integration Project wizard, ensure Create a module project is selected, and then click Next.
For the Module name, enter
CreateEmployee, and then click Finish. The Module field on the Generate Artifacts page contains the value
CreateEmployee(Figure 17), and the connection information contains the values that you entered on the first page of the wizard. You can change those values later by selecting the properties for the CreateEmployee import.
Figure 17: Generating the discovered artifacts
- Click Finish. The wizard closes and the import is added to the CreateEmployee assembly diagram.
If you want to create more imports for other BAPIs, then you can take a short cut instead of running the wizard again. As Figure 18 shows, there is an entry under the SAP resource adapter that has the same user name that you used to connect to the SAP server. To start at the Query page of the wizard, select the name and click Next.
Figure 18: Re-running the wizard
At this point, you are ready to add the business logic
to your application that will use the
import. Now, when you call the
createSapEmployeeAddressInput operation, the three
BAPI_EMPLOYEE_DEQUEUE, are called in that order,
using the data that is in the
business graph, followed by a commit call.
This article concludes the Getting connected with WebSphere Integration Developer adapters series. You have learned that the adapter space, despite its terminology, is actually straightforward, and that connecting to your EIS, database, flat files, and e-mail systems is fast. When you find the right adapter for your system, WebSphere Integration Developer uses the adapter you chose to determine what you can do with the backend system and then create services, operations, and business objects that your business logic can use. So, with a couple of wizards, you have services you can call from your business logic exactly the same way that you would call other reusable services. Your business logic code does not need to know the details of what happens behind the adapter curtain.
- WebSphere Adapter for SAP User Guide
- Technical overview of the Adapter for SAP
- Overview of all WebSphere adapters
- Getting connected with WebSphere Integration Developer adapters, Part 1: An introduction to connecting with adapters (developerWorks, Apr. 2007)
- Getting connected with WebSphere Integration Developer adapters, Part 2: An introduction to the WebSphere Adapter for Flat Files (developerWorks, May 2007)
- Getting connected with WebSphere Integration Developer adapters, Part 3, An introduction to the WebSphere Adapter for JDBC (developerWorks, June 2007)
- Enterprise Metadata Discovery
- Introduction to creating business processes with WebSphere Integration Developer
- J2EE Connector Architecture 1.5 specification
- Adapter documentation
- A guided tour of WebSphere Integration Developer
- WebSphere Integration Developer product information
- developerWorks: WebSphere Process Server and WebSphere Integration Developer resources
- developerWorks: WebSphere Business Integration zone
- developerWorks: WebSphere development tools zone
- Meet the experts: WebSphere Integration Developer