Admin Jobs

From Obsidian Scheduler
Jump to: navigation, search

The job screens give you access to the core of Obsidian's functionality - scheduling and configuring jobs. This screen can be accessed from the primary navigation sidebar, underneath the Configuration parent menu item.. This page discusses listing and modifying jobs. Other job-related features are discussed on other pages in the guide.


Job Listing

The default screen shows you a table of existing configured jobs.

JobListing 4.1.png


Fields shown in the job table are:

  • Job Nickname (links to job configuration screen)
  • Job Class
  • Folder
  • Status (current)
  • Schedule (current)
  • Submit Run Link (users with Write role only)
  • Clone Job Link (users with Write role only)

Submit 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 a new job edit screen pre-populated with the selected job's configuration, including parameters and schedules.


Job records can be optionally filtered by host, status and folder. In the case of each, selecting no options is equivalent to choosing all options . Selected options may be cleared by clicking the (X) next to the dropdown arrow.

When filtering by folder, subfolders are matched when searching by a parent folder. Note that intermediate folders with no contents will be suppressed if they do not offer any search value.

Exporting Results

The current contents of the table can be exported to Excel, CSV or XML by clicking on export icon displayed at the far right of 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 Submit Run link in the job listing, which will bring you to a screen to configure your submission.

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 ad hoc or one-time runs.

The Scheduled Time can be omitted when immediate execution is desired, assuming it is supported as just described.

AdHocJobSubmission 4.0.png

Run Parameters

Obsidian allows you to specify run parameters which are supplied to the job for a single execution. To add a parameter, click the Add Parameter button. You may add values by clicking the (+) and trash buttons to the right 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. If a parameter name for a run parameter has the same name as a configured job parameter, the job parameter values are dropped, and the run parameter values are used instead.

To remove a parameter and its values, click the Remove button.

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 (+) button in the job listing table header.

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

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.

AddJob 4.1.png

Job Settings

Nickname, Class and Folder

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 (hit enter to confirm and validate). 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.

The Folder selector allows you to select an in use folder, or type in a new folder. Clicking the (x) button will clear the selection so you can type in a custom folder. Jobs can be assigned to folders to help grouping and searching for them. You can use nested paths (e.g. A/B) using forward-slashes. Note that back-slashes will be automatically converted to forward slashes, and multiple slashes in succession are collapsed into a single slash. Leading and trailing slashes are stripped for consistency.

Advanced Options

This section allows you to specify options related to how jobs are picked up and recovered in exceptional circumstances. Click on Advanced Options or the chevron next to it to expand or collapse this section.

Recovery Type allows you to specify how the job will be handled when execution does not happen normally within the Pickup Buffer 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.

Auto Retries - # 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 subscribers at the Warning level or above. As of Obsidian 1.5.

Auto Interrupt allows you to specify if you wish an Interruptable Job to be interrupted when its maximum expected run length is exceeded. Only available as an option for those jobs that adhere to the Interruptable Job requirements and have a maximum expected length specified. As of Obsidian 3.4.0.

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. If a host is not listed and will be started later, simply type in the name and click the (+) button to add it to the list. 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. This can be found under Scheduler Settings/Job/adHocJobsRespectFixedHostsRestrictions.

Host Preference indicates that Fixed Hosts are only preferred hosts, and that other available hosts can run the job when none of the preferred hosts are running. When selected, you can also order the hosts using drag & drop. Obsidian will always choose the highest priority host to run the job if one is available.

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. Each chained target instance is queued for the same minute. Ensure your Pickup Buffer is set large enough for these to be picked up and run in sequence.


When adding a new job, the 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. Cron patterns are used to specify the schedule or you may use custom Recurrence expressions.

Multiple cron patterns may be specified for a single schedule by delimiting them with a semi-colon (e.g. 35 8 * * * *;20 12 * * *;40 16 * * *). This means that the job will fire if it matches any of the supplied patterns.

If you specify start and end dates, any dates outside this range will be initially set to the Disabled States.


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. Note that a one-time run must be requested after saving your job configuration for the job to be executed.

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 upon request. Note that a one-time run must be requested after saving your job configuration for the job to be executed.

Note: When editing a job, the 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.

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.

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 the current schedule in a read-only view in the Schedule section.

To update the current schedule or create a future schedule, click the Edit button, then make your changes. 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.

JobSchedule 4.0.png

If you wish to abandon your schedule changes, click the Revert button.

JobScheduleRevert 4.0.png

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 View All button will show all schedules that have been configured that are active now or in the future. The Include Expired checkbox can be used to include expired schedules in the listing. 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: In order to save your schedule changes, you'll need to save the job itself. If you click the Revert button after making schedule changes, they will be discarded and will not be included if you then click Save.

Below you can see the View All button being used to view the current schedules without making any changes.

NewJobSchedule 4.0.png

Custom Calendar Assignment

An Enabled Schedule may also be assigned a Custom Calendar. Use this to prevent scheduling/execution on the dates specified by the Custom Calendar.

CustomCalendarAssignment 4.0.png


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, buttons to the right 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.

If the parameter is defined to use a list of values, a select list will be presented instead of a text box.

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. In the Parameters section, click on Custom or the chevron next to it to expand or collapse this section.

To add a custom parameter, click the Add Custom Parameter button. Custom parameters always allow multiple values since they have no fixed definition, and you may add values by clicking the (+) and trash buttons to the right 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.

To remove a custom parameter and its values, click the Remove button.

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. Note that Obsidian does not support global parameter references embedded inside parameter values, since it does not perform text substitution - only parameter values containing only the global parameter reference will be replaced with the global parameter value.

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.


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.


You can delete a job and all its history and configuration from Obsidian. We recommend you use this feature sparingly. It is most useful 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 4.0.png