7 Manage Oracle Enterprise Scheduler Service and Jobs

The combination of work assignment controls, including specialization rules and workshifts, gives the possibility to select the kinds of job requests to be processed and decide how to allocate the request processor resources. For example, two workshifts can be defined : a day shift and a night shift to allocate processing for these periods. The day shift could have more resources allocated for a peak usage period, while the night shift could provide a different mix for its resource allocation.

By default, no work assignments are bound to a request processor and the request processor processes any ready job request. The default behavior is similar to using a request processor with no specialization rules and a workshift of 24x7 duration, all configured threads are used, and there are no limits on the number of asynchronous jobs.

The following table shows the properties that can be defined for specialization rules.

The following operators can be used to join the conditions of a rule: AND, OR (both of type binary), CONTAINS and NOT (unary). The following are sample specialization rules that can be used in a work assignment.

application = 'EssDemoApp' AND (definition = 'JobDefinition://mypackage/
Job_essdemo1' OR definition = 'JobDefinition://mypackage/LongRunningJob')

requestCategory ='Priority'

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

If a job request is specialized to two different work assignments, then either of those work assignments can process the job request depending on resource availability. Similarly, if the same work assignment is bound to two different servers, then either server may process the job request. In fact, different stages of the same request can be processed on different servers, such as preprocessing on one server and job execution on another server.

Note that the requestCategory value can be several label terms separated by a comma. In this way labels that mimic the behavior of tags can be specified, with specializations based on combinations of labels.

For example, the following labels could be defined :

",NODE1,CRITICAL,"
",NODE1,STANDARD,"
",NODE1,IMPORTANT,"

Assuming the preceding labels, a requestCategory expression such as the following examples could be written:

(requestCategory contains ',NODE1,') AND (requestCategory contains ',CRITICAL,')

(requestCategory contains ',STANDARD,') OR (requestCategory contains 
',IMPORTANT,') OR (requestCategory contains ',CRITICAL,')

If commas are used to delimit terms, every separate label term must be enclosed with the comma on both sides, as shown in the previous examples. The requestCategory expression must specify the full term including the commas to ensure that the expression does not select another term that contains the specified one.

To create or edit a work assignment, do the following:

When editing a work assignment, the following tasks can be performed:

• Change the work assignment's description.

• Change the specialization rules.

• Add a workshift or remove an existing one.

A work assignment can be deleted from the list of work assignments. Before deleting a work assignment, ensure that it is not bound to a request processor.

To delete a work assignment, complete the following steps:

To create or edit a workshift, complete the following steps:

1. From the navigation pane, expand the Scheduling Services folder, and select the Oracle Enterprise Scheduler application.

2. From the Scheduling Services menu, select Work Allocation, and then select Workshifts.

   The Workshifts page displays.

3. Click Create (or highlight an existing workshift and click Edit).

   The Create (or Edit) Workshift page displays.

   Figure 7-12 Create Workshift Page

   
   

   
   Description of "Figure 7-12 Create Workshift Page"

   
   

4. Enter the following information for the workshift.

   • Name: Enter a name for the workshift

   • Description: Enter a description for the workshift

5. In the Active Period section, select one of the following activation periods for the workshift.

   • Active 24x7: Select this option to always enable the workshift. Selecting this option disables the Duration text field.

   • Use existing schedule: Select this option to enable the workshift using a schedule previously created. Click the Browse button to display the Select Schedule window and search for the schedule using the Name and Package fields.

     In the Duration text field, enter the duration of the workshift in minutes.

   • Specify schedule: Select this option to create a schedule for the workshift. Enter a name and description for the schedule in the text fields provided.

     Choose a frequency from the Frequency drop-down list. Different options are presented based on which frequency item is chosen.

     In the Start Date field, click the Calendar button to select a date and time.

     From the Time Zone drop-down list, select a time zone for the schedule.

     (Optional) Select Use End Date, and in the End Date field, click the Calendar button to select a date and time.

     In the Duration text field, enter the duration of the workshift in minutes.

6. Expand the Advanced region. Specify the thread allocation and the asynchronous job limits.

   1. In the Thread Allocation field, enter the number of threads to be allocated to the processor when the workshift is active. If the total thread allocation of the active workshifts exceeds the number of available threads, then the threads are allocated proportionately to this workshift.

   2. In the Asynchronous Job Limits region, enter the number of asynchronous Java and PL/SQL jobs that can be active for the work assignment. This limit applies to all processors to which the work assignment is bound.

7. To save the workshift, click OK.

A workshift can be deleted from the list of workshifts. Before attempting to delete a work assignment, ensure that it is not bound to a work assignment.

To delete a workshift:

The job definitions created for an application can be viewed. The table of job definitions displays information about the jobs related to an application such as the job definition name, the full path to which it is saved, the job type, and so on.

In the Job Definitions page, an asterisk appears next to those jobs in the list that were seeded, and are not custom jobs. The asterisk also appears next to seeded jobs that have been customized.

To display job definitions, complete the following steps:

A new job definition can be created, which can then be used to create a job request for a particular application. The job definition includes the directory path of the job to be run, the name of the application with which the job definition is associated and the job type used for the job definition.

Additional properties can be defined for a job definition as follows:

• System Properties: Editable or read-only parameters can be configured to be submitted to the job request.

• Application Defined properties: Properties can be configured to be filled in by users at runtime, such as Boolean, number, and string values. Application defined properties associate parameter view objects and parameter taskflows with a particular job definition or job set. For example, an application defined property called parameterVO can be created and can be defined as its value the full name of the view object to be used in conjunction with the job definition. Alternatively, an application defined property called ParameterTaskFlow can be created with the task flow ID as its value. When the job definition runs, the application defined property defined for the job definition connects the relevant view object or task flow to the job request.

To create a job definition, complete the following steps:

1. From the navigation pane, expand Scheduling Services and select the Oracle Enterprise Scheduler application.

2. From the Scheduling Services menu, select Job Metadata and then select Job Definitions.

   The Job Definitions page displays.

3. From the Applications dropdown list, select the name of the UI application for which a job definition will be created.

   If there are applications with similar names, be sure to select the UI application. For example, if there are applications called ProjectFinancialsApp and ProjectFinancialsESSApp. Select ProjectFinancialsApp as this is the UI application.

4. Click Create to create a new job definition.

5. For the new job definition, configure the following required properties:

   • Name: Enter a name for the job definition.

   • Display Name: Enter the name to be shown for the job definition.

   • Package: Enter the path of the job to be run.

   • Description (optional): Enter a description of the job definition.

   • Job Type: From the dropdown list, select the job type that will be used for the job definition.

6. (Optional). Configure parameters, application defined properties, system preferences, and access control.

7. Click Save and Close.

Configure Application-Defined Properties for a Job

If the job definition requires additional properties to be filled in by users at runtime, these properties can be added in the Application Defined Properties tab of the job definition creation user interface.

To configure application defined properties for a job definition, complete the following steps:

1. In the job definition creation user interface, click the Application Defined Properties tab.

2. Select Actions and then select New, or click the New icon.

   The Create Application Defined Property dialog box appears.

3. In the Create Application Defined Property dialog box, enter the following information:

   • Name: Enter a name for the property.

   • Data Type: From the dropdown list, select a data type for the property. Data types include Boolean, Date, Number, and String.

   • Default Value: Enter a default value for the property.

   • Read Only: Select Read Only if the property will be shown only, not edited.

4. Click Save and Close.

Defining Parameters with Dependent Lists of Valued in Oracle Fusion Functional Setup Manager

In some cases, it is necessary to capture dependencies between interdependent parameter lists of values in the Oracle Enterprise Scheduler job definition. For example, suppose the job definition has three parameters, namely Country, State and City. In this job definition, the value of the Country parameter determines the values available in the State parameter, which in turn determines the values available in the City parameter. In this sense, the job parameters are dependent upon each other.

To define job parameters with dependent lists of values, complete the following steps:

1. Create a list of values view object with a data source and view criteria.

2. Define bind parameters for the view criteria and expose them.

3. Map the bind variable to the relevant job parameter value.

In the previous example, the City and State parameters defined in a job use the CityLovVO data source to display a list of cities in the UI. The CityLovVO data source includes a view criterion called filterByState with a bind variable called state_code. The bind variable state_code can be mapped to the value of the State parameter value such that the list of cities shown in the UI is restricted by the state selected before invoking the City list of values.

To define parameters with dependent lists of values, complete the following steps:

1. Create a job definition with parameters and a list of values view object with data source and bind variables. Be sure to mark as optional all the bind variables used for the dependent list of values view objects.

2. From the Administration menu in the global area of Oracle Fusion Applications, choose the Setup and Maintenance work area and click the All Tasks tab. Search for all tasks.

3. From the list of tasks that is displayed, select the relevant UI application that will be used to host the job definitions and parameter view objects. This Oracle Fusion application is the portlet producer application for the job.

   Click the Go to Task button.

   The Manage Job Definitions tab is displayed.

4. From the Manage Job Definitions tab, select the job definition to be edited and click the Edit button.

5. In the Edit Job Definition tab, click the Parameters tab and select the created parameter that is associated with a list of values.

6. Click the Manage Dependencies button to the right-hand side of the Delete button.

   The Manage List of Values Dependencies dialog is displayed, as shown in the following figure.

   Figure 7-17 Manage List of Values Dependencies Dialog

   
   

   
   Description of "Figure 7-17 Manage List of Values Dependencies Dialog"

   
   

7. Bind the selected criteria to the relevant job parameters defined earlier.

   1. From the Available View Criteria list, select the view criteria to be used and use the buttons to move them to the Selected View Criteria list.

   2. In the Bind Variables area, for each criteria name, from the Mapped Parameter drop-down list, select the job definition parameter to which the criteria name will be mapped.

   3. Click OK.

The job sets created for an application can be viewed.

To display job sets:

A job set is defined as either a serial or a parallel job set. At runtime, Oracle Enterprise Scheduler runs parallel job set steps simultaneously, in parallel. When a serial job set runs, Oracle Enterprise Scheduler runs the steps one after another in a specific sequence. Using a serial job set Oracle Enterprise Scheduler supports conditional branching between steps based on the execution status of a previous step.

For each step in a job set, an action to be taken upon completion of the step can be configured, depending on the state of the step. Parameters and system properties can also be configured for the job set, such as elevating access privileges to complete a particular job request or specifying the number of times a job can be retried in the event of a failure.

To create or edit a job set:

1. From the navigation pane, expand Scheduling Services and select the Oracle Enterprise Scheduler application.

2. From the Scheduling Services menu, select Job Metadata and then select Job Sets.

   The Job Sets page appears.

3. Click Create to define a new job set, or click Edit to modify an existing job set.

4. In the Job Set field, enter the name of the job set in the field provided. A description in the Description field can be added, and the name of the relevant job set Java package in the Package field.

5. In the Job Set Steps field, select Serial or Parallel to create a serial or parallel job set.

6. Add steps as required by clicking the Add icon. Define each step.

   1. In the Step tab, in the Step ID field, enter a meaningful ID for the step.

      In the Job field, enter search text and click the browsing button. In the window that appears, select the job definition that to be used for this step.

   2. In the Effective Application region, select Insert into main diagram or Add to list of available steps. If adding the step to the list of available steps is chosen, use the drop-down lists that appear to define an action for the possible job outcomes, namely On Success, On Error, and On Warning.

   3. In the Application Defined Properties tab, click the Add icon to define any required properties and enter their initial values in the field provided. For more information about defining application defined properties, see Configure Application-Defined Properties for a Job.

   4. In the System Properties tab, click the Add icon to define any system parameters required for the step.

      From the Name dropdown list, select the system property to be specified. Possible system properties are shown in the table that follows.

      In the Initial Value field, enter the value to be assigned to the system property.

      Table 7-7 System Properties

      System Property Name	Description
      SYS_allowMultPending	This property specifies whether multiple pending requests for the same job definition are allowed. This property has no meaning for a job set step. True or false.
      SYS_application	This property specifies the logical name of the Scheduling Services folder application used for request processing. This property is automatically set by Oracle Enterprise Scheduler during request submission.
      SYS_bizErrorExitCode	This property specifies the process exit code for a process job request that denotes an execution business error. If this property is not specified, the system treats a process exit code of 4 as an execution business error. This property is optional for a process job type. It is not used for other job types.
      SYS_className	This property specifies the Java executable file for a Java job request. This is the name of a Java class that implements the oracle.as.scheduler.Executable interface. This property is required for a Java job type. It is not used for other job types.
      SYS_cmdLine	This property specifies the command line used to invoke an external program for a process job request. This property is required for a Process job type. It is not used for other job types.
      SYS_effectiveApplication	This property specifies the logical name of the Scheduling Services folder application that will be the effective application used to process the request. A job definition, job type, or a job set step can be associated with a different application by defining the EFFECTIVE_APPLICATION system property. This property can only be specified through metadata and cannot be specified as a submission parameter.
      SYS_environmentVariables	This property specifies the environment variables to be set for the spawned process of a process job request.The property value must be a comma-separated list of name value pairs (name=value) representing the environment variables to be set. This property is optional for a Process job type. It is not used for other job types.
      SYS_executePast	This property specifies whether instances of a repeating request with an execution time in the past is generated. Instances are never generated before the requested start time nor after the requested end time. To cause past instances to be generated, this property must be set to TRUE and specify the requested start time as the initial time from which instances is generated. Note that a null requested start time defaults to the current time. Valid values for this property are: TRUE: All instances specified by a schedule are generated regardless of the time of generation. FALSE: Instances with a scheduled execution time in the past (that is, before the time of generation) will not be generated. Default: If this property is not specified, the system default is TRUE.
      SYS_extensionListener	This property is for internal use only.
      SYS_external_id	This property specifies an identifier for an external portion of an asynchronous Java job. For example, an asynchronous Java job usually invokes a remote process and then returns control to Oracle Enterprise Scheduler. This property can be used to identify the remote process. This property is set by the job implementation of asynchronous Java jobs when the identifier is known. It is never set by Oracle Enterprise Scheduler.
      SYS_groupName	This property specifies the name of the Oracle Enterprise Scheduler isolation group to which this request is bound. This property is automatically set by Oracle Enterprise Scheduler during request submission.
      SYS_inputList	This property specifies input to a job request. The input to a serial job set is forwarded as input to the first step only. The input to a parallel job set is forwarded as input to all the parallel steps. Oracle Enterprise Scheduler imposes no format on the value of this property.
      SYS_inputWorkDirectory	This property specifies the working directory used during job request processing for input files. Oracle Enterprise Scheduler sets the value of this property during job request processing.
      SYS_listener	This property specifies the event listener class associated with the request. This is the name of a Java class that implements the oracle.as.scheduler.EventListener interface.
      SYS_locale	This property specifies a language code to apply to the job.
      SYS_logWorkDirectory	This property specifies the logging working directory.
      SYS_outputList	This property specifies output from a request. The output of a serial job set is the OUTPUT_LIST of the last step. The output of a parallel job set is the concatenation of the OUTPUT_LIST of all the steps, in no order, with oracle.as.scheduler.SystemProperty.OUTPUT_LIST_DELIMITER as a separator.
      SYS_outputWorkDirectory	This property specifies the working directory used during job request processing for output files. Oracle Enterprise Scheduler sets the value of this property during job request processing.
      SYS_postProcess	This property specifies the postprocess callout handler class. This is the name of a Java class that implements the oracle.as.scheduler.PostProcessHandler interface.
      SYS_preProcess	This property specifies the preprocess callout handler class. This is the name of a Java class that implements the oracle.as.scheduler.PreProcessHandler interface.
      SYS_priority	This property specifies the request processing priority. The priority interval is [0...9] with 0 as the lowest priority and 9 as the highest. Default: If this property is not specified, the system default value used is 4.
      SYS_procedureName	This property specifies the name of the PL/SQL stored procedure to be called for a SQL job request. The stored procedure is specified using the schema.name format. The property is required for a SQL job type. It is not used for other job types.
      SYS_product	This property specifies the product within the application that submitted the request.
      SYS_redirectedOutputFile	This property specifies the file where standard output and error streams are redirected for a Process job request. This represents the full path of the log file where the standard output and error streams are redirected for the spawned process when the request is executed. This property is optional for Process job types. It is not used for other job types.
      SYS_reprocessDelay	This property specifies the callout handler processing delay time. This represents the time, in minutes, to delay request processing when a delay is requested by a callback handler. Default: If this property is not specified, the system default used is 5. Integer type.
      SYS_request_timeout	This property enables the job request to time out.
      SYS_requestCategory	This property specifies an application-specific label for a request. The label, defined by an application or system administrator, enables administrators to group job requests according to their own specific needs.
      SYS_requestedProcessor	This property specifies the request processor node on which the request is processed. This enables processor affinity to be specified for a job request. If this property is not specified, the request can run on any available request processor node. In general, this property should not be specified. If this property is specified for a request, the request processor's work assignments oracle.as.scheduler.WorkAssignment (specialization) must allow the execution of such requests; otherwise the request will never be executed. If the specified node is not running, the request will remain in READY state and will not be executed until the node is restarted.
      SYS_requestExpiration	This property specifies the expiration time for a request. This represents the time, in minutes, that a request will expire after its scheduled execution time. A expiration value of zero (0) means that the request never expires. If this property is not specified, the system default value used is 0. Request expiration only applies to requests that are waiting to run. If a request waits longer than the specified expiration period, it does not run. After a request starts running, the request expiration no longer applies.
      SYS_retries	This property specifies the retry limit for a failed request. If request execution fails, the request will be retried up to the number of times specified by this property until the request succeeds. If the retry limit is zero (0), a failed request will not be retried. If this property is not specified, the system default used is 0.
      SYS_runasApplicationID	This property enables elevating access privileges for completing a scheduled job. Typically, a request runs as the submitting user. However, if this property is set in the metadata of the job associated with the request, then the request executes under the user identified by this property. This property can only be specified through metadata, and cannot be specified as a submission parameter.
      SYS_selectState	This property specifies whether the result state of a job set step affects the eventual state of its parent job set. For the state of a job set step to be considered when determining the state of the job set, the SELECT_STATE must be set to true. If SELECT_STATE is not specified on a job set step, the state of the step will be included in the determination of the state of the job set. The data type is Boolean.
      SYS_sqlJobClass	This property specifies an Oracle Enterprise Scheduler job class to be assigned to the Oracle Enterprise Scheduler job used to execute a SQL job request. This property need not be specified unless the job used for a job request is associated with a particular Oracle Database resource consumer group or has affinity to a database service. If this property is not specified, a default Oracle Enterprise Scheduler job class is used for the job that executes the SQL request. That job class is associated with the default resource consumer group. It belongs to the default service, such that it has no service affinity and, in an Oracle RAC environment, any one of the database instances within the cluster might run the job. No additional privileges or grants are required for an Oracle Enterprise Scheduler SQL job request to use that default job class. This property is optional for a SQL job type. It is not used for other job types.
      SYS_submittingApplication	This property specifies the logical name of the Scheduling Services folder application for the submitted (absolute parent) request. This property is automatically set by Oracle Enterprise Scheduler during request submission.
      SYS_substitutionHandlers	This property has been deprecated.
      SYS_successExitCode	This property specifies the process exit code for a process job request that denotes an execution success. If this property is not specified, the system treats a process exit code of 0 as execution success. This property is optional for a process job type. It is not used for other job types.
      SYS_userFileDir	This property specifies a base directory in the file system where files, such as input and output files, may be stored for use by the request executable file. Oracle Enterprise Scheduler supports a configuration parameter that specifies a file directory where requests can store files. At request submission, a USER_FILE_DIR property is automatically added for the request if the configuration parameter is currently set and USER_FILE_DIR property was not specified for the request. If the property is added, it will be initialized to the value of the configuration parameter. The property will not be added if the configuration parameter is not set at the time of the request submission.
      SYS_userName	This property specifies the name of the user used to execute the request. Typically, this is the submitting user, unless the RUNAS_APPLICATIONID property was set in the job metadata. This property is automatically set by Oracle Enterprise Scheduler during the request submission.
      SYS_warningExitCode	This property specifies the process exit code for a process job request that denotes an execution warning. If this property is not specified, the system treats a process exit code of 3 as an execution warning. This property is optional for a Process job type. It is not used for other job types.
      SYS_workDirectoryRoot	This property specifies the working directory for the spawned process of a Process job request. This property is optional for a Process job type. It is not used for other job types.

   5. If the step was configured as a serial step, it appears in the job set flow diagram. Configure the action to be taken upon reaching the error and warning states, respectively. From the dropdown list for the error and warning icons, select Stop or the name of the job definition to run upon reaching an error or warning state.

      
      

      

      
      

7. Continue to define steps as required for the job set.

8. Define application defined properties and system properties as required towards the bottom of the job set window.

   These properties apply to the job set as a whole, as opposed to the properties configured earlier on the page that apply to specific steps in the job set.

9. Configure access control for the job set.

   1. In the Access Control section of the Create Job Set page, click the Add icon to add access control to the job set.

      The Add Access Control dialog box appears.

   2. From the Role drop-down list, select the name of the role to be applied to the job set. The role defines the users with sufficient permissions to access the job set.

   3. Select the actions to allow role members to take: Read, Execute, Update and then, Delete.

10. Click OK to save the job set.

To delete a job set, complete the following steps: