Sending A Message To PI As A Web Service
The following blog is written by Quincy Anderson—Senior Education Consultant in the North America SAP Education Delivery Organization since 1999 and is the first in a two part series dealing with Web Services from a PI perspective. Quincy specializes in the areas of ABAP, JAVA, Workflow, Process Integration, and Portal. Quincy holds both associate and professional level certifications for both ABAP and JAVA development and also associate level certifications for both Workflow and Portal development.
Recently in one of my PI training classes ( BIT400 is the 5 day training class that covers PI development and is one of the most popular classes in the SAP NetWeaver curriculum ) I noticed a large amount of interest in Web Services with PI. For most of the morning, the students ( about 11 or so as I recall ) were fairly quiet. As soon as I mentioned the word “services” I practically had to give out numbers as if we were in a meat market to make sure all the questions were answered:
“So Quincy, can you call PI as a web service?”
“Can PI call a web service instead?”
“Well wait a minute Quincy, is point to point possible if I don’t want to use PI?”
Based on this large amount of interest I decided to do a series on Web Services and PI. For easier digestibility I will break the series into two parts. Here today we will discuss sending a message to PI as a Web Service. In part two of the series we will discuss PI itself calling a Web Service. The difference is not simply semantics. The specific steps required will be different. We’ll keep the discussion practical. This isn’t a treatise on all the theoretical possibilities involving Web Services. But instead how to get something up, running, and transported over to production with minimum fuss, effort, and post transport maintenance. And of course ( and this is very important ) there will be plenty of screen shots for you to enjoy.
First let’s get a working definition of Web Services. We’ll use the one provided by W3C ( World Wide Web Consortium ) in its “Web Services Glossary”:
“[…] a software system designed to support interoperable machine-to-machine interaction over a network. It has an interface described in a machine-processable format (specifically WSDL). Other systems interact with the Web service in a manner prescribed by its description using SOAP messages, typically conveyed using HTTP with an XML serialization in conjunction with other Web-related standards.”
Figure 1
Now we don’t want to overcomplicate here so let’s basically break that above definition and it’s accompanying graphic down:
“machine-to-machine interaction”:
Web Services are based on the client \ server interaction model which means two machines namely a client machine ( known as a service requestor, hereinafter “Requestor” ) and a server machine ( known as a service provider, hereinafter “Provider” ) are interacting with one another with the Requestor initiating the communication ( by issuing a request ) and the Provider machine finalizing the communication ( by issuing a response ).
“over a network”:
The Requestor and Provider mentioned in the above paragraph must have access to one another via a network. The concept of network here is broad and vast. They can be in the same room, in another state, or now even in the cloud. As long as they have access to one another this requirement is satisfied.
“interface described in a machine-processable format (specifically WSDL)”:
For the Requestor and Provider to communicate they must agree on all aspects of the interaction. That means everything including their location ( all computers on a network must have an address identifiable on that network ), the import and export parameters needed ( after all one is “requesting” and the other is “responding” ), the data types for those parameters ( if I’m expecting a string then don’t send me a float ), and the authentication procedures to be used ( free access or encrypted certificates? ). All of the aforementioned questions are answered in a so called “WSDL Document” which is nothing more than a document with a lot of XML tags in it. But the meaning of those tags and the information described in the document will answer all the aforementioned questions.
“SOAP messages, typically conveyed using HTTP… other Web-related standards”:
SOAP is the content based format that both the Requester and Provider use to communicate with one another. SOAP is basically a standardized XML set of tags describing the content of messages being sent between the client and the server. Let’s say a sales order is being sent between the Requestor and the Provider. You and I would think of a sales order in terms of the customer number, the material ordered, the quantity, etc. That could be reflected in the following XML tags:
<customer>000000001</customer>
<material>123-456</material>
<quantity>3</quantity>
Now since these tags concern themselves with the business content of the message they would be placed in what is known as the “body” of the SOAP Message. Note below the additional tags added:
<soap:Body>
<customer>000000001</customer>
<material>123-456</material>
<quantity>3</quantity>
</soap:Body>
The message is completed by using the rest of the tags necessary for a complete “SOAP Message”:
<?xml version=”1.0″?>
<soap:Envelope xmlns:soap=” http://schemas.xmlsoap.org/soap/envelope “>
<soap:Header>
</soap:Header>
<soap:Body>
<customer>000000001</customer>
<material>123-456</material>
<quantity>3</quantity>
</soap:Body>
</soap:Envelope>
So if this is the message, then how does it get transported back and forth between the Requestor and the Provider? The answer is simple. The Internet and The World Wide Web. Both have become ubiquitous in our modern world and form the network basis for most machine to machine communication. While Web Services could *theoretically* be implemented over some other different type of network architecture the odds of this affecting you as an IT professional in the near ( or not so near ) future at this point are remote. Thus we will assume you are using the Internet \ World Wide Web for your development efforts. Thus the message above would be put inside an HTTP Packet ( the main protocol of the World Wide Web ) and transported from the Requestor to the Provider via TCP \ IP ( the main protocol of the Internet ).
One final point regarding the graphic above. You will notice toward the top a “Service Broker”. This is analogous to a phone book. Those all important WSDL documents alluded to earlier can be “published” in a repository ( technically a database ) and “discovered”. Just like you and I can look up someone’s number in a phone book. This repository is known as a “UDDI Server” and while intriguing is not strictly speaking required as part of the Web Services paradigm ( we certainly have the right to not publish our phone number if we don’t want to ). As a result, we will disregard UDDI Servers as part of our discussion.
Now that we have a working definition of Web Services, lets get a working definition of PI. Our definition today will be somewhat concise and targeted for our purposes. For a more thorough introduction as to all the capabilities of PI please refer to this excellent introductory tutorial written by Rana Brate De (http://scn.sap.com/docs/DOC-41766 ).
We’ll use the definition on SAP’s public website:
[…] quickly automate and flexibly optimize your business processes—from simple workflows to integrated processes that span applications and organizational boundries[…]
[…] Exchange data across SAP and non-SAP applications[…]
Figure 2
Figure 2 above is borrowed form Rana’s tutorial. PI ( the runtime identification of which is referred to as the “Integration Engine” in the above graphic ) is considered to be a message based “Integration Broker” because it sits in between the system sending the message (hereinafter “Sender” ) and the system receiving the message ( hereinafter “Receiver” ) and performs certain tasks on behalf of both to insure the messages are both processed and transferred successfully between the two thus ensuring a smooth running integration process that a customer could design and implement. Our sales order mentioned above could be a message that PI processes for example.
So in this blog we will look at PI being called as a Web Service. Or put another way the “Sender” is the “Requestor” and “PI” is the “Provider” ( but *not* the ultimate “Receiver of the message; that distinction is important and will be discussed further in part two of this blog series ). Or put yet a third way PI exposes itself as a Provider for purposes of the Requester being able to send a message to PI and thus take advantage of the Web Services Architecture. There are many reasons to utilize this approach but the most common is to integrate 3rd party Business Partners. In other words if you are designing an integration scenario in which you are expecting a message from your Business Partner ( whose systems you do not have access to or control of ), Web Services because they are based on standardized protocols provide an effective solution to enable PI to receive that message.
So how to do this? First since PI is message based, a message type is required. For our purposes we will use a message type named “MT_Material” contained in the Enterprise Services Repository ( hereinafter “ESR” ). Note Figure 4 below:
Figure 4
Note the fields contained in the message type in Figure 4. They represent the business data of the message ( in this case information about a material master record ) and will be present in the SOAP Body ( as discussed earlier ).
Once a message type is created then a Service Interface of type *Outbound* must be created. Outbound interface is important here. Remember PI is exposing itself as the Provider. Therefore from the Requestor’s perspective, to send a message to PI requires the utilization of an Outbound Service Interface ( Sender’s use Outbound Interfaces ). Note Figure 5 below:
Figure 5
Note in Figure 5 at the bottom that the message type “MT_Material” is in the role of “Request”. In other words the request ( and therefore the Requestor ) utilizes this message type.
Our next step is to create a “Business Component”. Business Components are created in the “Integration Directory” ( hereinafter “Directory” ). This Business Component will represent the Sender. Note Figures 6 through 8 below:
Figure 6
Figure 7
Figure 8
In Figure 9 below if you look to the left towards the bottom you will see our newly created Business Component. Notice that there are no Communication Channels yet. That is our next step.
Figure 9
This new Communication Channel will be named “SOAP_Sender_Channel” and will be of type “SOAP” and also of type “Sender”. Note Figures 10 & 11 below:
Figure 10
Figure 11
We’re getting close to the goal line now. PI doesn’t always require a “Sender Agreement” to receive a message but in this case one is required. Note Figures 12 through 14 below.
Figure 12
Figure 13
Figure 14
Now we’re ready to rock and roll. Our final step is to now actually have a Requestor send a SOAP Message. Remember that because of the trifecta of objects created in the Directory namely Business Component \ Communication Channel \ Sender Agreement ( the three of which together are linked to the Service Interface \ Message Type that are stored in the ESR ), PI is now configured to expect a SOAP Message. There are a plethora of ways to actually send this SOAP message. The Web Service Architecture specifies protocols but not their host environment. We could therefore create a Requester using ABAP, JAVA, .Net, or theoretically any programming language. For our purposes today a BSP ( Business Server Page ) will suffice. Note Figure 15 below:
Figure 15
There are two parts to this figure I would like to concentrate on. First the SOAP document itself:
<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes” ?>
<n0:Envelope xmlns:n0=”http://schemas.xmlsoap.org/soap/envelope/“>
<n0:Body>
<ns:MT_Material xmlns:ns=”urn:education.com:BIT400:A”>
<MaterialID>BIT400_00</MaterialID>
<IndustrySector>M</IndustrySector>
<BaseUnit>PCE</BaseUnit>
<MaterialGroup>00120</MaterialGroup>
<MaterialType>FERT</MaterialType>
<Description>
<Language>DE</Language>
<Description>Fahrrad</Description>
</Description>
</ns:MT_Material>
</n0:Body>
</n0:Envelope>
And second the target URL. Remember The Requestor ( in this case our BSP Application ) contacts the Provider ( in this case PI ) at the Provider’s location:
Pay particular attention to the channel parameter above ( channel=:ServiceRequestorComponent:SOAP_Sender_Channel ). This is our Business Component \ Communication Channel combination created previously. This combination provides an intuitive way to differentiate different SOAP Messages coming from different Requestors thus allowing us to also differentiate how those messages are handled.
Well that’s it. We now have a SOAP Message sent to PI and ready to be processed by PI. In my next blog we will explore the opposite side of the equation. PI calling a Web Service. Until then enjoy.