5 Managing the Work of Oracle Enterprise Scheduler Jobs

This chapter describes how you can add metadata to refine Oracle Enterprise Scheduler job logic, including how to add work specifics, group jobs into meaningful sets, assign schedules that guide when the work occurs, and create exceptions, such as when jobs should not run simultaneously.

This chapter includes the following sections:

• Introduction to Managing the Work of Oracle Enterprise Scheduler Jobs

• Managing Job Metadata

• Managing Work Assignments and Workshifts

• Managing Metadata Security for Jobs

5.1 Introduction to Managing the Work of Oracle Enterprise Scheduler Jobs

You can define meaningful work by associating metadata with job types and by assigning schedules to the work.

When managing the work of Oracle Enterprise Scheduler jobs, you can:

• Associate request instance-specific data through properties -- whether your own or the system's -- that tie jobs to the context in which they are running

• Determine what level of access a group of people have to data related to the work done by jobs.

• Organize jobs into job sets so that they can be run as a unit, whether in sequence or in parallel.

• Specify that certain job definitions may not run at the same time, and the circumstances under which they cannot.

• Define the constraints within which jobs may run, based on factors such as system resources.

5.2 Managing Job Metadata

Oracle Enterprise Scheduler job metadata refers to the components that form the basis of scheduled job requests.

These include the following:

• Job definition: A job definition is the smallest unit of work performed in the context of the application that executes the job. A job definition is defined by a job type, such as a Java or SQL job type.

• Job set: A job set is a sequential or parallel set of job steps, where a job step can be a single job or another job set. A job set and each of its job set steps can have additional parameters, the values for which are provided when the job or job set is submitted as a job request.

• Incompatibility: An incompatibility allows you to specify job definitions and job sets that cannot run concurrently.

Note:

When you use Oracle Enterprise Manager Fusion Middleware Control or WLST commands to search for metadata, be sure to search for the actual name of the job definition, job set, or incompatibility rather than the display name. Display names are not found during searches.

This section contains the following topics:

• Managing Job Definitions

• Managing Job Sets

• Managing Incompatibilities

5.2.1 Managing Job Definitions

The Job Definitions page in Fusion Middleware Control allows you to view, create, edit, delete and search for job definitions.

This section contains the following topics:

• Viewing Job Definitions

• Creating or Editing a Job Definition

• Deleting a Job Definition

Note:

For a detailed description about how to use Oracle JDeveloper and Oracle Enterprise Manager Fusion Middleware Control to create job definitions for web service jobs, see Developer's Guide for Oracle Enterprise Scheduler, "Using Oracle Enterprise Manager Fusion Middleware Control or Oracle JDeveloper to Create a Job Definition."

5.2.1.1 Viewing Job Definitions

You can view the job definitions created for a given application. The table of job definitions displays details 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.

To display job definitions:

1. From the navigation pane, expand the Scheduling Services folder 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 Application dropdown list, select the name of the application whose job definitions you want to view.

   Note:

   The application name is shown with its version number in parenthesis. The version number is not actually part of the application's name.

4. In the Name and Package fields, enter values to search for.
5. Click Go to search.

   The job definitions for that application display in a table below the application dropdown list.

   Column Name	Description
   Name	This column displays the name of the job definition.
   Display Name	This column contains a value that is displayed to users for this definition. This value may contain spaces and should be memorable for users who might later view or search for the definition in the user interface
   Package	This column displays the name of the Java package associated with the job definition.
   Job Type	This column displays the job type associated with the application.
   Description	This column displays a description of the job definition.

6. To view the details of a specific job definition, click the name of the relevant job definition.

5.2.1.2 Creating or Editing a Job Definition

You can create or edit a job definition. With a job definition created, you can 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. If the job is one of the web service types, the WSDL URL can also be specified.

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

• Parameters. You can configure editable or read-only parameters to be submitted to the job request.

• User properties. You can configure properties to be filled in by end users at runtime, such as boolean, number and string values.

This section contains the following topics:

• Configuring Application Defined Properties

• Configuring System Properties

• Configuring Access Control

To create or edit a job definition:

1. From the navigation pane, expand the Scheduling Services folder 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 application for which you want to create a job definition.
4. Click Create to create a new job definition, or Edit to modify an existing job definition.
5. For the job definition, configure the following properties:

   • Name (required): Enter a name that uniquely identifies this definition. This value may not contain spaces.

   • Display Name: Enter a value that is displayed to users for this definition. This value may contain spaces and should be memorable for users who might later view or search for the definition in the user interface.

     This property supports internationalization for adapting to differing locales.

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

   • Description: Enter a description for the job.

     This property supports internationalization for adapting to differing locales.

   • Job Type (required): From the dropdown list, select the job type you want to use for the job definition. Select the Override check box to override the existing value when editing an existing job definition.

     The Job Type you choose determines which one of the following fields is displayed beneath the Job Type. Note that you won't be able to edit the field's value if the corresponding value in this definition's job type was specified to be read only.

     • Class Name (for JavaJobType, SyncEjbJobType, AsyncEjbJobType)

       The class name that is associated with the job definition's job type. If you can edit the field, select Override and enter the class path and name or click Browse to specify a path name for the Java class.

     • Procedure Name (for PlsqlJobType)

       The procedure name for the PL/SQL procedure associated with this job definition's job type. If you can edit this field, select Override and enter the procedure name to be used by this job definition. You can also click the Browse button to use an already defined database connection to browse for a stored procedure.

     • Process Name (ProcessJobType)

       The string that is the command associated with the job type. If you can edit this field, select Override and enter the command to be used by this job definition.

     • Select Web Service button (for SyncWebserviceJobType, AsyncWebserviceJobType, OnewayWebserviceJobType)

       The Select Web Service button invokes the Select Web Service dialog. Use the dialog to specify a WSDL file. After you select a valid WSDL, you can select the type of WSDL, and then the service, port and operation.

       Note:

       If you are editing an existing web service job definition, this button is named Change Web Service and you can use it to change the WSDL specification.

6. Optionally, configure application defined properties, system properties, and access control. For more information, see Configuring Application Defined Properties, Configuring System Properties, and Configuring Access Control.

   If you are creating a job definition for a secured web service job type, you must select the security policies for invocation and callback. See Configuring Access Control for more information.

7. Click OK.

5.2.1.2.1 Configuring Application Defined Properties

You use a parameter to pass data to the job request. In the job submission user interface, parameters can be passed using a number of display controls, such as a text box, date picker, choice list or list of values.

To configure parameters for a job definition:

1. On the Create Job Definition page, expand the Application Defined Properties section.
2. Click the Add button.

   The Add Application Defined Property dialog box displays.

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

   • Type: From the dropdown list, select a data type for the parameter: String, Long, Integer, DateTime, or Boolean. Required.

   • Name: Enter a name for the parameter.

   • Initial Value: Enter the value that should be used for this parameter until the user changes it.

   • Read Only: Select the check box to have this parameter be read only to the user.

4. Click OK.

5.2.1.2.2 Configuring System Properties

System properties are parameter names that are known to and used by the system. You can specify that certain system properties should be used in your metadata.

Note:

If you modify the value of a system property, be sure that the modified value of the system property is correct. An incorrect system property value might cause the job definition to not work as expected.

To configure system properties for a job definition:

1. On the Create Job Definition page, expand the System Properties section.

2. Click the Add button.

   The Add System Property dialog box displays.

3. From the Name dropdown list, select the system property you want to specify. Possible system properties are shown in Table 5-1.

4. In the Initial Value text field, enter the value you want to assign to the system property.

5. Select the Read Only check box to have this property be read-only to the user.

6. Click OK.

Table 5-1 System Properties

System Property	Description
SYS_EXT_cmdLine.Unix	For a process job type, this specifies a string representing the command line command on Unix. If the SYS_cmdLine property is defined, this property is ignored.
SYS_EXT_cmdLine.Windows	For a process job type, this specifies a string representing the command line command on Windows. If the SYS_cmdLine property is defined, this property is ignored.
SYS_EXT_ejbOperationName [EJB_OPERATION_NAME]	Optional for EJB jobs. Specifies a pass-through parameter used by the EJB implementation to branch to the appropriate business methods. Example: manageFileAdapter
SYS_EXT_executableDir.Unix	For a process job, this specifies the directory where the process executable is located on Unix.
SYS_EXT_executableDir.Windows	For a process job, this specifies the directory where the process executable is located on Windows.
SYS_EXT_executableName	For a process job, this specifies the name of the process executable.
SYS_EXT_executableSuffix.Unix	Specifies the suffix for SYS_EXT_executableName on Unix. The default is ".sh".
SYS_EXT_executableSuffix.Windows	Specifies the suffix for SYS_EXT_executableName on Windows. The default is ".cmd".
SYS_EXT_executeAutoExport	For process and Java job types, this specifies a value that prompts Oracle Enterprise Scheduler to automatically export any previously imported output files to the request's output directory at the start of the execute stage. Using this property assumes that the request sets the SYS_EXT_supportOutputFiles property to "output" and the SYS_EXT_executeAutoExport property to "true". This can be useful in the case that RequestFileDirectory is a local directory and the execute stage requires access to output files that were created in the pre-processor or during a previous execution attempt, in case of retry.
SYS_EXT_fusionJob	Set this to "true" to specify that the current job is Fusion Applications CP job type.
SYS_EXT_invokeMessage	The XML submit message used to invoke the web service.
SYS_EXT_essAsyncRequestJndiMappedName [ESS_ASYNC_REQUEST_JNDI_MAPPED_NAME]	For EJB jobs, specifies the JNDI mapped name of Oracle Enterprise Scheduler's AsyncRequest bean defined in the hosting application and bound to Oracle Enterprise Scheduler server's JNDI tree. This property is required only if: The EJB invocation is asynchronous You use a hosting application other than EssNativeHostingApp is used The remote bean has to call back to Oracle Enterprise Scheduler beans (for example, an asynchronous callback).
SYS_EXT_essJndiCsfKey [ESS_JNDI_CSF_KEY_NAME]	Optional for EJB jobs. Specifies the CSF key alias of the authenticated Oracle Enterprise Scheduler server. This property is required only if the Oracle Enterprise Scheduler JNDI tree is authenticated. Example: ess-jndi-csf-key
SYS_EXT_essMetadataJndiMappedName [ESS_METADATA_JNDI_MAPPED_NAME]	For EJB jobs, specifies the JNDI mapped name of Oracle Enterprise Scheduler's MetadataService bean defined in the hosting application and bound to the Oracle Enterprise Scheduler server's JNDI tree. This property is required only if you use a hosting application other than EssNativeHostingApp and the remote bean requires access to Oracle Enterprise Scheduler's metadata bean
SYS_EXT_essRuntimeJndiMappedName [ESS_RUNTIME_JNDI_MAPPED_NAME]	For EJB jobs, specifies the JNDI mapped name of Oracle Enterprise Scheduler's RuntimeService bean that is defined in the hosting application and bound to the Oracle Enterprise Scheduler server's JNDI tree. This property is required only if you use a hosting application other than EssNativeHostingApp and the remote bean has to call the Oracle Enterprise Scheduler runtime bean (for example, to write output or log information, submit requests or operate on requests).
SYS_EXT_jndiCSFKey [JNDI_CSF_KEY]	Required for EJB jobs only if the JNDI tree of the EJB server is secured. Points to the CSF alias that is mapped to the user name and password in the keystore. This specific user name/password pair is the credential required to access the secured JNDI for JndiMappedName lookup. This property can be added to either the RequestParameters object or to the Oracle Enterprise Scheduler configuration of the hosting application.
SYS_EXT_jndiProviderUrl [JNDI_PROVIDER_URL]	Optional for EJB jobs. Specifies the URL of the remote server. Required only if the EJB is remotely located.
SYS_EXT_jndiMappedName [JNDI_MAPPED_NAME]	Required for EJB jobs. Specifies the JNDI lookup name of a remote EJB implementation. Example: ejb/fileAdapter
SYS_EXT_processArguments	For a process job, this specifies the arguments.
SYS_EXT_requestLogLevel	Specifies the log level for Java and PL/SQL request loggers. The default is "INFO".
SYS_EXT_resolvedCmdLine	For a process job type, after the job is successfully started, this property provides a place for Oracle Enterprise Scheduler to save the actual command line (with substitution performed). This property is for diagnostic purposes only. It is for use by Oracle Enterprise Scheduler and other values might be overwritten by the service.
SYS_EXT_supportOutputFiles	Specifies a string indicating whether the job creates files in the file system. The following values are supported: "work" to create a temporary file rather than an output file. "output" to use the file system to create output files. "none" (or no value) to not create any files in the file system.
SYS_EXT_uploadContentToRepository	Set this to "copy" to have Oracle Enterprise Scheduler upload request log and output files from its content store to a separate repository (UCM). The request log and output content remain in the content store, but are also available to user interfaces and tools that expect log/output in UCM.
SYS_EXT_useAlternateEnvironment	Set this to "true" to get environment properties from Fusion Applications-style files. The default is "false".
SYS_EXT_useExtendedSetup	Set this to "true" to have Oracle Enterprise Scheduler set up extended functionality, such as ApplSession, for each stage of the request if that functionality is available.
SYS_EXT_userFileDirShared	For process and Java job types that may create files in the file system, this prompts Oracle Enterprise Scheduler to save in the request the configured RequestFileDirectory and RequestFileDirectoryShared from the ess-config.xml file. These values are saved as the properties SYS_userFileDir and SYS_EXT_userFileDirShared, respectively. Oracle Enterprise Scheduler uses these properties to create the request work and output directories, depending on SYS_EXT_supportOutputFiles. This for use by Oracle Enterprise Scheduler and other values might be overwritten by the service.
SYS_EXT_wsCancelMessage	Optional. The XML message for the web service cancel operation.
SYS_EXT_wsCancelOperationName	Optional. The cancel operation name.
SYS_EXT_wsWsdlBaseUrl	The base URL part of WSDL URL.
SYS_EXT_wsWsdlUrl	The relative part of the web service WSDL URL (must be a concrete WSDL URL). Either the SYS_EXT_wsEndpointUrl property or the SYS_EXT_wsWsdlUrl property must be completely specified. For example, either wsWsdlBaseUrl and wsWsdlUrl are both configured, or wsEndpointBaseUrl and wsEndpointUrl are both configured.
SYS_EXT_wsEndpointBaseUrl	The base URL part of endpoint URL.
SYS_EXT_wsEndpointUrl	The endpoint URL for the web service. Either the SYS_EXT_wsEndpointUrl property or the SYS_EXT_wsWsdlUrl property must also be specified.
SYS_EXT_wsOperationName	The operation name.
SYS_EXT_wsPortName	The port name.
SYS_EXT_wsServiceName	The service name.
SYS_EXT_wsTargetNamespace	The target name space.
SYS_allowMultPending	Specifies whether multiple pending requests for the same job definition is allowed. This property has no meaning for a job set step. True or false.
SYS_application	Specifies the logical name of the J2EE application used for request processing. This property is automatically set by Oracle Enterprise Scheduler during request submission.
SYS_bizErrorExitCode	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. For more information about business errors, see Searching for a Job Request Using the Advanced Search Feature
SYS_className	Specifies the Java executable for a Java job request. This should be 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	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	Specifies the logical name of the J2EE application that is 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 using metadata and cannot be specified as a submission parameter.
SYS_environmentVariables	Specifies the environment variables to be set for the spawned process of a process job request. The property value should 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	Specifies whether instances of a repeating request with an execution time in the past should be generated. Instances are never generated before the requested start time or after the requested end time. To cause past instances to be generated, you must set this property to TRUE and specify the requested start time as the initial time from which instances should be generated. Note that a null requested start time defaults to the current time. 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) are not generated. If this property is not specified, the system defaults to TRUE.
SYS_extensionListener	For internal use only.
SYS_external_id	Specifies an identifier for an external portion of an asynchronous Java job. For example, an asynchronous Java job usually invokes some remote process and then returns control to Oracle Enterprise Scheduler. This property can be used to identify the remote process. This property should be set by the job implementation of asynchronous Java jobs when the identifier is known. It is never set by Oracle Enterprise Scheduler.
SYS_external_JobType	Optional. The supported values are “ADFBC", “OSB" or “SOA". Any other value is invalid.
SYS_groupName	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	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	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	Specifies the event listener class associated with the request. This should be the name of a Java class that implements the oracle.as.scheduler.EventListener interface.
SYS_locale	Specifies a language code to apply to the job.
SYS_logicalClusterName	Oracle Enterprise Scheduler provides the means by which EJB and web service jobs can define an 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. In the Job Definitions > Job Definition Details page, set the SYS_logicalClusterName system property to a name that you use to define the set of location related properties (LCN) in the Configuration > Application Properties page. For more information, see Job Location Properties. Note that the terms "logical cluster" and "job location" can be used interchangeably.
SYS_logWorkDirectory	Specifies the logging working directory. This is for use by Oracle Enterprise Scheduler and other values might be overwritten by the service.
SYS_outputList	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 guaranteed order, with oracle.as.scheduler.SystemProperty.OUTPUT_LIST_DELIMITER as a separator.
SYS_outputWorkDirectory	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. This is for use by Oracle Enterprise Scheduler and other values might be overwritten by the service.
SYS_postProcess	Specifies the post-process callout handler class. This should be the name of a Java class that implements the oracle.as.scheduler.PostProcessHandler interface.
SYS_preProcess	Specifies the pre-process callout handler class. This should be the name of a Java class that implements the oracle.as.scheduler.PreProcessHandler interface.
SYS_priority	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	Specifies the name of the PL/SQL stored procedure to be called for a SQL job request. The stored procedure should be specified using schema.name format. The property is required for a SQL job type. It is not used for other job types.
SYS_product	Specifies the product within the application that submitted the request.
SYS_redirectedOutputFile	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 process when the request is executed. This is for use by Oracle Enterprise Scheduler and other values might be overwritten by the service.
SYS_reprocessDelay	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_EXT_requestEffectiveEncoding	Specifies the effective encoding associated with a process job request. SpawnLauncher determines the locale setting for a spawned job request in the following precedence order: LC_ALL/LANG specified in the environment properties (SystemProperty.ENVIRONMENT_VARIABLES) for the request LC_ALL/LANG specified in the hosting application's ess-config.xml file WebLogic server LC_ALL/LANG The effective encoding is computed before the process is spawned and is stored in this property. This is later used to determine the encoding for the request log and output.
SYS_request_timeout	Specifies that job request can time out.
SYS_requestCategory	Specifies an application-specific label for a request. The label, defined by an application or system administrator, allows administrators to group job requests according to their own specific requirements.
SYS_requestedProcessor	Specifies the request processor node on which the request should be processed. This allows 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 never executes. If the specified node is not running, the request remains in the READY state and does not execute until the node is restarted.
SYS_requestExpiration	Specifies the expiration time for a request. This represents the time, in minutes, that a request expires after its scheduled execution time. An 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	Specifies the retry limit for a failed request. If request execution fails, the request retries up to the number of times specified by this property until the request succeeds. If retry limit is zero (0), a failed request is not 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. Normally, 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 using metadata and cannot be specified as a submission parameter.
SYS_selectState	Specifies whether the result state of a job set step affects the eventual state of its parent job set. In order 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 is included in the determination of the state of the job set. Boolean type.
SYS_sqlJobClass	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 privilege or grant is 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	Specifies the logical name of the J2EE 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	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	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. Oracle Enterprise Scheduler supports a configuration parameter that specifies a file directory where requests may 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 is initialized to the value of the configuration parameter. The property is not added if the configuration parameter is not set at the time of request submission. This is for use by Oracle Enterprise Scheduler and other values might be overwritten by the service. Note that if this property is deleted, its value defaults to a system-defined value of <server log path>/ess_request/ and the value of the SYS_EXT_userFileDirShared property is assumed to be false.
SYS_userName	Specifies the name of the user used to execute the request. Normally, 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 request submission.
SYS_warningExitCode	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 execution warning. This property is optional for a process job type. It is not used for other job types.
SYS_workDirectoryRoot	Specifies the working directory for the process of a process job request. This is for use by Oracle Enterprise Scheduler and other values might be overwritten by the service.

5.2.1.2.3 Configuring Access Control

You can specify the level of access to this metadata that groups of users have. The roles visible here are defined in a jazn-data.xml file used by the application.

1. On the Create Job Definition page, expand the Access Control section.
2. Click the Add button.

   The Add Access Control dialog box displays.

3. From the Role dropdown list, select the name of the role you want to apply to the job set. Users grouped by that role have the level of access you specify here.
4. Select the actions you want to allow role members to take: Read, Execute, Update and Delete.
5. Click OK.

5.2.1.2.4 Granting Permission to Job Roles in Enterprise Manager

This topic describes how to grant permission to job roles in Enterprise Manager

You can create a job definition in Enterprise Manager. When creating the job definition, you can grant permissions to a job and attach it to a role.

Before you grant permission to a job, you need to create an application role in essnativehostingappstripe in Enterprise Manager and associate a user or a group to this role in Enterprise Manager. You can do this using the security link in Weblogic Enterprise Manager.

Note:

You can associate groups or individual users using the security link in Weblogic Enterprise Manager and not in ESS Enterprise Manager.

When you grant permissions to a job in Enterprise Manager and then create the job in ESS Enterprise Manager, the roles you created show up in Enterprise Manager. You can then attach the permissions to these roles.

To grant permission to job roles in Enterprise Manager:

1. In the Enterprise Manager window, navigate to compact_domain in the navigation pane.
2. In the Application Stripe dropdown, select ESSNativeHostingApp.
3. Click Create to specify the role for ESSNativeHostingApp.
4. In the Role Name filed, enter ESSJobRole as the role name.
5. Click the Add icon to add the principal.
6. Search for the principal, test and click OK.
7. To select and role and specify the actions it can perform, go to the navigation panel and click Scheduling Services > ESSAPP (AdminServer)
8. Select the application for which you want to add the job definition.
9. You can use the filter criteria to look up the application.
10. To define a job type, open the job definition and click Select Web Services.
11. Add the access controls and click OK.

5.2.1.3 Deleting a Job Definition

You can delete a job definition.

To delete a job definition:

1. Search for the relevant job definition, as described in Viewing Job Definitions.
2. In the Results table, select the job definition you want to delete and click the Delete button.

5.2.2 Managing Job Sets

You can view, create, edit, delete and search for job sets, which are collections of job requests that can be grouped together to run as a single unit. You can nest a job set so that it may contain a collection of job requests or one or more child job sets. Each job request or job set included within a job set is called a job set step.

Note:

To avoid creating a cyclical dependency, do not add a job set to a job set that contains it. For example, if JobSet2 contains JobSet1, be sure not to add JobSet2 to JobSet1.

You manage job sets with the Job Sets page in Fusion Middleware Control.

This section contains the following topics:

• Viewing Job Sets

• Creating or Editing a Job Set

• Deleting a Job Set

5.2.2.1 Viewing Job Sets

You can view the job sets created for a given application.

To display job sets:

1. From the navigation pane, expand the Scheduling Services folder 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 displays.

3. From the Applications dropdown list, select the name of the application whose job sets you want to view.
4. Enter the name and package name of the job set you want to find, and click Go.

   The job sets for the application you selected display in the Results table below the Filter Criteria section of the page.

   Column Name	Description
   Name	This column displays the name of the job set.
   Display Name	The name displayed to users for this job set.
   Package	This column displays the name of the Java package associated with the job set.
   Execution Mode	This column displays the execution mode of the job set, Serial or Parallel.
   Description	This column displays a description of the job set.

5. To view the details of a specific job set, click the name of the job set you're interested in.

Figure 5-1 shows the Results table in the Job Sets page. The Results table displays job sets and their attributes, including name, package, execution mode and description.

Figure 5-1 The Job Sets Page and Results Table

Description of "Figure 5-1 The Job Sets Page and Results Table"

5.2.2.2 Creating or Editing a Job Set

You define a job set as either serial or parallel. At runtime, Oracle Enterprise Scheduler runs parallel job set steps together, in parallel. When a serial job set runs, on the other hand, Oracle Enterprise Scheduler runs the steps one after another in a specified sequence. With 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, you can configure an action to be taken on completion of the step, depending on the state of the step. You can also configure parameters and system properties 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 failure.

To create or edit a job set:

1. From the navigation pane, expand the Scheduling Services folder 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 displays.

3. From the Applications dropdown list, select the name of the application for which you want to create or edit job sets.

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

5. In the Name field, enter the name of the job set. Fill in the Display Name field with a name that is shown to users. Optionally, add a description in the Description text field, and the name of the relevant job set Java package in the Package text field.

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

7. Add steps as required by clicking the Add button. Define each step as required.

   1. In the Step tab, in the Step ID field, enter a meaningful ID for the step. The step ID must be unique for all steps in this job set.

      In the Job field, click the search button. In the window that displays, select the job or job set that you want to use for this step, then click OK.

   2. Select Insert into main diagram or Add to list of available steps. If you choose to add the step to the list of available steps, use the dropdown lists that display to select actions for the possible job outcomes, namely On Success, On Error and On Warning.

   3. In the Application Defined Properties tab, click the Add button to define any required parameters and enter their initial value in the field provided. For more information about defining parameters, see Configuring Application Defined Properties.

   4. In the System Properties tab, click the Add button to select system properties and enter their initial value in the field provided. For more information about selecting system properties, see Configuring System Properties.

   5. Click OK.

   6. If you configured the step as a serial step, it displays in the job set flow diagram. Configure the action to be taken upon reaching 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.

      
      Description of the illustration schedule_ess_job_step_error.png

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

9. If your job set requires them, define application defined properties and system properties in sections toward the bottom of the job set window.

10. Configure access control for the job set. For more on defining access control, see Configuring Access Control.

11. On the Create Job Set page, click OK to save the job set.

5.2.2.3 Deleting a Job Set

You can delete a job set.

To delete a job set:

1. Search for the relevant job set, as described in Viewing Job Sets.
2. In the Results table, select the job set you want to delete and click the Delete button.

5.2.3 Managing Incompatibilities

An Oracle Enterprise Scheduler incompatibility specifies which job definitions should not run simultaneously with one another.

An incompatibility defines either a global incompatibility or a domain-specific, property-based incompatibility.

This section contains the following topics:

• Viewing Incompatibilities

• Creating or Editing an Incompatibility

• Deleting an Incompatibility

5.2.3.1 Viewing Incompatibilities

The Incompatibilities page displays an incompatibility's name, the Java package associated it, and a description for the incompatibility.

To view job incompatibilities:

1. From the navigation pane, expand the Scheduling Services folder and select the Oracle Enterprise Scheduler application.
2. From the Scheduling Services menu, select Job Metadata and then select Incompatibilities.

   The Incompatibilities page displays.

3. From the Application dropdown list, select the name of the application whose incompatibilities you want to view.
4. Enter the name and package name of the incompatibilities you want to find, and click Go.

   The incompatibilities for that application display in a table below the application dropdown list.

   Column Name	Description
   Name	This column displays the name of the incompatibility.
   Display Name	A name displayed to users for this incompatibility.
   Package	This column displays the name of the Java package associated with the incompatibility.
   Incompatibility Type	This column displays the type of incompatibility, global or domain specific.
   Description	This column displays a description of the incompatibility.

5. To view the details of a specific incompatibility, click the incompatibility's name.

5.2.3.2 Creating or Editing an Incompatibility

An incompatibility consists of one or more job definitions configured as incompatible, and optionally the resource over which they must be incompatible. A resource is not specified for a global incompatibility.

In a domain incompatibility, the resource is represented by the property name that forms the Incompatibility. The property name might be different across job definitions. For example, if two job definitions, JobA and JobB, are made incompatible, then the property identified for incompatibility might have different names in JobA and JobB.

The following gives more information about the difference between domain and global incompatibilities:

• Domain-specific: In a domain incompatibility, Oracle Enterprise Scheduler ensures that requests for the incompatible jobs or job sets, with a property that has the same property value, do not run at the same time.

  You add two or more job definitions as incompatible within the scope of a resource, where the resource is identified by a system property name or a parameter name. Each entity can use the same property name or a different property name. For a property-based incompatibility, you must specify a job definition or a job set and a property name for each entity.

• Global: In a global incompatibility, Oracle Enterprise Scheduler ensures that requests for the incompatible jobs or job sets do not run at the same time.

  Two or more job definitions cannot run together at any time. A global incompatibility is used when the incompatible entities are not to be run at the same time regardless of any property. For global incompatibility, only the job definition or job set is specified for each entity.

Usually an incompatibility is defined using two or more job or job set entities. An incompatibility can be defined for one entity as long as that entity is marked as self-incompatible. A self-incompatibility implies that multiple job requests associated with that job or job set cannot run together.

Defining an incompatibility involves the following:

• Package and scope: Select a relevant Java package to use for the incompatibility and set the scope for the incompatibility (global or domain only).

• Jobs: Select the jobs that are incompatible.

• Parameters and properties: Define parameters and properties as required.

• Access control: Define access control as required.

To create or edit an incompatibility:

1. From the navigation pane, expand the Scheduling Services folder and select the Oracle Enterprise Scheduler application.
2. From the Scheduling Services menu, select Job Metadata and then select Incompatibilities.

   The Incompatibilities page displays.

3. From the Application dropdown list, select the name of the application whose incompatibilities you want to create or edit.
4. Click Create to define a new incompatibility, or Edit to modify an existing incompatibility.

   The Create (or Edit) Incompatibilities page displays.

5. Enter the following information:

   • Name: Enter a name for the incompatibility.

   • Display Name: A name displayed to users for this job set.

   • Package: Enter the name of the relevant incompatibility Java package.

   • Description: Optionally, add descriptive text for the incompatibility.

   • Type: Configure the scope of the incompatibility by selecting Global or Domain.

6. In the Entities section, click the Add button to add jobs to the incompatibility.

   The Add Entity dialog box displays. Select one or more jobs and click OK.

7. If this is a domain incompatibility, select each entity listed in the Entities table, click the Edit button, and select the property whose value should be incompatible with the other entities in the list.
8. If entities in the list are self incompatible -- meaning that they should not run simultaneously with other instances of the same entity -- edit the entity and select the Self Incompatible check box.
9. Configure access control for the incompatibility, as described in Configuring Access Control.
10. Click OK to save the incompatibility.

5.2.3.3 Deleting an Incompatibility

Deleting an incompatibility results in the incompatible job requests or job sets becoming compatible again.

To delete an incompatibility:

1. Search for the relevant incompatibility, as described in Viewing Incompatibilities.
2. In the Results table, select the incompatibility you want to delete and click the Delete button.

5.2.4 Bulk Customization of Job Metadata

Typically, customization of existing Oracle Enterprise Scheduler jobs involves editing job properties using Oracle Enterprise Manager Fusion Middleware Control or Oracle JDeveloper. This approach is limited and repetitive for customers interested in bulk updates of job properties. The System MBean Browser and the bulk customization APIs enable you to customize the property of a piece of metadata in bulk for a number of jobs without changing the base metadata.

The following properties can be updated or customized in bulk:

• oracle.as.scheduler.SystemProperty.PRIORITY

• oracle.as.scheduler.SystemProperty.RETRIES

• oracle.as.scheduler.SystemProperty.REQUEST_CATEGORY

• oracle.as.scheduler.SystemProperty.ASYNC_REQUEST_TIMEOUT

• oracle.as.scheduler.SystemProperty.LOGICAL_CLUSTER_NAME

• enableTrace

• enableTimeStatistics

5.2.4.1 Bulk Customization Using the System MBean Browser

The bulk customization API can be conveniently invoked from the Oracle Enterprise Manager Fusion Middleware Control System MBean Browser. The process has two steps:

1. Export the list of job definition properties that can be customized to an XML file. This step queries the job definitions that match the specified filter criteria in the Oracle Enterprise Scheduler hosting application MDS repository. The generated XML output file can be edited. This XML file serves as the input for the customization step.
2. Customize the job definition property metadata definitions contained in the previously exported XML file. This step customizes the job definition property metadata definitions defined in the input XML file generated in the export step without changing the base metadata. This process makes use of the MDS metadata customization functionality, and an exception is thrown if the properties are not members of the one of the MetadataService.CustomizableProperty enumerations. This step modifies the base metadata for job definition properties that belong to the custom name space specified in the <cust-config> element of the adf-config.xml file.

   Note:

   In order for this feature to work correctly, the application must define a customization class in its adf-config.xml file. Refer to the MDS documentation for more information.

5.2.4.1.1 Example

The following example shows how to use the System MBean Browser to export and customize job definition properties.

1. Start the Oracle Enterprise Manager Fusion Middleware Control System MBean Browser by choosing it from the Weblogic Domain menu as shown in Figure 5-2.

   Figure 5-2 Start the Oracle Enterprise Manager Fusion Middleware Control System MBean Browser

   
   Description of "Figure 5-2 Start the Oracle Enterprise Manager Fusion Middleware Control System MBean Browser"

2. In the System MBean Browser, navigate to your application's MetadataService entry. Figure 5-3 shows an example. Note that your server and application names may be different.

   Figure 5-3 Navigation Path to MetadataService

   
   Description of "Figure 5-3 Navigation Path to MetadataService"

3. Click on the Operations tab as shown in Figure 5-4.

   Figure 5-4 Choose the exportESSJobMetadataBulk Item

   
   Description of "Figure 5-4 Choose the exportESSJobMetadataBulk Item"

4. Click on the exportESSJobMetadataBulk item (Figure 5-4) to invoke the Operation:exportESSJobMetadatBulk page.

5. On the Operation:exportESSJobMetadatBulk page, fill in the fields in the Value column using the parameters listed in Table 5-2 and then click Invoke. Figure 5-5 shows an example.

   Figure 5-5 Operation: exportESSJobMetadataBulk Page

   
   Description of "Figure 5-5 Operation: exportESSJobMetadataBulk Page"

   The following tables show additional examples of parameters and values that might be used in the Operation: exportESSJobMetadataBulk page.

   Parameter	Value
   filterQueryField	package
   filterComparator	CONTAINS
   filterValue	oracle/as/ess/customer-pkg

   Parameter	Value
   filterQueryField	job-type
   filterComparator	ENDS_WITH
   filterValue	PlsqlJobType

   Parameter	Value
   filterQueryField	name
   filterComparator	EQUALS
   filterValue	some_env_value

6. Click Return to return to the MetadataService page and then click on the customizeJobDefinitionBulk item to invoke the Operation:customizeJobDefinitionBulk page.

   Figure 5-6 Choose the customizeJobDefinitionBulk Item

   
   Description of "Figure 5-6 Choose the customizeJobDefinitionBulk Item"

7. Fill in the fields in the Value column as shown in Figure 5-7. The xmlInputFile entry is the name of the file to which you previously exported the parameters. Click the Invoke button to complete the customization.

   Figure 5-7 The Operation: customizeJobDefinition Page

   
   Description of "Figure 5-7 The Operation: customizeJobDefinition Page"

5.2.4.2 Bulk Customization MBean API

The bulk customization API is comprised of two methods, exportESSJobMetadataBulk and customizeJobDefinitionBulk.

5.2.4.2.1 exportESSJobMetadataBulk Method

This method exports the list of job definition properties that can be customized. This method queries the job definitions that match the specified filter criteria in the Oracle Enterprise Scheduler hosting application MDS repository.

The generated XML output file can be edited by an administrator. This file serves as the input to the customizeJobDefinitionBulk method described in customizeJobDefinitionBulk Method.

5.2.4.2.1.1 Syntax

void exportESSJobMetadataBulk (java.lang.String xmlOutputFile,
                               java.lang.String filterQueryField,
                               java.lang.String filterComparator,
                               java.lang.String filterValue,
                               java.lang.String application)
                                throws java.io.IOException,
                                       javax.management.RuntimeOperationsException

Table 5-2 exportESSJobMetadataBulk Parameters

Parameter	Description
xmlOutputFile	The absolute path of the output XML file to which the list of the job definitions' customizable properties is exported.
filterQueryField	The name of the query field by which to filter. The following are the supported query fields: Package Name JobType ExecutionType These query fields are defined in the package oracle/as/scheduler/metadata/query/MetadataQueryField.
filterQueryComparator	The name of the filter comparison operator. The following are the supported comparators: EQUALS NOT_EQUALS CONTAINS NOT_CONTAINS STARTS_WITH ENDS_WITH These comparators are defined in the package /oracle/as/scheduler/Filter.Comparator.
filterValue	The value with which to compare the filter query field.
application	The name of the Oracle Enterprise Scheduler hosting application whose metadata repository is to be used.

Table 5-3 exportESSJobMetadataBulk Exceptions

Exception	Description
java.io.IOException	Thrown if a protocol error occurs.
javax.management.RuntimeOperationsException	Thrown if the metadata sub-system encounters failures.

5.2.4.2.2 customizeJobDefinitionBulk Method

This method customizes the job definition property metadata definitions defined in the input XML file generated by the exportESSJobMetadataBulk method without changing the base metadata. The MDS metadata customization functionality is used, and an exception is thrown if the properties are not members of the one of the MetadataService.CustomizableProperty enumerations.

This method modifies the base metadata for job definition properties that belong to the custom name space /oracle/apps/ess/custom.

Note:

In order for this feature to work correctly, the application must define a customization class in its adf-config.xml file. Refer to the MDS documentation for more information.

5.2.4.2.2.1 Syntax

void customizeJobDefinitionBulk (java.lang.String xmlInputFile,
                                 java.lang.String application)
                           throws java.io.IOException, 
                                  javax.management.InstanceNotFoundException,
                                  javax.management.OperationsException,
                                  javax.management.InvalidAttributeValueException,
                                  javax.management.RuntimeOperationsException

Table 5-4 customizeJobDefinitionBulk Parameters

Parameter	Description
xmlInputFile	The path to the input XML file that contains the exported list of job definitions. The format of the file is dictated by the output of the exportESSJobMetadatBulk method.
application	The name of the application whose metadata repository is to be used.

Table 5-5 customizeJobDefinitionBulk Exceptions

Exception	Description
java.io.IOException	Thrown if a protocol error occurs.
javax.management.InvalidAttributeValueException	Thrown if the validation of the definition fails.
javax.management.RuntimeOperationsException	Thrown if the metadata sub-system encounters failures.
javax.management.InstanceNotFoundException	Thrown if the specified MBean does not exist in the repository.
javax.management.OperationsException	Represents exceptions thrown in the MBean server when performing operations on MBeans.

5.3 Managing Work Assignments and Workshifts

With work allocation, you can define constraints on where and when jobs run, as well as the amount of resources that can be used to process the jobs. This process includes creating a work assignment and binding the work assignment to a request processor.

A work assignment consists of a specialization rule and one or more workshifts. The specialization rule defines restrictions on which jobs can be processed. A workshift defines the temporal windows when the jobs can be processed and what resources can be used during those periods. The resources defined in a workshift include threads, which are a local resource of the request processor, and asynchronous workers, a global resource. The number of asynchronous workers can be specified to throttle the use of a shared global resource, such as database jobs.

Binding associates a work assignment with a request processor on a server, determining where the jobs can run. An exclusive binding mode is supported to not only determine when the jobs can run but to prevent them from running anywhere else.

By default, no work assignments are bound. When there is no bound or active work assignment, a virtual default work assignment is started to process all jobs using all available resources. This default work assignment is limited to the number of threads configured for the processor, but there is no default limit for asynchronous workers. To limit asynchronous workers, it is necessary to create and bind one or more work assignments.

This section contains the following topics:

• Managing Work Assignments

• Managing Workshifts

• Managing Schedules

5.3.1 Managing Work Assignments

Work assignments provide the following controls for processing job requests:

• At runtime, work assignments can be bound to a request processor and can limit the period during which job requests of a certain type can be processed.

• At runtime, the request processor can be configured to limit the threads that are available to process all job requests.

5.3.1.1 Determining Active Work Assignments

A bound work assignment is active if it is enabled, has an active workshift and the enabled flag is set on the work assignment definition. A workshift is active if it has an allocation greater than zero and includes a current schedule (where the current time is within a time window defined by the schedule and duration), or the workshift is a 24x7 workshift. If there are no bound work assignments on the server, the default work assignment is active using all threads and having no limits on asynchronous workers.

5.3.1.2 Determining Work Assignment Thread Allocation

An active work assignment is assigned the thread allocation specified by the active workshift unless the total number of threads required to satisfy the allocations of all active work assignments exceeds the configured thread count. In this case, Oracle Enterprise Scheduler weighs the thread allocation against the percentage of threads allotted to the workshift out of the total number of thread allocations for all work assignments.

For example, suppose work assignment 1 has a thread allocation of 70, work assignment 2 has a thread allocation of 30, and there are 20 processor threads configured. The total desired allocation is 100, so the weight for work assignment 1 is 70 percent while the weight for work assignment 2 is 30 percent. Oracle Enterprise Scheduler allocates 14 threads to work assignment 1 and 6 threads to work assignment 2.

If the default work assignment is active, the number of threads allocated to the work assignment is equal to the configured thread count.

Note:

Each active work assignment is assigned at least one thread.

5.3.1.3 Processing Active Work Assignments

After determining work assignments and thread allocations, Oracle Enterprise Scheduler begins a thread pool for each active work assignment. The threads are responsible for processing job requests that are specialized to the work assignment, except for requests that are specialized to an exclusive work assignment. The exclusion is effective for all work assignments, including the default work assignment. If an exclusive work assignment is bound to any server in the group, no other work assignment can process job requests specialized to that exclusive work assignment.

Note:

All work assignments bound in exclusive mode are excluded, including disabled work assignments. Exclusive bindings apply even if the server to which they are bound is unavailable. You must unbind an exclusive work assignment if you do not want it to be excluded.

5.3.1.4 Creating or Editing a Work Assignment

A work assignment includes two primary components that define request processor constraints:

• Specialization rules: Define restrictions for job request processing on a request processor.

• Workshifts: Specify temporal windows for processing job requests and thus describe the schedule for when job requests can be processed on a request processor

This combination of work assignment controls, including specialization rules and workshifts gives you the ability to select the kinds of job requests to be processed and decide how to allocate the request processor resources. For example, you can define two workshifts: 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 24/7 duration, all configured threads are used and there are no limits on the number of asynchronous jobs.

Table 5-6 shows the properties that you can define for specialization rules.

Table 5-6 Specialization Properties Available for Specialization Rules

Specialization Property	Description
Application	Specifies the name of the application associated with a job request.
Product	Specifies the name of the product within an application.
Submitted By	Specifies a user who submitted a job request.
Job Definition	Specifies a specific job request name.
Request Category	Specifies labels defined by the system administrator allowing administrators to group job requests for specific requirements. You can include multiple labels that are separated by a delimiting character.
Logical Cluster Name	Specifies the name of the logical cluster.

The following operators are used for creating conditions: equals, not equals, contains, starts with, ends with and NOT (unary).

The following operators can be used to join the conditions of a rule: AND and OR (both of type binary).

Example 5-1 shows sample specialization rules that can be used in a work assignment.

If a job request is specialized to two different work assignments, either of those work assignments may process the job request depending on resource availability. Similarly, if the same work assignment is bound to two different servers, either server may process the job request. In fact, different stages of the same request may be processed on different servers, such as pre-processing 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 you can specify labels that mimic the behavior of tags, with specializations based on combinations of labels.

For example, you could define the following labels:

Assuming the preceding labels, you could write a requestCategory expression such as the following examples:

If you use commas to delimit terms, you must enclose every separate label term with the comma on both sides, as shown in Example 5-2. Your requestCategory expression must specify the full term including the commas, as shown in Example 5-3, to ensure that the expression does not select another term that contains the one you specify.

To create or edit a work assignment:

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 Work Assignments.

   The Work Assignments page displays.

3. Click the Create or Edit buttons to create or edit a work assignment.

   The Create (or Edit) Work Assignment page displays.

4. Enter a name and description for the work assignment in the relevant text fields.
5. Select the Enabled check box to enable the work assignment.
6. Click Create Specialization to add conditions under which the work assignment runs.
7. In the Workshifts section, click the Add button to add one or more workshifts to the work assignment.
8. Click OK to save the work assignment.

Example 5-1 Sample Specialization Rules

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')

Example 5-2 Request Category Labels That Combine Terms

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

Example 5-3 requestCategory Expressions That Use Multiple Combined Labels

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

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

5.3.1.5 Deleting a Work Assignment

You can delete a work assignment from the list of work assignments. Before deleting a work assignment, make sure that it is not bound to a request processor.

To delete a work assignment:

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 Work Assignments.

   The Work Assignments page displays.

3. Select the work assignment you want to delete and click Delete.

5.3.2 Managing Workshifts

A workshift indicates the operating, active times for a request processor. Specifically, a workshift defines a sequence of temporal windows in which resources or threads, are made available for processing job requests. When a work assignment is bound to a request processor, one or more workshifts are associated with the work assignment. At runtime, Oracle Enterprise Scheduler determines the resource allocation for the workshifts within the work assignment.

You can use different amounts of resources during different periods of time by using multiple workshifts, each with a different time window and resource limits. For example, you can create daytime workshift that starts at 8 a.m. and has your daytime thread allocation and async job limits; and you can create a nighttime workshift that starts at 6 p.m. and has your nighttime thread allocation and async job limits.

Note that workshifts may overlap, but Oracle Enterprise Scheduler chooses one workshift as the current workshift.

While there is at most one currently active workshift for a given work assignment, there may still be active requests for a workshift that is no longer active. This can happen if a request runs beyond the defined operating window for the workshift it started running in. For example, if a request started running while the daytime workshift was active and that request is still running when the nighttime workshift starts. Oracle Enterprise Scheduler uses the limits of the currently active workshift and accounts for all active requests that started during any workshift in the work assignment. If the number of active requests exceeds the current limit, no more requests are run until the number of active requests drops below the limit.

A workshift defines the following resources:

• Thread allocation

• Asynchronous job limits for asynchronous Java and PL/SQL jobs

Thread allocation specifies the number of threads that can be used by the request processor. These threads are used to perform local tasks, including processing synchronous jobs, initiating and finalizing asynchronous jobs, pre- and post-processing of job requests and updating events. When the workshift in a work assignment is active, each request processor for the work assignment can use the specified number of threads. For example, suppose a work assignment includes a 24x7 workshift with a thread allocation of 15. If that work assignment were bound to three request processors, each request processor could use 15 threads, for a total of 45 threads across all three servers.

Asynchronous, PL/SQL, and asynchronous Java jobs use a global resource that must be shared across the entire system. The workshift can specify limits on the number of PL/SQL jobs and asynchronous Java jobs that can be active for the work assignment. This limit applies across all request processors for the work assignment in the entire system. For example, suppose a work assignment includes a 24x7 workshift with a PL/SQL job limit of ten. If that work assignment were bound to three request processors, all three request processors share the ten PL/SQL asynchronous workers, for a maximum of ten PL/SQL jobs active for that work assignment.

An asynchronous job reserves and holds an asynchronous worker before pre-processing starts and through finalization. In the case of pre-process delay, the async worker is released during the delay and reserved when the delay ends. A request that submits a subrequest and pauses, releases its async worker and the async worker is reserved when the request is resumed. A BLOCKED request does not hold an async worker.

When deciding on thread allocation and asynchronous job limits for a workshift, take note of the types of jobs specialized to the work assignment where the workshift is to be used.

This section contains the following topics:

• Creating or Editing a Workshift

• Deleting a Workshift

5.3.2.1 Creating or Editing a Workshift

Creating a workshift involves the following:

• Schedule: Associate a schedule with the workshift.

• Duration: Enter a duration for the workshift.

• Thread allocation: Specify the number of threads you want to allocate to the workshift.

• Asynchronous job limits: Specify limits on the number of asynchronous Java jobs and PL/SQL jobs that can be active for the work assignment.

To create or edit a workshift:

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 the Create or Edit buttons to create or edit a workshift.

   The Create (or Edit) Workshift page displays.

4. Enter the following information for the workshift.

   • Schedule Name: Enter a name for the workshift.

   • Schedule 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 to always enable the workshift. Selecting this option disables the Duration text field.

   • Use existing schedule: Select to enable the workshift using a schedule you created previously. 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 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 dropdown list. You are presented with different options based on which frequency item you choose.

     From the Time Zone dropdown list, select a time zone for the schedule.

     In the Start 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 across all processors to which the work assignment is bound.

7. Click OK to save the workshift.

5.3.2.2 Deleting a Workshift

You can delete a workshift from the list of workshifts. Before attempting to delete a work assignment, make sure that it is not bound to a work assignment.

To delete a workshift:

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. Select the workshift you want to delete and click Delete.

5.3.3 Managing Schedules

Schedules are used to configure the start and end times as well as the frequency of work allocations and purge policies.

Note:

For information about scheduling job request execution, see Creating or Editing Predefined Job Schedules.

This section contains the following topics:

• Creating a Schedule

• Editing a Schedule

• Deleting a Schedule

5.3.3.1 Creating a Schedule

A job schedule specifies a predefined time or recurrence for execution. Work allocation and purge policy schedules are defined separately from job schedules. A job schedule can be associated with one or more jobs

To create a schedule:

1. From the navigation pane, expand the Scheduling Services folder and select the Oracle Enterprise Scheduler application.
2. There two ways to create schedules:

   • To create a schedule for job requests, select Job Requests and then select Define Schedules from the Scheduling Services menu.

   • To create a schedule for work assignments and purge policies, select Work Allocation and then select Schedules from the Scheduling Services menu.

3. Click Create to define a new schedule.

   The Create Schedule page displays.

4. Enter the following information:

   • Name: Enter a name for the schedule.

   • Description: Optionally, add descriptive text for the schedule.

   • Choose a frequency from the Frequency dropdown list. You are presented with different options based on which frequency item you choose.

   • From the Time Zone dropdown list, select a time zone for the schedule.

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

5. Click OK to save the schedule.

5.3.3.2 Editing a Schedule

To modify an existing schedule:

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 Schedules.

   The Schedules page displays.

3. Select a schedule from the table and click Edit.

   The Edit Schedule page displays.

4. Edit the following information:

   • Description: Optionally, change the descriptive text for the schedule.

   • Click the Change Frequency button. You are presented with different options based on which frequency item you choose.

   • From the Time Zone dropdown list, select a time zone for the schedule.

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

5. Click OK to save the schedule.

5.3.3.3 Deleting a Schedule

You can delete a schedule from the list of schedules.

To delete a schedule:

1. From the navigation pane, expand the Scheduling Services folder and select the Oracle Enterprise Scheduler application.
2. From the Scheduling Services menu, select Job Request and then select Schedules.

   The Schedules page displays.

3. Select the schedule you want to delete and click the Delete button.

   Note:

   To delete a work assignment or purge policy schedule, from the Scheduling Services menu, select Work Allocation and then select Schedules.

5.4 Managing Metadata Security for Jobs

You can manage the level of access assigned for working with job metadata.

Using Fusion Middleware Control, you can create policies that grant permissions for resources in your application.

5.4.1 Metadata Security Actions

You grant permissions by associating specific actions with resources, then granting those permissions (or permission/resource combinations) to particular users, groups, or roles.

When granting permissions, you specify the actions that someone can take with a given resources. Table 5-7 lists possible actions.

Table 5-7 Grant Actions for Metadata Security

Action	Effect
READ	Read the job metadata.
EXECUTE	Submit a job request.
CREATE	Add metadata.
UPDATE	Change the metadata.
DELETE	Delete the metadata.

The resources with which you associate permissions are expressed as entities known to the application, such as by the entity's containing package. That list includes items you or application developers might have defined as well as items Oracle Enterprise Scheduler has defined. Table 5-8 lists a few examples of the effect of granting permission for certain actions to certain resources.

Table 5-8 Sample Permission Grants for Security

Resource	Actions	Effect
mypackage.JobDefinition.MyJavaSucJobDef	EXECUTE	Grants the ability to submit requests for a single metadata item.
mypackage.subpackage.*	CREATE,EXECUTE	Grants to ability to create and execute any new metadata items in /mypackage/subpackage
JobDefinition.SYS_AdHocRequest	CREATE,EXECUTE	Grants ad hoc submission permission
mypackage.*	CREATE,EXECUTE,DELETE	Grants wide-open permissions

5.4.2 How to Create Metadata Policies for Oracle Enterprise Scheduler Resources

You can use Enterprise Manager to create functional To manage metadata permissions:

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

   The Application Policies page displays.

3. In the Search section, from the Application Stripe dropdown, select the application stripe with which you want to work.
4. Click Create to begin granting permissions to certain users, groups, or application roles.

   The Create Application Grant page appears.

5. In the Create Application Grant page, in the Grantee section, click Add.
6. In the Add Principal window, from the Type dropdown, select a type of principal, then enter a principal name or display name and click the search button to find the principal you want to add.
7. Under Search Principals, click the principal you want, then click OK.
8. In the Permissions section, click Add.
9. In the Search section, click Permissions.
10. From the Permission Class dropdown, select oracle.as.scheduler.security.MetadataPermission.
11. Click the Search button.
12. Under Search Results, select the resource to which you want to assign permissions.

    The Search Results table lists resources that represent entities known to the application. Table 5-8 lists a few examples.

13. Click Continue.
14. In the Add Permission window, in the Permission Actions field, edit the comma-separated list of permission actions so that the list reflects the permissions you want to grant.

    Table 5-7 lists possible actions.

15. Click OK.