How Define AutoSys Job Example

How Define AutoSys Job Example

All activity controlled by AutoSys is based on the jobs. Job is any single command or executable or UNIX shell script, or Windows batch file. Other objects such as monitors, reports, and the Job Status Console, track job progress. A job is a foundation for entire operations cycle.

You can also define jobs to CA Workload Automation by creating job definitions. Every job definition contains attributes that specify jobs properties and behavior. For example you can specify conditions that determine when and where job runs.

You can define jobs using following ways:

• JIL: It’s a scripting language which lets you define, modify assets such as jobs, machines, global variables, user-defined job types, blobs and external instances.
• CA WCC: Tool that you can use interactively set the attributes that describe where, when and how job should run. Fields in CA WCC GUI correspond to the JIL sub commands and attributes. In addition from CA WCC GUI you can also define global variables, calendars, and monitor and manage jobs. CA WCC is supplied with CA Workload Automation AE.

In this tutorial we will cover only JIL to define the jobs:

Job Types: When you create a new job definition you should specify job type. This job types defines type of work needs to scheduled. For example you could create CMD job to run on Windows command or FTP job to download file from the server or SAPEM job to monitor triggering of SAP events.

Basic structure of the job depends on job type. Following below shows structure of Command, File Watcher, and Box job:

• Common Job Attributes: Many JIL attributes are common to the all job types. As an example, you could define any job to send alarm if job fails or terminates. You could also define starting or restart conditions for any of the job.

Required Attributes for All Job Types:

• job_name: Name of the job
• machine: Machine name where job has been defined for execution

Note: By default job type will be set to CMD and you could define different job type using job_type attribute.

Optional Attributes for All Job Types:

• condition: Any number of job dependencies can be specified; however, every dependency must evaluate to true before the dependent job will be run. Examples of job dependencies include successful completion of a job, failure of a job, a job’s exit code, and the value of a global variable. Various combinations of conditions may also be specified. Job dependencies can reference jobs residing on different instances. If a condition is specified for an undefined job, the condition will be evaluated as FALSE, and any jobs dependent on this condition will not run. To check for this type of invalid condition statement, you can use the chk_cond, stored procedure (see chk_cond (SP) in the chapter “Commands” in the Unicenter AutoSys Job Management for Windows and UNIX Reference Guide ).
  Note: You should study the Starting Parameters in the chapter “Jobs” and review the JIL examples provided in the chapter “Defining Jobs Using JIL.” This functionality opens up all sorts of possibilities for controlling jobs, and provides information that will help you when creating your own job definitions.Type, or status attributes futher define conditions. There are several Job Status Dependencies that can be used to control when a job should run; or when a job should not run.
  • ‘d’ (done): Indicates that the job you are defining may run when the job specified within the condition completes with a status of SUCCESS, FAILURE, or TERMINATED.
  • ‘f’ (failure): Indicates that the job you are defining may run when the job specified within the condition completes with a status of FAILURE.
  • ‘n’ (notrunning):  Indicates that the job you are defining may run when the job specified within the condition is any value except RUNNING – preventing the dependent job from running at the same time as the job referenced within the condition.
  • ‘s’ (success): Indicates that the job you are defining may run when the job specified within the condition completes with a status of SUCCESS.
  • ‘t’ (terminated): Indicates that the job you are defining may run when the job specified within the condition is TERMINATED.
• run_calendar: The days on which a job should be run can be specified by way of a custom
  calendar, rather than through a list of days of the week. Custom calendars, specified through the Graphical Calendar Facility, or the autocal_asc command, can include any number of dates on which the job should be run. Each calendar is stored in the database as a separate object with a unique name, and a calendar can be associated with one or more jobs, using this attribute or the
  exclude_calendar attribute.
• box_terminator: This attribute specifies whether or not the box containing this job should be
  terminated if the job fails or terminates. By using this attribute in combination with the “Terminate the Job if the Box Fails” attribute, you can control how nested jobs react when a job fails. This attribute only applies if the job is being placed in a box.
• resources: This specifies resources.
• box_name: Boxes allow a set of jobs to be manipulated as a group. This feature is particularly useful for setting starting conditions at the box level, to “gate” the jobs inside the box, then specifying their starting conditions relative to each other individually, if necessary. This attribute specifies the name of the box in which the job is to be placed. The specified box must already exist before you can place jobs in it.
• priority: The queue priority establishes the relative priority of all jobs queued for a given machine, with the lower number indicating higher priority. If a job is ready to run on a designated machine, but the current load on that machine is too large to accept the new job’s load, the job will be “queued” for that machine.
  The priority attribute only influences the starting of jobs that are queued, unless the jobs are in a box. If jobs in a box have a priority attribute setting, they will be processed in order of priority, highest to lowest.
• avg_runtime: The avg_runtime attribute is used to provide an average runtime (in minutes) for a job that is newly submitted to the database; it establishes this value in the absence of the job having been run multiple times. This attribute is used solely to establish an average runtime for the new job in the avg_job_runs table.
• permission: In UNIX, there are three levels of permission by user ID (uid), and within Unicenter AutoSys JM, two levels of job permission.
  Permissions are based on the UNIX user ID scheme. This scheme contains three types: owner, group, and world (or public). The owner is the user who originally created the job. The group is the primary group of which the owner is a member, and the world is every user with a valid logon for the system.
  Unicenter AutoSys JM also allows designation of an exec superuser and an edit superuser, by way of the autosys_secure command. The edit superuser can edit any job definition, change the owner of a job, and change the permissions assigned to a job; no other user has this authority. The exec superuser can shut down the event processor, and can issue sendevent commands to any job,
  regardless of its owner.
  The permission scheme used is as follows:
  • Execute: If execute permissions are enabled for the user’s group, allows the user to
    issue events that affect the running (starting, stopping, and so on) of the job.
    Users in primary and secondary groups have this permission.
  • Edit: If edit permissions are enabled for the user’s group, allows the user to edit or delete the job definition. Only users in the primary group have this permission.The permission scheme is based on the same permissions used in native UNIX environment. The user ID (uid) and group ID (gid) specified in the UNIX environment do the following:
  • Control access to the job definitions themselves.
  • Determine the execution permissions to be used when executing the actual UNIX command specified in the job. For command jobs, the following optional attributes can be specified, in addition to those listed in Attributes Common to All Job Types in this chapter. These
    attributes typically default to “inactive” if not specified.
• auto_hold: This feature is only for jobs in a box. When a job is in a box, it inherits the starting conditions of the box. This means that when a box goes into the RUNNING state, the box job will start all the jobs within it (unless other conditions are not satisfied). This is typically the desired behavior; however, there are occasions when it is not.
  For example, you may want to place a job in a box, but not start the job until a non-job (that is, operating system level) event arrives. By specifying “yes” to Autohold On, Unicenter AutoSys JM automatically changes the job state to ON_HOLD when the box it is in begins RUNNING. At this point, the job is in exactly the same state as if it were manually placed on hold. To start the job, take
  the job off hold by sending the JOB_OFF_HOLD event through the Send Event dialog or the sendevent command.
• owner (This attribute does not apply to File Trigger jobs.):
• auto_delete: This attribute indicates whether or not the job definition should be automatically
  deleted after successful completion. A number of hours can be specified (including “0” for immediately), or the attribute can be turned “off” by specifying a negative value (for example “-1”), which is the default. If auto_delete is set to 0, Unicenter AutoSys JM will immediately delete job
  definitions only if the job completed successfully.
  If the job did not complete successfully, Unicenter AutoSys JM will keep the job definition for seven days before automatically deleting it. This attribute is useful for scheduling and running a one-time batch job.
• notification_msg: If job generates alarm this include notification message
• application: It uniquely identifies the application including it covers permission of the job based Active Directory group. Only people who belongs to application will be able to read/write/execute the job. 
• notification_id: Specifies the notification ID or email address of the user who receives the notification.
  Limits: Up to128 characters
• alarm_if_fail: This attribute specifies whether or not an alarm should be generated when the job fails. Failure is defined as the job completing with a FAILURE or TERMINATED status. (The “Maximum Exit Code for SUCCESS” attribute determines what codes are interpreted as FAILURE for a job, and the “Box Failure Condition” attribute determines what constitutes a box failure.) Alarms are informational, and they do nothing on their own. A monitor or the Operator Console must be running and tracking alarms in order for them to be seen and acted upon in real time.
• run_window: This attribute has the following format: “time-time” time-time Defines the interval during which a job may start in the format “hh:mm-hh:mm”, where hh denotes hours (in 24-hour format) and mm denotes minutes. You must enclose the interval in quotation marks (“) and separate the beginning and ending times with a hyphen (-). The specified interval can overlap midnight, but cannot encompass more than 24 hours. Limits: Up to 20 alphanumeric characters
  For example: If you are running the Job exactly once between 00:06 – 00:56 and 04:06 – 04:56 time frames you can try to set starttime as 00.06 and 04.06 and set max_run_alarm: 50
• date_conditions: The start date/time dependencies attribute is a toggle, which specifies whether or not there is date, time, or both, conditions required for starting the job. If the attribute is set to “no,” the remainder of the related date/time attributes, described following, will be ignored.
• send_notification: Specifies the conditions under which a notification is sent when a job completes, as follows:
  Do not notify — Does not send a notification.
  Notify only if job fails — Sends a notification only if the job completes with a FAILURE status.
  Notify unconditionally — Sends a notification when the job completes with any status.
  Default: Do not notify
• days_of_week: The days of the week attribute specifies the days on which the job should be run.
  You can specify one or more days, or “all” for every day.
• service_desk: Indicates whether to open a service desk request when the job fails.
• description: This attribute specifies a time range (or time window) during which a job can be
  started. When the starting conditions for a job have been met, Unicenter AutoSys JM checks if the current time is within the specified run window. The job will not start outside of the specified window.
  This attribute controls only when the job will start, not when it will stop running. This attribute is particularly useful when, for example, it is not known when a watched-for file will arrive, and there are certain times when jobs dependent on that file should not run. This setting can prevent a late-arriving file from causing a job to run at an inopportune time. The run window range cannot span more than 24 hours. Jobs that are not in a box must have starting conditions in started.
  Note: You can also block out times of day when you do not want a job to start by putting the job on hold, then taking it off hold later. The sendevent command can be used to accomplish this, executed either from the command line, through the Send Event dialog, or from within a shell script or batch file in another job.
• start_mins: One or more specific times per hour when the job should be started can be specified. Each time is specified in minutes past the hour. The job will be started at each specified time every hour of the day, on every day specified in the associated date attributes. This attribute and the “Specific Times of Day to Run” (start_times) attribute are mutually exclusive.
• exclude_calendar: The days on which a job should not be run can be specified by way of a custom
  calendar. Custom calendars, specified through the Graphical Calendar Facility, or the autocal_asc command, can include any number of dates on which the job should not be run. Each calendar is stored in the database as a separate object with a unique name, and a calendar can be associated with one or more jobs, using this attribute or the run_calendar attribute.
• start_times: This attribute specifies one or more specific times of day when the job should be
  started. The job will be started at each specified time of day, on every day specified in the associated date attributes. This attribute and the “Specific Times Every Hour to Run” (start_mins) attribute are mutually exclusive.
• group: Indicates the permission levels to associate with the job, as follows:
  Group (execute): Assigns group execute permissions to the job.
  JIL attribute: permission: gx
  Group (edit): Assigns group edit permissions to the job.
  JIL attribute: permission: ge
  World (execute): Assigns world execute permissions to the job.
  JIL attribute: permission: wx
  World (edit): Assigns world edit permissions to the job.
  JIL attribute: permission: we
  All hosts (execute): Indicates that any authorized user may execute the job, regardless of the machine they are on. Otherwise, the user must be logged on to the machine specified in the owner field (for example, user@host_or_domain).
  JIL attribute: permission: mx
  All hosts (edit): Indicates that any authorized user may edit the job, regardless of the machine they are on. Otherwise, the user must be logged on to the machine specified in the owner field (for example, user@host_or_domain).
  JIL attribute: permission: me
• svcdesk_attr: Specifies additional information to include in the service desk request generated when the job fails.
  Limits: Up to 128 characters
• job_load: Machines can be assigned “maximum job loads,” which is a measure of the CPU load that is desirable for a machine at any given time. Similarly, jobs can be assigned loads, indicating the relative amount of processing power they consume. This scheme allows for machine loading to be controlled, and prevents a machine from being overloaded. If a job is ready to run on a designated machine, but the current load on that machine is too large to accept the new job’s
  load, the job will be “queued” for that machine, to be run when sufficient resources are available. For load balancing to function properly, all jobs to be run on a controlled machine must have job loads specified; otherwise, their impact on a machine cannot be measured.
  Note: If you force a job to start, it will run even if its load exceeds the machine’s max_load. Also, if job_load is specified for a job and no priority attribute (described following) is set, Unicenter AutoSys JM uses the default priority of zero, which means ignore the job_load and run the job immediately.
• svcdesk_desc: Specifies a description to include in the service desk request generated when the job fails.
• job_type: Type of Job (valid types are c => command, f  => file watcher b => box)
• svcdesk_imp: Specifies the impact level of the request, as follows:0 – None
  1 – High
  2 – Medium-high
  3 – Medium
  4 – Medium-low
  5 – Low
• max_run_alarm: A maximum runtime can be specified for a job. If a maximum runtime is specified, the job should not take longer than the specified time to finish. This “reasonability” test may catch an error, such as the application being stuck in a loop, or the application waiting for additional data that may never arrive. If the job runs longer than this time, an alarm is generated to alert someone to
  investigate the situation and take corrective action. Alarms are informational, and they do nothing on their own. A monitor, or the Operator Console, must be running and tracking alarms in order for them to be seen and acted upon in real time.
  The attribute “Terminate this job Mins after starting” ( rm_run_time ) can be used to automatically terminate a job that has been running for too long. If term_run_time is not set, the job will continue running until manually interrupted, or it completes by itself.
• svcdesk_pri:
• min_run_alarm: A minimum run time (in minutes) can be specified for a job; the job should not end in less than the specified time. This may prevent an inadvertent truncation of the file being processed before it is complete. If the job does end prior to this time, an alarm is generated to alert someone to investigate the situation and take corrective action. Alarms are informational, and they do nothing on their own. A monitor or the Operator Console must be running and tracking alarms in order for them to be seen and acted upon in real time.
• svcdesk_sev: Service desk priority specifies the priority level of the request, as follows:0 – None
  1 – High
  2 – Medium-high
  3 – Medium
  4 – Medium-low
  5 – Low
• must_complete_times: Defines the amount of time that a job is allowed to run or a specific time by which a job must run before completing. You can specify a relative value to the start time (Minutes after each hour) or an absolute value. If the job has not completed before the time expires, an alarm is issued. Relative times must be preceded by a plus sign (+). Absolute times must be specified in hh:mm format, where hh denotes hours (in 24-hour format) and mm denotes minutes. To specify multiple absolute times, separate each value by a comma.Limits: Up to 128 characters; 71:59 maximum absolute value
  Examples: +5 (relative time), 11:30, 12:30, 15:30 (absolute times)
• term_run_time: A maximum run time (in minutes) can be specified for a job; the job should not take longer than the specified time to finish. This feature allows the job to be automatically terminated if it runs longer than the allotted time.
• must_start_times: Defines the amount of time that a job is allowed to wait or a specific time until which a job must wait before starting. You can specify a relative value to the start time (Minutes after each hour) or an absolute value. If the job has not started before the time expires, an alarm is issued. Relative times must be preceded by a plus sign (+). Absolute times must be specified in hh:mm format, where hh denotes hours (in 24-hour format) and mm denotes minutes. To specify multiple absolute times, separate each value by a comma.Limits: Up to 128 characters; 71:59 maximum absolute value
  Examples: +5 (relative time), 11:30, 12:30, 15:30 (absolute times)
• timezone: This attribute lets you schedule a job based on a chosen time zone. When this attribute is used, the time settings in the job are based on the specified time zone. For example, if you define a start time of 01:00 for a job running on a machine in Denver, and enter San Francisco in the Time Zone field, the job will start at 1:00 a.m. Pacific time, which is 2:00 a.m. in Denver.
  If you specify a time zone that includes a colon, you must quote the time zone name if you are using JIL. For example: timezone: “IST-5:30”
  If you do not quote a time zone specification that contains a colon, JIL will interpret the colon as a delimiter, producing unexpected results.
  Jobs with time-based starting conditions that do not specify a time zone will have their start event scheduled based on the TZ environment variable, which specifies the time zone under which the event processor is running.
• n_retrys: This attribute specifies how many times, if any, the job should be restarted after exiting with a FAILURE status. The default is 0, which means the job will not be automatically restarted after an application failure. This attribute applies to application failures (for example, Unicenter AutoSys JM is unable to find a file or a command, or permissions are not properly set); it does not apply to system or network failures (for example, machine unavailability, the socket connect timed
  out, the fork in the Remote Agent failed, or the file system space resource check failed).
  The number of restarts after system or network failures is specified using the
  MaxRestartTrys parameter in the configuration file.
• job_terminator: This attribute specifies whether or not the job should be terminated if the box it
  is in fails or terminates. By using this attribute in combination with the “Terminate the Box if the Job Fails” attribute, you can control how nested jobs react when a job fails. This attribute only applies if the job is being placed in a box.
• profile: The profile attribute specifies the file to be sourced by the Bourne shell before the specified command is executed. The remote agent always spawns a process and starts the Bourne shell in that process, passing it the name of the profile to be sourced. This profile typically includes definitions and exports of environment variables, which can be referenced in the job’s command. The primary environment variable in the profile is the $PATH. If a profile is not specified, the
  default profile, /etc/auto.profile, is used. If the profile attribute is specified, that profile is searched for on the machine on which the command is to run.
  If a command that normally executes when entered at the command line fails when run as a job, it is usually due to the incomplete specification of the required environment for the command in the profile file.
  Note: It is essential that no Korn shell and C-shell statements appear in the profile file, because the Bourne shell that runs will not be able to process them. If you include these types of statements, unexpected results will occur, often interfering with the proper redirection of the stdin, stdout, and stderr files.
• std_in_file: The standard input file can be redirected to any file to which the job owner has read permission on the client machine. The full path name must be specified, although variables exported from the default /etc/auto.profile or job’s profile file, as well as global variables, can be used in the path name specification.
  The default is /dev/null.
• std_out_file: The standard output file can be redirected to any file on the client machine to which the job owner has write permission. The full path name must be specified, although variables exported from the default /etc/auto.profile or job’s profile file, as well as global variables, can be used in the path name specification. The default is /dev/null.
  By default, new information is appended to the file. By placing the following notation as the first characters in the std_out_file specification, you can specify if the error file should be appended to or overwritten:
       > Overwrite file
       >> Append file
  This setting overrides the instance-wide setting for the AutoInstWideAppend parameter in the configuration file. It also overrides the machine-specific setting for the AutoMachWideAppend parameter in the /etc/auto.profile file.
  Note: If you are running jobs across platforms, realize that the event processor of
  the issuing instance controls the default behavior. If the issuing instance is
  Windows, the default is to overwrite this file.
• std_err_file: The standard error file can be redirected to any file on the client machine to which the job owner has write permission. The full path name must be specified, although variables exported from the default /etc/auto.profile or job’s profile file, as well as global variables, can be used in the path name specification. The default is /dev/null.
  By default, new information is appended to the file. By placing the following notation as the first characters in the std_err_file specification, you can specify if the error file should be appended to or overwritten:
        > Overwrite file
        >> Append file
  This setting overrides the instance-wide setting for the AutoInstWideAppend parameter in the configuration file. It also overrides the machine-specific setting for the AutoMachWideAppend parameter in the /etc/auto.profile file.
  Note: If you are running jobs across platforms, realize that the Event processor of the issuing instance controls the default behavior. If the issuing instance is Windows, the default is to overwrite this file.
• override_job: You can specify a one-time job override for the next run of a particular job. An
  override lets you change the behavior of a job the next time the job runs.
  The following attributes can be modified in a job override:
  auto_hold profile watch_file_min_size min_run_alarm term_run_time exclude_calendar
  std_in_file date_conditions start_mins command run_calendar watch_interval n_retrys watch_file machine std_out_file days_of_week start_times condition run_window max_run_alarm std_err_file
• max_exit_success: The maximum exit code for success attribute indicates what exit codes will be
  considered as a success. It is used when a command can exit with more than just a single exit code, indicating either “degrees of success,” or other conditions that may not indicate a failure. This attribute lets you define complex branching logic based on specific exit code values. Unicenter AutoSys JM reserves exit codes greater than 120 for internal use, so do not use exit codes of 120 or greater.
• heartbeat_interval: Heartbeats are a means of monitoring a job’s progress. It automates the common practice of outputting characters, similar to displaying “progress” asterisks across the screen as a process runs. If a job does not send a heartbeat within this specified interval, a HEARTBEAT alarm is generated. The heartbeat interval is specified in minutes.
  To send a heartbeat from a C program, call the routine found in the following
  source file:
  $AUTOSYS/code/heartbeat.c
  To send a heartbeat from a Bourne shell script, execute the code found in the following file:
  $AUTOSYS/code/heartbeat.sh
  The event processor must be configured to check for heartbeats. To do this, modify the configuration file, which has the following name:
  $AUTOUSER/config.$AUTOSERV
• chk_files: This attribute specifies a minimum amount of file space that must be available on the designated file systems for the job to be started. One or more file systems, specified with full path names or directory names, and their corresponding sizes, can be specified. If multiple file systems are specified, separate them with a single space. When the remote agent is preparing to start the job on the client machine, it checks whether or not the required space is available before starting
  the job. If the requirements are not met, an alarm is generated and Unicenter AutoSys JM automatically reschedules the job to start again after a delay. It will perform the same resource check the next time it attempts to start. This feature is intended to prevent a job that is known to require large amounts of file space from failing due to a shortage of space during processing time.

Box Job Attributes: For box jobs, the following optional attributes can be specified, in addition to
those listed in Attributes Common to All Job Types in this chapter. These
attributes typically default to “inactive” or NULL if not specified.

• box_success: The default condition required for a box to be considered successful is that every job in the box must have completed with a success condition. A box can contain complex branching logic, which can take a number of different paths, all of which constitute a success. In this case, some jobs in the box may never need to run; but if the default box behavior is applied, the jobs that did not run would prevent the box from ever completing.
  This attribute can be used to specify what is considered a success, which could be as simple as the success of a single job, or as complex as necessary. This attribute is only displayed in the GUI when you select a box job type.
• box_failure: The default condition required for a box to complete with a FAILURE status is that all jobs in the box have completed and one or more jobs in the box completed with a failure condition. A box can contain complex branching logic, which may take a number of different paths, one of which may include recovery from a failed job. In this case, you may want the box to be considered successful, even though a job within it failed. This attribute can be used to specify what will be considered as a failure, which could be as simple as the failure of a single job, or as complex as necessary. This attribute is only displayed in the GUI when you select a box job type.

File Watcher Job Attributes: For file watcher jobs, the following attributes can be specified in addition to
those listed in Essential Job Attributes (File Watcher Job Attributes) in this chapter. These attributes typically default to inactive if not specified.

• watch_file_min_size: The watch file minimum size determines when enough data has been written to the file to consider it “complete.” This attribute is specified in bytes. You should specify a reasonable file size to ensure that a nearly empty file is not assumed to be complete. Use caution with this attribute. If you specify a large file size Unicenter AutoSys JM will wait for the file to reach that size, even if the file has reached a steady state and is no longer growing.
• watch_interval: The watch interval specifies (in seconds) how often the File Watcher should check the current file size to ascertain whether data is still being written to the file. The default is every 60 seconds.
• chk_files: This attribute specifies a minimum amount of file space that must be available on designated file systems for a command job to be started. One or more file systems, specified with full path names or directory names, and their corresponding sizes can be specified. When the remote agent is preparing to start the job on the client machine, it checks whether the required space is available before starting the job. If the requirements are not met, an alarm is generated.
  File watcher jobs will still be started.