Accessing External Web Services from SAP WebFlow

Out there on the Web and on your intranet, there are myriad services just waiting for you to make use of them: conference bookings; "who's who" services; hotel, flight, or car reservations; fax and paging functions; procurement services… Wouldn't it be great if you could use these functions in your workflow processes as transparently as calling an SAP transaction? Well, with WebFlow, SAP's workflow technology for intranet/Internet use, this is now possible. We at SAP have implemented a service handler that enables services to be included within a workflow definition, and using plug-in technology, this is available for SAP systems even as early as Release 4.0. For example, suppose an employee needs to attend a conference. After his manager has approved the WebFlow request, the workflow sends a new work item to the employee to take care of conference registration. When the employee executes this work item, it launches a Web service, where the employee fills in his personal preferences in his Web browser. The registration confirmation number is returned to the workflow. The same procedure applies to the hotel booking and travel arrangement functions (see Figure 1), although the work item for the travel arrangements will likely be sent to a secretary or the travel department. Finally, an e-mail with a trip summary is automatically sent to the applicant and the departmental secretary. If the employee needs to cancel the trip, WebFlow can take care of it, since all the reservation numbers and details have been stored in the workflow's basic data. Figure 1 Accessing a Web Service Directly from SAP WebFlow This article describes how to add a Web service to a workflow definition, along with the add-ons you will need to support releases predating the 6.10 SAP Web Application Server. But before you add a service to your workflow definition, there are a few things you need to consider:  The Thorny Question of Standards There are a number of standards evolving to support services offered on the Web. Several have been recommended by the W3C.1 As a W3C member, SAP is actively involved in the definition of several of these standards, and it is a sure bet that some of these standards will eventually dominate the Web. However, many companies have created their services without using any interface or definition standards, simply to have the service available sooner rather than later - something particularly true of services created within a company's intranet for internal use only. In order to support the maximum number of existing services, WebFlow implementation does not depend on one standard or another. In this sense, it acts as a simple glue that binds together disparate Web services in a workflow definition. However, in contrast to Wf-XML (a "snap-on" method of integrating workflow systems with each other using a well-defined interface), when using WebFlow Web services you will need to analyze each service to determine whether or not it can be used with WebFlow. This depends on whether the service can be parameterized. Clearly the ultimate goal is to support major standards as they emerge,2 so the architecture of WebFlow Web services is in an excellent position support W3C interfaces as they are finalized.  Types of Services Supported By its very nature, workflow supports two types of processes - user interactions and automatic functions - which in turn can be conveniently mapped to two types of services. First, dialog services support user interactions, such as performing research in a search engine or selecting a hotel for a conference. The user will receive a work item in his or her inbox and execute it. At this point, the Web browser is launched with the correct URL, together with the correct parameters. The user can finish the task from within the Web browser. The second type of service consists of automatic procedures, called background services. In this case, the WebFlow system calls the URL in the background without any user interaction at all. In both cases parameters are passed from the workflow to the service, and results can be returned to the workflow. With a background service, these results can often be returned right away. In the case of dialog services, results will not be returned immediately because the user interaction will probably take several minutes. Rather than block the system while a user navigates in the Web browser, the WebFlow system surrenders control to the browser and returns to other duties until the service calls back with a result or confirmation. At this point WebFlow kicks back into action and continues with the next step. This is called an asynchronous interaction. The complete palette of services supported is shown in Table 1. You will see that it does not cover all permutations, but it does cover those that are used in practice. The distinction between these different types of services and interactions has important practical consequences. For example, with dialog services, the user has the freedom to surf off to other Web sites for additional information before completing a Web service. The user could also cancel an action and execute the work item at a later time. Asynchronous background services come in handy in cases where there is a time lag - when there might be a matter of days between sending an order (work item started) and receiving the goods-delivered acknowledgement (work item completed). Type of User Interface? Synchronous/ Asynchronous Interaction? Results Returned to Workflow? Example Dialog Synchronous No Perform a Google search Dialog Asynchronous Yes Make a hotel reservation. Background Synchronous Yes Send a preformatted pager message. Background Asynchronous Yes Send a preformatted pager message and return an acknowledgement after the message has been recieved on the mobile device. Table 1 Examples of Types of Web Services  System Landscape There are two possible landscapes for WebFlow Web services. You may either use the SAP Web Application Server as the service handler or, alternatively, use a simple standalone Java engine with XML configuration files (for those customers who do not yet have access to a 6.10 Web Application Server).3 In Figure 2, notice that WebFlow's directory of Web services does not reside in the component system. It is stored centrally, so that it can be called by any of the SAP component systems without duplicating the maintenance. In other words, if you set up one service, it can be used by all other SAP systems in your system landscape, provided they have the WebFlow Service plug-in installed and use a Basis platform that is not older than Release 4.0. The plug-in is simply an independent suite of ABAP code and database table definitions, so it is release independent. The next step is to configure a Web service and generate a workflow task that integrates that Web service. For this article, our examples will only consider the SAP Web Application Server engine, not the Java engine, although the principles are more or less identical. Figure 2 Directory of WebFlow Web Services in the SAP Web Application Server Landscape Configuring the Web Service Configuring a Web service in WebFlow's central service directory is a piece of cake using transaction wf_extsrv, shown in Figure 3. Figure 3 Definition of a Web Service In this example, we are defining a messaging Web service like the one detailed in the sidebar "Messaging from Your Workflow Using Web Services." Before completing the creation of the Web service, you will need to determine three things: Decide whether you will be using the HTTP or HTTPS (secure) protocol. Enter this into the Log field in Figure 4. Specify how the service will be called - in other words, whether it is a dialog or background service. Enter this information into the Mode field. You also need to determine whether the service returns results for processing in the workflow. A dialog task that does not return a result will be called in the Web browser, with a button in a separate frame that users will press when they want to complete the work item. Specify the parameters used by the service. When adding information in the "Parameters" screen, be careful - parameter names are often case sensitive. These parameters are not usually assigned a type (string, etc.), so you will also need to make sure that the workflow data is converted into the type that the service will expect. Each URL, like the one in our messaging example, is divided into the domain and directory (in red) and the parameters that are filled by WebFlow when the workflow executes (in purple): www.unimobile.com/services/sms?partner_phone=0049123432123 &msginv=How%are%you&partner_id=1234 This information is then stored in the WebFlow Web service directory (see the sidebar, "Messaging from Your Workflow Using Web Services"). Figure 4 Configuring the Parameters of a Web Service Messaging from Your Workflow Using Web Services A synchronous Web service can be used to send external messages* from a workflow via an external Web service, rather than by setting up a paging system within the local system landscape. In this example, we used a Web service offered by wireless data solution provider Unimobile, and were pleased to find that one telephone call and thirty minutes in the system was enough to get the scenario running. The URL generated by WebFlow looked something like this: www.unimobile.com/services/sms?partner_phone=0049123432123&msginv= How%are%you&partner_id=1234 The variable names telno, msg, and customerid are specified in the Web service directory and filled with values as the workflow proceeds. When the URL is called, Unimobile sends the SMS message to the mobile phone and the workflow continues. (Many Web services offer authentication to provide access control, but here this will not be necessary, since it is within the intranet.) The service is synchronous because the Unimobile service returns control to WebFlow immediately after putting the pager message in its queue. The handling of asynchronous Web services is slightly different, because the Web service must be capable of passing back the results to the workflow long after the workflow engine has given up control. For example, if we wanted to add a feature and design the service to terminate with an acknowledgement once the message is received (which can be a matter of hours, if the mobile phone isn't switched on until long after the message is transmitted), we would set up an asynchronous service instead. For an example that demonstrates some of the differences between asynchronous and synchronous Web services, see the sidebar "Accessing a Who's Who Service from Your Workflow." * For this demonstration, SAP used SMS (Short Message Service), a service that sends messages of up to 160 characters to mobile phones that use Global System for Mobile (GSM) communication. SMS messages do not require the mobile phone to be active and within range, and can be held for a number of days. Although GSM and SMS communication is primarily available in Europe, Unimobile, along with other companies, support the equivalent North American (and international) paging services, as demonstrated at the hands-on session at SAP TechEd 2001 in Los Angeles last November.  TIP: One quirk of this scenario is that blank spaces cannot be used in a URL, so WebFlow Service Packs convert them to escape characters before calling the URL. Using the New Service in a Workflow Process There is no need to manually create the workflow task for a Web service. Instead, it is generated directly from the Web service definition, using the Business Service Page (BSP) wf_srv_task_generate/createtask.html, which is part of the SAP Web Application Server or Java add-on. Once you pick the Web service and the component system on which the workflow will run, press the Generate task button. The task can be used just like any other task. You will notice that createtask.html generates input and export container elements that match the parameters belonging to the Web service. Bind the task into the workflow as usual by selecting the container elements that are to be passed to the Web service and those that will be returned. Accessing a Who's Who Service from Your Workflow Suppose your organization has a "who's who" service. From this service, users can choose from an employee directory to help determine, for example, the best customer service representative to contact a customer. If you want to add this feature as part of a workflow process, you would create an asynchronous Web service. An asynchronous Web service differs slightly from synchronous Web services because it must be capable of passing the results back to the workflow long after the workflow engine has given up control. It does this via a callback URL, which is passed to the Web Service as the parameter SAPWFCBURL at the time it is called. This is generated every time the work item is executed to ensure that it is unique. The who's who service requires the input parameters area, skills, and callback url, together with the export parameter Userid. The outgoing call made by the workflow system to the workflow service might look like this: http://intranet/whoiswho?area=timbuctoo&skills=engineer& SAPWFCBURL=http://intranet/webflow/abcdkdkekk3k3k3k3aka1234 The variables in the URL have been filled automatically by the workflow, and the complete URL is then generated and dispatched by WebFlow automatically. When the user executes the work item, he will see the company who's who service with a list of suitable colleagues. He can even navigate through the web site, to consult calendars or skills profiles before making his choice. Then, once he presses the Select button, the Web service will call the callback URL passed to it by WebFlow, together with the user ID of the customer service representative he selected, for example: http://intranet/webflow/abcdkdkekk3k3k3k3aka1234?Userid=USER1234 After the callback, the workflow will automatically transfer the user ID to the workflow container and continue to the next step as usual. Summary The beauty of this feature is that so many Web services already exist, especially within company intranet Web sites. These have been developed outside the SAP environment, for example, using Active Server Pages (ASP) or Java. Now these services can be used in WebFlow - and without upgrading the whole SAP component that contains the workflow definition. For more information on WebFlow Web services and how to integrate them into your workflow, or to view a recorded demonstration of how this works in practice, visit the WebFlow Service Portal at http://service.sap.com/webflow. 1 W3C (www.w3c.org) is the international industry consortium and resource for protocols, information, and applications for the World Wide Web. 2 For example, in one feasibility test we integrated a Web service using SOAP (Simple Object Access Protocol), one of the hottest Internet standards to emerge in recent years (authored by Microsoft, SAP, IBM, and others).