        |  |
 |
 |
 |
 |
 |
 |
 |
 |
 |
|
SAP Connect User's Guide
CHAPTER 5
The SAP Service is a type of Composer service that can be activated by an incoming RFC call to an SAP server. In essence, the SAP Service becomes a BAPI destination, and the action logic in the service becomes the BAPI logic of that destination. The Composer SAP Service may call other BAPIs (via SAP Components) or it may not. The service might, in the course of executing, call JDBC or 3270 components, execute LDAP queries, participate in a CICS transaction, or use other kinds of connectivity involving other Composer Connect products. Then again, it might simply take data in, transform it in some way, and send XML out.
In this chapter, you'll learn what the capabilities of the SAP Service are, how to create such a service, and how to use it. Before proceeding, you should already have familiarized yourself with the sections of this guide that deal with creating SAP connections (see Getting Started with the SAP Component Editor) and using SAP actions (see Performing SAP Actions). You should also be familiar with Composer action-model programming concepts (see the separate Composer User's Guide).
In Composer's navigation tree (or explorer tree), there is a category called Service. Under this category, if you have Composer Enterprise Edition, you will see three types of service listed: JMS Service, Web Service, and SAP Service. (The latter is visible only if you have the SAP Connect and all relevant JCO libraries installed as described in Getting Started with the SAP Component Editor.) You can create service xObjects (instances of deployable services, created in Composer) falling under any one of these service types.
The services you create in Composer usually execute components. Any of the types of services listed above can make calls to any number of components of any type. For example, an SAP Service can wrapper calls to XML Map, JDBC, and SAP Components. What distinguishes a service from a component is that the service xObject is triggerable. When your project is deployed on the server (in EAR form, usually), the components in it can be invoked only by Composer services, whereas the services within a project can be invoked by various kinds of trigger objects (the most common being HTTP servlets). Composer's three main kinds of service differ in how they are invoked. The JMS Service is triggered by arrival of messages on a JMS message queue or topic. The Web Service can be triggered by any number of mechanisms: arrival of an HTTP request, arrival of e-mail at a mail server, direct invocation by a Java object, etc.
The SAP Service is an event listener that registers with an SAP gateway server. When an RFC (remote function call) is executed on an SAP gateway server, the results are forwarded to the listener (in this case, a Composer SAP Service). The listener can then call other remote functions on the gateway server using the same connection that was established to register the listener.
The choice of whether to wrapper your SAP Components with an SAP Service as opposed to, say, a Web Service should be based on the kind of message-exchange pattern in which your service will participate. Will your service respond to RFCs? Or will it initiate function calls on its own? Consider the four canonical Web Service message-exchange types:
Request-response. The endpoint receives a message, and sends a correlated message.
Solicit-response. The endpoint sends a message, and receives a correlated message.
If messages are being sent via RFC, the first two types of exchange patterns (one-way and request-response) can be implemented with an SAP Service. The second two kinds of exchanges, in which the endpoint (your application) initiates the sending of a message (by calling an RFC), can be handled with an SAP Component packaged inside any kind of service.
The rule of thumb is: If your application will be consumed by other SAP applications or functions, using RFCs transmitted via SAP gateway server, your app is going to be deployed as an SAP Service. If your application will be invoked by non-SAP-gateway processes (i.e., you don't need to register with an SAP gateway server), then you'll deploy your SAP-enabled application as a Web Service or JMS Service.
The SAP Service is like any other kind of executable xObject (XML Map Component, JDBC Component, etc.) in that it has an action model that can utilize any of Composer's core action types: Log, Map, Decision, etc. In theory, you could perform all of your business logic inside the SAP Service's action model (assuming no other kinds of connectivity are needed, such as JDBC or LDAP). As a best-practices issue, however, you should put all of your business logic in individual components, and use the service to call the components. The kinds of logic you should employ at the service level are things like fault-trapping and logging.
When you first create an SAP Service, you will notice that an action (called an SAP Service Switch) is present in the action model. This action is present once and only once in any given SAP Service and never occurs in an SAP Component. Therefore, it is not available on any menu commands. Composer always creates the action for you when you create an SAP Service. The purpose of this action is to allow you to associate RFC Function Names with action logic on a case basis. This action is discussed again in a later section of this chapter.
The following steps tell how to create an SAP Service in Composer.
Create an SAP Service Connection Resource (if you have not already done so) to define the connection between your service and the SAP host or gateway server.
NOTE: The SAP Service Connection Resource is different from an ordinary SAP Connection Resource. Please refer to the discussion at "To create an SAP Service Connection resource:" in "Getting Started with the SAP Component Editor" for more information.
In Composer's explorer tree, right-click on the SAP Service category and choose New. Alternatively, use File > New > xObject and select SAP Service as shown in the illustration below.
In the dialog that appears, enter a Name for your service in the text field provided. See below.
In this dialog, specify the XML Template sample documents you wish to use in the design of your service's inputs and outputs.
In this dialog, specify any Temp documents you would like to use in your service. (You can add these later, if need be. If you're not sure what to do, click Next for now.)
In this dialog, verify (using the Connection pulldown menu control at the top of the list of controls) that you have selected the desired SAP Service Connection that will be used by this SAP Service. Optionally click the Test button to verify that a live connection exists.
Click Finish. The dialog goes away and a new action model appears, with one SAP Service Switch action in it.
As mentioned earlier, whenever you create a new SAP Service component, Composer creates a new action model containing a single action called SAP Service Switch. This action allows you to specify Function names that you would like to designate as the RFC targets that your action model can handle. In this respect, the SAP Service Switch is like an ordinary Switch action. A request comes in to your service, and depending on which function-name the requestor is looking for, the SAP Service Switch action executes at the appropriate "case" statement.
The following example shows how this action works.
To configure and use the SAP Service Switch:
In an SAP Service's action model, find and doubleclick the SAP Service Switch action line. When you do this, a dialog appears:
To search for function names that are registered on the server, enter a search string (with optional wildcards) in the Search for Function text area. Then use the Search button to initiate a search. Results will be displayed in the Found Functions list.
In the above illustration, the search term was "BAPI*" (which means "bring back all names of all functions that begin with BAPI"). Many function names were found that meet this description. Probably only a few (perhaps just one) will be handled by your service. This step verifies that the names you want to handle are in fact registered on the server.
Use the Found Functions picklist on the left to designate function names that will be handled by your service. Transfer selected names under Found Functions to the list on the right by using the plus-sign icon. Use the minus-sign icon to remove names from the list on the right. (Use up and down arrows to reorder the chosen names.) Names on the right will become the basis of "case" blocks in your SAP Service Switch action.
NOTE: You may optionally enter (by hand), in the right-hand list, the name(s) of functions you know will be handled by your service. You can also use the flyout menu on the right edge of the Mapping list to bring up buttons that will let you determine the mapped value programmatically, using ECMAScript, or by LDAP lookup.
Highlight (select) one of the items in the list on the right, then click the Mapping button. A dialog will appear.
This dialog has two tabs: SAP Service Request and SAP Service Response. Their usage is identical to that of the SAP Request and SAP Response tabs in the dialog for the SAP Function Action, as described in the Actions chapter, under the section beginning under "Click on the SAP Request Tab." Refer to that discussion for a detailed explanation.
Exit out of all dialogs. In the action model, you will see new lines that start with "FUNCTION:" and the name(s) of the function(s) you specified in the previous pickers. You can now create individual actions as need be under each function block, to handle calls to that function name.
Notice that when you single-click on any "FUNCTION:" line (any case in the switch), the native environment pane (NEP) updates to show the structure of SAP Service Request and SAP Service Response documents (each with its own tab). Again, the usage of these tabs is similar to that of the SAP Request and SAP Response tabs in the NEP when working with SAP Actions. See the discussion at "Mapping a Portion of an XML Document into SAP Request Tab" for details.
To deploy an SAP Service in Novell exteNd Composer Enterprise Edition,using the Composer deployment UI, simply create a Deployment xObject as described in the Deployment chapter of the Composer User's Guide, and drag any SAP service instance from the instance pane under the explorer tree, to the SAP Service category node under the Deployment Object explorer tree.
Use File > Deploy Project (Cntl-F5) to begin the deployment process.
Since the SAP Service merely listens for incoming RFC requests targeted at named destinations, the only true way to test an SAP Service in "host mode" is to establish a live connection to an SAP gateway server and then have a remote entity make an RFC request to your service. As it turns out, this can be done at design time (and you can then step through your service in debug mode), if you can establish a live connection and you have a process of some kind (perhaps an SAP component built for test purposes) that can "call" your service with the appropriate function name. Although doing this is not hard, it does require the availability of a live SAP system for testing, the use of SAP tools for creating and configuring RFC destinations, and experience with BAPIs. These techniques are beyond the scope of this guide, but you can obtain additional help and guidance by consulting the Novell exteNd web site and/or by contacting your Novell representative directly.
NOTE: If you try to enter Animation mode in an SAP Service action model, all animation toolbar buttons will become disabled except for the Stop button. Then nothing happens. Here's what's going on: Hitting the Start Animation button actually does start the execution of your service. But because the service requires an incoming RFC request to act on, it will appear to "hang" on the initial action (the SAP Service Switch action) while it "listens" on the connection. If a request never comes in, the service "listens" forever (or until you hit the Stop Animation button). If a request does come in, animation will continue and you can step into or step over individual actions in debug mode using the toolbar buttons.
Copyright © 2003 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...
