Legacy API

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.

Overview

The Obsidian Embedded 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 Embedded 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, 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.
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 Embedded 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>	The host names that this job is restricted to.
JobParameter	List<JobParameter>	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 Embedded API is not secured. Any code that has access to the Obsidian database via its defined credentials can manipulate Obsidian job configurations.