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 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. You can even call API operations from within jobs, which you can use to get custom chaining or workflow behaviour, or update configuration on certain types of events detected in a job.
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, job conflicts and chaining.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.
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.
Note on compatibility: Prior to Obsidian 2.5, some request classes used String values rather than Java enums. This is no longer the case.
Note on naming: Prior to Obsidian 2.5, input values for REST endpoints could use spaces in place of underscores for enumeration values. This is no longer the case.
Job State
ENABLED
DISABLED
UNSCHEDULED_ACTIVE
CHAIN_ACTIVE
AD_HOC_ACTIVE
Job History Status
READY
RUNNING
COMPLETED
FAILED
MISSED
DIED
CONFLICTED
OVERLAPPED
ABANDONED
CONFLICT_MISSED
CHAIN_SKIPPED
PENDING
Job Submission Mode
CHAIN_SUBMISSION
CONFLICTED_RECOVERY
Job Recovery Type
NONE
LAST
ALL
CONFLICTED
Job Parameter Type
STRING
INTEGER
LONG
DECIMAL
BOOLEAN
CLASS
Job Chain Status
ABANDONED
COMPLETED
CONDITIONAL
DIED
FAILED
MISSED
OVERLAPPED
CHAIN_SKIPPED
Job Chain/Conditional Job Notification Operator
EQUALS
NOT_EQUALS
IN
NOT_IN
EXISTS
NOT_EXISTS
REGEXP
STARTS_WITH
ENDS_WITH
CONTAINS
GREATER_THAN
LESS_THAN
GREATER_THAN_OR_EQUAL
LESS_THAN_OR_EQUAL
Subscription/Log Category
DASHBOARD
DISPATCH
JOB
JOB_CHAIN
JOB_CONFIG
JOB_QUEUER
JOB_RECOVERY
JOB_RUN
JOB_SPAWNER
LICENCE
SYSTEM_PARAMETER
QUEUE
Subscription/Log Level
FATAL
ERROR
WARNING
INFO
DEBUG
TRACE
User Role
ADMIN
WRITE
OPERATOR
AUTHOR
API
LIMITED_READ
As of Obsidian 5.0.0, these are class constants instead of enums to support dynamic roles.
Subscription Job Status
COMPLETED
CONDITIONAL
DIED
FAILED
RECOVERY
Sort Direction
ASC
DESC
JobManager API
JobManager is used to manage job configurations, conflicts and chaining. If you are looking for ways to view or manage job runtimes, see RuntimeManager.
List 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
.
JobListingParameters Fields
Field | Required? | Notes |
---|---|---|
activeStatuses | N | Restricts the preview to the selected a valid JobStatus values |
effectiveDate | N | If querying by activeStatuses, this allows you to indicate what point in time to compare against the job status. Defaults to next minute. |
hosts | N | If specified, only jobs that run on the specified host name(s) are included. |
nicknames | N | If specified, only jobs matching the supplied nicknames are returned. Wildcards may be included to support partial matches by using %, or exact literals can be used. For example, to find all jobs containing the word "order", use "%order%". |
jobClasses | N | If specified, only jobs matching the supplied job class are returned. Wildcards may be included to support partial matches by using %, or exact literals can be used. For example, to find all jobs with job classes containing the word "Export", use "%export%". Supports multiple values. Available from version 3.4.0 forward. |
folders | N | If specified, only jobs matching the supplied folders are returned. If a parent path is supplied, all jobs containing that path or subpaths are included in the results. If an empty string or null is supplied, jobs with no folder will be returned. Supports multiple values. Available from version 4.1.0 forward. |
filterParameters | N | If specified, values supplied in this map can be used to match on job parameter values, either custom or defined. If multiple values for the same name (i.e. key) are supplied, a job is matched if any of its configured values match one of the supplied values. If multiple names are used, each must have a matching value for the job to be returned.
Usage note: This can be used to tag jobs with searchable metadata by configuring custom parameters. For example, if jobs belong to logical groups, you may create a custom parameter on applicable jobs named "group" and use filterParameters to locate jobs belonging to specific groups, such as "customer" or "order". |
REST equivalent: GET a list of jobs
Get a Job's Details
To get full job information, including all historical schedules and parameter information, call JobManager.getJob() with the appropriate job ID. The method will return a JobDetail, or throw a MissingEntityException if it does not exist.
REST equivalent: GET details of an existing job
Add a Job
You can add a new job using JobManager.addJob(), which accepts a JobCreationRequest. The method will return the job as a JobDetail.
When you create the job, you provide an initial schedule.
Note: When supplying effective and end dates for schedules, seconds must be omitted. To do so, use com.carfey.jdk.lang.DateTime.clearSeconds()
, which returns a copy of the date with seconds removed.
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. |
folder | N | Folder in which to place the job. Paths are separated by forward-slashes. Back-slashes are automatically converted to forward-slashes, and leading or trailing slashes are removed. Max 255 chars. Available from version 4.1.0 forward. |
pickupBufferMinutes | N | Pickup buffer minutes which defaults to 2. Integer greater than zero. |
recoveryType | Y | The JobRecoveryType to use for the job. |
state | Y | Initial schedule's JobStatus. |
schedule | Y/N | If state is ENABLED , the mandatory cron-style schedule for the job. If not ENABLED , this should be omitted. As of Obsidian 3.3.0, you may specify multiple cron patterns delimiting them with a semi-colon.
|
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". |
autoInterrupt | N | Boolean indicating whether auto interrupt functionality is desired. May only be true when the job is an interruptable job and a maxExecutionDuration has been specified. Defaults to false. |
autoRetryCount | N | Number of auto retries on non-interrupted execution failure. Defaults to 0, which means none are desired. |
autoRetryInterval | N | As of Obsidian 2.5. Minimum number of minutes between auto retries - calculated from failure time. Defaults to 0 and indicates try at next available opportunity. |
autoRetryIntervalExponent | N | As of Obsidian 2.5. Boolean indicating whether to exponentially increase interval time between retries. |
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 ParameterType. To define multiple values for a single parameter name, simply include multiple items in the parameters collection. As of 2.5, values may contain global parameter references (e.g. {{globalParameterName}} ).
|
REST equivalent: POST a new job
Update a Job
You can update an existing job using JobManager.updateJob(), which accepts a job ID and a JobUpdateRequest. The method will return the new state of the job as a JobDetail, or throw a MissingEntityException if it does not exist.
This does not support schedule changes or additions. For schedule changes, see Add a New Schedule to a Job.
This method will only update fields that are supplied in the JobUpdateRequest
. You may update one or more fields as desired.
JobUpdateRequest Format
Field | Required? | Notes |
---|---|---|
jobClass | N | Fully qualified class name of the job. Max 255 chars. |
nickname | N | Unique nickname for the job. Max 255 chars. |
folder | N | Folder in which to place the job. Paths are separated by forward-slashes. Back-slashes are automatically converted to forward-slashes, and leading or trailing slashes are removed. Max 255 chars. Available from version 4.1.0 forward. |
pickupBufferMinutes | N | Pickup buffer minutes. Integer greater than zero. |
recoveryType | N | The JobRecoveryType to use for the job. |
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: "2h". |
autoInterrupt | N | Boolean indicating whether auto interrupt functionality is desired. May only be true when the job is an interruptable job and a maxExecutionDuration has been specified. Defaults to false. |
autoRetryCount | N | Number of auto retries on non-interrupted execution failure. 0 if 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. |
parameters | 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. Note that a null value will result in existing parameters being preserved, while an empty list is considered replacing existing parameters. Parameter definitions must have values for name , type and value , where type is a valid ParameterType. To define multiple values for a single parameter name, simply include multiple items in the parameters collection. As of 2.5, values may contain global parameter references (e.g. {{globalParameterName}} ).
|
REST equivalent: PUT updates to an existing job
Delete a Job
You can delete an existing job using JobManager.deleteJob(), which accepts a job ID and cascade flag. The method will return the final state of the job before deletion as a JobDetail, or throw a MissingEntityException if it does not exist.
Parameters
Field | Required? | Notes |
---|---|---|
cascade | Y | If set to true, all job conflict and chain definitions for this job will also be deleted. If set to false, any existing job conflicts or chain definitions will cause the request to fail. |
REST equivalent: DELETE an existing job
List a Job's Schedules
You can access the full history of a job's schedules via JobManager.listJobSchedules() which accepts an optional JobScheduleListingParameters and returns a JobScheduleListing.
Note that the full schedule history can also be obtained via the schedules field of the JobDetail returned by JobManager.getJob().
REST equivalent: GET a list of an existing job's schedules
Add a New Schedule to a Job
You can add a new schedule to a job via JobManager.addJobSchedule(), which accepts a ScheduleCreationRequest.
This may be used to immediately change a job's scheduling state, or to schedule a future change. Creating a new schedule automatically splits and merges existing schedules. For example, if you have an enabled job and you disabled it for a day, the job will automatically re-enable after that day.
Note: When supplying effective and end dates for schedules, seconds must be omitted. To do so, use com.carfey.jdk.lang.DateTime.clearSeconds()
, which returns a copy of the date with seconds removed.
ScheduleCreationRequest Fields
Field | Required? | Notes |
---|---|---|
state | Y | The schedule's JobStatus. |
schedule | Y/N | If state is ENABLED , the mandatory cron-style schedule for the job. If not ENABLED , this should be omitted. As of Obsidian 3.3.0, you may specify multiple cron patterns delimiting them with a semi-colon.
|
effectiveDate | N | Optional effective date for the 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 schedule, with no seconds specified. If set, the job will become DISABLED after this date passes.
|
customCalendarId | N | Optional custom calendar for schedule. |
REST equivalent: POST a new schedule to an existing job
List Job Chains
You can list or search existing job chains using JobManager.listChains(), which accepts an optional JobChainListingParameters and returns a JobChainListing.
You can limit the returned job chains by providing a JobChainListingParameters
instance with the fields below.
JobChainListingParameters Fields
Field | Required? | Notes |
---|---|---|
active | N | Limits results to those matching the active flag (true/false). |
sourceJobId | N | Limits results to those matching the supplied source job ID. |
targetJobId | N | Limits results to those matching the supplied target job ID. |
REST equivalent: GET a list of job chains
Add a Job Chain
You can add a new job chain using JobManager.addChain(), which accepts a JobChainUpdateRequest. The method will return a JobChain.
JobChainUpdateRequest Fields
Field | Required? | Notes |
---|---|---|
sourceJobId | Y | ID of the source job. |
targetJobId | Y | ID of the target job to chain |
schedule | N | Optional schedule that constrains when the job chain triggers. |
triggerStates | Y | One or more JobChainStatus. Note that CONDITIONAL and COMPLETED types cannot be used on the same chain.
|
resultConditions | Y/N | Conditions based on job results that apply to the CONDITIONAL trigger state. Must be supplied only when that state is used, in which case at least one condition must be supplied. Result conditions consist of a variableName , an operator as a JobChainConditionOperator, and for most operators, a list of values . The EXISTS and NOT EXISTS operators do not use values, so they must not be supplied. Operators IN and NOT IN support one or more values, and all other operators accept a single value in the values list.
|
REST equivalent: POST a new job chain
Update a Job Chain
You can add update an existing job chain using JobManager.updateChain(), which accepts a JobChainUpdateRequest. The method will return the updated JobChain.
The format of JobChainUpdateRequest
is identical to that of Add a Job Chain.
REST equivalent: PUT updates to an existing job chain
Delete a Job Chain
As of Obsidian 2.6.
You can delete an existing job chain using JobManager.deleteChain(). The method will return the final state of the job chain before deletion as a JobChain, or throw a MissingEntityException if it does not exist.
REST equivalent: DELETE an existing job chain
List Conflicts
You can access all configured job conflict configuration via JobManager.listConflicts(), which will return ConflictListing.
The return value includes all job conflict sets, with each set in order of priority. Non-conflicted jobs are also returned.
REST equivalent: GET a list of job conflicts
Update Conflicts
To update the configured job conflict sets, use JobManager.updateConflicts() with a ConflictUpdateRequest which will return the updated ConflictListing.
The request replaces the current job conflict configuration with the supplied configuration. The return value includes all job conflict sets, with each set in order of priority. Non-conflicted jobs are also returned.
ConflictUpdateRequest Format
Field | Required? | Notes |
---|---|---|
conflicts | N | A list of ordered sets containing job IDs. Each inner set contains jobs that conflict with each other, in order of execution precedence. Jobs that do not conflict with any other jobs are simply omitted from this list. As of 2.9.0, a job can exist in multiple conflict sets, but should only occur in a particular set once. To remove all job conflicts, an empty list can be supplied for this field.
When selecting available non-conflicted jobs to run, Obsidian inspects the conflict sets in the order provided when they are saved, and selects the highest priority available job before moving onto the next conflict set. When priority is significant and varies across different sets, ensure your conflict sets are in the desired order. |
REST equivalent: PUT updates to job conflicts
List a Specific Job's Conflicts
You can return conflicts for a specific job with JobManager.listJobConflicts(long), which will return JobConflictListing.
Conflicting jobs are returned in priority order, including the job for which this request was made, in order that its priority within the set can be determined. Note that if the job has no conflicts, the returned conflicting jobs list will be empty, and will not contain the requested job.
REST equivalent: GET a list of conflicts for a specific job
Update Global Parameters
To update the configured global parameters, use JobManager.updateGlobalParameters() with a GlobalParameterUpdateRequest which will return the updated GlobalParameterListing.
The request replaces the current global parameters with the supplied configuration. Supplying an empty list of parameters will result in all global parameters being deleted.
Note: Calls to remove or alter global parameters may fail if jobs that use them do not pass parameter validation as a result of the change. This can be caused by removing a referenced global parameter or values that cannot be interpreted as the appropriate type in a job.
GlobalParameterListing Format
Field | Required? | Notes |
---|---|---|
parameters | N | Zero or more GlobalParameter instances. Each parameter must have values for name , type and values , where type is a valid ParameterType.
|
REST equivalent: PUT updates to global parameters
List Global Parameters
You can list all configured global parameters using listGlobalParameters(), which will return a GlobalParameterListing.
REST equivalent: GET a list of configured global parameters
List Job Folders
You can list all used job folders using listJobFolders(), which will return a JobFolderListing.
REST equivalent: GET a list of job folders
RuntimeManager API
RuntimeManager is used to manage and view scheduled job runtimes (i.e. history). If you are looking for ways to view or manage jobs, see JobManager.
List Scheduled Runtimes
To get a list of scheduled or completed job runtimes (i.e. history), use RuntimeManager.listRuntimes(), which accepts an optional RuntimeListingParameters instance. As of Obsidian 3.5, the results in the returned RuntimeListing are ordered by scheduled time descending, unless overridden by the sort
parameter.
Note: The nextPageStartKey
field in the RuntimeListing
indicates that there were too many results to return (i.e. exceeded maxRecords
as configured in the scheduler settings screen, or the quantity
parameter). To fetch the next page of results, invoke the same method with the startKey
field on RuntimeListingParameters
set to the returned nextPageStartKey
.
RuntimeListingParameters Fields
Field | Required? | Notes |
---|---|---|
jobIds | N | Restricts the search to the selected jobs. |
statuses | N | Restricts the search to the selected JobRuntimeStatus values. |
hosts | N | If specified, only job runtimes that are assigned to the specified host(s) are included. |
folders | N | If specified, only jobs matching the supplied folders are returned. If a parent path is supplied, all jobs containing that path or subpaths are included in the results. If an empty string is supplied, jobs with no folder will be returned. Supports multiple values. Available from version 4.1.0 forward. |
startDate | N | Start date for the job runtimes to return (inclusive). Defaults to 24 hours ago. |
endDate | N | End date for the job runtimes to return (inclusive). Defaults to a day after the start time. Must be after the start time. |
startKey | N | If requesting the next page of results from a previous call, set it to the returned nextPageStartKey .
|
quantity | N | Indicates the maximum number of results to return. This overrides the maxRecords as configured in the scheduler settings screen. As of Obsidian 3.5.0.
|
sort | N | A valid SortDirection, which controls the ordering of returned results. In all cases, the job scheduled time is used to sort results. As of Obsidian 3.5.0. |
filterParameters | N | If specified, values supplied in this map can be used to match on runtime parameter values (not job-level parameters). If multiple values for the same name (i.e. key) are supplied, a runtime is matched if any of its configured values match one of the supplied values. If multiple names are used, each must have a matching value for the runtime to be returned. |
REST equivalent: GET a list of scheduled runtimes
Get Details on a Scheduled or Completed Runtime
To get full details on a scheduled or completed job runtime, including job results and one-time run configuration, use RuntimeManager.getRuntime(). The method returns a RuntimeResult, which has a nested RuntimeDetail containing the full job output and one-time run parameters, or throws a MissingEntityException if it does not exist.
REST equivalent: GET details of an existing scheduled or completed runtime
Preview Runtimes
To preview future runtimes for one or more jobs, use RuntimeManager.listRuntimePreview(), which accepts an optional RuntimePreviewParameters instance to filter the results. The method returns a RuntimePreviewListing.
This method is useful to see when jobs will run during a given time period. Note that these are an estimate of runtimes and cannot account for overlapped jobs, schedule changes or other issues that may result in altered execution times. Results are ordered by scheduled time ascending.
Note: The capped field in the returned RuntimePreviewListing
indicates that there were too many results to return (i.e. exceeded maxRecords as configured in the scheduler settings screen). If you are hitting this condition, try limiting your date range or other parameters. Due to the nature of the runtime preview, paging is not feasible.
RuntimePreviewParameters Fields
Field | Required? | Notes |
---|---|---|
jobIds | N | Restricts the preview to the selected jobs. |
startDate | N | Start date for the runtimes to preview (inclusive). Defaults to the current minute. |
endDate | N | End date for the runtimes to preview (inclusive). Defaults to a day after the start time. Must be after the start time. |
REST equivalent: GET a list of runtime previews
Schedule a New Runtime for a Job
To submit an ad hoc job run (executed immediately), or a one-time run scheduled for a later time, use RuntimeManager.submitRuntime(). A RuntimeSubmissionRequest must be supplied. The method returns a RuntimeSubmissionResult if it succeeds, or throws a MissingEntityException if the specified job ID does not exist.
Note: The job must be in a valid state to allow for execution (i.e. UNSCHEDULED_ACTIVE
, ENABLED
, or AD_HOC_ACTIVE
).
RuntimeSubmissionRequest Fields
Field | Required? | Notes |
---|---|---|
scheduledTime | N | The scheduled time, when the request is for a scheduled one-time run. If not supplied, the runtime is submitted for immediate execution as an ad hoc job. |
parameters | N | Zero or more parameter definitions. Parameter definitions must have values for name , type and value , where type is a valid ParameterType. To define multiple values for a single parameter name, simply include multiple items in the parameters collection. If the parameter name matches a parameter defined for the job, it must be of the same type, and it will completely replace all configured values at the job level.
|
REST equivalent: POST a new scheduled runtime for an existing job
Delete a Future Scheduled Runtime for a Job
Since Obsidian 4.7.0
To delete a future scheduled runtime, use RuntimeManager.deleteOneTimeRun(). A OneTimeRunDeleteRequest must be supplied. The method returns a OneTimeDeletionResult if it succeeds, or throws a MissingEntityException if the specified job ID does not exist.
Note: When more than on runtime is scheduled for the given time, this function will remove gaps, that is ensure the remaining ordinals start at 0 and increment without skipping any values. For example, if you have 3 instances scheduled (ordinals 0, 1 & 2) and request ordinal 0 be deleted, the remaining two ordinals (1 & 2) will be renumbered to 0 & 1.
OneTimeRunDeleteRequestFields
Field | Required? | Notes |
---|---|---|
scheduledTime | Y | The future scheduled runtime. |
ordinal | Y/N | The ordinal of future dated runtime. If only one runtime is scheduled for the given date, the value can be omitted or should be 0. If more than one instance is scheduled at the given time, the actual ordinal must be specified. |
REST equivalent: DELETE a future scheduled runtime
Resubmit a Failed Job Runtime
If a job execution fails and you wish to resubmit it, use RuntimeManager.resubmitRuntime() with the appropriate job runtime ID. The method returns a RuntimeResubmissionResult if the action succeeds, or throws a MissingEntityException if the specified job runtime ID does not exist.
REST equivalent: POST a resubmission request for a failed job runtime
Interrupt a Running Job Runtime
To interrupt a currently running job runtime, use RuntimeManager.interruptRuntime() with the appropriate job runtime ID. A JobInterruptResult is returned upon success, or a MissingEntityException is thrown if the specified job runtime ID does not exist.
This request can only be made once successfully. An interruption request will result in the job being terminated, as long as it does not terminate naturally very soon after the request is made, and the job is capable of shutting down. Not all jobs can be terminated. See Interruptable Jobs for full details.
REST equivalent: POST an interruption request to kill a running job
Post Results to a Pending (Async) Runtime
As of Obsidian 4.5.0
To indicate the final status of an Async Job, use RuntimeManager.setAsyncRuntimeResults() with the appropriate job runtime ID. An AsyncJobRuntimeResultsRequest is returned upon success, or a MissingEntityException is thrown if the specified job runtime ID does not exist.
This request can only be made once successfully. Final state can only be COMPLETED
or FAILED
as per AsyncJobRuntimeStatus. If FAILED
, then a finalizationException must be provided. If COMPLETED
, finalizationException must be null.
REST equivalent: POST async results
List Job Dashboard (Latest Scheduled Runtime by Job)
As of Obsidian 4.10.2
To get a list of latest job runtimes by job(i.e. history), use RuntimeManager.listJobsDashboard(), which accepts an optional JobDashboardListingParameters instance. The results in the returned JobDashboardListing are ordered by scheduled time descending, unless overridden by the sort
parameter.
Note: The nextPageStartKey
field in the JobDashboardListing
indicates that there were too many results to return (i.e. exceeded maxRecords
as configured in the scheduler settings screen, or the quantity
parameter). To fetch the next page of results, invoke the same method with the startKey
field on JobDashboardListingParameters
set to the returned nextPageStartKey
.
JobDashboardListingParametersFields
Field | Required? | Notes |
---|---|---|
jobIds | N | Restricts the search to the selected jobs. Do not combine with jobNicknames. |
jobNicknames | N | Restricts the search to the selected jobs. Do not combine with jobIds. |
hosts | N | If specified, only the latest job runtimes that are run on the specified host(s) are included. |
folders | N | If specified, only jobs matching the supplied folders are returned. If a parent path is supplied, all jobs containing that path or subpaths are included in the results. If an empty string is supplied, jobs with no folder will be returned. Supports multiple values. |
startKey | N | If requesting the next page of results from a previous call, set it to the returned nextPageStartKey .
|
quantity | N | Indicates the maximum number of results to return. This overrides the maxRecords as configured in the scheduler settings screen.
|
sort | N | A valid SortDirection, which controls the ordering of returned results. In all cases, the job scheduled time is used to sort results. |
REST equivalent: GET a list of the latest scheduled runtime by job
HostManager API
HostManager is used to manage and view scheduling hosts.
List Scheduling Hosts
To get a list of known hosts which are running or recently shut down abnormally, use HostManager.listHosts(), which returns a HostListing.
REST equivalent: GET a list of known scheduling hosts
Get a Specific Host
To get details on a host by ID or name, use HostManager.getHost(id) or or HostManager.getHost(String).
The method returns a HostDetail, or throws a MissingEntityException if the specified host ID or name does not exist.
REST equivalent: GET details on an existing scheduling host
Get Licence Health by Host
As of Obsidian 4.3.0
Identical to Get a Specific Host, except it throws an Exception if the licence is invalid or expired.
To get licence health on a host by ID or name, use HostManager.getLicenceHealth(id) or or HostManager.getLicenceHealth(String).
The method returns a HostDetail, or throws a MissingEntityException if the specified host ID or name does not exist.
REST equivalent: GET licence details on an existing scheduling host
Update a Host
To enable or disable a scheduling host, use HostManager.updateHost(long) or HostManager.updateHost(String) with a HostUpdateRequest. Both methods return a HostDetail, or throw a MissingEntityException if the specified host ID or name does not exist.
HostUpdateRequest Fields
Field | Required? | Notes |
---|---|---|
enabled | Y | Should this host should be enabled? |
REST equivalent: PUT updates to an existing scheduling host
CustomCalendarManager API
The CustomCalendarManager allows for managing of Custom Calendars.
List Calendars
To list existing custom calendars, use CustomCalendarManager.listCalendars(), which returns a CustomCalendarListing.
REST equivalent: GET a list of custom calendars
Get Details on a Calendar
To get details on an existing custom calendar, use CustomCalendarManager.getCalendar(), which returns a CustomCalendar, or throws a MissingEntityException if the specified calendar ID does not exist.
REST equivalent: GET details on an existing custom calendar
Add a Calendar
To add a new custom calendar, use CustomCalendarManager.addCalendar() with a CustomCalendarUpdateRequest. The method returns a CustomCalendar.
CustomCalendarUpdateRequest Format
Field | Required? | Notes |
---|---|---|
name | Y | Calendar name |
dates | Y | Dates to exclude |
REST equivalent: POST a new custom calendar
Update a Calendar
To update an existing calendar, use CustomCalendarManager.updateCalendar() with a CustomCalendarUpdateRequest. The method returns a CustomCalendar or throws a MissingEntityException if the specified calendar ID does not exist.
The format of CustomCalendarUpdateRequest
is identical to that of Add a Calendar.
REST equivalent: PUT updates to an existing custom calendar
Delete a Calendar
Available as of version 3.0.
You can delete an existing job using CustomCalendarManager.deleteCalendar(). The method will return the final state of the calendar before deletion as a CustomCalendar or throw a MissingEntityException if the specified calendar ID does not exist.
REST equivalent: DELETE an existing custom calendar
NotificationManager API
As of Obsidian 3.0
The NotificationManager allows for managing of Obsidian event notifications, including subscribers and templates used to send notifications, and allows searching of triggered notifications.
List Subscribers
To list existing subscribers, use NotificationManager.listSubscribers(), which returns a SubscriberListing.
REST equivalent: GET a list of subscribers
Get Details on a Subscriber
To get details on an existing subscriber, use NotificationManager.getSubscriber(), which returns a Subscriber, or throws a MissingEntityException if the specified subscriber ID does not exist.
REST equivalent: GET details of an existing subscriber
Add a Subscriber
To add a new subscriber, use NotificationManager.addSubscriber() with a SubscriberUpdateRequest. The method returns a Subscriber.
SubscriberUpdateRequest Format
Field | Required? | Notes |
---|---|---|
emailAddress | Y | Valid email address of the subscriber. Must be unique. |
active | N | Whether the subscription is active. Defaults to false. |
generalSubscriptions | N | Zero or more instances of GeneralSubscriptionUpdateRequest. Each item contains a required subscription Category and LogLevel in the category and level fields respectively, an optional jobId and an optional active flag which defaults to false.
Note: Only |
jobExecutionSubscriptions | N | Zero or more instances of JobExecutionSubscriptionUpdateRequest. Each item contains a required triggerStates field which uses the SubscriptionJobStatus enum. Note that CONDITIONAL and COMPLETED types cannot be used on the same chain.
If the In addition, two additional optional fields control which jobs the subscription applies to. Finally, the |
REST equivalent: POST a new subscriber
Update a Subscriber
To update an existing subscriber, use NotificationManager.updateSubscriber() with a SubscriberUpdateRequest. The method returns a Subscriber or throws a MissingEntityException if the specified subscriber ID does not exist.
The format of SubscriberUpdateRequest
is identical to that of Add a Subscriber.
REST equivalent: PUT updates to an existing subscriber
Delete a Subscriber
You can delete an existing subscriber using NotificationManager.deleteSubscriber(). The method will return the final state of the subscriber before deletion as a Subscriber, or throw a MissingEntityException if it does not exist.
REST equivalent: DELETE an existing subscriber
List Templates
To list existing notification templates, use NotificationManager.listTemplates(), which returns a TemplateListing.
REST equivalent: GET a list of templates
Get Details on a Template
To get details on an existing template, use NotificationManager.getTemplate(), which returns a Template, or throws a MissingEntityException if the specified template ID does not exist.
REST equivalent: GET details of an existing template
Add a Template
To add a new template, use NotificationManager.addTemplate() with a TemplateUpdateRequest. The method returns a Template.
TemplateUpdateRequest Format
Field | Required? | Notes |
---|---|---|
name | Y | Unique name of the template. |
active | N | Whether the template is active. Defaults to false. |
category | N | The Category for the template, or null if it is the default generic template. Supports multiple values. Not all categories are supported. Only JOB , JOB_CHAIN , JOB_CONFIG , JOB_RECOVERY , LICENCE , QUEUE , SYSTEM_PARAMETER and null are valid values.
|
defaultForJobs | N | For job-related categories, setting this to true allows for a template to be used as the default template when one isn't assigned to a particular job. Defaults to false. |
jobIds | N | For job-related categories, specific jobs may be assigned to use this template. |
subjectTemplate | Y | A valid Mustache template for the subject. |
bodyTemplate | Y | A valid Mustache template for the body. |
REST equivalent: POST a new template
Update a Template
To update an existing template, use NotificationManager.updateTemplate() with a TemplateUpdateRequest. The method returns a Template or throws a MissingEntityException if the specified template ID does not exist.
The format of TemplateUpdateRequest
is identical to that of Add a Template.
REST equivalent: PUT updates to an existing template
Delete a Template
You can delete an existing template using NotificationManager.deleteTemplate(). The method will return the final state of the template before deletion as a Template, or throw a MissingEntityException if it does not exist.
REST equivalent: DELETE an existing template
List Notifications
To get a list notifications, use NotificationManager.listNotifications(), which accepts an optional NotificationListingParameters instance. The results in the returned NotificationListing are ordered roughly according to when they were created, but ordering is not guaranteed to be in order of created time. Note that existence of records does not necessarily indicate the notification was successfully sent or received.
Note: The nextPageStartKey
field in the LogListing
indicates that there were too many results to return (i.e. exceeded maxRecords
as configured in the scheduler settings screen). To fetch the next page of results, invoke the same method with the startKey
field on LogListingParameters
set to the returned nextPageStartKey
.
LogListingParameters Fields
Field | Required? | Notes |
---|---|---|
category | N | One or more notification log Category values used to limit the returned results. |
level | N | One or more notification log LogLevel values used to limit the returned results. |
start | N | Start date for the notifications to return (inclusive). Defaults to the current minute. |
end | N | Start date for the notifications to return (inclusive). Defaults to a day after the start time. Must be after the start time. |
startKey | N | If requesting the next page of results from a previous call, set it to the returned nextPageStartKey .
|
REST equivalent: GET a list of notifications
Get Details on a Notification
To get details on a single notification entry use NotificationManager.getNotification(). The method returns a Notification or throws a MissingEntityException if it does not exist. Note that existence of a record does not necessarily indicate the notification was successfully sent or received.
REST equivalent: GET details of an existing notification
LogManager API
As of Obsidian 3.0
LogManager is used to retrieve event log entries.
List Log Entries
To get a list log entries, use LogManager.listLogs(), which accepts an optional LogListingParameters instance. The results in the returned LogListing are ordered roughly according to when they were created, but ordering is not guaranteed to be in order of created time.
Note: The nextPageStartKey
field in the LogListing
indicates that there were too many results to return (i.e. exceeded maxRecords
as configured in the scheduler settings screen). To fetch the next page of results, invoke the same method with the startKey
field on LogListingParameters
set to the returned nextPageStartKey
.
LogListingParameters Fields
Field | Required? | Notes |
---|---|---|
host | N | If specified, only logs from the specified host name(s) are included. Supports multiple values. |
filterText | N | If specified, only messages containing the supplied filter text are returned. '%' can be used as a wildcard. |
category | N | One or more log Category values used to limit the returned results. |
level | N | One or more log LogLevel values used to limit the returned results. |
start | N | Start date for the logs to return (inclusive). Defaults to the current minute. |
end | N | Start date for the logs to return (inclusive). Defaults to a day after the start time. Must be after the start time. |
startKey | N | If requesting the next page of results from a previous call, set it to the returned nextPageStartKey .
|
REST equivalent: GET a list of logs
Get Details on a Log Entry
To get details on a single log entry use LogManager.getLog(). The method returns a Log or throws a MissingEntityException if it does not exist.
REST equivalent: GET details of an existing log
SystemParameterManager API
As of Obsidian 3.0
The SystemParameterManager allows for listing and updating Obsidian scheduler settings.
List System Parameters
To list editable system parameters, use SystemParameterManager.listParameters(), which returns a SystemParameterListing.
REST equivalent: GET a list of system parameters
Get Details on a System Parameter
To get details on specific system parameter, use SystemParameterManager.getParameter(), which returns a SystemParameter, or throws a MissingEntityException if the specified system parameter does not exist.
REST equivalent: GET details of system parameter
Update a System Parameter
To update a system parameter's value, use SystemParameterManager.updateParameter() with a value supplied as a String. The supplied value must be a valid String representation of the type for the system parameter (e.g. Integer, Boolean).
The method returns a SystemParameter or throws a MissingEntityException if the specified system parameter does not exist.
REST equivalent: PUT updates to a system parameter
UserManager API
As of Obsidian 3.0
The UserManager allows for managing of Obsidian users when native authentication is used. This API cannot be used when using LDAP or other custom authentication methods.
List Users
To list existing users, use UserManager.listUsers(), which returns a UserListing.
REST equivalent: GET a list of users
Get Details on a User
To get details on an existing user, use UserManager.getUser(), which returns a User, or throws a MissingEntityException if the specified user ID does not exist.
REST equivalent: GET details of an existing user
Add a User
To add a new user, use UserManager.addUser() with a UserCreationRequest. The method returns a User.
UserCreationRequest Format
Field | Required? | Notes |
---|---|---|
userName | Y | Unique user name used to log in. |
active | N | Whether the user is enabled. Defaults to false. |
roles | N | Zero or more Role values. Supplying no roles indicates it is a normal read-only user. |
password | Y | A password at least 6 characters long. |
REST equivalent: POST a new user
Update a User
To update an existing user, use UserManager.updateUser() with a UserUpdateRequest. The method returns a User or throws a MissingEntityException if the specified user ID does not exist.
Note that only supplied fields are updated. If a field is left null, the existing value will be left unchanged.
UserUpdateRequest Format
Field | Required? | Notes |
---|---|---|
active | N | Whether the user is enabled. Defaults to the existing active state. |
roles | N | Zero or more Role values. Supplying an empty list of roles indicates it is a normal read-only user. Supplying null indicates that the roles should not be updated. |
password | N | A password at least 6 characters long. If not supplied, the password is not changed. |
REST equivalent: PUT updates to an existing user
Delete a User
You can delete an existing user using UserManager.deleteUser(). The method will return the final state of the user before deletion as a User, or throw a MissingEntityException if it does not exist.
REST equivalent: DELETE an existing user
List Known MFA Users
As of Obsidian 5.0
To list all known MFA users, use UserManager.listMfaUsers(), which returns a MfaUserListing.
REST equivalent: GET a list of known MFA users
Reset Users' MFA State
As of Obsidian 5.0
You can reset one or more users' MFA state using UserManager.resetMfa() with a ResetMfaRequest. The method returns a MfaUserListing which echoes the user names that were reset.
REST equivalent: PUT MFA user resets
SystemRestore API
As of Obsidian 3.0
The SystemRestoreManager allows for importing and exporting full Obsidian configuration. See Initializing and Restoring for more details.
Get System Restore Configuration
To extract the current system restore configuration, use SystemRestoreManager.getConfiguration() which accepts an optional SystemRestoreParameters and returns a SystemRestoreConfiguration.
You can limit the returned configuration by providing a SystemRestoreParameters.
SystemRestoreParameters Fields
Field | Required? | Notes |
---|---|---|
excludeItems | N | Allows filtering out of specific groups of system configuration items. Supported values are jobs , chains , conflicts , systemParameters , customCalendars , globalParameters , users , templates , subscribers . Filtering out jobs automatically also filters out chains and conflicts and drops any other job references (such as in templates and subscribers). Since 3.8.0.
|
jobNicknames | N | Allows targeting only specific jobs in the jobs export. Filtering out any jobs automatically filters out all conflicts, any chains where these jobs exist and and drops any other references to these jobs (such as in templates and subscribers). Since 3.8.0. |
REST equivalent: GET a system restore configuration
Update System Restore Configuration
To import a system restore configuration (partial or complete), use SystemRestoreManager.updateConfiguration() with a SystemRestoreConfiguration. The method returns a SystemRestoreConfiguration representing the full system state, which may not be the same as the input value.
REST equivalent: PUT a system restore configuration
ScheduleAliasManager API
As of Obsidian 5.0
The ScheduleAliasManager allows for retrieving, creating, editing and deleting schedule aliases. See Schedule Aliases for more information.
List Schedule Aliases
To list the current schedule aliases, use ScheduleAliasManager.listScheduleAliases() which returns a ScheduleAliasListing.
REST equivalent: GET a list of schedule aliases
Create or Update Schedule Alias
To create or update a schedule alias, use ScheduleAliasManager.addOrUpdateScheduleAlias(). The method returns the updated ScheduleAlias representing the full system state, which may not be the same as the input value.
REST equivalent: PUT a schedule alias
Get a Schedule Alias
To retrieve a current schedule alias, use ScheduleAliasManager.getScheduleAlias() which returns a ScheduleAlias.
REST equivalent: GET a schedule alias
Delete a Schedule Alias
To delete an unused schedule alias, use ScheduleAliasManager.deleteScheduleAlias() which returns the deleted ScheduleAlias.
REST equivalent: DELETE a schedule alias