18.4 Managing Web Source Modules

Web Source Modules act as a reference to one or multiple external web services. A module can contain one or many Web Source Operations which are the references to a concrete external web service.

• About Web Source Modules
  
• Creating a Web Source Module
  
• Editing or Deleting a Web Source Module
  
• Copying a Web Source Module
  
• Viewing Web Service Module Utilization
  
• Viewing Web Service Module History
  

18.4.1 About Web Source Modules

How Web Sources Differ from Web Service References

Web Source Modules enable developers to access to Representational State Transfer (REST) services or generic JSON data feeds in applications applications and use the data in Application Express components such as reports, interactive reports, and interactive grids. Unlike existing Web Service References, a Web Source Module contains metadata about the Web service which can be used by Application Express Components or PL/SQL processes to invoke the service and to process the responses.

Web Source Modules contain multiple operators that differ depending upon the Web service target. For a REST services, an operation is a specific service handler (such as, GET, PUT, POST, or DELETE). Developers assign Operation a Database Action such as Fetch Multiple Rows, Fetch Single Row, Insert Row, Update Row, and Delete Row. However, you can assign each Database Operation only once to a Web Source Operation.

Integration with Application Express Components

Oracle Application Express provides direct integration of Web Source Modules classic reports, interactive reports, CSS Calendar, and JET Charts.

About Remote Servers

Oracle Application Express splits the endpoint URL of a Web Service into two parts. The server-specific part is stored as a separate entity called the Remote Server. You can reuse a Remote Server with multiple Web Source Modules if it uses the same server, port and URL Path Prefix (context root).

If you change the attributes of a Remote Server, the change impacts all Web Source Modules using the Remote Server. Remote Servers make it easy to move a collection of Web Source Modules. For example, you can move from test system to a production system by changing the URL within the Remote Server object.

About Authentication and Credentials

Web Source Modules support both Basic Authentication and the OAuth Client Credentials flow. Authentication credentials can be specified at the Remote Server-level for all Web Source Modules using the Remote Server). If credentials are set at the Web Source Module-level, that setting supersedes credentials stored at the Remote Server level.

A Credential denotes the Authentication method, a Client ID (or user name) and a Client Secret (or password). Credentials are stored as a named entity within Shared Components and can be re-used across multiple Web Source Modules or Remote Servers.

See Also:

"Managing Remote Servers" and "Managing Web Credentials"

18.4.2 Creating a Web Source Module

To create a Web Source Module:

1. Navigate to the Web Service Modules page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components in the center of the page.
   4. Under Data Sources, select Web Source Modules.
2. On the Web Source Modules page, click Create.
3. For Create Web Source Module - Method, select From Scratch and click Next.

   Tip:

   If you select, As copy of an existing web source module select the application to copy from and follow the on-screen instructions.
4. Specify the following attributes:
   1. Web Source Type - Select a web source type:
      • Simple HTTP - Denotes a simple HTTP data feed. Application Express assumes that all data is returned with the first request and that the server does not support server-side filtering, ordering or other advanced REST service feature. All invocation details and parameters must be configured manually. Use this Web Source Type if the REST service is neither an ORDS or Oracle Cloud SaaS service (see below).
      • Oracle REST Data Services - Denotes ORDS (Oracle REST Data Services) REST Services. These REST services follow the Oracle REST standard, which means that GET, POST, PUT or DELETE operations are standardized. Server-side filtering and ordering are supported. Application Express can leverage these features by delegating report order-bys and filters to the REST service.
      • Oracle Cloud Applications (SaaS) REST Service - Denotes RESTful web services provided by Oracle Cloud SaaS Applications. Use this web service type to integrate Oracle SaaS REST Services into your Application Express Application. Application Express supports pagination for these Services.
   2. Name - Enter a descriptive name for this Web Source Module.
   3. Endpoint URL - Enter the Endpoint URL (starting with http:// or https://) for this web source.
   4. Remote Server - Select Create New or select an existing Remote Server object.
      The HTTP Endpoint URL of a Web Source Module consists of the remote server (Base URL) and the service specific part. Remote Servers are stored as separate Entities.
   5. Base URL - Enter the Base URL.
      The URL endpoint of the web source module consists of the Base URL (starting with http:// or https://) and the service path suffix being appended to that. The Base URL is stored as a Remote Server object and can be shared between multiple web source modules. Note that the Base URL can (and frequently should) be more than just the server name and the port. Most often the first parts of the URL path (for example the context root) are also server-specific. For example: http://myserver.com:8080/myservices/test/.
   6. Service URL Path - Enter the service-specific URL Path for this Web Source Module. The HTTP Endpoint URL is built by appending this to the Base URL specified in the Remote Server object. For example: /services/customers/.
   7. Click Next.
5. For Authentication Required, select Yes or No to determine whether the new Web Source Module requires Authentication.
6. To proceed, select one of the following buttons:
   • Create Module Manually - This option does not include Web Source Discovery mode. Based on the previously entered information, a Web Source Module is created with a few sample operations and a sample data profile. Create Module Manually creates an incomplete Web Source Module that is unusable with an Oracle Application Express component. To correctly reflect the external web service, you will need to edit the web source operations and the data profile.
   • Advanced - Presents advanced parameters for the Data Profile. Use Response Sample to upload a sample JSON (or XML) response. Once a file is uploaded, Oracle Application Express performs a Data Profile Discovery on the uploaded file.
   • Discover - Starts Web Source Discovery mode. Oracle Application Express executes multiple HTTP requests in order to get information about the external Web service. Application Express samples the data (JSON or XML) returned by the Web service and derives a Data Profile (consisting of metadata about the JSON attributes). Discovery results then display and confirms whether to create the Web Source Module.
7. If you click Advanced, the Parameter page appears. Advanced enables you to configure some initial Web source parameters which might be required for discovery. Some Web sources may require you set specific HTTP Headers (for example, User-Agent). After setting advanced parameters, select either Discover or Create Module Manually buttons.
8. If you select Discover, Application Express invokes the REST service URL and a Preview appears. From the JSON response, Application Express derives attributes and their data types and uses this to create a Data Profile.

   The information that displays depends upon the complexity of the target service. For simple HTTP services or ORDS services which do not provide metadata about their JSON response attributes, Application Express investigates the JSON or XML response, samples the data, and creates a proposal for a data profile. The Data tab displays the sample response data, formatted as a report.

   The columns tab shows information about the data profile columns Application Express has found during discovery. Use this tab to verify whether the column data types are correct.

   Click More Detail to view additional tabs that show more detailed information about the Web Source response, such as the response body, response headers and the Web Source operations.

9. Click Create Web Source.
   The Web Source Module is created.

18.4.3 Editing or Deleting a Web Source Module

To edit or delete a Web Source Module:

1. Navigate to the Web Service Modules page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components in the center of the page.
   4. Under Data Sources, select Web Source Modules.
2. On the Web Source Modules page, under Module Name, click the name of the Web Source Module.
3. To delete the Web Service Module, click Delete. Otherwise, edit the attributes.

   Note:

   A Web Source Module can only be deleted, if no Oracle Application Express component is referencing it.
4. Under Web Source Module:
   1. Name - Enter a descriptive name for this Web Source Module.
   2. Web Source Type - Options include:

      • Simple HTTP  - Select this option for a simple HTTP data feed. Application Express assumes that all data is returned with the first request and that the server does not support server-side filtering, ordering or other advanced REST service feature. All invocation details and parameters must be configured manually.

      • Oracle REST Data Services - Select this option for Oracle REST Data Services (ORDS) REST Services. These REST services follow the Oracle REST standard, which means that GET, POST, PUT or DELETE operations are standardized. Server-side filtering and ordering are supported. Application Express can leverage these features by delegating report 

      • Oracle REST Data Services (Legacy Syntax) - Select this option for services powered by older versions of ORDS (Oracle REST Data Services). These services are not completely compliant to the Oracle REST Standard.

      • Oracle Cloud Applications (SaaS) REST Service - Select this option for RESTful services provided by Oracle Cloud Applications (SaaS). Use this web service type to integrate Oracle SaaS REST Services into your Application Express Application. Application Express supports pagination for these Services.

   3. Remote Server - Choose a Remote Server object for this web source. To learn more, see field-level Help.
   4. Base URL - Lists the Base URL.
   5. URL Path Prefix - The URL Path Prefix is specific to this Web Source Module. The URL Endpoints of all operations within the Web Source Module share the same URL Path Prefix. To learn more, see field-level Help.
5. Subscription lists Web Source Modules that subscribe to this module.
6. Under Data Profile:
   1. Click Edit Data Profile to change how Web source responses (in XML or JSON) format are being parsed and converted to rows and columns.
      The Data Profile page appears.
   2. Under Data Profile and Columns, edit the attributes.
      Row Selector stores an XML or JSON path expression pointing to the node containing the collection of rows. Columns determine how one row is parsed and converted to multiple columns.
   3. Click Apply Change to save your changes.
7. Under Operations:
   1. Operation - Click Add Operation to add a Web Source Operation. A web source Operation contains the actual information about the external web service handler. 
      The Web Source Operation page appears.
   2. Under Operation and Operation Parameters, edit the attributes.
      Operations can be mapped to Database Operations which enables Application Express components to pick up the correct operation. Reports, interactive reports or CSS calendars will pick up the operation which is mapped to the Fetch Rows database operation.
   3. Click Create .
8. Under Authentication:
   • Credentials - Choose stored credentials for authentication.
9. Under Module Parameters:
   1. Click Add Parameter to configure a Web Source Parameters.
      Use thee parameters to pass HTTP Request Headers, use dynamic URLs, or request bodies. When a parameter, its type, default value, and direction is declared on the Edit Web Source Parameter page, Application Express components can reference it.
   2. Click Add Parameter.
10. Under Advanced:
    • Static ID -Use the Static ID to reference the Web Source Module in API Calls.
    • Pass ECID - Select Yes or No to indicate whether to pass the ECID to the external web services for end to end tracing.
    • HTTP Transfer Timeout - Specify a timeout value in seconds. When an HTTP request for this web source value exceeds the timeout value, the end user sees an error message. This is to prevent non-responding pages due to an unresponsive web service.
    • Comments - Enter Comments or notes.
11. To save your changes, click Apply Changes.

18.4.4 Copying a Web Source Module

To copy a Web Source Module:

1. Navigate to the Web Service Modules page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components in the center of the page.
   4. Under Data Sources, select Web Source Modules.
2. On the Web Source Modules page, click Copy.
3. On Copy Web Source Module:
   1. Copy Web Source Module - Select an existing Web Source Module.
   2. New Web Source Module Name - Enter a new name.
   3. Click Copy.

18.4.5 Viewing Web Service Module Utilization

To view Web Source Modules utilization:

1. Navigate to the Web Service Modules page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components in the center of the page.
   4. Under Data Sources, select Web Source Modules.
2. On the Web Source Modules page, click Utilization.
   The Utilization page displays where a Web Source Module is used within the application.

18.4.6 Viewing Web Service Module History

To view recent modifications to Web Source Modules:

1. Navigate to the Web Service Modules page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components in the center of the page.
   4. Under Data Sources, select Web Source Modules.
2. On the Web Source Modules page, click History.
   The History page displays recent modifications made to Web Service Modules in the current workspace.