Performing Basic Administration Tasks

3 Performing Basic Administration Tasks

This chapter describes how to create and configure the infrastructure on which Oracle Enterprise Scheduler runs. Oracle Enterprise Scheduler is installed with applications for which it provides scheduling services. However, before you begin using Oracle Enterprise Scheduler, you might have to configure its infrastructure.

This chapter includes the following sections:

3.1 Introduction to Performing Basic Administration Tasks

Oracle Enterprise Scheduler is installed by the product that includes it in order to provide job scheduling services for the product. However, it might be necessary for you to select deployment of Oracle Enterprise Scheduler explicitly during domain creation, or to configure aspects of Oracle Enterprise Scheduler before you can get the most out of the service.

Among the basic administration tasks you might need to perform are:

Installing Oracle Enterprise Scheduler and creating a domain that includes Oracle Enterprise Scheduler components.
Configuring Oracle Enterprise Scheduler by configuring a cluster, request processor, and request dispatcher. While a cluster is optional (Oracle Enterprise Scheduler can run on a single node), a processor and dispatcher are required in order for Oracle Enterprise Scheduler to do its work.
Starting and stopping the service instance, its request processors or request dispatchers.
Manage application and role policies or service web services.

3.2 Installing Oracle Enterprise Scheduler

Oracle Enterprise Scheduler does not have its own installer, but is installed by the installer of the embedding product such as Oracle SOA Suite. Refer to the embedding product's installation documentation for details.

The IDE is installed by the design time installer of the embedding product (for example, the Oracle SOA Suite design time installer). The installer installs the IDE and automatically configures it to Oracle JDeveloper. Before you run JDeveloper, make sure to set the variable MW_HOME to the middleware home location as required by the IDE.

The Oracle Enterprise Scheduler runtime component is installed by the design time or production installer of the embedding product (for example, Oracle SOA suite). The embedding product may automatically deploy Oracle Enterprise Scheduler, but if it does not, then it can be deployed using the “Oracle Enterprise Scheduler Service Basic" template to a server or cluster. The “Oracle Enterprise Manager Fusion Middleware Control Plugin for ESS" template must be deployed and selected to enable Oracle Enterprise Scheduler functionality in Oracle Enterprise Manager Fusion Middleware Control.

3.2.1 Targeting Oracle Enterprise Scheduler During Domain Creation

If the Oracle Enterprise Scheduler is not automatically targeted by the embedding product, you must select the Oracle Enterprise Scheduler basic template when the domain is created. By default, the Oracle Enterprise Scheduler is targeted to a default server called ess_server1. You can use the following procedure to target it to a different server (for example a SOA server):

When you extend SOA with Oracle Enterprise Scheduler, ess-server1 is created and the ESS-MGD-SVRS server group is targeted to ess_server1 by default. Use the following steps to target Oracle Enterprise Scheduler to soa_server1:
1. Check ESS-MGD-SVRS for soa_server1.
2. Uncheck ESS-MGD-SVRS for ess-server1.
3. Delete ess_server1.

3.2.2 OWSM-PM Targeting With Oracle Enterprise Scheduler

OWSM-PM is intended to be targeted to just one server in a domain. To facilitate this requirement, Oracle Enterprise Scheduler templates no longer target OWSM-PM. If another product in the domain automatically targets OWSM-PM, then there is nothing to do. However, if there are no managed servers in the domain except for Oracle Enterprise Scheduler, or none of these servers has OWSM-PM, then OWSM-PM must be targeted manually.

3.2.2.1 Targeting OWSM-PM Manually

In the Fusion Middleware Configuration Wizard, select the Managed Servers, Clusters and Coherence check box as shown in Figure 3-1.

Figure 3-1 Fusion Middleware Configuration Wizard

Description of "Figure 3-1 Fusion Middleware Configuration Wizard"

On the Managed Server screen, for ess_server1, select the WSMPM-MAN-SVR server group. ESS-MGD-SVRS should already be selected.

3.3 Configuring Perl to Support Process Jobs

To complete domain setup, you may need to configure Perl to support process jobs. Oracle Enterprise Scheduler optionally uses Perl for supporting process jobs.

For more information see "How to Create and Store a Process Type Job Definition" in Oracle Fusion Middleware Developer's Guide for Oracle Enterprise Scheduler.

You do this in the Enterprise Manager.

In Enterprise Manager, from the Scheduling Service menu, choose Configuration > Application Properties.
Configure the ESS level property in ESSAPP called PerlCommand to the perl executable location. For example, PerlCommand = c:\Perl\bin\perl.exe.
Perl version is 5.10 or higher.
ESS locates perl in the following order:
1. From the configuration above.
2. If WL_HOME is defined, it looks here: $WL_HOME.../../webtier_mwhome/webtier/perl/bin/perl.
3. Otherwise, it uses it from the container's path.

3.4 Configuring Oracle Enterprise Scheduler

You can run Oracle Enterprise Scheduler as a single instance or as a cluster of servers. Each Oracle Enterprise Scheduler server includes a request processor and dispatcher, both of which must be configured.

Configuring Oracle Enterprise Scheduler involves the following main steps:

Configure a cluster. Optionally, configure a cluster of Oracle Enterprise Scheduler servers.
Configure the request processor. Configure the Oracle Enterprise Scheduler component which receives and manages job requests.
Configure the request dispatcher. Configure the Oracle Enterprise Scheduler component that polls the request processor for job requests and dispatches jobs.

This section contains the following topics:

3.4.1 Expanding an Oracle Enterprise Scheduler Cluster

An Oracle Enterprise Scheduler cluster is created when the WebLogic domain is created. You may want to expand the cluster to handle a larger load. You can add new cluster nodes to an Oracle Enterprise Scheduler cluster from the Oracle WebLogic Server Console.

When scaling out an Oracle Enterprise Scheduler cluster with an additional managed server, it may be undesirable for the new server to immediately begin processing requests in the default work assignment. This could be the case if all other servers have work assignments bound in standard mode. If one or more of the running servers is using the default work assignment, however, then the present work allocation is compatible with a server using the default work assignment.

When you add a new server to an existing cluster, it may be undesirable for the new server to immediately start processing requests in the default work assignment. This could be the case if all other servers have work assignments bound in standard mode. If at least one of the running servers uses the default work assignment, this implies that the present work allocation is compatible with a server using the default work assignment.

Oracle Enterprise Scheduler provides protection for a new server so the user has an opportunity to perform work allocation before the server starts processing jobs. When a newly created server starts for the first time, Oracle Enterprise Scheduler determines whether using the default work assignment could be problematic and if so, binds a pre-seeded internal work assignment (ESSInternalWA) which includes a health check job. The user can use the health check job to check the server, and then unbind the internal work assignment and bind a user-created work assignment as needed.

Note that when determining if the default work assignment can be used, Oracle Enterprise Scheduler considers all running servers in the group and it is irrelevant what applications are deployed to the servers. Servers that are down are not taken into account.

For more information about work assignments, see Managing Work Assignments.

For more information about expanding a cluster using Oracle WebLogic Server Console, see Oracle WebLogic Server Administration Console Online Help..

3.4.2 Configuring a Request Processor

If no work assignment bound to a request processor, the default work assignment processes job requests. The binding of work assignments provides control over what jobs run at what times and with what resources. A binding can be made in one of two modes: standard (the default) or exclusive.

Standard binding mode means the request processor can process job requests as defined by the specialization rules when an active workshift is defined. If a job request is specialized to two different work assignments, either of those work assignments or the default work assignment can process the job request.

When using exclusive binding mode, job requests specialized to the work assignment are processed exclusively by that work assignment when it is active. These job requests are excluded from all other work assignments, including the default work assignment. If the work assignment does not have an active workshift, then the job request can be processed by another work assignment.

As an example, consider the following work assignments:

LongWA, specialization is (definition = 'JobDefinition://mypackage/LongRunningJob')
SamWA, specialization is (definition = 'JobDefinition://mypackage/LongRunningJob' AND user = 'sam')

Suppose both LongWA and SamWA are bound in standard mode. When Sam submits LongRunningJob, either LongWA or SamWA can process the request.

Suppose LongWA is bound in standard mode and SamWA is bound in exclusive mode. When Sam submits LongRunningJob, only SamWA can process the request. The exclusive binding causes the specialization for LongWA to act as if it is:

(definition = 'JobDefinition://mypackage/LongRunningJob') AND NOT (definition 'JobDefinition://mypackage/LongRunningJob' AND user = 'sam')

which is effectively:

(definition = 'JobDefinition://mypackage/LongRunningJob') AND NOT (user = 'sam')

Note:

Be careful about using the exclusive binding mode when your specializations overlap. For example, if you bind both LongWA and SamWA in exclusive mode, then SamWA cannot run LongRunningJob at all. In this case, the specialization for SamWA becomes:

(definition = 'JobDefinition://mypackage/LongRunningJob' AND user = 'sam') AND NOT (definition = 'JobDefinition://mypackage/LongRunningJob')

Requirements for binding a work assignment are as follows:

The work assignment must be enabled, meaning its active flag must be set.
The work assignment must have at least one workshift.
Each workshift in the work assignment must have a thread allocation of at least one.
If the workshift includes a schedule, the following must be true:
- The schedule must be active, meaning it is not expired.
- The workshift duration must be at least one.
A work assignment can be bound to a particular server at most one time.
A work assignment can be bound to any number of servers in the group, but all bindings must use the same mode. Within a group, a work assignment cannot be bound in standard mode on one server and exclusive mode on another server.

For more information about work assignments, see Managing Work Assignments.

To configure a request processor:

From the navigation pane, expand the Scheduling Services folder and select the Oracle Enterprise Scheduler application.
From the Scheduling Services menu, select Request Processor and then select Configure.
Under the Enable Request Processor field, enable or disable the request processor. Select the Enable Request Processor check box to turn on request processing.
Optionally, under the Work Assignment Bindings section, bind a work assignment to the request processor.
- Add: To bind a work assignment to the request processor, click Add.
  
  From the Select Work Assignment popup window, select a work assignment from the list and click OK.
- Remove: To delete a work assignment binding from the job request processor, select a work assignment from the list of bindings and click Remove.
- Exclusive Binding: Select to bind a work assignment exclusively to the request processor. The binding applies even if the work assignment is not enabled in the work assignment definition, or if the server is down. If a work assignment is bound to multiple servers, all the servers to which it is bound must use the same binding mode.
Optionally, under the Advanced Configuration section, configure the number of threads and the starvation threshold in minutes.
- Thread Count: In the text field, enter the number of threads you want the processor to handle.
- Starvation threshold (min): In the text field, enter the starvation threshold in minutes. The starvation threshold specifies the wait time for job requests.
Click Apply to save your changes.

3.4.3 Configuring a Request Dispatcher

Use the Configure Request Dispatcher page to enable or disable the job request dispatcher. You can also configure the polling interval for the request dispatcher.

Requests remain in waiting state in the Oracle Enterprise Scheduler repository, until the request dispatcher polls the repository for requests that are ready to run. After polling the repository, the dispatcher sets all requests to ready state. The request processor takes over control of the job requests after they have been placed in ready state.

The default maximum polling interval is 15 seconds.

To configure a request dispatcher:

From the navigation pane, expand the Scheduling Services folder and select the Oracle Enterprise Scheduler application.
From the Scheduling Services menu, select Request Dispatcher and then select Configure.
Under the Enable Request Dispatcher field, enable or disable the request processor.

Select the Enable Request Dispatcher check box to turn on request dispatching.
Optionally, under the Advanced Configuration section, configure the polling interval for the request dispatcher. In the Maximum Poll Interval field, enter the minimum interval at which the dispatcher polls for requests.
Click Apply to save your changes.

3.5 Searching for Configuration Changes to Oracle Enterprise Scheduler in Cloud Control

You can search for changes made to configurations to Oracle Enterprise Scheduler using the search page in Cloud Control.

To search for changes to configurations to Oracle Enterprise Scheduler in Cloud Control:

Display the alerts for Oracle Enterprise Scheduler as described in Viewing Alerts for Oracle Enterprise Scheduler in Cloud Control.
In the Monitoring and Diagnostics pane, click the number of configuration changes to display the search page for configuration changes to Oracle Enterprise Scheduler alerts.

Description of the illustration schedule_ess_search_config.png
Configure your search as desired.
- Target Type: Select the Scheduler Service or Scheduler Service Group.
- Target Name: Search for or enter the name of the target you want to search. From the dropdown list, select the criterion by which you want to search for the target name: contains, is, is not, does not contain, starts with, or ends with.
- Type of Change: From the dropdown list, select the type of configuration change for which you want to search.
- Show History Records: From the dropdown list, select the way you want the records to display, Grouped or Show All.
- Include Member Target Changes: Select to display configuration changes made to members of the target.
- Changes Discovered in Last: Select to search for changes discovered within a given number of days, weeks or months.
- Changes Discovered: Select to search for changes discovered within a particular time period. Use the After and Before fields to enter the relevant time period.
Click Search to search for the changes.

3.6 Starting and Stopping Oracle Enterprise Scheduler Components

You can start up and shut down an instance of Oracle Enterprise Scheduler from Fusion Middleware Control.

The following components can be started and stopped:

Oracle Enterprise Scheduler instance.
Job request processor and dispatcher.

Note:

Stopping an Oracle Enterprise Scheduler instance or component is not recommended. Shutting down an Oracle Enterprise Scheduler component does not stop job requests from accumulating in the queue.

This section contains the following topics:

3.6.1 Starting and Stopping an Oracle Enterprise Scheduler Service Instance

The Control menu for the scheduling service allows you to start an Oracle Enterprise Scheduler instance and consequently begin managing scheduled job requests.

Note:

Stopping an Oracle Enterprise Scheduler instance or component is not recommended.

To start up an instance of Oracle Enterprise Scheduler:

From the Scheduling Service menu, select Control.
Select Start Up.

To shut down an instance of Oracle Enterprise Scheduler:

From the Scheduling Service menu, select Control.
Select Shut Down.

3.6.2 Starting and Stopping a Request Processor or Dispatcher

You can start or stop a configured request processor or dispatcher from the Scheduling Service menu.

Note:

Stopping an Oracle Enterprise Scheduler instance or component is not recommended.

To start or stop a request processor or dispatcher:

From the navigation pane, expand the Scheduling Services folder and select the Oracle Enterprise Scheduler application.
Start the request processor or request dispatcher as follows.
- From the Scheduling Services menu, select Request Processor and then select Start OR on the Home page, select a request processor in the Scheduler Components area and click on the Start button.
- From the Scheduling Services menu, select Request Dispatcher and then select Start OR on the Home page, select a request dispatcher in the Scheduler Components area and click on the Start button.
Stop the request processor or request dispatcher as follows.
- From the Scheduling Services menu, select Request Processor and then select Stop OR on the Home page, select a request processor in the Scheduler Components area and click on the Stop button.
- From the Scheduling Services menu, select Request Dispatcher and then select Stop OR on the Home page, select a request dispatcher in the Scheduler Components area and click on the Stop button.
When prompted as to whether or not to stop the processor or dispatcher, click OK.

3.7 Starting and Stopping a Request Processor Dispatcher

You can start or stop a configured request processor or dispatcher from the Scheduling Service menu.

Note:

Stopping an Oracle Enterprise Scheduler instance or component is not recommended.

To start or stop a request processor or dispatcher:

From the navigation pane, expand the Scheduling Services folder and select the Oracle Enterprise Scheduler application.
Start the request processor or request dispatcher as follows.
- From the Scheduling Services menu, select Request Processor and then select Start OR on the Home page, select a request processor in the Scheduler Components area and click on the Start button.
- From the Scheduling Services menu, select Request Dispatcher and then select Start OR on the Home page, select a request dispatcher in the Scheduler Components area and click on the Start button.
Stop the request processor or request dispatcher as follows.
- From the Scheduling Services menu, select Request Processor and then select Stop OR on the Home page, select a request processor in the Scheduler Components area and click on the Stop button.
- From the Scheduling Services menu, select Request Dispatcher and then select Stop OR on the Home page, select a request dispatcher in the Scheduler Components area and click on the Stop button.
When prompted as to whether or not to stop the processor or dispatcher, click OK.

3.8 Managing Application Properties

You can configure Oracle Enterprise Scheduler interaction with applications by setting application properties. On the Application Properties page in Fusion Middleware Control, you can set values for properties that are defined by Oracle Enterprise Scheduler or properties specified for the application in its deployed configuration.

Oracle Enterprise Scheduler defines the following properties that you configure on the Application Properties page:

RequestFileDirectory: Specifies the directory for request and log output. The default is "{ESS_ENV:jrfServerLogPath}/ess_request/".
RequestFileDirectoryShared: Specifies a flag indicating whether the request file directory is shared. The default is "false".
PerlCommand: By default, Oracle Enterprise Scheduler uses the Java agent handler for requests in standard and extended mode. It always uses the Perl agent handler for requests in Fusion mode. To use the Perl agent handler in standard and extended request modes, you must add the PerlCommand property to the ess-config.xml file associated with the hosting application running the process job as shown in the following example:
```
<EssProperties>
   <EssProperty key="RequestFileDirectory" value="/tmp/ess/requestFileDirectory"/>
   <EssProperty key="RequestFileDirectoryShared" value="false"/>
     ...   
   <EssProperty key="PerlCommand" value="/usr/bin/perl"/>
</EssProperties>
```
You can use token substitution to specify environment dependent values like directory names.

The Oracle Enterprise Scheduler Perl agent handler requires Oracle Perl version 5.10 or later. Instructions for installing Perl to support process jobs can be found in Configuring Perl to Support Process Jobs.
EssCallbackClientSecurityPolicyURI: Specifies the security policy URI used in the WS-Security headers for web service invocations from Oracle Enterprise Scheduler for web service callbacks. The default is null.
ClusterMode: Specifies whether the server instance is in standalone or extended mode. This is a read-only and immutable property.
HostingAppPolicyStripe: An Oracle Enterprise Scheduler configuration property that is applicable only for the predeployed native hosting application. This property is preconfigured in the predeployed native hosting application to support multiple security stripes that can be leveraged by SOA and OSB applications. There is no static definition of policy stripes in the predeployed native hosting application's ejb-jar.xml file. The list of stripes (for additional components) can be extended dynamically using a runtime configuration MBean, Fusion Middleware Control or WLST scripts.
ServerURL: The value of this property value is a string with the following format:

http://host:port

It is used at runtime to determine the ESSWebService end point address and is published as part of the ESSWebService concrete WSDL.
CallbackServerURL: The value of this property is a string with the following format:

http://host:port

It is used at runtime to determine the end point address of Oracle Enterprise Scheduler callback web services (including EssAsyncCallbackService, and EssWsJobAsyncCallbackService). These end point addresses are published as part of the respective WSDLs.

To edit application properties:

From the navigation pane, expand the Scheduling Services folder and select the Oracle Enterprise Scheduler application.
From the Scheduling Services menu, select Configuration and then select Application Properties.

The Application Properties page displays.
In the Application dropdown field, select the application for which you want to set properties.
In the Configuration Properties section, locate the property whose value you want to change, then enter a new value in the Value column for that property.
To add a property, click Add.

The Add Property dialog box appears.
To delete a property, click Delete.
From the Type dropdown, select the new property's type.

Select ESS to choose a property defined by Oracle Enterprise Scheduler, then select the property's name from the Name dropdown. Enter the property's value in the Value text field.
Select another type to enter the name and value for another property.
Click Add to save the new property setting.
On the Application Properties page, click Apply to save application properties changes.

3.8.1 Job Location Properties

Oracle Enterprise Scheduler provides the means by which EJB and web service jobs can define a named abstract job location. The job location is specified by the Oracle Enterprise Scheduler SYS_logicalClusterName system property and specifies a logical cluster name (LCN). If the job definition for an EJB or web service job specifies a value for an LCN, certain environment-specific properties are specified using Oracle Enterprise Manager Fusion Middleware Control at the hosting application level rather than in the job definition. All job definitions with the same LCN share the value of the properties entered in the hosting application configuration properties using Oracle Enterprise Manager Fusion Middleware Control.

Note:

The terms "logical cluster" and "job location" can be used interchangeably.

To use the job location feature:

From the navigation pane, expand the Scheduling Services folder and select the Oracle Enterprise Scheduler application.
From the Scheduling Services menu, select Job Metadata and then select Job Definitions. Select a job definition from the Results table to open the Job Definitions Details page.
In the System Properties section, set the SYS_logicalClusterName system property to a name that you use to define the set of location related properties in the Application Properties page.
From the Scheduling Services menu, select Configuration and then select Application Properties.
Select the hosting application in the Application dropdown menu.
In the Job Location Properties section of the Applications Properties page, click the Add Job Location icon.

The Add Job Location dialog box appears.
In the Job Location field, enter the name you assigned to the SYS_logicalClusterName system property in step 3.

Fill in the values for the three fields that correspond to the properties shown in Table 3-1.

Table 3-1 Job Location Properties

Field	Property Name	Description
JNDI Provider URL	`JndiProviderUrl`	The JNDI provider for the cluster. Used with the EJB job type.
Web service endpoint base URL	`WsEndpointBaseUrl`	The host and port. Used with the web service job type.
Web service WSDL base URL	`WsWsdlBaseUrl`	The host and port of the WSDL. Used with the web service job type.

Click Add to save the new property setting.
On the Application Properties page, click Apply to save any application properties changes.

Note:

You can also delete job locations and properties by selecting them in the table and then clicking Delete Job Location or Delete Property.

3.9 Managing Application and Role Policies

To control access to Oracle Enterprise Scheduler data and metadata, you can create application roles to represent users and user groups, then grant them access to specific application resources.

This section describes how to create application roles. You might also be interested in the following sections:

For more on granting access to metadata, see Managing Metadata Security for Jobs in Managing the Work of Oracle Enterprise Scheduler Jobs.
For more on granting access to data, see Configuring Simple Data Security for Job Requests in Managing Oracle Enterprise Scheduler Requests.

3.9.1 Managing Application Roles

Using Fusion Middleware Control, you can create application roles with which you later associate people and access privileges.

From the navigation pane, expand the WebLogic Domain folder and select the domain for which you're creating policies.
From the WebLogic Domain menu, select Security and then select Application Roles.

The Application Roles page displays.
In the Search section, from the Application Stripe dropdown, select the application stripe with which you want to work.
Click Create.

The Create Application Role page displays.
In the General section, in the Role Name field, enter the name for the application role you're creating.
Optionally, enter a display name and description in the fields provided.
In the Members section, click Add to search for members to add to the role.
In the Add Principal window, in the Search section, from the Type dropdown select a principal type. You can also add name information to narrow your search.
Note that the Type values are as follows:
- An Application Role type is another application role.
- A Group is a WebLogic Server user group.
- A User is a WebLogic Server user.
Click the Search button to search for a principal based on the type and name you specified.
In the Searched Principals section, select the name of a principal you want to add to the role.
Click OK.
In Create Application Role page, click OK.

3.10 Managing Oracle Enterprise Scheduler Web Services

Oracle Enterprise Scheduler web services are Oracle Infrastructure Web Services.

For information about managing the web services, see Understanding Oracle WSM Policy Framework in Administering Web Services.

Note:

Oracle Enterprise Scheduler web services cannot be invoked from a web browser.

3.10.1 Securing Web Services

You can use either globally attached policies or directly attached policies to configure OWSM policies for Oracle Enterprise Scheduler web services and Oracle Enterprise Scheduler asynchronous callback web services.

Note:

Both the Oracle Enterprise Scheduler web service and asynchronous callback web service are Oracle Infrastructure Web Services.

Instructions for attaching globally and directly attached OWSM policies is documented in Attaching Policies in Securing Web Services and Managing Policies with Oracle Web Services Manager. Specifically, the following sections can be especially useful when configuring globally attached or directly attached policies for Oracle Enterprise Scheduler web services: