Working with Web Service Data Controls

25 Working with Web Service Data Controls

Use a web service data control to retrieve data from a web service data source to display in your portal.

Permissions:

To perform the tasks in this chapter, you need one of the following portal-level permissions:

Assets: Create, Edit, and Delete Assets or Create Assets and Edit Assets (standard permissions)
Data Controls: Create, Edit, and Delete Data Controls or Create Data Controls and Edit Data Controls (advanced permissions)

See About Roles and Permissions for a Portal.

Topics:

About Web Service Data Controls

A web service data control is essentially a bridge that makes data from a source available to a portal.

Data retrieved from a web service by a data control can be rendered on a portal page in a custom task flow. You can select how to present the data, appropriate to the specific data control. For example, the data can be shown as a table, graph, form, button, or label. You can enable users to control the data displayed by a data control by including a parameter form along with the data presentation. You can also wire data control parameters to task flow parameters so that the data control retrieves data based on the values specified for the task flow parameters. Users can change the value of the task flow parameters in the page editor to request the corresponding data from the data control.

The basic steps to accomplish this are:

Create a data control (see Creating a Web Service Data Control).
Create a custom task flow (see Creating a Task Flow).
Add the custom task flow component to a page, then add the data control you want to render on the page (see Consuming a Data Control in a Task Flow and Controlling the Data Displayed in a Task Flow Using a Data Control).

A web service data control retrieves data from a web service that is accessed using standard protocols, such as SOAP and HTTP. You can use the objects in the data control (such as accessors, methods, and attributes) to create data-bound user interface components that you can include in a custom task flows.

To collect data from a web service, you must know the path to the Web Service Description Language (WSDL) file. The WSDL file describes the web service and specifies the methods that can be called, including the expected parameters. It also describes the returned data.

Based on the permissions you have on a web service data source, you can only provide values for the parameters specified by the methods of the web service. You cannot add or delete parameters. You can provide values for the following types of parameters:

Scalar parameters—Simple parameters for which you can directly specify string or EL values to display data.
Complex parameters—Derived parameters that take objects as parameters. They may also get their value from scalar parameters exposed by the method.
Array parameters—Enable you to pass multiple values at a time, thereby updating multiple records in the data source simultaneously.

As well as querying the data source, a web service data control may also provide an option to update records, but only if the underlying web service allows data to be updated.

Creating a Web Service Data Control

A web service data control retrieves data from a web service that is accessed using standard protocols, such as SOAP and HTTP.

To create a web service data control:

Navigate to one of the following:
- To create an application-level data control, go to the Shared Assets page. For more information, see Accessing Shared Assets.
- To create a portal-level data control, go to the Assets page for the portal in which you want to create it. For more information, see Accessing Portal Assets.
In the left pane, under Integration, click Data Controls.
In the toolbar, click Create.
In the Create New Data Control dialog, in the Name field, enter a name for the data control.

This name is displayed in the resource catalog.
In the Description field, enter a brief description of the data control.

The description is displayed in the resource catalog.
From the Data Control Type drop-down list, select Web Service and then click Continue to display the Create New Data Control wizard.
In the WSDL URL field, enter the location of the web service's WSDL file, for example:
```
http://www.example.com/exampleservice/example.asmx?WSDL
```
If the web service is on the other side of a firewall from your portal, use the Host and Port fields to configure proxy authentication.

To ensure a secure connection to the web service, you must first configure your application to use proxy authentication.
Tip:
- If a central WebCenter Portal proxy (or RSS proxy) is already configured, then the proxy fields are automatically populated with that proxy host name and port number. You can modify the proxy details or clear the fields if you do not want to configure the proxy.
  
  Changing the WebCenter Portal central proxy does not change the proxy settings against the web service data control. However, changing the web service data control proxy setting changes the WebCenter Portal central proxy setting.
- If a Web Logic Domain proxy is already configured, and if you choose not to set a proxy while creating or editing the web service data control, then the Web Logic Domain proxy is used as the default setting.
If you are connecting to a secured web service, then enter the Username and Password to access the web service endpoint.

Tip:

If access to the WSDL itself is secured, then you cannot connect to the web service from the Create New Data Control page. To work around this limitation, access the WSDL in a browser by specifying the user name and password, download the WSDL page, save it locally as a .wsdl document, then specify the path to this document in the WSDL URL field.
Click Show Methods to establish a connection to the web service using the specified WSDL and display the methods available for the web service.
From the Service drop-down list, select the service to use for the data control.
From the Port drop-down list, select one of the available ports.

The Methods field displays the methods available for the specified web service.

All methods under the selected port are added to the data control. These methods are later available for selection in the resource catalog.

Figure 25-1 Adding Web Service Methods to a Data Control

Description of "Figure 25-1 Adding Web Service Methods to a Data Control"

If the web service is secured using OWSM, use the fields in the Oracle Web Service Manager Security Policies section to specify the policies to use, as described in Table 25-1.

Table 25-1 OWSM Security Information

Name	Description
MTOM	The MOTM (message transmission optimization mechanism) policy you want to use.
Reliability	The reliability policy you want to use.
Addressing	The addressing policy you want to use.
Security	Any additional security policies you want to apply.

For example, if your web service is secured using a policy named mycompany/wss_username_token_service_policy, populate the Security field with the client policy, which is mycompany/wss_username_token_service_policy.

For more information about security policies, see Testing OWSM Security Policies in Administering Web Services.

You can override properties on the Security policy that you specified in the previous step. Use the Add Property and Remove Property buttons to add or remove entries in the Override OWSM Policy Properties table.

Tip:

Override properties are defined by the policy. Therefore, to perform this step, you must know the policy being used and the properties that you can override.

For example, if you specified a Security policy, mycompany/wss_username_token_client_policy, and the policy has a csf-key property, then in the override section, click Add Property to add a value for csf-key. Note that this key must exist in the configured keystore.

For more information about adding csf-key to the credential store, see Configuring the Credential Store in Securing Web Services and Managing Policies with Oracle Web Services Manager.
To set values for a method's parameters, select the method and click Next.

A web service may expose scalar and complex parameters that control the data displayed by the data control. For more information, see About Web Service Data Controls.

For each parameter:

Tip:

For complex parameters, you must first expand the parameter to display the scalar values that make up the parameter.
1. In the Display Name field, enter a user-friendly name for the parameter.
  
  This name is displayed to users when they consume the data control in a task flow.
2. In the Tooltip Text field, enter a brief description of the parameter.
  
  This provides users with assistance in determining the purpose of the parameter.
3. Select Show to User to display the parameter to users when they consume the data control in a task flow.
Note:

You can specify values for exposed parameters only while consuming the data control in a task flow. For more information, see Editing Data Control Parameter Values.
Click Create.

The newly created data control is listed on the Assets or Shared Assets page. The empty check box in the Available column indicates that the data control is not yet published and hence is not available for users to add to their task flows. To publish the data control, select the check box to enable users to add the data control to a task flow in the page editor (see Creating a Task Flow).

Editing a Web Service Data Control

You can modify a web service data control by selecting it and choosing the Edit quick link. The Edit dialog enables you to modify the values that you provided while creating the data control.

Note:

When you edit a web service data control, the references to this data control in task flows may be broken. Therefore, use the Edit option on a data control with caution, after considering the impact on the consuming task flows.

To fix references to edited data controls, you must edit the task flow's source files. For more information, see Editing the Source Code of an Asset.

To edit a web service data control:

Navigate to one of the following:
- To edit an application-level data control, go to the Shared Assets page. For more information, see Accessing Shared Assets.
- To edit a portal-level data control, go to the Assets page for the portal in which the data control was created. For more information, see Accessing Portal Assets.
In the sidebar, under Integration, click Data Controls.
Click the Edit quick link for the data control that you want to edit (Figure 25-2).

Figure 25-2 The Edit Quick Link for a Data Control

Description of "Figure 25-2 The Edit Quick Link for a Data Control"
The fields in the Edit Data Control page are similar to those in the Create Data Control page.

For information about these fields, see Creating a Web Service Data Control.
When you are done, click Save and Close.

Managing Web Service Data Controls

The following options are available on the Assets and Shared Assets page to enable you to manage web service data controls.