Understanding Web Service Adapters

The system provides tools to communicate with an external system using certain types of web services. The base product provides a configuration object called Web Service Adapter that provides the following functionality:

WSDL import. An implementer can use the WSDL import functionality to read the WSDL details into the system
Internal API generation. The system generates internal data areas that have 2 purposes: they provide the API for custom code to define the appropriate input and output data for the web service call using Oracle Utilities Application Framework schema language. In addition, the web service dispatcher uses element mapping defined in the data areas to transform the internal XML into the structure expected by the external system as described in the WSDL.
Defines the URL needed to perform the web service call at runtime.

The following points highlight limitations associated with the types of web services that the system supports:

It is possible for one WSDL document to contain definitions for several web services. The system currently supports only one port or service per WSDL document.
It is possible for a WSDL to support multiple message patterns. The system currently supports only request / response.

The following topics describe the system functionality in more detail.

Importing a WSDL

The configuration of a Web Service Adapter starts by identifying the WSDL (the web service description language document used to define the interface) provided by the external system. The following steps describe the base product functionality provided to allow a user to import a WSDL.

Navigate to the Web Service Adapter page in add mode and select the appropriate base business object.
Enter a meaningful Web Service Name and appropriate descriptions.
Provide the URL of the given WSDL.
Click Import to retrieve the details of the WSDL. The system parses the WSDL details and populates the WSDL Service Name, WSDL Source, WSDL Port, URL and a list of Operations (methods) defined in the WSDL.
Determine which Operations should be active based on the business requirements for invoking this web service. Active operations are those that the implementation is planning to invoke from the system. These require appropriate request and response data areas generated for them. The following section provides more information about that.
Specify the appropriate Security Type to configure the type of security to use when invoking this web service.
Save

At this point, a web service adapter record is created in pending status. The next step is to generate the request and response data areas for the operations configured as active.

Generating Request and Response Data Areas

Each active operation for the web service adapter requires a pair of data areas, request and response, that represent the request and response XML messages for the operation.

The base product provides steps to generate the data areas as follows:

As described in the Importing a WSDL section above, the operations listed in the WSDL are generated for the web service adapter and the implementer should indicate which operation to activate.
After saving the pending web service adapter, the display lists all the active operations and for each one includes a Generate button.
After clicking Generate for an operation, a window appears where the names of the new Request and Response Data Areas may be defined. Click Save to generate the data areas.

The generated data areas provide the API for the implementer to use when implementing the web service call in an appropriate algorithm or service in the system. The data areas contain the appropriate mapping from the elements that the implementer works with in the code that invokes the web services and the WSDL definitions.

To facilitate the generation of the request and response data areas, the base product invokes a special business service used to create the appropriate mapping. The business service is defined as a BO option on the Web Service Adapter business object. This allows an implementation to provide a custom business service to further enhance the request and response mapping where appropriate.

Note:

Generated data areas. It is possible to edit and modify the generated data areas after they are created. An implementer can change element names or remove unneeded elements if desired. Manually changing the generated data areas must be done only when absolutely necessary. The system is not able to validate manual changes. Issues with the data areas would only be detected at run time.

Activating Web Service Adapters

The business objects provided by the base package for web service adapters include a simple lifecycle of pending and active. Configure the web service adapter and its data areas while in pending status and activate it when it is ready to be implemented in the appropriate system functionality.

Invoking Web Services

To make a call to a web service using a web service adapter, the system has provided a Web Service Dispatcher business service (F1-InvokeWebService) to submit a web service call. The calling program is responsible for retrieving all the information to correctly populate the request data required by the web service call before invoking the business service.

Note:

Refer to the detailed description of the business service for more information.