13 Creating and Using Web Service Jobs
This chapter describes how to use Oracle Enterprise Scheduler to create Web Service jobs and contains the following sections:
13.1 Introduction
Web services provide a standard means to expose services on the web. Web services are accessible from a URL and use SOAP and XML as their payloads. Web services are described by the WSDL standard that defines the interface and the URL of the web service.
The following are examples of web services
-
SOA suite composites
-
Oracle Service Bus proxy services
-
ADF Business Component web services
Web services can expose one-way, synchronous, or asynchronous operations. A one-way web service operation is a fire-and-forget operation where the web service does not return a response. A synchronous web service operation returns a response as part of the same web service invocation. Typically, a web service client blocks until the synchronous operation response is received. An asynchronous web service operation involves two one-way messages: one for the web service operation request and a separate one for the response. Asynchronous web service operations typically represent long running operations. A web service client invokes an asynchronous web service operation, but does not wait for the response. Instead, the client specifies a callback URL at which to receive the response from the web service. The web service processes the request in the background and uses a callback operation to return the response to the client-specified callback URL.
Oracle Enterprise Scheduler supports web service jobs that use synchronous, one-way and asynchronous interfaces. The web service job definition can be defined using JDeveloper (as part of a hosting application or client application) or using Oracle Enterprise Manager Fusion Middleware Control. When the web service job type is selected, a wizard leads the user through a simple set of steps to define the web service job (see the example in Using Oracle Enterprise Manager Fusion Middleware Control to Create a Job Definition). This wizard obtains the WSDL URL and asks the user to select the WSDL service, port type, and operation. It then creates sample XML for the payload based on the WSDL, and allows the user to update it. Asynchronous and synchronous web service may optionally have a designated operation for cancel. If there is a cancel operation, the operation is selected and the sample XML code for the cancel operation is modified. The wizard populates a set of predefined system properties in the job definition with values entered or derived from what the user enters in the wizard.
Note:
The WSDL URL in a web services job type must be a concrete WSDL URL. It cannot be an abstract WSDL URL.
The job definition can have user defined parameters. Elements or attributes in the invoke or cancel payload XML code can specify that one of these parameters be plugged in as the element value by specifying a token substitution instruction. For example, plug in the parameter customerID with the token substitution command ${ESS_REQ:customerID}. This allows the job submitter to just enter parameter values and have the XML payload constructed from them. Token substitutions can also be specified for the WSDL base URL and WSDL relative URL system properties. For more information about token substitution see Using Tokens and Logical Clusters .
Web service jobs are secured by Oracle Web Services Manager (OWSM) policies. In Oracle Enterprise Manager Fusion Middleware Control or JDeveloper, you can attach OWSM directly attached policies for the job definition for the invocation (client policy) and the callback (service policy) actions. You can use globally attached policies to define policies globally or you can secure individual job definitions with directly attached policies.
Note:
See the following sections in Securing Web Services and Managing Policies with Oracle Web Services Manager for more information about using Oracle Web Services Manager (OWSM) policies:
Progress messages are supported for asynchronous web service jobs. These messages are written to the job log. In the callback operation, the job can indicate if the job succeeded or failed. The callback message comprises the job's output
13.2 Predefined Web Service Job Types
Oracle Enterprise Scheduler supports three predefined web services job types. The job type you specify in the web service job definition implicitly determines whether the configured web service operation is invoked using an asynchronous, synchronous or one-way (fire-and-forget) operation.
As described in Introduction, Oracle Enterprise Scheduler supports three predefined web service job types. The web service predefined job types are shown in Table 13-1.
Table 13-1 The Predefined Web Service Job Types
| Predefined Job Type | Description |
|---|---|
|
|
(Asynchronous) The caller invokes the web service, the web service runs asynchronously in the background, and the web service calls back to the caller at a callback URL |
|
|
(Synchronous) The caller blocks until the response is returned (request/response) |
|
|
(One-way) The caller does not expect a response. The web service runs in the background (fire-and-forget). |
13.3 Cancel and Fault Support
Supporting a cancel operation for web service jobs is optional. The web service may support a cancel operation that allows a running web service invocation to be canceled.
The cancel operation must not be an abort operation (hammer-on-head style), where the composite is terminated and never calls back to complete the original operation. A well-behaved cancel implementation by a web service provider ensures the original web service operation returns an "operation canceled response," with a predefined wsa:Action code (see Table 13-2) in the SOAP response header. The cancel web service operation must be a synchronous web service operation.
Both synchronous and asynchronous web service jobs can indicate whether the web service operation was canceled or resulted in a fault (error) by specifying the appropriate value in the wsa:Action SOAP response message header. If the callback response SOAP message does not match the “Canceled" or “Fault" response (through one of the mechanisms listed below), then the job state is “Succeeded".
The Table 13-2 shows the different web service operation statuses that can be specified using the SOAP wsa:Action header.
Table 13-2 SOAP Web Service Operation Statuses
| Action Code Name | Action URI |
|---|---|
|
Cancelled |
"http://xmlns.oracle.com/schedulercallback/wsOperationCancelled" |
|
Fault |
|
The Oracle SOA Suite does not support setting wsa:Action message headers. As an alternative you can add one of the strings listed in Table 13-3 to the SOAP body element of a callback message.
Table 13-3 Oracle SOA Suite Status Operations
| Operation | String |
|---|---|
|
Cancelled |
"wsOperationCancelled" |
|
Fault |
"wsOperationFault" |
13.4 Configuration Properties for Web Service Jobs
Oracle Enterprise Scheduler uses specific configuration properties for web service jobs.
Table 13-4 lists the properties associated with the web service job type.
Table 13-4 Web Service Job Configuration Properties
| Property Name | Description |
|---|---|
|
|
The base URL part of WSDL URL. |
|
|
The relative part of the web service WSDL URL (must be a concrete WSDL URL). Either the |
|
|
The base URL part of endpoint URL. |
|
|
The relative part of the web service endpoint URL (must be a concrete WSDL URL). Either the |
|
|
The target name space. |
|
|
The service name. |
|
|
The port name. |
|
|
The operation name. |
|
|
The XML submit message used to invoke the web service. |
|
|
Optional. The cancel operation name. |
|
|
Optional. The XML message for the web service cancel operation. |
|
|
Optional. The supported values are “ADFBC", “OSB" or “SOA". Any other value is invalid. |
Footnote 1
This property can be specified using token substitution. Refer to Using Tokens and Logical Clusters for more information.
If the SYS_EXT_wsEndpointBaseUrl property and the SYS_EXT_wsEndpointUrl property are specified in the job definition, Oracle Enterprise Scheduler has enough information to invoke the web service. If the SYS_EXT_wsEndpointBaseUrl and SYS_EXT_wsEndpointUrl properties are not specified in the job definition and the SYS_EXT_wsWsdlBaseUrl and the SYS_EXT_wsWsdlUrl properties are specified, Oracle Enterprise Scheduler retrieves the WSDL at runtime (before invoking the job), gets the EndpointUrl and TargetNamespace property values from the WSDL and invokes the web service.
The SYS_EXT_wsServiceName, SYS_EXT_wsPortName and SYS_EXT_wsOperationName properties must be specified to identify the specific web service operation to be invoked.
The SYS_EXT_invokeMessage property contains the XML message (SOAP body payload) for invocation. This can either be an XML template or full XML.
An XML template contains tokens that are replaced at runtime. The job submitter specifies the parameter values to substitute for the tokens in the template. If full XML is used without tokens, no substitution is required and the specified XML in the job definition is used “as is" for job invocation.
Note:
The angle brackets (“<“and “>") in XML statements must be escaped.
After it is invoked, the remote web service can log progress messages to update its status. These messages are logged by the web service job and are available in the request logs. The web service response XML is captured as job output.
If the SYS_EXT_wsCancelMessage and SYS_EXT_wsCancelOperationName properties are configured with a cancel message, the message is invoked when a cancel operation is initiated on a running web service job. The cancel operation is always invoked as a synchronous web service operation.
The cancel message SOAP header is automatically populated with the WS-Addressing relatesToId property set to the wsa:messageId associated with the invoke web service operation. The cancel operation uses the same OWSM policy as the invoke operation. If the SYS_EXT_wsCancelMessage property is not configured, it indicates that the web service does not support cancellation and therefore cannot be canceled.
The SYS_externalJobType property allows web service job definitions to specify a web service type (ADFBC, Service Bus or SOA). Intended for future customized web service job implementations.
13.5 Oracle Web Services Manager Policy Configuration
The web service job type uses decoupled Oracle Web Services Manager (OWSM) policy subjects (Job-Invoke, Job-Callback) and associated globally attached policies and directly attached policies for web service invocation and callback operations.
The Job-Invoke policy subject is associated with all web service job types (one-way, synchronous and asynchronous), whereas the Job-Callback policy subject is available only for the asynchronous web service job type. The Job-Invoke and Job-Callback globally attached policies can be specified at the domain level and configured using EM or WLST.
If a Job-Invoke globally attached policy or a directly attached policy is not specified for a web service job definition, an attempt is made to invoke the web service anonymously. This only works for the one-way and synchronous job type, because anonymous callbacks are not supported for the asynchronous web service job type.
Job-Invoke and Job-Callback directly attached policies are specific to individual web service job definitions and are captured in the policy assembly descriptor associated with the web service job definition. These directly attached policies can be specified at design time using JDeveloper or at runtime using Oracle Enterprise Manager Fusion Middleware Control, or using WLST commands.
Globally attached policies for web service job policy subjects can be set up using Oracle Enterprise Manager Fusion Middleware Control or using a WLST script to configure domain-level globally attached policies for web service job policy subjects. Example 13-1 shows how such a script might look.
Example 13-1 WLST Script to Configure Globally Attached Policies
connect(adminuser, adminpassword, adminurl)
beginRepositorySession()
deletePolicySet('domain-default-job-invoke-client-policies')
describeRepositorySession()
commitRepositorySession()
beginRepositorySession()
deletePolicySet('domain-default-job-callback-service-policies')
describeRepositorySession()
commitRepositorySession()
print "-- create domain-default-job-invoke-client-policies --"
beginRepositorySession()
describeRepositorySession()
createPolicySet('domain-default-job-invoke-client-policies', 'job-invoke', 'Domain("*")')
attachPolicySetPolicy("oracle/wss11_saml_token_with_message_protection_client_policy")
describeRepositorySession()
commitRepositorySession()
print "-- create domain-default-job-callback-service-policies --"
beginRepositorySession()
describeRepositorySession()
createPolicySet('domain-default-job-callback-service-policies', 'job-callback', 'Domain("*")')
attachPolicySetPolicy("oracle/wss11_saml_or_username_token_with_message_protection_service_policy")
describeRepositorySession()
commitRepositorySession()
13.6 Creating a Web Service Job Definition
Both Oracle JDeveloper and Oracle Enterprise Manager Fusion Middleware Control offer convenient graphical user interfaces to help you create web service job definitions.
Using Oracle JDeveloper to Create a Job Definition describes how to use Oracle JDeveloper to create a job definition and Using Oracle Enterprise Manager Fusion Middleware Control to Create a Job Definition describes how to use Oracle Enterprise Manager Fusion Middleware Control to do the same.
13.6.1 Using Oracle JDeveloper to Create a Job Definition
You can use Oracle JDeveloper to create a web service job definition while creating your application. Refer to Using Oracle JDeveloper to Generate an Oracle Enterprise Scheduler Application for general information about how to use Oracle JDeveloper to create applications that work with the Oracle Enterprise Scheduler.
JDeveloper provides accessibility options, such as support for screen readers, screen magnifiers, and standard shortcut keys for keyboard navigation. You can also customize JDeveloper for better readability, including the size and color of fonts and the color and shape of objects. For information and instructions on configuring accessibility in JDeveloper, see Oracle JDeveloper Accessibility Informationin Developing Applications with Oracle JDeveloper.
The following steps show you how to create a job definition for an asynchronous web service job type.
- Navigate to the Job Definition tab. Fill in the Name, Display Name, and Description fields and choose an appropriate web service job type as shown in the example in Figure 13-1. Have the WSDL URL for the target web service available.
Figure 13-1 Oracle JDeveloper: Job Definition Tab
Description of "Figure 13-1 Oracle JDeveloper: Job Definition Tab" - Click the Web Service Explorer button to launch the Web Service configuration wizard as shown in Figure 13-2. Enter the WSDL URL, the Service, Port, Operation and configure the payload XML as shown in the example, then click OK.
Note:
The example shown in Figure 13-2 shows the invoke XML payload with the substitutable token
SubmitArgument1, whose value is provided at submission request time. Token substitution is described in Using Tokens and Logical Clusters .Figure 13-2 Oracle JDeveloper: Web Service Popup
Description of "Figure 13-2 Oracle JDeveloper: Web Service Popup" - Click the Specify Security Policies button as shown in Figure 13-3. Select For Request to configure the directly attached policy for the Job-Invoke policy subject.
Figure 13-3 Oracle JDeveloper: Job Definition Tab
Description of "Figure 13-3 Oracle JDeveloper: Job Definition Tab" - The Job-Invoke policy subject is available for all web service job definition types (one-way, synchronous and asynchronous. Select and attach the required OWSM client policy for the Job-Invoke directly attached policy. You should see a screen like the one shown in Figure 13-4.
Figure 13-4 Oracle JDeveloper: ESS Web Service Policies Popup
Description of "Figure 13-4 Oracle JDeveloper: ESS Web Service Policies Popup" - This completes directly attached policy configuration for a synchronous or one-way web service job definition. For asynchronous job definitions, you can also configure the directly attached policy for the Job-Callback policy subject.
To configure a Job-Callback directly attached policy for an asynchronous job definition, repeat step 3 of this procedure and instead of For request, select For callback. Select and attach the required OWSM service policy for the Job-Callback directly attached policy as shown in Figure 13-4.
Note:
Post deployment, you can use Oracle Enterprise Manager Fusion Middleware Control to change job policies associated with web service job definitions.
Figure 13-5 Oracle JDeveloper: ESS Web Service Policies Popup
Description of "Figure 13-5 Oracle JDeveloper: ESS Web Service Policies Popup"
13.6.2 Using Oracle Enterprise Manager Fusion Middleware Control to Create a Job Definition
This procedure shows how to use the Oracle Enterprise Manger to create and configure a web service job definition.
- Fill in the Name, Display Name, and Description fields and choose the appropriate web service job type from the Job Type dropdown as shown in the example in Figure 13-6.
Figure 13-6 Fusion Middleware Control Console: Create Job Definition Page
Description of "Figure 13-6 Fusion Middleware Control Console: Create Job Definition Page" - Click the Select Web Service button and enter the WSDL URL in the Select Web Service popup window. After you enter the URL, select the Service, Port Type, Operation and configure the Invoke Operation XML payload.
The example shown in Figure 13-7 shows the invoke XML payload with the substitutable token
SubmitArgument1, whose value is provided at submission request time.Note:
Token substitution is described in Using Tokens and Logical Clusters .
Figure 13-7 Fusion Middleware Control Console: Select Web Service Popup
Description of "Figure 13-7 Fusion Middleware Control Console: Select Web Service Popup" - After you create the job definition, return to the Job Definitions page and select the job definition name (“AsyncWSJob1" in this example) in the Results table. Click the Attach/Detach Policy button and select Invoke as shown in Figure 13-8 to configure the directly attached policy for the Job-Invoke policy subject. The Job-Invoke policy subject is available for all web service job type definitions.
Figure 13-8 Fusion Middleware Control Console: Job Definitions Page
Description of "Figure 13-8 Fusion Middleware Control Console: Job Definitions Page" - In the Web Services Policy page, select the policy and click the Attach/Detach button to attach the required OWSM client policy for the Job-Invoke directly attached policy. This is shown in Figure 13-9. The Attach/Detach Policies popup is displayed.
Figure 13-9 Fusion Middleware Control Console: Web Service Policies Page
Description of "Figure 13-9 Fusion Middleware Control Console: Web Service Policies Page" - Select the policy and click OK to complete the attachment.
Figure 13-10 Fusion Middleware Control Console: Policy Attachment Popup
Description of "Figure 13-10 Fusion Middleware Control Console: Policy Attachment Popup"