Legacy API

From Obsidian Scheduler
Jump to: navigation, search

Obsidian 2.0 introduced a fully supported public embedded API to allow integration into other applications and software environments where the REST API is unavailable or undesired. A selection of job configuration and scheduling features are exposed via the API. Javadoc formatted documentation is also available.


Note: This API is deprecated as of version 2.3 in favour of the more complete and unified Embedded API.


Overview

The Obsidian Legacy API allows your application a way to access Obsidian data, schedule jobs, and control Obsidian in a variety of ways. It is written in Java and must be accessed within the context of a running Obsidian node, although the scheduler itself need not be active.

The API gives users the power to do things like initialize scheduled jobs at deployment time, trigger jobs based on events in your applications, and expose pieces of the Obsidian API in their own custom user interfaces.

API

The API is exposed through the class com.carfey.ops.api.ObsidianAdministrator. Javadoc formatted documentation is also available. You may instantiate a new ObsidianAdminstrator - new ObsidianAdministrator() - or retrieve a shared instance - ObsidianAdministrator.get().

Create and configure a job

JobConfiguration createJob(Job job, com.carfey.jdk.lang.DateTime effectiveDate, com.carfey.jdk.lang.DateTime endDate, String status, String schedule, Long customCalendarId, String auditUser) throws Exception

Parameters

Parameter Required? Notes
job Y
effectiveDate Y Must be at least one minute in the future.
endDate Y Must be at least one minute in the future. For an unending schedule, use ObsidianAdministrator.END_OF_TIME.
status Y Must be one of ENABLED, UNSCHEDULED_ACTIVE, CHAIN_ACTIVE, DISABLED, AD_HOC_ACTIVE.
schedule N Only required if the status would require a schedule. Cron syntax.
customCalendarId N On ENABLED schedules, optional CustomCalendar.
auditUser N Optional user that is marked in Obsidian Audit columns.

Delete a job and all its history and configuration

void deleteJob(Job job, boolean cascadeDelete, String auditUser) throws Exception

Parameters

Parameter Required? Notes
job Y Only JobId and Version are required attributes.
cascadeDelete Y See Job Delete
auditUser N Optional user that is marked in Obsidian Audit columns.

Retrieve a list of configured jobs

List<JobConfiguration> getJobsByNicknamePattern(String nicknamePattern) throws Exception

Parameters

Parameter Required? Notes
nicknamePattern N Null means return all jobs. Patterns can include the % character to perform SQL LIKE matches.

Retrieve a list of known scheduling hosts

List<Host> getSchedulingHosts(boolean activeOnly) throws Exception

Parameters

Parameter Required? Notes
activeOnly Y Use this flag to restrict the return values to only Obsidian hosts currently active. Otherwise, all hosts associated with this Obsidian cluster are returned.

Create new JobState

JobConfiguration insertJobSchedule(Job job, String schedule, String status, com.carfey.jdk.lang.DateTime effectiveDate, com.carfey.jdk.lang.DateTime endDate, Long customCalendarId, String auditUser) throws Exception

Will cause existing schedules to be modified, split, overwritten as dictated by the current configuration and new values.

Parameters

Parameter Required? Notes
job Y No data values from this job will be applied. Only used as a referenced to JobId and Version.
effectiveDate Y Must be at least one minute in the future.
endDate Y Must be at least one minute in the future. For an unending schedule, use ObsidianAdministrator.END_OF_TIME.
status Y Must be one of ENABLED, UNSCHEDULED_ACTIVE, CHAIN_ACTIVE, DISABLED, AD_HOC_ACTIVE.
schedule N Only required if the status would require a schedule. Cron syntax.
customCalendarId N On ENABLED schedules, optional CustomCalendar.
auditUser N Optional user that is marked in Obsidian Audit columns.

Submit job for execution

void submitOneTimeExecution(Job job, com.carfey.jdk.lang.DateTime optionalFutureRuntime, JobParameter[] parameters, String auditUser) throws Exception

Submit a job for one-time execution either immediately or at a specified time in the future.

Parameters

Parameter Required? Notes
job Y No data values from this job will be applied. Only used as a referenced to JobId and Version.
parameters N Optional. Parameter definitions are merged into the job's runtime parameters for this runtime only. Parameters must have values for "name", "type" and "value". To define multiple values for a single parameter name, simply supply multiple items with the same name. If the parameter name matches a parameter defined for the job, it must be of the same type. Type must be one of STRING, INTEGER, LONG, DECIMAL, BOOLEAN or CLASS.
optionalFutureRuntime N Not null values must be in the future. If specified, the job will be run at the specified date and time (minute-precision) in the future. Otherwise, the job will be queued up to be triggered at the next minute.
auditUser N Optional user that is marked in Obsidian Audit columns.

Update a job's configuration

JobConfiguration updateJob(Job job, String auditUser) throws Exception

Parameters

Parameter Required? Notes
job Y All values contained therein will be used to update the job. If you wish to only change some values, retrieve the job and then modify those values on the returned value.
auditUser N Optional user that is marked in Obsidian Audit columns.

Create or Update a Custom Calendar

CustomCalendarsaveCustomCalendar(CustomCalendar calendar, String auditUser) throws Exception

Create or update an existing Custom Calendar. Names must be unique across all Calendars.

Parameters

Parameter Required? Notes
calendar Y
auditUser N Optional user that is marked in Obsidian Audit columns.

Retrieve a list of available Custom Calendars

List<CustomCalendar> listCustomCalendars() throws Exception

List all available CustomCalendars.

Classes

To represent Obsidian state in the Legacy API, a few basic bean classes are used as described below. Javadoc formatted documentation is also available.

com.carfey.ops.api.Host

Obsidian Host(Node) information.

Fields

Parameter Type Notes
HostName String Name of host. Either as assigned during Obsidian startup or as derived from Operating System.
HeartBeatTime com.carfey.jdk.lang.DateTime Last heartbeat of Obsidian.
HostEnabled Boolean Is host currently enabled.

com.carfey.ops.api.JobState

Represents a scheduled job state. Each job can have many of these including historical data. Fields as outlined at Schedule Wiki

Fields

Parameter Type Notes
EffectiveDate com.carfey.jdk.lang.DateTime
EndDate com.carfey.jdk.lang.DateTime
JobStatus String The status associated with the state. Must be one of ENABLED, UNSCHEDULED_ACTIVE, CHAIN_ACTIVE, DISABLED, AD_HOC_ACTIVE.
Schedule String Schedule pattern using cron syntax. Mandatory or not permitted as per rules associated with JobStatus.

com.carfey.ops.api.CustomCalendar

Used to exclude specific dates from a job's runtime schedule.

Fields

Parameter Type Notes
Name String Custom Calendar name.
CustomCalendarId Long Custom Calendar Primary Key
Version Long
Dates List<Date> List of dates for exclusion.

com.carfey.ops.api.Job

This class represents an executable Obsidian Job. Can either represent an Obsidian Job that already is configured (for modification requests) or one that is to be created. All fields correspond to the Admin Jobs UI.

Fields

Parameter Type Notes
JobId Long Job Primary Key.
Version Long Job Version. Used for optimistic database updates.
JobClass String Mandatory value specifying the fully qualified job class.
Nickname String Mandatory value used throughout Obsidian in display, messaging and logging.
ChainAll Boolean Mandatory value, defaults to false.
PickupBufferMinutes Long Mandatory value, defaults to 2.
MinExecutionDuration String Optional.
MaxExecutionDuration String Optional.
RecoveryType String Mandatory, defaults to NONE. Must be one of NONE, LAST, CONFLICTED, ALL.
FixedHosts List<String> Optional. The host names that this job is restricted to.
JobParameter List<JobParameter> Optional. If a job defines required parameters with the @Configuration annotation, a job will fail to create unless they are supplied. Otherwise, this field is optional. Parameter definitions must have values for "name", "type" and "value", where type is one of STRING, INTEGER, LONG, DECIMAL, BOOLEAN or CLASS.

com.carfey.ops.api.JobConfiguration

This class represents an executable Obsidian Job as configured in this Obsidian cluster and is a specialization of com.carfey.ops.api.Job. All fields correspond to the Admin Jobs UI.

Fields

Parameter Type Notes
Job Fields As above
JobStates List<JobState> Configured JobStates.

Authorization

The Legacy API is not secured. Any code that has access to the Obsidian database via its defined credentials can manipulate Obsidian job configurations.