We introduced SAP’s new Web service tool in our March 2007 article, and now we’ll take a more detailed look at it to provide you with some valuable tips for your projects. The technical information also gives you a good introduction to the SAP CRM architecture featured in SAP CRM 2006s and SAP CRM 2007.

With the new releases, SAP has not changed the general architecture of the SAP CRM server or the business process customization. Instead, the changes focus on the UI layers, although the technology is based on Business Server Pages (BSPs). We address the changes as they occur in SAP CRM 2006s, but the information in this article also applies to SAP CRM 2007.

We’ll follow the example from our March article of developing a Web service with two operations to create and read a business partner account. In this scenario, we distributed service tickets to our field technicians and external service providers using Adobe Interactive Forms. We created a Web service to fill the form and play the changed data back to SAP CRM. The Web service also allows us to upload the ticket data to the Interactive Form and send it to our field technicians via email. When the technicians return the form via email, the system uses another Web service to update the data.

This time we’ll first take a look at SAP CRM’s basic architecture, focusing on the most important layers. Then we’ll describe the underlying technical steps. By knowing the technical background of the Web services, you’ll be able to define what you want in the Web service, which lets IT build it to meet your needs.

SAP CRM Architecture and the BOL

Figure 1 depicts the complete design with respect to the CRM WebClient UI. The basic SAP CRM architecture is comprised of three layers: business engines, the business layer, and the presentation layer for the user interface (UI). Within the business layer, you have the business object layer (BOL) and the generic interaction layer (GenIL). The BOL is the foundation for the Web service tool. It caches business object data, such as business partners and sales orders, at the runtime of a CRM WebClient UI session. The presentation layer contains the components that send the data between the UI and the back-end system, such as SAP CRM.

Figure 1

CRM WebClient architecture layers — UI (Source: SAP)

Another important layer within the business layer is the GenIL, which handles the data transfer from the BOL to the Application Programming Interfaces (APIs) of the underlying CRM business engine (application logic and database tables). The GenIL connects the BOL to the underlying business logic and database through the underlying application APIs, in most cases the SAP CRM APIs.

For the technical realization of the Web service tool, we used the standardized BOL to model the Web services on top of it — we reused the BOL and replaced the presentation layer with a new Web service tool engine (Figure 2).

Figure 2

CRM Web service tool architecture layers (Source: SAP)

With the Web service tool design we rethought the way IT, administrators, and functionalists can create their own service interfaces. In the past, the service interface development process was quite time consuming and involved lots of manual activities. By reusing the BOL architecture and models, SAP CRM allows you to create Web services by modeling them instead of programming them.

Now let’s walk through the four steps in the Web service tool creation wizard with respect to what happens in the system in the background as you move through the wizard. Refer to our March article for additional information about the steps.

Wizard Step 1

Name the Web service and select a business object. In this part of the wizard, you select the business object for which you want to create a Web service and decide which service operations you want to provide. In our example, we chose the business object Business Partner/Account and selected the Create and Read operations. Finally, provide a name and a brief description for the service object. The system stores all gathered information within database tables. From a technical perspective, this first step is not that elaborate — you can refer to our March article for more details about how to carry it out.

Wizard Step 2

Select the attributes for your service. In the second step, you select the attributes you want to expose in the interface of the Web service. As Figure 3 shows, first you choose a relation from the left side of the screen and select the required attributes from the list on right side of the screen. Then you go to the second relation to choose the respective attributes for it.

Figure 3

Choose the relation and the attributes for the Web service

Technically, you perform this selection from the BOL attributes, which is the architectural trick of the Web service tool. You can find the complete network of BOL nodes within the BOL browser, which you access via transaction GENIL_MODEL_BROWSER (see the “Glossary” sidebar below). Here you can get an idea about the options available when modeling your business with SAP CRM.

In our example, we chose the city and postal code (technical BOL names City and POSTL_COD1) out of the available attributes from the relation Address (technical BOL name BuilAddress).

Although the visualization in the BOL browser suggests that you are dealing with a tree, it is indeed a network because the Dependent Objects folder can include recursions. For instance, Attribute Structures can refer to themselves via a subsequent relation. This makes sense from the modeling point of view for your business because you are free to reuse the same structure on any hierarchy level you like when defining the business objects.

A good example of this is in the BOL component for the business partner. The technical object BuilAddress (representing a business partner address) contains the relation BuilAddressDuplicateRel (pointing to all address duplicates detected in the system). In turn, this relation leads back to the object BuilAddress.

This makes sense because the duplicate of an Address is of course itself an address. The BOL is generic, so the relation that is valid for a technical object is valid independently of the hierarchy level. In our example, this means that the duplicate of an address could theoretically also have a duplicate.

The Web service designer must delete these types of recursions either automatically or manually — the Web service tool supports both ways. If a recursion exists directly from an object to itself — without any steps in between — the tool handles it automatically.

Wizard Step 3

Maintain the attributes. After you choose the attributes for your Web service, you can rename the technical attribute names and assign default values to them (Figure 4). Furthermore, you can hide the attributes if you do not want them to become part of the Web Service Definition Language (WSDL) file. (Refer to our March article for details on how to do this with the Web service tool.)

Figure 4

Rename attributes and assign default values to them

Technically, the database table CRMC_WST_DESIGN stores the changed data. The Ref. Name field is the name of the tag in the XML document produced as the body of the Web service response. This means that the name is visible in the WSDL file to any application that uses the Web service, such as SAP NetWeaver Composites designed with Visual Composer, or non-SAP consumers — for example, Adobe Forms or Microsoft Office applications. Make sure to provide a logical name for the Web service you’re creating. You may also specify a default value for an attribute, which the system then automatically assigns when the Web service call does not pass the attribute automatically. For instance, you would do this if you wanted to set an org unit or partner function as a default for all service calls. If you like to have an attribute Read Only for the Web service, select Excluded.

Wizard Step 4

Save, check, and activate the Web service. Up to this point in the wizard you basically collect the data you need to create the Web service. In this last part of the wizard, you only have to save your work and the system generates the Web service object automatically. You can divide this process into three parts:

• Generated function modules
  
  
• Web service tool runtime
  
  
• Using the Web service features in SAP NetWeaver

Generated Function Modules

After you click on the Generate button, the Web service tool generates complex, nested ABAP structures. These structures represent the input and output payload of the Web services. The payload is the actual content (business data) of the message. The input message is called a requesting message and the output message is called a response.

The input and output messages of a Web service are valid, hierarchically structured XML files with a well- defined single root node. This allows you to transform the structure of an XML file into an ABAP structure and vice versa. You perform this transformation with the ABAP statement CALL TRANSFORMATION. This statement is heavily used within the Web service tool. For further information about this statement, refer to the online documentation at https://help.sap.com and review the “Providing and Consuming Web Services” section.

With these generated structures you can process the input and output of the Web service by using ABAP structures. In fact, you can use ABAP functionality to split up the input, call the GenIL interfaces to get the results, and use the results to build the XML output for the Web service.

All of the generated structures begin with the prefix /CRMOST/ followed by the first three characters of the service name. To ensure unique names, the system assigns a three-digit number to the ABAP structure followed by characters to distinguish between inbound or outbound and the different types of operations:

• M: Change
  
  
• N: Create
  
  
• R: Read
  
  
• Q: Query
  
  
• D: Dynamic
  
  
• G: General

If you are interested in the generated structures, you may want to look at them in the ABAP dictionary (transaction SE11).

To understand the relationship between the XML payloads and the representing structures, you have to take into account that for an object’s relations to itself — for example, a sub-item of the items of an opportunity — no additional substructures are included. This refers back to the remark about recursion in the “Wizard Step 2” section.

However, the relation is resolved when the system adds a column within the structure to build the table of opportunity items. Therefore, you might detect attributes within the ABAP structure nodes that you did not select explicitly during the Web service modeling process.

With the tool, the system creates these additional structures to resolve recursions automatically.

Additionally, the Web service tool creates the following:

• Substructures for error messages
  
  
• Warnings (log)
  
  
• Information about which input payload attributes are empty (controller)

The log stores the warning texts in a log file. The controller keeps additional information regarding the payload. This information is important for Web services that perform change operations because, in this case, the payload reduces dramatically if the Web services contain only the attributes that you need to change or create. To distinguish between change and create, refer to another technical attribute that’s within the generated structures: ACTION_CODE.

Table 1 provides the possible values for the action code. When you call a Web service, the calling program sets these values. They indicate whether you have to change, create, or delete a given sub-object of an object. For instance, you may create an address for an existing business partner or you may want to delete an item in an existing sales order. Normally, you delete a complete document, such as a business partner, by selecting the Archive flag.

Transaction SE11 (transaction for ABAP dictionary) in Figure 5 shows an example for an input structure for a change service as given in the ABAP Dictionary. Here you find ACTION_CODE and CONTROLLER on the root level. The Web service tool user did not select these attributes — the Web service tool generated them automatically.

Figure 5

Example structure ACCOUNT1 in ABAP Dictionary

If you double-click on ACCOUNT1, the screen in Figure 6 appears. Here you can find all the attributes selected in step 2 of the Web service tool wizard: BP_NUMBER, BP_CATEGORY, EMPLOYER, FIRSTNAME, LASTNAME, NATIONALITY, and PARTNERTYPE. The attributes ACTION_CODE and CONTROLLER are present again. This happens for all levels within the hierarchy of the Web service structure because you need the information they include.

Figure 6

BUILHEADER structure in ABAP Dictionary

After you activate a Web service, you can find the same structure in the SAP NetWeaver Web service test environment and, in a slightly different manner, in the WSDL file for the Web service.

You have now learned how the Web service tool generates the needed structures for the request and responds to Web service messages. Next, let us show you how we create the function modules in which you generate the program coding that operates on these structures.

You may expect that the ABAP structures are now used as the input and output of the ABAP function modules for operations that build on the Web services payloads. Indeed the Web service tool generates the needed function modules at design time. You can see the result of this step within the ABAP Object Navigator (transaction SE80), shown in Figure 7.

Figure 7

SAP Workbench — Example for function module ZACCOUNT

The generated function modules start with a common prefix /CRMOST/ followed by an abbreviation of the name you assigned to it in the step 1 of the Web service tool wizard. For each operation (create, change, read, and query), the Web service tool creates a separate function module. In our current example, the two modules are /CRMOST/ZACCOUNT_CHG for the change operation and /CRMOST/ZACCOUNT_CRT for the create operation. Both function modules are generated into a function group called /CRMOST/ ZACCOUNT_FCT.

As you might expect, you find one importing and one exporting parameter in the signature of the ABAP function module (Figure 8). The input parameter is the representation of the XML body of the request of the Web service. The output parameter is the representation of the response to that Web service request. The ABAP statement CALL TRANSFORMATION in the Web service tool later transforms the XML code to the input parameter, and then the output parameter to XML.

Figure 8

Input and output parameters in function module Z_ACCOUNT_CHG

Web Service Tool Runtime

So far we have discussed the generation steps at the design time of the Web service tool. Now, let’s have a quick look at what happens during the runtime.

All the Web services generated with the Web service tool are stateless, so we do not need sophisticated ways of buffering and session handling — tasks the BOL layer normally handles. Therefore, we use the more direct access to the business logic represented in the GenIL by bypassing the BOL. When you use a Web service, it invokes and executes the generated coding for the function modules at runtime. The coding is generic and calls the API of the underlying GenIL interfaces directly, as shown in Figure 3. By doing this, we also reach maximum performance for the Web services.

Using the Web Service Features in SAP NetWeaver

For the Web service tool we reused a standard feature that SAP NetWeaver 7.0 offers for function modules — the ability to create a Web service interface on top of function modules. The Web service tool invokes this functionality automatically when it generates a Web service. It also hands over the chosen security parameters to the SAP NetWeaver API.

You can also invoke the same functionality manually. Go to transaction SE80 (ABAP Object Navigator) and select a function module. Right-click on the function module and select Create>Web Service from the context menu. The SAP NetWeaver Web service wizard appears in a pop-up screen and guides you through the process.

Software Logistics

By looking at an example in the system, you can see that all structures, function modules, and Web services are generated in a specific namespace (/CRMOST/) in a temporary development class ($WS_BOL_GEN). This is a temporary class, which means that all generated objects are never transported through the system landscape. The only objects that are transported from the development system to the production system are the metadata of the service object maintained in the Web service tool. To initiate such a transport, you can invoke the ABAP report CRMOST_TRANSPORT via transaction SE38 (ABAP Editor). You can select the Web service objects you want to transport within this report.

The fact that only the metadata is transported has some major advantages. If any minor changes occur in the BOL between two releases, you can change your service object before you generate it again. Furthermore, it ensures that you do not transport unnecessary coding from one system to the other. For instance, by using this report you can easily transport your best practice services that you have built in your main system to other decentralized systems, where you can adapt them to local needs before you generate them.

Finally, let us leave you with a special tip for making it to the end of this article — a gift you won’t find in other documentation. With the report CRMOST_GENSTATUS_MONITOR you can summarize every generated object around your Web services. This tool is not maintained by SAP officially, but if you come across it while using the Web service generation it might serve you as a great source of help.

Markus Kupke

Markus Kupke studied physics and mathematics at the University of Vienna and Erlangen, earning a master’s degree in mathematics in the area of profinite groups and Frattini modules. He worked as a software engineer for a life insurance company until 1997. He started as a developer at SAP in 1997 in the area of Sales and Distribution-Computer Aided Selling (SD-CAS). He has experience in many areas, including SAP Enterprise Portal, SAP NetWeaver Business Intelligence, enterprise service-oriented architecture, Web services, and business-process applications, such as activity and opportunity management. Since 2004, he has been a development manager responsible for a team of 10 engineers.

You may contact the author at markus.kupke@sap.com.

If you have comments about this article or publication, or would like to submit an article idea, please contact the editor.

Thilo Berndt

Thilo Berndt is a solution manager for SAP CRM Solution Management in Bangalore. He is a graduate of the business school at the University of Mannheim, Germany. Thilo has worked at SAP since 2002. Currently, he is responsible for the SAP CRM enterprise service-oriented architecture strategy and the Web service tool.

You may contact the author at thilo.berndt@sap.com.

If you have comments about this article or publication, or would like to submit an article idea, please contact the editor.