Admin Jobs

From Obsidian Scheduler
Jump to: navigation, search

The job listing and edit pages give you access to the core of Obsidian's functionality - scheduling and configuring jobs. All job-related screens are accessible under the Jobs tab, with secondary navigation underneath for various features. This page discusses listing and modifying jobs. Other job-related features in the administration app are discussed on other pages in the Admin Web Application Guide.

Contents

Job Listing

The default screen under the Jobs tab will show you existing configured jobs.

2.5.0.JobListing.PNG

Exporting Results

The current contents of the table can be exported to Excel, CSV or XML by clicking on the corresponding icon in the table header. The download will automatically begin and will include all pages of the current table of results.

Fields

Fields shown in the job table are:

  • Job nickname (links to job configuration screen)
  • Job Class
  • Schedule (current)
  • Status
  • Recovery Type
  • Pickup Buffer Minutes
  • One-Time Run (users with Write role only)
  • Clone Job (users with Write role only)

Job records can be optionally filtered by host. The Refresh button is used to refresh the results table.

One-Time Run either provides the option to submit a job for immediate or scheduled one-time execution. A job's current state must be either Enabled, Ad Hoc Active or Unscheduled Active to support immediate one-time execution. Otherwise, only future scheduled one-time execution is supported.

Clone Job opens up the Add Job screen pre-populated with the selected job's configuration, including parameters and schedules.

Exporting Results

The current contents of the table can be exported to Excel, CSV or XML by clicking on the corresponding icon in the table header. The download will automatically begin and will include all pages of the current table of results.


Ad Hoc & One-Time Run Submission

You may submit a job for a single execution by clicking the One-Time Run link in the job listing and confirming your run details in the shown dialog.

One-time runs can be submitted either for immediate or scheduled one-time execution. A job's current state must be either Enabled, Ad Hoc Active or Unscheduled Active to support immediate one-time execution. Otherwise, only future scheduled one-time execution is supported. The date and time fields can be omitted when immediate execution is desired, assuming it is supported as just described.


2.5.0.AdHocJobSubmission.PNG

Run Parameters

As of Obsidian 2.1.1, Obsidian allows you to specify run parameters which are supplied to the job for a single execution. To add a parameter, click the Add Run Parameter link. You may add values by clicking the Add Value and Remove links to the left of the field. Any entered values will be validated against the selected type, plus against any parameter of the same name defined at the job level, to ensure data types and other restrictions are enforced.

Note that the first field has a Remove Parameter link instead of Remove, and it will remove all values for that named parameter.

If you reference a global parameter by entering a value surrounded by double curly braces (e.g. {{param}}), Obsidian will resolve this to the values that are configured for the corresponding global parameter (e.g. param). When the job is executed, Obsidian will use the global parameter's values in place of the global parameter reference. You may use multiple global parameters for a given run parameter by specifying each in its own value field, and they can be combined with regular parameter values, also in their own fields. All imported global parameter values will be validated against applicable job parameter definitions and data types.

Adding & Editing Jobs

To add a new job, click the Add Job either at the top left of the job results table, or within the sub-navigation bar beneath the tabs.

To edit or view a job's configuration, click the nickname in the results table.

Job Edit Screen

The job edit screen contains multiple configuration items with which you should be familiar. They are outlined in the sections below.


Note: The question mark icon next to form titles indicates inline help. Click on the icon to view help related to the current item. This is your best source of help when making changes to job details.

2.5.0.AddJob.PNG


Job Nickname and Class

All jobs must have a unique job nickname which identifies the job in logs and event notifications.

The Job Class selector allows you to choose existing jobs that Obsidian knows about, and you may also manually type in a custom job. When selecting a job, not that it must be available to the admin application (i.e. in the classpath) so that it can retrieve parameter information and validate your configuration. It is not possible to configure a job that cannot be found within the admin web application classpath.

Note: When selecting or choosing a new job, the defined and custom parameters sections will refresh based on that specific job's parameter definitions.


Date Fields

Dates and times are used to specify schedule start and end times.

From and To fields will show user-friendly date and time selectors which enforce a valid date range. If you cannot select a date in the past or future, it is because the date widget is enforcing a valid time, and you may need to edit your from or to times appropriately.

Note: If you wish minute-level specificity, simply manually type your time into the time field in the 24-hour format HH:MM. You do not have to use the time selector.

There is some helpful behaviour when you wish a schedule to be indefinite and immediately active. You do not have to specify times in this common case:

  • Blank from dates will be treated as today's date.
  • Blank from times will be treated as the next valid minute, unless a non-current date is specified, in which case it is treated as midnight.
  • Blank to dates will be considered as indefinite (no end).
  • Blank to times will be considered as end of day (11:59 PM), or indefinite when the to date is blank.


Defined Parameters

If a job has defined parameters as discussed in Implementing Jobs, this section will show the configurable parameters. The label on the left will indicate the name and type of the parameter.

If the parameter definition allows multiple values, links to the left of the text field will allow you to add or remove values. Note that remove will not appear for the first item, and if you wish to omit the parameter value, simply leave the first field blank.

Defined parameters support global parameter references.

Asterisks indicate required values.


Custom Parameters

In addition to defined parameters, you always have the option of specifying custom parameters, which the job may use in a dynamic fashion. To add a custom parameter, click the Add Custom Parameter link. Custom parameters always allow multiple values since they have no fixed definition, and you may add values by clicking the Add Value and Remove links to the left of the field. Any entered values will be validated against the selected type, and the selected type will determine how they are stored and provided to the job.

Note that the first field has a Remove Parameter link instead of Remove, and it will remove all values for that named custom parameter.

Custom parameters support global parameter references.

Global Parameters

Both defined and custom parameters support the usage of global parameters. These let you configure job parameters globally, and then simply import them into jobs as needed.

To use a global parameter in a job, simply enter its name surrounded by double curly braces (e.g. {{param}}) in the value field, and Obsidian will locate the matching global parameter (e.g. param). When the job is executed, Obsidian discards the global parameter reference and replaces it with the current global parameter values. You may use multiple global parameters for a given parameter by specifying each in its own value field, and they can be combined with regular parameter values, also in their own fields. All imported global parameter values will be validated against applicable job parameter definitions and data types.

When you save your job changes, Obsidian will validate that any reference global parameter values match your defined data types and other parameter restrictions.

See Parameterization - Global Parameters for more details on type handling and validation of global parameters.

Current Schedule

When adding a new job, the current schedule section will allow you to specify the initial schedule. You will have the ability to overwrite, adjust or add new schedules after initial creation. Schedule is required only for enabled jobs and is ignored for other states. See Date Fields for details on how the date and time fields can be used.

State

Enabled is the standard state that allows scheduling, chaining, and one-time run submissions. This is the only state that takes a schedule (cron) pattern.

Disabled allows you to disable the job completely during the specified window.

Chain Active allows the job to be executed as a chain target only.

Ad Hoc Active allows the job to be submitted and executed for one-time runs only.

Unscheduled Active allows the job to be executed as a chain target and also allows the job to be submitted and executed for one-time runs.

Note: When editing a job, the current schedule section shows a read-only view of the active schedule, or if one is not active yet, the first schedule that will become active.

Execution & Pickup

This section allows you to specify options related to how jobs are picked up and recovered in exceptional circumstances.

Recovery Type allows you to specify how the job will be handled when execution does not happen normally because of conflicts, server downtime, etc.

Pickup Buffer indicates for how many minutes the job is considered within normal execution time from the exact scheduled time. This allows for leniency when dealing with conflicting jobs or with short-term downtime. If a minor delay isn't significant to your job, using a higher buffer can help prevent jobs from being marked missed or conflict missed unnecessarily.

Fixed Hosts allows you to indicate that only certain hosts should run this job. You can select one or more hosts which Obsidian knows about, and add additional options in case a host is not yet deployed or active. As of Obsidian 2.2.1, a configuration item allows you to specify whether you wish host restrictions to apply on AdHoc jobs or not. On new installations of 2.2.1, it defaults to TRUE while it defaults FALSE (to maintain behaviour from versions before 2.2.1) on upgrades from prior releases. Can by found under Admin_System/Job/adHocJobsRespectFixedHostsRestrictions.

Auto Retries - Count allows you to indicate the number of times you wish Obsidian to automatically resubmit (retry) the job for execution when triggered by a non-interrupted execution failure. As of Obsidian 2.0.

Auto Retries - Interval allows you to indicate the minimum interval in minutes from the point in time the job failed and the job will be retried. As of Obsidian 2.5.0.

Auto Retries - Exponential allows you to indicate if you desire the auto retries interval to exponentially increase as retries are attempted. For example, if you set the interval minutes to 5 and check Exponential, the first retry will be 5 minutes after failure, the second retry after a subsequent failure will be 10 minutes later, then 20 minutes, and so on. As of Obsidian 2.5.0.

Expected Length allows you to trigger event notifications in the event that the job execution is shorter or longer than the durations specified. Both fields are optional, and you are permitted to specify only one of the two. Specify a duration followed by a unit indicator (s-seconds, m-minutes, h-hours), e.g. 45s, 10m or 1h. To receive notifications based on the job running outside these parameters, configure Notifications at the Warning level or above. As of Obsidian 1.5.

Chain All allows you allows you specify the behaviour when this job is to be chained but is executing another instance at that moment. By default, only one newly chained instance will be queued. Choose this option to chain all such occurrences. As of Obsidian 2.0.

Saving

To save your configuration changes, click the Save button at the bottom of the form or in the left navigation area. If there are problems with your changes, you will be notified at the top of the screen. You can then correct your entered information and re-save. Upon success, you will see a success confirmation.

Deleting

As of Obsidian 1.4, you can delete a job and all its history and configuration from Obsidian. We recommend you use this feature sparingly on long-obsolete jobs. When you attempt to delete a job, Obsidian will ask for your confirmation along with prompting you with a choice.

Deleting a job in Obsidian assumes you are fine with losing all runtime results, defined parameters and any schedules and states. You will also lose any chain references from this job, i.e if a job was chained from the job you're deleting, it will show as chained, but the source job information will be lost. Since jobs can have an impact on other jobs, namely chaining and conflict configuration, the default delete will fail to complete if there are any active chains referencing the job in question or if the job is included in any conflict groups. Optionally, you can also select the option Delete all active job configuration? in the Delete Job window and this will delete any of these as well.

DeleteJobWindow.png

Edit, View & Change Schedules

After you have saved the initial job configuration, you can then make schedule changes and additions.

When saving a new job or loading an existing job's configuration, you will see a Edit/View/Add Schedules link above the save button beneath the Current Schedule section. Clicking this link will expand the schedule change section, so you can preview and confirm schedule changes.

2.5.0.SaveJob.PNG


When making changes here, the fields work the same was as the Current Schedule section. New schedules may overlap, contain or be within existing schedules with no issue. Obsidian will automatically split and merge schedules to create a complete schedule based on your changes.

To simply replace any current schedules with a new permanent schedule, leave the time fields blank, and it will become active indefinitely at the beginning of the next minute.

Clicking the Preview link will refresh the table of combined schedules. This will be the existing schedules if no new schedule is entered, or a preview of the new altered schedules based on your input if specified. This allows you to view the effect of your changes before confirming them.

Note: If you wish to confirm your changes, you should click either Save button with the Add New Schedule box open. If you click the Cancel button above the new schedule box, your changes will be discarded and will not be included if you then click Save.

2.5.0.JobSchedule.PNG


Below you can see the Edit/Add Schedule box being used to view the current schedules without making any changes. If you wish to simply see the active schedules, you can use the preview button here.

2.5.0.NewJobSchedule.PNG

Custom Calendar Assignment

As of Obsidian 2.0, an Enabled Schedule may also be assigned a Custom Calendar. Use this to prevent scheduling/execution on the dates specified by the Custom Calendar.

2.5.0.CustomCalendarAssignment.png

Custom Calendars

Obsidian 2.0 introduced Custom Calendars. These provide a mechanism to prevent jobs from ever being scheduled and executed on certain dates regardless of their scheduled cron pattern. Job schedules may optionally be assigned a custom calendar on a schedule/state group.

Note: Custom Calendars have no impact on chaining, failure resubmissions or one-time runs of jobs.


Custom Calendar Listing

Lists all available custom calendars.

2.5.0.CalendarListing.PNG

Add/Update Custom Calendar

You may update the name or the dates associated with a Custom Calendar.

Dates are specified in the format yyyy-MM-dd (e.g. 2013-12-31) and can be separated by commas, spaces or newlines.

Note: Once you have created a custom calendar, to apply it to a specific job you must create a new schedule for it which uses the custom calendar.


2.5.0.NewCalendar.PNG