17.3 Implementing Web Services

1. Navigate to the Shared Components page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components.

      The Shared Components page appears.

2. Under Data References, click Web Service References.

   The Web Service References page appears.

1. On the Workspace home page, click the App Builder icon.

   The App Builder home page appears.

2. Select an application.

   Application home page appears.

3. Click Edit Application Properties.
4. Under Properties, enter the proxy server in the Proxy Server field.
5. Click Apply Changes.

Before you create a Web service reference based on a WSDL, you must decide how to locate the WSDL. You locate a WSDL by entering the URL to the WSDL document.

When you create a Web service reference based on a WSDL, the wizard analyzes the WSDL and collects all the necessary information to create a valid SOAP message, including:

• The URL used to post the SOAP request over HTTP(S)

• A Universal Resource Identifier (URI) identifying the SOAP HTTP request

• Operations of the Web Service

• Input parameters for each operation

• Output parameters for each operation

1. Navigate to the Web Service References page.
2. Click Create.
3. For Web Reference Type, select Based on WSDL and click Next.
4. When prompted to search a UDDI registry to find a WSDL, click No then Next.
5. In WSDL Location, enter the URL to the WSDL document.
6. For Username, enter the username required to access the WSDL.
7. For Password, enter the password required to access the WSDL.
8. Click Next.

   The Web Service Details page appears.

9. For Basic Authentication, select:

   • No - Select this option if authentication credentials are not sent as part of the HTTP request.

   • Yes - Select this option if authentication credentials are sent as part of the HTTP request. Web services that employ basic authentication usually also use the HTTPS (SSL) protocol since the username and password are sent in clear text.

10. Click Create Reference.

    The Web service reference is added to the Web Service References Repository.

11. On the Create page, the following selections are available:

    • View Web Service References - Select to go to the Web Service Reference page.

    • Create Form on Web Service - Select to create a Form for this Web Service Reference.

    • Create Form & Report on Web Service - Select to create a Form and Report for this Web Service Reference.

1. Navigate to the Web Service References page.
2. Select the View Report icon.
3. Click the Test icon for the Web Service reference you want to test.

   The Test Web Service Reference page appears. The Web service name and URL endpoint display at the top of the page.

4. From Operation, select an operation (that is, the method to be executed).
5. Under Input Parameters, enter the appropriate values.
6. Click Test.

   The message request and response appear at the bottom of the page under Messages.

When you create a Web service reference manually, you supply the necessary information to create a valid SOAP request, including:

• The URL used to post the SOAP request over HTTP(S)

• A Universal Resource Identifier (URI) identifying the SOAP HTTP request

• The SOAP envelope for the request, including any item substitutions

• Optionally the name of a collection to store the response from the Web service

1. Navigate to the Web Service References page.
2. Click Create.
3. Select Manual and click Next.

   The Create/Edit Web Service page appears.

4. Under Web Service, for Name, enter a name to identify the reference.
5. Under Service Description. make these changes:
   1. URL - Enter the URL used to post the SOAP request over HTTP. This corresponds to the soap:address location of a service port in the WSDL.
   2. Action - Enter the intent of the SOAP HTTP request (optional). The value is a URI identifying the intent. SOAP places no restrictions on the format or specificity of the URI or requires that it is resolvable.
   3. Proxy - Enter a proxy to override the application proxy for this service.
   4. SOAP Version - Select 1.1 or 1.2.
   5. Basic Authentication - Choose whether the Web service requires authentication. Select Yes or No.
6. Under SOAP Envelope, for SOAP Envelope, enter the SOAP envelope to be used for the SOAP request to the Web service.

   Note:

   You can reference items from session state in the SOAP envelope by using #ITEM_NAME# syntax.

7. Under SOAP Response, for Store Response in Collection, enter the name of a collection to store the response (optional). The response is stored in the CLOB001 column.
8. Click Create.

1. Navigate to the Web Service References page.
2. Select the View Report icon.
3. Click the Test icon for the Web Service reference you want to test.

   The Test Web Service Reference page appears. The Web service name and URL endpoint display at the top of the page.

4. If required, enter the username and password under Basic Authentication.
5. In SOAP Envelope text area, optionally edit the SOAP request envelope.
6. Click Test.

   The message request and response appear at the bottom of the page under Messages.

When you create a RESTful Web service reference, you supply the necessary information about the structure of the request and response including:

• A Universal Resource Identifier (URI) identifying the RESTful request

• The HTTP method identifying the method of the Web service

• HTTP Headers, if required, that are part of the request

• The type of input expected by the Web service

• The format of the response and how to identify the response parameters

1. Navigate to the Web Service References page.
2. Click Create.
3. Select REST and click Next.
4. For REST Details, specify the following:
   1. Name - Enter a name to identify the reference.
   2. URL - Enter the URL endpoint of the Web service.
   3. Proxy - Enter a proxy to override the application proxy for this service (optional). This setting is overridden by the proxy setting for this instance.
   4. HTTP Method - Choose the http method used for the request to the Web service. Select GET, HEAD, POST, PUT or DELETE.
   5. Basic Authentication - Select Yes to require HTTP Basic Authentication. Otherwise, select No.
   6. REST HTTP Headers - Enter the names of the HTTP headers to send with the request.
   7. Click Next.
5. For REST Input parameters, specify the following:
   1. Name - Enter the name of the input parameter expected by the method.
   2. Type - Select the input type.
   3. Click Add Parameter.
   4. Repeat steps a though c for each expected input.
   5. Click Next.
6. For REST Output parameters, specify the following:
   1. Output Format - Select XML, Text or JSON for the response format expected from the Web service.
   2. XPath to Output Parameters (XML only) - Enter an XPath expression to the relevant part of the response.

      For example:

      /ListBucketResult/Contents
      

   3. Response Namespace (XML only) - Enter the namespace corresponding to the Response XPath.

      For example:

      http://s3.amazonaws.com/doc/2006-03-01/
      

   4. Parameter Delimiter (Text only)- Enter the character or sequence that separates parameters returned from the Web service. Use \n to indicate a new line and \t to indicate a tab character.
   5. New Record Delimiter (Text only) - Enter the character or sequence that determines a new record in a text response from the Web service. Use \n to indicate a new line and \t to indicate a tab character.
   6. Name - Enter the name of the output parameter returned by the method.
   7. Path - Enter the path. If the response is XML, the path is an XPath expression to the node. If the response is Text, the path is a number. If the response is JSON, the entire response is stored in the CLOB001 column of a collection you specify.
   8. Type - Select the output type.
   9. Click Add Parameter.
   10. Repeat steps f though h for each returned output parameter.

   Note:

   Click Test to send a request to a RESTful Web service and see the response. This test process helps you specify the appropriate Output parameters.

7. Click Create.

1. Navigate to the Web Service References page.
2. Select the View Report icon.
3. Click the Test icon for the Web Service reference you want to test.

   The Test Web Service Reference page appears. The Web service name and URL endpoint display at the top of the page.

4. In the URL and Proxy Override fields, optionally edit the values for the test.
5. If required, enter the username and password under Basic Authentication.
6. Under HTTP Headers, enter appropriate values.
7. Under Input Parameters, enter appropriate values.
8. Click Test.

   The message response appears at the bottom of the page under Messages.

The Create Form and Report on Web Service Wizard creates an input form, a submit button, and a report for displaying results. You can execute this wizard directly after creating the Web service reference from a WSDL or a RESTful style Web service, or by adding a page.

Use this wizard when you expect a nonscalar result from the Web service. The Amazon Product API Web service is a good example. This Web service returns many results based on the search criteria entered in an input form.

1. Create the Web service reference.
2. After the Web service reference has been added, select Create Form & Report on Web Service.
3. For Choose Service and Operation, make these selections and click Next:
   1. Web Service Reference - Select the Web service reference.
   2. Operation - Select the method to be executed. For REST style Web references, select doREST.
   3. User Interface - Select Desktop to create a form and report for a desktop. Select jQuery Mobile Smartphone to create a form and report for a mobile phone. The jQuery Mobile Smartphone option is only available if the user interface options for the application properties have jQuery Mobile Smartphone selected.
4. For Page and Region Attributes, review the displayed attributes and click Next.

   Note:

   If the page you specify does not exist, the wizard creates the page for you.

5. For Input Items, make these selections and click Next:
   1. Identify which items to add to the form. To include an item, select Yes in the Create column. Otherwise, select No.
   2. If necessary, edit the Item Name.
   3. If necessary, edit the Item Label.
6. If applicable, specify the Item Names and Item Labels for basic authentication and click Next.

   Note:

   This step only appears if basic authentication was specified for this Web service reference when it was created.

7. For Window Service Results, make these selections and click Next:
   1. Temporary Result Set Name - Enter a name for the collection that stores the Web service result.
   2. Result Tree to Report On (Not displayed for REST style Web service references) - Select the portion of the resulting XML document that contains the information you want to include in the report.
8. For Report Parameters, select the parameters to be included in the report and click Next.
9. For Tab Options, select whether the page should have tabs and how they should be created, then click Next.
10. Review confirmation page and click Create.

1. Create the Web service reference.
2. Create a new page.

   In the Create Page Wizard:

   1. For User Interface, select Desktop to create a form and report for a desktop. Select jQuery Mobile Smartphone to create a form and report for a mobile phone. The jQuery Mobile Smartphone option is only available if the user interface options for the application properties have jQuery Mobile Smartphone selected.
   2. Select Form and click Next.
   3. Select Form and Report on Web Service and click Next.
3. For Choose Service and Operation, make the following selections and click Next:
   1. Web Service Reference - Select the Web service reference.
   2. Operation - Select the method to be executed. For RESTful style Web references, doREST is selected automatically. The Operation option does not appear for Manual style Web references.
4. For Page and Region Attributes, review the page and region attributes and click Next.

   Note:

   If the page you specify does not exist, the wizard creates the page for you.

5. For Input Items, make the following selections and click Next:
   1. Identify which items to add to the form. To include an item, select Yes in the Create column. Otherwise, select No.
   2. If necessary, edit the Item Name.
   3. If necessary, edit the Item Label.
6. If applicable, specify the Item Names and Item Labels for basic authentication, then click Next.

   Note:

   This step only appears if basic authentication was specified for this Web service reference when it was created.

7. Follow the on-screen instructions.
8. Click Finish.

The Create Form on Web Service Wizard creates a form and a submit button. You can execute this wizard after creating the Web service reference from a WSDL or on a RESTful style Web service, or by running the Create Page Wizard.

Use this wizard when you expect a scalar result from the Web service. A Web service that looks up a stock price is a good example because the input is a stock symbol and the output is the scalar value price.

1. Create the Web service reference.
2. After the Web service reference has been added, select Create Form on Web Service.
3. For Choose Service and Operation, Make the following selections then click Next:
   1. Web Service Reference - Select the Web service reference.
   2. Operation - Select the method to be executed. For RESTful style Web references, doREST is selected automatically. The Operation option does not appear for Manual style Web references.
   3. User Interface - Select Desktop to create a form and report for a desktop. Select jQuery Mobile Smartphone to create a form and report for a mobile phone. The jQuery Mobile Smartphone option is only available if the user interface options for the application properties have jQuery Mobile Smartphone selected.
4. For Page and Region Attributes, review the page and region attributes and click Next.

   Note:

   If the page you specify does not exist, the wizard creates the page for you.

5. For Input Items, make these selections and click Next:
   1. Identify which items to add to the form. To include an item, select Yes in the Create column. Otherwise, select No.
   2. If necessary, edit the Item Name.
   3. If necessary, edit the Item Label.
6. If applicable, specify the Item Names and Item Labels for basic authentication and click Next.

   Note:

   This step only appears if basic authentication was specified for this Web service reference when it was created.

7. If applicable, specify the Item Names and Item Labels for basic authentication.

   Note that this step only appears if basic authentication was specified for this Web service reference when it was created.

8. For Output Items, make these selections and click Next:
   1. Identify which items to add to the form. To include an item, select Yes in the Create column. Otherwise, select No.
   2. If necessary, edit the Item Name.
   3. If necessary, edit the Item Label.
9. For Tab Options, select whether the page should have tabs and how they should be created, then click Next.
10. Review confirmation page and click Create.

1. Create the Web service reference.
2. Create a new page.

   In the Create Page Wizard:

   1. For User Interface, select Desktop to create a form and report for a desktop. Select jQuery Mobile Smartphone to create a form and report for a mobile phone. The jQuery Mobile Smartphone option is only available if the user interface options for the application properties have jQuery Mobile Smartphone selected.
   2. Select Form and click Next.
   3. Select Form on Web Service and click Next.
3. For Choose Service and Operation, Make the following selections then click Next:
   1. Web Service Reference - Select the Web service reference.
   2. Operation - Select the method to be executed. For RESTful style Web references, doREST is selected automatically. The Operation option does not appear for Manual style Web references.
4. For Page and Region Attributes, review the page and region attributes and click Next.

   Note:

   If the page you specify does not exist, the wizard creates the page for you.

5. For Input Items, make these selections and click Next:
   1. Identify which items to add to the form. To include an item, select Yes in the Create column. Otherwise, select No.
   2. If necessary, edit the Item Name.
   3. If necessary, edit the Item Label.
6. If applicable, specify the Item Names and Item Labels for basic authentication and click Next.

   Note:

   This step only appears if basic authentication was specified for this Web service reference when it was created.

7. If applicable, specify the Item Names and Item Labels for basic authentication.

   Note that this step only appears if basic authentication was specified for this Web service reference when it was created.

8. For Output Items, make these selections and click Next:
   1. Identify which items to add to the form. To include an item, select Yes in the Create column. Otherwise, select No.
   2. If necessary, edit the Item Name.
   3. If necessary, edit the Item Label.
9. For Tab Options, select whether the page should have tabs and how they should be created, then click Next.
10. Review confirmation page and click Create.

1. Create a Web Service Reference. See "Creating Web Service References Based on a WSDL," "Creating Web Service References Manually," or "Creating a RESTful Web Service Reference."
2. Create a page.

   In the Create Page Wizard:

   1. Select Blank Page.
   2. If prompted to use a navigation menu, select No.
3. Click Edit Page.
4. Under Page Rendering or Page Processing, locate the Processes section, right click and select Create Process.

   The Create Page Process wizard appears.

5. For Process Type, select Web Services and click Next.
6. For Process Attributes, specify the following and click Next:
   1. Name - Enter the process name.
   2. Sequence - Enter the sequence for this component. This specifies the order of evaluation.
   3. Point - Select the processing point.
7. For Process, specify the following:
   1. Web Service Reference - Select the Web service reference for this process.

      If the Web reference was created from a WSDL or is RESTful style, the Operation selection appears.

   2. Operation (WSDL or RESTful style Web service references only) - Select the Web service operation this process executes.

      The Web Service Input Parameters and Web Service Output Parameters appear.

   3. Under Web Service Input Parameters, specify inputs to the Web service process:

      • Source - Select the source type.

      • Value - Select the source value.

   4. Under Web Service Output Parameters, specify where the results are stored:

      To store the results in a collection:

      • Store Result in - Select Collection.

      • Value - Enter a name for the collection.

      To store the results in items on the page:

      • Store Result in - Select Items.

      • Value - Enter the appropriate item value.

   5. Click Next.
8. For Messages, make the following entries and click Next:
   1. Success Message - Enter the message that displays on the next page when the process runs successfully.
   2. Failure Message - Enter the message that displays when an unhandled exception is raised. After any error processing stops, a rollback is issued and an error message displays.
9. For Process Conditions, make the following selections and click Next:
   1. When Button Pressed - Select that button that causes the process to run.
   2. Condition Type - Select a condition type that must be met in order for this component to be processed. If the condition type requires expressions for comparison, the Expression 1 and possibly Expression 2 fields display. Enter expressions into these fields as required.
10. Click Create Process.

1. Navigate to the page.
2. In component view, for Regions, click the Create icon.

   The Create Region Wizard appears.

3. For the region type, select Report and click Next.
4. For Region, select Web Service Result and click Next.
5. For Display Attributes, enter a region title and optionally edit the region attributes and click Next.
6. Choose whether the Web reference was created manually, from a WSDL, or is RESTful style and click Next.
7. If the Web service reference was created from a WSDL:
   1. For Web Service Reference, select the Web service reference to execute.
   2. For Operation, select the method to be executed.
   3. For Result Tree to Report On, select the portion of the resulting XML document that contains the information you want to include in the report.
   4. For Report Parameters and Options:

      • In Temporary Result Set Name, enter a name for the collection that stores the Web service result.

      • Select and deselect the appropriate parameters.

8. If the Web service reference was created manually:
   1. Select the Web service reference.
   2. Choose the SOAP style.
   3. Choose the message format.
   4. Enter the XPath expression to the node to report on.
   5. Enter the namespace for the SOAP response envelope and click Next.
   6. Enter the name of the collection where the response message is stored.
   7. Enter the names of the parameters that you want to be included in the report.
9. If the Web service reference is REST style:
   1. Select the Web service reference.
   2. Enter the name of the collection where the response message is stored.
   3. Choose the report template and the number of rows to display per page.
   4. Select the parameters to be included in the report.
10. Click Create SQL Report.

To expose a report region as a RESTful Web service, perform the following steps:

• Step 1: The Instance administrator must enable the REST provider feature in instance settings.

• Step 2: A developer must enable RESTful access to a report region.

• Step 3: The page that contains the report must not require authentication.

1. On the Workspace home page, click App Builder.

   The App Builder home page appears.

2. Select an application.
3. View the page in Component View that contains the report you want to enable.
4. Make the page public:
   1. Under Page, click the Edit All icon.
   2. Under Security, select Page is Public from the Authentication list.
   3. Click Apply Changes.
5. Enable a report region for RESTful access:
   1. Under Regions, click the name of the region that contains the report you want to enable.
   2. Under Attributes, enter a value for Static ID field. This value is used to access the report RESTfully.
   3. From the Enable RESTful Access List, select Yes.

      Note:

      The Enable RESTful Access List option only displays if RESTful access to this Oracle Application Express instance has been enabled.

   4. Click Apply Changes.

Once you enable a report for RESTful access, you need to know the endpoint URL and parameters to pass to the RESTful Web service. The endpoint URL is similar to the URL used to access this instance of Oracle Application Express followed by the resource apex_rest.getReport. For example:

http://apex.oracle.com/apex/apex_rest.getReport

The apex_rest service also has an operation to allow discoverability of RESTful enabled reports, given an application ID or alias. The response is an XML document with a description of all reports that can be accessed by RESTful Web services. This service is invoked with a URL similar to the following:

http://apex.oracle.com/apex/apex_rest.getServiceDescription?app=691

In the URL above, 691 is the numeric ID of an application. The document returned is similar to the following:

<?xml version="1.0"?>
<urn:getServiceDescriptionResponse xmlns:urn="urn:oasis:names:tc:wsrp:v1:types">
        <urn:requiresRegistration>false</urn:requiresRegistration>
        <urn:offeredPortlets>
                    <urn:PortletDescription>
                              <urn:portletHandle>employees</urn:portletHandle>
                              <urn:markupTypes>
                                        <urn:mimeType>application/xml</urn:mimeType>
                                        <urn:mimeType>application/json</urn:mimeType>
                              </urn:markupTypes>
                              <urn:groupID>1</urn:groupID>
                              <urn:description/>
                              <urn:title>EMP</urn:title>
                              <urn:keywords>
                                <urn:value>P1_JOB</urn:value>
                                      <urn:value>P1_DEPTNO</urn:value>
                              </urn:keywords>
                    </urn:PortletDescription>
        </urn:offeredPortlets>
</urn:getServiceDescriptionResponse

The portletHandle maps to the Static ID of the report region or the reportid parameter in the REST request. The groupID maps to the page id or the page parameter in the REST request. Finally, any parameters used by the SQL report are listed as children of the keywords node.