PeopleSoft SOAP Integration

Although web services can certainly be more complex than other integration methods, there is a lot of horsepower and potential benefit from a web services approach, especially when there is a requirement for near real-time integration.

Following is an overview of how to consume a SOAP web service in PeopleSoft, call the web service from PeopleCode, and parse the response message.

Overview of SOAP

SOAP is a lightweight protocol intended for the exchange of structured information between distributed systems.  SOAP uses XML to provide an extensible and flexible messaging framework.  A SOAP message consists of three parts:

• Envelope: This required element identifies the XML document as a SOAP message.
• Header:  This optional element contains application-specific information about the SOAP message.  If the Header element exists, it must be the first child element of the Envelope element.
• Body:  This required element contains the actual message information intended for the recipient.

SOAP messages can be transported via various transport protocols, but the most common protocol for use over the Internet is HTTP.

Web Services Description Language (WSDL)

WSDL is an XML document used to describe a web service, including the location of the service and the available operations for the service.

Example Web Service

For the purpose of this example, assume that you have a third-party, web-based system which houses data on new applicants who have applied online, and you want to import this data into PeopleSoft via a "GetApplicants" web service provided by the third-party.

Our example web service will accept a date and an API key, and will return a response message with all of the applications for that date.  A sample request message is structured as follows:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope>
  <soap:Body>
    <GetApplicants xmlns="http://www.example.com/">
      <APIKey>123456789</APIKey>
      <Date>2012-04-14</Date>
    </GetApplicants>
  </soap:Body>
</soap:Envelope>

The response message will return the id, name, birthdate, and declared major for each applicant, as shown in the following example:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope>
  <soap:Body>
    <GetApplicantsResponse xmlns="http://www.example.com/">
      <Applicant>
        <Id>12345</Id>
        <Name>Smith, John</Name>
        <Birthdate>1982-08-25</Birthdate>
        <Major>Computer Science</Major>
      </Applicant>
      <Applicant>
        <Id>12346</Id>
        <Name>Jones, Sally</Name>
        <Birthdate>1983-11-04</Birthdate>
        <Major>Engineering</Major>
      </Applicant>
    </GetApplicantsResponse>
  </soap:Body>
</soap:Envelope>

PeopleSoft Consume Web Service Wizard

Oracle has delivered a wizard which will interrogate the WSDL URL for a web service, and then build the appropriate PeopleSoft components within Integration Broker for using that web service.  To set up the "GetApplicants" web service using the Consume Web Service Wizard:

1. Navigate to: PeopleTools > Integration Broker > Web Services > Consume Web Service
2. Select WSDL Source:
1. Choose "WSDL URL" and paste in: "http://www.example.com/webservices.wsdl"
2. Click "Next".
3. Select the appropriate Service and click "Next".
4. Select Service Ports: Check the row for "SERVICESOAP" and click "Next".
5. Select Service Operations: Check the row for "GetApplicants" and click "Next".
6. Rename Operation Messages: Click "Next".
7. Select the Receiver Node: Click "Finish" to accept "WSDL_NODE" as the default node.

This process will create a Service Operation named "GetApplicants", as well as the Request and Response Message definitions associated with the Service Operation.

Invoking a Synchronous Web Service from PeopleCode

From here, we can invoke the Service Operation from PeopleCode using delivered Integration Broker PeopleCode libraries.  The PeopleCode is actually very simple:

import PS_PT:Integration:*;
&reqStr = "<Request XML from above...>";
/* (1) Create Request Message from Service Operation */
&reqMsg = CreateMessage(@("Operation.GetApplicants"));
/* (2) Create XML Document from Request XML Text String */
&inXml = CreateXmlDoc(&reqStr);
/* (3) Set XML Document on Request Message */
&reqMsg.SetXmlDoc(&inXml);
/* (4) Invoke SyncRequest for Request Message */
&respMsg = %IntBroker.SyncRequest(&reqMsg);
/* (5) Get XML Document from Response Message */
&outXml = &respMsg.GetXmlDoc();

If we wanted to print the raw XML response to a log or to a text area on the screen, we can return a formatted XML string using the following PeopleCode:

/* (6) Display Returned XML Text String */
&outXml.GenFormattedXmlString();

You've successfully made the round-trip from PeopleSoft to the third-party web service and back.  You now have response data which can be manipulated according to your business need.

Parsing the Response Data

The last piece is to deconstruct the XML response so that data can be loaded appropriately into your system.  The following PeopleCode will isolate the Applicants from the XML response and print the Id and Name for each applicant to a popup Message:

/* Pull out all of the Applicant elements into an array */
Local array of XmlNode &applicantList;
& applicantList = &outXml.DocumentElement.GetElementsByTagName("Applicant");
  
/* Print the number of Applicants to a Message */
MessageBox(%MsgStyle_OK, " ", 0, 0, "Applicants: " | &applicantList .Len);

/* Iterate over the Applicants and print the Id and Name for each */
&i = 0;
While & applicantList.Next(&i)
    MessageBox(%MsgStyle_OK, " ", 0, 0, " Applicant " | &i | ": Id(" | &applicantList.Get(&i).GetChildNode(1).NodeValue | ") Name(" | &applicantList.Get(&i).GetChildNode(2).NodeValue | ")");
End-While;

For our example Response message from above, which had two Applicants, this PeopleCode would fire two Message popups, with the following text in each:

Applicant 1: Id(12345) Name(Smith, John)
Applicant 2: Id(12346) Name(Jones, Sally)

Now that we know how to get the actual data values, we have all of the pieces we need to evaluate and take action on the response data.  From here, a common exercise would be to load a staging table or possibly load a delivered Component via a Component Interface.