Consuming Services

This chapter discuses how to:

• Consume services.

• Access integration metadata for consumed services.

Understanding Consuming Services

PeopleSoft Integration Broker can consume external services by way of consuming WSDL documents and generates PeopleSoft integration metadata, so that PeopleSoft applications can invoke outbound synchronous and outbound asynchronous services.

PeopleSoft Integration Broker features a Consume Web Service wizard that steps you through the task of consuming WSDL documents.

Understanding the Consume Web Service Wizard

This section discusses the Consume Web Service wizard.

Consume Web Service Wizard Features

The Consume Web Service wizard supports:

• WS-interoperability standards for WSDL.

• Consumption of WSDL version 1.1 documents.

• Consuming WSDL with SOAP, HTTP–GET/POST bindings.

• Nested URIs to resolve WSDL fragments.

Operation Types Supported

You can consume WSDL documents for the following service operation types:

• Synchronous.

• Asynchronous one-way.

• Asynchronous request/response.

Sources for Consuming WSDL Document

You can use the Consume Web Service wizard to consume WSDL documents from the following sources:

• UDDI repositories.

• WSDL URL.

• WSIL registries.

• File.

• Legacy PeopleSoft WSDL documents.

Integration Metadata Created by the Consume Web Service Wizard

The Consume Web Service wizard creates the following integration metadata in the PeopleSoft system from the consumed WSDL documents:

Note. The internal name is the name that the PeopleSoft system assigns to the metadata and is the definition name that appears in the PeopleSoft system.

Messages Generated

By default, the system creates document type messages based on the message schema(s). Documents generated are restricted. To modify the document, you must use the Restricted Documents page to clear the restricted status.

If the system cannot create document type messages or if you chose not to create document type messages, it creates nonrowset-based or container messages with references to schemas.

See Also

Securing Documents

PeopleSoft Documents Technology Preface

Fault Messages

By default, the Consume Web Service wizard builds document type messages and will create a single fault message.

To read faults in document type messages generated by the Consume Web Service wizard, use the GetContentString() method of the Message object.

To process multiple faults, you can examine the stored WSDL generated by the wizard.

Another option to capturing and reading multiple faults is to clear the Build Document Messages option in Step 1 of the wizard so that the system generates nonrowset–based messages. If generating nonrowset-based messages, PeopleSoft Integration Broker creates a part message for each fault in the WSDL operation. The system then creates a container message and places the fault part messages in the container. The container message is assigned as a fault message to the created service operation.

Multiple Root Elements in Message Schemas

In a WSDL document, the schema defined in the <types> section may have multiple root elements, corresponding to multiple messages used by one or more operations. When the PeopleSoft system consumes such a WSDL document, the entire message schema contained in the WSDL document gets associated with each of the service operation messages when the PeopleSoft system generates the integration metadata.

Use the element name that appears in the Comments text box of the message definition to construct the XML data for the correct schema fragment in the message.

Delivered Queues and Nodes

PeopleSoft delivers a queue, WSDL_QUEUE, and a node, WSDL_NODE, that the Consume Web Service wizard uses as defaults.

You may use these objects or select other existing queues or nodes.

Binding Style of Consumed WSDL Documents

The binding style of consumed WSDL documents appears in the service operation definition for the consumed service. The Default Service Operation Version section of the Service Operations page features a Comments box. The binding style appears in that box.

Working with Asynchronous Request/Response Service Operations

If a WSDL document has two port types with a single input message in each operation, the Consume Web Service wizard displays step where you can convert a pair of asynchronous one-way operations to a single asynchronous request/response operation. In this step you can special the request and callback service operations and convert the operation.

Prerequisites for Consuming Services

To consume services you must set properties in the Service Configuration component as follows:

• Use the Services Configuration page to define the service namespace, schema namespace, target location, and service system status.

  See Configuring PeopleSoft Integration Broker for Handling Services.

• If consuming services from a UDDI repository, you must first specify the UDDI server and other relevant information within the PeopleSoft system using the Services Configuration-UDDI Configuration page.

  See Specifying UDDI Repositories in PeopleSoft Systems for Providing and Consuming Services.

To consume WSDL from a file, you must set the PS_FILEDIR environment variable on the machine on which the application server resides. If you do not set this variable and attempt to consume WSDL from a file, you will receive an error that the WSDL cannot be parsed.

See Setting PS_FILEDIR and PS_SERVDIR Environment Variables.

Before consuming services evaluate your security requirements.

Common Elements Used in This Chapter

See Also

http://www.w3.org/TR/wsdl

Using the Consume Web Service Wizard

This section discusses how to use the Consume Web Service wizard to:

• Select the WSDL source.

• Select a service.

• Select a service port.

• Select service operations.

• Convert asynchronous operations.

• Rename operation messages.

• Select a queue for asynchronous operations.

• Select the receiver node.

• Confirm and view results.

Step 1: Select WSDL Source

Use the Select WSDL Source page (IB_WSDL_IMP_LOC) to select the source for consuming a WSDL document. The following example shows the page:

To select the WSDL source:

1. Access the Select WSDL Source page (PeopleTools, Integration Broker, Web Services, Consume Services).

2. Select the radio button next to one of the following values and enter the information specified:

   UDDI	To consume a WSDL document from a UDDI repository, select theUDDI radio button. After you select the radio button, select the UDDI repository from the drop-down list box. To use this option, you must first specify the UDDI repository in the PeopleSoft system. See Prerequisites for Consuming Services.
   WSDL URL	To consume a WSDL document from a WSDL URL, select the WSDL URL radio button. After you select the radio button, enter the URL in the WSDL URL field.
   WSIL URL	To consume a WSDL document from a WSIL URL, select the WSIL URL radio button. After you select the radio button, enter a URL in the WSIL URL field.
   File	To consume a WSDL document from a file, perform one of the following actions: In the File field, enter the path and file name. For example: c:\temp\sample.wsdl. Browse for the file location and name. Click the Load from File button. A file upload page appears. Click the Browse button to search for and select the file location and name. Click the Upload button. The Select WSDL Source page appears with the file location and name populated in the File field.
   Legacy WSDL (Prior to 8.48)	Select this option to consume a PeopleSoft WSDL document generated from releases prior to PeopleTools 8.48.

3. At the Build Document Messages box:

   • Select the box to build document type messages for the consumed service. (Default.)

   • Clear the box to build nonrowset-based messages for the consumed service.

4. Click the Next button to proceed to the next step in the wizard.

Step 2: Select Service

Use the Select Service page (IB_WSDL_IMP_SVC) to select the services to consume. The following example shows the page:

Before selecting services to consume, you can click the View WSDL link to view the WSDL for each service. The WSDL document opens in a browser. Close the browser when you have finished viewing the WSDL document.

WSDL documents that the PeopleSoft system consumes from pre-PeopleTools 8.48 systems display in an edit box.

To select services to consume:

1. Check the box next to each service to consume.

   To clear a selection, check the box again.

2. Click the Next button to proceed to the next step in the wizard.

Step 3: Select Service Ports

If a service you select has more than one port, the Select Service Ports page (IB_WSDL_IMP_SVC2) appears. The following example shows the page:

Multiple port options only appear when you are working with asynchronous request/response operations in a WSDL document or the service has multiple bindings. Typically, when working with this operation type, you select both options.

To select service ports, in the Select column, check the box next to each service.

Step 4: Select Service Operations

Use the Select Service Operations page (IB_WSDL_IMP_OPR) to select the operations in the selected service to consume. The following example shows the page:

To select service operations to consume, in the Select column, check the box next to each service operation to consume.

Step 5: Convert Asynchronous Operations

The Convert Asynchronous Operations page (IB_WSDL_IMP_ASYNOP) appears when the system detects that you are consuming two asynchronous one-way operations. The two asynchronous one-way operations appear in the Asynchronous One-Way Operations section on the page as shown in the following example:

This page enables you to convert the two operations into a single asynchronous request/response operation type.

WSDL specification 1.1 has no standards for specifying an asynchronous request/response operation. Hence, the Consume Web Service wizard is not able to automatically detect such operations in a WSDL 1.1 document.

To make this conversion, you must specify the request operation and the callback operation, using the Request Operation and Callback Operation fields on the page. The system populates the possible values to select in each field from the operation selected.

After you make the conversion the new asynchronous request/response operation appears in the Asynchronous Request/Response Operations section of the page. The following example shows the Convert Asynchronous Operations page after making such a conversion:

To convert two one-way asynchronous operations into one asynchronous request/response operation:

1. From the Request Operation drop-down list box, select the request operation.

2. From the Callback Operation drop-down list box, select the callback operation.

3. Click the Convert button.

The single operation appears in the Asynchronous Request/Response Operations grid at the bottom of the page.

Clicking the minus button (-) at the end of a data row in the Asynchronous Request/Response grid undoes the conversion.

Step 6: Rename Operation Messages

The Rename Operation Messages page (IB_WSDL_IMP_MSGS) is shown in the following example:

When the system creates request, response and fault messages from the consumed service, it provides them with system-generated names. The previous example shows system-generated names appearing for all messages.

Use the page to rename the messages to more meaningful names. The following example shows all messages renamed:

To rename operation messages:

1. Clear the system-generated name from a message name field.

2. Enter a new name in the field.

3. Click the Next button to proceed to the next step in the wizard.

The system checks whether the user-entered message name already exists in the database and displays an error if the name exists.

Step 7: Select a Queue for Asynchronous Operations

The Select a Queue for Asynchronous Operations page (IB_WSDL_IMP_QUEUE) appears only when you are consuming asynchronous one-way and asynchronous request/response operations. The following example shows the page:

Note. This page appears only when asynchronous operations are being consumed from the WSDL document.

Use the Select a Queue for Asynchronous Operations page to select a service operation queue for an asynchronous service operation.

PeopleSoft delivers a queue, WSDL_QUEUE, to which it assigns asynchronous service operations by default. However, you can select a different queue to use.

To select a queue for asynchronous operations:

1. Click the Use Existing Queue radio button.

2. From the Use Existing Queue drop-down list box, select the queue to use for the service operation.

3. Click the Next button to proceed to the next step in the wizard.

Step 8: Select the Receiver Node

Use the Select the Receiver Node page (IB_WSDL_IMP_NODE) to select the receiving node for the service. The following example shows the page:

PeopleSoft delivers a node, WSDL_NODE, that the system uses as the receiving node by default. However, you can select a different receiving node.

If you use the Default node as the receiver node, the system adds connector property overrides to the default node in the generated service operation routing.

Note. You can apply WS-Security to services you consume using the Consume Web Service wizard. The node you select in this step determines how you implement WS-Security for these services.

See Implementing WS-Security on Services Consumed Using the Consume Web Service Wizard.

To select a receiving node for a service operation:

1. Click the Use Existing Node radio button.

2. From the Use Existing Node drop-down list box, select the receiving node to use for the service operation.

3. Click the Finish button to proceed to the next step in the wizard.

Confirm and View Results

The final page in the Consume Web Service wizard is the Confirm Results page (IB_WSDL_IMP_RSLTS) shown in the following example:

The Confirm Results page provides a WSDL Import Log. The WSDL Import log provides a summary of the WSDL import and lists the integration metadata created. The following example shows the contents of the WSDL Import Log for the example shown in this chapter of consuming a service:

Created/Updated Operation : INITIATE.
Created Request Message : LOANSVC_REQ_MSG.
Generated schema for Message : LOANSVC_REQ_MSG
Created Response Message : LOANSVC_RESP_MSG.
Generated schema for Message : LOANSVC_RESP_MSG
Created Fault Message : LOANSVC_FAULT_MSG.
Failed to generate schema for Message : LOANSVC_FAULT_MSG
Created Routing: ~IMPORTED~18003 for Operation: INITIATE
Created Operation Version: V1

The Confirm Results page also features the following page elements:

Accessing Integration Metadata for Consumed Services

After using the Consume Web Service wizard to consume a service into the PeopleSoft system, use the Service component to access, view and modify the integration metadata created.

The following example shows the service definition for the LOANSERVICE service created with the Consume Web Service wizard.

The example shows that when consuming a service, the PeopleSoft system creates active versioned service operations for all operations of the service. In addition, the system saves the consumed WSDL documents for the service operations and you can view the WSDL documents by clicking the View WSDL link.

In the Existing Operations section, click the name of the service operation to open the Service Operations component. Use the Service Operations component to view and modify service operation data and message data, add handlers, and view and modify routing definitions created by the system.

Use one of the following methods to access the Services page and access and view integration metadata for a consumed service:

• On the Consume Web Service Wizard Results page, click the View Consumed Service link.

• Select PeopleTools, Integration Broker, Integration Setup, Services and select the name of the consumed service for which to view data.

See Also

Accessing and Viewing Service Definitions