7 Adding Job Types

7.4.1 Understanding Job Type Categories

A job type can have one of the following categories depending on how it performs tasks on the targets to which it is applied:

• Single-Node

  A single-node job type is a job type that runs the same set of steps in parallel on every target on which the job is run. Typically, the target lists for these job types is not fixed. They can take any number of targets. The following are examples of single-node job types:

  • OSCommand

    Runs an OS command or script on all of its targets.

  • SQL

    Runs a specified SQL script on all of its targets.

• Multi-Node/Combination

  A multi-node job type is a job type that performs different, possibly inter-related tasks on multiple targets. Such job types typically operate on a fixed set of targets. For example, a Clone job that clones an application schema might require two targets, a source database and a target database.

  Note:

  Iterative stepsets may be used for multi-node and combination job types to repeat the same activity over multiple targets.

7.4.2 Using Agent-Bound Job Types

An Agent-bound job type is one whose jobs cannot be run unless the Agent of one or more targets in the target list is functioning and responding. A job type that fits this category must declare itself to be Agent-bound by setting the agentBound attribute of the jobType XML tag to true.

If a job type is Agent-bound, then the job system does not schedule any executions if one or more of the Agents corresponding to the targets in the target list of the job execution are down or not responding. The job (and all its scheduled steps) is set to a special state called Suspended/Agent down. The job is kept in this state until the Enterprise Manager repository tier detects that the emd has come back up.

At this point, the job and its steps are set to scheduled status again and the job can now execute. By declaring their job types to be Agent-bound, a job-type writer can ensure that the job system will not schedule the job when it has detected that the Agent is down.

If an Agent-bound job has multiple targets in its target list, it is marked as Suspended even if one of the Agents goes down.

A good example of an Agent-bound job type is the OSCommand job type, which executes an OSCommand using the Agent of a specified target. However, not all job types are Agent-bound. For example, a job type that executes SQL in the Management Repository is not Agent-bound.

Enterprise Manager has a heartbeat mechanism that enables the repository tier to quickly determine when a remote emd goes down. After an emd is marked as Down, all Agent-bound job executions that have this emd in their target list are marked Suspended/Agent Down. However, there is still a possibility that the job system will try to dispatch some remote operations during the time the emd went down and when the Management Repository detects the fact. In cases when agent cannot be contacted and the step executes, the step is set back to a SCHEDULED state and is retried by the job system. The series of retries continues until the heartbeat mechanism marks the node as down, at which point the job is suspended.

When a job is marked as Suspended/Agent Down, by default the job system keeps the job in that state until the emd comes back up. However, there is a parameter called the grace period which, if defined, can override this behavior. The grace period is the maximum amount of time (in minutes) that a job's execution is allowed to start executing within. If the job cannot start within this grace period, the job execution is skipped for that schedule.

The only way that a job execution in a Suspended/Agent Down state can resume is for the Agents to come back up. The resume_execution() APIs cannot be used to resume the job.

7.4.3 About Job Steps

The unit of execution in a job is called a step. A step has a command, which determines what work the step will be doing. Each command has a Java class, called a command executor, that implements the command. A command also has a set of parameters, which will be interpreted by the command executor.

The job system will offer a fixed set of pre-built commands, such as the remote operation command (which executes a command remotely), the file transfer command that transfers a file between two Agents, and a get file command that streams a log file produced on the Agent tier into the Management Repository).

Steps are grouped into sets called stepsets. Stepsets can contain steps or other stepsets and can be categorized into the following types:

• Serial Stepsets

  Serial stepsets are stepsets whose steps execute serially. Steps in a serial stepset can have dependencies on their execution. For example, a job can specify that step S2 executes only if step S1 completes successfully, or that step S3 executes only if S1 fails.

  Steps in a serial stepset can have dependencies only on other steps or stepsets within the same stepset. By default, a serial stepset is considered to complete successfully if the last step in the stepset completed successfully. It is considered to have aborted/failed if the last step in the stepset was aborted. This behavior may be overridden by using the stepsetStatus attribute. Overriding is allowed only when the step is not a dependent on another (no successOf/failureOf/abortOf attribute).

• Parallel Stepsets

  Parallel stepsets are stepsets whose steps execute in parallel (execute simultaneously). Steps in a parallel stepset cannot have dependencies. A parallel stepset is considered to have succeeded if all the parallel steps have completed successfully. It is considered to have aborted if any step within it was aborted. By default, a parallel stepset is considered to have failed if one or more of its constituent steps failed, and no steps were aborted. This behavior can be overridden by using the stepsetStatus attribute.

• Iterative Stepsets

  Iterative stepsets are special stepsets that iterate over a vector parameter. The target list of a job is available using special, implicit parameters named job_target_names and job_target_types. An iterative stepset iterates over the target list or vector parameter and essentially executes the stepset N times; once for each value of the target list or vector parameter.

  Iterative stepsets can execute in parallel (N stepset instances execute at simultaneously), or serially (N stepset instances are scheduled serially, one after another). An iterative stepset is said to have succeeded if all its N instances have succeeded. Otherwise, it is said to have aborted if at least one of the N stepsets aborted. It is said to have failed if at least one of the N stepsets failed and none were aborted. An abort will always cause an iterative stepset to stop processing further.

  Steps within each iterative stepset instance execute serially and can have serial dependencies similar to those within serial stepsets. Iterative serial stepsets have an attribute called iterateHaltOnFailure (not applicable for iterativeParallel stepsets). If this is set to true, the stepset halts at the first failed or aborted child iteration. By default, all iterations of an iterative serial stepset execute, even if some of them fail (iterateHaltOnFailure=false).

• Switch Stepsets

  Switch stepsets are stepsets where only one of the steps in the stepset is executed based on the value of a specified job parameter. A switch stepset has an attribute called switchVarName, which is a job (scalar) parameter whose value will be examined by the job system to determine which of the steps in the stepset should be executed. Each step in a switch stepset has an attribute called switchCaseVal, which is one of the possible values the parameter specified by switchVarName can have.

  The step in the switch stepset that is executed is the one whose switchCaseVal parameter value matches the value of the switchVarName parameter of the switch stepset. Only the selected step in the switch stepset is executed. Steps in a switch stepset cannot have dependencies with other steps or stepsets within the same stepset or outside.

  By default, a switch stepset is considered to complete successfully if the selected step in the stepset completed successfully. It is considered to have aborted/failed if the selected step in the stepset was aborted/failed. Also, a switch stepset will succeed if no step in the stepset was selected.

  For example, if there is a switch stepset with two steps, S1 and S2 and you specify that switchVarName is sendEmail and that switchCaseVal for S1 is true and false for S2. If the job is submitted with the job parameter sendEmail set to true, then S1 will be executed. If the job is submitted with the job parameter sendEmail set to false, then S2 will be executed. If the value of sendEmail is anything else, the stepset will still succeed but do nothing.

• Nested Jobs

  One of the steps in a stepset may itself be a reference to another job type. A job type can therefore include other job types within itself. However, a job type cannot reference itself.

  Nested jobs are a convenient way to reuse blocks of functionality. For example, performing a database backup could be a job in its own right, with a complicated sequence of steps. However, other job types (such as patch and clone) might use the backup facility as a nested job. With nested jobs, the job type writer can choose to pass all the targets of the containing job to the nested job, or only a subset of the targets. Likewise, the job type can specify whether the containing job should pass all its parameters to the nested job or whether the nested job has its own set of parameters (derived from the parent job's parameters). The status of a nested job is determined by the status of the individual steps and stepsets (and possibly other nested jobs) within the nested job.

7.5.1 About the remoteOp Command

The remote operation command has the identifier remoteOp. The command accepts a credential usage with name as defaultHostCred. These credentials are required to perform the operation on the host of the target. The binding can be performed as follows:

<step ID="Step_2" command="remoteOp">
  <credList>
    <cred usage="defaultHostCred" reference="osCreds"/>
  </credList>
  <paramList>
    <param name="targetName">%job_target_names%[1]</param>
    <param name="targetType">%job_target_types%[1]</param>
    <param name="remoteCommand">%remoteCommand%</param>
    <param name="args">%args%</param>
    <param name="executeSynchronous">false</param>
  </paramList>
</step>

Here defaultHostCred is the credential usage which is understood by the command. For example, the java code in the command would make a call for credential with this sting, whereas the osCreds is the credential usage declared in the job type at the top level.

It takes the following parameters:

• remoteCommand: The path name to the executable/script (for example, /usr/local/bin/perl).

• args: A comma-separated list of arguments to the remoteCommand.

• targetName: The name of the target that the command is executed on. Note that placeholders can be used to represent targets.

• targetType: The target type that the command is executed on.

• executeSynchronous: This option defaults to false whereby a remote command always executes asynchronously on the Agent and the status of the step is updated after the command is done executing.

  If set to true, the command executes synchronously, waiting until the Agent completes the process. Typically, this parameter is set to true for quick, short-lived remote operations (such as starting up a listener). For remote operations that take a long time to execute, this parameter should always be set to false.

• successStatus: A comma-separated list of integer values that determines the success of the step. If the remote command returns any of these numbers as the exit status, the step is considered successful. The default is zero. These values are only applicable when executeSynchronous is set to true.

• failureStatus: A comma-separated list of integer values that determines the failure of the step. If the remote command returns any of these numbers as the exit status, the step is considered to have failed. The default is all non-zero values. These values are only applicable when executeSynchronous is set to true.

• input: If specified, this is passed as standard input to the remote program.

• outputType: Specifies the type of output the remote command is expected to generate. This can have two values, normal (the default) or command. Normal output is output that is stored in the log corresponding to this step and is not interpreted in any way. Command output is output that could contain one or more command blocks, which are XML sequences that map to pre-registered SQL procedure calls. By using the command output option, a remote command can generate command blocks that can be directly loaded into schema in the Enterprise Manager repository database.

The standard output generated by the executed command is stored by the job system as the output corresponding to this step.

7.5.2 Using the fileTransfer Command

The fileTransfer command transfers a file from one Agent to another. It can also execute a command on the source Agent and transfer its standard output as a file to the destination Agent or as standard input to a command on the destination Agent. The fileTransfer command is always asynchronous and it takes the following parameters:

<step ID="S1" command="fileTransfer">
  <credList>
      <cred usage=”srcReadCreds” reference=”mySourceReadCreds”/>
      <cred usage=”dstWriteCreds” reference=”myDestWriteCreds”/>
  </credList>
    <paramList>
      <param name="sourceTargetName">%job_target_names%[1]</param>
      <param name="sourceTargetType">%job_target_types%[1]</param>
      <param name="destTargetName">%job_target_names%[2]</param>
      <param name="destTargetType">%job_target_types%[2]</param>
      <param name="sourceFile">%sourceFile%</param>
      <param name="sourceCommand">%sourceCommand%</param>
      <param name="sourceArgs">%sourceArgs%</param>
      <param name="sourceInput">%sourceInput%</param>
      <param name="destFile">%destFile%</param>
      <param name="destCommand">%destCommand%</param>
      <param name="destArgs">%destArgs%</param>
  </paramList>
</step>

The following command uses two credentials. The srcReadCreds credential is used to read the file from the source and the dstWriteCreds credential is used to write the file to the destination. The binding can be performed as follows:

<step ID="S1" command="fileTransfer">
      <credList>
        <cred usage=”srcReadCreds” reference=”mySourceReadCreds”/>
        <cred usage=”dstWriteCreds” reference=”myDestWriteCreds”/>
      </credList>
  <paramList>
    <param name="sourceTargetName">%job_target_names%[1]</param>
    <param name="sourceTargetType">%job_target_types%[1]</param>
    <param name="destTargetName">%job_target_names%[2]</param>
    <param name="destTargetType">%job_target_types%[2]</param>
    <param name="sourceFile">%sourceFile%</param>
    <param name="sourceCommand">%sourceCommand%</param>
    <param name="sourceArgs">%sourceArgs%</param>
    <param name="sourceInput">%sourceInput%</param>
    <param name="destFile">%destFile%</param>
    <param name="destCommand">%destCommand%</param>
    <param name="destArgs">%destArgs%</param>
  </paramList>
</step>

• sourceTargetName: The target name corresponding to the source Agent.

• destTargetName: The target name corresponding to the destination Agent.

• destTargetType: The target type corresponding to the destination Agent.

• sourceFile: The file to be transferred from the source Agent.

• sourceCommand: The command to be executed on the source Agent. If this is specified, then the standard output of this command is streamed to the destination Agent. Both sourceFile and sourceCommand parameters cannot be specified.

• sourceArgs: A comma-separated set of command-line parameters for the sourceCommand.

• destFile: The location or file name where the file is to be stored on the destination Agent.

• destCommand: The command to be executed on the destination emd. If this is specified, then the stream generated from the source emd (whether from a file or from a command) is sent to the standard input of this command. Both destFile and destCommand parameters cannot be specified.

• destArgs: A comma-separated set of command-line parameters for the destCommand.

The fileTransfer command succeeds (and returns a status code of 0) if the file was successfully transferred between the Agents. If there was an error, it returns error codes appropriate to the reason for failure.

7.5.3 About the putFile Command

The putFile command affords the capability to transfer large amounts of data from the Management Repository to a file on the Management Agent. The data transferred can come from a blob in the Management Repository, a file on the file system, or be embedded in the specification (inline).

If a file is being transferred, the location of the file must be accessible from the Management Repository installation. If a blob in a database is being transferred, it must be in a table in the Management Repository database that is accessible to the Management Repository schema user (typically mgmt_rep).

The command accepts a credential usage with name as defaultHostCred. These credentials are required to write the file at the host of the target. The binding can be performed as follows:

<step ID="S1" command="putFile">
       <credList>
          <cred usage="defaultHostCred" reference="osCreds"/>
       </credList>
    <paramList>
     <param name="sourceType">file</param>
     <param name="targetName">%job_target_names%[1]</param>
     <param name="targetType">%job_target_types%[1]</param>
     <param name="sourceFile">%oms_root%/myfile</param>
     <param name="destFile">%emd_root%/yourfle</param>
   </paramList>
</step>

The putFile command requires the following parameters:

• sourceType: The type of the source data. This may be sql, file, or inline.

• targetName: The name of the target where the file is to be transferred (destination Agent).

• targetType: The type of the destination target.

• sourceFile: The file to be transferred from the Management Repository, if the sourceType is set to fileSystem. This must be a file that is accessible to the Management Repository installation.

• sqlType: The type of SQL data (if the sourceType is set to sql). Valid values are CLOB and BLOB.

• accessSql: A SQL statement that is used to retrieve the blob data (if the sourceType is set to sql). For example, " select output from my_output_table where blob_id=%blobid%".

• destFile: The location or file name where the file is to be stored on the destination Agent.

• contents: If the sourceType is set to "inline", this parameter contains the contents of the file. Note that the text could include placeholders for parameters in the form %param%.

The putFile command succeeds if the file was transferred successfully and the status code is set to 0. On failure, the status code is set to an integer appropriate to the reason for failure.

7.5.4 Using the getFile Command

The getFile command transfers a file from a Management Agent to the Management Repository. The file is stored as the output of the step that executed this command.

The command accepts a credential usage with name as defaultHostCred. These credentials are required to read the file at the host of the target. The binding can be performed as follows:

<step ID="S1" command="getFile">
       <credList>
         <cred usage="defaultHostCred" reference="osCreds"/>
       </credList>
   <paramList>
     <param name="targetName">%job_target_names%[1]</param>
     <param name="targetType">%job_target_types%[1]</param>
     <param name="sourceFile">%sourceFile%</param>
     <param name="destType">%destType%</param>
     <param name="destFile">%destFile%</param>
     <param name="destParam">%destParam%</param>
   </paramList>
</step>

The getFile command has the following parameters:

• sourceFile: The location of the file to be transferred on the Agent.

• targetName: The name of the target whose Agent will be contacted to get the file.

• targetType: The type of the target.

The getFile command succeeds if the file was transferred successfully and the status code is set to 0. On failure, the status code is set to an integer appropriate to the reason for failure.

7.5.5 Using the execAndSuspend Command

The execAndSuspend command accepts a credential usage with name as defaultHostCred. These credentials are required to perform the operation on target host of the target. The binding can be performed as follows:

<step ID="Ta_S1_suspend" command="execAndSuspend">
      <credList>
         <cred usage="defaultHostCred" reference="osCreds"/>
      </credList>
   <paramList>
     <param name="remoteCommand">%command%</param>
     <param name="args">%args%</param>
     <param name="targetName">%job_target_names%[1]</param>
     <param name="targetType">%job_target_types%[1]</param>
     <param name="suspendTimeout">2</param>
   </paramList>
</step>

Here defaultHostCred is the credential usage which is understood by the command. For example, the java code in the command would make a call for credential with this sting, whereas the osCreds is the credential usage declared in the job type at the top level.

7.7.1 Configuring the Job Dispatcher to Handle Long-Running Commands

The dispatcher is a component of the job system that executes the various steps of a job when they are ready to execute. The command class associated with each step is called and any asynchronous operations requested by it are dispatched; a process referred to as dispatching a step. The dispatcher uses thread-pools to execute steps. A thread-pool is a collection of a specified number of worker threads, any one of which can dispatch a step.

The job system dispatcher uses two thread-pools, namely, a short-command pool for dispatching asynchronous steps and short synchronous steps, and a long-command pool for dispatching steps that have long-running commands. Typically, the short-command pool will have a larger number of threads (for example, 25) compared to the long-running pool (for example, 10).

The theory is that long-running middle-tier steps will be few compared to more numerous, short-running commands. However, the sizes of the two pools will be fully configurable in the dispatcher to suit the job mix at a particular site. Since multiple dispatchers can be run on different nodes, the site administrator will be able to even dedicate a dispatcher to only dispatch long-running or short-running steps.

7.8.1 Understanding SQLParameter Source

The SQL parameter source allows the plug-in developer to specify a SQL query or a PL/SQL procedure that will fetch a set of parameters.

<paramSource sourceType="sql" paramNames="param1, param2, ...">
      <sourceParam name="procName"   value="MyPackage.MyPLSQLProc"/>
      <sourceParam name="procParams" value="%a%, %b%[1], ..."/>
    </paramSource>

<paramSource sourceType="sql" paramNames="db_role_suffix">
      <sourceParam name="procName"   value="MGMT_JOB_FUNCTIONS.get_dbrole_
        prefix"/>
      <sourceParam name="procParams" value="%job_id%, %job_execution_id%, db_
        role"/>
    </paramSource>

7.8.2 About the User Parameter Source

The job system also offers a special parameter source called "user" which indicates that a set of parameters must be supplied when a job of that type is submitted. If a parameter is declared to be of source "user" and the "required" attribute is set to "true", the job system will validate that all specified parameters in the source are provided when a job is submitted.

The user source can be evaluated at job submission time or job execution time. When evaluated at submission time, it causes an exception to be thrown if any required parameters are missing. When evaluated at execution time, it causes the execution to abort if there are any missing required parameters.

<paramInfo>
    <!-- Indicate that parameters a, b and c are required params -->
    <paramSource paramNames="a, b, c" required="true" sourceType="user" />
</paramInfo>

The user source can also be used to indicate that a pair of parameters are target parameters. For example:

<paramInfo>
    <!-- Indicate that parameters a, b, c, d, e, f are target params -->
    <paramSource paramNames="a, b, c, d, e, f" sourceType="user" >
        <sourceParam name="targetNameParams" value="a, b, c" />
        <sourceParam name="targetTypeParams" value="d, e, f" />
    </paramSource>
</paramInfo>

The example shown above indicates that parameters (a,d), (b,e), (c,f) are parameters that hold target information. Parameter "a" holds target names and "d" holds the corresponding target types. Similarly with parameters "b" and "e", and "c" and "f". For each parameter that holds target names, there must be a corresponding parameter that holds target types. The parameters may be either scalar or vector.

7.8.3 About the Inline Parameter Source

The inline parameter source allows job types to define parameters in terms of other parameters. It is a convenient mechanism to construct parameters that can be reused in other parts of the job type. For example, the section below creates a parameter called filename based on the job execution id, presumably for use in other parts of the job type.

<jobType>
      <paramInfo>
           <!-- Indicate that value for parameter filename is provided inline -->
           <paramSource paramNames="fileName" sourceType="inline" >
                <sourceParam name="paramValues" value="%job_execution_id%.log" />
                </paramSource>
      </paramInfo>
.....
      <stepset ID="main" type="serial">
        <step command="putFile" ID="S1">
             ...
            <param name="destFile">%fileName%</param>
             ...
        </step>
      </stepset>
</jobType>

The following example sets a vector parameter called vparam to be a vector of the values v1, v2, v3, and v4. Only one vector parameter at a time can be set using the inline source.

<jobType>
      <paramInfo>
          <!-- Indicate that value for parameter vparam is provided inline -->
          <paramSource paramNames="vparam" sourceType="inline" >
              <sourceParam name="paramValues" value="v1,v2,v3,v4" />
              <sourceParam name="vectorParams" value="vparam" />
          </paramSource>
      </paramInfo>
....

7.8.4 Using the checkValue Parameter Source

The checkValue parameter source allows job types to have the job system check that a specified set of parameters has a specified set of values. If a parameter does not have the specified value, the job system will either terminate or suspend the job.

<paramInfo>
      <!-- Check that the parameter halt has the value true. If not, suspend the job
-->
      <paramSource paramNames="halt" sourceType="checkValue" >
          sourceParam name="paramValues" value="true" />
          <sourceParam name="action" value="suspend" />
      </paramSource>
</paramInfo>

The following example checks whether a vector parameter v has the values v1,v2,v3, and v4. Only one vector parameter at a time can be specified in a checkValue parameter source. If the vector parameter does not have those values, in that order, then the job is terminated.

<paramInfo>
    <!-- Check that the parameter halt has the value true. If not, suspend the job -->
    <paramSource paramNames="v"  sourceType="checkValue" >
        <sourceParam name="paramValues" value="v1,v2,v3,v4" />
        <sourceParam name="action" value="abort" />
        <sourceParam name="vectorParams" value="v" />
    </paramSource>
</paramInfo>

7.8.5 About the properties Parameter Source

The properties parameter source fetches a named set of target properties for each of a specified set of targets and stores each set of property values in a vector parameter.

The example below fetches the properties "OracleHome" and "OracleSID" for the specified set of targets (dlsun966 and ap952sun), into the vector parameters ohomes and osids, respectively. The first vector value in the ohomes parameter will contain the OracleHome property for dlsun966, and the second will contain the OracleHome property for ap952sun. Likewise with the OracleSID property.

<paramInfo>
    <!-- Fetch the OracleHome and OracleSID property into the vector params ohmes, osids -->
    <paramSource paramNames="ohomes,osids" overrideUser="true" sourceType="properties">
      <sourceParams>
            <sourceParam name="propertyNames" value="OracleHome,OracleSID" />
            <sourceParam name="targetNames" value="dlsun966,ap952sun" />
            <sourceParam name="targetTypes" value="host,host" />
      </sourceParams>
    </paramSource>
</paramInfo>

As with the credentials source, vector parameter names can be provided for the target names and types.

<paramInfo>
    <!-- Fetch the OracleHome and OracleSID property into the vector params ohmes, osids -->
    <paramSource paramNames="ohomes,osids" overrideUser="true" sourceType="properties">
      <sourceParams>
            <sourceParam name="propertyNames" value="OracleHome,OracleSID" />
            <sourceParam name="targetNamesParam" value="job_target_names" />
            <sourceParam name="targetTypes" value="job_target_types" />
      </sourceParams>
    </paramSource>
</paramInfo>

7.8.6 Understanding Parameter Sources and Parameter Substitution

Parameter sources are applied in the order they are specified. Parameter substitution (of the form %param%) can be used inside sourceParam tags, but the parameter that is being substituted must exist when the parameter source is evaluated. Otherwise, the job system will substitute an empty string in its place.

7.8.7 About Parameter Encryption

The job system offers the facility of storing specified parameters in encrypted form. Parameters that contain sensitive information, such as passwords, must be stored encrypted. A job type can indicate that parameters fetched through a parameter source be encrypted by setting the encrypted attribute to true in a parameter source.

For example:

<paramInfo>
    <!-- Fetch params from the credentials table into vector parameters; store them encrypted -->
    <paramSource paramNames="vec_usernames,vec_passwords" overrideUser="true" 
                                  sourceType="credentials" encrypted="true">
      <sourceParams>
            <sourceParam name="credentialType" value="patch" />
            <sourceParam name="credentialColumns" value="node_username,node_password" />
            <sourceParam name="targetNames" value="dlsun966,ap952sun" />
            <sourceParam name="targetTypes" value="host,host" />
            <sourceParam name="credentialScope" value="system" />
      </sourceParams>
    </paramSource>
</paramInfo>

A job type can also specify that parameters supplied by the user be stored encrypted:

<paramInfo>
    <!-- Indicate that parameters a, b and c are required params -->
    <paramSource paramNames="a, b, c" required="true" sourceType="user" encrypted="true" />
</paramInfo>

7.9.1 About Credential Usage

A credential usage is the point where the credential is required to perform an operation. The various tags present in the credential usage are required to mainly paint the credential selector UI component provided by the project 28263. Credential submissions should be made against these usages only.

7.9.2 Overview of Credential Binding

A credential binding is a reference of a credential by a step. Each step exposes its credential usage which needs to be fulfilled in the metadata. Therefore, each credential binding refers to a reference credential usage that is defined in the credential usage section of the metadata. When the step requests its own credential usage, a binding helps resolve which credential submission in a particular automation entity (Job or DP instance) should be passed to that step.

In earlier releases, the job types would have a credential parameter source to extract the username and password from the credentials (JobCredRecord) passed to the job and then these were available as parameters to the entire job type. This behavior has been deprecated with no support and is being superseded by the new credential usage structure.

The following Job type example shows the use of credentials declaration in the job type:

<jobType version="1.0" name="OSCommandNG" 
         singleTarget="true" targetTypes="all" 
         defaultTargetType="host" editable="true" 
         restartable="true" suspendable="true" > 
    <credentials> 
       <credential usage=”hostCreds” authTargetType=”host” 
                   defaultCredentialSet=”HostCredsNormal”/> 
    </credentials> 
    <paramInfo> 
         <paramSource sourceType="user" paramNames="command" 
              required="true" evaluateAtSubmission="true" /> 
         <paramSource sourceType="inline" 
                      paramNames="TargetName,TargetType" 
                    overrideUser="true" 
            evaluateAtSubmission="true"> 
             <sourceParam name="paramValues" 
                         value="%job_target_names%[1],
                           %job_target_types%[1]" /> 
         </paramSource> 
         <paramSource sourceType="properties" 
                    overrideUser="true" 
            evaluateAtSubmission="false" > 
            <sourceParam name="targetNamesParam" 
                        value="job_target_names" /> 
            <sourceParam name="targetTypesParam" 
                        value="job_target_types" /> 
         </paramSource> 
         <paramSource sourceType="substValues" 
                      paramNames="host_command,host_args,os_script" 
                    overrideUser="true" evaluateAtSubmission="false"> 
              <sourceParam name="sourceParams" 
                          value="command,args,os_script" /> 
         </paramSource> 
     </paramInfo> 
     <stepset ID="main" type="serial" > 
        <step ID="Command" command="sampleRemoteOp"> 
           <credList> 
              <cred usage=”OS_CRED” reference=”hostCreds”/> 
           </credList> 
           <paramList> 
              <param name="remoteCommand">%host_command%</param> 
              <param name="args">%host_args%</param> 
              <param name="input"><![CDATA[%os_script%]]></param> 
              <param name="largeInputParam">large_os_script</param> 
              <param name="substituteLargeParam">true</param> 
              <param name="targetName">%job_target_names%[1]</param> 
              <param name="targetType">%job_target_types%[1]</param> 
              <param name="executeSynchronous">false</param> 
          </paramList> 
       </step> 
    </stepset> 
</jobType> 

The first set of three lines declares a credential usage in the job type. The next set of lines binds the credential usage to that of the step. Note that user name and password cannot be extracted by the jobs system and therefore can no longer be exposed as parameters.

7.9.3 XSD Elements – Credential Usage and Credential Binding

The XSD element credential usage and credentials binding are explained in Table 7-3 and Table 7-4.

7.13.1 Restarting Versus Resubmitting

If a step in a job is resubmitted, it means that it executes regardless of whether the original execution of the step completed or failed. If a stepset is resubmitted, then the first step/stepset/job in the stepset is resubmitted, recursively. Therefore, when a job is resubmitted the entire job is executed again by recursively resubmitting its initial stepset. The parameters and targets used are the same that were used when the job was first submitted. Essentially, the job executes as if it were submitted for the first time with the specified set of parameters and targets. A job can be resubmitted by using the resubmit_job API in the mgmt_jobs package. Jobs can also be resubmitted even if the earlier executions completed successfully.

Job executions that were aborted or failed can be restarted. Restarting a job generally refers to resuming job execution from the last failed step (although the job type can control this behavior using the restartMode attribute of steps/stepsets/jobs). In the common case, steps from the failed job execution that actually succeeded are not re-executed. A failed or terminated job can be restarted by calling the restart_job API in the mgmt_jobs package. A job that completed successfully cannot be restarted.

7.13.2 Default Restart Behavior

Restarting a job creates a new execution called the restart execution. The original, failed execution of the job is called the source execution. All parameters and targets are copied over from the source execution to the restart execution. Parameter sources are not reevaluated, unless the original job aborted because of a parameter source failure.

To restart a serial (or iterative stepset), the job system first examines the status of the serial stepset. If the status of the serial stepset is "Completed", then all the entries for its constituent steps are copied over from the source execution to the restart execution. If the status of the stepset is "Failed" or "Aborted", then the job system starts top down from the first step in the stepset.

If the step previously completed successfully in the source execution, it is copied to the restart execution. If the step previously failed or aborted, it is rescheduled for execution in the restart execution. After such a step has finished executing, the job system determines the next steps to execute. These could be successOf or failureOf dependencies, or simply steps/stepsets/jobs that execute after the current step.

If the subsequent step completed successfully in the source execution, then it will not be scheduled for execution again and the job system merely copies the source execution status to the restart execution for that step. It continues in this fashion until it reaches the end of the stepset. It then recomputes the status of the stepset based on the new executions.

To restart a parallel stepset, the job system first examines the status of the parallel stepset. If the status of the stepset is "Completed", then all the entries for its constituent steps are copied over from the source execution to the restart execution. If the status of the stepset is "Failed" or "Aborted", the job system copies over all successful steps in the steps from the source to the restart execution. It reschedules all steps that failed or aborted in the source execution, in parallel. After these steps have finished executing, the status of the stepset is recomputed.

To restart a nested job, the restart algorithm is applied recursively to the first (outer) stepset of the nested job.

Note that in the previous paragraphs, if one of the entities being considered is a stepset or a nested job, the restart mechanism is applied recursively to the stepset or job. When entries for steps are copied over to the restart execution, the child execution entries point to the same output CLOB entries as the parent execution.

7.13.3 Using the restartMode Directive

A job type can affect the restart behavior of each step, stepset, or job within it by the use of the restartMode attribute. This can be set to "failure" (the default) or "always". When set to failure and the top-down copying process described in the previous section occurs, the step, stepset, or job is copied without being re-executed if it succeeded in the source execution. If it failed or terminated in the source execution, it is restarted recursively at the last point of failure.

When the restartMode attribute is set to "always" for a step, the step is always re-executed in a restart, regardless of whether it succeeded or failed in the source execution. The use of this attribute is useful when certain steps in a job must always be re-executed in a restart (for example, a step that shuts down a database prior to backing it up).

For a stepset or nested job, if the restartMode attribute is set to "always", then all steps in the stepset/nested job are restarted, even if they completed successfully in the source execution. If it is set to "failure", then restart is attempted only if the status of the stepset or nested job was set to Failed or Aborted in the source execution.

Note that individual steps inside a stepset or nested job may have their restartMode set to "always" and such steps are always re-executed.

Restart Examples

The following sections discuss a range of scenarios related to restarting stepsets.

Example 1

Consider the serial stepset with the sequence of steps below:

<jobtype ...>
<stepset ID="main" type="serial" >
    <step ID="S1" ...>
     ...
    </step>
    <step ID="S2" ...>
     ...
    </step>
    <step ID="S3" failureOf="S2"...>
     ...
    </step>
    <step ID="S4" successOf="S2"...>
     ...
    </step> 
</stepset>
</jobtype>

In the above stepset, assume the source execution had S1 execute successfully and step S2 and S3 (the failure dependency of S2) fail. When the job is restarted, steps S1 is copied to the restart execution from the source execution without being re-executed (since it successfully completed in the source execution). Step S2, which failed in the source execution, is rescheduled and executed. If S2 completes successfully, then S4, its success dependency (which never executed in the source execution), is scheduled and executed. The status of the stepset (and the job) is the status of S4. If S2 fails, then S3 (its failure dependency) is rescheduled and executed (since it had failed in the source execution), and the status of the stepset (and the job) is the status of S3.

Assume that step S1 succeeded, S2 failed, and S3 (its failure dependency) succeeded in the source execution. As a result, the stepset (and therefore the job execution) succeeded. This execution cannot be restarted since the execution completed successfully although one of its steps failed.

Finally, assume that steps S1 and S2 succeed, but S4 (S2's success dependency) failed. Note that S3 is not scheduled in this situation. When the execution is restarted, the job system copies over the executions of S1 and S2 from the source to the restart execution, and reschedules and executes S4. The job succeeds if S4 succeeds.

Example 2

Consider the following:

<jobtype ...>
<stepset ID="main" type="serial" stepsetStatus="S2" >
    <step ID="S1" restartMode="always" ...>
     ...
    </step>
    <step ID="S2" ...>
     ...
    </step>
    <step ID="S3" ...>
     ...
    </step> 
</stepset>
</jobtype>

In the previous example, assume that step S1 completes and S2 fails. S3 executes (since it does not have a dependency on S2) and succeeds. The job, however, fails, since the stepset main has its stepsetStatus set to S2. When the job is restarted, S1 is executed all over again, although it completed the first time, since the restartMode of S1 was set to "always". Step S2 is rescheduled and executed, since it failed in the source execution. After S2 executes, step S3 is not rescheduled for execution again, since it executed successfully in the source execution. If the intention is that S3 must execute in the restart execution, its restartMode must be set to "always".

If, in the above example, S1 and S2 succeeded and S3 failed, the stepset main would still succeed (since S2 determines the status of the stepset). In this case, the job would succeed, and cannot be restarted.

Example 3

Consider the following example:

<jobtype ...>
<stepset ID="main" type="serial"  >
  <stepset type="serial" ID="SS1" stepsetStatus="S1">
    <step ID="S1" ...>
     ...
    </step>
    <stepset ID="S2" ...>
     ...
    </step>
  </stepset>
  <stepset type="parallel" ID="PS1" successOf="S1" >
    <step ID="P1" ...>
     ...
    </step>
    <step ID="P2" ...>
     ...
    </step>
    <step ID="P3" ...>
     ...
    </step>
  </stepset>
</stepset>
</jobtype>

In the above example, let us assume that steps S1 and S2 succeeded (and therefore, stepset SS1 completed successfully). Thereafter, the parallel stepset PS1 was scheduled, and let us assume that P1 completed, but P2 and P3 failed. As a result, the stepset "main" (and the job) failed. When the execution is restarted, the steps S1 and S2 (and therefore the stepset SS1) will be copied over without execution. In the parallel stepset PS1, both the steps that failed (P2 and P3) will be rescheduled and executed.

Now assume that S1 completed and S2 failed in the source execution. Note that stepset SS1 still completed successfully since the status of the stepset is determined by S1, not S2 (because of the stepsetStatus directive). Now, assume that PS1 was scheduled and P1 failed, and P2 and P3 executed successfully. When this job is rescheduled, the step S2 will not be re-executed (since the stepset SS1 completed successfully). The step P1 will be rescheduled and executed.

Example 4

Consider a slightly modified version of the XML in "Example 3":

<jobtype ...>
<stepset ID="main" type="serial"  >
  <stepset type="serial" ID="SS1" stepsetStatus="S1" restartMode="always" >
    <step ID="S1" ...>
     ...
    </step>
    <stepset ID="S2" ...>
     ...
    </step>
  </stepset>
  <stepset type="parallel" ID="PS1" successOf="S1" >
    <step ID="P1" ...>
     ...
    </step>
    <step ID="P2" ...>
     ...
    </step>
    <step ID="P3" ...>
     ...
    </step>
  </stepset>
</stepset>
</jobtype>

In the previous example, assume that S1 and S2 succeeded (and therefore, stepset SS1 completed successfully). Thereafter, the parallel stepset PS1 was scheduled, and let us assume that P1 completed, but P2 and P3 failed. When the job is restarted, the entire stepset SS1 is restarted (since the restartMode is set to "always"). This means that steps S1 and S2 are successively scheduled and executed. Now the stepset PS1 is restarted, and since the restartMode is not specified (it is always "failure" by default), it is restarted at the point of failure, which in this case means that the failed steps P2 and P3 are re-executed, but not P1.

7.14.1 Adding a Job Type to the Job Activity Page

As shown it Figure 7-1, setting the useDefaultCreateUI attribute to "true" allows users creating a job to select the newly added job type from the Create Job menu.

Figure 7-1 Available Job Types from the Job Activity Page

Making the job type available from the Job Activity page also permits access to the default Create Job user interface when a user attempts to create a job using the newly added job type.

Adding the displayInfo Tag

The displayInfo tag can be added to the job definition file at any point after the </stepset> tag and before the </jobtype> tag at the end of the job definition file, as shown in the following example.

<jobtype ...>
<stepset ID="main" type="serial"  >
  <stepset type="serial" ID="SS1" stepsetStatus="S1">
    <step ID="S1" ...>
     ...
    </step>
    <stepset ID="S2" ...>
     ...
    </step>
  </stepset>
  <stepset type="parallel" ID="PS1" successOf="S1" >
    <step ID="P1" ...>
     ...
    </step>
    <step ID="P2" ...>
     ...
    </step>
    <step ID="P3" ...>
     ...
    </step>
  </stepset>
</stepset>
<displayInfo useDefaultCreateUI="true"/>
</jobtype>

7.14.2 Adding a Job Type to the Job Library Page

To make the job type available from the Job Library page, you must also set the jobType tag's editable attribute to "true" in addition to adding the displayInfo tag, This makes the newly added job type a selectable option from the Create Library Job menu.

Making the Job Type Editable

The editable attribute of the jobtype tag is set at the beginning of the job definition file, as shown in the following example.

<jobtype name="jobType1" editable="true">
<stepset ID="main" type="serial"  >
  <stepset type="serial" ID="SS1" stepsetStatus="S1">
    <step ID="S1" ...>
     ...
    </step>
    <stepset ID="S2" ...>
     ...
    </step>
  </stepset>
  <stepset type="parallel" ID="PS1" successOf="S1" >
    <step ID="P1" ...>
     ...
    </step>
    <step ID="P2" ...>
     ...
    </step>
    <step ID="P3" ...>
     ...
    </step>
  </stepset>
</stepset>
<displayInfo useDefaultCreateUI="true"/>
</jobtype>

7.16.1 Using Parameter Sources

The following issues are important in relation to the use of parameter sources:

• Parameter sources are a convenient way to obtain needed parameters from known sources, such as the Management Repository or the credentials table. The parameter sources must be used only for quick queries that fetch information already stored somewhere else.

• Parameter sources that are evaluated at job execution time will ,in general, effect the throughput of the job dispatcher and must be used with care. In some cases, the fetching of parameters at execution time may be unavoidable and if you do not care whether the parameters are fetched at execution time or submission time, set evaluateAtSubmission to false.

• When executing SQL queries to obtain parameters (using the SQL parameter source) the usual performance improvement guidelines apply. These include using indexes only where necessary and avoiding the joining of large tables.