Embedded API

Obsidian 2.3 introduced a new unified Embedded API which contains all the same actions and semantics as the REST API. It replaces the old Legacy API.

This API is accessible through Java, and can be used in software environments where the REST API is unavailable or undesired.

Javadoc is also available to supplement this page.

Overview

The Obsidian Embedded API allows your application a way to access Obsidian data, schedule jobs, and control Obsidian in a variety of ways.

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.

Accessing the API

The Embedded API is written in Java and can be be accessed within the context of a running Obsidian node, although the scheduler itself need not be active.

In addition, it can be embedded in applications that are not running Obsidian, simply by including Obsidian's dependent libraries and properties file.

Authorization

The Embedded API is not secured, though all actions accept an audit user which is linked to actions which modify Obsidian state. Any code that has access to the Obsidian database via its defined credentials can manipulate Obsidian job configurations.

Transactions

By default, when you invoke actions within the API, each individual call is in its own transaction which is committed when successful, and rolls back on failure.

However, you can wrap multiple API calls into a single transaction, so you get one unit of work which either is fully committed or rolled back. An example is shown below. For full semantics, see AbstractAPIManager.withTransaction.

final String auditUser = "Bob";

List<HostDetail> updated = new HostManager().withTransaction(auditUser, new Callable<<HostDetail>>() {
    
    public List<HostDetail> call() throws Exception {
        
        // disable some hosts in an atomic manner (does not have to be the same instance of even type of Manager class)
        HostDetail hostA = new HostManager().updateHost("hostA", new HostUpdateRequest().withEnabled(false), auditUser );
        HostDetail hostB = new HostManager().updateHost("hostB", new HostUpdateRequest().withEnabled(false), auditUser );
            
        // this is within the same transaction
        new JobManager().resubmitRuntime(jobToResubmit, auditUser);

        return Arrays.asList(hostA, hostB);
    }
});
     
System.out.println("Updated hosts: " + updated);

API Basics

The API is exposed through Manager classes in the package com.carfey.ops.api.embedded:

• JobManager - Create and manage jobs.
• RuntimeManager - List job runtime history, resubmit jobs, preview scheduled times, etc.
• HostManager - Manage and list active scheduling hosts (i.e. nodes).
• CustomCalendarManager - Manage custom calendars.

To invoke an API method, simply create a new Manager instance, and invoke the appropriate method:

RuntimeListing recentRuntimes = new RuntimeManager().listRuntimes(new RuntimeListingParameters());

You can reuse manager instances if you like, but it is ultimately up to your preference, as it offers no clear

Exceptions

API calls generally throw three types of exceptions:

• ValidationException - some sort of validation error occurred.
• MissingEntityException - The requested entity could not be found by the ID supplied.
• All other Exception types - some other type of error that you probably can't do much with (database issues, etc.).

When integrating the API into your application, you may wish to apply appropriate handling to ValidationException and MissingEntityException, but otherwise you can treat exceptions as a generic server errors.

Enumerations

Below are valid values for commonly used fields in the API. These are also used by the REST API.

Corresponding Java enums can be found in the package com.carfey.ops.api.enums.

Job Status

• ENABLED
• DISABLED
• UNSCHEDULED_ACTIVE or UNSCHEDULED ACTIVE
• CHAIN_ACTIVE or CHAIN ACTIVE
• AD_HOC_ACTIVE or AD HOC ACTIVE

Job History Status

• READY
• RUNNING
• COMPLETED
• FAILED
• MISSED
• DIED
• CONFLICTED
• OVERLAPPED
• ABANDONED
• CONFLICT_MISSED or CONFLICT MISSED
• CHAIN_SKIPPED or CHAIN SKIPPED

Job Recovery Type

• NONE
• LAST
• ALL
• CONFLICTED

Job Parameter Type

• STRING
• INTEGER
• LONG
• DECIMAL
• BOOLEAN
• CLASS

JobManager API

JobManager is used to manage job configurations. If you are looking for ways to view or manage job runtimes, see RuntimeManager.

Listing/Searching Jobs

You can list or search existing jobs using JobManager.listJobs(), which accepts an optional JobListingParameters and returns a JobListing.

You can limit the returned jobs by providing a JobListingParameters.

REST equivalent: Get a list of jobs

Adding a Job

You can add a new job using JobManager.addJob(), which accepts a JobCreationRequest.

When you create the job, you provide an initial schedule.

JobCreationRequest Fields

Field	Required?	Notes
jobClass	Y	Fully qualified class name of the job. Max 255 chars.
nickname	Y	Unique nickname for the job. Max 255 chars.
pickupBufferMinutes	N	Pickup buffer minutes which defaults to 2. Integer greater than zero.
recoveryType	Y	Recovery type as defined in Enumerations.
state	Y	Initial schedule's job status as defined in Enumerations.
schedule	Y/N	If state is ENABLED, the mandatory cron-style schedule for the job. If not ENABLED, this should be omitted.
effectiveDate	N	Optional effective date for the initial schedule, with no seconds specified. If not set, this defaults to next minute. Until this date is reached, the job is DISABLED.
endDate	N	Optional end date for the initial schedule, with no seconds specified. If set, the job will become DISABLED after this date passes.
customCalendarId	N	Optional custom calendar id.
hosts	N	Zero or more host names that this job may run on. If none set, the job may run on any host.
minExecutionDuration	N	The minimum expected job runtime. Format is an integer greater than zero immediately followed by "s", "m" or "h". Example: "15m".
maxExecutionDuration	N	The maximum expected job runtime. Format is an integer greater than zero immediately followed by "s", "m" or "h". Example: "15m".
autoRetryCount	N	Number of auto retries on non-interrupted execution failure. Defaults to 0, which means none are desired.
chainAll	N	Boolean indicating whether all chained instances are triggered when job is currently running. Otherwise, only one newly chained record is created. Defaults to false.
parameters	Y/N	Zero or more parameter definitions. 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 a valid parameter type outlined in Enumerations. To define multiple values for a single parameter name, simply include multiple items in the parameters collection.

REST equivalent: POST a new job

RuntimeManager API

Coming soon

HostManager API

Coming soon

CustomCalendarManager API

Coming soon