10 Using Tokens and Logical Clusters

In order to make job definitions easily portable from test environments to production environments, it is best for job definitions not to contain environment-specific information such as host names and port numbers. The Oracle Enterprise Scheduler token substitution and logical cluster features allow you to abstract metadata so that it can be easily changed to correctly fit the target deployment during the T2P process.

This chapter contains the following sections:

• Using Token Substitution

• Using Logical Clusters

10.1 Using Token Substitution

To improve the flexibility of configuration and reduce the need for provisioning, Oracle Enterprise Scheduler allows you to include substitutable tokens in request parameters and environment properties.

Tokens take the following form: ${TokenPrefix:token}

Where token is the name of the token and TokenPrefix is where the substitution value is specified. Supported token prefixes are: APP_ENV, ESS_ENV, and ESS_REQ. The examples given below are simple, but illustrate the capabilities of Oracle Enterprise Scheduler substitution.

• APP_ENV

  The substitution value comes from the application environment properties.

  For example, the following environment variable is specified in the hosting application configuration properties using Oracle Enterprise Manager Fusion Middleware Control or WLST:

  AppEnvVar1=foo

  A request parameter is specified in a job definition:

  MyParam=${APP_ENV:appEnvVar1}

  After the substitution, the value of MyParam is foo.

• ESS_ENV

  Substitution values come from the Oracle Enterprise Scheduler server environment. This includes the following three possible sources:

  • JVM system properties: The token value is the name of the system property.

  • JVM environment variables: The token value is the name of the environment variable.

  • JRF: Token values are jrfServerLogPath, jrfServerConfigDirectory, and jrfDomainConfigDirectory.

  The following example shows the use of the ESS_ENV token prefix in the specification of an environment variable in the hosting application configuration properties.

  wlstLocation = ${ESS_ENV:common.components.home}/common/bin/wlst.sh.

  When the substitution is performed, the Oracle Enterprise Scheduler process job environment includes an environment variable named wlstLocation whose value is a complete path. For example:

  /myInstallHome/mw_home/oracle_common/common/bin/wlst.sh.

• ESS_REQ

  ESS_REQ substitutions come from information specific to the Oracle Enterprise Scheduler request in question. The following are the supported tokens:

  • REQUEST_ID

  • REQUEST_HANDLE

  • IS_RESUMED

  • PAUSED_STATE

  • Request parameter names for those requests

10.1.1 Nested Substitutions

Nested substitutions are automatically resolved when the top-level substitution is done. For example, the following request parameters are specified in a job definition for a process job:

MyParam1=${ESS_REQ:MyParam2}
MyParam2=${APP_ENV:MyEnvProp1}

An application's environment properties includes the following:

MyEnvProp1=${ESS_ENV:weblogic.Name}

The value of the JVM system property weblogic.Name might be something like ess_server1. When substitution is performed on MyParam1, it resolves to the value of MyParam2, which in turn resolves to the value of MyEnvProp1. The the result of the nested substitution is that the value of MyParam1 is ess_server1.

10.1.2 Automatic Substitution

Automatic Oracle Enterprise Scheduler substitution is available for process job command lines and environment properties, as well as for some request properties used by EJB and web service jobs.

These sections list the automatically substituted request parameters for EJB jobs, web service jobs, and process jobs.

For more information about these properties refer to the following chapters:

• Creating and Using EJB Jobs

• Creating and Using Web Service Jobs

• Creating and Using Process Jobs .

EJB Job Type Automatically Substituted Properties

The automatically substituted properties for the EJB job type are:

• SYS_EXT_jndiProviderUrl

• SYS_EXT_essRuntimeJndiMappedName

• SYS_EXT_essMetadataJndiMappedName

• SYS_EXT_essAsyncRequestJndiMappedName

• SYS_EXT_essJndiCsfKey

• SYS_EXT_invokeMessage

Web Services Job Type: Automatically Substituted Properties

The automatically substituted properties for the web service job type are:

• SYS_EXT_wsEndpointBaseUrl

• SYS_EXT_wsEndpointUrl

• SYS_EXT_wsWsdlBaseUrl

• SYS_EXT_wsWsdlUrl

• SYS_EXT_invokeMessage

• SYS_EXT_wsCancelMessage

Process Job Type: Automatically Substituted Properties

The automatically substituted properties for the process job type are:

• SYS_cmdLine

• SYS_EXT_cmdLine.Unix

• SYS_EXT_cmdLine.Windows

• SYS_environmentVariables

10.2 Using Logical Clusters

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 or WLST commands 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 or WLST commands.

Note:

Oracle Enterprise Manager Fusion Middleware Control refers to logical cluster functionality as "job location." The terms "logical clusters" and "job location" can be used interchangeably.

If a job definition specifies a value for the SYS_logicalClusterName property, then the value is used as a prefix for a set of application configuration properties that define attributes of the logical cluster. Table 10-1 lists the properties associated with job location, where prefix represents the logical cluster name. Note that these properties need not be specified if they are configured in the hosting application.

Table 10-1 Properties Associated With a Job Location

Property Name	Corresponding System Property	Description
LCN.prefix.JndiProviderUrl	SYS_EXT_jndiProviderUrl	The JNDI provider for the cluster. Used with the EJB job type. The corresponding system property, SYS_EXT_jndiProviderUrl, need not be specified in the job.
LCN.prefix.WsEndpointBaseUrl	SYS_EXT_wsEndpointBaseUrl	The host and port. For example, http://host:port/. Used with the EJB job type. The corresponding system property, SYS_EXT_wsEndpointBaseUrl, need not be specified in the job.
LCN.prefix.WsWsdlBaseUrl	SYS_EXT_wsWsdlBaseUrl	The host and port of the WSDL. For example, http://host:port/. Used with the EJB job type. The Corresponding system property, SYS_EXT_wsWsdlBaseUrl, need not be specified in the job.

For example, if a job defines the SYS_logicalClusterName property as SOA_Cluster1, then the application configuration might contain the following properties:

LCN.SOA_Cluster1.WsEndpointBaseURL=http://host:port/
LCN.SOA_Cluster1.WsWsdlBaseURL=http://host:port/
LCN.SOA_Cluster1.JndiProviderURL=t3://host1;port1;host2:port2/

Note:

The value of the SYS_logicalClusterName property cannot contain the “." character.