REST Endpoints

2025-12-16T00:05:02Z

Craig:

This page documents the format of each available REST endpoint.

For information on data formats, valid enumerations values, common behaviour and more, see the primary [[REST API]] page.

As of Obsidian 2.3, all endpoints have corresponding bean classes that can be used with JSON object mappers like [https://github.com/google/gson Gson]. If you wish to use these, please review [[REST_API#JSON_Bean_Classes|bean classes]] for information on serialization of Obsidian's custom types.

= Job Endpoints =

==GET a list of jobs==
'''<code>GET http(s)://localhost/rest/jobs[?host=host1&activeStatus=ENABLED&nickname=jobname&param_group=orders&jobClass=com.example.ExportJob]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobListing</code>

Returns a list of configured jobs, optionally filtered by query string parameters.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| activeStatus || N || Restricts the preview to the selected statuses. See [[Unified_API#Enumerations|Enumerations]] for valid values. Supports multiple values.
|-
| effectiveDate || N || If querying by activeStatus, this allows you to indicate what point in time to compare against the job status. Defaults to next minute.
|-
| host || N || If specified, only jobs that run on the specified host name(s) are included. Supports multiple values.
|-
| nickname || N || If specified, only jobs matching the supplied nickname 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%". Supports multiple values.
|-
| jobClass || 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.''
|-
| folder || 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.''
|-
| param_''parameterName'' || N || If specified, values starting with ''param_'' can be used to match only on jobs with specific job parameter values, either custom or defined. If multiple values for the same query parameter starting with ''param_'' are supplied, a job is matched if any of its configured values match one of the supplied values. If ''param_'' filters with separate 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 a query like the following to find jobs belonging to the "customer" or "order" groups:
<code>GET http(s)://localhost/rest/jobs[?param_group=customer&param_group=order]</code>

|}

'''Sample Response'''
<pre>
{
"jobs": [
{
"recoveryType": "NONE",
"jobId": 33,
"pickupBufferMinutes": 5,
"nickname": "jobOne",
"folder": "Production/Test", // as of 4.1.0
"interruptable": false, // indicates if job can be interrupted (as of 1.5.1)
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll" : true, // corresponds to chainAll setting on job creation (as of 2.3)
"activeSchedule": {
"jobScheduleId": 34,
"status": "CHAIN_ACTIVE",
"endDate": "2999-12-31T23:59:00-0800",
"effectiveDate": "2013-01-06T14:37:00-0800",
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
"jobClass": "com.carfey.ops.job.maint.JobHistoryCleanupJob",
"revision": 0
},
{
"recoveryType": "CONFLICTED",
"jobId": 35,
"pickupBufferMinutes": 123,
"nickname": "jobTwo",
"interruptable": false
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll" : true, // corresponds to chainAll setting on job creation (as of 2.3)
"activeSchedule": {
"jobScheduleId": 37,
"status": "ENABLED",
"schedule": "@daily",
"scheduleDescription": "At midnight every day" (as of 5.2.0)
"endDate": "2013-01-08T14:34:00-0800",
"effectiveDate": "2013-01-07T14:34:00-0800",
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"revision": 2
}
]
}
</pre>

==GET details of an existing job==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Returns full job information, including all historical schedules and parameter information. Returns a 404 if not found.

'''Sample Response (with inline comments)'''
<pre>
{
"schedules": [
{
"effectiveDate": "2013-01-08T15:15:00-0800",
"endDate": "2031-04-30T07:59:00-0800",
"status": "ENABLED",
"schedule": "* * * * *",
"scheduleDescription": "Every minute every day" (as of 5.2.0)
"jobScheduleId": 35,
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
{
"effectiveDate": "2031-04-30T08:00:00-0800",
"endDate": "2031-04-30T08:00:00-0800",
"schedule": "0 8 30 4 3#5",
"scheduleDescription": "At 8:00AM on the 30th during April on the 3rd Friday" (as of 5.2.0)
"status": "ENABLED",
"jobScheduleId": 2952,
"parameters": [{
"value": "value",
"name": "paramName",
"type": "STRING",
"values": ["value"]
}]
},
{
"effectiveDate": "2015-01-06T15:53:00-0800",
"endDate": "2016-01-06T15:53:00-0800",
"status": "AD_HOC_ACTIVE",
"jobScheduleId": 38
}
],
"currentJobScheduleId": 35, // id of the item in "schedules" which is active right now
"jobClassDescription": "This job cleans up log history beyond the configured age.", // returned only if Job is annotated with @Description
"hosts": [
"host1"
],
"job": {
"jobId": 34,
"revision": 0,
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"nickname": "testCreateWithEffectiveDatesAndParams",
"folder": "Production/Test", // as of 4.1.0
"pickupBufferMinutes": 5,
"recoveryType": "NONE",
"interruptable": false, // indicates if job can be interrupted (as 1.5.1)
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll" : true // corresponds to chainAll setting on job creation (as of 2.3)
},
"parameters": [
{
"name": "level",
"type": "STRING",
"allowMultiple": true,
"required": true,
"values": [ "WARN", "ERROR" ], // as of 2.5, values may contain global parameter references
"defaultValue": "ALL",
"defined": true // true if defined by @Configuration annotation on the job
},
{
"name": "maxAgeDays",
"type": "INTEGER", // see Enumerations above for valid values
"allowMultiple": false,
"required": true,
"values": [ "60" ], // values is always a list for consistency, even when allowMultiple is false
"defaultValue": "120",
"defined": true
}
]
}
</pre>

==POST a new job==

'''<code>POST http(s)://localhost/rest/jobs</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.JobCreationRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Creates a new job with an initial schedule.

'''Sample Request'''
<pre>
{
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"nickname": "testCreateMixedHostsAndParams",
"pickupBufferMinutes": 5,
"recoveryType": "NONE",
"state": "ENABLED",
"schedule": "@daily",
"effectiveDate": "2012-01-10T15:33:00-0800",
"endDate": "2013-01-10T15:33:00-0800",
"hosts": [
"host1",
"host2"
],
"minExecutionDuration": "1s",
"maxExecutionDuration": "5m",
"autoInterrupt" : false, //indicates if a job should be auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false, // as of 2.0
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"customCalendarId": null, // as of 2.0
"parameters": [
{
"name": "level",
"type": "STRING",
"value": "ERROR"
},
{
"name": "level",
"type": "STRING",
"value": "{{globalLevels}}" // as of 2.5, values may contain global parameter references
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobClass || Y || Fully qualified class name of the job. Max 255 chars.
|-
| nickname || Y || Unique nickname for the job. Max 50 chars before 1.5.2, after which it is 255 chars.
|-
| pickupBufferMinutes || Y || Pickup buffer minutes. Integer greater than zero.
|-
| recoveryType || Y || Recovery type as defined in [[Unified_API#Enumerations|Enumerations]].
|-
| state || Y || Initial schedule's job status as defined in [[Unified_API#Enumerations|Enumerations]].
|-
| 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 || As of Obsidian 2.0. 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|| Y || As of Obsidian 2.0. Number of auto retries on non-interrupted execution failure. 0 if 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 || As of Obsidian 2.0. Boolean indicating whether all chained instances are triggered when job is currently running. Otherwise, only one newly chained record is created.
|-
| parameters || Y/N || Zero or more parameter definitions. If a job defines required parameters with the <code>@Configuration</code> 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 [[Unified_API#Enumerations|Enumerations]]. To define multiple values for a single parameter name, simply include multiple items in the parameters collection.
|}

Responses have the same format as GET.

==PUT updates to an existing job==

'''<code>PUT http(s)://localhost/rest/jobs/{jobId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.JobUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Updates a job's configuration. Does not support schedule changes or additions. For schedule changes, see [[#POST a new schedule to an existing job|POST a new schedule to an existing job]].

As of Obsidian 2.3, this endpoint will only update fields that are supplied in the request, similar to a PATCH request. You may update one or more fields as desired.

'''Sample Request'''
<pre>
{
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"nickname": "testCreateMixedHostsAndParams",
"pickupBufferMinutes": 5,
"recoveryType": "NONE",
"hosts": [
"host1",
"host2"
],
"minExecutionDuration": "1s",
"maxExecutionDuration": "5m",
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"chainAll": false,
"parameters": [
{
"name": "level",
"type": "STRING",
"value": "ERROR"
},
{
"name": "level",
"type": "STRING",
"value": "WARN"
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTNable"
! Field || Required? || Notes
|-
| jobClass || N || Fully qualified class name of the job. Max 255 chars.
|-
| nickname || N || Unique nickname for the job. Max 50 chars.
|-
| pickupBufferMinutes || N || Pickup buffer minutes. Integer greater than zero.
|-
| recoveryType || N || Recovery type as defined in [[Unified_API#Enumerations|Enumerations]].
|-
| 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 || As of Obsidian 2.0. Number of auto retries on non-interrupted execution failure. 0 if 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 || As of Obsidian 2.0. 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 <code>@Configuration</code> 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 [[Unified_API#Enumerations|Enumerations]]. To define multiple values for a single parameter name, simply include multiple items in the parameters collection.
|}

Responses have the same format as GET.

==DELETE an existing job==

'''<code>DELETE http(s)://localhost/rest/jobs/{jobId}[?cascade=true]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Deletes a job and its history. Returns a 404 if not found.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| cascade|| N || If set to true, all job conflict and chain definitions for this job will also be deleted. If not set, or set to false, any existing job conflicts or chain definitions will cause the request to fail.
|}

Responses have the same format as GET, and return the final state of the job before the delete.

==GET a list of an existing job's schedules==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}/schedules[?start=1356987599000&end=1357510546000]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobScheduleListing</code>

Returns historical schedules for a job. This is essentially a subset of the primary GET endpoint for an existing job.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| start || N || Start date for the runtimes to preview (inclusive). As of Obsidian 3.7.0.
|-
| end || N || End date for the runtimes to preview (inclusive). Must be after the start time. As of Obsidian 3.7.0.
|}

'''Sample Response'''
<pre>
{
"schedules": [
{
"effectiveDate": "2012-01-06T15:53:00-0800",
"endDate": "2012-08-06T15:53:00-0700",
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"jobScheduleId": 37,
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
{
"effectiveDate": "2015-01-06T15:53:00-0800",
"endDate": "2016-01-06T15:53:00-0800",
"status": "AD_HOC_ACTIVE",
"jobScheduleId": 38
}
],
"jobId": 35,
"currentJobScheduleId": 38
}
</pre>

==POST a new schedule to an existing job==
'''<code>POST http(s)://localhost/rest/jobs/{jobId}/schedules</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleCreationRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobScheduleListing</code>

Creates a new schedule for the job. 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.

'''Sample Request'''
<pre>
{
"state": "ENABLED",
"schedule": "@daily",
"effectiveDate": "2012-01-10T15:33:00-0800",
"endDate": "2013-01-10T15:33:00-0800",
"customCalendarId": 123 // if desired, the custom calendar (as of 2.0)
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| state || Y || The schedule's job status as defined in [[Unified_API#Enumerations|Enumerations]].
|-
| 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 || As of Obsidian 2.0, optional custom calendar for schedule.
|}

Responses have the same format as GET.

==GET a list of configured global parameters ==
'''<code>GET http(s)://localhost/rest/global_parameters</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.GlobalParameterListing</code>

''Available as of version 2.5.''

Lists the configured global parameters

'''Sample Response'''
<pre>
{
"parameters": [
{
"name": "forceSSL",
"type": "BOOLEAN",
"values": ["false"]
},
{
"name": "hostNames",
"type": "STRING",
"values": ["example.com", "test.com"]
}
]
}
</pre>

==PUT updates to global parameters ==

'''<code>PUT http(s)://localhost/rest/global_parameters</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.GlobalParameterUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.GlobalParameterListing</code>

''Available as of version 2.5.''

Replaces the configured global parameters with the supplied values. If the value for parameters is missing or empty, all global parameters will be 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.

'''Sample Request'''
<pre>
{
"parameters": [
{
"name": "forceSSL",
"type": "BOOLEAN",
"values": ["false"]
},
{
"name": "hostNames",
"type": "STRING",
"values": ["example.com", "test.com"]
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| parameters || N || Zero or more parameter definitions. Parameter definitions must have values for "name", "type" and "values", where type is a valid parameter type outlined in Enumerations.
|}

Responses have the same format as GET.

==GET a list of job folders ==
'''<code>GET http(s)://localhost/rest/job_folders</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobFolderListing</code>

''Available as of version 4.1.''

Lists all used job folders in both flat and hierarchical modes.

'''Sample Response'''
<pre>

"flat": [
"Prod",
"Prod/Test",
"QA",
"QA/123/456/789/Test",
"QA/Tester"
],
"hierarchy": [
{
"folder": "Prod",
"children": [
{
"folder": "Test",
"children": [

],
"jobUsingDirectly": true
}
],
"jobUsingDirectly": true
},
{
"folder": "QA",
"children": [
{
"folder": "123",
"children": [
{
"folder": "456",
"children": [
{
"folder": "789",
"children": [
{
"folder": "Test",
"children": [

],
"jobUsingDirectly": true
}
],
"jobUsingDirectly": false
}
],
"jobUsingDirectly": false
}
],
"jobUsingDirectly": false
},
{
"folder": "Tester",
"children": [

],
"jobUsingDirectly": true
}
],
"jobUsingDirectly": true
}
]
}
</pre>

= Runtimes Endpoints (i.e. Job History) =

==GET a list of scheduled runtimes (supports multiple jobs)==
'''<code>GET http(s)://localhost/rest/job_runtimes[?startKey=12345&status=RUNNING&host=host1&quantity=100&sort=asc]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeListing</code>

Returns a list of scheduled or completed job runtimes (i.e. history), optionally filtered by query string parameters. As of Obsidian 3.5, ordering is guaranteed to be in order of scheduled time descending, unless overridden by the <code>sort</code> parameter.

'''Note:''' The <code>nextPageStartKey</code> field in the response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen, or the <code>quantity</code> parameter). To fetch the next page of results, invoke the same endpoint with the <code>startKey</code> query string parameter set to the returned <code>nextPageStartKey</code>.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobId || N || Restricts the search to the selected jobs. Supports multiple values.
|-
| status || N || Restricts the search to the selected statuses. See [[Unified_API#Enumerations|Enumerations]] for valid values. Supports multiple values.
|-
| host || N || If specified, only job runtimes that are assigned to the specified host(s) are included. Supports multiple values.
|-
| folder || N || If specified, only job runtimes with 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.''
|-
| start || N || Start date for the job runtimes to return (inclusive). Defaults to 24 hours ago (before 2.3, it defaulted to the current minute).
|-
| end || 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 <code>nextPageStartKey</code>.
|-
| quantity || N || Indicates the maximum number of results to return. This overrides the <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen. ''As of Obsidian 3.5.0.''
|-
| sort || N || A value of either "asc" or "desc", 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.''
|-
| param_''parameterName'' || N || If specified, values starting with ''param_'' can be used to match only on runtimes with specific runtime parameter values (not job-level parameters). If multiple values for the same query parameter starting with ''param_'' are supplied, a runtime is matched if any of its configured values match one of the supplied values. If ''param_'' filters with separate names are used, each must have a matching value for the runtime to be returned.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"nextPageStartKey" : "2013-01-06T16:05:00-0800 634",
"start": "2013-10-31T23:59:00-0800", // the inclusive search from date (as of 2.3)
"end": "2013-11-01T23:59:00-0800", // the inclusive search to date (as of 2.3)
"runtimes": [
{
"runtimeOrdinal": 0, //as of 3.8.0
"heartbeatTime": "2013-01-06T16:05:00-0800",
"jobRuntimeId": 8,
"adHoc": false,
"pickupTime": "2013-01-06T16:04:00-0800",
// present when this job was resubmitted from another job runtime
"resubmissionSource": {
"jobRuntimeId": 10,
"status": "READY",
"scheduledTime": "2013-01-06T16:06:00-0800"
},
"endTime": "2013-01-06T16:05:00-0800",
"revision": 1,
"resubmission": false,
"scheduledTime": "2013-01-06T16:04:00-0800",
"autoRetryCount": 2, // present if this job was auto-retried from a failure (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"status": "FAILED",
"error": { // present if the job fails
"message": "arg was null",
"detail": "stack trace..."
},
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 43,
"nickname": "jobThatChainsOthers",
"interruptable": false, // indicates if job can be interrupted (as of 1.5.1)
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"revision" : 0, // Present as of 2.3
"activeSchedule": {
"jobScheduleId": 44,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T17:44:00-0800",
"effectiveDate": "2013-01-06T16:03:00-0800",
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
"jobClass": "someclass"
},
// optional interruption element if job execution was interrupted (as of version 1.5.1)
"interruption" : {
"requester": "userName",
"requestTime": "2013-01-06T16:04:54-0800",
"interruptTime":"2013-01-06T16:04:56-0800" // this time will be set if successfully interrupted (otherwise not present)
},
// contains a list of job runtimes that were chained from this job runtime
"chainTargets": [
{
"trigger": true,
"detail": null, // if trigger is false, this will contains details of why it didn't trigger
"jobRuntimeId": 9,
"job": {
"jobId": 44,
"nickname": "jobThatGetsChained"
},
"scheduledTime": "2013-01-06T16:05:00-0800"
}
],
"executionType": "Resubmission" // when present, indicates it executed as a "Resubmission", "Chained", or "Ad Hoc" job
},
{
"runtimeOrdinal": 0, //as of 3.8.0
"jobRuntimeId": 9,
"adHoc": false,
"revision": 0,
"resubmission": false,
"scheduledTime": "2013-01-06T16:05:00-0800",
"status": "READY",
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 44,
"nickname": "jobThatGetsChained",
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"revision" : 0, // Present as of 2.3
"activeSchedule": {
"jobScheduleId": 45,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T17:44:00-0800",
"effectiveDate": "2013-01-06T16:03:00-0800"
},
"jobClass": "someclass2"
},
// when present, this includes this runtime was chained as a result of another job runtime
"chainSource": {
"trigger": true,
"detail": "chained it",
"jobRuntimeId": 8,
"job": {
"jobId": 43,
"nickname": "jobThatChainsOthers"
},
"scheduledTime": "2013-01-06T16:04:00-0800"
},
"chainTargets": [ ],
"executionType": "Chained"
}
]
}
</pre>

==GET a list of a job's scheduled runtimes==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}/runtimes</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeListing</code>

This endpoint is equivalent the other runtime endpoint (see preceding item) with a URL like the following: <code>GET http(s)://localhost/rest/job_runtimes?jobId={jobId}</code>

Other than the jobId, all other query string parameters from the multi-job endpoint are supported.

==POST a new scheduled runtime for an existing job (i.e. submit a one-time or ad hoc run)==
'''<code>POST http(s)://localhost/rest/jobs/{jobId}/runtimes</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeSubmissionRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeSubmissionResult</code>

Allows for submission of an ad hoc job run (executed immediately), or a one-time run scheduled for a later time.

'''Note:''' The job must be in a valid state to allow for execution (i.e. <code>UNSCHEDULED_ACTIVE</code>, <code>ENABLED</code>, or <code>AD_HOC_ACTIVE</code>).

'''Sample Request'''
<pre>
{
"scheduledTime": "2013-02-06T16:40:00-0800",
// Optional. Available as of 2.1.1. Parameters supplied for scheduled runtime which will be available to the job when executing.
"parameters": [
{
"name": "level",
"type": "STRING",
"value": "ERROR"
},
{
"name": "level",
"type": "STRING",
"value": "WARN"
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! 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 parameter type outlined in [[Unified_API#Enumerations|Enumerations]]. 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.
|}

'''Note:''' A <code>jobRuntimeId</code> is only returned in the case of an ad hoc run.

'''Sample Response (with inline comments) '''
<pre>
{
"jobRuntimeId": 2, // only returned for ad hoc submission (no scheduled time supplied)
"jobId": 36,
"scheduledTime": "2013-01-06T16:37:00-0800"
}
</pre>

==GET details of an existing scheduled (or completed) job runtime==
'''<code>GET http(s)://localhost/rest/job_runtimes/{jobRuntimeId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeResult</code>

Returns detailed information for the requested job runtime. Responses will contain all the same details as a single record from a <code>/job_runtimes</code> GET request, with the addition of the <code>output</code> and <code>parameters</code> elements, which contain saved job results and runtime-specific parameters respectively.

'''Sample Response'''
<pre>
{
"runtime": {
"heartbeatTime": "2013-01-06T16:27:00-0800",
"jobRuntimeId": 2,
"adHoc": false,
"pickupTime": "2013-01-06T16:26:00-0800",
"endTime": "2013-01-06T16:27:00-0800",
"revision": 6,
"resubmission": false,
"scheduledTime": "2013-01-06T16:26:00-0800",
"runningHost": "test3",
"status": "FAILED",
"interruptable": false, // indicates if job can be interrupted (as of 1.5.1)
"autoRetryCount": 2, // present if this job was auto-retried from a failure (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 36,
"nickname": "testWithOutput",
"activeSchedule": {
"jobScheduleId": 37,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T18:06:00-0800",
"effectiveDate": "2013-01-06T16:25:00-0800",
"customCalendarId": 123 // if configured, the custom calendar for this job (as of 2.0)
},
"jobClass": "someclass"
},
"chainSource": null,
"chainTargets": [

],
"output": [
{
"jobRuntimeResultId": 4,
"name": "testname",
"value": "testvalue",
"valueType": "java.lang.String"
},
{
"jobRuntimeResultId": 5,
"name": "testname",
"value": "testvalue2",
"valueType": "java.lang.String"
},
{
"jobRuntimeResultId": 6,
"name": "testname2",
"value": "testvalue3",
"valueType": "java.lang.String"
}
],
// Parameters specified for ad-hoc or one-time runtime (as of 2.1.1). This does not include parameters defined at the job level.
"parameters": [
{
"name": "level",
"type": "STRING", // see Enumerations above for valid values
"values": [ "WARN", "ERROR" ]
},
{
"name": "maxAgeDays",
"type": "INTEGER",
"values": [ "60" ] // values is always a list for consistency
}
]
}
}
</pre>

==DELETE a future scheduled runtime ==

''Since Obsidian 4.7.0''

'''<code>DELETE http(s)://localhost/rest/jobs/{jobId}/runtimes</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.history.OneTimeRunDeleteRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.OneTimeDeletionResult</code>

Allows for deletion of a future scheduled ad hoc job run.

'''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.

'''Sample Request'''
<pre>
{
"scheduledTime": "2021-02-01T19:00:00-0800",
// Optional if only one instance scheduled at the specified time.
"runtimeOrdinal": 2
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| scheduledTime|| Y || The scheduled time, when the job was previously requested to be run. Must yet be in the future.
|-
| runtimeOrdinal|| 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.
|}

'''Sample Response (with inline comments) '''
<pre>
{
"jobId": 2,
"jobRuntimeId": 36389,
"scheduledTime": "2021-02-01T19:00:00-0800"
}
</pre>

==POST a resubmission request for a failed job runtime==
'''<code>POST http(s)://localhost/rest/job_runtimes/{jobRuntimeId}/resubmissions</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeResubmissionResult</code>

Allows for resubmission of a failed job runtime.

'''Sample Response '''
<pre>
{
"resubmission": {
"revision": 0,
"jobId": 35,
"resubmission": true,
"runtimeOrdinal": 0, // as of 3.8.0
"scheduledTime": "2013-01-06T16:49:00-0800",
"status": "READY",
"jobRuntimeId": 2
}
}
</pre>

==POST an interruption request to kill a running job ==
'''<code>POST http(s)://localhost/rest/job_runtimes/{jobRuntimeId}/interrupts</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.JobInterruptResult</code>

''Available as of version 1.5.1.''

Allows for interruption of a currently running job runtime. 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 it is capable of shutting down. Not all jobs can be terminated. See [[Implementing_Jobs#Interruptable_Jobs|Interruptable Jobs]] for full details.

'''Sample Response '''
<pre>
{
"interruption": {
"requester": "apiUserName",
"requestTime": "2013-01-06T16:49:00-0800"
}
}
</pre>

== POST async results ==

'''<code>POST http(s)://localhost/rest/job_runtimes/{jobRuntimeId}/async_results</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.history.AsyncJobRuntimeResultsRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeResult</code>

''Available as of version 4.5.0.''

Used to indicate the final status of an Async job. This request can only be made once successfully. See [[Implementing_Jobs#Async_Jobs | Async Job]] for full details.

'''Sample Request '''
<pre>
{
"asyncJobRuntimeStatus": "FAILED",
"resultTime": "2018-03-09T22:04:08-0500",
"jobResults": {
"Job Failure Description": "Could not acquire locks on all resources. Tables [reference_object,reference_entity] were not optimized."
},
"resultException": {"detailMessage":"Lock Not Acquired","stackTrace":[{"declaringClass":"com.carfey.finance.OptimizeDatabase","methodName":"optimize","fileName":"OptimizeDatabase.java","lineNumber":132},{"declaringClass":"com.carfey.ops.job.OptimizeDatabase","methodName":"acquireLocks","fileName":"OptimizeDatabase.java","lineNumber":445}],"suppressedExceptions":[]}
}
</pre>

'''Sample Response '''
<pre>
{
"runtime": {
"runningHost": "obsidian-production",
"runtimeOrdinal": 0,
"output": [
{
"name": "Job Failure Description",
"value": "Could not acquire locks on all resources. Tables [reference_object,reference_entity] were not optimized.",
"valueType": "java.lang.String",
"jobRuntimeResultId": 551
}
],
"pickupTime": "2018-03-09T07:45:30-0500",
"adHoc": false,
"heartbeatTime": "2018-03-09T07:46:59-0500",
"lastUpdatedBy": "REST: webServiceCallback",
"scheduledTime": "2018-03-09T07:45:00-0500",
"revision": 603,
"resubmission": false,
"job": {
"hostPreference": false,
"autoInterrupt": false,
"pickupBufferMinutes": 2,
"recoveryType": "NONE",
"autoRetryCount": 0,
"jobClass": "com.carfey.ops.job.WebServiceJob",
"nickname": "Finance DB Optimization Service",
"lastUpdatedBy": "devops",
"activeSchedule": {
"schedule": "@daily",
"lastUpdatedBy": "devops",
"lastUpdatedDate": "2018-03-08T23:57:37-0500",
"createdDate": "2018-03-08T23:57:37-0500",
"endDate": "2999-12-31T23:59:00-0500",
"createdBy": "devops",
"jobScheduleId": 152,
"effectiveDate": "2018-03-08T23:58:00-0500",
"status": "ENABLED"
},
"interruptable": false,
"autoRetryInterval": 0,
"revision": 201,
"jobId": 1,
"lastUpdatedDate": "2018-03-08T23:57:37-0500",
"createdDate": "2018-03-08T14:47:33-0500",
"createdBy": "devops",
"autoRetryIntervalExponent": false,
"chainAll": false
},
"parameters": [],
"status": "FAILED",
"chainTargets": [],
"error": {
"exceptionClass": "java.lang.Exception",
"detail": "java.lang.Exception: Lock Not Acquired\r\n\tat com.carfey.finance.OptimizeDatabase.optimize(OptimizeDatabase.java:132)\r\n\tat com.carfey.ops.job.OptimizeDatabase.acquireLocks(OptimizeDatabase.java:445)\r\n",
"message": "Lock Not Acquired"
},
"jobRuntimeId": 756,
"lastUpdatedDate": "2018-03-09T21:50:57-0500",
"createdDate": "2018-03-09T07:44:01-0500",
"createdBy": "JobQueuer",
"endTime": "2018-03-09T22:04:08-0500"
}
}
</pre>

==GET a list of the latest scheduled runtime by job (supports multiple jobs)==
'''<code>GET http(s)://localhost/rest/job_runtimes/latest[?startKey=12345&host=host1&quantity=100&sort=asc]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.JobDashboardListing</code>

''Available as of version 4.10.2.''

Returns a list of the latest job runtimes by job(i.e. history), optionally filtered by query string parameters. Ordering is guaranteed to be in order of scheduled time descending, unless overridden by the <code>sort</code> parameter.

'''Note:''' The <code>nextPageStartKey</code> field in the response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen, or the <code>quantity</code> parameter). To fetch the next page of results, invoke the same endpoint with the <code>startKey</code> query string parameter set to the returned <code>nextPageStartKey</code>.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobId || N || Restricts the search to the selected jobs. Supports multiple values. ''Do not combine with nickname.''
|-
| nickname || N || If specified, only jobs matching the supplied nickname 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%". Supports multiple values. ''Do not combine with jobId.''
|-
| host || N || If specified, only the latest job runtimes that are assigned to the specified host(s) are included. Supports multiple values.
|-
| folder || N || If specified, only job runtimes with 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 <code>nextPageStartKey</code>.
|-
| quantity || N || Indicates the maximum number of results to return. This overrides the <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen.
|-
| sort || N || A value of either "asc" or "desc", which controls the ordering of returned results. In all cases, the job scheduled time is used to sort results.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"nextPageStartKey" : "2013-01-06T16:05:00-0800 634",
"start": "2013-10-31T23:59:00-0800",
"end": "2013-11-01T23:59:00-0800",
"runtimes": [
{
"runtimeOrdinal": 0,
"heartbeatTime": "2013-01-06T16:05:00-0800",
"jobRuntimeId": 8,
"adHoc": false,
"pickupTime": "2013-01-06T16:04:00-0800",
// present when this job was resubmitted from another job runtime
"resubmissionSource": {
"jobRuntimeId": 10,
"status": "READY",
"scheduledTime": "2013-01-06T16:06:00-0800"
},
"endTime": "2013-01-06T16:05:00-0800",
"revision": 1,
"resubmission": false,
"scheduledTime": "2013-01-06T16:04:00-0800",
"autoRetryCount": 2, // present if this job was auto-retried from a failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"status": "FAILED",
"error": { // present if the job fails
"message": "arg was null",
"detail": "stack trace..."
},
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 43,
"nickname": "jobThatChainsOthers",
"interruptable": false, // indicates if job can be interrupted
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"revision" : 0,
"activeSchedule": {
"jobScheduleId": 44,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T17:44:00-0800",
"effectiveDate": "2013-01-06T16:03:00-0800",
"customCalendarId": 123 // if configured, the custom calendar
},
"jobClass": "someclass"
},
// optional interruption element if job execution was interrupted
"interruption" : {
"requester": "userName",
"requestTime": "2013-01-06T16:04:54-0800",
"interruptTime":"2013-01-06T16:04:56-0800" // this time will be set if successfully interrupted (otherwise not present)
},
// contains a list of job runtimes that were chained from this job runtime
"chainTargets": [
{
"trigger": true,
"detail": null, // if trigger is false, this will contains details of why it didn't trigger
"jobRuntimeId": 9,
"job": {
"jobId": 44,
"nickname": "jobThatGetsChained"
},
"scheduledTime": "2013-01-06T16:05:00-0800"
}
],
"executionType": "Resubmission" // when present, indicates it executed as a "Resubmission", "Chained", or "Ad Hoc" job
},
{
"runtimeOrdinal": 0,
"jobRuntimeId": 9,
"adHoc": false,
"revision": 0,
"resubmission": false,
"scheduledTime": "2013-01-06T16:05:00-0800",
"status": "READY",
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 44,
"nickname": "jobThatGetsChained",
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"revision" : 0,
"activeSchedule": {
"jobScheduleId": 45,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T17:44:00-0800",
"effectiveDate": "2013-01-06T16:03:00-0800"
},
"jobClass": "someclass2"
},
// when present, this includes this runtime was chained as a result of another job runtime
"chainSource": {
"trigger": true,
"detail": "chained it",
"jobRuntimeId": 8,
"job": {
"jobId": 43,
"nickname": "jobThatChainsOthers"
},
"scheduledTime": "2013-01-06T16:04:00-0800"
},
"chainTargets": [ ],
"executionType": "Chained"
}
]
}
</pre>

= Runtime Preview Endpoints =

==GET a list of runtime previews (supports multiple jobs)==
'''<code>GET http(s)://localhost/rest/job_runtimes/previews[?jobId=1&jobId=2&start=1356987599000&end=1357510546000]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.RuntimePreviewListing</code>

Returns a preview of runtimes, optionally filtered based on the supplied query string parameters. This 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 response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen). If you are hitting this condition, try limiting your date range or other parameters.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobId || N || Restricts the preview to the selected jobs. Supports multiple values.
|-
| start || N || Start date for the runtimes to preview (inclusive). Defaults to the current minute.
|-
| end || N || End date for the runtimes to preview (inclusive). Defaults to a day after the start time. Must be after the start time.
|}

'''Sample Response'''
<pre>
{
"capped": false,
"start": "2013-10-31T23:59:00-0800", // the inclusive search from date (as of 2.3)
"end": "2013-11-01T23:59:00-0800", // the inclusive search to date (as of 2.3)
"runtimes": [
{
"jobId": 36,
"nickname": "jobOne",
"schedule": "* * * * *",
"scheduleDescription": "Every minute every day", (as of 5.2.0)
"scheduledTime": "2013-01-06T15:31:00-0800",
"scheduleEffectiveDate": "2013-01-06T13:50:00-0800",
"scheduleEndDate": "2999-12-31T23:59:00-0800"
},
{
"jobId": 37,
"nickname": "jobTwo",
"schedule": "* * * * *",
"scheduleDescription": "Every minute every day", (as of 5.2.0)
"scheduledTime": "2013-01-06T15:30:00-0800",
"scheduleEffectiveDate": "2013-01-06T13:50:00-0800",
"scheduleEndDate": "2999-12-31T23:59:00-0800"
}
]
}
</pre>

==GET a list of runtime previews for an existing job==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}/runtimes/previews</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.RuntimePreviewListing</code>

This endpoint is equivalent the other runtime preview endpoint (see preceding item) with a URL like the following:
<code>GET http(s)://localhost/rest/job_runtimes/previews?jobId={jobId}</code>

Other than the <code>jobId</code>, all other query string parameters from the multi-job endpoint are supported.

= Job Chain Endpoints =

''As of Obsidian 2.4.''

==GET a list of job chains==
'''<code>GET http(s)://localhost/rest/chains[?active=true&sourceJobId=123&targetJobId=456]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChainListing</code>

Returns a list of configured job chains, optionally filtered by query string parameters.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! 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.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"jobChains": [
{
"jobChainId": 1,
"schedule": "* * * * *", // if specified
"scheduleDescription": "Every minute every day", (as of 5.2.0)
"active": true,
"sourceJob": {
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Order Export Job",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.example.OrderExportJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 2
},
"target": {
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
},
"triggerStates": ["FAILED","CONDITIONAL"],
"resultConditions": [
{
"variableName": "exportFile",
"operator": "EXISTS",
"values": [] // empty list when values do not apply
},
{
"variableName":"fileSize",
"operator": "GREATER_THAN",
"values": ["0"] // list with one element when multiples aren't applicable
},
{
"variableName": "status",
"operator": "IN",
"values": ["EXPORTED", "ZIPPED"]
}
]
},
{
"jobChainId": 2,
"active": false,
"sourceJob": {
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Customer Export Job",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.example.CustomerExportJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 2
},
"target": {
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
},
"triggerStates": ["COMPLETED"],
"resultConditions": [] // only populated when CONDITIONAL state is used
}
]
}
</pre>

==GET details of an existing job chain==
'''<code>GET http(s)://localhost/rest/chains/{jobChainId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChain</code>

Returns details of a configured job chain, or a 404 if not found. Contains the same set of fields as the job chain listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"jobChainId": 1,
"schedule": "* * * * *", // if specified
"scheduleDescription": "Every minute every day", (as of 5.2.0)
"active": true,
"sourceJob": {
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Order Export Job",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.example.OrderExportJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 2
},
"target": {
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
},
"triggerStates": ["FAILED", "CONDITIONAL"],
"resultConditions": [ // only populated when CONDITIONAL state is used
{
"variableName": "exportFile",
"operator": "EXISTS",
"values": [] // empty list when values do not apply
},
{
"variableName": "fileSize",
"operator": "GREATER_THAN",
"values": ["0"] // list with one element when multiples aren't applicable
},
{
"variableName": "status",
"operator": "IN",
"values": ["EXPORTED", "ZIPPED"]
}
]
}
</pre>

==POST a new job chain==

'''<code>POST http(s)://localhost/rest/chains</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.JobChainUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChain</code>

Creates a new job chain.

'''Sample Request'''
<pre>
{
"sourceJobId": 12,
"targetJobId": 54,
"schedule": "* * * * *", //optional
"active": true,
"triggerStates": ["CONDITIONAL", "FAILED"],
"resultConditions": [ // only supplied when CONDITIONAL state is supplied
{
"variableName": "exportFile",
"operator":"EXISTS" // no "values" field required for EXISTS or NOT_EXISTS
},
{
"variableName": "fileSize",
"operator": "GREATER_THAN",
"values":["0"] // in this case, only one value allowed
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! 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.
|-
| active || Y || Flag to indicate whether the chain is active or not.
|-
| triggerStates || Y || One or more job chain states as defined in [[Unified_API#Enumerations|Enumerations]]. Note that <code>CONDITIONAL</code> and <code>COMPLETED</code> types cannot be used on the same chain.
|-
| resultConditions || Y/N || Conditions based on job results that apply to the <code>CONDITIONAL</code> 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 <code>variableName</code>, an <code>operator</code> as defined in [[Unified_API#Enumerations|Enumerations]], and for most operators, a list of <code>values</code>. The <code>EXISTS</code> and <code>NOT EXISTS</code> operators do not use values, so they must not be supplied. Operators <code>IN</code> and <code>NOT IN</code> support one or more values, and all other operators accept a single value in the <code>values</code> list. Values for this field map to bean class <code>com.carfey.ops.api.enums.JobChainConditionOperator</code>.
|}

Responses have the same format as GET.

==PUT updates to an existing job chain==

'''<code>PUT http(s)://localhost/rest/chains/{jobChainId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.JobChainUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChain</code>

Updates an existing job chain. Returns a 404 if not found.

Requests and responses have the same format as POST.

==DELETE an existing job chain==
''Available as of version 2.6.''

'''<code>DELETE http(s)://localhost/rest/chains/{jobChainId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChain</code>

Deletes a job chain. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the job chain before the delete.

= Job Conflict Endpoints =

''As of Obsidian 2.4.

==GET a list of job conflicts ==
'''<code>GET http(s)://localhost/rest/conflicts</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.ConflictListing</code>

Lists the configured job conflicts. Non-conflicted jobs are also included in the return value.

Conflicting jobs are returned in priority order within the same list. Multiple conflicting job sets can be returned in the <code>conflictJobs</code> field.

'''Sample Response (with inline comments)'''
<pre>
{
"conflictJobs": [
[
{
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set A - 1",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"folder": "Production/Test", // as of 4.1.0
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 2
},
{
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set A - 2",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
}
],
[
{
"jobId": 53,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set B - 1",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 2
},
{
"jobId": 54,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set B - 2",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
},
{
"jobId": 55,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set B - 3",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
}
],
],
"nonConflictJobs": [
{
"jobId": 56,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Non-Conflicted Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
}
]
}
</pre>

==PUT updates to job conflicts ==

'''<code>PUT http(s)://localhost/rest/conflicts</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.ConflictUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Replaces the current job conflict configuration with the supplied configuration.

'''Sample Request'''
<pre>
{

// Note that if Job 5 and Job 2 are scheduled for the same minute, Job 5 will run first as it is selected as the highest priority job from the first conflict set.
// When priority is significant and varies across different sets, ensure your conflict sets are in the desired order.
"conflicts": [
[1, 2, 3, 5], // Job 1 has highest priority
[2, 5, 4] // Job 2 also conflicts with 4 & 5.
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| conflicts || N || A list of lists containing job IDs. Each inner list 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.
|}

Responses have the same format as GET.

==GET a list of conflicts for a specific job==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}/conflicts</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobConflictListing</code>

Lists all jobs that conflict with the requested job.

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.

'''Sample Response (with inline comments)'''
<pre>
{
"conflictJobs": [
{
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Conflict A",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 2
},
{
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Conflict B",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
},
{
"jobId": 56, // this is the requested job
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Requested Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
}
],
"job": {
"jobId": 56,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Requested Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
}
}
</pre>

= Scheduling Hosts Endpoints =

==GET a list of known scheduling hosts==
'''<code>GET http(s)://localhost/rest/hosts</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostListing</code>

Returns a list of known hosts. These are either running or recently shut down abnormally. Hosts that shut down normally are unregistered on shutdown. Note that returned IDs are transient and may change after startup or shutdown or a node. Heartbeat time indicates when the server last performed the heartbeat health check against the database.

'''Sample Response'''
<pre>
{
"hosts": [
{
"id": 32,
"name": "production1",
"heartbeatTime": "2013-01-05T21:15:59-0800",
"enabled": true
},
{
"id": 33,
"name": "production2",
"heartbeatTime": "2013-01-05T21:15:59-0800",
"enabled": false
}
]
}
</pre>

==GET details on an existing scheduling host==
'''<code>GET http(s)://localhost/rest/hosts/{id}</code>'''

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostDetail</code>

Returns the requested host, or a 404 if not found.

'''Note:''' The name field corresponds to the host name, as described [[Getting_Started#Setting_Host_Names|here]]. Explicit host names should be set if you intend to rely known host names in this endpoint. Heartbeat time indicates when the server last performed the heartbeat health check against the database.

'''Sample Response'''
<pre>
{
"host": {
"id": 33,
"name": "production1",
"heartbeatTime": "2013-01-05T21:18:18-0800",
"licenceLeaseExpiryUtc": "2017-06-15 01:36:06",
"enabled": true,
"licenceStatus": "internet_node_verified",
"licenceLeaseExpiryUtc": "2017-06-15 02:15:42"
}
}
</pre>

==GET health details on an existing scheduling host==
''As of Obsidian 6.3.0''

<code>GET http(s)://localhost/rest/hosts/{id}/health</code>

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}/health</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostDetail</code>

The intended use of this endpoint is as a health check. This endpoint response is to be parsed to evaluate health as it will include full health details with 200 response code if all is well, and a 400 if any part of system is unhealthy including license verification, job queuer and/or job spawner.

'''Note:''' The name field corresponds to the host name, as described [[Getting_Started#Setting_Host_Names|here]]. Explicit host names should be set if you intend to rely known host names in this endpoint. Heartbeat time indicates when the server last performed the heartbeat health check against the database.

'''Sample Response'''
<pre>
{
"host": {
"id": 243,
"name": "obsidian.production",
"heartbeatTime": "2025-07-17T20:28:34Z",
"licenceLeaseExpiryUtc": "2025-07-18 01:27:14",
"enabled": true,
"licenceStatus": "internet_node_verified",
"jobQueuerStatus": "healthy",//or laggy,delayed,unresponsive
"jobQueuerUpdateTimeUtc": "2025-07-17 20:28:28",
"jobSpawnerStatus": "healthy"//or laggy,delayed,unresponsive
"jobSpawnerUpdateTimeUtc": "2025-07-17 20:28:20",
"createdDate": "2025-07-17T19:27:13Z",
"createdBy": "SchedulerStarter.startUp",
"lastUpdatedBy": "SchedulerStarter.designator",
"lastUpdatedDate": "2025-07-17T20:28:34Z",
}
}
</pre>

==GET licence details on an existing scheduling host==
'''<code>GET http(s)://localhost/rest/hosts/{id}/licence_health</code>'''        ''Prior to 4.5'': '''<code>GET http(s)://localhost/rest/hosts/licenceHealthCheck/{id}</code>'''

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}/licence_health</code>'''        ''Prior to 4.5'': '''<code>GET http(s)://localhost/rest/hosts/licenceHealthCheck/names/{name}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostDetail</code>

The intended use of this endpoint is as a health check. This endpoint is identical to the [[REST_Endpoints#GET_details_on_an_existing_scheduling_host |GET details on an existing scheduling host]] above, with the exception that it will return a 400 if the licence has expired or is in some way invalid.

Returns the requested host with licence status, or a 404 if not found, or a 400 if the licence is invalid or its lease has expired.

'''Note:''' The name field corresponds to the host name, as described [[Getting_Started#Setting_Host_Names|here]]. Explicit host names should be set if you intend to rely known host names in this endpoint. Heartbeat time indicates when the server last performed the heartbeat health check against the database.

'''Sample Response'''
<pre>
{
"host": {
"id": 33,
"name": "production1",
"heartbeatTime": "2013-01-05T21:18:18-0800",
"licenceLeaseExpiryUtc": "2017-06-15 01:36:06",
"enabled": true,
"licenceStatus": "internet_node_verified",
"licenceLeaseExpiryUtc": "2017-06-15 02:15:42"
}
}
</pre>

==PUT updates to an existing scheduling host==
'''<code>PUT http(s)://localhost/rest/hosts/{id}</code>'''

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.host.HostUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostDetail</code>

Updates the enabled status of the requested host, or a 404 if not found. This endpoint is used to enable or disable scheduling nodes.

'''Note:''' The name field corresponds to the host name, as described [[Getting_Started#Setting_Host_Names|here]]. Explicit host names should be set if you intend to rely known host names in this endpoint.

'''Sample Request'''
<pre>
{
"enabled": false
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| enabled || Y || Should this host should be enabled?
|}

Responses have the same format as GET.

= Event Hooks Endpoints =
''As of Obsidian 5.4.0''

==GET event hooks==
'''<code>GET http(s)://localhost/rest/event_hooks</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.EventHookListing</code>

Returns all event hooks across the cluster.

'''Sample Response'''
<pre>
{
"hostEventHooks": [
{
"host": "prod-obsidian-RG1",
"eventHooks": [
{
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"name": "SlackEventHook",
"status": "INACTIVE",
"registrationTime": "2024-06-01T15:52:07-0400",
"heartbeat": "2024-06-01T16:52:09-0400",
"markedInactiveAt": "2024-06-01T16:52:09-0400" --if applicable
}
]
},
{
"host": "prod-obsidian-HL1",
"eventHooks": [
{
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"name": "SlackEventHook",
"status": "ACTIVE",
"registrationTime": "2024-06-01T18:08:11-0400",
"heartbeat": "2024-06-01T19:01:37-0400"
}
]
}
]
}
</pre>

==GET event hooks on host==

'''<code>GET http(s)://localhost/rest/hosts/{id}/event_hooks</code>'''

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}/event_hooks</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.EventHookListing</code>

Returns all event hooks for the given host.

'''Sample Response'''
<pre>
{
"hostEventHooks": [
{
"host": "prod-obsidian-RG1",
"eventHooks": [
{
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"name": "SlackEventHook",
"status": "INACTIVE",
"registrationTime": "2024-06-01T15:52:07-0400",
"heartbeat": "2024-06-01T16:52:09-0400",
"markedInactiveAt": "2024-06-01T16:52:09-0400" --if applicable
}
]
}
]
}
</pre>

==POST event hook pause or resume ==
''As of Obsidian 5.5.0''

'''<code>POST http(s)://localhost/rest/event_hooks</code>'''

Alternate (by host id): POST http(s)://localhost/rest/hosts/{id}/event_hooks

Alternate (by host name): POST http(s)://localhost/rest/hosts/names/{name}/event_hooks

'''Request bean class:''' <code>com.carfey.ops.api.bean.host.UpdateEventHookRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.EventHookListing</code>

Requests a specific event hook on a specific host to either Pause or Resume

'''Sample Request'''

<pre>
{
"hostName": "obsidian-prod-1",//only used when using non host-specific event_hooks endpoint
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"eventHookName": "SlackEventHook"
"eventHookAction": "PAUSE"
}
</pre>

'''Sample Response'''
<pre>
{
"hostEventHooks": [
{
"host": "obsidian-prod-1",
"eventHooks": [
{
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"name": "SlackEventHook",
"status": "ACTIVE",
"registrationTime": "2024-06-01T15:52:07-0400",
"heartbeat": "2024-06-01T16:52:09-0400",
"requestedStatus" : "PAUSE",
"requestedBy" : "carey-ops"
}
]
}
]
}
</pre>

= Custom Calendar Endpoints =

''As of Obsidian 2.0. Format revised in 2.3.''

The following endpoints allow for managing of [[Job_Features#Custom_Calendars|Custom Calendars]].

==GET a list of custom calendars==
'''<code>GET http(s)://localhost/rest/calendars</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendarListing</code>

Returns a list of custom calendars.

'''Sample Response'''
<pre>
{
"customCalendars": [
{
"revision": 0,
"dates": ["2013-01-01", "2013-02-18", "2013-04-01", "2013-05-20"],
"name": "Corporate Holidays 2013",
"customCalendarId": 1
},
{
"revision": 0,
"dates": ["2013-01-01", "2013-02-18", "2013-04-01", "2013-05-20"],
"name": "Corporate Holidays 2014",
"customCalendarId": 2
}
]
}
</pre>
==GET details on an existing custom calendar==
'''<code>GET http(s)://localhost/rest/calendars/{id}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendar</code>

''As of Obsidian 2.3.''

Returns the requested custom calendar, or a 404 if not found..

'''Sample Response'''
<pre>
{
"revision": 0,
"dates": ["2013-01-01", "2013-02-18", "2013-04-01", "2013-05-20"],
"name": "Corporate Holidays 2013",
"customCalendarId": 1
}
</pre>

==POST a new custom calendar ==
'''<code>POST http(s)://localhost/rest/calendars/</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendarUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendar</code>

Updates the name and dates of the requested calendar, or a 404 if not found.

'''Sample Request'''
<pre>
{
"name": "Cal1",
"dates": ["2016-10-14" ,"2018-06-14"],
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| name|| Y || Calendar name
|-
| dates|| Y || Dates to exclude
|}

Responses have the same format as GET.

==PUT updates to an existing custom calendar==
'''<code>PUT http(s)://localhost/rest/calendars/{id}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendarUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendar</code>

Updates the name and dates of the requested calendar, or a 404 if not found.

'''Sample Request'''
<pre>
{
"name": "Cal2",
"dates": ["2018-06-13","2016-10-13"]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| name|| Y || Calendar name
|-
| dates|| Y || Dates to exclude
|}

Responses have the same format as POST.

==DELETE an existing custom calendar==

''Available as of version 3.0.''

'''<code>DELETE http(s)://localhost/rest/calendars/{id}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendar</code>

Deletes a custom calendar. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the calendar before the delete.

= Subscriber Endpoints =

''As of Obsidian 3.0.''

==GET a list of subscribers==
'''<code>GET http(s)://localhost/rest/subscribers</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.SubscriberListing</code>

Returns a list of configured notification subscribers.

'''Sample Response (with inline comments)'''
<pre>
{
"subscribers": [
{
"id": 1,
"emailAddress": "test@example.com",
"active": true,
"generalSubscriptions": [
{
"category": "QUEUE",
"level": "ERROR",
"active": true,
},
{
"category": "JOB",
"level": "ERROR",
"active": true,
"job" : { // only exists when the subscription applies to a specific job
"recoveryType": "NONE",
"jobId": 1,
"pickupBufferMinutes": 2,
"nickname": "Cleanup Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.JobHistoryCleanupJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"chainAll": false,
"hostPreference": true,
"revision": 52
}
}
],
"jobExecutionSubscriptions": [
{
"allJobs": true,
"jobs": [], // always empty when allJobs is true
"triggerStates": [ "DIED", "FAILED", "RECOVERY" ],
"resultConditions": [], // present when CONDITIONAL triggerState is used
"active": false
},
{
"allJobs": false,
"jobs": [
{
"recoveryType": "NONE",
"jobId": 1,
"pickupBufferMinutes": 2,
"nickname": "Cleanup Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.JobHistoryCleanupJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"chainAll": false,
"hostPreference": true,
"revision": 52
}
],
"triggerStates": [ "CONDITIONAL" ],
"resultConditions": [
{
"variableName": "cleanupState",
"operator": "EQUALS",
"values": [ "incomplete" ] // depending on the operator, values may be empty, have 1 value, or multiple.
},
{
"variableName": "warnings",
"operator": "EXISTS",
"values": []
}
],
"active": true
}
]
},
{
"id": 2,
"emailAddress": "inactive@example.com",
"active": false,
"generalSubscriptions": [],
"jobExecutionSubscriptions": []
}
]
}
</pre>

==GET details of an existing subscriber==
'''<code>GET http(s)://localhost/rest/subscribers/{subscriberId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Subscriber</code>

Returns details of an existing subscriber, or a 404 if not found. Contains the same set of fields as the listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 1,
"emailAddress": "test@example.com",
"active": true,
"generalSubscriptions": [
{
"active": true,
"category": "QUEUE",
"level": "ERROR"
}
],
"jobExecutionSubscriptions": [
{
"active": false,
"allJobs": true,
"jobs": [],
"triggerStates": [ "DIED", "FAILED", "RECOVERY" ],
"resultConditions": []
}
]
}
</pre>

==POST a new subscriber==

'''<code>POST http(s)://localhost/rest/subscribers</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.notification.SubscriberUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Subscriber</code>

Creates a new notification subscriber.

'''Sample Request'''
<pre>
{
"emailAddress": "test@example.com",
"active": true,
"generalSubscriptions": [
{
"category": "JOB",
"level": "ERROR",
"active": true,
"jobId": 123 // optional, and only valid when a job-related category is selected
}
],
"jobExecutionSubscriptions":[
{
"active": false,
"allJobs": true,
"triggerStates": [ "DIED", "FAILED", "RECOVERY" ]
},
{
"active": true,
"jobIds": [ 123 ], // should not be supplied with the allJobs flag which takes precedence
"triggerStates": [ "CONDITIONAL" ],
"resultConditions": [
{
"variableName": "cleanupState",
"operator": "EQUALS",
"values": [ "incomplete" ] // depending on the operator, values may be empty, have 1 value, or multiple.
}
]
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! 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 general subscriptions. Each item contains a required subscription <code>category</code> and <code>level</code> as defined in [[Unified_API#Enumerations|Enumerations]], an optional <code>jobId</code> and an optional <code>active</code> flag which defaults to false.

'''Note:''' Only <code>ERROR</code>, <code>WARNING</code> AND <code>INFO</code> are valid values for <code>level</code>. Only <code>JOB</code>, <code>JOB_CHAIN</code>, <code>JOB_CONFIG</code>, <code>JOB_RECOVERY</code>, <code>LICENCE</code>, <code>QUEUE</code>, <code>SYSTEM_PARAMETER</code> and null are valid values for <code>category</code>.
|-
| jobExecutionSubscriptions || N || Zero or more job execution subscriptions. Each item contains a required <code>triggerStates</code> field containing at least one subscription job status as defined in [[Unified_API#Enumerations|Enumerations]]. Note that <code>CONDITIONAL</code> and <code>COMPLETED</code> types cannot be used on the same chain.

If the <code>CONDITIONAL</code> state is selected, at least one condition must be supplied in the <code>resultConditions</code> field. Result conditions consist of a <code>variableName</code>, an <code>operator</code> as defined in [[Unified_API#Enumerations|Enumerations]], and for most operators, a list of <code>values</code>. The <code>EXISTS</code> and <code>NOT EXISTS</code> operators do not use values, so they must not be supplied. Operators <code>IN</code> and <code>NOT IN</code> support one or more values, and all other operators accept a single value in the <code>values</code> list. Values for this field map to bean class <code>com.carfey.ops.api.enums.JobSubscriptionConditionOperator</code>.

In addition, two additional optional fields control which jobs the subscription applies to. <code>jobIds</code> is used to specify specific jobs, while <code>allJobs</code> may be set to true to make it apply to all jobs. If <code>jobIds</code> is supplied and <code>allJobs</code> is set to true, <code>jobIds</code> will be ignored.

Finally, the <code>active</code> flag may be supplied which defaults to true.
|}

Responses have the same format as GET.

==PUT updates to an existing subscriber ==

'''<code>PUT http(s)://localhost/rest/subscribers/{subscriberId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.notification.SubscriberUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Subscriber</code>

Updates an existing subscriber. Returns a 404 if not found.

Requests and responses have the same format as POST.

==DELETE an existing subscriber==

'''<code>DELETE http(s)://localhost/rest/subscribers/{subscriberId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Subscriber</code>

Deletes a subscriber. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the subscriber before the delete.

= Templates Endpoints =

''As of version 3.0.''

These endpoints allow for managing notification templates.

==GET a list of templates==
'''<code>GET http(s)://localhost/rest/templates</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.TemplateListing</code>

Returns a list of configured templates.

'''Sample Response (with inline comments)'''
<pre>
{
"templates":[
{
"id": 1,
"name": "Obsidian Default Job Template",
"active": true,
"category": "JOB",
"defaultForJobs": true, // indicates if it is the default job template for the category
"jobs": [ // only present for job categories when defaultForJobs is false
{
"recoveryType": "NONE",
"jobId": 1,
"pickupBufferMinutes": 2,
"nickname": "Cleanup Job",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.JobHistoryCleanupJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"chainAll": false,
"hostPreference": true,
"revision": 52
}
],
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Obsidian {{hostName}} Body content..."
},
{
"id": 2,
"name": "Obsidian Default Other Template",
"active": true,
"defaultForJobs": false,
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Obsidian {{hostName}} Body content..."
}
]
}
</pre>

==GET details of an existing template==
'''<code>GET http(s)://localhost/rest/templates/{templateId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Template</code>

Returns details of a configured template, or a 404 if not found. Contains the same set of fields as the template listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 2,
"name": "Obsidian Default Other Template",
"active": true,
"category": "LICENCE", // if missing, it is the default generic template
"defaultForJobs": false,
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Obsidian {{hostName}} Body content..."
}
</pre>

==POST a new template==

'''<code>POST http(s)://localhost/rest/templates</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.notification.TemplateUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Template</code>

Creates a new template.

'''Sample Request'''
<pre>
{
"name": "Cleanup Job Template",
"active": true,
"category": "JOB", // category not required when it is the default template
"defaultForJobs": false, // when true, jobIds are ignored
"jobIds": [ 123, 456 ],
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Obsidian {{hostName}} Body content..."
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! 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 as defined in [[Unified_API#Enumerations|Enumerations]], or null if it is the default generic template. Supports multiple values. Not all categories are supported. Only <code>JOB</code>, <code>JOB_CHAIN</code>, <code>JOB_CONFIG</code>, <code>JOB_RECOVERY</code>, <code>LICENCE</code>, <code>QUEUE</code>, <code>SYSTEM_PARAMETER</code> 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 [[Email_Templates|Mustache template]] for the subject.
|-
| bodyTemplate || Y || A valid [[Email_Templates|Mustache template]] for the body.
|}

Responses have the same format as GET.

==PUT updates to an existing template==

'''<code>PUT http(s)://localhost/rest/templates/{templateId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.notification.TemplateUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Template</code>

Requests and responses have the same format as POST.

==DELETE an existing template ==

'''<code>DELETE http(s)://localhost/rest/templates/{templateId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Template</code>

Deletes a template. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the template before the delete.

= Notification Endpoints =

''As of Obsidian 3.0''

These endpoints allow you to query what notifications were triggered in Obsidian. Note that existence of records does not necessarily indicate the notification was successfully sent or received.

==GET a list of notifications==
'''<code>GET http(s)://localhost/rest/notifications[?category=QUEUE&level=ERROR&start=1356987599000&end=1357510546000&startKey=123]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.NotificationListing</code>

Returns a list of notifications, optionally filtered by query string parameters. Results are ordered roughly according to when they were created, but ordering is not guaranteed to be in order of created time.

'''Note:''' The <code>nextPageStartKey</code> field in the response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen). To fetch the next page of results, invoke the same endpoint with the <code>startKey</code> query string parameter set to the returned <code>nextPageStartKey</code>.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| category || N || The category of the notifications as defined in [[Unified_API#Enumerations|Enumerations]]. Supports multiple values.
|-
| level || N || The logging level of the notifications defined in [[Unified_API#Enumerations|Enumerations]]. Supports multiple values.
|-
| 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 <code>nextPageStartKey</code>.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"nextPageStartKey": "123",
"notifications": [
{
"id": 51,
"log": {
"id": 292,
"eventTime": "2015-01-22T16:44:00-0800",
"host": "Demo",
"category": "JOB_RUN",
"level": "INFO",
"summary": "Completed job [Job History Cleanup 033] scheduled for [2015-01-22 16:44:00]."
},
"subscriber":{
"id": 51,
"emailAddress": "test@test.com",
"active": true // current active state (not when triggered)
}
},
{
"id": 52,
"log": {
"id": 295,
"eventTime": "2015-01-22T16:44:00-0800",
"host": "Demo",
"category": "JOB_RUN",
"level": "INFO",
"summary": "Completed job [Job History Cleanup 145] scheduled for [2015-01-22 16:44:00]."
},
"subscriber": {
"id": 51,
"emailAddress": "test@test.com",
"active": true
}
},
]
}
</pre>

==GET details of an existing notification==
'''<code>GET http(s)://localhost/rest/notifications/{id}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Notification</code>

Returns detail of an existing notification, which contains the same fields as the listing endpoint. Returns a 404 if not found.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 51,
"log": {
"id": 292,
"eventTime": "2015-01-22T16:44:00-0800",
"host": "Demo",
"category": "JOB_RUN",
"level": "INFO",
"summary": "Completed job [Job History Cleanup 033] scheduled for [2015-01-22 16:44:00]."
},
"subscriber":{
"id": 51,
"emailAddress": "test@test.com",
"active": true // current active state (not when triggered)
}
}
</pre>

= Log Endpoints =

''As of Obsidian 3.0''

==GET a list of logs==
'''<code>GET http(s)://localhost/rest/logs[?host=host1&filterText=error&category=QUEUE&level=ERROR&start=1356987599000&end=1357510546000&startKey=123]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.log.LogListing</code>

Returns a list of event logs, optionally filtered by query string parameters. Results are ordered roughly according to when they were created, but ordering is not guaranteed to be in order of created time.

'''Note:''' The <code>nextPageStartKey</code> field in the response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen). To fetch the next page of results, invoke the same endpoint with the <code>startKey</code> query string parameter set to the returned <code>nextPageStartKey</code>.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! 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 || The category of the log as defined in [[Unified_API#Enumerations|Enumerations]]. Supports multiple values.
|-
| level || N || The logging level of the log as defined in [[Unified_API#Enumerations|Enumerations]]. Supports multiple values.
|-
| 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 <code>nextPageStartKey</code>.
|}

'''Sample Response'''
<pre>
{
"nextPageStartKey" : "123",
"logs": [
{
"id": 1619,
"eventTime": "2015-01-21T13:59:43-0800",
"host": "Demo",
"category": "JOB_SPAWNER",
"level": "DEBUG",
"summary": "Spawning [Test Job] scheduled for 2015-01-21 13:59:00"
},
{
"id": 4,
"eventTime": "2015-01-20T11:54:49-0800",
"host": "Demo",
"category": "LICENCE",
"level": "INFO",
"summary": "Successfully refreshed licence from server https://licence.carfey.com/licence for 120 minutes."
}
]
}
</pre>

==GET details of an existing log==
'''<code>GET http(s)://localhost/rest/logs/{logId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.log.Log</code>

Returns detail of an existing log entry. Returns a 404 if not found.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 1619,
"eventTime": "2015-01-21T13:59:43-0800",
"host": "Demo",
"category": "JOB_SPAWNER",
"level": "DEBUG",
"summary": "Spawning [Test Job] scheduled for 2015-01-21 13:59:00"
}
</pre>

= System Parameter Endpoints =

''As of version 3.0.''

==GET a list of system parameters==
'''<code>GET http(s)://localhost/rest/system_parameters</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.SystemParameterListing</code>

Returns a list of system parameters which can be edited.

'''Sample Response (with inline comments)'''
<pre>
{
"parameters": [
{
"name": "clientKeyServerUrl",
"description": "Address of the primary key server. If running a proxy, this should be the address of the proxy server.",
"type": "STRING",
"category": "LICENCE",
"value": "https://licence.carfey.com/licence"
},
{
"name": "maxJobThreads",
"description": "This value determines the maximum number of threads that will be spawned for running jobs. Changes to this value require a server restart.",
"type": "INTEGER",
"category": "JOB_SPAWNER",
"value": "1000"
}
]
}
</pre>

==GET details of a system parameter ==
'''<code>GET http(s)://localhost/rest/system_parameters/{name}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.SystemParameter</code>

Returns details of a system parameter, or a 404 if not found. Contains the same set of fields as the listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"name": "clientKeyServerUrl",
"description": "Address of the primary key server. If running a proxy, this should be the address of the proxy server.",
"type": "STRING",
"category": "LICENCE",
"value": "https://licence.carfey.com/licence"
}
</pre>

==PUT updates to a system parameter ==

'''<code>PUT http(s)://localhost/rest/system_parameters/{name}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.system.SystemParameterUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.SystemParameter</code>

Updates a system parameter's value. Values are accepted as strings, but must be valid for their target type (integer, boolean, etc.). Returns a 404 if not found.

'''Sample Request'''
<pre>
{
"value": "60"
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| value || N || The new value for the system parameter, which can be converted into the appropriate target type. Some string values support an empty value.
|}

Responses have the same format as GET.

= User Endpoints =

''As of version 3.0.''

Note that user endpoints are only available when using Obsidian's native authentication, and do not support LDAP or custom authentication.

==GET a list of users==
'''<code>GET http(s)://localhost/rest/users</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.UserListing</code>

Returns a list of configured users.

'''Sample Response (with inline comments)'''
<pre>
{
"users": [
{
"id": 1,
"userName": "admin",
"active": true,
"roles": ["ADMIN","API"]
},
{
"id": 2
"userName": "reader",
"active": false,
"roles": [] // no roles means read-only
}
]
}
</pre>

==GET details of an existing user==
'''<code>GET http(s)://localhost/rest/users/{userId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.User</code>

Returns details of a configured user, or a 404 if not found. Contains the same set of fields as the user listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 1,
"userName": "admin",
"active": true,
"roles": ["ADMIN","API"]
}
</pre>

==POST a new user==

'''<code>POST http(s)://localhost/rest/users</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.user.UserCreationRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.User</code>

Creates a new user.

'''Sample Request'''
<pre>
{
"userName": "admin",
"active": true,
"roles": ["ADMIN","API"],
"password": "changeme"
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! 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 roles as defined in [[Unified_API#Enumerations|Enumerations]]. Supplying no roles indicates it is a normal read-only user.
|-
| password || Y || A password at least 6 characters long.
|}

Responses have the same format as GET.

==PUT updates to an existing user==

'''<code>PUT http(s)://localhost/rest/users/{userId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.user.UserUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.User</code>

Updates an existing user. Returns a 404 if not found. Semantics similar to a PATCH request are used, so that only supplied fields are updated. User names cannot be updated.

'''Sample Request'''
<pre>
{
"active": true,
"roles": ["ADMIN","API"],
"password": "changeme"
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| active || N || Whether the user is enabled. Defaults to the existing active state.
|-
| roles || N || Zero or more roles as defined in [[Unified_API#Enumerations|Enumerations]]. 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.
|}

Responses have the same format as POST.

==DELETE an existing user ==

'''<code>DELETE http(s)://localhost/rest/users/{userId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.User</code>

Deletes a user. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the user before the delete.

==GET a list of known MFA users==

''As of version 5.0.''

'''<code>GET http(s)://localhost/rest/users/mfa</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.MfaUserListing</code>

Returns all known users which may have Multi-Factor Authentication (MFA) resets applied. Exists to facilitate use of the MFA reset endpoint.

'''Sample Response'''
<pre>
{
"userNames": [
"admin",
"john.doe",
"operator"
]
}
</pre>

==PUT MFA user resets==

''As of version 5.0.''

'''<code>PUT http(s)://localhost/rest/users/mfa/reset</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.user.ResetMfaRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.MfaUserListing</code>

Resets the requested users' Multi-Factor Authentication (MFA) state so that they may perform MFA setup. This is useful when a user does not complete MFA setup within the required time, or when adding a user when not using Obsidian's native authentication.

'''Sample Request'''
<pre>
{
"userNames": [
"admin",
"john.doe",
"operator"
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| userNames || Y || The list of user names to reset. Note that these do not have to correspond to known Obsidian users, since it must support custom authentication methods.
|}

Responses echo the users in the request.

'''Sample Response'''
<pre>
{
"userNames": [
"admin",
"john.doe",
"operator"
]
}
</pre>

= System Restore Endpoints =

''As of version 3.0.''

These endpoinds can be used to import and export Obsidian's configuration, including job-related configuration, subscription-related configuration, users and system parameters. See [[Initializing_and_Restoring|Initializing and Restoring]] for more details.

==GET a system restore configuration ==
'''<code>GET http(s)://localhost/rest/system_restores[?excludeItem=users&jobNickname=jobname]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration</code>

Returns the system's exported configuration. The output from this endpoint can be used with the corresponding [[#PUT_a_system_restore_configuration|PUT endpoint]] directly.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| excludeItem || N || Allows filtering out of specific groups of system configuration items. Supported values are <code>jobs</code>, <code>chains</code>, <code>conflicts</code>, <code>systemParameters</code>, <code>customCalendars</code>, <code>globalParameters</code>, <code>users</code>, <code>templates</code>, <code>subscribers</code>. Filtering out jobs automatically also filters out chains and conflicts and drops any other job references (such as in templates and subscribers). Supports multiple values. Since 3.8.0.
|-
| jobNickname || 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). Supports multiple values. Since 3.8.0.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"jobs": [
{
"updateSchedule": false, // whether to apply the current schedule and any additional jobSchedules when the job already exists
"updateAttributes": false, // whether job attributes (jobClass, recoveryType, pickupBufferMinutes, etc.) will be updated when the job exists
"jobSchedules": [
{
"state": "DISABLED",
"effectiveDate": "2015-03-20T10:35:00-0700",
"endDate": "2999-12-31T23:59:00-0800"
}
],
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"minExecutionDuration": "2s",
"maxExecutionDuration": "3s",
"nickname": "Log Cleanup",
"folder": "Production/Test", // as of 4.1.0
"pickupBufferMinutes": 2,
"recoveryType": "NONE",
"hosts": [ "Demo-PC" ],
"ordinalParameters": [ // as of 3.8.0, prior to 3.8.0, parameters child element was at this level
"ordinal": 0, //as of 3.8.0
"parameters": [
{
"name": "level",
"type": "STRING",
"value": "ALL"
},
{
"name": "maxAgeDays",
"type": "INTEGER",
"value": "120"
}
]
],
"chainAll": false,
"hostPreference": true,
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"state": "ENABLED",
"schedule": "* * * * *",
"effectiveDate": "2015-01-01T00:00:00-0700"
"endDate": "2015-03-20T10:34:00-0700"
},
{
"updateSchedule": false,
"updateAttributes": false,
"jobSchedules": [],
"jobClass": "com.carfey.ops.job.script.GroovyJob",
"nickname": "Script Job",
"pickupBufferMinutes": 2,
"recoveryType": "NONE",
"hosts": [],
"ordinalParameters": [ // as of 3.8.0, prior to 3.8.0, parameters child element was at this level
"ordinal": 0, //as of 3.8.0
"parameters": [
{
name": "script",
"type": "STRING",
"value": "sdfds"
}
]
],
"chainAll": false,
"hostPreference": false,
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"state": "DISABLED",
"effectiveDate": "2015-01-01T00:00:00-0700"
"endDate": "2999-12-31T23:59:00-0800"
}
],
"users": [
{
"update": false, // when false, the user attributes will not be updated if the user already exists
"userName": "admin",
"active": true,
"roles": [
"API",
"ADMIN",
"WRITE"
],
"password": "changeme"
}
],
"chains": {
"replaceAll": false, // if set to false or omitted, chains will only be created if none exist - existing chains are not updated.
"items": [
{
"sourceJobNickname": "Script Job",
"targetJobNickname": "Log Cleanup",
"active": true,
"triggerStates": [
"FAILED",
"CONDITIONAL"
],
"resultConditions": [
{
"variableName": "dfdsfds",
"operator": "EQUALS",
"values": [
"sdfs"
]
}
]
}
]
},
"conflicts": [
[
"Script Job",
"Log Cleanup"
]
],
"customCalendars": [
{
"name": "Sample Calendar",
"dates": [
"2011-01-01"
]
}
],
"systemParameters": [
{
"name": "adHocJobsRespectFixedHostsRestrictions",
"description": "This value determines whether the Fixed Hosts restriction assigned to a Job is respected for Ad Hoc jobs.",
"category": "JOB",
"value": "true"
}
],
"templates": [
{
"jobNicknames": [],
"name": "Obsidian Default Job Template",
"active": true,
"category": "JOB",
"defaultForJobs": true,
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Body Template"
}
],
"subscribers": [
{
"generalSubscriptions": [
{
"jobNickname": "Log Cleanup",
"category": "JOB",
"level": "ERROR",
"active": true
}
],
"jobExecutionSubscriptions": [
{
"jobNicknames": [],
"allJobs": true,
"triggerStates": [
"CONDITIONAL",
"DIED",
"FAILED",
"RECOVERY"
],
"resultConditions": [
{
"variableName": "someVar",
"operator": "EQUALS",
"values": [
"someValue"
]
}
],
"active": true
}
],
"emailAddress": "test@example.com",
"active": true
}
]
}
</pre>

==PUT a system restore configuration==
'''<code>PUT http(s)://localhost/rest/system_restores</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration</code>

Imports the requested system restore configuration, updating, creating and replacing data based on the input.

'''Usage Note:''' Entities within the export are generally identified by their names. For details on required fields, formats and update logic, refer to the [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemRestoreManager.html#updateConfiguration(com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration,java.lang.String) Javadoc] and the [[Initializing_and_Restoring|Initializing and Restoring]] page. The Embedded API and REST API both use the same format and processing rules.

Requests are in the same format as the [[#GET_a_system_restore_configuration|GET endpoint's]] response.

Responses are in the same format as the GET and return the full Obsidian system restore configuration following the changes (not necessarily the same as the input).

= Schedule Alias Endpoints =

''As of version 5.0.''

These endpoints can be used to manage schedule aliases. See [[Admin_Schedule_Aliases|Schedule Aliases]] for more details.

==GET a list of schedule aliases ==
'''<code>GET http(s)://localhost/rest/schedule_aliases</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAliasListing</code>

Returns the system's schedule aliases.

'''Sample Response'''
<pre>
{
"scheduleAliases": [
{
"alias": "@every4Minutes",
"schedule": "0/4 * * * *",
"scheduleDescription": "Every 4th minute every day" (as of Obsidian 5.2.0)
},
{
"alias": "@dailyAtNoon",
"schedule": "12 * * * *",
"scheduleDescription": "At 12:00PM every day" (as of Obsidian 5.2.0)
},
{
"alias": "@threeTimesWeekly",
"schedule": "0 0 * 1,3,5 *",
"scheduleDescription": "At midnight on Mondays, Wednesdays, Fridays" (as of Obsidian 5.2.0)
},
{
"alias": "@combinedExample",
"schedule": "@dailyAtNoon;@threeTimesWeekly",
"scheduleDescription": "At 12:00PM every day - AND - At midnight on Mondays, Wednesdays, Fridays" (as of Obsidian 5.2.0)
}
]
}
</pre>

==PUT a schedule alias==
'''<code>PUT http(s)://localhost/rest/schedule_aliases/{alias}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAliasUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAlias</code>

'''Sample Request'''
<pre>
{
"schedule": "5 11 * * 2"
}
</pre>

'''Sample Response'''
<pre>
{ "alias": "@1105AMTuesdays",
"schedule": "5 11 * * 2",
"schedule": "At 11:05AM on Tuesdays" (as of Obsidian 5.2.0)
}
</pre>

==GET a schedule alias==
'''<code>GET http(s)://localhost/rest/schedule_aliases/{alias}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAlias</code>

'''Sample Response'''
<pre>
{ "alias": "@1105AMTuesdays",
"schedule": "5 11 * * 2",
"schedule": "At 11:05AM on Tuesdays" (as of Obsidian 5.2.0)
}
</pre>

==DELETE a schedule alias==
'''<code>DELETE http(s)://localhost/rest/schedule_aliases/{alias}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAlias</code>

'''Sample Response'''
<pre>
{ "alias": "@1105AMTuesdays",
"schedule": "5 11 * * 2"
}
</pre>

= Job Execution Statistics Endpoints =

''As of version 6.4.0.''

To retrieve job execution statistics. Assumes [[Built-in_Jobs#Obsidian_Execution_Statistics_Job|Execution Statistics Job]] has run to completion at least once.

== GET a list of job execution statistics ==
'''<code>GET http(s)://localhost/rest/stats[?jobNickname=jobname&job_id=1&duration=six_months&unit=seconds&status=completed&acrossHosts=false&host=prod.obsidian-a1&host=prod.obsidian-a2]</code>'''

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobNickname || N || Allows targeting only specific jobs by nickname in the stats export. Supports multiple values.
|-
| jobId || N || Allows targeting only specific jobs by id in the stats export. Supports multiple values.
|-
| duration || N || Allows targeting stats durations. See [[Unified_API#Enumerations|Enumerations]] for valid values - case-insensitive. Supports multiple values.
|-
| unit || N || Allows targeting stats units. See [[Unified_API#Enumerations|Enumerations]] for valid values - case-insensitive. Supports multiple values.
|-
| status || N || Allows targeting stats terminal statuses. See [[Unified_API#Enumerations|Enumerations]] for valid values - case-insensitive. Supports multiple values.
|-
| host || N || Allows targeting stats from specific hosts. Supports multiple values.
|-
| acrossHosts || N || Allows selecting stats collected across all hosts. Boolean.
|}

'''Response bean class:''' <code>com.carfey.ops.api.bean.stats.StatsListing</code>

Returns the cluster's job execution statistics.

'''Sample Response'''
<pre>
{
"stats": [
{
"statsId": 733,
"jobId": 55,
"nickname": "Cache Reloader",
"host": "prod.obsidian-a1",
"status": "COMPLETED",
"unit": "SECONDS",
"duration": "YEAR",
"start": "2024-12-14",
"end": "2025-12-14",
"count": 97,
"average": 7701.463918,
"median": 6965.0,
"mode": 62,
"min": 62.0,
"max": 17925.0,
"variance": 23055960.248698,
"standardDeviation": 4801.66
},
{
"statsId": 545,
"jobId": 55,
"nickname": "Cache Reloader",
"host": "prod.obsidian-a2",
"status": "COMPLETED",
"unit": "HOURS",
"duration": "YEAR",
"start": "2024-12-14",
"end": "2025-12-14",
"count": 114,
"average": 2.238684,
"median": 1.932778,
"mode": 1,
"min": 0.015,
"max": 4.989444,
"variance": 2.18319,
"standardDeviation": 1.47756
}
],
"hosts": [
"prod.obsidian-a1",
"prod.obsidian-a2"
]
}
</pre>

Release Notes

2025-12-16T00:03:55Z

Craig:

Please review our [[Upgrading_Obsidian|Upgrade Instructions]].

Read about our [[Planned_Releases|Planned Releases]].

Looking for old release notes? See [[Release_Notes_-_Older_Releases|Release Notes - Older Releases]].

<div class="toclimit-2">__TOC__</div>

== Obsidian 6.4.0 ==
To Be Released December 2025

=== Enhancements ===
* New [[Built-in_Jobs#Obsidian_Execution_Statistics_Job|Execution Statistics Job]] and built in [[Admin_Job_Stats|UI]] and Embedded API and REST API

=== Bug Fixes ===

* Fixed issue preventing [[Admin_Jobs#Deleting|job deletion]] when resubmissions of failed executions existed. Bug applied to UI and APIs.
* Fixed UI styling issue for [[Admin_Jobs#Deleting|job deletion]] where checkbox label did not appear.

== Obsidian 6.3.3 ==
Released November 2025

=== Enhancements ===
* [https://web.obsidianscheduler.com/obsidianapi/com/carfey/suite/security/LdapAuthenticator.html LDAPAuthenticator] supports configurable check user active override - com.carfey.suite.security.LdapAuthenticator.checkActiveAttribute
* [https://web.obsidianscheduler.com/obsidianapi/com/carfey/suite/security/LdapAuthenticator.html#isUserActive(javax.naming.directory.DirContext,java.lang.String) LDAPAuthenticator.isUserActive(DirContext,String)] visibility increased to protected to allow for functionality override in subclasses.

=== Bug Fixes ===

* Correct LdapAuthenticator case with delimited configuration where active check wasn't applied.
* [https://web.obsidianscheduler.com/obsidianapi/com/carfey/suite/security/LdapAuthenticator.html#isUserActive(javax.naming.directory.DirContext,java.lang.String) LDAPAuthenticator.isUserActive(DirContext,String)] javadoc added for isUserActive fully detailing the implementation.

== Obsidian 6.3.2 ==
Released October 2025

=== Enhancements ===
* Notification failures now trigger Dispatch category Error level event on first failure. For use in log alerts and Event Hooks.

=== Bug Fixes ===

* Notification failures no longer log on every failure reducing chatty failure logs.
* No-arg constructors added to multiple JSON serializable candidate POJOs missing them. Addresses GSON's workaround use of sun.misc.Unsafe.

== Obsidian 6.3.1 ==
Released August 2025

=== Bug Fixes ===

* Fix failure response codes on [[REST_Endpoints#GET_health_details_on_an_existing_scheduling_host|REST health endpoint]]
* Fix automatic upgrade issue from 6.1.0 to any of 6.2.0, 6.2.1, 6.3.0
* Fix auth issue when [[Admin_User_Management#Multi-Factor_Authentication_.28MFA.29|MFA]] is enabled that allows REST access when account has been locked out due to MFA not being setup. [[Contact_the_Obsidian_Scheduler_Team|Contact us]] if you need workaround details for earlier versions.
* Fix native auth issue that allows REST access when account has been flagged as inactive.

== Obsidian 6.3.0 ==
Released July 2025

=== Features / Enhancements ===

* Cron day of month expansion for [[Cron#Special_Character_Usage|day of week proximity]] using [[Cron#Examples|~]]
* Annotation based job and chain configuration [[Initializing_and_Restoring#Annotation_Initialization|initialization]]
* Health endpoint with details for Job Queuer and Job Spawner - [[REST_Endpoints#GET_health_details_on_an_existing_scheduling_host|REST API]] or Embedded API [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#getHealth(java.lang.String) by hostname] or [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#getHealth(long) by host id]
* JDBC URL construction from parts [[Advanced_Configuration#Database_Properties|host/port/databaseName/dbType/oracleSid]]

== Obsidian 6.2.1 ==
Released June 2025

=== Bug Fixes ===

* Certain recoveries greater than 24 hours using new day of month proximity patterns introduced in 6.2.0 would result in no jobs spawning.
* Migrations targeting 6.0.0 and greater that start earlier than 5.0.0 skip the 5.0.0 migration. Migrating to any 5.x version first and then to 6.0.0 or later works around this issue.

== Obsidian 6.2.0 ==
Released May 2025

=== Features / Enhancements ===

* Cron day of month expansion for [[Cron#Special_Character_Usage|day of week proximity]] using [[Cron#Examples|< > ≥ ≤]]
* Cron day of month expansion for [[Cron#Special_Character_Usage|weekday proximity]] using [[Cron#Examples|< > ≥ ≤]]
* [[Admin_Global_Parameters#Using_Global_Parameters_in_Jobs|Global Parameters]] reference in job edit page support mouseover/title display of actual value when permissions allow
* Host time displayed in [[Admin_Host_Status|hosts status]] in UI
* [[Admin_Job_Runtime_Preview|Runtime Preview]] optimizations for large date ranges in both UI and APIs.

=== Bug Fixes ===

* Combination of table prefix, sorting by clob column and Oracle metadata load failure no longer results in sql error. This occurred in the UI when viewing raw job history results and in API calls for job runtime results.

== Obsidian 6.1.1 ==
Released March 2025

=== Features / Enhancements ===

* [[Authenticator#Implementation_of_a_Custom_Authenticator|Authenticator]] supports optional <code>authenticateREST()</code> method.

=== Bug Fixes ===

* Native authentication REST logins do not apply 'last login' timestamps. Avoids noisy error that was appearing in logs.

== Obsidian 6.1.0 ==
Released March 2025

=== Features / Enhancements ===

* Native authentication now disables users after 4 invalid login attempts, either password or MFA code if applicable. Invalid attempts threshold is configurable.
* Native authentication last login datetime displayed on list user screen.
* Stronger licensing controls. Site and hardware licenses as of this version must be regenerated by Carfey Software and every 2 years. Contact us at licensing [[Image:atSymbol.png]] obsidianscheduler.com.

=== Bug Fixes ===

* Native authentication password complexity pattern properly created and no longer overwritten on restart.

== Obsidian 6.0.1 ==
Released February 2025

=== Features / Enhancements ===

* [[Built-in_Jobs#File_Archive_Job|File Archive Job]] and [[Built-in_Jobs#File_Scanner_Job|File Scanner Job]] both now support min/max file sizes and minimum age.

=== Bug Fixes ===

* Native authentication user updates now support long passwords.

== Obsidian 6.0.0 ==
Released December 27, 2024

=== Features / Enhancements ===

* Jakarta Servlet 5.0
** Servlet container for Web Admin must support Jakarta Servlet 5.0 (e.g. Tomcat 10, Jetty 11)
* [[Micronaut_Integration|Micronaut]] integration support
* [[Advanced_Configuration#Dependent_Libraries|Groovy 4]] support
* [[Advanced_Configuration#Properties.2FYaml_File|Yaml]] configuration support<ref>

If you are using automated installer files from previous releases, you will need to add an additional configuration item to choose between yaml and properties formats in UserInputPanel.0.
<pre>
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.0">
<userInput>
......snip......
<entry key="config.format" value="yaml" />
OR
<entry key="config.format" value="properties" />
......snip......
</userInput>
</com.izforge.izpack.panels.UserInputPanel>
</pre></ref>
* Native authentication supports customizable [[Admin_Login#Password_Complexity|password complexity]] requirements
* XML support deprecated across the product including XML UI downloads, XML runner configurations and XML license leases.
** '''Starting January 1st 2027, XML license lease requests will stop being processed. All Obsidian instances running using internet-verified licenses (including licence key proxies) will be required to use release 6.0.0 or later as of January 1st 2027.'''
** Above noted XML support will be removed in the first Obsidian version released in 2027.
* License leases use JSON payloads.

== Obsidian 5.5.1 ==
Released December 16, 2024

=== Bug Fixes ===

* Admin only (no scheduler) UI no longer generates event hook errors while running nor during shutdown
* Quick start installer file no longer generates errors during installation
* A few small web UI enhancements

== Obsidian 5.5.0 ==
Released October 2024

=== Features / Enhancements ===

* Event Hooks management available in [[Admin_Host_Status#Event_Hook_Status|UI]], [[Embedded_API#Event_Hook_Resume_or_Pause|Embedded API]] and [[REST_Endpoints#POST_event_hook_pause_or_resume|REST API]].
* [[Installation_Guide#Additional_configuration_items|Installer]] supports custom add on configurations '''Potential breaking change to automated installer files.''' <ref>

If you are using automated installer files from previous releases, you will need to add a new section of xml as of Obsidian 5.5.0 to handle a new UserInputPanel. Immediately after the UserInputPanel.17 closing brace, add the following:
<pre>
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.18">
<userInput>
<entry key="extra.log4j2.properties.1" value=""/>
<entry key="extra.log4j2.properties.2" value=""/>
<entry key="extra.log4j2.properties.3" value=""/>
<entry key="extra.log4j2.properties.4" value=""/>
<entry key="extra.log4j2.properties.5" value=""/>
<entry key="extra.log4j2.properties.6" value=""/>
<entry key="extra.log4j2.properties.7" value=""/>
<entry key="extra.log4j2.properties.8" value=""/>
<entry key="extra.log4j2.properties.9" value=""/>
<entry key="extra.log4j2.properties.10" value=""/>
<entry key="extra.log4j2.properties.11" value=""/>
<entry key="extra.log4j2.properties.12" value=""/>
<entry key="extra.log4j2.properties.13" value=""/>
<entry key="extra.log4j2.properties.14" value=""/>
<entry key="extra.log4j2.properties.15" value=""/>
<entry key="extra.log4j2.properties.16" value=""/>
<entry key="extra.log4j2.properties.17" value=""/>
<entry key="extra.log4j2.properties.18" value=""/>
<entry key="extra.log4j2.properties.19" value=""/>
<entry key="extra.log4j2.properties.20" value=""/>
<entry key="extra.carfey.properties.1" value=""/>
<entry key="extra.carfey.properties.2" value=""/>
<entry key="extra.carfey.properties.3" value=""/>
<entry key="extra.carfey.properties.4" value=""/>
<entry key="extra.carfey.properties.5" value=""/>
<entry key="extra.carfey.properties.6" value=""/>
<entry key="extra.carfey.properties.7" value=""/>
<entry key="extra.carfey.properties.8" value=""/>
<entry key="extra.carfey.properties.9" value=""/>
<entry key="extra.carfey.properties.11" value=""/>
<entry key="extra.carfey.properties.10" value=""/>
<entry key="extra.carfey.properties.12" value=""/>
<entry key="extra.carfey.properties.13" value=""/>
<entry key="extra.carfey.properties.14" value=""/>
<entry key="extra.carfey.properties.15" value=""/>
<entry key="extra.carfey.properties.16" value=""/>
<entry key="extra.carfey.properties.17" value=""/>
<entry key="extra.carfey.properties.18" value=""/>
<entry key="extra.carfey.properties.19" value=""/>
<entry key="extra.carfey.properties.20" value=""/>
</userInput>
</com.izforge.izpack.panels.UserInputPanel>
</pre>
</ref>

=== Bug Fixes ===

* Certain Cron expressions that fail to generate text descriptions no longer impact scheduling.
* Text database columns were previously restricted to maximum length of MySQL implementation. Corrected to validate length via DB implementation.

== Obsidian 5.4.0 ==
Released June 2024

=== Features / Enhancements ===

* Event Hooks available in [[Embedded_API#List_Event_Hooks|Embedded API]] and [[REST_Endpoints#GET_event_hooks|REST API]].
* [[Advanced_Configuration#Dependent_Libraries|GSON library]] upgrade to support Java 21

=== Bug Fixes ===

* Oracle identifier no longer too long when using prefixes.

== Obsidian 5.3.0 ==
Released March 2024

=== Features / Enhancements ===

* New [[Admin_Host_Status#Event_Hook_Status| Event Hooks Status]] available in the UI.

=== Bug Fixes ===

* Some improvements throughout the [[Admin_Web_Application_Guide|Admin Web Application]] for autofocus of fields.
* Additional classes and interfaces added to [https://web.obsidianscheduler.com/obsidianapi/ javadoc].
* Some cleanup in [https://web.obsidianscheduler.com/obsidianapi/ javadoc] documenation.

== Obsidian 5.2.1 ==
Released January 2024

=== Features / Enhancements ===

* [[Built-in_Jobs#Maintenance_Jobs|Maintenance Jobs]] are now scheduled by default in new installations. Can be disabled via [[Advanced_Configuration#Miscellaneous_Properties|Configuration]] property.
* New [[Event_Hooks#Standard_Output.2FError_Streams_Event_Hook | Standard Output/Error Streams Event Hook]].

=== Bug Fixes ===

* Schedule descriptions are now updated after edits are applied in all UI screens and APIs.

== Obsidian 5.2.0 ==
Released December 2023

=== Features / Enhancements ===

* [[Cron]] & [[Cron#Recurrence|Recur]] patterns along with any use of [[Admin_Schedule_Aliases|Schedule Aliases]] now support plain language description of the patterns throughout the [[Admin_Web_Application_Guide|UI]], visible while hovering patterns, and in [[REST_Endpoints|REST]] and [[Embedded_API|Embedded]] API responses.
* All screens supporting UI exports now support JSON ([[Admin_Job_Activity#Exporting_Results|Job Activity]], [[Admin_Jobs#Exporting_Results|Jobs]], [[Admin_Job_Runtime_Preview#Exporting_Results|Runtime Previews]], [[Admin_Job_Chains#Job_Chain_Listing|Job Chains]], [[Admin_Logs#Exporting_Results|Logs]], [[Admin_Notifications#Exporting_Results|Sent Notifications]], [[Admin_User_Management#Exporting_Results|Users]], [[Admin_Custom_Calendars#Calendar_Listing|Calendars]])
* All screens supporting UI exports and search criteria and/or inline filters now include any specified search criteria and filter text in Excel, XML and JSON downloads ([[Admin_Job_Activity#Exporting_Results|Job Activity]], [[Admin_Jobs#Exporting_Results|Jobs]], [[Admin_Job_Runtime_Preview#Exporting_Results|Runtime Previews]], [[Admin_Job_Chains#Job_Chain_Listing|Job Chains]], [[Admin_Logs#Exporting_Results|Logs]], [[Admin_Notifications#Exporting_Results|Sent Notifications]], [[Admin_User_Management#Exporting_Results|Users]])
* Support for [[Installation_Guide#Choosing_Email_Support|Jakarta EE mail]] '''Potential breaking change to automated installer files.''' <ref>

If you are using automated installer files from previous releases and had email configured, you will need to add a new section of xml as of Obsidian 5.2.0 to handle a new UserInputPanel. Immediately after the UserInputPanel.16 closing brace, add the following:
<pre>
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.17">
<userInput>
<entry key="mail.type.selection" value="javax"/>
</userInput>
</com.izforge.izpack.panels.UserInputPanel>
</pre>
</ref>
* New [[Event_Hooks#REST_Endpoint_Event_Hook|REST Endpoint Event Hook]]
* [[Key_Server_Proxy|Key Server proxy]] artifact obtained via web download during installation

=== Bug Fixes ===

* Time picker buttons (hour, minute, AM/PM) in [[Admin_Job_Activity#Filtering|Job Activity filtering]] no longer change other elements of the selected time.
* Cron pattern with [[Cron#Special_Character_Usage|LW]] and any other non-L value in day position no longer also incorrectly evaluates to last day.

== Obsidian 5.1.1 ==
Released June 2023

=== Bug Fixes ===

* [[Authenticator|Native authentication]] no longer fails when user deletes are attempted from the UI.
* Built in maintenance job [[Built-in_Jobs#Job_History_Cleanup_Job|Job History Cleanup]] no longer leaves deletion candidate CHAIN SKIPPED records in the JOB_HISTORY table in rare circumstances.

== Obsidian 5.1.0 ==
Released April 2023

=== Features / Enhancements ===

* [[Admin_Schedule_Aliases#Schedule_Alias_Fragments|Schedule Aliases]] now support fragments for configuration-time substitutions.
* New convenience job [[Built-in_Jobs#Database_File_Export_Job|Database File Export Job]] for generating basic file extracts from database queries.
* New convenience job [[Built-in_Jobs#REST_Invocation_Job|REST Invocation Job]] for making simple REST calls and storing results.
* Performance improvements in job failure handling.

== Obsidian 5.0.4 ==
Released February 2022

=== Features / Enhancements ===
* Log4j2 2.17.1 as fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.17.1 RCE vulnerability] where attackers can modify log4j configuration.
* Restore missing default log4j2 configuration in installation artifacts.

== Obsidian 5.0.3 ==
Released December 2021

=== Features / Enhancements ===
* Log4j2 2.17.0 as fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.17.0 DOS vulnerability]
* Fix native login issue showing as inactive on some databases.

== Obsidian 5.0.2 ==
Released December 2021

=== Features / Enhancements ===
* Log4j2 2.16.0 as permanent fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.16.0 RCE vulnerability]

== Obsidian 5.0.1 ==
Released December 2021

=== Features / Enhancements ===
* Log4j2 2.15.0 as fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.15.0 RCE vulnerability]

=== Bug Fixes ===
* Fix sporadic native login issue on some databases.
* Formatting fix in quick installer file

== Obsidian 5.0.0 ==
Released August 2021.

=== Features / Enhancements ===
* Java 11 (minimum Java version)
* [[Admin_Schedule_Aliases|Schedule Aliases]] including support in [[REST_Endpoints#Schedule_Alias_Endpoints|REST API]] and [[Embedded_API#ScheduleAliasManager_API|Embedded API]]
* [[Admin_User_Management#Multi-Factor_Authentication_.28MFA.29|MFA Support]] for UI logins
* New [[Admin_User_Management#User_Rights|Author and Operator]] roles
* Convention-based role permissions by [[Admin_User_Management#Job_Folder_Rights|root job folder]] for Write, Author and Operator.<ref>
There is a possibility of a breaking change to Embedded or REST API use due to the need to change the [[Embedded_API#Enumerations|User Role enumeration]] from a Java enum to an enum-style class to support this feature. Bringing in the upgraded Obsidian library and compiling should reveal any such broken use of these enumerations. Needed changes should be minor and self-explanatory.</ref>
* Bundled Jetty 10.0.2
* Legacy Embedded API (from Obsidian 1.5) dropped
* Signal handler disabled by default. Enabled only via [[Advanced_Configuration#Miscellaneous_Properties|configuration]].
* Many [[Advanced_Configuration#Dependent_Libraries|library upgrades]].
* UI javascript library updates.

== Footnotes ==
<references/>

Embedded API

2025-12-15T22:00:21Z

Craig: /* Enumerations */

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.

[https://web.obsidianscheduler.com/obsidianapi/ 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 [[Advanced_Configuration#Dependent_Libraries|dependent libraries]] and [[Advanced_Configuration#Properties_File|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 [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/AbstractAPIManager.html#withTransaction(java.lang.String,java.util.concurrent.Callable) AbstractAPIManager.withTransaction].

<pre>
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);
</pre>

==API Basics ==
The API is exposed through <code>Manager</code> classes in the package [https://web.obsidianscheduler.com/obsidianapi/index.html?com/carfey/ops/api/embedded/package-summary.html com.carfey.ops.api.embedded]:
* <code>JobManager</code> - Create and manage jobs, job conflicts and chaining.
* <code>RuntimeManager</code> - List job runtime history, resubmit jobs, preview scheduled times, etc.
* <code>HostManager</code> - Manage and list active scheduling hosts (i.e. nodes).
* <code>CustomCalendarManager</code> - Manage custom calendars.

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

<pre>
RuntimeListing recentRuntimes = new RuntimeManager().listRuntimes(new RuntimeListingParameters());
</pre>

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:

* [https://web.obsidianscheduler.com/obsidianapi/com/carfey/suite/action/ValidationException.html ValidationException] - some sort of validation error occurred.
* [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html 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 <code>ValidationException</code> and <code>MissingEntityException</code>, 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 [https://web.obsidianscheduler.com/obsidianapi/index.html?com/carfey/ops/api/enums/package-summary.html 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 [[Admin_Jobs#State|State]]'''
* <code>ENABLED</code>
* <code>DISABLED</code>
* <code>UNSCHEDULED_ACTIVE</code>
* <code>CHAIN_ACTIVE</code>
* <code>AD_HOC_ACTIVE</code>

'''Job History [[Job_Features#Execution_Statuses | Status]]'''
* <code>READY</code>
* <code>RUNNING</code>
* <code>COMPLETED</code>
* <code>FAILED</code>
* <code>MISSED</code>
* <code>DIED</code>
* <code>CONFLICTED</code>
* <code>OVERLAPPED</code>
* <code>ABANDONED</code>
* <code>CONFLICT_MISSED</code>
* <code>CHAIN_SKIPPED</code>
* <code>PENDING</code>

'''Job Submission Mode '''
* <code>CHAIN_SUBMISSION</code>
* <code>CONFLICTED_RECOVERY</code>

'''Job [[Job_Features#Recovery | Recovery Type]]'''
* <code>NONE</code>
* <code>LAST</code>
* <code>ALL</code>
* <code>CONFLICTED</code>

'''Job Parameter Type'''
* <code>STRING</code>
* <code>INTEGER</code>
* <code>LONG</code>
* <code>DECIMAL</code>
* <code>BOOLEAN</code>
* <code>CLASS</code>

'''Job Chain [[Job_Features#Execution_Statuses | Status]]'''
* <code>ABANDONED</code>
* <code>COMPLETED</code>
* <code>CONDITIONAL</code>
* <code>DIED</code>
* <code>FAILED</code>
* <code>MISSED</code>
* <code>OVERLAPPED</code>
* <code>CHAIN_SKIPPED</code>

'''Job Chain/Conditional Job Notification Operator'''
* <code>EQUALS</code>
* <code>NOT_EQUALS</code>
* <code>IN</code>
* <code>NOT_IN</code>
* <code>EXISTS</code>
* <code>NOT_EXISTS</code>
* <code>REGEXP</code>
* <code>STARTS_WITH</code>
* <code>ENDS_WITH</code>
* <code>CONTAINS</code>
* <code>GREATER_THAN</code>
* <code>LESS_THAN</code>
* <code>GREATER_THAN_OR_EQUAL</code>
* <code>LESS_THAN_OR_EQUAL</code>

'''Subscription/Log [[Event_Notifications#Category-Based_Subscriptions | Category]]'''
* <code>DASHBOARD</code>
* <code>DISPATCH</code>
* <code>JOB</code>
* <code>JOB_CHAIN</code>
* <code>JOB_CONFIG</code>
* <code>JOB_QUEUER</code>
* <code>JOB_RECOVERY</code>
* <code>JOB_RUN</code>
* <code>JOB_SPAWNER</code>
* <code>LICENCE</code>
* <code>SYSTEM_PARAMETER</code>
* <code>QUEUE</code>

'''Subscription/Log Level'''
* <code>FATAL</code>
* <code>ERROR</code>
* <code>WARNING</code>
* <code>INFO</code>
* <code>DEBUG</code>
* <code>TRACE</code>

'''User Role'''
* <code>ADMIN</code>
* <code>WRITE</code>
* <code>OPERATOR</code>
* <code>AUTHOR</code>
* <code>API</code>
* <code>LIMITED_READ</code>
As of ''Obsidian 5.0.0'', these are class constants instead of enums to support [[Admin_User_Management#Job_Folder_Rights|dynamic roles]].

'''Subscription Job Status'''
* <code>COMPLETED</code>
* <code>CONDITIONAL</code>
* <code>DIED</code>
* <code>FAILED</code>
* <code>RECOVERY</code>

'''Sort Direction'''
* <code>ASC</code>
* <code>DESC</code>

'''Event Hook Action'''
* <code>PAUSE</code>
* <code>RESUME</code>

'''Job Stats [[Job_Features#Execution_Statuses | Status]]'''
* <code>COMPLETED</code>
* <code>FAILED</code>
* <code>MISSED</code>
* <code>DIED</code>
* <code>OVERLAPPED</code>
* <code>ABANDONED</code>
* <code>CONFLICT_MISSED</code>
* <code>CHAIN_SKIPPED</code>

'''Job Stats Unit'''
* <code>SECONDS</code>
* <code>MINUTES</code>
* <code>HOURS</code>

'''Job Stats Duration'''
* <code>DAY</code>
* <code>TWO_DAY</code>
* <code>THREE_DAY</code>
* <code>FIVE_DAY</code>
* <code>WEEK</code>
* <code>MONTH</code>
* <code>TWO_MONTH</code>
* <code>THREE_MONTH</code>
* <code>SIX_MONTH</code>
* <code>YEAR</code>

= JobManager API =

[https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html JobManager] is used to manage job configurations, conflicts and chaining. If you are looking for ways to view or manage job runtimes, see [[#RuntimeManager API|RuntimeManager]].

== List Jobs ==

You can list or search existing jobs using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#listJobs(com.carfey.ops.api.bean.job.JobListingParameters) JobManager.listJobs()], which accepts an optional [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobListingParameters.html JobListingParameters] and returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobListing.html JobListing].

You can limit the returned jobs by providing a <code>JobListingParameters</code>.

'''JobListingParameters Fields'''

{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| activeStatuses || N || Restricts the preview to the selected a valid [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/JobStatus.html 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: [[REST_Endpoints#GET_a_list_of_jobs|GET a list of jobs]]

== Get a Job's Details ==

To get full job information, including all historical schedules and parameter information, call [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#getJob(long) JobManager.getJob()] with the appropriate job ID. The method will return a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobDetail.html JobDetail], or throw a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if it does not exist.

REST equivalent: [[REST_Endpoints#GET_details_of_an_existing_job|GET details of an existing job]]

== Add a Job ==

You can add a new job using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#addJob(com.carfey.ops.api.bean.job.JobCreationRequest,java.lang.String) JobManager.addJob()], which accepts a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobCreationRequest.html JobCreationRequest]. The method will return the job as a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobDetail.html 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 <code>com.carfey.jdk.lang.DateTime.clearSeconds()</code>, which returns a copy of the date with seconds removed.

'''JobCreationRequest Fields '''
{| class="wikitable leftAlignTable"
! 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 [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/JobRecoveryType.html JobRecoveryType] to use for the job.
|-
| state || Y || Initial schedule's [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/JobStatus.html JobStatus].
|-
| schedule || Y/N || If state is <code>ENABLED</code>, the mandatory cron-style schedule for the job. If not <code>ENABLED</code>, 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 <code>DISABLED</code>.
|-
| endDate || N || Optional end date for the initial schedule, with no seconds specified. If set, the job will become <code>DISABLED</code> 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 <code>@Configuration</code> annotation, a job will fail to create unless they are supplied. Otherwise, this field is optional. Parameter definitions must have values for <code>name</code>, <code>type</code> and <code>value</code>, where <code>type</code> is a valid [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/ParameterType.html 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. <code>{{globalParameterName}}</code>).
|}

REST equivalent: [[REST_Endpoints#POST_a_new_job|POST a new job]]

== Update a Job ==

You can update an existing job using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#updateJob(long,com.carfey.ops.api.bean.job.JobUpdateRequest,java.lang.String) JobManager.updateJob()], which accepts a job ID and a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobUpdateRequest.html JobUpdateRequest]. The method will return the new state of the job as a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobDetail.html JobDetail], or throw a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html 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|Add a New Schedule to a Job]].

This method will only update fields that are supplied in the <code>JobUpdateRequest</code>. You may update one or more fields as desired.

'''JobUpdateRequest Format'''
{| class="wikitable leftAlignTable"
! 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 [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/JobRecoveryType.html 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 <code>@Configuration</code> 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 <code>name</code>, <code>type</code> and <code>value</code>, where <code>type</code> is a valid [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/ParameterType.html 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. <code>{{globalParameterName}}</code>).
|}

REST equivalent: [[REST_Endpoints#PUT_updates_to_an_existing_job|PUT updates to an existing job]]

== Delete a Job ==

You can delete an existing job using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#deleteJob(long,boolean,java.lang.String) JobManager.deleteJob()], which accepts a job ID and ''cascade'' flag. The method will return the final state of the job before deletion as a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobDetail.html JobDetail], or throw a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if it does not exist.

'''Parameters'''
{| class="wikitable leftAlignTable"
! 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: [[REST_Endpoints#DELETE_an_existing_job|DELETE an existing job]]

== List a Job's Schedules ==

You can access the full history of a job's schedules via [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#listJobSchedules(long) JobManager.listJobSchedules()] which accepts an optional [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobScheduleListingParameters.html JobScheduleListingParameters] and returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobScheduleListing.html JobScheduleListing].

Note that the full schedule history can also be obtained via the schedules field of the [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobDetail.html JobDetail] returned by [[#Get_a_Job's_Details|JobManager.getJob()]].

REST equivalent: [[REST_Endpoints#GET_a_list_of_an_existing_job.27s_schedules|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 [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#addJobSchedule(long,com.carfey.ops.api.bean.schedule.ScheduleCreationRequest,java.lang.String) JobManager.addJobSchedule()], which accepts a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/schedule/ScheduleCreationRequest.html 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 <code>com.carfey.jdk.lang.DateTime.clearSeconds()</code>, which returns a copy of the date with seconds removed.

'''ScheduleCreationRequest Fields '''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| state || Y || The schedule's [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/JobStatus.html JobStatus].
|-
| schedule || Y/N || If state is <code>ENABLED</code>, the mandatory cron-style schedule for the job. If not <code>ENABLED</code>, 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 <code>DISABLED</code>.
|-
| endDate || N || Optional end date for the schedule, with no seconds specified. If set, the job will become <code>DISABLED</code> after this date passes.
|-
| customCalendarId || N || Optional custom calendar for schedule.
|}

REST equivalent: [[REST_Endpoints#POST_a_new_schedule_to_an_existing_job|POST a new schedule to an existing job]]

== List Job Chains ==

You can list or search existing job chains using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#listChains(com.carfey.ops.api.bean.job.JobChainListingParameters) JobManager.listChains()], which accepts an optional [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobChainListingParameters.html JobChainListingParameters] and returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobChainListing.html JobChainListing].

You can limit the returned job chains by providing a <code>JobChainListingParameters</code> instance with the fields below.

'''JobChainListingParameters Fields'''

{| class="wikitable leftAlignTable"
! 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: [[REST_Endpoints#GET_a_list_of_job_chains| GET a list of job chains]]

== Add a Job Chain ==

You can add a new job chain using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#addChain(com.carfey.ops.api.bean.job.JobChainUpdateRequest,java.lang.String) JobManager.addChain()], which accepts a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobChainUpdateRequest.html JobChainUpdateRequest]. The method will return a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobChain.html JobChain].

'''JobChainUpdateRequest Fields'''

{| class="wikitable leftAlignTable"
! 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 [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/JobChainStatus.html JobChainStatus]. Note that <code>CONDITIONAL</code> and <code>COMPLETED</code> types cannot be used on the same chain.
|-
| resultConditions || Y/N || Conditions based on job results that apply to the <code>CONDITIONAL</code> 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 <code>variableName</code>, an <code>operator</code> as a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/JobChainConditionOperator.html JobChainConditionOperator], and for most operators, a list of <code>values</code>. The <code>EXISTS</code> and <code>NOT EXISTS</code> operators do not use values, so they must not be supplied. Operators <code>IN</code> and <code>NOT IN</code> support one or more values, and all other operators accept a single value in the <code>values</code> list.
|}

REST equivalent: [[REST_Endpoints#POST_a_new_job_chain| POST a new job chain]]

== Update a Job Chain ==

You can add update an existing job chain using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#updateChain(long,com.carfey.ops.api.bean.job.JobChainUpdateRequest,java.lang.String) JobManager.updateChain()], which accepts a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobChainUpdateRequest.html JobChainUpdateRequest]. The method will return the updated [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobChain.html JobChain].

The format of <code>JobChainUpdateRequest</code> is identical to that of [[#Add_a_Job_Chain|Add a Job Chain]].

REST equivalent: [[REST_Endpoints#PUT_updates_to_an_existing_job_chain| PUT updates to an existing job chain]]

== Delete a Job Chain ==

''As of Obsidian 2.6.''

You can delete an existing job chain using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#deleteChain(long,java.lang.String) JobManager.deleteChain()]. The method will return the final state of the job chain before deletion as a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobChain.html JobChain], or throw a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if it does not exist.

REST equivalent: [[REST_Endpoints#DELETE_an_existing_job_chain| DELETE an existing job chain]]

== List Conflicts ==

You can access all configured job conflict configuration via [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#listConflicts() JobManager.listConflicts()], which will return [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/ConflictListing.html ConflictListing].

The return value includes all job conflict sets, with each set in order of priority. Non-conflicted jobs are also returned.

REST equivalent: [[REST_Endpoints#GET_a_list_of_job_conflicts| GET a list of job conflicts]]

== Update Conflicts ==

To update the configured job conflict sets, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#updateConflicts(com.carfey.ops.api.bean.job.ConflictUpdateRequest,java.lang.String) JobManager.updateConflicts()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/ConflictUpdateRequest.html ConflictUpdateRequest] which will return the updated [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/ConflictListing.html 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'''
{| class="wikitable leftAlignTable"
! 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: [[REST_Endpoints#PUT_updates_to_job_conflicts| PUT updates to job conflicts]]

== List a Specific Job's Conflicts ==

You can return conflicts for a specific job with [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#listJobConflicts(long) JobManager.listJobConflicts(long)], which will return [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobConflictListing.html 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: [[REST_Endpoints#GET_a_list_of_conflicts_for_a_specific_job| GET a list of conflicts for a specific job]]

== Update Global Parameters ==

To update the configured global parameters, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#updateGlobalParameters(com.carfey.ops.api.bean.job.GlobalParameterUpdateRequest,java.lang.String) JobManager.updateGlobalParameters()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/GlobalParameterUpdateRequest.html GlobalParameterUpdateRequest] which will return the updated [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/GlobalParameterListing.html 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'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| parameters || N || Zero or more [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/GlobalParameter.html GlobalParameter] instances. Each parameter must have values for <code>name</code>, <code>type</code> and <code>values</code>, where <code>type</code> is a valid [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/ParameterType.html ParameterType].
|}

REST equivalent: [[REST_Endpoints#PUT_updates_to_global_parameters| PUT updates to global parameters]]

== List Global Parameters ==

You can list all configured global parameters using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#listGlobalParameters() listGlobalParameters()], which will return a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/GlobalParameterListing.html GlobalParameterListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_configured_global_parameters| GET a list of configured global parameters]]

== List Job Folders ==

You can list all used job folders using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#listJobFolders() listJobFolders()], which will return a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobFolderListing.html JobFolderListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_job_folders| GET a list of job folders]]

= RuntimeManager API =

[https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html 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 API|JobManager]].

== List Scheduled Runtimes ==

To get a list of scheduled or completed job runtimes (i.e. history), use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html#listRuntimes(com.carfey.ops.api.bean.history.RuntimeListingParameters) RuntimeManager.listRuntimes()], which accepts an optional [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/RuntimeListingParameters.html RuntimeListingParameters] instance. As of Obsidian 3.5, the results in the returned [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/RuntimeListing.html RuntimeListing] are ordered by scheduled time descending, unless overridden by the <code>sort</code> parameter.

'''Note:''' The <code>nextPageStartKey</code> field in the <code>RuntimeListing</code> indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen, or the <code>quantity</code> parameter). To fetch the next page of results, invoke the same method with the <code>startKey</code> field on <code>RuntimeListingParameters</code> set to the returned <code>nextPageStartKey</code>.

'''RuntimeListingParameters Fields'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobIds || N || Restricts the search to the selected jobs.
|-
| statuses || N || Restricts the search to the selected [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/JobRuntimeStatus.html 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 <code>nextPageStartKey</code>.
|-
| quantity || N || Indicates the maximum number of results to return. This overrides the <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen. ''As of Obsidian 3.5.0.''
|-
| sort || N || A valid [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/SortDirection.html 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: [[REST_Endpoints#GET_a_list_of_scheduled_runtimes_.28supports_multiple_jobs.29|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 [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html#getRuntime(long) RuntimeManager.getRuntime()]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/RuntimeResult.html RuntimeResult], which has a nested [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/RuntimeDetail.html RuntimeDetail] containing the full job output and one-time run parameters, or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if it does not exist.

REST equivalent: [[REST_Endpoints#GET_details_of_an_existing_scheduled_.28or_completed.29_job_runtime|GET details of an existing scheduled or completed runtime]]

== Preview Runtimes ==

To preview future runtimes for one or more jobs, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html#listRuntimePreviews(com.carfey.ops.api.bean.schedule.RuntimePreviewParameters) RuntimeManager.listRuntimePreview()], which accepts an optional [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/schedule/RuntimePreviewParameters.html RuntimePreviewParameters] instance to filter the results. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/schedule/RuntimePreviewListing.html 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 <code>RuntimePreviewListing</code> indicates that there were too many results to return (i.e. exceeded maxRecords as configured in the [[Admin Scheduler Settings|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'''
{| class="wikitable leftAlignTable"
! 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: [[REST_Endpoints#GET_a_list_of_runtime_previews_.28supports_multiple_jobs.29|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 [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html#submitRuntime(long,com.carfey.ops.api.bean.history.RuntimeSubmissionRequest,java.lang.String) RuntimeManager.submitRuntime()]. A [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/RuntimeSubmissionRequest.html RuntimeSubmissionRequest] must be supplied. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/RuntimeSubmissionResult.html RuntimeSubmissionResult] if it succeeds, or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified job ID does not exist.

'''Note:''' The job must be in a valid state to allow for execution (i.e. <code>UNSCHEDULED_ACTIVE</code>, <code>ENABLED</code>, or <code>AD_HOC_ACTIVE</code>).

'''RuntimeSubmissionRequest Fields'''
{| class="wikitable leftAlignTable"
! 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 <code>name</code>, <code>type</code> and <code>value</code>, where <code>type</code> is a valid [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/ParameterType.html 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: [[REST_Endpoints#POST_a_new_scheduled_runtime_for_an_existing_job_.28i.e._submit_a_one-time_or_ad_hoc_run.29|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 [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html#deleteOneTimeRun(long,com.carfey.ops.api.bean.history.OneTimeRunDeleteRequest,java.lang.String) RuntimeManager.deleteOneTimeRun()]. A [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/OneTimeRunDeleteRequest.html OneTimeRunDeleteRequest] must be supplied. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/OneTimeDeletionResult.html OneTimeDeletionResult] if it succeeds, or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html 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'''
{| class="wikitable leftAlignTable"
! 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: [[REST_Endpoints#DELETE_a_future_scheduled_runtime|DELETE a future scheduled runtime]]

== Resubmit a Failed Job Runtime ==

If a job execution fails and you wish to resubmit it, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html#resubmitRuntime(long,java.lang.String) RuntimeManager.resubmitRuntime()] with the appropriate job runtime ID. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/RuntimeResubmissionResult.html RuntimeResubmissionResult] if the action succeeds, or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified job runtime ID does not exist.

REST equivalent: [[REST_Endpoints#POST_a_resubmission_request_for_a_failed_job_runtime|POST a resubmission request for a failed job runtime]]

== Interrupt a Running Job Runtime ==

To interrupt a currently running job runtime, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html#interruptRuntime(long,java.lang.String) RuntimeManager.interruptRuntime()] with the appropriate job runtime ID. A [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/JobInterruptResult.html JobInterruptResult] is returned upon success, or a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html 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 [[Implementing_Jobs#Interruptable_Jobs|Interruptable Jobs]] for full details.

REST equivalent: [[REST_Endpoints#POST_an_interruption_request_to_kill_a_running_job|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 [[Implementing_Jobs#Async_Jobs | Async Job]], use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html#setAsyncRuntimeResults(long,com.carfey.ops.api.bean.history.AsyncJobRuntimeResultsRequest,java.lang.String) RuntimeManager.setAsyncRuntimeResults()] with the appropriate job runtime ID. An [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/AsyncJobRuntimeResultsRequest.html AsyncJobRuntimeResultsRequest] is returned upon success, or a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html 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 <code>COMPLETED</code> or <code>FAILED</code> as per [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/AsyncJobRuntimeStatus.html AsyncJobRuntimeStatus]. If <code>FAILED</code>, then a finalizationException must be provided. If <code>COMPLETED</code>, finalizationException must be null.

REST equivalent: [[REST_Endpoints#POST_async_results|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 [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html#listJobsDashboard(com.carfey.ops.api.bean.history.JobDashboardListingParameters) RuntimeManager.listJobsDashboard()], which accepts an optional [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/JobDashboardListingParameters.html JobDashboardListingParameters] instance. The results in the returned [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/JobDashboardListing.html JobDashboardListing] are ordered by scheduled time descending, unless overridden by the <code>sort</code> parameter.

'''Note:''' The <code>nextPageStartKey</code> field in the <code>JobDashboardListing</code> indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen, or the <code>quantity</code> parameter). To fetch the next page of results, invoke the same method with the <code>startKey</code> field on <code>JobDashboardListingParameters</code> set to the returned <code>nextPageStartKey</code>.

'''JobDashboardListingParametersFields'''
{| class="wikitable leftAlignTable"
! 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 <code>nextPageStartKey</code>.
|-
| quantity || N || Indicates the maximum number of results to return. This overrides the <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen.
|-
| sort || N || A valid [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/SortDirection.html SortDirection], which controls the ordering of returned results. In all cases, the job scheduled time is used to sort results.
|}

REST equivalent: [[REST_Endpoints#GET_a_list_of_the_latest_scheduled_runtime_by_job_.28supports_multiple_jobs.29|GET a list of the latest scheduled runtime by job]]

= HostManager API =

[https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html HostManager] is used to manage and view scheduling hosts and see additional host details including event hooks.

== List Scheduling Hosts ==

To get a list of known hosts which are running or recently shut down abnormally, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#listHosts() HostManager.listHosts()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/host/HostListing.html HostListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_known_scheduling_hosts|GET a list of known scheduling hosts]]

== Get a Specific Host ==

To get details on a host by ID or name, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#getHost(long) HostManager.getHost(id)] or [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#getHost(java.lang.String) or HostManager.getHost(String)].

The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/host/HostDetail.html HostDetail], or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified host ID or name does not exist.

REST equivalent: [[REST_Endpoints#GET_details_on_an_existing_scheduling_host|GET details on an existing scheduling host]]

== Get Licence Health by Host ==

'''As of Obsidian 4.3.0'''

Identical to [[Embedded_API#Get_a_Specific_Host | 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 [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#getLicenceHealth(long) HostManager.getLicenceHealth(id)] or [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#getLicenceHealth(java.lang.String) or HostManager.getLicenceHealth(String)].

The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/host/HostDetail.html HostDetail], or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified host ID or name does not exist.

REST equivalent: [[REST_Endpoints#GET_licence_details_on_an_existing_scheduling_host|GET licence details on an existing scheduling host]]

== Update a Host ==

To enable or disable a scheduling host, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#updateHost(long,com.carfey.ops.api.bean.host.HostUpdateRequest,java.lang.String) HostManager.updateHost(long)] or [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#updateHost(java.lang.String,com.carfey.ops.api.bean.host.HostUpdateRequest,java.lang.String) HostManager.updateHost(String)] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/host/HostUpdateRequest.html HostUpdateRequest]. Both methods return a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/host/HostDetail.html HostDetail], or throw a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified host ID or name does not exist.

'''HostUpdateRequest Fields'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| enabled || Y || Should this host should be enabled?
|}

REST equivalent: [[REST_Endpoints#PUT_updates_to_an_existing_scheduling_host|PUT updates to an existing scheduling host]]

== List Event Hooks ==
''As of Obsidian 5.4.0''

To get a list of all event hooks against all hosts, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#listEventHooksByHost() HostManager.listEventHooksByHost()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/host/EventHookListing.html EventHookListing].

REST equivalent: [[REST_Endpoints#GET_event_hooks|GET a list of event hooks]]

== Get Event Hooks on a specific Host ==
''As of Obsidian 5.4.0''

To get event hooks on a host by ID or name, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#listEventHooksByHost(long) HostManager.listEventHooksByHost(id)] or [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#listEventHooksByHost(java.lang.String) or HostManager.listEventHooksByHost(String)].

The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/host/EventHookListing.html EventHookListing], or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified host ID or name does not exist.

REST equivalent: [[REST_Endpoints#GET_event_hooks_on_host|GET event hooks on host]]

== Event Hook Resume or Pause ==
''As of Obsidian 5.5.0''

To trigger a pause or resume of event hooks, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#updateEventHook(com.carfey.ops.api.bean.host.UpdateEventHookRequest,java.lang.String) HostManager.updateEventHook(UpdateEventHookRequest,String)] which accepts an [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/host/UpdateEventHookRequest.html UpdateEventHookRequest].

The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/host/EventHookListing.html EventHookListing], or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified host ID/name does not exist or the event hook does not exist on the specified host.

REST equivalent: [[REST_Endpoints#POST_event_hook_pause_or_resume|POST event hook pause/resume]]

= CustomCalendarManager API =

The [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/CustomCalendarManager.html CustomCalendarManager] allows for managing of [[Job_Features#Custom_Calendars|Custom Calendars]].

== List Calendars ==

To list existing custom calendars, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/CustomCalendarManager.html#listCalendars() CustomCalendarManager.listCalendars()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/calendar/CustomCalendarListing.html CustomCalendarListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_custom_calendars|GET a list of custom calendars]]

== Get Details on a Calendar ==

To get details on an existing custom calendar, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/CustomCalendarManager.html#getCalendar(long) CustomCalendarManager.getCalendar()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/calendar/CustomCalendar.html CustomCalendar], or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified calendar ID does not exist.

REST equivalent: [[REST_Endpoints#GET_details_on_an_existing_custom_calendar|GET details on an existing custom calendar]]

== Add a Calendar ==

To add a new custom calendar, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/CustomCalendarManager.html#addCalendar(com.carfey.ops.api.bean.calendar.CustomCalendarUpdateRequest,java.lang.String) CustomCalendarManager.addCalendar()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/calendar/CustomCalendarUpdateRequest.html CustomCalendarUpdateRequest]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/calendar/CustomCalendar.html CustomCalendar].

'''CustomCalendarUpdateRequest Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| name|| Y || Calendar name
|-
| dates|| Y || Dates to exclude
|}

REST equivalent: [[REST_Endpoints#POST_a_new_custom_calendar|POST a new custom calendar]]

== Update a Calendar ==

To update an existing calendar, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/CustomCalendarManager.html#updateCalendar(long,com.carfey.ops.api.bean.calendar.CustomCalendarUpdateRequest,java.lang.String) CustomCalendarManager.updateCalendar()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/calendar/CustomCalendarUpdateRequest.html CustomCalendarUpdateRequest]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/calendar/CustomCalendar.html CustomCalendar] or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified calendar ID does not exist.

The format of <code>CustomCalendarUpdateRequest</code> is identical to that of [[#Add_a_Calendar|Add a Calendar]].

REST equivalent: [[REST_Endpoints#PUT_updates_to_an_existing_custom_calendar|PUT updates to an existing custom calendar]]

== Delete a Calendar ==

''Available as of version 3.0.''

You can delete an existing job using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/CustomCalendarManager.html#deleteCalendar(long,java.lang.String) CustomCalendarManager.deleteCalendar()]. The method will return the final state of the calendar before deletion as a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/calendar/CustomCalendar.html CustomCalendar] or throw a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified calendar ID does not exist.

REST equivalent: [[REST_Endpoints#DELETE_an_existing_custom_calendar|DELETE an existing custom calendar]]

= NotificationManager API =

''As of Obsidian 3.0''

The [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html NotificationManager] allows for managing of Obsidian [[Event_Notifications|event notifications]], including subscribers and templates used to send notifications, and allows searching of triggered notifications.

== List Subscribers ==

To list existing subscribers, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#listSubscribers() NotificationManager.listSubscribers()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/SubscriberListing.html SubscriberListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_subscribers|GET a list of subscribers]]

== Get Details on a Subscriber ==

To get details on an existing subscriber, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#getSubscriber(long) NotificationManager.getSubscriber()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/Subscriber.html Subscriber], or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified subscriber ID does not exist.

REST equivalent: [[REST_Endpoints#GET_details_of_an_existing_subscriber|GET details of an existing subscriber]]

== Add a Subscriber ==

To add a new subscriber, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#addSubscriber(com.carfey.ops.api.bean.notification.SubscriberUpdateRequest,java.lang.String) NotificationManager.addSubscriber()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/SubscriberUpdateRequest.html SubscriberUpdateRequest]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/Subscriber.html Subscriber].

'''SubscriberUpdateRequest Format'''
{| class="wikitable leftAlignTable"
! 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 [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/GeneralSubscriptionUpdateRequest.html GeneralSubscriptionUpdateRequest]. Each item contains a required subscription [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/Category.html Category] and [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/LogLevel.html LogLevel] in the <code>category</code> and <code>level</code> fields respectively, an optional <code>jobId</code> and an optional <code>active</code> flag which defaults to false.

'''Note:''' Only <code>ERROR</code>, <code>WARNING</code> AND <code>INFO</code> are valid values for <code>level</code>. Only <code>JOB</code>, <code>JOB_CHAIN</code>, <code>JOB_CONFIG</code>, <code>JOB_RECOVERY</code>, <code>LICENCE</code>, <code>QUEUE</code>, <code>SYSTEM_PARAMETER</code> and null are valid values for <code>category</code>.
|-
| jobExecutionSubscriptions || N || Zero or more instances of [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/JobExecutionSubscriptionUpdateRequest.html JobExecutionSubscriptionUpdateRequest]. Each item contains a required <code>triggerStates</code> field which uses the [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/SubscriptionJobStatus.html SubscriptionJobStatus] enum. Note that <code>CONDITIONAL</code> and <code>COMPLETED</code> types cannot be used on the same chain.

If the <code>CONDITIONAL</code> state is selected, at least one [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/JobSubscriptionCondition.html JobSubscriptionCondition] must be supplied in the <code>resultConditions</code> field. Result conditions consist of a <code>variableName</code>, an <code>operator</code> using the [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/JobSubscriptionConditionOperator.html JobSubscriptionConditionOperator] enum, and for most operators, a list of <code>values</code>. The <code>EXISTS</code> and <code>NOT EXISTS</code> operators do not use values, so they must not be supplied. Operators <code>IN</code> and <code>NOT IN</code> support one or more values, and all other operators accept a single value in the <code>values</code> list.

In addition, two additional optional fields control which jobs the subscription applies to. <code>jobIds</code> is used to specify specific jobs, while <code>allJobs</code> may be set to true to make it apply to all jobs. If <code>jobIds</code> is supplied and <code>allJobs</code> is set to true, <code>jobIds</code> will be ignored.

Finally, the <code>active</code> flag may be supplied which defaults to true.
|}

REST equivalent: [[REST_Endpoints#POST_a_new_subscriber|POST a new subscriber]]

== Update a Subscriber ==

To update an existing subscriber, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#updateSubscriber(long,com.carfey.ops.api.bean.notification.SubscriberUpdateRequest,java.lang.String) NotificationManager.updateSubscriber()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/SubscriberUpdateRequest.html SubscriberUpdateRequest]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/Subscriber.html Subscriber] or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified subscriber ID does not exist.

The format of <code>SubscriberUpdateRequest</code> is identical to that of [[#Add_a_Subscriber|Add a Subscriber]].

REST equivalent: [[REST_Endpoints#PUT_updates_to_an_existing_subscriber|PUT updates to an existing subscriber]]

== Delete a Subscriber ==

You can delete an existing subscriber using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#deleteSubscriber(long,java.lang.String) NotificationManager.deleteSubscriber()]. The method will return the final state of the subscriber before deletion as a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/Subscriber.html Subscriber], or throw a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if it does not exist.

REST equivalent: [[REST_Endpoints#DELETE_an_existing_subscriber| DELETE an existing subscriber]]

== List Templates ==

To list existing notification templates, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#listTemplates() NotificationManager.listTemplates()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/TemplateListing.html TemplateListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_templates|GET a list of templates]]

== Get Details on a Template ==

To get details on an existing template, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#getTemplate(long) NotificationManager.getTemplate()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/Template.html Template], or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified template ID does not exist.

REST equivalent: [[REST_Endpoints#GET_details_of_an_existing_template|GET details of an existing template]]

== Add a Template ==

To add a new template, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#addTemplate(com.carfey.ops.api.bean.notification.TemplateUpdateRequest,java.lang.String) NotificationManager.addTemplate()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/TemplateUpdateRequest.html TemplateUpdateRequest]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/Template.html Template].

'''TemplateUpdateRequest Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| name || Y || Unique name of the template.
|-
| active || N || Whether the template is active. Defaults to false.
|-
| category || N || The [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/Category.html Category] for the template, or null if it is the default generic template. Supports multiple values. Not all categories are supported. Only <code>JOB</code>, <code>JOB_CHAIN</code>, <code>JOB_CONFIG</code>, <code>JOB_RECOVERY</code>, <code>LICENCE</code>, <code>QUEUE</code>, <code>SYSTEM_PARAMETER</code> 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 [[Email_Templates|Mustache template]] for the subject.
|-
| bodyTemplate || Y || A valid [[Email_Templates|Mustache template]] for the body.
|}

REST equivalent: [[REST_Endpoints#POST_a_new_template|POST a new template]]

== Update a Template ==

To update an existing template, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#updateTemplate(long,com.carfey.ops.api.bean.notification.TemplateUpdateRequest,java.lang.String) NotificationManager.updateTemplate()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/TemplateUpdateRequest.html TemplateUpdateRequest]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/Template.html Template] or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified template ID does not exist.

The format of <code>TemplateUpdateRequest</code> is identical to that of [[#Add_a_Template|Add a Template]].

REST equivalent: [[REST_Endpoints#PUT_updates_to_an_existing_template|PUT updates to an existing template]]

== Delete a Template ==

You can delete an existing template using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#deleteTemplate(long,java.lang.String) NotificationManager.deleteTemplate()]. The method will return the final state of the template before deletion as a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/Template.html Template], or throw a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if it does not exist.

REST equivalent: [[REST_Endpoints#DELETE_an_existing_template| DELETE an existing template]]

== List Notifications==

To get a list notifications, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#listNotifications(com.carfey.ops.api.bean.notification.NotificationListingParameters) NotificationManager.listNotifications()], which accepts an optional [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/NotificationListingParameters.html NotificationListingParameters] instance. The results in the returned [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/NotificationListing.html 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 <code>nextPageStartKey</code> field in the <code>LogListing</code> indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen). To fetch the next page of results, invoke the same method with the <code>startKey</code> field on <code>LogListingParameters</code> set to the returned <code>nextPageStartKey</code>.

'''LogListingParameters Fields'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| category || N || One or more notification log [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/Category.html Category] values used to limit the returned results.
|-
| level || N || One or more notification log [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/LogLevel.html 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 <code>nextPageStartKey</code>.
|}

REST equivalent: [[REST_Endpoints#GET_a_list_of_notifications|GET a list of notifications]]

== Get Details on a Notification ==

To get details on a single notification entry use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#getNotification(long) NotificationManager.getNotification()]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/Notification.html Notification] or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html 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: [[REST_Endpoints#GET_details_of_an_existing_notification|GET details of an existing notification]]

= LogManager API =

''As of Obsidian 3.0''

[https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/LogManager.html LogManager] is used to retrieve event log entries.

== List Log Entries==

To get a list log entries, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/LogManager.html#listLogs(com.carfey.ops.api.bean.log.LogListingParameters) LogManager.listLogs()], which accepts an optional [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/log/LogListingParameters.html LogListingParameters] instance. The results in the returned [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/log/LogListing.html LogListing] are ordered roughly according to when they were created, but ordering is not guaranteed to be in order of created time.

'''Note:''' The <code>nextPageStartKey</code> field in the <code>LogListing</code> indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen). To fetch the next page of results, invoke the same method with the <code>startKey</code> field on <code>LogListingParameters</code> set to the returned <code>nextPageStartKey</code>.

'''LogListingParameters Fields'''
{| class="wikitable leftAlignTable"
! 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 [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/Category.html Category] values used to limit the returned results.
|-
| level || N || One or more log [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/LogLevel.html 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 <code>nextPageStartKey</code>.
|}

REST equivalent: [[REST_Endpoints#GET_a_list_of_logs|GET a list of logs]]

== Get Details on a Log Entry ==

To get details on a single log entry use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/LogManager.html#getLog(long) LogManager.getLog()]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/log/Log.html Log] or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if it does not exist.

REST equivalent: [[REST_Endpoints#GET_details_of_an_existing_log|GET details of an existing log]]

= SystemParameterManager API =

''As of Obsidian 3.0''

The [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemParameterManager.html SystemParameterManager] allows for listing and updating Obsidian [[Admin_Scheduler Settings|scheduler settings]].

== List System Parameters ==

To list editable system parameters, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemParameterManager.html#listParameters() SystemParameterManager.listParameters()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/SystemParameterListing.html SystemParameterListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_system_parameters|GET a list of system parameters]]

== Get Details on a System Parameter ==

To get details on specific system parameter, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemParameterManager.html#getParameter(java.lang.String) SystemParameterManager.getParameter()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/SystemParameter.html SystemParameter], or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified system parameter does not exist.

REST equivalent: [[REST_Endpoints#GET_details_of_a_system_parameter|GET details of system parameter]]

== Update a System Parameter ==

To update a system parameter's value, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemParameterManager.html#updateParameter(java.lang.String,java.lang.String,java.lang.String) 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 [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/SystemParameter.html SystemParameter] or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified system parameter does not exist.

REST equivalent: [[REST_Endpoints#PUT_updates_to_a_system_parameter|PUT updates to a system parameter]]

= UserManager API =

''As of Obsidian 3.0''

The [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/UserManager.html UserManager] allows for managing of Obsidian [[Admin_User_Management|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 [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/UserManager.html#listUsers() UserManager.listUsers()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/UserListing.html UserListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_users|GET a list of users]]

== Get Details on a User ==

To get details on an existing user, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/UserManager.html#getUser(long) UserManager.getUser()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/User.html User], or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified user ID does not exist.

REST equivalent: [[REST_Endpoints#GET_details_of_an_existing_user|GET details of an existing user]]

== Add a User ==

To add a new user, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/UserManager.html#addUser(com.carfey.ops.api.bean.user.UserCreationRequest,java.lang.String) UserManager.addUser()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/UserCreationRequest.html UserCreationRequest]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/User.html User].

'''UserCreationRequest Format'''
{| class="wikitable leftAlignTable"
! 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 [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/Role.html Role] values. Supplying no roles indicates it is a normal read-only user.
|-
| password || Y || A password at least 6 characters long.
|}

REST equivalent: [[REST_Endpoints#POST_a_new_user|POST a new user]]

== Update a User ==

To update an existing user, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/UserManager.html#updateUser(long,com.carfey.ops.api.bean.user.UserUpdateRequest,java.lang.String) UserManager.updateUser()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/UserUpdateRequest.html UserUpdateRequest]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/User.html User] or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html 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'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| active || N || Whether the user is enabled. Defaults to the existing active state.
|-
| roles || N || Zero or more [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/Role.html 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: [[REST_Endpoints#PUT_updates_to_an_existing_user|PUT updates to an existing user]]

== Delete a User ==

You can delete an existing user using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/UserManager.html#deleteUser(long,java.lang.String) UserManager.deleteUser()]. The method will return the final state of the user before deletion as a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/User.html User], or throw a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if it does not exist.

REST equivalent: [[REST_Endpoints#DELETE_an_existing_user| DELETE an existing user]]

== List Known MFA Users ==

''As of Obsidian 5.0''

To list all known MFA users, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/UserManager.html#listMfaUsers() UserManager.listMfaUsers()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/MfaUserListing.html MfaUserListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_known_MFA_users|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 [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/UserManager.html#resetMfa(com.carfey.ops.api.bean.user.ResetMfaRequest,java.lang.String) UserManager.resetMfa()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/ResetMfaRequest.html ResetMfaRequest]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/MfaUserListing.html MfaUserListing] which echoes the user names that were reset.

REST equivalent: [[REST_Endpoints#PUT_MFA_user_resets| PUT MFA user resets]]

= SystemRestore API =

''As of Obsidian 3.0''

The [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemRestoreManager.html SystemRestoreManager] allows for importing and exporting full Obsidian configuration. See [[Initializing_and_Restoring|Initializing and Restoring]] for more details.

== Get System Restore Configuration ==

To extract the current system restore configuration, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemRestoreManager.html#getConfiguration() SystemRestoreManager.getConfiguration()] which accepts an optional [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/restore/SystemRestoreParameters.html SystemRestoreParameters] and returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/restore/SystemRestoreConfiguration.html SystemRestoreConfiguration].

You can limit the returned configuration by providing a SystemRestoreParameters.

'''SystemRestoreParameters Fields'''

{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| excludeItems || N || Allows filtering out of specific groups of system configuration items. Supported values are <code>jobs</code>, <code>chains</code>, <code>conflicts</code>, <code>systemParameters</code>, <code>customCalendars</code>, <code>globalParameters</code>, <code>users</code>, <code>templates</code>, <code>subscribers</code>. 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: [[REST_Endpoints#GET_a_system_restore_configuration|GET a system restore configuration]]

== Update System Restore Configuration ==

To import a system restore configuration (partial or complete), use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemRestoreManager.html#updateConfiguration(com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration,java.lang.String) SystemRestoreManager.updateConfiguration()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/restore/SystemRestoreConfiguration.html SystemRestoreConfiguration]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/restore/SystemRestoreConfiguration.html SystemRestoreConfiguration] representing the full system state, which may not be the same as the input value.

REST equivalent: [[REST_Endpoints#PUT_a_system_restore_configuration|PUT a system restore configuration]]

= ScheduleAliasManager API =

''As of Obsidian 5.0''

The [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/ScheduleAliasManager.html ScheduleAliasManager] allows for retrieving, creating, editing and deleting schedule aliases. See [[Admin_Schedule_Aliases|Schedule Aliases]] for more information.

== List Schedule Aliases ==

To list the current schedule aliases, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/ScheduleAliasManager.html#listScheduleAliases() ScheduleAliasManager.listScheduleAliases()] which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/schedule/ScheduleAliasListing.html ScheduleAliasListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_schedule_aliases|GET a list of schedule aliases]]

== Create or Update Schedule Alias ==

To create or update a schedule alias, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/ScheduleAliasManager.html#addOrUpdateScheduleAlias(java.lang.String,java.lang.String,java.lang.String) ScheduleAliasManager.addOrUpdateScheduleAlias()]. The method returns the updated [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/schedule/ScheduleAlias.html ScheduleAlias] representing the full system state, which may not be the same as the input value.

REST equivalent: [[REST_Endpoints#PUT_a_schedule_alias|PUT a schedule alias]]

== Get a Schedule Alias ==

To retrieve a current schedule alias, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/ScheduleAliasManager.html#getScheduleAlias(java.lang.String) ScheduleAliasManager.getScheduleAlias()] which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/schedule/ScheduleAlias.html ScheduleAlias].

REST equivalent: [[REST_Endpoints#GET_a_schedule_alias|GET a schedule alias]]

== Delete a Schedule Alias ==

To delete an unused schedule alias, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/ScheduleAliasManager.html#deleteScheduleAlias(java.lang.String,java.lang.String) ScheduleAliasManager.deleteScheduleAlias()] which returns the deleted [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/schedule/ScheduleAlias.html ScheduleAlias].

REST equivalent: [[REST_Endpoints#DELETE_a_schedule_alias|DELETE a schedule alias]]

= StatsManager API =

''As of Obsidian 6.4.0''

The [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/StatsManager.html StatsManager] allows for retrieving job execution statistics. Assumes the [[Built-in_Jobs#Obsidian_Execution_Statistics_Job|Execution Statistics Job]] has run at least once successfully.

== List Stats ==

To list the job execution statistics, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/StatsManager.html#listStats(com.carfey.ops.api.bean.stats.StatsListingRequest) StatsManager.listStats()] which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/stats/StatsListing.html StatsListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_job_execution_statistics|GET a list of job execution statistics]]

Embedded API

2025-12-15T21:59:55Z

Craig: /* Enumerations */

REST Endpoints

2025-12-15T21:57:07Z

Craig: /* GET a list of job statistics */

This page documents the format of each available REST endpoint.

For information on data formats, valid enumerations values, common behaviour and more, see the primary [[REST API]] page.

As of Obsidian 2.3, all endpoints have corresponding bean classes that can be used with JSON object mappers like [https://github.com/google/gson Gson]. If you wish to use these, please review [[REST_API#JSON_Bean_Classes|bean classes]] for information on serialization of Obsidian's custom types.

= Job Endpoints =

==GET a list of jobs==
'''<code>GET http(s)://localhost/rest/jobs[?host=host1&activeStatus=ENABLED&nickname=jobname&param_group=orders&jobClass=com.example.ExportJob]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobListing</code>

Returns a list of configured jobs, optionally filtered by query string parameters.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| activeStatus || N || Restricts the preview to the selected statuses. See [[Unified_API#Enumerations|Enumerations]] for valid values. Supports multiple values.
|-
| effectiveDate || N || If querying by activeStatus, this allows you to indicate what point in time to compare against the job status. Defaults to next minute.
|-
| host || N || If specified, only jobs that run on the specified host name(s) are included. Supports multiple values.
|-
| nickname || N || If specified, only jobs matching the supplied nickname 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%". Supports multiple values.
|-
| jobClass || 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.''
|-
| folder || 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.''
|-
| param_''parameterName'' || N || If specified, values starting with ''param_'' can be used to match only on jobs with specific job parameter values, either custom or defined. If multiple values for the same query parameter starting with ''param_'' are supplied, a job is matched if any of its configured values match one of the supplied values. If ''param_'' filters with separate 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 a query like the following to find jobs belonging to the "customer" or "order" groups:
<code>GET http(s)://localhost/rest/jobs[?param_group=customer&param_group=order]</code>

|}

'''Sample Response'''
<pre>
{
"jobs": [
{
"recoveryType": "NONE",
"jobId": 33,
"pickupBufferMinutes": 5,
"nickname": "jobOne",
"folder": "Production/Test", // as of 4.1.0
"interruptable": false, // indicates if job can be interrupted (as of 1.5.1)
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll" : true, // corresponds to chainAll setting on job creation (as of 2.3)
"activeSchedule": {
"jobScheduleId": 34,
"status": "CHAIN_ACTIVE",
"endDate": "2999-12-31T23:59:00-0800",
"effectiveDate": "2013-01-06T14:37:00-0800",
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
"jobClass": "com.carfey.ops.job.maint.JobHistoryCleanupJob",
"revision": 0
},
{
"recoveryType": "CONFLICTED",
"jobId": 35,
"pickupBufferMinutes": 123,
"nickname": "jobTwo",
"interruptable": false
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll" : true, // corresponds to chainAll setting on job creation (as of 2.3)
"activeSchedule": {
"jobScheduleId": 37,
"status": "ENABLED",
"schedule": "@daily",
"scheduleDescription": "At midnight every day" (as of 5.2.0)
"endDate": "2013-01-08T14:34:00-0800",
"effectiveDate": "2013-01-07T14:34:00-0800",
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"revision": 2
}
]
}
</pre>

==GET details of an existing job==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Returns full job information, including all historical schedules and parameter information. Returns a 404 if not found.

'''Sample Response (with inline comments)'''
<pre>
{
"schedules": [
{
"effectiveDate": "2013-01-08T15:15:00-0800",
"endDate": "2031-04-30T07:59:00-0800",
"status": "ENABLED",
"schedule": "* * * * *",
"scheduleDescription": "Every minute every day" (as of 5.2.0)
"jobScheduleId": 35,
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
{
"effectiveDate": "2031-04-30T08:00:00-0800",
"endDate": "2031-04-30T08:00:00-0800",
"schedule": "0 8 30 4 3#5",
"scheduleDescription": "At 8:00AM on the 30th during April on the 3rd Friday" (as of 5.2.0)
"status": "ENABLED",
"jobScheduleId": 2952,
"parameters": [{
"value": "value",
"name": "paramName",
"type": "STRING",
"values": ["value"]
}]
},
{
"effectiveDate": "2015-01-06T15:53:00-0800",
"endDate": "2016-01-06T15:53:00-0800",
"status": "AD_HOC_ACTIVE",
"jobScheduleId": 38
}
],
"currentJobScheduleId": 35, // id of the item in "schedules" which is active right now
"jobClassDescription": "This job cleans up log history beyond the configured age.", // returned only if Job is annotated with @Description
"hosts": [
"host1"
],
"job": {
"jobId": 34,
"revision": 0,
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"nickname": "testCreateWithEffectiveDatesAndParams",
"folder": "Production/Test", // as of 4.1.0
"pickupBufferMinutes": 5,
"recoveryType": "NONE",
"interruptable": false, // indicates if job can be interrupted (as 1.5.1)
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll" : true // corresponds to chainAll setting on job creation (as of 2.3)
},
"parameters": [
{
"name": "level",
"type": "STRING",
"allowMultiple": true,
"required": true,
"values": [ "WARN", "ERROR" ], // as of 2.5, values may contain global parameter references
"defaultValue": "ALL",
"defined": true // true if defined by @Configuration annotation on the job
},
{
"name": "maxAgeDays",
"type": "INTEGER", // see Enumerations above for valid values
"allowMultiple": false,
"required": true,
"values": [ "60" ], // values is always a list for consistency, even when allowMultiple is false
"defaultValue": "120",
"defined": true
}
]
}
</pre>

==POST a new job==

'''<code>POST http(s)://localhost/rest/jobs</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.JobCreationRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Creates a new job with an initial schedule.

'''Sample Request'''
<pre>
{
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"nickname": "testCreateMixedHostsAndParams",
"pickupBufferMinutes": 5,
"recoveryType": "NONE",
"state": "ENABLED",
"schedule": "@daily",
"effectiveDate": "2012-01-10T15:33:00-0800",
"endDate": "2013-01-10T15:33:00-0800",
"hosts": [
"host1",
"host2"
],
"minExecutionDuration": "1s",
"maxExecutionDuration": "5m",
"autoInterrupt" : false, //indicates if a job should be auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false, // as of 2.0
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"customCalendarId": null, // as of 2.0
"parameters": [
{
"name": "level",
"type": "STRING",
"value": "ERROR"
},
{
"name": "level",
"type": "STRING",
"value": "{{globalLevels}}" // as of 2.5, values may contain global parameter references
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobClass || Y || Fully qualified class name of the job. Max 255 chars.
|-
| nickname || Y || Unique nickname for the job. Max 50 chars before 1.5.2, after which it is 255 chars.
|-
| pickupBufferMinutes || Y || Pickup buffer minutes. Integer greater than zero.
|-
| recoveryType || Y || Recovery type as defined in [[Unified_API#Enumerations|Enumerations]].
|-
| state || Y || Initial schedule's job status as defined in [[Unified_API#Enumerations|Enumerations]].
|-
| 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 || As of Obsidian 2.0. 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|| Y || As of Obsidian 2.0. Number of auto retries on non-interrupted execution failure. 0 if 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 || As of Obsidian 2.0. Boolean indicating whether all chained instances are triggered when job is currently running. Otherwise, only one newly chained record is created.
|-
| parameters || Y/N || Zero or more parameter definitions. If a job defines required parameters with the <code>@Configuration</code> 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 [[Unified_API#Enumerations|Enumerations]]. To define multiple values for a single parameter name, simply include multiple items in the parameters collection.
|}

Responses have the same format as GET.

==PUT updates to an existing job==

'''<code>PUT http(s)://localhost/rest/jobs/{jobId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.JobUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Updates a job's configuration. Does not support schedule changes or additions. For schedule changes, see [[#POST a new schedule to an existing job|POST a new schedule to an existing job]].

As of Obsidian 2.3, this endpoint will only update fields that are supplied in the request, similar to a PATCH request. You may update one or more fields as desired.

'''Sample Request'''
<pre>
{
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"nickname": "testCreateMixedHostsAndParams",
"pickupBufferMinutes": 5,
"recoveryType": "NONE",
"hosts": [
"host1",
"host2"
],
"minExecutionDuration": "1s",
"maxExecutionDuration": "5m",
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"chainAll": false,
"parameters": [
{
"name": "level",
"type": "STRING",
"value": "ERROR"
},
{
"name": "level",
"type": "STRING",
"value": "WARN"
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTNable"
! Field || Required? || Notes
|-
| jobClass || N || Fully qualified class name of the job. Max 255 chars.
|-
| nickname || N || Unique nickname for the job. Max 50 chars.
|-
| pickupBufferMinutes || N || Pickup buffer minutes. Integer greater than zero.
|-
| recoveryType || N || Recovery type as defined in [[Unified_API#Enumerations|Enumerations]].
|-
| 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 || As of Obsidian 2.0. Number of auto retries on non-interrupted execution failure. 0 if 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 || As of Obsidian 2.0. 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 <code>@Configuration</code> 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 [[Unified_API#Enumerations|Enumerations]]. To define multiple values for a single parameter name, simply include multiple items in the parameters collection.
|}

Responses have the same format as GET.

==DELETE an existing job==

'''<code>DELETE http(s)://localhost/rest/jobs/{jobId}[?cascade=true]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Deletes a job and its history. Returns a 404 if not found.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| cascade|| N || If set to true, all job conflict and chain definitions for this job will also be deleted. If not set, or set to false, any existing job conflicts or chain definitions will cause the request to fail.
|}

Responses have the same format as GET, and return the final state of the job before the delete.

==GET a list of an existing job's schedules==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}/schedules[?start=1356987599000&end=1357510546000]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobScheduleListing</code>

Returns historical schedules for a job. This is essentially a subset of the primary GET endpoint for an existing job.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| start || N || Start date for the runtimes to preview (inclusive). As of Obsidian 3.7.0.
|-
| end || N || End date for the runtimes to preview (inclusive). Must be after the start time. As of Obsidian 3.7.0.
|}

'''Sample Response'''
<pre>
{
"schedules": [
{
"effectiveDate": "2012-01-06T15:53:00-0800",
"endDate": "2012-08-06T15:53:00-0700",
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"jobScheduleId": 37,
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
{
"effectiveDate": "2015-01-06T15:53:00-0800",
"endDate": "2016-01-06T15:53:00-0800",
"status": "AD_HOC_ACTIVE",
"jobScheduleId": 38
}
],
"jobId": 35,
"currentJobScheduleId": 38
}
</pre>

==POST a new schedule to an existing job==
'''<code>POST http(s)://localhost/rest/jobs/{jobId}/schedules</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleCreationRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobScheduleListing</code>

Creates a new schedule for the job. 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.

'''Sample Request'''
<pre>
{
"state": "ENABLED",
"schedule": "@daily",
"effectiveDate": "2012-01-10T15:33:00-0800",
"endDate": "2013-01-10T15:33:00-0800",
"customCalendarId": 123 // if desired, the custom calendar (as of 2.0)
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| state || Y || The schedule's job status as defined in [[Unified_API#Enumerations|Enumerations]].
|-
| 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 || As of Obsidian 2.0, optional custom calendar for schedule.
|}

Responses have the same format as GET.

==GET a list of configured global parameters ==
'''<code>GET http(s)://localhost/rest/global_parameters</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.GlobalParameterListing</code>

''Available as of version 2.5.''

Lists the configured global parameters

'''Sample Response'''
<pre>
{
"parameters": [
{
"name": "forceSSL",
"type": "BOOLEAN",
"values": ["false"]
},
{
"name": "hostNames",
"type": "STRING",
"values": ["example.com", "test.com"]
}
]
}
</pre>

==PUT updates to global parameters ==

'''<code>PUT http(s)://localhost/rest/global_parameters</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.GlobalParameterUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.GlobalParameterListing</code>

''Available as of version 2.5.''

Replaces the configured global parameters with the supplied values. If the value for parameters is missing or empty, all global parameters will be 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.

'''Sample Request'''
<pre>
{
"parameters": [
{
"name": "forceSSL",
"type": "BOOLEAN",
"values": ["false"]
},
{
"name": "hostNames",
"type": "STRING",
"values": ["example.com", "test.com"]
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| parameters || N || Zero or more parameter definitions. Parameter definitions must have values for "name", "type" and "values", where type is a valid parameter type outlined in Enumerations.
|}

Responses have the same format as GET.

==GET a list of job folders ==
'''<code>GET http(s)://localhost/rest/job_folders</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobFolderListing</code>

''Available as of version 4.1.''

Lists all used job folders in both flat and hierarchical modes.

'''Sample Response'''
<pre>

"flat": [
"Prod",
"Prod/Test",
"QA",
"QA/123/456/789/Test",
"QA/Tester"
],
"hierarchy": [
{
"folder": "Prod",
"children": [
{
"folder": "Test",
"children": [

],
"jobUsingDirectly": true
}
],
"jobUsingDirectly": true
},
{
"folder": "QA",
"children": [
{
"folder": "123",
"children": [
{
"folder": "456",
"children": [
{
"folder": "789",
"children": [
{
"folder": "Test",
"children": [

],
"jobUsingDirectly": true
}
],
"jobUsingDirectly": false
}
],
"jobUsingDirectly": false
}
],
"jobUsingDirectly": false
},
{
"folder": "Tester",
"children": [

],
"jobUsingDirectly": true
}
],
"jobUsingDirectly": true
}
]
}
</pre>

= Runtimes Endpoints (i.e. Job History) =

==GET a list of scheduled runtimes (supports multiple jobs)==
'''<code>GET http(s)://localhost/rest/job_runtimes[?startKey=12345&status=RUNNING&host=host1&quantity=100&sort=asc]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeListing</code>

Returns a list of scheduled or completed job runtimes (i.e. history), optionally filtered by query string parameters. As of Obsidian 3.5, ordering is guaranteed to be in order of scheduled time descending, unless overridden by the <code>sort</code> parameter.

'''Note:''' The <code>nextPageStartKey</code> field in the response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen, or the <code>quantity</code> parameter). To fetch the next page of results, invoke the same endpoint with the <code>startKey</code> query string parameter set to the returned <code>nextPageStartKey</code>.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobId || N || Restricts the search to the selected jobs. Supports multiple values.
|-
| status || N || Restricts the search to the selected statuses. See [[Unified_API#Enumerations|Enumerations]] for valid values. Supports multiple values.
|-
| host || N || If specified, only job runtimes that are assigned to the specified host(s) are included. Supports multiple values.
|-
| folder || N || If specified, only job runtimes with 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.''
|-
| start || N || Start date for the job runtimes to return (inclusive). Defaults to 24 hours ago (before 2.3, it defaulted to the current minute).
|-
| end || 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 <code>nextPageStartKey</code>.
|-
| quantity || N || Indicates the maximum number of results to return. This overrides the <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen. ''As of Obsidian 3.5.0.''
|-
| sort || N || A value of either "asc" or "desc", 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.''
|-
| param_''parameterName'' || N || If specified, values starting with ''param_'' can be used to match only on runtimes with specific runtime parameter values (not job-level parameters). If multiple values for the same query parameter starting with ''param_'' are supplied, a runtime is matched if any of its configured values match one of the supplied values. If ''param_'' filters with separate names are used, each must have a matching value for the runtime to be returned.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"nextPageStartKey" : "2013-01-06T16:05:00-0800 634",
"start": "2013-10-31T23:59:00-0800", // the inclusive search from date (as of 2.3)
"end": "2013-11-01T23:59:00-0800", // the inclusive search to date (as of 2.3)
"runtimes": [
{
"runtimeOrdinal": 0, //as of 3.8.0
"heartbeatTime": "2013-01-06T16:05:00-0800",
"jobRuntimeId": 8,
"adHoc": false,
"pickupTime": "2013-01-06T16:04:00-0800",
// present when this job was resubmitted from another job runtime
"resubmissionSource": {
"jobRuntimeId": 10,
"status": "READY",
"scheduledTime": "2013-01-06T16:06:00-0800"
},
"endTime": "2013-01-06T16:05:00-0800",
"revision": 1,
"resubmission": false,
"scheduledTime": "2013-01-06T16:04:00-0800",
"autoRetryCount": 2, // present if this job was auto-retried from a failure (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"status": "FAILED",
"error": { // present if the job fails
"message": "arg was null",
"detail": "stack trace..."
},
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 43,
"nickname": "jobThatChainsOthers",
"interruptable": false, // indicates if job can be interrupted (as of 1.5.1)
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"revision" : 0, // Present as of 2.3
"activeSchedule": {
"jobScheduleId": 44,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T17:44:00-0800",
"effectiveDate": "2013-01-06T16:03:00-0800",
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
"jobClass": "someclass"
},
// optional interruption element if job execution was interrupted (as of version 1.5.1)
"interruption" : {
"requester": "userName",
"requestTime": "2013-01-06T16:04:54-0800",
"interruptTime":"2013-01-06T16:04:56-0800" // this time will be set if successfully interrupted (otherwise not present)
},
// contains a list of job runtimes that were chained from this job runtime
"chainTargets": [
{
"trigger": true,
"detail": null, // if trigger is false, this will contains details of why it didn't trigger
"jobRuntimeId": 9,
"job": {
"jobId": 44,
"nickname": "jobThatGetsChained"
},
"scheduledTime": "2013-01-06T16:05:00-0800"
}
],
"executionType": "Resubmission" // when present, indicates it executed as a "Resubmission", "Chained", or "Ad Hoc" job
},
{
"runtimeOrdinal": 0, //as of 3.8.0
"jobRuntimeId": 9,
"adHoc": false,
"revision": 0,
"resubmission": false,
"scheduledTime": "2013-01-06T16:05:00-0800",
"status": "READY",
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 44,
"nickname": "jobThatGetsChained",
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"revision" : 0, // Present as of 2.3
"activeSchedule": {
"jobScheduleId": 45,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T17:44:00-0800",
"effectiveDate": "2013-01-06T16:03:00-0800"
},
"jobClass": "someclass2"
},
// when present, this includes this runtime was chained as a result of another job runtime
"chainSource": {
"trigger": true,
"detail": "chained it",
"jobRuntimeId": 8,
"job": {
"jobId": 43,
"nickname": "jobThatChainsOthers"
},
"scheduledTime": "2013-01-06T16:04:00-0800"
},
"chainTargets": [ ],
"executionType": "Chained"
}
]
}
</pre>

==GET a list of a job's scheduled runtimes==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}/runtimes</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeListing</code>

This endpoint is equivalent the other runtime endpoint (see preceding item) with a URL like the following: <code>GET http(s)://localhost/rest/job_runtimes?jobId={jobId}</code>

Other than the jobId, all other query string parameters from the multi-job endpoint are supported.

==POST a new scheduled runtime for an existing job (i.e. submit a one-time or ad hoc run)==
'''<code>POST http(s)://localhost/rest/jobs/{jobId}/runtimes</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeSubmissionRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeSubmissionResult</code>

Allows for submission of an ad hoc job run (executed immediately), or a one-time run scheduled for a later time.

'''Note:''' The job must be in a valid state to allow for execution (i.e. <code>UNSCHEDULED_ACTIVE</code>, <code>ENABLED</code>, or <code>AD_HOC_ACTIVE</code>).

'''Sample Request'''
<pre>
{
"scheduledTime": "2013-02-06T16:40:00-0800",
// Optional. Available as of 2.1.1. Parameters supplied for scheduled runtime which will be available to the job when executing.
"parameters": [
{
"name": "level",
"type": "STRING",
"value": "ERROR"
},
{
"name": "level",
"type": "STRING",
"value": "WARN"
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! 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 parameter type outlined in [[Unified_API#Enumerations|Enumerations]]. 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.
|}

'''Note:''' A <code>jobRuntimeId</code> is only returned in the case of an ad hoc run.

'''Sample Response (with inline comments) '''
<pre>
{
"jobRuntimeId": 2, // only returned for ad hoc submission (no scheduled time supplied)
"jobId": 36,
"scheduledTime": "2013-01-06T16:37:00-0800"
}
</pre>

==GET details of an existing scheduled (or completed) job runtime==
'''<code>GET http(s)://localhost/rest/job_runtimes/{jobRuntimeId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeResult</code>

Returns detailed information for the requested job runtime. Responses will contain all the same details as a single record from a <code>/job_runtimes</code> GET request, with the addition of the <code>output</code> and <code>parameters</code> elements, which contain saved job results and runtime-specific parameters respectively.

'''Sample Response'''
<pre>
{
"runtime": {
"heartbeatTime": "2013-01-06T16:27:00-0800",
"jobRuntimeId": 2,
"adHoc": false,
"pickupTime": "2013-01-06T16:26:00-0800",
"endTime": "2013-01-06T16:27:00-0800",
"revision": 6,
"resubmission": false,
"scheduledTime": "2013-01-06T16:26:00-0800",
"runningHost": "test3",
"status": "FAILED",
"interruptable": false, // indicates if job can be interrupted (as of 1.5.1)
"autoRetryCount": 2, // present if this job was auto-retried from a failure (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 36,
"nickname": "testWithOutput",
"activeSchedule": {
"jobScheduleId": 37,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T18:06:00-0800",
"effectiveDate": "2013-01-06T16:25:00-0800",
"customCalendarId": 123 // if configured, the custom calendar for this job (as of 2.0)
},
"jobClass": "someclass"
},
"chainSource": null,
"chainTargets": [

],
"output": [
{
"jobRuntimeResultId": 4,
"name": "testname",
"value": "testvalue",
"valueType": "java.lang.String"
},
{
"jobRuntimeResultId": 5,
"name": "testname",
"value": "testvalue2",
"valueType": "java.lang.String"
},
{
"jobRuntimeResultId": 6,
"name": "testname2",
"value": "testvalue3",
"valueType": "java.lang.String"
}
],
// Parameters specified for ad-hoc or one-time runtime (as of 2.1.1). This does not include parameters defined at the job level.
"parameters": [
{
"name": "level",
"type": "STRING", // see Enumerations above for valid values
"values": [ "WARN", "ERROR" ]
},
{
"name": "maxAgeDays",
"type": "INTEGER",
"values": [ "60" ] // values is always a list for consistency
}
]
}
}
</pre>

==DELETE a future scheduled runtime ==

''Since Obsidian 4.7.0''

'''<code>DELETE http(s)://localhost/rest/jobs/{jobId}/runtimes</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.history.OneTimeRunDeleteRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.OneTimeDeletionResult</code>

Allows for deletion of a future scheduled ad hoc job run.

'''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.

'''Sample Request'''
<pre>
{
"scheduledTime": "2021-02-01T19:00:00-0800",
// Optional if only one instance scheduled at the specified time.
"runtimeOrdinal": 2
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| scheduledTime|| Y || The scheduled time, when the job was previously requested to be run. Must yet be in the future.
|-
| runtimeOrdinal|| 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.
|}

'''Sample Response (with inline comments) '''
<pre>
{
"jobId": 2,
"jobRuntimeId": 36389,
"scheduledTime": "2021-02-01T19:00:00-0800"
}
</pre>

==POST a resubmission request for a failed job runtime==
'''<code>POST http(s)://localhost/rest/job_runtimes/{jobRuntimeId}/resubmissions</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeResubmissionResult</code>

Allows for resubmission of a failed job runtime.

'''Sample Response '''
<pre>
{
"resubmission": {
"revision": 0,
"jobId": 35,
"resubmission": true,
"runtimeOrdinal": 0, // as of 3.8.0
"scheduledTime": "2013-01-06T16:49:00-0800",
"status": "READY",
"jobRuntimeId": 2
}
}
</pre>

==POST an interruption request to kill a running job ==
'''<code>POST http(s)://localhost/rest/job_runtimes/{jobRuntimeId}/interrupts</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.JobInterruptResult</code>

''Available as of version 1.5.1.''

Allows for interruption of a currently running job runtime. 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 it is capable of shutting down. Not all jobs can be terminated. See [[Implementing_Jobs#Interruptable_Jobs|Interruptable Jobs]] for full details.

'''Sample Response '''
<pre>
{
"interruption": {
"requester": "apiUserName",
"requestTime": "2013-01-06T16:49:00-0800"
}
}
</pre>

== POST async results ==

'''<code>POST http(s)://localhost/rest/job_runtimes/{jobRuntimeId}/async_results</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.history.AsyncJobRuntimeResultsRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeResult</code>

''Available as of version 4.5.0.''

Used to indicate the final status of an Async job. This request can only be made once successfully. See [[Implementing_Jobs#Async_Jobs | Async Job]] for full details.

'''Sample Request '''
<pre>
{
"asyncJobRuntimeStatus": "FAILED",
"resultTime": "2018-03-09T22:04:08-0500",
"jobResults": {
"Job Failure Description": "Could not acquire locks on all resources. Tables [reference_object,reference_entity] were not optimized."
},
"resultException": {"detailMessage":"Lock Not Acquired","stackTrace":[{"declaringClass":"com.carfey.finance.OptimizeDatabase","methodName":"optimize","fileName":"OptimizeDatabase.java","lineNumber":132},{"declaringClass":"com.carfey.ops.job.OptimizeDatabase","methodName":"acquireLocks","fileName":"OptimizeDatabase.java","lineNumber":445}],"suppressedExceptions":[]}
}
</pre>

'''Sample Response '''
<pre>
{
"runtime": {
"runningHost": "obsidian-production",
"runtimeOrdinal": 0,
"output": [
{
"name": "Job Failure Description",
"value": "Could not acquire locks on all resources. Tables [reference_object,reference_entity] were not optimized.",
"valueType": "java.lang.String",
"jobRuntimeResultId": 551
}
],
"pickupTime": "2018-03-09T07:45:30-0500",
"adHoc": false,
"heartbeatTime": "2018-03-09T07:46:59-0500",
"lastUpdatedBy": "REST: webServiceCallback",
"scheduledTime": "2018-03-09T07:45:00-0500",
"revision": 603,
"resubmission": false,
"job": {
"hostPreference": false,
"autoInterrupt": false,
"pickupBufferMinutes": 2,
"recoveryType": "NONE",
"autoRetryCount": 0,
"jobClass": "com.carfey.ops.job.WebServiceJob",
"nickname": "Finance DB Optimization Service",
"lastUpdatedBy": "devops",
"activeSchedule": {
"schedule": "@daily",
"lastUpdatedBy": "devops",
"lastUpdatedDate": "2018-03-08T23:57:37-0500",
"createdDate": "2018-03-08T23:57:37-0500",
"endDate": "2999-12-31T23:59:00-0500",
"createdBy": "devops",
"jobScheduleId": 152,
"effectiveDate": "2018-03-08T23:58:00-0500",
"status": "ENABLED"
},
"interruptable": false,
"autoRetryInterval": 0,
"revision": 201,
"jobId": 1,
"lastUpdatedDate": "2018-03-08T23:57:37-0500",
"createdDate": "2018-03-08T14:47:33-0500",
"createdBy": "devops",
"autoRetryIntervalExponent": false,
"chainAll": false
},
"parameters": [],
"status": "FAILED",
"chainTargets": [],
"error": {
"exceptionClass": "java.lang.Exception",
"detail": "java.lang.Exception: Lock Not Acquired\r\n\tat com.carfey.finance.OptimizeDatabase.optimize(OptimizeDatabase.java:132)\r\n\tat com.carfey.ops.job.OptimizeDatabase.acquireLocks(OptimizeDatabase.java:445)\r\n",
"message": "Lock Not Acquired"
},
"jobRuntimeId": 756,
"lastUpdatedDate": "2018-03-09T21:50:57-0500",
"createdDate": "2018-03-09T07:44:01-0500",
"createdBy": "JobQueuer",
"endTime": "2018-03-09T22:04:08-0500"
}
}
</pre>

==GET a list of the latest scheduled runtime by job (supports multiple jobs)==
'''<code>GET http(s)://localhost/rest/job_runtimes/latest[?startKey=12345&host=host1&quantity=100&sort=asc]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.JobDashboardListing</code>

''Available as of version 4.10.2.''

Returns a list of the latest job runtimes by job(i.e. history), optionally filtered by query string parameters. Ordering is guaranteed to be in order of scheduled time descending, unless overridden by the <code>sort</code> parameter.

'''Note:''' The <code>nextPageStartKey</code> field in the response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen, or the <code>quantity</code> parameter). To fetch the next page of results, invoke the same endpoint with the <code>startKey</code> query string parameter set to the returned <code>nextPageStartKey</code>.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobId || N || Restricts the search to the selected jobs. Supports multiple values. ''Do not combine with nickname.''
|-
| nickname || N || If specified, only jobs matching the supplied nickname 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%". Supports multiple values. ''Do not combine with jobId.''
|-
| host || N || If specified, only the latest job runtimes that are assigned to the specified host(s) are included. Supports multiple values.
|-
| folder || N || If specified, only job runtimes with 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 <code>nextPageStartKey</code>.
|-
| quantity || N || Indicates the maximum number of results to return. This overrides the <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen.
|-
| sort || N || A value of either "asc" or "desc", which controls the ordering of returned results. In all cases, the job scheduled time is used to sort results.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"nextPageStartKey" : "2013-01-06T16:05:00-0800 634",
"start": "2013-10-31T23:59:00-0800",
"end": "2013-11-01T23:59:00-0800",
"runtimes": [
{
"runtimeOrdinal": 0,
"heartbeatTime": "2013-01-06T16:05:00-0800",
"jobRuntimeId": 8,
"adHoc": false,
"pickupTime": "2013-01-06T16:04:00-0800",
// present when this job was resubmitted from another job runtime
"resubmissionSource": {
"jobRuntimeId": 10,
"status": "READY",
"scheduledTime": "2013-01-06T16:06:00-0800"
},
"endTime": "2013-01-06T16:05:00-0800",
"revision": 1,
"resubmission": false,
"scheduledTime": "2013-01-06T16:04:00-0800",
"autoRetryCount": 2, // present if this job was auto-retried from a failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"status": "FAILED",
"error": { // present if the job fails
"message": "arg was null",
"detail": "stack trace..."
},
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 43,
"nickname": "jobThatChainsOthers",
"interruptable": false, // indicates if job can be interrupted
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"revision" : 0,
"activeSchedule": {
"jobScheduleId": 44,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T17:44:00-0800",
"effectiveDate": "2013-01-06T16:03:00-0800",
"customCalendarId": 123 // if configured, the custom calendar
},
"jobClass": "someclass"
},
// optional interruption element if job execution was interrupted
"interruption" : {
"requester": "userName",
"requestTime": "2013-01-06T16:04:54-0800",
"interruptTime":"2013-01-06T16:04:56-0800" // this time will be set if successfully interrupted (otherwise not present)
},
// contains a list of job runtimes that were chained from this job runtime
"chainTargets": [
{
"trigger": true,
"detail": null, // if trigger is false, this will contains details of why it didn't trigger
"jobRuntimeId": 9,
"job": {
"jobId": 44,
"nickname": "jobThatGetsChained"
},
"scheduledTime": "2013-01-06T16:05:00-0800"
}
],
"executionType": "Resubmission" // when present, indicates it executed as a "Resubmission", "Chained", or "Ad Hoc" job
},
{
"runtimeOrdinal": 0,
"jobRuntimeId": 9,
"adHoc": false,
"revision": 0,
"resubmission": false,
"scheduledTime": "2013-01-06T16:05:00-0800",
"status": "READY",
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 44,
"nickname": "jobThatGetsChained",
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"revision" : 0,
"activeSchedule": {
"jobScheduleId": 45,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T17:44:00-0800",
"effectiveDate": "2013-01-06T16:03:00-0800"
},
"jobClass": "someclass2"
},
// when present, this includes this runtime was chained as a result of another job runtime
"chainSource": {
"trigger": true,
"detail": "chained it",
"jobRuntimeId": 8,
"job": {
"jobId": 43,
"nickname": "jobThatChainsOthers"
},
"scheduledTime": "2013-01-06T16:04:00-0800"
},
"chainTargets": [ ],
"executionType": "Chained"
}
]
}
</pre>

= Runtime Preview Endpoints =

==GET a list of runtime previews (supports multiple jobs)==
'''<code>GET http(s)://localhost/rest/job_runtimes/previews[?jobId=1&jobId=2&start=1356987599000&end=1357510546000]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.RuntimePreviewListing</code>

Returns a preview of runtimes, optionally filtered based on the supplied query string parameters. This 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 response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen). If you are hitting this condition, try limiting your date range or other parameters.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobId || N || Restricts the preview to the selected jobs. Supports multiple values.
|-
| start || N || Start date for the runtimes to preview (inclusive). Defaults to the current minute.
|-
| end || N || End date for the runtimes to preview (inclusive). Defaults to a day after the start time. Must be after the start time.
|}

'''Sample Response'''
<pre>
{
"capped": false,
"start": "2013-10-31T23:59:00-0800", // the inclusive search from date (as of 2.3)
"end": "2013-11-01T23:59:00-0800", // the inclusive search to date (as of 2.3)
"runtimes": [
{
"jobId": 36,
"nickname": "jobOne",
"schedule": "* * * * *",
"scheduleDescription": "Every minute every day", (as of 5.2.0)
"scheduledTime": "2013-01-06T15:31:00-0800",
"scheduleEffectiveDate": "2013-01-06T13:50:00-0800",
"scheduleEndDate": "2999-12-31T23:59:00-0800"
},
{
"jobId": 37,
"nickname": "jobTwo",
"schedule": "* * * * *",
"scheduleDescription": "Every minute every day", (as of 5.2.0)
"scheduledTime": "2013-01-06T15:30:00-0800",
"scheduleEffectiveDate": "2013-01-06T13:50:00-0800",
"scheduleEndDate": "2999-12-31T23:59:00-0800"
}
]
}
</pre>

==GET a list of runtime previews for an existing job==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}/runtimes/previews</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.RuntimePreviewListing</code>

This endpoint is equivalent the other runtime preview endpoint (see preceding item) with a URL like the following:
<code>GET http(s)://localhost/rest/job_runtimes/previews?jobId={jobId}</code>

Other than the <code>jobId</code>, all other query string parameters from the multi-job endpoint are supported.

= Job Chain Endpoints =

''As of Obsidian 2.4.''

==GET a list of job chains==
'''<code>GET http(s)://localhost/rest/chains[?active=true&sourceJobId=123&targetJobId=456]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChainListing</code>

Returns a list of configured job chains, optionally filtered by query string parameters.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! 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.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"jobChains": [
{
"jobChainId": 1,
"schedule": "* * * * *", // if specified
"scheduleDescription": "Every minute every day", (as of 5.2.0)
"active": true,
"sourceJob": {
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Order Export Job",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.example.OrderExportJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 2
},
"target": {
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
},
"triggerStates": ["FAILED","CONDITIONAL"],
"resultConditions": [
{
"variableName": "exportFile",
"operator": "EXISTS",
"values": [] // empty list when values do not apply
},
{
"variableName":"fileSize",
"operator": "GREATER_THAN",
"values": ["0"] // list with one element when multiples aren't applicable
},
{
"variableName": "status",
"operator": "IN",
"values": ["EXPORTED", "ZIPPED"]
}
]
},
{
"jobChainId": 2,
"active": false,
"sourceJob": {
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Customer Export Job",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.example.CustomerExportJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 2
},
"target": {
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
},
"triggerStates": ["COMPLETED"],
"resultConditions": [] // only populated when CONDITIONAL state is used
}
]
}
</pre>

==GET details of an existing job chain==
'''<code>GET http(s)://localhost/rest/chains/{jobChainId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChain</code>

Returns details of a configured job chain, or a 404 if not found. Contains the same set of fields as the job chain listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"jobChainId": 1,
"schedule": "* * * * *", // if specified
"scheduleDescription": "Every minute every day", (as of 5.2.0)
"active": true,
"sourceJob": {
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Order Export Job",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.example.OrderExportJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 2
},
"target": {
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
},
"triggerStates": ["FAILED", "CONDITIONAL"],
"resultConditions": [ // only populated when CONDITIONAL state is used
{
"variableName": "exportFile",
"operator": "EXISTS",
"values": [] // empty list when values do not apply
},
{
"variableName": "fileSize",
"operator": "GREATER_THAN",
"values": ["0"] // list with one element when multiples aren't applicable
},
{
"variableName": "status",
"operator": "IN",
"values": ["EXPORTED", "ZIPPED"]
}
]
}
</pre>

==POST a new job chain==

'''<code>POST http(s)://localhost/rest/chains</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.JobChainUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChain</code>

Creates a new job chain.

'''Sample Request'''
<pre>
{
"sourceJobId": 12,
"targetJobId": 54,
"schedule": "* * * * *", //optional
"active": true,
"triggerStates": ["CONDITIONAL", "FAILED"],
"resultConditions": [ // only supplied when CONDITIONAL state is supplied
{
"variableName": "exportFile",
"operator":"EXISTS" // no "values" field required for EXISTS or NOT_EXISTS
},
{
"variableName": "fileSize",
"operator": "GREATER_THAN",
"values":["0"] // in this case, only one value allowed
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! 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.
|-
| active || Y || Flag to indicate whether the chain is active or not.
|-
| triggerStates || Y || One or more job chain states as defined in [[Unified_API#Enumerations|Enumerations]]. Note that <code>CONDITIONAL</code> and <code>COMPLETED</code> types cannot be used on the same chain.
|-
| resultConditions || Y/N || Conditions based on job results that apply to the <code>CONDITIONAL</code> 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 <code>variableName</code>, an <code>operator</code> as defined in [[Unified_API#Enumerations|Enumerations]], and for most operators, a list of <code>values</code>. The <code>EXISTS</code> and <code>NOT EXISTS</code> operators do not use values, so they must not be supplied. Operators <code>IN</code> and <code>NOT IN</code> support one or more values, and all other operators accept a single value in the <code>values</code> list. Values for this field map to bean class <code>com.carfey.ops.api.enums.JobChainConditionOperator</code>.
|}

Responses have the same format as GET.

==PUT updates to an existing job chain==

'''<code>PUT http(s)://localhost/rest/chains/{jobChainId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.JobChainUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChain</code>

Updates an existing job chain. Returns a 404 if not found.

Requests and responses have the same format as POST.

==DELETE an existing job chain==
''Available as of version 2.6.''

'''<code>DELETE http(s)://localhost/rest/chains/{jobChainId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChain</code>

Deletes a job chain. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the job chain before the delete.

= Job Conflict Endpoints =

''As of Obsidian 2.4.

==GET a list of job conflicts ==
'''<code>GET http(s)://localhost/rest/conflicts</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.ConflictListing</code>

Lists the configured job conflicts. Non-conflicted jobs are also included in the return value.

Conflicting jobs are returned in priority order within the same list. Multiple conflicting job sets can be returned in the <code>conflictJobs</code> field.

'''Sample Response (with inline comments)'''
<pre>
{
"conflictJobs": [
[
{
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set A - 1",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"folder": "Production/Test", // as of 4.1.0
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 2
},
{
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set A - 2",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
}
],
[
{
"jobId": 53,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set B - 1",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 2
},
{
"jobId": 54,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set B - 2",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
},
{
"jobId": 55,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set B - 3",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
}
],
],
"nonConflictJobs": [
{
"jobId": 56,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Non-Conflicted Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
}
]
}
</pre>

==PUT updates to job conflicts ==

'''<code>PUT http(s)://localhost/rest/conflicts</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.ConflictUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Replaces the current job conflict configuration with the supplied configuration.

'''Sample Request'''
<pre>
{

// Note that if Job 5 and Job 2 are scheduled for the same minute, Job 5 will run first as it is selected as the highest priority job from the first conflict set.
// When priority is significant and varies across different sets, ensure your conflict sets are in the desired order.
"conflicts": [
[1, 2, 3, 5], // Job 1 has highest priority
[2, 5, 4] // Job 2 also conflicts with 4 & 5.
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| conflicts || N || A list of lists containing job IDs. Each inner list 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.
|}

Responses have the same format as GET.

==GET a list of conflicts for a specific job==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}/conflicts</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobConflictListing</code>

Lists all jobs that conflict with the requested job.

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.

'''Sample Response (with inline comments)'''
<pre>
{
"conflictJobs": [
{
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Conflict A",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 2
},
{
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Conflict B",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
},
{
"jobId": 56, // this is the requested job
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Requested Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
}
],
"job": {
"jobId": 56,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Requested Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
}
}
</pre>

= Scheduling Hosts Endpoints =

==GET a list of known scheduling hosts==
'''<code>GET http(s)://localhost/rest/hosts</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostListing</code>

Returns a list of known hosts. These are either running or recently shut down abnormally. Hosts that shut down normally are unregistered on shutdown. Note that returned IDs are transient and may change after startup or shutdown or a node. Heartbeat time indicates when the server last performed the heartbeat health check against the database.

'''Sample Response'''
<pre>
{
"hosts": [
{
"id": 32,
"name": "production1",
"heartbeatTime": "2013-01-05T21:15:59-0800",
"enabled": true
},
{
"id": 33,
"name": "production2",
"heartbeatTime": "2013-01-05T21:15:59-0800",
"enabled": false
}
]
}
</pre>

==GET details on an existing scheduling host==
'''<code>GET http(s)://localhost/rest/hosts/{id}</code>'''

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostDetail</code>

Returns the requested host, or a 404 if not found.

'''Note:''' The name field corresponds to the host name, as described [[Getting_Started#Setting_Host_Names|here]]. Explicit host names should be set if you intend to rely known host names in this endpoint. Heartbeat time indicates when the server last performed the heartbeat health check against the database.

'''Sample Response'''
<pre>
{
"host": {
"id": 33,
"name": "production1",
"heartbeatTime": "2013-01-05T21:18:18-0800",
"licenceLeaseExpiryUtc": "2017-06-15 01:36:06",
"enabled": true,
"licenceStatus": "internet_node_verified",
"licenceLeaseExpiryUtc": "2017-06-15 02:15:42"
}
}
</pre>

==GET health details on an existing scheduling host==
''As of Obsidian 6.3.0''

<code>GET http(s)://localhost/rest/hosts/{id}/health</code>

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}/health</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostDetail</code>

The intended use of this endpoint is as a health check. This endpoint response is to be parsed to evaluate health as it will include full health details with 200 response code if all is well, and a 400 if any part of system is unhealthy including license verification, job queuer and/or job spawner.

'''Note:''' The name field corresponds to the host name, as described [[Getting_Started#Setting_Host_Names|here]]. Explicit host names should be set if you intend to rely known host names in this endpoint. Heartbeat time indicates when the server last performed the heartbeat health check against the database.

'''Sample Response'''
<pre>
{
"host": {
"id": 243,
"name": "obsidian.production",
"heartbeatTime": "2025-07-17T20:28:34Z",
"licenceLeaseExpiryUtc": "2025-07-18 01:27:14",
"enabled": true,
"licenceStatus": "internet_node_verified",
"jobQueuerStatus": "healthy",//or laggy,delayed,unresponsive
"jobQueuerUpdateTimeUtc": "2025-07-17 20:28:28",
"jobSpawnerStatus": "healthy"//or laggy,delayed,unresponsive
"jobSpawnerUpdateTimeUtc": "2025-07-17 20:28:20",
"createdDate": "2025-07-17T19:27:13Z",
"createdBy": "SchedulerStarter.startUp",
"lastUpdatedBy": "SchedulerStarter.designator",
"lastUpdatedDate": "2025-07-17T20:28:34Z",
}
}
</pre>

==GET licence details on an existing scheduling host==
'''<code>GET http(s)://localhost/rest/hosts/{id}/licence_health</code>'''        ''Prior to 4.5'': '''<code>GET http(s)://localhost/rest/hosts/licenceHealthCheck/{id}</code>'''

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}/licence_health</code>'''        ''Prior to 4.5'': '''<code>GET http(s)://localhost/rest/hosts/licenceHealthCheck/names/{name}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostDetail</code>

The intended use of this endpoint is as a health check. This endpoint is identical to the [[REST_Endpoints#GET_details_on_an_existing_scheduling_host |GET details on an existing scheduling host]] above, with the exception that it will return a 400 if the licence has expired or is in some way invalid.

Returns the requested host with licence status, or a 404 if not found, or a 400 if the licence is invalid or its lease has expired.

'''Note:''' The name field corresponds to the host name, as described [[Getting_Started#Setting_Host_Names|here]]. Explicit host names should be set if you intend to rely known host names in this endpoint. Heartbeat time indicates when the server last performed the heartbeat health check against the database.

'''Sample Response'''
<pre>
{
"host": {
"id": 33,
"name": "production1",
"heartbeatTime": "2013-01-05T21:18:18-0800",
"licenceLeaseExpiryUtc": "2017-06-15 01:36:06",
"enabled": true,
"licenceStatus": "internet_node_verified",
"licenceLeaseExpiryUtc": "2017-06-15 02:15:42"
}
}
</pre>

==PUT updates to an existing scheduling host==
'''<code>PUT http(s)://localhost/rest/hosts/{id}</code>'''

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.host.HostUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostDetail</code>

Updates the enabled status of the requested host, or a 404 if not found. This endpoint is used to enable or disable scheduling nodes.

'''Note:''' The name field corresponds to the host name, as described [[Getting_Started#Setting_Host_Names|here]]. Explicit host names should be set if you intend to rely known host names in this endpoint.

'''Sample Request'''
<pre>
{
"enabled": false
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| enabled || Y || Should this host should be enabled?
|}

Responses have the same format as GET.

= Event Hooks Endpoints =
''As of Obsidian 5.4.0''

==GET event hooks==
'''<code>GET http(s)://localhost/rest/event_hooks</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.EventHookListing</code>

Returns all event hooks across the cluster.

'''Sample Response'''
<pre>
{
"hostEventHooks": [
{
"host": "prod-obsidian-RG1",
"eventHooks": [
{
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"name": "SlackEventHook",
"status": "INACTIVE",
"registrationTime": "2024-06-01T15:52:07-0400",
"heartbeat": "2024-06-01T16:52:09-0400",
"markedInactiveAt": "2024-06-01T16:52:09-0400" --if applicable
}
]
},
{
"host": "prod-obsidian-HL1",
"eventHooks": [
{
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"name": "SlackEventHook",
"status": "ACTIVE",
"registrationTime": "2024-06-01T18:08:11-0400",
"heartbeat": "2024-06-01T19:01:37-0400"
}
]
}
]
}
</pre>

==GET event hooks on host==

'''<code>GET http(s)://localhost/rest/hosts/{id}/event_hooks</code>'''

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}/event_hooks</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.EventHookListing</code>

Returns all event hooks for the given host.

'''Sample Response'''
<pre>
{
"hostEventHooks": [
{
"host": "prod-obsidian-RG1",
"eventHooks": [
{
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"name": "SlackEventHook",
"status": "INACTIVE",
"registrationTime": "2024-06-01T15:52:07-0400",
"heartbeat": "2024-06-01T16:52:09-0400",
"markedInactiveAt": "2024-06-01T16:52:09-0400" --if applicable
}
]
}
]
}
</pre>

==POST event hook pause or resume ==
''As of Obsidian 5.5.0''

'''<code>POST http(s)://localhost/rest/event_hooks</code>'''

Alternate (by host id): POST http(s)://localhost/rest/hosts/{id}/event_hooks

Alternate (by host name): POST http(s)://localhost/rest/hosts/names/{name}/event_hooks

'''Request bean class:''' <code>com.carfey.ops.api.bean.host.UpdateEventHookRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.EventHookListing</code>

Requests a specific event hook on a specific host to either Pause or Resume

'''Sample Request'''

<pre>
{
"hostName": "obsidian-prod-1",//only used when using non host-specific event_hooks endpoint
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"eventHookName": "SlackEventHook"
"eventHookAction": "PAUSE"
}
</pre>

'''Sample Response'''
<pre>
{
"hostEventHooks": [
{
"host": "obsidian-prod-1",
"eventHooks": [
{
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"name": "SlackEventHook",
"status": "ACTIVE",
"registrationTime": "2024-06-01T15:52:07-0400",
"heartbeat": "2024-06-01T16:52:09-0400",
"requestedStatus" : "PAUSE",
"requestedBy" : "carey-ops"
}
]
}
]
}
</pre>

= Custom Calendar Endpoints =

''As of Obsidian 2.0. Format revised in 2.3.''

The following endpoints allow for managing of [[Job_Features#Custom_Calendars|Custom Calendars]].

==GET a list of custom calendars==
'''<code>GET http(s)://localhost/rest/calendars</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendarListing</code>

Returns a list of custom calendars.

'''Sample Response'''
<pre>
{
"customCalendars": [
{
"revision": 0,
"dates": ["2013-01-01", "2013-02-18", "2013-04-01", "2013-05-20"],
"name": "Corporate Holidays 2013",
"customCalendarId": 1
},
{
"revision": 0,
"dates": ["2013-01-01", "2013-02-18", "2013-04-01", "2013-05-20"],
"name": "Corporate Holidays 2014",
"customCalendarId": 2
}
]
}
</pre>
==GET details on an existing custom calendar==
'''<code>GET http(s)://localhost/rest/calendars/{id}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendar</code>

''As of Obsidian 2.3.''

Returns the requested custom calendar, or a 404 if not found..

'''Sample Response'''
<pre>
{
"revision": 0,
"dates": ["2013-01-01", "2013-02-18", "2013-04-01", "2013-05-20"],
"name": "Corporate Holidays 2013",
"customCalendarId": 1
}
</pre>

==POST a new custom calendar ==
'''<code>POST http(s)://localhost/rest/calendars/</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendarUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendar</code>

Updates the name and dates of the requested calendar, or a 404 if not found.

'''Sample Request'''
<pre>
{
"name": "Cal1",
"dates": ["2016-10-14" ,"2018-06-14"],
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| name|| Y || Calendar name
|-
| dates|| Y || Dates to exclude
|}

Responses have the same format as GET.

==PUT updates to an existing custom calendar==
'''<code>PUT http(s)://localhost/rest/calendars/{id}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendarUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendar</code>

Updates the name and dates of the requested calendar, or a 404 if not found.

'''Sample Request'''
<pre>
{
"name": "Cal2",
"dates": ["2018-06-13","2016-10-13"]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| name|| Y || Calendar name
|-
| dates|| Y || Dates to exclude
|}

Responses have the same format as POST.

==DELETE an existing custom calendar==

''Available as of version 3.0.''

'''<code>DELETE http(s)://localhost/rest/calendars/{id}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendar</code>

Deletes a custom calendar. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the calendar before the delete.

= Subscriber Endpoints =

''As of Obsidian 3.0.''

==GET a list of subscribers==
'''<code>GET http(s)://localhost/rest/subscribers</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.SubscriberListing</code>

Returns a list of configured notification subscribers.

'''Sample Response (with inline comments)'''
<pre>
{
"subscribers": [
{
"id": 1,
"emailAddress": "test@example.com",
"active": true,
"generalSubscriptions": [
{
"category": "QUEUE",
"level": "ERROR",
"active": true,
},
{
"category": "JOB",
"level": "ERROR",
"active": true,
"job" : { // only exists when the subscription applies to a specific job
"recoveryType": "NONE",
"jobId": 1,
"pickupBufferMinutes": 2,
"nickname": "Cleanup Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.JobHistoryCleanupJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"chainAll": false,
"hostPreference": true,
"revision": 52
}
}
],
"jobExecutionSubscriptions": [
{
"allJobs": true,
"jobs": [], // always empty when allJobs is true
"triggerStates": [ "DIED", "FAILED", "RECOVERY" ],
"resultConditions": [], // present when CONDITIONAL triggerState is used
"active": false
},
{
"allJobs": false,
"jobs": [
{
"recoveryType": "NONE",
"jobId": 1,
"pickupBufferMinutes": 2,
"nickname": "Cleanup Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.JobHistoryCleanupJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"chainAll": false,
"hostPreference": true,
"revision": 52
}
],
"triggerStates": [ "CONDITIONAL" ],
"resultConditions": [
{
"variableName": "cleanupState",
"operator": "EQUALS",
"values": [ "incomplete" ] // depending on the operator, values may be empty, have 1 value, or multiple.
},
{
"variableName": "warnings",
"operator": "EXISTS",
"values": []
}
],
"active": true
}
]
},
{
"id": 2,
"emailAddress": "inactive@example.com",
"active": false,
"generalSubscriptions": [],
"jobExecutionSubscriptions": []
}
]
}
</pre>

==GET details of an existing subscriber==
'''<code>GET http(s)://localhost/rest/subscribers/{subscriberId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Subscriber</code>

Returns details of an existing subscriber, or a 404 if not found. Contains the same set of fields as the listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 1,
"emailAddress": "test@example.com",
"active": true,
"generalSubscriptions": [
{
"active": true,
"category": "QUEUE",
"level": "ERROR"
}
],
"jobExecutionSubscriptions": [
{
"active": false,
"allJobs": true,
"jobs": [],
"triggerStates": [ "DIED", "FAILED", "RECOVERY" ],
"resultConditions": []
}
]
}
</pre>

==POST a new subscriber==

'''<code>POST http(s)://localhost/rest/subscribers</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.notification.SubscriberUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Subscriber</code>

Creates a new notification subscriber.

'''Sample Request'''
<pre>
{
"emailAddress": "test@example.com",
"active": true,
"generalSubscriptions": [
{
"category": "JOB",
"level": "ERROR",
"active": true,
"jobId": 123 // optional, and only valid when a job-related category is selected
}
],
"jobExecutionSubscriptions":[
{
"active": false,
"allJobs": true,
"triggerStates": [ "DIED", "FAILED", "RECOVERY" ]
},
{
"active": true,
"jobIds": [ 123 ], // should not be supplied with the allJobs flag which takes precedence
"triggerStates": [ "CONDITIONAL" ],
"resultConditions": [
{
"variableName": "cleanupState",
"operator": "EQUALS",
"values": [ "incomplete" ] // depending on the operator, values may be empty, have 1 value, or multiple.
}
]
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! 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 general subscriptions. Each item contains a required subscription <code>category</code> and <code>level</code> as defined in [[Unified_API#Enumerations|Enumerations]], an optional <code>jobId</code> and an optional <code>active</code> flag which defaults to false.

'''Note:''' Only <code>ERROR</code>, <code>WARNING</code> AND <code>INFO</code> are valid values for <code>level</code>. Only <code>JOB</code>, <code>JOB_CHAIN</code>, <code>JOB_CONFIG</code>, <code>JOB_RECOVERY</code>, <code>LICENCE</code>, <code>QUEUE</code>, <code>SYSTEM_PARAMETER</code> and null are valid values for <code>category</code>.
|-
| jobExecutionSubscriptions || N || Zero or more job execution subscriptions. Each item contains a required <code>triggerStates</code> field containing at least one subscription job status as defined in [[Unified_API#Enumerations|Enumerations]]. Note that <code>CONDITIONAL</code> and <code>COMPLETED</code> types cannot be used on the same chain.

If the <code>CONDITIONAL</code> state is selected, at least one condition must be supplied in the <code>resultConditions</code> field. Result conditions consist of a <code>variableName</code>, an <code>operator</code> as defined in [[Unified_API#Enumerations|Enumerations]], and for most operators, a list of <code>values</code>. The <code>EXISTS</code> and <code>NOT EXISTS</code> operators do not use values, so they must not be supplied. Operators <code>IN</code> and <code>NOT IN</code> support one or more values, and all other operators accept a single value in the <code>values</code> list. Values for this field map to bean class <code>com.carfey.ops.api.enums.JobSubscriptionConditionOperator</code>.

In addition, two additional optional fields control which jobs the subscription applies to. <code>jobIds</code> is used to specify specific jobs, while <code>allJobs</code> may be set to true to make it apply to all jobs. If <code>jobIds</code> is supplied and <code>allJobs</code> is set to true, <code>jobIds</code> will be ignored.

Finally, the <code>active</code> flag may be supplied which defaults to true.
|}

Responses have the same format as GET.

==PUT updates to an existing subscriber ==

'''<code>PUT http(s)://localhost/rest/subscribers/{subscriberId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.notification.SubscriberUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Subscriber</code>

Updates an existing subscriber. Returns a 404 if not found.

Requests and responses have the same format as POST.

==DELETE an existing subscriber==

'''<code>DELETE http(s)://localhost/rest/subscribers/{subscriberId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Subscriber</code>

Deletes a subscriber. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the subscriber before the delete.

= Templates Endpoints =

''As of version 3.0.''

These endpoints allow for managing notification templates.

==GET a list of templates==
'''<code>GET http(s)://localhost/rest/templates</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.TemplateListing</code>

Returns a list of configured templates.

'''Sample Response (with inline comments)'''
<pre>
{
"templates":[
{
"id": 1,
"name": "Obsidian Default Job Template",
"active": true,
"category": "JOB",
"defaultForJobs": true, // indicates if it is the default job template for the category
"jobs": [ // only present for job categories when defaultForJobs is false
{
"recoveryType": "NONE",
"jobId": 1,
"pickupBufferMinutes": 2,
"nickname": "Cleanup Job",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.JobHistoryCleanupJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"chainAll": false,
"hostPreference": true,
"revision": 52
}
],
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Obsidian {{hostName}} Body content..."
},
{
"id": 2,
"name": "Obsidian Default Other Template",
"active": true,
"defaultForJobs": false,
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Obsidian {{hostName}} Body content..."
}
]
}
</pre>

==GET details of an existing template==
'''<code>GET http(s)://localhost/rest/templates/{templateId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Template</code>

Returns details of a configured template, or a 404 if not found. Contains the same set of fields as the template listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 2,
"name": "Obsidian Default Other Template",
"active": true,
"category": "LICENCE", // if missing, it is the default generic template
"defaultForJobs": false,
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Obsidian {{hostName}} Body content..."
}
</pre>

==POST a new template==

'''<code>POST http(s)://localhost/rest/templates</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.notification.TemplateUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Template</code>

Creates a new template.

'''Sample Request'''
<pre>
{
"name": "Cleanup Job Template",
"active": true,
"category": "JOB", // category not required when it is the default template
"defaultForJobs": false, // when true, jobIds are ignored
"jobIds": [ 123, 456 ],
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Obsidian {{hostName}} Body content..."
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! 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 as defined in [[Unified_API#Enumerations|Enumerations]], or null if it is the default generic template. Supports multiple values. Not all categories are supported. Only <code>JOB</code>, <code>JOB_CHAIN</code>, <code>JOB_CONFIG</code>, <code>JOB_RECOVERY</code>, <code>LICENCE</code>, <code>QUEUE</code>, <code>SYSTEM_PARAMETER</code> 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 [[Email_Templates|Mustache template]] for the subject.
|-
| bodyTemplate || Y || A valid [[Email_Templates|Mustache template]] for the body.
|}

Responses have the same format as GET.

==PUT updates to an existing template==

'''<code>PUT http(s)://localhost/rest/templates/{templateId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.notification.TemplateUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Template</code>

Requests and responses have the same format as POST.

==DELETE an existing template ==

'''<code>DELETE http(s)://localhost/rest/templates/{templateId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Template</code>

Deletes a template. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the template before the delete.

= Notification Endpoints =

''As of Obsidian 3.0''

These endpoints allow you to query what notifications were triggered in Obsidian. Note that existence of records does not necessarily indicate the notification was successfully sent or received.

==GET a list of notifications==
'''<code>GET http(s)://localhost/rest/notifications[?category=QUEUE&level=ERROR&start=1356987599000&end=1357510546000&startKey=123]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.NotificationListing</code>

Returns a list of notifications, optionally filtered by query string parameters. Results are ordered roughly according to when they were created, but ordering is not guaranteed to be in order of created time.

'''Note:''' The <code>nextPageStartKey</code> field in the response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen). To fetch the next page of results, invoke the same endpoint with the <code>startKey</code> query string parameter set to the returned <code>nextPageStartKey</code>.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| category || N || The category of the notifications as defined in [[Unified_API#Enumerations|Enumerations]]. Supports multiple values.
|-
| level || N || The logging level of the notifications defined in [[Unified_API#Enumerations|Enumerations]]. Supports multiple values.
|-
| 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 <code>nextPageStartKey</code>.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"nextPageStartKey": "123",
"notifications": [
{
"id": 51,
"log": {
"id": 292,
"eventTime": "2015-01-22T16:44:00-0800",
"host": "Demo",
"category": "JOB_RUN",
"level": "INFO",
"summary": "Completed job [Job History Cleanup 033] scheduled for [2015-01-22 16:44:00]."
},
"subscriber":{
"id": 51,
"emailAddress": "test@test.com",
"active": true // current active state (not when triggered)
}
},
{
"id": 52,
"log": {
"id": 295,
"eventTime": "2015-01-22T16:44:00-0800",
"host": "Demo",
"category": "JOB_RUN",
"level": "INFO",
"summary": "Completed job [Job History Cleanup 145] scheduled for [2015-01-22 16:44:00]."
},
"subscriber": {
"id": 51,
"emailAddress": "test@test.com",
"active": true
}
},
]
}
</pre>

==GET details of an existing notification==
'''<code>GET http(s)://localhost/rest/notifications/{id}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Notification</code>

Returns detail of an existing notification, which contains the same fields as the listing endpoint. Returns a 404 if not found.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 51,
"log": {
"id": 292,
"eventTime": "2015-01-22T16:44:00-0800",
"host": "Demo",
"category": "JOB_RUN",
"level": "INFO",
"summary": "Completed job [Job History Cleanup 033] scheduled for [2015-01-22 16:44:00]."
},
"subscriber":{
"id": 51,
"emailAddress": "test@test.com",
"active": true // current active state (not when triggered)
}
}
</pre>

= Log Endpoints =

''As of Obsidian 3.0''

==GET a list of logs==
'''<code>GET http(s)://localhost/rest/logs[?host=host1&filterText=error&category=QUEUE&level=ERROR&start=1356987599000&end=1357510546000&startKey=123]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.log.LogListing</code>

Returns a list of event logs, optionally filtered by query string parameters. Results are ordered roughly according to when they were created, but ordering is not guaranteed to be in order of created time.

'''Note:''' The <code>nextPageStartKey</code> field in the response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen). To fetch the next page of results, invoke the same endpoint with the <code>startKey</code> query string parameter set to the returned <code>nextPageStartKey</code>.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! 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 || The category of the log as defined in [[Unified_API#Enumerations|Enumerations]]. Supports multiple values.
|-
| level || N || The logging level of the log as defined in [[Unified_API#Enumerations|Enumerations]]. Supports multiple values.
|-
| 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 <code>nextPageStartKey</code>.
|}

'''Sample Response'''
<pre>
{
"nextPageStartKey" : "123",
"logs": [
{
"id": 1619,
"eventTime": "2015-01-21T13:59:43-0800",
"host": "Demo",
"category": "JOB_SPAWNER",
"level": "DEBUG",
"summary": "Spawning [Test Job] scheduled for 2015-01-21 13:59:00"
},
{
"id": 4,
"eventTime": "2015-01-20T11:54:49-0800",
"host": "Demo",
"category": "LICENCE",
"level": "INFO",
"summary": "Successfully refreshed licence from server https://licence.carfey.com/licence for 120 minutes."
}
]
}
</pre>

==GET details of an existing log==
'''<code>GET http(s)://localhost/rest/logs/{logId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.log.Log</code>

Returns detail of an existing log entry. Returns a 404 if not found.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 1619,
"eventTime": "2015-01-21T13:59:43-0800",
"host": "Demo",
"category": "JOB_SPAWNER",
"level": "DEBUG",
"summary": "Spawning [Test Job] scheduled for 2015-01-21 13:59:00"
}
</pre>

= System Parameter Endpoints =

''As of version 3.0.''

==GET a list of system parameters==
'''<code>GET http(s)://localhost/rest/system_parameters</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.SystemParameterListing</code>

Returns a list of system parameters which can be edited.

'''Sample Response (with inline comments)'''
<pre>
{
"parameters": [
{
"name": "clientKeyServerUrl",
"description": "Address of the primary key server. If running a proxy, this should be the address of the proxy server.",
"type": "STRING",
"category": "LICENCE",
"value": "https://licence.carfey.com/licence"
},
{
"name": "maxJobThreads",
"description": "This value determines the maximum number of threads that will be spawned for running jobs. Changes to this value require a server restart.",
"type": "INTEGER",
"category": "JOB_SPAWNER",
"value": "1000"
}
]
}
</pre>

==GET details of a system parameter ==
'''<code>GET http(s)://localhost/rest/system_parameters/{name}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.SystemParameter</code>

Returns details of a system parameter, or a 404 if not found. Contains the same set of fields as the listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"name": "clientKeyServerUrl",
"description": "Address of the primary key server. If running a proxy, this should be the address of the proxy server.",
"type": "STRING",
"category": "LICENCE",
"value": "https://licence.carfey.com/licence"
}
</pre>

==PUT updates to a system parameter ==

'''<code>PUT http(s)://localhost/rest/system_parameters/{name}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.system.SystemParameterUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.SystemParameter</code>

Updates a system parameter's value. Values are accepted as strings, but must be valid for their target type (integer, boolean, etc.). Returns a 404 if not found.

'''Sample Request'''
<pre>
{
"value": "60"
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| value || N || The new value for the system parameter, which can be converted into the appropriate target type. Some string values support an empty value.
|}

Responses have the same format as GET.

= User Endpoints =

''As of version 3.0.''

Note that user endpoints are only available when using Obsidian's native authentication, and do not support LDAP or custom authentication.

==GET a list of users==
'''<code>GET http(s)://localhost/rest/users</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.UserListing</code>

Returns a list of configured users.

'''Sample Response (with inline comments)'''
<pre>
{
"users": [
{
"id": 1,
"userName": "admin",
"active": true,
"roles": ["ADMIN","API"]
},
{
"id": 2
"userName": "reader",
"active": false,
"roles": [] // no roles means read-only
}
]
}
</pre>

==GET details of an existing user==
'''<code>GET http(s)://localhost/rest/users/{userId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.User</code>

Returns details of a configured user, or a 404 if not found. Contains the same set of fields as the user listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 1,
"userName": "admin",
"active": true,
"roles": ["ADMIN","API"]
}
</pre>

==POST a new user==

'''<code>POST http(s)://localhost/rest/users</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.user.UserCreationRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.User</code>

Creates a new user.

'''Sample Request'''
<pre>
{
"userName": "admin",
"active": true,
"roles": ["ADMIN","API"],
"password": "changeme"
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! 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 roles as defined in [[Unified_API#Enumerations|Enumerations]]. Supplying no roles indicates it is a normal read-only user.
|-
| password || Y || A password at least 6 characters long.
|}

Responses have the same format as GET.

==PUT updates to an existing user==

'''<code>PUT http(s)://localhost/rest/users/{userId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.user.UserUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.User</code>

Updates an existing user. Returns a 404 if not found. Semantics similar to a PATCH request are used, so that only supplied fields are updated. User names cannot be updated.

'''Sample Request'''
<pre>
{
"active": true,
"roles": ["ADMIN","API"],
"password": "changeme"
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| active || N || Whether the user is enabled. Defaults to the existing active state.
|-
| roles || N || Zero or more roles as defined in [[Unified_API#Enumerations|Enumerations]]. 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.
|}

Responses have the same format as POST.

==DELETE an existing user ==

'''<code>DELETE http(s)://localhost/rest/users/{userId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.User</code>

Deletes a user. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the user before the delete.

==GET a list of known MFA users==

''As of version 5.0.''

'''<code>GET http(s)://localhost/rest/users/mfa</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.MfaUserListing</code>

Returns all known users which may have Multi-Factor Authentication (MFA) resets applied. Exists to facilitate use of the MFA reset endpoint.

'''Sample Response'''
<pre>
{
"userNames": [
"admin",
"john.doe",
"operator"
]
}
</pre>

==PUT MFA user resets==

''As of version 5.0.''

'''<code>PUT http(s)://localhost/rest/users/mfa/reset</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.user.ResetMfaRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.MfaUserListing</code>

Resets the requested users' Multi-Factor Authentication (MFA) state so that they may perform MFA setup. This is useful when a user does not complete MFA setup within the required time, or when adding a user when not using Obsidian's native authentication.

'''Sample Request'''
<pre>
{
"userNames": [
"admin",
"john.doe",
"operator"
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| userNames || Y || The list of user names to reset. Note that these do not have to correspond to known Obsidian users, since it must support custom authentication methods.
|}

Responses echo the users in the request.

'''Sample Response'''
<pre>
{
"userNames": [
"admin",
"john.doe",
"operator"
]
}
</pre>

= System Restore Endpoints =

''As of version 3.0.''

These endpoinds can be used to import and export Obsidian's configuration, including job-related configuration, subscription-related configuration, users and system parameters. See [[Initializing_and_Restoring|Initializing and Restoring]] for more details.

==GET a system restore configuration ==
'''<code>GET http(s)://localhost/rest/system_restores[?excludeItem=users&jobNickname=jobname]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration</code>

Returns the system's exported configuration. The output from this endpoint can be used with the corresponding [[#PUT_a_system_restore_configuration|PUT endpoint]] directly.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| excludeItem || N || Allows filtering out of specific groups of system configuration items. Supported values are <code>jobs</code>, <code>chains</code>, <code>conflicts</code>, <code>systemParameters</code>, <code>customCalendars</code>, <code>globalParameters</code>, <code>users</code>, <code>templates</code>, <code>subscribers</code>. Filtering out jobs automatically also filters out chains and conflicts and drops any other job references (such as in templates and subscribers). Supports multiple values. Since 3.8.0.
|-
| jobNickname || 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). Supports multiple values. Since 3.8.0.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"jobs": [
{
"updateSchedule": false, // whether to apply the current schedule and any additional jobSchedules when the job already exists
"updateAttributes": false, // whether job attributes (jobClass, recoveryType, pickupBufferMinutes, etc.) will be updated when the job exists
"jobSchedules": [
{
"state": "DISABLED",
"effectiveDate": "2015-03-20T10:35:00-0700",
"endDate": "2999-12-31T23:59:00-0800"
}
],
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"minExecutionDuration": "2s",
"maxExecutionDuration": "3s",
"nickname": "Log Cleanup",
"folder": "Production/Test", // as of 4.1.0
"pickupBufferMinutes": 2,
"recoveryType": "NONE",
"hosts": [ "Demo-PC" ],
"ordinalParameters": [ // as of 3.8.0, prior to 3.8.0, parameters child element was at this level
"ordinal": 0, //as of 3.8.0
"parameters": [
{
"name": "level",
"type": "STRING",
"value": "ALL"
},
{
"name": "maxAgeDays",
"type": "INTEGER",
"value": "120"
}
]
],
"chainAll": false,
"hostPreference": true,
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"state": "ENABLED",
"schedule": "* * * * *",
"effectiveDate": "2015-01-01T00:00:00-0700"
"endDate": "2015-03-20T10:34:00-0700"
},
{
"updateSchedule": false,
"updateAttributes": false,
"jobSchedules": [],
"jobClass": "com.carfey.ops.job.script.GroovyJob",
"nickname": "Script Job",
"pickupBufferMinutes": 2,
"recoveryType": "NONE",
"hosts": [],
"ordinalParameters": [ // as of 3.8.0, prior to 3.8.0, parameters child element was at this level
"ordinal": 0, //as of 3.8.0
"parameters": [
{
name": "script",
"type": "STRING",
"value": "sdfds"
}
]
],
"chainAll": false,
"hostPreference": false,
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"state": "DISABLED",
"effectiveDate": "2015-01-01T00:00:00-0700"
"endDate": "2999-12-31T23:59:00-0800"
}
],
"users": [
{
"update": false, // when false, the user attributes will not be updated if the user already exists
"userName": "admin",
"active": true,
"roles": [
"API",
"ADMIN",
"WRITE"
],
"password": "changeme"
}
],
"chains": {
"replaceAll": false, // if set to false or omitted, chains will only be created if none exist - existing chains are not updated.
"items": [
{
"sourceJobNickname": "Script Job",
"targetJobNickname": "Log Cleanup",
"active": true,
"triggerStates": [
"FAILED",
"CONDITIONAL"
],
"resultConditions": [
{
"variableName": "dfdsfds",
"operator": "EQUALS",
"values": [
"sdfs"
]
}
]
}
]
},
"conflicts": [
[
"Script Job",
"Log Cleanup"
]
],
"customCalendars": [
{
"name": "Sample Calendar",
"dates": [
"2011-01-01"
]
}
],
"systemParameters": [
{
"name": "adHocJobsRespectFixedHostsRestrictions",
"description": "This value determines whether the Fixed Hosts restriction assigned to a Job is respected for Ad Hoc jobs.",
"category": "JOB",
"value": "true"
}
],
"templates": [
{
"jobNicknames": [],
"name": "Obsidian Default Job Template",
"active": true,
"category": "JOB",
"defaultForJobs": true,
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Body Template"
}
],
"subscribers": [
{
"generalSubscriptions": [
{
"jobNickname": "Log Cleanup",
"category": "JOB",
"level": "ERROR",
"active": true
}
],
"jobExecutionSubscriptions": [
{
"jobNicknames": [],
"allJobs": true,
"triggerStates": [
"CONDITIONAL",
"DIED",
"FAILED",
"RECOVERY"
],
"resultConditions": [
{
"variableName": "someVar",
"operator": "EQUALS",
"values": [
"someValue"
]
}
],
"active": true
}
],
"emailAddress": "test@example.com",
"active": true
}
]
}
</pre>

==PUT a system restore configuration==
'''<code>PUT http(s)://localhost/rest/system_restores</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration</code>

Imports the requested system restore configuration, updating, creating and replacing data based on the input.

'''Usage Note:''' Entities within the export are generally identified by their names. For details on required fields, formats and update logic, refer to the [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemRestoreManager.html#updateConfiguration(com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration,java.lang.String) Javadoc] and the [[Initializing_and_Restoring|Initializing and Restoring]] page. The Embedded API and REST API both use the same format and processing rules.

Requests are in the same format as the [[#GET_a_system_restore_configuration|GET endpoint's]] response.

Responses are in the same format as the GET and return the full Obsidian system restore configuration following the changes (not necessarily the same as the input).

= Schedule Alias Endpoints =

''As of version 5.0.''

These endpoints can be used to manage schedule aliases. See [[Admin_Schedule_Aliases|Schedule Aliases]] for more details.

==GET a list of schedule aliases ==
'''<code>GET http(s)://localhost/rest/schedule_aliases</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAliasListing</code>

Returns the system's schedule aliases.

'''Sample Response'''
<pre>
{
"scheduleAliases": [
{
"alias": "@every4Minutes",
"schedule": "0/4 * * * *",
"scheduleDescription": "Every 4th minute every day" (as of Obsidian 5.2.0)
},
{
"alias": "@dailyAtNoon",
"schedule": "12 * * * *",
"scheduleDescription": "At 12:00PM every day" (as of Obsidian 5.2.0)
},
{
"alias": "@threeTimesWeekly",
"schedule": "0 0 * 1,3,5 *",
"scheduleDescription": "At midnight on Mondays, Wednesdays, Fridays" (as of Obsidian 5.2.0)
},
{
"alias": "@combinedExample",
"schedule": "@dailyAtNoon;@threeTimesWeekly",
"scheduleDescription": "At 12:00PM every day - AND - At midnight on Mondays, Wednesdays, Fridays" (as of Obsidian 5.2.0)
}
]
}
</pre>

==PUT a schedule alias==
'''<code>PUT http(s)://localhost/rest/schedule_aliases/{alias}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAliasUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAlias</code>

'''Sample Request'''
<pre>
{
"schedule": "5 11 * * 2"
}
</pre>

'''Sample Response'''
<pre>
{ "alias": "@1105AMTuesdays",
"schedule": "5 11 * * 2",
"schedule": "At 11:05AM on Tuesdays" (as of Obsidian 5.2.0)
}
</pre>

==GET a schedule alias==
'''<code>GET http(s)://localhost/rest/schedule_aliases/{alias}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAlias</code>

'''Sample Response'''
<pre>
{ "alias": "@1105AMTuesdays",
"schedule": "5 11 * * 2",
"schedule": "At 11:05AM on Tuesdays" (as of Obsidian 5.2.0)
}
</pre>

==DELETE a schedule alias==
'''<code>DELETE http(s)://localhost/rest/schedule_aliases/{alias}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAlias</code>

'''Sample Response'''
<pre>
{ "alias": "@1105AMTuesdays",
"schedule": "5 11 * * 2"
}
</pre>

= Job Execution Statistics Endpoints =

''As of version 6.4.0.''

To retrieve job execution statistics. Assumes [[Built-in_Jobs#Obsidian_Execution_Statistics_Job|Execution Statistics Job]] has run to completion at least once.

== GET a list of job statistics ==
'''<code>GET http(s)://localhost/rest/stats[?jobNickname=jobname&job_id=1&duration=six_months&unit=seconds&status=completed&acrossHosts=false&host=prod.obsidian-a1&host=prod.obsidian-a2]</code>'''

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobNickname || N || Allows targeting only specific jobs by nickname in the stats export. Supports multiple values.
|-
| jobId || N || Allows targeting only specific jobs by id in the stats export. Supports multiple values.
|-
| duration || N || Allows targeting stats durations. See [[Unified_API#Enumerations|Enumerations]] for valid values - case-insensitive. Supports multiple values.
|-
| unit || N || Allows targeting stats units. See [[Unified_API#Enumerations|Enumerations]] for valid values - case-insensitive. Supports multiple values.
|-
| status || N || Allows targeting stats terminal statuses. See [[Unified_API#Enumerations|Enumerations]] for valid values - case-insensitive. Supports multiple values.
|-
| host || N || Allows targeting stats from specific hosts. Supports multiple values.
|-
| acrossHosts || N || Allows selecting stats collected across all hosts. Boolean.
|}

'''Response bean class:''' <code>com.carfey.ops.api.bean.stats.StatsListing</code>

Returns the cluster's job execution statistics.

'''Sample Response'''
<pre>
{
"stats": [
{
"statsId": 733,
"jobId": 55,
"nickname": "Cache Reloader",
"host": "prod.obsidian-a1",
"status": "COMPLETED",
"unit": "SECONDS",
"duration": "YEAR",
"start": "2024-12-14",
"end": "2025-12-14",
"count": 97,
"average": 7701.463918,
"median": 6965.0,
"mode": 62,
"min": 62.0,
"max": 17925.0,
"variance": 23055960.248698,
"standardDeviation": 4801.66
},
{
"statsId": 545,
"jobId": 55,
"nickname": "Cache Reloader",
"host": "prod.obsidian-a2",
"status": "COMPLETED",
"unit": "HOURS",
"duration": "YEAR",
"start": "2024-12-14",
"end": "2025-12-14",
"count": 114,
"average": 2.238684,
"median": 1.932778,
"mode": 1,
"min": 0.015,
"max": 4.989444,
"variance": 2.18319,
"standardDeviation": 1.47756
}
],
"hosts": [
"prod.obsidian-a1",
"prod.obsidian-a2"
]
}
</pre>

REST Endpoints

2025-12-15T21:54:47Z

Craig:

This page documents the format of each available REST endpoint.

For information on data formats, valid enumerations values, common behaviour and more, see the primary [[REST API]] page.

As of Obsidian 2.3, all endpoints have corresponding bean classes that can be used with JSON object mappers like [https://github.com/google/gson Gson]. If you wish to use these, please review [[REST_API#JSON_Bean_Classes|bean classes]] for information on serialization of Obsidian's custom types.

= Job Endpoints =

==GET a list of jobs==
'''<code>GET http(s)://localhost/rest/jobs[?host=host1&activeStatus=ENABLED&nickname=jobname&param_group=orders&jobClass=com.example.ExportJob]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobListing</code>

Returns a list of configured jobs, optionally filtered by query string parameters.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| activeStatus || N || Restricts the preview to the selected statuses. See [[Unified_API#Enumerations|Enumerations]] for valid values. Supports multiple values.
|-
| effectiveDate || N || If querying by activeStatus, this allows you to indicate what point in time to compare against the job status. Defaults to next minute.
|-
| host || N || If specified, only jobs that run on the specified host name(s) are included. Supports multiple values.
|-
| nickname || N || If specified, only jobs matching the supplied nickname 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%". Supports multiple values.
|-
| jobClass || 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.''
|-
| folder || 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.''
|-
| param_''parameterName'' || N || If specified, values starting with ''param_'' can be used to match only on jobs with specific job parameter values, either custom or defined. If multiple values for the same query parameter starting with ''param_'' are supplied, a job is matched if any of its configured values match one of the supplied values. If ''param_'' filters with separate 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 a query like the following to find jobs belonging to the "customer" or "order" groups:
<code>GET http(s)://localhost/rest/jobs[?param_group=customer&param_group=order]</code>

|}

'''Sample Response'''
<pre>
{
"jobs": [
{
"recoveryType": "NONE",
"jobId": 33,
"pickupBufferMinutes": 5,
"nickname": "jobOne",
"folder": "Production/Test", // as of 4.1.0
"interruptable": false, // indicates if job can be interrupted (as of 1.5.1)
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll" : true, // corresponds to chainAll setting on job creation (as of 2.3)
"activeSchedule": {
"jobScheduleId": 34,
"status": "CHAIN_ACTIVE",
"endDate": "2999-12-31T23:59:00-0800",
"effectiveDate": "2013-01-06T14:37:00-0800",
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
"jobClass": "com.carfey.ops.job.maint.JobHistoryCleanupJob",
"revision": 0
},
{
"recoveryType": "CONFLICTED",
"jobId": 35,
"pickupBufferMinutes": 123,
"nickname": "jobTwo",
"interruptable": false
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll" : true, // corresponds to chainAll setting on job creation (as of 2.3)
"activeSchedule": {
"jobScheduleId": 37,
"status": "ENABLED",
"schedule": "@daily",
"scheduleDescription": "At midnight every day" (as of 5.2.0)
"endDate": "2013-01-08T14:34:00-0800",
"effectiveDate": "2013-01-07T14:34:00-0800",
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"revision": 2
}
]
}
</pre>

==GET details of an existing job==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Returns full job information, including all historical schedules and parameter information. Returns a 404 if not found.

'''Sample Response (with inline comments)'''
<pre>
{
"schedules": [
{
"effectiveDate": "2013-01-08T15:15:00-0800",
"endDate": "2031-04-30T07:59:00-0800",
"status": "ENABLED",
"schedule": "* * * * *",
"scheduleDescription": "Every minute every day" (as of 5.2.0)
"jobScheduleId": 35,
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
{
"effectiveDate": "2031-04-30T08:00:00-0800",
"endDate": "2031-04-30T08:00:00-0800",
"schedule": "0 8 30 4 3#5",
"scheduleDescription": "At 8:00AM on the 30th during April on the 3rd Friday" (as of 5.2.0)
"status": "ENABLED",
"jobScheduleId": 2952,
"parameters": [{
"value": "value",
"name": "paramName",
"type": "STRING",
"values": ["value"]
}]
},
{
"effectiveDate": "2015-01-06T15:53:00-0800",
"endDate": "2016-01-06T15:53:00-0800",
"status": "AD_HOC_ACTIVE",
"jobScheduleId": 38
}
],
"currentJobScheduleId": 35, // id of the item in "schedules" which is active right now
"jobClassDescription": "This job cleans up log history beyond the configured age.", // returned only if Job is annotated with @Description
"hosts": [
"host1"
],
"job": {
"jobId": 34,
"revision": 0,
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"nickname": "testCreateWithEffectiveDatesAndParams",
"folder": "Production/Test", // as of 4.1.0
"pickupBufferMinutes": 5,
"recoveryType": "NONE",
"interruptable": false, // indicates if job can be interrupted (as 1.5.1)
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll" : true // corresponds to chainAll setting on job creation (as of 2.3)
},
"parameters": [
{
"name": "level",
"type": "STRING",
"allowMultiple": true,
"required": true,
"values": [ "WARN", "ERROR" ], // as of 2.5, values may contain global parameter references
"defaultValue": "ALL",
"defined": true // true if defined by @Configuration annotation on the job
},
{
"name": "maxAgeDays",
"type": "INTEGER", // see Enumerations above for valid values
"allowMultiple": false,
"required": true,
"values": [ "60" ], // values is always a list for consistency, even when allowMultiple is false
"defaultValue": "120",
"defined": true
}
]
}
</pre>

==POST a new job==

'''<code>POST http(s)://localhost/rest/jobs</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.JobCreationRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Creates a new job with an initial schedule.

'''Sample Request'''
<pre>
{
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"nickname": "testCreateMixedHostsAndParams",
"pickupBufferMinutes": 5,
"recoveryType": "NONE",
"state": "ENABLED",
"schedule": "@daily",
"effectiveDate": "2012-01-10T15:33:00-0800",
"endDate": "2013-01-10T15:33:00-0800",
"hosts": [
"host1",
"host2"
],
"minExecutionDuration": "1s",
"maxExecutionDuration": "5m",
"autoInterrupt" : false, //indicates if a job should be auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false, // as of 2.0
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"customCalendarId": null, // as of 2.0
"parameters": [
{
"name": "level",
"type": "STRING",
"value": "ERROR"
},
{
"name": "level",
"type": "STRING",
"value": "{{globalLevels}}" // as of 2.5, values may contain global parameter references
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobClass || Y || Fully qualified class name of the job. Max 255 chars.
|-
| nickname || Y || Unique nickname for the job. Max 50 chars before 1.5.2, after which it is 255 chars.
|-
| pickupBufferMinutes || Y || Pickup buffer minutes. Integer greater than zero.
|-
| recoveryType || Y || Recovery type as defined in [[Unified_API#Enumerations|Enumerations]].
|-
| state || Y || Initial schedule's job status as defined in [[Unified_API#Enumerations|Enumerations]].
|-
| 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 || As of Obsidian 2.0. 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|| Y || As of Obsidian 2.0. Number of auto retries on non-interrupted execution failure. 0 if 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 || As of Obsidian 2.0. Boolean indicating whether all chained instances are triggered when job is currently running. Otherwise, only one newly chained record is created.
|-
| parameters || Y/N || Zero or more parameter definitions. If a job defines required parameters with the <code>@Configuration</code> 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 [[Unified_API#Enumerations|Enumerations]]. To define multiple values for a single parameter name, simply include multiple items in the parameters collection.
|}

Responses have the same format as GET.

==PUT updates to an existing job==

'''<code>PUT http(s)://localhost/rest/jobs/{jobId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.JobUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Updates a job's configuration. Does not support schedule changes or additions. For schedule changes, see [[#POST a new schedule to an existing job|POST a new schedule to an existing job]].

As of Obsidian 2.3, this endpoint will only update fields that are supplied in the request, similar to a PATCH request. You may update one or more fields as desired.

'''Sample Request'''
<pre>
{
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"nickname": "testCreateMixedHostsAndParams",
"pickupBufferMinutes": 5,
"recoveryType": "NONE",
"hosts": [
"host1",
"host2"
],
"minExecutionDuration": "1s",
"maxExecutionDuration": "5m",
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"chainAll": false,
"parameters": [
{
"name": "level",
"type": "STRING",
"value": "ERROR"
},
{
"name": "level",
"type": "STRING",
"value": "WARN"
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTNable"
! Field || Required? || Notes
|-
| jobClass || N || Fully qualified class name of the job. Max 255 chars.
|-
| nickname || N || Unique nickname for the job. Max 50 chars.
|-
| pickupBufferMinutes || N || Pickup buffer minutes. Integer greater than zero.
|-
| recoveryType || N || Recovery type as defined in [[Unified_API#Enumerations|Enumerations]].
|-
| 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 || As of Obsidian 2.0. Number of auto retries on non-interrupted execution failure. 0 if 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 || As of Obsidian 2.0. 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 <code>@Configuration</code> 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 [[Unified_API#Enumerations|Enumerations]]. To define multiple values for a single parameter name, simply include multiple items in the parameters collection.
|}

Responses have the same format as GET.

==DELETE an existing job==

'''<code>DELETE http(s)://localhost/rest/jobs/{jobId}[?cascade=true]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Deletes a job and its history. Returns a 404 if not found.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| cascade|| N || If set to true, all job conflict and chain definitions for this job will also be deleted. If not set, or set to false, any existing job conflicts or chain definitions will cause the request to fail.
|}

Responses have the same format as GET, and return the final state of the job before the delete.

==GET a list of an existing job's schedules==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}/schedules[?start=1356987599000&end=1357510546000]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobScheduleListing</code>

Returns historical schedules for a job. This is essentially a subset of the primary GET endpoint for an existing job.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| start || N || Start date for the runtimes to preview (inclusive). As of Obsidian 3.7.0.
|-
| end || N || End date for the runtimes to preview (inclusive). Must be after the start time. As of Obsidian 3.7.0.
|}

'''Sample Response'''
<pre>
{
"schedules": [
{
"effectiveDate": "2012-01-06T15:53:00-0800",
"endDate": "2012-08-06T15:53:00-0700",
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"jobScheduleId": 37,
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
{
"effectiveDate": "2015-01-06T15:53:00-0800",
"endDate": "2016-01-06T15:53:00-0800",
"status": "AD_HOC_ACTIVE",
"jobScheduleId": 38
}
],
"jobId": 35,
"currentJobScheduleId": 38
}
</pre>

==POST a new schedule to an existing job==
'''<code>POST http(s)://localhost/rest/jobs/{jobId}/schedules</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleCreationRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobScheduleListing</code>

Creates a new schedule for the job. 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.

'''Sample Request'''
<pre>
{
"state": "ENABLED",
"schedule": "@daily",
"effectiveDate": "2012-01-10T15:33:00-0800",
"endDate": "2013-01-10T15:33:00-0800",
"customCalendarId": 123 // if desired, the custom calendar (as of 2.0)
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| state || Y || The schedule's job status as defined in [[Unified_API#Enumerations|Enumerations]].
|-
| 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 || As of Obsidian 2.0, optional custom calendar for schedule.
|}

Responses have the same format as GET.

==GET a list of configured global parameters ==
'''<code>GET http(s)://localhost/rest/global_parameters</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.GlobalParameterListing</code>

''Available as of version 2.5.''

Lists the configured global parameters

'''Sample Response'''
<pre>
{
"parameters": [
{
"name": "forceSSL",
"type": "BOOLEAN",
"values": ["false"]
},
{
"name": "hostNames",
"type": "STRING",
"values": ["example.com", "test.com"]
}
]
}
</pre>

==PUT updates to global parameters ==

'''<code>PUT http(s)://localhost/rest/global_parameters</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.GlobalParameterUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.GlobalParameterListing</code>

''Available as of version 2.5.''

Replaces the configured global parameters with the supplied values. If the value for parameters is missing or empty, all global parameters will be 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.

'''Sample Request'''
<pre>
{
"parameters": [
{
"name": "forceSSL",
"type": "BOOLEAN",
"values": ["false"]
},
{
"name": "hostNames",
"type": "STRING",
"values": ["example.com", "test.com"]
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| parameters || N || Zero or more parameter definitions. Parameter definitions must have values for "name", "type" and "values", where type is a valid parameter type outlined in Enumerations.
|}

Responses have the same format as GET.

==GET a list of job folders ==
'''<code>GET http(s)://localhost/rest/job_folders</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobFolderListing</code>

''Available as of version 4.1.''

Lists all used job folders in both flat and hierarchical modes.

'''Sample Response'''
<pre>

"flat": [
"Prod",
"Prod/Test",
"QA",
"QA/123/456/789/Test",
"QA/Tester"
],
"hierarchy": [
{
"folder": "Prod",
"children": [
{
"folder": "Test",
"children": [

],
"jobUsingDirectly": true
}
],
"jobUsingDirectly": true
},
{
"folder": "QA",
"children": [
{
"folder": "123",
"children": [
{
"folder": "456",
"children": [
{
"folder": "789",
"children": [
{
"folder": "Test",
"children": [

],
"jobUsingDirectly": true
}
],
"jobUsingDirectly": false
}
],
"jobUsingDirectly": false
}
],
"jobUsingDirectly": false
},
{
"folder": "Tester",
"children": [

],
"jobUsingDirectly": true
}
],
"jobUsingDirectly": true
}
]
}
</pre>

= Runtimes Endpoints (i.e. Job History) =

==GET a list of scheduled runtimes (supports multiple jobs)==
'''<code>GET http(s)://localhost/rest/job_runtimes[?startKey=12345&status=RUNNING&host=host1&quantity=100&sort=asc]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeListing</code>

Returns a list of scheduled or completed job runtimes (i.e. history), optionally filtered by query string parameters. As of Obsidian 3.5, ordering is guaranteed to be in order of scheduled time descending, unless overridden by the <code>sort</code> parameter.

'''Note:''' The <code>nextPageStartKey</code> field in the response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen, or the <code>quantity</code> parameter). To fetch the next page of results, invoke the same endpoint with the <code>startKey</code> query string parameter set to the returned <code>nextPageStartKey</code>.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobId || N || Restricts the search to the selected jobs. Supports multiple values.
|-
| status || N || Restricts the search to the selected statuses. See [[Unified_API#Enumerations|Enumerations]] for valid values. Supports multiple values.
|-
| host || N || If specified, only job runtimes that are assigned to the specified host(s) are included. Supports multiple values.
|-
| folder || N || If specified, only job runtimes with 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.''
|-
| start || N || Start date for the job runtimes to return (inclusive). Defaults to 24 hours ago (before 2.3, it defaulted to the current minute).
|-
| end || 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 <code>nextPageStartKey</code>.
|-
| quantity || N || Indicates the maximum number of results to return. This overrides the <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen. ''As of Obsidian 3.5.0.''
|-
| sort || N || A value of either "asc" or "desc", 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.''
|-
| param_''parameterName'' || N || If specified, values starting with ''param_'' can be used to match only on runtimes with specific runtime parameter values (not job-level parameters). If multiple values for the same query parameter starting with ''param_'' are supplied, a runtime is matched if any of its configured values match one of the supplied values. If ''param_'' filters with separate names are used, each must have a matching value for the runtime to be returned.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"nextPageStartKey" : "2013-01-06T16:05:00-0800 634",
"start": "2013-10-31T23:59:00-0800", // the inclusive search from date (as of 2.3)
"end": "2013-11-01T23:59:00-0800", // the inclusive search to date (as of 2.3)
"runtimes": [
{
"runtimeOrdinal": 0, //as of 3.8.0
"heartbeatTime": "2013-01-06T16:05:00-0800",
"jobRuntimeId": 8,
"adHoc": false,
"pickupTime": "2013-01-06T16:04:00-0800",
// present when this job was resubmitted from another job runtime
"resubmissionSource": {
"jobRuntimeId": 10,
"status": "READY",
"scheduledTime": "2013-01-06T16:06:00-0800"
},
"endTime": "2013-01-06T16:05:00-0800",
"revision": 1,
"resubmission": false,
"scheduledTime": "2013-01-06T16:04:00-0800",
"autoRetryCount": 2, // present if this job was auto-retried from a failure (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"status": "FAILED",
"error": { // present if the job fails
"message": "arg was null",
"detail": "stack trace..."
},
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 43,
"nickname": "jobThatChainsOthers",
"interruptable": false, // indicates if job can be interrupted (as of 1.5.1)
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"revision" : 0, // Present as of 2.3
"activeSchedule": {
"jobScheduleId": 44,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T17:44:00-0800",
"effectiveDate": "2013-01-06T16:03:00-0800",
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
"jobClass": "someclass"
},
// optional interruption element if job execution was interrupted (as of version 1.5.1)
"interruption" : {
"requester": "userName",
"requestTime": "2013-01-06T16:04:54-0800",
"interruptTime":"2013-01-06T16:04:56-0800" // this time will be set if successfully interrupted (otherwise not present)
},
// contains a list of job runtimes that were chained from this job runtime
"chainTargets": [
{
"trigger": true,
"detail": null, // if trigger is false, this will contains details of why it didn't trigger
"jobRuntimeId": 9,
"job": {
"jobId": 44,
"nickname": "jobThatGetsChained"
},
"scheduledTime": "2013-01-06T16:05:00-0800"
}
],
"executionType": "Resubmission" // when present, indicates it executed as a "Resubmission", "Chained", or "Ad Hoc" job
},
{
"runtimeOrdinal": 0, //as of 3.8.0
"jobRuntimeId": 9,
"adHoc": false,
"revision": 0,
"resubmission": false,
"scheduledTime": "2013-01-06T16:05:00-0800",
"status": "READY",
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 44,
"nickname": "jobThatGetsChained",
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"revision" : 0, // Present as of 2.3
"activeSchedule": {
"jobScheduleId": 45,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T17:44:00-0800",
"effectiveDate": "2013-01-06T16:03:00-0800"
},
"jobClass": "someclass2"
},
// when present, this includes this runtime was chained as a result of another job runtime
"chainSource": {
"trigger": true,
"detail": "chained it",
"jobRuntimeId": 8,
"job": {
"jobId": 43,
"nickname": "jobThatChainsOthers"
},
"scheduledTime": "2013-01-06T16:04:00-0800"
},
"chainTargets": [ ],
"executionType": "Chained"
}
]
}
</pre>

==GET a list of a job's scheduled runtimes==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}/runtimes</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeListing</code>

This endpoint is equivalent the other runtime endpoint (see preceding item) with a URL like the following: <code>GET http(s)://localhost/rest/job_runtimes?jobId={jobId}</code>

Other than the jobId, all other query string parameters from the multi-job endpoint are supported.

==POST a new scheduled runtime for an existing job (i.e. submit a one-time or ad hoc run)==
'''<code>POST http(s)://localhost/rest/jobs/{jobId}/runtimes</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeSubmissionRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeSubmissionResult</code>

Allows for submission of an ad hoc job run (executed immediately), or a one-time run scheduled for a later time.

'''Note:''' The job must be in a valid state to allow for execution (i.e. <code>UNSCHEDULED_ACTIVE</code>, <code>ENABLED</code>, or <code>AD_HOC_ACTIVE</code>).

'''Sample Request'''
<pre>
{
"scheduledTime": "2013-02-06T16:40:00-0800",
// Optional. Available as of 2.1.1. Parameters supplied for scheduled runtime which will be available to the job when executing.
"parameters": [
{
"name": "level",
"type": "STRING",
"value": "ERROR"
},
{
"name": "level",
"type": "STRING",
"value": "WARN"
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! 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 parameter type outlined in [[Unified_API#Enumerations|Enumerations]]. 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.
|}

'''Note:''' A <code>jobRuntimeId</code> is only returned in the case of an ad hoc run.

'''Sample Response (with inline comments) '''
<pre>
{
"jobRuntimeId": 2, // only returned for ad hoc submission (no scheduled time supplied)
"jobId": 36,
"scheduledTime": "2013-01-06T16:37:00-0800"
}
</pre>

==GET details of an existing scheduled (or completed) job runtime==
'''<code>GET http(s)://localhost/rest/job_runtimes/{jobRuntimeId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeResult</code>

Returns detailed information for the requested job runtime. Responses will contain all the same details as a single record from a <code>/job_runtimes</code> GET request, with the addition of the <code>output</code> and <code>parameters</code> elements, which contain saved job results and runtime-specific parameters respectively.

'''Sample Response'''
<pre>
{
"runtime": {
"heartbeatTime": "2013-01-06T16:27:00-0800",
"jobRuntimeId": 2,
"adHoc": false,
"pickupTime": "2013-01-06T16:26:00-0800",
"endTime": "2013-01-06T16:27:00-0800",
"revision": 6,
"resubmission": false,
"scheduledTime": "2013-01-06T16:26:00-0800",
"runningHost": "test3",
"status": "FAILED",
"interruptable": false, // indicates if job can be interrupted (as of 1.5.1)
"autoRetryCount": 2, // present if this job was auto-retried from a failure (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 36,
"nickname": "testWithOutput",
"activeSchedule": {
"jobScheduleId": 37,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T18:06:00-0800",
"effectiveDate": "2013-01-06T16:25:00-0800",
"customCalendarId": 123 // if configured, the custom calendar for this job (as of 2.0)
},
"jobClass": "someclass"
},
"chainSource": null,
"chainTargets": [

],
"output": [
{
"jobRuntimeResultId": 4,
"name": "testname",
"value": "testvalue",
"valueType": "java.lang.String"
},
{
"jobRuntimeResultId": 5,
"name": "testname",
"value": "testvalue2",
"valueType": "java.lang.String"
},
{
"jobRuntimeResultId": 6,
"name": "testname2",
"value": "testvalue3",
"valueType": "java.lang.String"
}
],
// Parameters specified for ad-hoc or one-time runtime (as of 2.1.1). This does not include parameters defined at the job level.
"parameters": [
{
"name": "level",
"type": "STRING", // see Enumerations above for valid values
"values": [ "WARN", "ERROR" ]
},
{
"name": "maxAgeDays",
"type": "INTEGER",
"values": [ "60" ] // values is always a list for consistency
}
]
}
}
</pre>

==DELETE a future scheduled runtime ==

''Since Obsidian 4.7.0''

'''<code>DELETE http(s)://localhost/rest/jobs/{jobId}/runtimes</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.history.OneTimeRunDeleteRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.OneTimeDeletionResult</code>

Allows for deletion of a future scheduled ad hoc job run.

'''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.

'''Sample Request'''
<pre>
{
"scheduledTime": "2021-02-01T19:00:00-0800",
// Optional if only one instance scheduled at the specified time.
"runtimeOrdinal": 2
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| scheduledTime|| Y || The scheduled time, when the job was previously requested to be run. Must yet be in the future.
|-
| runtimeOrdinal|| 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.
|}

'''Sample Response (with inline comments) '''
<pre>
{
"jobId": 2,
"jobRuntimeId": 36389,
"scheduledTime": "2021-02-01T19:00:00-0800"
}
</pre>

==POST a resubmission request for a failed job runtime==
'''<code>POST http(s)://localhost/rest/job_runtimes/{jobRuntimeId}/resubmissions</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeResubmissionResult</code>

Allows for resubmission of a failed job runtime.

'''Sample Response '''
<pre>
{
"resubmission": {
"revision": 0,
"jobId": 35,
"resubmission": true,
"runtimeOrdinal": 0, // as of 3.8.0
"scheduledTime": "2013-01-06T16:49:00-0800",
"status": "READY",
"jobRuntimeId": 2
}
}
</pre>

==POST an interruption request to kill a running job ==
'''<code>POST http(s)://localhost/rest/job_runtimes/{jobRuntimeId}/interrupts</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.JobInterruptResult</code>

''Available as of version 1.5.1.''

Allows for interruption of a currently running job runtime. 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 it is capable of shutting down. Not all jobs can be terminated. See [[Implementing_Jobs#Interruptable_Jobs|Interruptable Jobs]] for full details.

'''Sample Response '''
<pre>
{
"interruption": {
"requester": "apiUserName",
"requestTime": "2013-01-06T16:49:00-0800"
}
}
</pre>

== POST async results ==

'''<code>POST http(s)://localhost/rest/job_runtimes/{jobRuntimeId}/async_results</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.history.AsyncJobRuntimeResultsRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeResult</code>

''Available as of version 4.5.0.''

Used to indicate the final status of an Async job. This request can only be made once successfully. See [[Implementing_Jobs#Async_Jobs | Async Job]] for full details.

'''Sample Request '''
<pre>
{
"asyncJobRuntimeStatus": "FAILED",
"resultTime": "2018-03-09T22:04:08-0500",
"jobResults": {
"Job Failure Description": "Could not acquire locks on all resources. Tables [reference_object,reference_entity] were not optimized."
},
"resultException": {"detailMessage":"Lock Not Acquired","stackTrace":[{"declaringClass":"com.carfey.finance.OptimizeDatabase","methodName":"optimize","fileName":"OptimizeDatabase.java","lineNumber":132},{"declaringClass":"com.carfey.ops.job.OptimizeDatabase","methodName":"acquireLocks","fileName":"OptimizeDatabase.java","lineNumber":445}],"suppressedExceptions":[]}
}
</pre>

'''Sample Response '''
<pre>
{
"runtime": {
"runningHost": "obsidian-production",
"runtimeOrdinal": 0,
"output": [
{
"name": "Job Failure Description",
"value": "Could not acquire locks on all resources. Tables [reference_object,reference_entity] were not optimized.",
"valueType": "java.lang.String",
"jobRuntimeResultId": 551
}
],
"pickupTime": "2018-03-09T07:45:30-0500",
"adHoc": false,
"heartbeatTime": "2018-03-09T07:46:59-0500",
"lastUpdatedBy": "REST: webServiceCallback",
"scheduledTime": "2018-03-09T07:45:00-0500",
"revision": 603,
"resubmission": false,
"job": {
"hostPreference": false,
"autoInterrupt": false,
"pickupBufferMinutes": 2,
"recoveryType": "NONE",
"autoRetryCount": 0,
"jobClass": "com.carfey.ops.job.WebServiceJob",
"nickname": "Finance DB Optimization Service",
"lastUpdatedBy": "devops",
"activeSchedule": {
"schedule": "@daily",
"lastUpdatedBy": "devops",
"lastUpdatedDate": "2018-03-08T23:57:37-0500",
"createdDate": "2018-03-08T23:57:37-0500",
"endDate": "2999-12-31T23:59:00-0500",
"createdBy": "devops",
"jobScheduleId": 152,
"effectiveDate": "2018-03-08T23:58:00-0500",
"status": "ENABLED"
},
"interruptable": false,
"autoRetryInterval": 0,
"revision": 201,
"jobId": 1,
"lastUpdatedDate": "2018-03-08T23:57:37-0500",
"createdDate": "2018-03-08T14:47:33-0500",
"createdBy": "devops",
"autoRetryIntervalExponent": false,
"chainAll": false
},
"parameters": [],
"status": "FAILED",
"chainTargets": [],
"error": {
"exceptionClass": "java.lang.Exception",
"detail": "java.lang.Exception: Lock Not Acquired\r\n\tat com.carfey.finance.OptimizeDatabase.optimize(OptimizeDatabase.java:132)\r\n\tat com.carfey.ops.job.OptimizeDatabase.acquireLocks(OptimizeDatabase.java:445)\r\n",
"message": "Lock Not Acquired"
},
"jobRuntimeId": 756,
"lastUpdatedDate": "2018-03-09T21:50:57-0500",
"createdDate": "2018-03-09T07:44:01-0500",
"createdBy": "JobQueuer",
"endTime": "2018-03-09T22:04:08-0500"
}
}
</pre>

==GET a list of the latest scheduled runtime by job (supports multiple jobs)==
'''<code>GET http(s)://localhost/rest/job_runtimes/latest[?startKey=12345&host=host1&quantity=100&sort=asc]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.JobDashboardListing</code>

''Available as of version 4.10.2.''

Returns a list of the latest job runtimes by job(i.e. history), optionally filtered by query string parameters. Ordering is guaranteed to be in order of scheduled time descending, unless overridden by the <code>sort</code> parameter.

'''Note:''' The <code>nextPageStartKey</code> field in the response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen, or the <code>quantity</code> parameter). To fetch the next page of results, invoke the same endpoint with the <code>startKey</code> query string parameter set to the returned <code>nextPageStartKey</code>.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobId || N || Restricts the search to the selected jobs. Supports multiple values. ''Do not combine with nickname.''
|-
| nickname || N || If specified, only jobs matching the supplied nickname 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%". Supports multiple values. ''Do not combine with jobId.''
|-
| host || N || If specified, only the latest job runtimes that are assigned to the specified host(s) are included. Supports multiple values.
|-
| folder || N || If specified, only job runtimes with 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 <code>nextPageStartKey</code>.
|-
| quantity || N || Indicates the maximum number of results to return. This overrides the <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen.
|-
| sort || N || A value of either "asc" or "desc", which controls the ordering of returned results. In all cases, the job scheduled time is used to sort results.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"nextPageStartKey" : "2013-01-06T16:05:00-0800 634",
"start": "2013-10-31T23:59:00-0800",
"end": "2013-11-01T23:59:00-0800",
"runtimes": [
{
"runtimeOrdinal": 0,
"heartbeatTime": "2013-01-06T16:05:00-0800",
"jobRuntimeId": 8,
"adHoc": false,
"pickupTime": "2013-01-06T16:04:00-0800",
// present when this job was resubmitted from another job runtime
"resubmissionSource": {
"jobRuntimeId": 10,
"status": "READY",
"scheduledTime": "2013-01-06T16:06:00-0800"
},
"endTime": "2013-01-06T16:05:00-0800",
"revision": 1,
"resubmission": false,
"scheduledTime": "2013-01-06T16:04:00-0800",
"autoRetryCount": 2, // present if this job was auto-retried from a failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"status": "FAILED",
"error": { // present if the job fails
"message": "arg was null",
"detail": "stack trace..."
},
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 43,
"nickname": "jobThatChainsOthers",
"interruptable": false, // indicates if job can be interrupted
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"revision" : 0,
"activeSchedule": {
"jobScheduleId": 44,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T17:44:00-0800",
"effectiveDate": "2013-01-06T16:03:00-0800",
"customCalendarId": 123 // if configured, the custom calendar
},
"jobClass": "someclass"
},
// optional interruption element if job execution was interrupted
"interruption" : {
"requester": "userName",
"requestTime": "2013-01-06T16:04:54-0800",
"interruptTime":"2013-01-06T16:04:56-0800" // this time will be set if successfully interrupted (otherwise not present)
},
// contains a list of job runtimes that were chained from this job runtime
"chainTargets": [
{
"trigger": true,
"detail": null, // if trigger is false, this will contains details of why it didn't trigger
"jobRuntimeId": 9,
"job": {
"jobId": 44,
"nickname": "jobThatGetsChained"
},
"scheduledTime": "2013-01-06T16:05:00-0800"
}
],
"executionType": "Resubmission" // when present, indicates it executed as a "Resubmission", "Chained", or "Ad Hoc" job
},
{
"runtimeOrdinal": 0,
"jobRuntimeId": 9,
"adHoc": false,
"revision": 0,
"resubmission": false,
"scheduledTime": "2013-01-06T16:05:00-0800",
"status": "READY",
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 44,
"nickname": "jobThatGetsChained",
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"revision" : 0,
"activeSchedule": {
"jobScheduleId": 45,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T17:44:00-0800",
"effectiveDate": "2013-01-06T16:03:00-0800"
},
"jobClass": "someclass2"
},
// when present, this includes this runtime was chained as a result of another job runtime
"chainSource": {
"trigger": true,
"detail": "chained it",
"jobRuntimeId": 8,
"job": {
"jobId": 43,
"nickname": "jobThatChainsOthers"
},
"scheduledTime": "2013-01-06T16:04:00-0800"
},
"chainTargets": [ ],
"executionType": "Chained"
}
]
}
</pre>

= Runtime Preview Endpoints =

==GET a list of runtime previews (supports multiple jobs)==
'''<code>GET http(s)://localhost/rest/job_runtimes/previews[?jobId=1&jobId=2&start=1356987599000&end=1357510546000]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.RuntimePreviewListing</code>

Returns a preview of runtimes, optionally filtered based on the supplied query string parameters. This 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 response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen). If you are hitting this condition, try limiting your date range or other parameters.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobId || N || Restricts the preview to the selected jobs. Supports multiple values.
|-
| start || N || Start date for the runtimes to preview (inclusive). Defaults to the current minute.
|-
| end || N || End date for the runtimes to preview (inclusive). Defaults to a day after the start time. Must be after the start time.
|}

'''Sample Response'''
<pre>
{
"capped": false,
"start": "2013-10-31T23:59:00-0800", // the inclusive search from date (as of 2.3)
"end": "2013-11-01T23:59:00-0800", // the inclusive search to date (as of 2.3)
"runtimes": [
{
"jobId": 36,
"nickname": "jobOne",
"schedule": "* * * * *",
"scheduleDescription": "Every minute every day", (as of 5.2.0)
"scheduledTime": "2013-01-06T15:31:00-0800",
"scheduleEffectiveDate": "2013-01-06T13:50:00-0800",
"scheduleEndDate": "2999-12-31T23:59:00-0800"
},
{
"jobId": 37,
"nickname": "jobTwo",
"schedule": "* * * * *",
"scheduleDescription": "Every minute every day", (as of 5.2.0)
"scheduledTime": "2013-01-06T15:30:00-0800",
"scheduleEffectiveDate": "2013-01-06T13:50:00-0800",
"scheduleEndDate": "2999-12-31T23:59:00-0800"
}
]
}
</pre>

==GET a list of runtime previews for an existing job==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}/runtimes/previews</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.RuntimePreviewListing</code>

This endpoint is equivalent the other runtime preview endpoint (see preceding item) with a URL like the following:
<code>GET http(s)://localhost/rest/job_runtimes/previews?jobId={jobId}</code>

Other than the <code>jobId</code>, all other query string parameters from the multi-job endpoint are supported.

= Job Chain Endpoints =

''As of Obsidian 2.4.''

==GET a list of job chains==
'''<code>GET http(s)://localhost/rest/chains[?active=true&sourceJobId=123&targetJobId=456]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChainListing</code>

Returns a list of configured job chains, optionally filtered by query string parameters.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! 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.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"jobChains": [
{
"jobChainId": 1,
"schedule": "* * * * *", // if specified
"scheduleDescription": "Every minute every day", (as of 5.2.0)
"active": true,
"sourceJob": {
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Order Export Job",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.example.OrderExportJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 2
},
"target": {
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
},
"triggerStates": ["FAILED","CONDITIONAL"],
"resultConditions": [
{
"variableName": "exportFile",
"operator": "EXISTS",
"values": [] // empty list when values do not apply
},
{
"variableName":"fileSize",
"operator": "GREATER_THAN",
"values": ["0"] // list with one element when multiples aren't applicable
},
{
"variableName": "status",
"operator": "IN",
"values": ["EXPORTED", "ZIPPED"]
}
]
},
{
"jobChainId": 2,
"active": false,
"sourceJob": {
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Customer Export Job",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.example.CustomerExportJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 2
},
"target": {
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
},
"triggerStates": ["COMPLETED"],
"resultConditions": [] // only populated when CONDITIONAL state is used
}
]
}
</pre>

==GET details of an existing job chain==
'''<code>GET http(s)://localhost/rest/chains/{jobChainId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChain</code>

Returns details of a configured job chain, or a 404 if not found. Contains the same set of fields as the job chain listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"jobChainId": 1,
"schedule": "* * * * *", // if specified
"scheduleDescription": "Every minute every day", (as of 5.2.0)
"active": true,
"sourceJob": {
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Order Export Job",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.example.OrderExportJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 2
},
"target": {
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
},
"triggerStates": ["FAILED", "CONDITIONAL"],
"resultConditions": [ // only populated when CONDITIONAL state is used
{
"variableName": "exportFile",
"operator": "EXISTS",
"values": [] // empty list when values do not apply
},
{
"variableName": "fileSize",
"operator": "GREATER_THAN",
"values": ["0"] // list with one element when multiples aren't applicable
},
{
"variableName": "status",
"operator": "IN",
"values": ["EXPORTED", "ZIPPED"]
}
]
}
</pre>

==POST a new job chain==

'''<code>POST http(s)://localhost/rest/chains</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.JobChainUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChain</code>

Creates a new job chain.

'''Sample Request'''
<pre>
{
"sourceJobId": 12,
"targetJobId": 54,
"schedule": "* * * * *", //optional
"active": true,
"triggerStates": ["CONDITIONAL", "FAILED"],
"resultConditions": [ // only supplied when CONDITIONAL state is supplied
{
"variableName": "exportFile",
"operator":"EXISTS" // no "values" field required for EXISTS or NOT_EXISTS
},
{
"variableName": "fileSize",
"operator": "GREATER_THAN",
"values":["0"] // in this case, only one value allowed
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! 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.
|-
| active || Y || Flag to indicate whether the chain is active or not.
|-
| triggerStates || Y || One or more job chain states as defined in [[Unified_API#Enumerations|Enumerations]]. Note that <code>CONDITIONAL</code> and <code>COMPLETED</code> types cannot be used on the same chain.
|-
| resultConditions || Y/N || Conditions based on job results that apply to the <code>CONDITIONAL</code> 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 <code>variableName</code>, an <code>operator</code> as defined in [[Unified_API#Enumerations|Enumerations]], and for most operators, a list of <code>values</code>. The <code>EXISTS</code> and <code>NOT EXISTS</code> operators do not use values, so they must not be supplied. Operators <code>IN</code> and <code>NOT IN</code> support one or more values, and all other operators accept a single value in the <code>values</code> list. Values for this field map to bean class <code>com.carfey.ops.api.enums.JobChainConditionOperator</code>.
|}

Responses have the same format as GET.

==PUT updates to an existing job chain==

'''<code>PUT http(s)://localhost/rest/chains/{jobChainId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.JobChainUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChain</code>

Updates an existing job chain. Returns a 404 if not found.

Requests and responses have the same format as POST.

==DELETE an existing job chain==
''Available as of version 2.6.''

'''<code>DELETE http(s)://localhost/rest/chains/{jobChainId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChain</code>

Deletes a job chain. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the job chain before the delete.

= Job Conflict Endpoints =

''As of Obsidian 2.4.

==GET a list of job conflicts ==
'''<code>GET http(s)://localhost/rest/conflicts</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.ConflictListing</code>

Lists the configured job conflicts. Non-conflicted jobs are also included in the return value.

Conflicting jobs are returned in priority order within the same list. Multiple conflicting job sets can be returned in the <code>conflictJobs</code> field.

'''Sample Response (with inline comments)'''
<pre>
{
"conflictJobs": [
[
{
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set A - 1",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"folder": "Production/Test", // as of 4.1.0
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 2
},
{
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set A - 2",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
}
],
[
{
"jobId": 53,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set B - 1",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 2
},
{
"jobId": 54,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set B - 2",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
},
{
"jobId": 55,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set B - 3",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
}
],
],
"nonConflictJobs": [
{
"jobId": 56,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Non-Conflicted Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
}
]
}
</pre>

==PUT updates to job conflicts ==

'''<code>PUT http(s)://localhost/rest/conflicts</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.ConflictUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Replaces the current job conflict configuration with the supplied configuration.

'''Sample Request'''
<pre>
{

// Note that if Job 5 and Job 2 are scheduled for the same minute, Job 5 will run first as it is selected as the highest priority job from the first conflict set.
// When priority is significant and varies across different sets, ensure your conflict sets are in the desired order.
"conflicts": [
[1, 2, 3, 5], // Job 1 has highest priority
[2, 5, 4] // Job 2 also conflicts with 4 & 5.
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| conflicts || N || A list of lists containing job IDs. Each inner list 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.
|}

Responses have the same format as GET.

==GET a list of conflicts for a specific job==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}/conflicts</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobConflictListing</code>

Lists all jobs that conflict with the requested job.

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.

'''Sample Response (with inline comments)'''
<pre>
{
"conflictJobs": [
{
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Conflict A",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 2
},
{
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Conflict B",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
},
{
"jobId": 56, // this is the requested job
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Requested Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
}
],
"job": {
"jobId": 56,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Requested Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll": false,
"revision": 5
}
}
</pre>

= Scheduling Hosts Endpoints =

==GET a list of known scheduling hosts==
'''<code>GET http(s)://localhost/rest/hosts</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostListing</code>

Returns a list of known hosts. These are either running or recently shut down abnormally. Hosts that shut down normally are unregistered on shutdown. Note that returned IDs are transient and may change after startup or shutdown or a node. Heartbeat time indicates when the server last performed the heartbeat health check against the database.

'''Sample Response'''
<pre>
{
"hosts": [
{
"id": 32,
"name": "production1",
"heartbeatTime": "2013-01-05T21:15:59-0800",
"enabled": true
},
{
"id": 33,
"name": "production2",
"heartbeatTime": "2013-01-05T21:15:59-0800",
"enabled": false
}
]
}
</pre>

==GET details on an existing scheduling host==
'''<code>GET http(s)://localhost/rest/hosts/{id}</code>'''

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostDetail</code>

Returns the requested host, or a 404 if not found.

'''Note:''' The name field corresponds to the host name, as described [[Getting_Started#Setting_Host_Names|here]]. Explicit host names should be set if you intend to rely known host names in this endpoint. Heartbeat time indicates when the server last performed the heartbeat health check against the database.

'''Sample Response'''
<pre>
{
"host": {
"id": 33,
"name": "production1",
"heartbeatTime": "2013-01-05T21:18:18-0800",
"licenceLeaseExpiryUtc": "2017-06-15 01:36:06",
"enabled": true,
"licenceStatus": "internet_node_verified",
"licenceLeaseExpiryUtc": "2017-06-15 02:15:42"
}
}
</pre>

==GET health details on an existing scheduling host==
''As of Obsidian 6.3.0''

<code>GET http(s)://localhost/rest/hosts/{id}/health</code>

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}/health</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostDetail</code>

The intended use of this endpoint is as a health check. This endpoint response is to be parsed to evaluate health as it will include full health details with 200 response code if all is well, and a 400 if any part of system is unhealthy including license verification, job queuer and/or job spawner.

'''Note:''' The name field corresponds to the host name, as described [[Getting_Started#Setting_Host_Names|here]]. Explicit host names should be set if you intend to rely known host names in this endpoint. Heartbeat time indicates when the server last performed the heartbeat health check against the database.

'''Sample Response'''
<pre>
{
"host": {
"id": 243,
"name": "obsidian.production",
"heartbeatTime": "2025-07-17T20:28:34Z",
"licenceLeaseExpiryUtc": "2025-07-18 01:27:14",
"enabled": true,
"licenceStatus": "internet_node_verified",
"jobQueuerStatus": "healthy",//or laggy,delayed,unresponsive
"jobQueuerUpdateTimeUtc": "2025-07-17 20:28:28",
"jobSpawnerStatus": "healthy"//or laggy,delayed,unresponsive
"jobSpawnerUpdateTimeUtc": "2025-07-17 20:28:20",
"createdDate": "2025-07-17T19:27:13Z",
"createdBy": "SchedulerStarter.startUp",
"lastUpdatedBy": "SchedulerStarter.designator",
"lastUpdatedDate": "2025-07-17T20:28:34Z",
}
}
</pre>

==GET licence details on an existing scheduling host==
'''<code>GET http(s)://localhost/rest/hosts/{id}/licence_health</code>'''        ''Prior to 4.5'': '''<code>GET http(s)://localhost/rest/hosts/licenceHealthCheck/{id}</code>'''

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}/licence_health</code>'''        ''Prior to 4.5'': '''<code>GET http(s)://localhost/rest/hosts/licenceHealthCheck/names/{name}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostDetail</code>

The intended use of this endpoint is as a health check. This endpoint is identical to the [[REST_Endpoints#GET_details_on_an_existing_scheduling_host |GET details on an existing scheduling host]] above, with the exception that it will return a 400 if the licence has expired or is in some way invalid.

Returns the requested host with licence status, or a 404 if not found, or a 400 if the licence is invalid or its lease has expired.

'''Note:''' The name field corresponds to the host name, as described [[Getting_Started#Setting_Host_Names|here]]. Explicit host names should be set if you intend to rely known host names in this endpoint. Heartbeat time indicates when the server last performed the heartbeat health check against the database.

'''Sample Response'''
<pre>
{
"host": {
"id": 33,
"name": "production1",
"heartbeatTime": "2013-01-05T21:18:18-0800",
"licenceLeaseExpiryUtc": "2017-06-15 01:36:06",
"enabled": true,
"licenceStatus": "internet_node_verified",
"licenceLeaseExpiryUtc": "2017-06-15 02:15:42"
}
}
</pre>

==PUT updates to an existing scheduling host==
'''<code>PUT http(s)://localhost/rest/hosts/{id}</code>'''

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.host.HostUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostDetail</code>

Updates the enabled status of the requested host, or a 404 if not found. This endpoint is used to enable or disable scheduling nodes.

'''Note:''' The name field corresponds to the host name, as described [[Getting_Started#Setting_Host_Names|here]]. Explicit host names should be set if you intend to rely known host names in this endpoint.

'''Sample Request'''
<pre>
{
"enabled": false
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| enabled || Y || Should this host should be enabled?
|}

Responses have the same format as GET.

= Event Hooks Endpoints =
''As of Obsidian 5.4.0''

==GET event hooks==
'''<code>GET http(s)://localhost/rest/event_hooks</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.EventHookListing</code>

Returns all event hooks across the cluster.

'''Sample Response'''
<pre>
{
"hostEventHooks": [
{
"host": "prod-obsidian-RG1",
"eventHooks": [
{
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"name": "SlackEventHook",
"status": "INACTIVE",
"registrationTime": "2024-06-01T15:52:07-0400",
"heartbeat": "2024-06-01T16:52:09-0400",
"markedInactiveAt": "2024-06-01T16:52:09-0400" --if applicable
}
]
},
{
"host": "prod-obsidian-HL1",
"eventHooks": [
{
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"name": "SlackEventHook",
"status": "ACTIVE",
"registrationTime": "2024-06-01T18:08:11-0400",
"heartbeat": "2024-06-01T19:01:37-0400"
}
]
}
]
}
</pre>

==GET event hooks on host==

'''<code>GET http(s)://localhost/rest/hosts/{id}/event_hooks</code>'''

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}/event_hooks</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.EventHookListing</code>

Returns all event hooks for the given host.

'''Sample Response'''
<pre>
{
"hostEventHooks": [
{
"host": "prod-obsidian-RG1",
"eventHooks": [
{
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"name": "SlackEventHook",
"status": "INACTIVE",
"registrationTime": "2024-06-01T15:52:07-0400",
"heartbeat": "2024-06-01T16:52:09-0400",
"markedInactiveAt": "2024-06-01T16:52:09-0400" --if applicable
}
]
}
]
}
</pre>

==POST event hook pause or resume ==
''As of Obsidian 5.5.0''

'''<code>POST http(s)://localhost/rest/event_hooks</code>'''

Alternate (by host id): POST http(s)://localhost/rest/hosts/{id}/event_hooks

Alternate (by host name): POST http(s)://localhost/rest/hosts/names/{name}/event_hooks

'''Request bean class:''' <code>com.carfey.ops.api.bean.host.UpdateEventHookRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.EventHookListing</code>

Requests a specific event hook on a specific host to either Pause or Resume

'''Sample Request'''

<pre>
{
"hostName": "obsidian-prod-1",//only used when using non host-specific event_hooks endpoint
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"eventHookName": "SlackEventHook"
"eventHookAction": "PAUSE"
}
</pre>

'''Sample Response'''
<pre>
{
"hostEventHooks": [
{
"host": "obsidian-prod-1",
"eventHooks": [
{
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"name": "SlackEventHook",
"status": "ACTIVE",
"registrationTime": "2024-06-01T15:52:07-0400",
"heartbeat": "2024-06-01T16:52:09-0400",
"requestedStatus" : "PAUSE",
"requestedBy" : "carey-ops"
}
]
}
]
}
</pre>

= Custom Calendar Endpoints =

''As of Obsidian 2.0. Format revised in 2.3.''

The following endpoints allow for managing of [[Job_Features#Custom_Calendars|Custom Calendars]].

==GET a list of custom calendars==
'''<code>GET http(s)://localhost/rest/calendars</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendarListing</code>

Returns a list of custom calendars.

'''Sample Response'''
<pre>
{
"customCalendars": [
{
"revision": 0,
"dates": ["2013-01-01", "2013-02-18", "2013-04-01", "2013-05-20"],
"name": "Corporate Holidays 2013",
"customCalendarId": 1
},
{
"revision": 0,
"dates": ["2013-01-01", "2013-02-18", "2013-04-01", "2013-05-20"],
"name": "Corporate Holidays 2014",
"customCalendarId": 2
}
]
}
</pre>
==GET details on an existing custom calendar==
'''<code>GET http(s)://localhost/rest/calendars/{id}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendar</code>

''As of Obsidian 2.3.''

Returns the requested custom calendar, or a 404 if not found..

'''Sample Response'''
<pre>
{
"revision": 0,
"dates": ["2013-01-01", "2013-02-18", "2013-04-01", "2013-05-20"],
"name": "Corporate Holidays 2013",
"customCalendarId": 1
}
</pre>

==POST a new custom calendar ==
'''<code>POST http(s)://localhost/rest/calendars/</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendarUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendar</code>

Updates the name and dates of the requested calendar, or a 404 if not found.

'''Sample Request'''
<pre>
{
"name": "Cal1",
"dates": ["2016-10-14" ,"2018-06-14"],
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| name|| Y || Calendar name
|-
| dates|| Y || Dates to exclude
|}

Responses have the same format as GET.

==PUT updates to an existing custom calendar==
'''<code>PUT http(s)://localhost/rest/calendars/{id}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendarUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendar</code>

Updates the name and dates of the requested calendar, or a 404 if not found.

'''Sample Request'''
<pre>
{
"name": "Cal2",
"dates": ["2018-06-13","2016-10-13"]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| name|| Y || Calendar name
|-
| dates|| Y || Dates to exclude
|}

Responses have the same format as POST.

==DELETE an existing custom calendar==

''Available as of version 3.0.''

'''<code>DELETE http(s)://localhost/rest/calendars/{id}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendar</code>

Deletes a custom calendar. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the calendar before the delete.

= Subscriber Endpoints =

''As of Obsidian 3.0.''

==GET a list of subscribers==
'''<code>GET http(s)://localhost/rest/subscribers</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.SubscriberListing</code>

Returns a list of configured notification subscribers.

'''Sample Response (with inline comments)'''
<pre>
{
"subscribers": [
{
"id": 1,
"emailAddress": "test@example.com",
"active": true,
"generalSubscriptions": [
{
"category": "QUEUE",
"level": "ERROR",
"active": true,
},
{
"category": "JOB",
"level": "ERROR",
"active": true,
"job" : { // only exists when the subscription applies to a specific job
"recoveryType": "NONE",
"jobId": 1,
"pickupBufferMinutes": 2,
"nickname": "Cleanup Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.JobHistoryCleanupJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"chainAll": false,
"hostPreference": true,
"revision": 52
}
}
],
"jobExecutionSubscriptions": [
{
"allJobs": true,
"jobs": [], // always empty when allJobs is true
"triggerStates": [ "DIED", "FAILED", "RECOVERY" ],
"resultConditions": [], // present when CONDITIONAL triggerState is used
"active": false
},
{
"allJobs": false,
"jobs": [
{
"recoveryType": "NONE",
"jobId": 1,
"pickupBufferMinutes": 2,
"nickname": "Cleanup Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.JobHistoryCleanupJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"chainAll": false,
"hostPreference": true,
"revision": 52
}
],
"triggerStates": [ "CONDITIONAL" ],
"resultConditions": [
{
"variableName": "cleanupState",
"operator": "EQUALS",
"values": [ "incomplete" ] // depending on the operator, values may be empty, have 1 value, or multiple.
},
{
"variableName": "warnings",
"operator": "EXISTS",
"values": []
}
],
"active": true
}
]
},
{
"id": 2,
"emailAddress": "inactive@example.com",
"active": false,
"generalSubscriptions": [],
"jobExecutionSubscriptions": []
}
]
}
</pre>

==GET details of an existing subscriber==
'''<code>GET http(s)://localhost/rest/subscribers/{subscriberId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Subscriber</code>

Returns details of an existing subscriber, or a 404 if not found. Contains the same set of fields as the listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 1,
"emailAddress": "test@example.com",
"active": true,
"generalSubscriptions": [
{
"active": true,
"category": "QUEUE",
"level": "ERROR"
}
],
"jobExecutionSubscriptions": [
{
"active": false,
"allJobs": true,
"jobs": [],
"triggerStates": [ "DIED", "FAILED", "RECOVERY" ],
"resultConditions": []
}
]
}
</pre>

==POST a new subscriber==

'''<code>POST http(s)://localhost/rest/subscribers</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.notification.SubscriberUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Subscriber</code>

Creates a new notification subscriber.

'''Sample Request'''
<pre>
{
"emailAddress": "test@example.com",
"active": true,
"generalSubscriptions": [
{
"category": "JOB",
"level": "ERROR",
"active": true,
"jobId": 123 // optional, and only valid when a job-related category is selected
}
],
"jobExecutionSubscriptions":[
{
"active": false,
"allJobs": true,
"triggerStates": [ "DIED", "FAILED", "RECOVERY" ]
},
{
"active": true,
"jobIds": [ 123 ], // should not be supplied with the allJobs flag which takes precedence
"triggerStates": [ "CONDITIONAL" ],
"resultConditions": [
{
"variableName": "cleanupState",
"operator": "EQUALS",
"values": [ "incomplete" ] // depending on the operator, values may be empty, have 1 value, or multiple.
}
]
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! 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 general subscriptions. Each item contains a required subscription <code>category</code> and <code>level</code> as defined in [[Unified_API#Enumerations|Enumerations]], an optional <code>jobId</code> and an optional <code>active</code> flag which defaults to false.

'''Note:''' Only <code>ERROR</code>, <code>WARNING</code> AND <code>INFO</code> are valid values for <code>level</code>. Only <code>JOB</code>, <code>JOB_CHAIN</code>, <code>JOB_CONFIG</code>, <code>JOB_RECOVERY</code>, <code>LICENCE</code>, <code>QUEUE</code>, <code>SYSTEM_PARAMETER</code> and null are valid values for <code>category</code>.
|-
| jobExecutionSubscriptions || N || Zero or more job execution subscriptions. Each item contains a required <code>triggerStates</code> field containing at least one subscription job status as defined in [[Unified_API#Enumerations|Enumerations]]. Note that <code>CONDITIONAL</code> and <code>COMPLETED</code> types cannot be used on the same chain.

If the <code>CONDITIONAL</code> state is selected, at least one condition must be supplied in the <code>resultConditions</code> field. Result conditions consist of a <code>variableName</code>, an <code>operator</code> as defined in [[Unified_API#Enumerations|Enumerations]], and for most operators, a list of <code>values</code>. The <code>EXISTS</code> and <code>NOT EXISTS</code> operators do not use values, so they must not be supplied. Operators <code>IN</code> and <code>NOT IN</code> support one or more values, and all other operators accept a single value in the <code>values</code> list. Values for this field map to bean class <code>com.carfey.ops.api.enums.JobSubscriptionConditionOperator</code>.

In addition, two additional optional fields control which jobs the subscription applies to. <code>jobIds</code> is used to specify specific jobs, while <code>allJobs</code> may be set to true to make it apply to all jobs. If <code>jobIds</code> is supplied and <code>allJobs</code> is set to true, <code>jobIds</code> will be ignored.

Finally, the <code>active</code> flag may be supplied which defaults to true.
|}

Responses have the same format as GET.

==PUT updates to an existing subscriber ==

'''<code>PUT http(s)://localhost/rest/subscribers/{subscriberId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.notification.SubscriberUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Subscriber</code>

Updates an existing subscriber. Returns a 404 if not found.

Requests and responses have the same format as POST.

==DELETE an existing subscriber==

'''<code>DELETE http(s)://localhost/rest/subscribers/{subscriberId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Subscriber</code>

Deletes a subscriber. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the subscriber before the delete.

= Templates Endpoints =

''As of version 3.0.''

These endpoints allow for managing notification templates.

==GET a list of templates==
'''<code>GET http(s)://localhost/rest/templates</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.TemplateListing</code>

Returns a list of configured templates.

'''Sample Response (with inline comments)'''
<pre>
{
"templates":[
{
"id": 1,
"name": "Obsidian Default Job Template",
"active": true,
"category": "JOB",
"defaultForJobs": true, // indicates if it is the default job template for the category
"jobs": [ // only present for job categories when defaultForJobs is false
{
"recoveryType": "NONE",
"jobId": 1,
"pickupBufferMinutes": 2,
"nickname": "Cleanup Job",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.JobHistoryCleanupJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"chainAll": false,
"hostPreference": true,
"revision": 52
}
],
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Obsidian {{hostName}} Body content..."
},
{
"id": 2,
"name": "Obsidian Default Other Template",
"active": true,
"defaultForJobs": false,
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Obsidian {{hostName}} Body content..."
}
]
}
</pre>

==GET details of an existing template==
'''<code>GET http(s)://localhost/rest/templates/{templateId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Template</code>

Returns details of a configured template, or a 404 if not found. Contains the same set of fields as the template listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 2,
"name": "Obsidian Default Other Template",
"active": true,
"category": "LICENCE", // if missing, it is the default generic template
"defaultForJobs": false,
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Obsidian {{hostName}} Body content..."
}
</pre>

==POST a new template==

'''<code>POST http(s)://localhost/rest/templates</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.notification.TemplateUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Template</code>

Creates a new template.

'''Sample Request'''
<pre>
{
"name": "Cleanup Job Template",
"active": true,
"category": "JOB", // category not required when it is the default template
"defaultForJobs": false, // when true, jobIds are ignored
"jobIds": [ 123, 456 ],
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Obsidian {{hostName}} Body content..."
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! 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 as defined in [[Unified_API#Enumerations|Enumerations]], or null if it is the default generic template. Supports multiple values. Not all categories are supported. Only <code>JOB</code>, <code>JOB_CHAIN</code>, <code>JOB_CONFIG</code>, <code>JOB_RECOVERY</code>, <code>LICENCE</code>, <code>QUEUE</code>, <code>SYSTEM_PARAMETER</code> 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 [[Email_Templates|Mustache template]] for the subject.
|-
| bodyTemplate || Y || A valid [[Email_Templates|Mustache template]] for the body.
|}

Responses have the same format as GET.

==PUT updates to an existing template==

'''<code>PUT http(s)://localhost/rest/templates/{templateId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.notification.TemplateUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Template</code>

Requests and responses have the same format as POST.

==DELETE an existing template ==

'''<code>DELETE http(s)://localhost/rest/templates/{templateId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Template</code>

Deletes a template. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the template before the delete.

= Notification Endpoints =

''As of Obsidian 3.0''

These endpoints allow you to query what notifications were triggered in Obsidian. Note that existence of records does not necessarily indicate the notification was successfully sent or received.

==GET a list of notifications==
'''<code>GET http(s)://localhost/rest/notifications[?category=QUEUE&level=ERROR&start=1356987599000&end=1357510546000&startKey=123]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.NotificationListing</code>

Returns a list of notifications, optionally filtered by query string parameters. Results are ordered roughly according to when they were created, but ordering is not guaranteed to be in order of created time.

'''Note:''' The <code>nextPageStartKey</code> field in the response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen). To fetch the next page of results, invoke the same endpoint with the <code>startKey</code> query string parameter set to the returned <code>nextPageStartKey</code>.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| category || N || The category of the notifications as defined in [[Unified_API#Enumerations|Enumerations]]. Supports multiple values.
|-
| level || N || The logging level of the notifications defined in [[Unified_API#Enumerations|Enumerations]]. Supports multiple values.
|-
| 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 <code>nextPageStartKey</code>.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"nextPageStartKey": "123",
"notifications": [
{
"id": 51,
"log": {
"id": 292,
"eventTime": "2015-01-22T16:44:00-0800",
"host": "Demo",
"category": "JOB_RUN",
"level": "INFO",
"summary": "Completed job [Job History Cleanup 033] scheduled for [2015-01-22 16:44:00]."
},
"subscriber":{
"id": 51,
"emailAddress": "test@test.com",
"active": true // current active state (not when triggered)
}
},
{
"id": 52,
"log": {
"id": 295,
"eventTime": "2015-01-22T16:44:00-0800",
"host": "Demo",
"category": "JOB_RUN",
"level": "INFO",
"summary": "Completed job [Job History Cleanup 145] scheduled for [2015-01-22 16:44:00]."
},
"subscriber": {
"id": 51,
"emailAddress": "test@test.com",
"active": true
}
},
]
}
</pre>

==GET details of an existing notification==
'''<code>GET http(s)://localhost/rest/notifications/{id}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Notification</code>

Returns detail of an existing notification, which contains the same fields as the listing endpoint. Returns a 404 if not found.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 51,
"log": {
"id": 292,
"eventTime": "2015-01-22T16:44:00-0800",
"host": "Demo",
"category": "JOB_RUN",
"level": "INFO",
"summary": "Completed job [Job History Cleanup 033] scheduled for [2015-01-22 16:44:00]."
},
"subscriber":{
"id": 51,
"emailAddress": "test@test.com",
"active": true // current active state (not when triggered)
}
}
</pre>

= Log Endpoints =

''As of Obsidian 3.0''

==GET a list of logs==
'''<code>GET http(s)://localhost/rest/logs[?host=host1&filterText=error&category=QUEUE&level=ERROR&start=1356987599000&end=1357510546000&startKey=123]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.log.LogListing</code>

Returns a list of event logs, optionally filtered by query string parameters. Results are ordered roughly according to when they were created, but ordering is not guaranteed to be in order of created time.

'''Note:''' The <code>nextPageStartKey</code> field in the response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen). To fetch the next page of results, invoke the same endpoint with the <code>startKey</code> query string parameter set to the returned <code>nextPageStartKey</code>.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! 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 || The category of the log as defined in [[Unified_API#Enumerations|Enumerations]]. Supports multiple values.
|-
| level || N || The logging level of the log as defined in [[Unified_API#Enumerations|Enumerations]]. Supports multiple values.
|-
| 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 <code>nextPageStartKey</code>.
|}

'''Sample Response'''
<pre>
{
"nextPageStartKey" : "123",
"logs": [
{
"id": 1619,
"eventTime": "2015-01-21T13:59:43-0800",
"host": "Demo",
"category": "JOB_SPAWNER",
"level": "DEBUG",
"summary": "Spawning [Test Job] scheduled for 2015-01-21 13:59:00"
},
{
"id": 4,
"eventTime": "2015-01-20T11:54:49-0800",
"host": "Demo",
"category": "LICENCE",
"level": "INFO",
"summary": "Successfully refreshed licence from server https://licence.carfey.com/licence for 120 minutes."
}
]
}
</pre>

==GET details of an existing log==
'''<code>GET http(s)://localhost/rest/logs/{logId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.log.Log</code>

Returns detail of an existing log entry. Returns a 404 if not found.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 1619,
"eventTime": "2015-01-21T13:59:43-0800",
"host": "Demo",
"category": "JOB_SPAWNER",
"level": "DEBUG",
"summary": "Spawning [Test Job] scheduled for 2015-01-21 13:59:00"
}
</pre>

= System Parameter Endpoints =

''As of version 3.0.''

==GET a list of system parameters==
'''<code>GET http(s)://localhost/rest/system_parameters</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.SystemParameterListing</code>

Returns a list of system parameters which can be edited.

'''Sample Response (with inline comments)'''
<pre>
{
"parameters": [
{
"name": "clientKeyServerUrl",
"description": "Address of the primary key server. If running a proxy, this should be the address of the proxy server.",
"type": "STRING",
"category": "LICENCE",
"value": "https://licence.carfey.com/licence"
},
{
"name": "maxJobThreads",
"description": "This value determines the maximum number of threads that will be spawned for running jobs. Changes to this value require a server restart.",
"type": "INTEGER",
"category": "JOB_SPAWNER",
"value": "1000"
}
]
}
</pre>

==GET details of a system parameter ==
'''<code>GET http(s)://localhost/rest/system_parameters/{name}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.SystemParameter</code>

Returns details of a system parameter, or a 404 if not found. Contains the same set of fields as the listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"name": "clientKeyServerUrl",
"description": "Address of the primary key server. If running a proxy, this should be the address of the proxy server.",
"type": "STRING",
"category": "LICENCE",
"value": "https://licence.carfey.com/licence"
}
</pre>

==PUT updates to a system parameter ==

'''<code>PUT http(s)://localhost/rest/system_parameters/{name}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.system.SystemParameterUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.SystemParameter</code>

Updates a system parameter's value. Values are accepted as strings, but must be valid for their target type (integer, boolean, etc.). Returns a 404 if not found.

'''Sample Request'''
<pre>
{
"value": "60"
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| value || N || The new value for the system parameter, which can be converted into the appropriate target type. Some string values support an empty value.
|}

Responses have the same format as GET.

= User Endpoints =

''As of version 3.0.''

Note that user endpoints are only available when using Obsidian's native authentication, and do not support LDAP or custom authentication.

==GET a list of users==
'''<code>GET http(s)://localhost/rest/users</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.UserListing</code>

Returns a list of configured users.

'''Sample Response (with inline comments)'''
<pre>
{
"users": [
{
"id": 1,
"userName": "admin",
"active": true,
"roles": ["ADMIN","API"]
},
{
"id": 2
"userName": "reader",
"active": false,
"roles": [] // no roles means read-only
}
]
}
</pre>

==GET details of an existing user==
'''<code>GET http(s)://localhost/rest/users/{userId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.User</code>

Returns details of a configured user, or a 404 if not found. Contains the same set of fields as the user listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 1,
"userName": "admin",
"active": true,
"roles": ["ADMIN","API"]
}
</pre>

==POST a new user==

'''<code>POST http(s)://localhost/rest/users</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.user.UserCreationRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.User</code>

Creates a new user.

'''Sample Request'''
<pre>
{
"userName": "admin",
"active": true,
"roles": ["ADMIN","API"],
"password": "changeme"
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! 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 roles as defined in [[Unified_API#Enumerations|Enumerations]]. Supplying no roles indicates it is a normal read-only user.
|-
| password || Y || A password at least 6 characters long.
|}

Responses have the same format as GET.

==PUT updates to an existing user==

'''<code>PUT http(s)://localhost/rest/users/{userId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.user.UserUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.User</code>

Updates an existing user. Returns a 404 if not found. Semantics similar to a PATCH request are used, so that only supplied fields are updated. User names cannot be updated.

'''Sample Request'''
<pre>
{
"active": true,
"roles": ["ADMIN","API"],
"password": "changeme"
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| active || N || Whether the user is enabled. Defaults to the existing active state.
|-
| roles || N || Zero or more roles as defined in [[Unified_API#Enumerations|Enumerations]]. 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.
|}

Responses have the same format as POST.

==DELETE an existing user ==

'''<code>DELETE http(s)://localhost/rest/users/{userId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.User</code>

Deletes a user. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the user before the delete.

==GET a list of known MFA users==

''As of version 5.0.''

'''<code>GET http(s)://localhost/rest/users/mfa</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.MfaUserListing</code>

Returns all known users which may have Multi-Factor Authentication (MFA) resets applied. Exists to facilitate use of the MFA reset endpoint.

'''Sample Response'''
<pre>
{
"userNames": [
"admin",
"john.doe",
"operator"
]
}
</pre>

==PUT MFA user resets==

''As of version 5.0.''

'''<code>PUT http(s)://localhost/rest/users/mfa/reset</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.user.ResetMfaRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.MfaUserListing</code>

Resets the requested users' Multi-Factor Authentication (MFA) state so that they may perform MFA setup. This is useful when a user does not complete MFA setup within the required time, or when adding a user when not using Obsidian's native authentication.

'''Sample Request'''
<pre>
{
"userNames": [
"admin",
"john.doe",
"operator"
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| userNames || Y || The list of user names to reset. Note that these do not have to correspond to known Obsidian users, since it must support custom authentication methods.
|}

Responses echo the users in the request.

'''Sample Response'''
<pre>
{
"userNames": [
"admin",
"john.doe",
"operator"
]
}
</pre>

= System Restore Endpoints =

''As of version 3.0.''

These endpoinds can be used to import and export Obsidian's configuration, including job-related configuration, subscription-related configuration, users and system parameters. See [[Initializing_and_Restoring|Initializing and Restoring]] for more details.

==GET a system restore configuration ==
'''<code>GET http(s)://localhost/rest/system_restores[?excludeItem=users&jobNickname=jobname]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration</code>

Returns the system's exported configuration. The output from this endpoint can be used with the corresponding [[#PUT_a_system_restore_configuration|PUT endpoint]] directly.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| excludeItem || N || Allows filtering out of specific groups of system configuration items. Supported values are <code>jobs</code>, <code>chains</code>, <code>conflicts</code>, <code>systemParameters</code>, <code>customCalendars</code>, <code>globalParameters</code>, <code>users</code>, <code>templates</code>, <code>subscribers</code>. Filtering out jobs automatically also filters out chains and conflicts and drops any other job references (such as in templates and subscribers). Supports multiple values. Since 3.8.0.
|-
| jobNickname || 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). Supports multiple values. Since 3.8.0.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"jobs": [
{
"updateSchedule": false, // whether to apply the current schedule and any additional jobSchedules when the job already exists
"updateAttributes": false, // whether job attributes (jobClass, recoveryType, pickupBufferMinutes, etc.) will be updated when the job exists
"jobSchedules": [
{
"state": "DISABLED",
"effectiveDate": "2015-03-20T10:35:00-0700",
"endDate": "2999-12-31T23:59:00-0800"
}
],
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"minExecutionDuration": "2s",
"maxExecutionDuration": "3s",
"nickname": "Log Cleanup",
"folder": "Production/Test", // as of 4.1.0
"pickupBufferMinutes": 2,
"recoveryType": "NONE",
"hosts": [ "Demo-PC" ],
"ordinalParameters": [ // as of 3.8.0, prior to 3.8.0, parameters child element was at this level
"ordinal": 0, //as of 3.8.0
"parameters": [
{
"name": "level",
"type": "STRING",
"value": "ALL"
},
{
"name": "maxAgeDays",
"type": "INTEGER",
"value": "120"
}
]
],
"chainAll": false,
"hostPreference": true,
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"state": "ENABLED",
"schedule": "* * * * *",
"effectiveDate": "2015-01-01T00:00:00-0700"
"endDate": "2015-03-20T10:34:00-0700"
},
{
"updateSchedule": false,
"updateAttributes": false,
"jobSchedules": [],
"jobClass": "com.carfey.ops.job.script.GroovyJob",
"nickname": "Script Job",
"pickupBufferMinutes": 2,
"recoveryType": "NONE",
"hosts": [],
"ordinalParameters": [ // as of 3.8.0, prior to 3.8.0, parameters child element was at this level
"ordinal": 0, //as of 3.8.0
"parameters": [
{
name": "script",
"type": "STRING",
"value": "sdfds"
}
]
],
"chainAll": false,
"hostPreference": false,
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"state": "DISABLED",
"effectiveDate": "2015-01-01T00:00:00-0700"
"endDate": "2999-12-31T23:59:00-0800"
}
],
"users": [
{
"update": false, // when false, the user attributes will not be updated if the user already exists
"userName": "admin",
"active": true,
"roles": [
"API",
"ADMIN",
"WRITE"
],
"password": "changeme"
}
],
"chains": {
"replaceAll": false, // if set to false or omitted, chains will only be created if none exist - existing chains are not updated.
"items": [
{
"sourceJobNickname": "Script Job",
"targetJobNickname": "Log Cleanup",
"active": true,
"triggerStates": [
"FAILED",
"CONDITIONAL"
],
"resultConditions": [
{
"variableName": "dfdsfds",
"operator": "EQUALS",
"values": [
"sdfs"
]
}
]
}
]
},
"conflicts": [
[
"Script Job",
"Log Cleanup"
]
],
"customCalendars": [
{
"name": "Sample Calendar",
"dates": [
"2011-01-01"
]
}
],
"systemParameters": [
{
"name": "adHocJobsRespectFixedHostsRestrictions",
"description": "This value determines whether the Fixed Hosts restriction assigned to a Job is respected for Ad Hoc jobs.",
"category": "JOB",
"value": "true"
}
],
"templates": [
{
"jobNicknames": [],
"name": "Obsidian Default Job Template",
"active": true,
"category": "JOB",
"defaultForJobs": true,
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Body Template"
}
],
"subscribers": [
{
"generalSubscriptions": [
{
"jobNickname": "Log Cleanup",
"category": "JOB",
"level": "ERROR",
"active": true
}
],
"jobExecutionSubscriptions": [
{
"jobNicknames": [],
"allJobs": true,
"triggerStates": [
"CONDITIONAL",
"DIED",
"FAILED",
"RECOVERY"
],
"resultConditions": [
{
"variableName": "someVar",
"operator": "EQUALS",
"values": [
"someValue"
]
}
],
"active": true
}
],
"emailAddress": "test@example.com",
"active": true
}
]
}
</pre>

==PUT a system restore configuration==
'''<code>PUT http(s)://localhost/rest/system_restores</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration</code>

Imports the requested system restore configuration, updating, creating and replacing data based on the input.

'''Usage Note:''' Entities within the export are generally identified by their names. For details on required fields, formats and update logic, refer to the [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemRestoreManager.html#updateConfiguration(com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration,java.lang.String) Javadoc] and the [[Initializing_and_Restoring|Initializing and Restoring]] page. The Embedded API and REST API both use the same format and processing rules.

Requests are in the same format as the [[#GET_a_system_restore_configuration|GET endpoint's]] response.

Responses are in the same format as the GET and return the full Obsidian system restore configuration following the changes (not necessarily the same as the input).

= Schedule Alias Endpoints =

''As of version 5.0.''

These endpoints can be used to manage schedule aliases. See [[Admin_Schedule_Aliases|Schedule Aliases]] for more details.

==GET a list of schedule aliases ==
'''<code>GET http(s)://localhost/rest/schedule_aliases</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAliasListing</code>

Returns the system's schedule aliases.

'''Sample Response'''
<pre>
{
"scheduleAliases": [
{
"alias": "@every4Minutes",
"schedule": "0/4 * * * *",
"scheduleDescription": "Every 4th minute every day" (as of Obsidian 5.2.0)
},
{
"alias": "@dailyAtNoon",
"schedule": "12 * * * *",
"scheduleDescription": "At 12:00PM every day" (as of Obsidian 5.2.0)
},
{
"alias": "@threeTimesWeekly",
"schedule": "0 0 * 1,3,5 *",
"scheduleDescription": "At midnight on Mondays, Wednesdays, Fridays" (as of Obsidian 5.2.0)
},
{
"alias": "@combinedExample",
"schedule": "@dailyAtNoon;@threeTimesWeekly",
"scheduleDescription": "At 12:00PM every day - AND - At midnight on Mondays, Wednesdays, Fridays" (as of Obsidian 5.2.0)
}
]
}
</pre>

==PUT a schedule alias==
'''<code>PUT http(s)://localhost/rest/schedule_aliases/{alias}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAliasUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAlias</code>

'''Sample Request'''
<pre>
{
"schedule": "5 11 * * 2"
}
</pre>

'''Sample Response'''
<pre>
{ "alias": "@1105AMTuesdays",
"schedule": "5 11 * * 2",
"schedule": "At 11:05AM on Tuesdays" (as of Obsidian 5.2.0)
}
</pre>

==GET a schedule alias==
'''<code>GET http(s)://localhost/rest/schedule_aliases/{alias}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAlias</code>

'''Sample Response'''
<pre>
{ "alias": "@1105AMTuesdays",
"schedule": "5 11 * * 2",
"schedule": "At 11:05AM on Tuesdays" (as of Obsidian 5.2.0)
}
</pre>

==DELETE a schedule alias==
'''<code>DELETE http(s)://localhost/rest/schedule_aliases/{alias}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAlias</code>

'''Sample Response'''
<pre>
{ "alias": "@1105AMTuesdays",
"schedule": "5 11 * * 2"
}
</pre>

= Job Execution Statistics Endpoints =

''As of version 6.4.0.''

To retrieve job execution statistics. Assumes [[Built-in_Jobs#Obsidian_Execution_Statistics_Job|Execution Statistics Job]] has run to completion at least once.

== GET a list of job statistics ==
'''<code>GET http(s)://localhost/rest/stats[?jobNickname=jobname&job_id=1&duration=six_months&unit=seconds&status=completed&acrossHosts=false&host=prod.obsidian-a1&host=prod.obsidian-a2]</code>'''

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobNickname || N || Allows targeting only specific jobs by nickname in the stats export. Supports multiple values.
|-
| jobId || N || Allows targeting only specific jobs by id in the stats export. Supports multiple values.
|-
| duration || N || Allows targeting stats durations. See [[Unified_API#Enumerations|Enumerations]] for valid values. Supports multiple values.
|-
| unit || N || Allows targeting stats units. See [[Unified_API#Enumerations|Enumerations]] for valid values. Supports multiple values.
|-
| status || N || Allows targeting stats terminal statuses. See [[Unified_API#Enumerations|Enumerations]] for valid values. Supports multiple values.
|-
| host || N || Allows targeting stats from specific hosts. Supports multiple values.
|-
| acrossHosts || N || Allows selecting stats collected across all hosts. Boolean.
|}

'''Response bean class:''' <code>com.carfey.ops.api.bean.stats.StatsListing</code>

Returns the cluster's job execution statistics.

'''Sample Response'''
<pre>
{
"stats": [
{
"statsId": 733,
"jobId": 55,
"nickname": "Cache Reloader",
"host": "prod.obsidian-a1",
"status": "COMPLETED",
"unit": "SECONDS",
"duration": "YEAR",
"start": "2024-12-14",
"end": "2025-12-14",
"count": 97,
"average": 7701.463918,
"median": 6965.0,
"mode": 62,
"min": 62.0,
"max": 17925.0,
"variance": 23055960.248698,
"standardDeviation": 4801.66
},
{
"statsId": 545,
"jobId": 55,
"nickname": "Cache Reloader",
"host": "prod.obsidian-a2",
"status": "COMPLETED",
"unit": "HOURS",
"duration": "YEAR",
"start": "2024-12-14",
"end": "2025-12-14",
"count": 114,
"average": 2.238684,
"median": 1.932778,
"mode": 1,
"min": 0.015,
"max": 4.989444,
"variance": 2.18319,
"standardDeviation": 1.47756
}
],
"hosts": [
"prod.obsidian-a1",
"prod.obsidian-a2"
]
}
</pre>

2025-11-26T23:13:49Z

Craig:

Admin Job Stats

2025-11-26T23:11:36Z

Craig:

''' As of Obsidian 6.4.0 '''

Job Stats is where you can review and query the statistics collected by the [[Built-in_Jobs#Obsidian_Execution_Statistics_Job|Obsidian Execution Statistics Job]]. If no data is available, check that your job is scheduled and running successfully.

== Fields ==

Fields shown in the job stats table are:

* Job nickname (links to job configuration screen)
* Start and end (represent the date range for the stat collection <i>duration</i>
* Host (only shown if not view stats across hosts)
* [[Job_Features#Execution_Statuses|Status]] (only terminal statuses are available)
* Duration (lookback duration; one of Day, Two Day, Three Day, Five Day, Week, Month, Two Month, Three Month, Six Month, Year)
* Unit (unit of each stat; one of Seconds, Minutes, Hours)
* Total Executions (how many job executions are in the statistic)
* Average
* Median
* Mode (rounded down to whole number)
* Minimum
* Maximum
* Variance
* Standard Deviation

== Filtering ==

Stat records can be filtered by Job, Host, Duration, Unit, Status. You can also choose to view stats across hosts for which you can't filter hosts.

[[File:Obsidian-6.4.0-Job-Stats-Across-Hosts.png]]
[[File:Obsidian-6.4.0-Job-Stats-By-Host.png]]

== Exporting Results ==
The current contents of the table can be exported to Excel, CSV, XML or JSON 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.

Admin Job Stats

2025-11-26T23:09:52Z

Craig:

Job Stats is where you can review and query the statistics collected by the [[Built-in_Jobs#Obsidian_Execution_Statistics_Job|Obsidian Execution Statistics Job]]. If no data is available, check that your job is scheduled and running successfully.

== Fields ==

Fields shown in the job stats table are:

* Job nickname (links to job configuration screen)
* Start and end (represent the date range for the stat collection <i>duration</i>
* Host (only shown if not view stats across hosts)
* [[Job_Features#Execution_Statuses|Status]] (only terminal statuses are available)
* Duration (lookback duration; one of Day, Two Day, Three Day, Five Day, Week, Month, Two Month, Three Month, Six Month, Year)
* Unit (unit of each stat; one of Seconds, Minutes, Hours)
* Total Executions (how many job executions are in the statistic)
* Average
* Median
* Mode (rounded down to whole number)
* Minimum
* Maximum
* Variance
* Standard Deviation

== Filtering ==

Stat records can be filtered by Job, Host, Duration, Unit, Status. You can also choose to view stats across hosts for which you can't filter hosts.

[[File:Obsidian-6.4.0-Job-Stats-Across-Hosts.png]]
[[File:Obsidian-6.4.0-Job-Stats-By-Host.png]]

== Exporting Results ==
The current contents of the table can be exported to Excel, CSV, XML or JSON 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.

Built-in Jobs

2025-11-26T22:48:31Z

Craig:

Obsidian comes bundled with free [[Admin_Jobs|jobs]] for common tasks. These are provided in addition to [[Scripting Jobs]] to reduce implementation and testing time for common job functions.

As of '''Obsidian 2.7.0''', we have open-sourced our built-in convenience jobs under the [[https://opensource.org/license/mit/ MIT License]]. In the root of the installation folder, you can find the source in <code>obsidian-builtin-job-src.jar</code>.

= File Processing Jobs =

These jobs are provided to provide common basic file operations, such as file cleanup (deletion) and archiving. These jobs can be used to reduce the amount of code your organization needs to write.

== File Cleanup Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.FileCleanupJob</code>

''Introduced in version 2.0''

This job deletes files in specified paths based on one or more file masks (using regular expressions).

It supports the following configuration options:

* ''Directory (1 or more Strings)'' - A directory to scan for files. If recursive processing is enabled, child directories are also scanned.
* ''File Mask (0 or more Strings)'' - A regular expression that files must match to be deleted. This is based on <code>java.util.regex.Pattern</code>. To match all files, remove all configured values or use ".*" without quotes. If multiple values are used, files are eligible for deletion if they match any of the file masks.
* ''Abort on Deletion Failure (Boolean)'' - If deletion fails, should we fail the job?
* ''File Size Minimum (String)'' - The minimum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb).
* ''File Size Maximum (String)'' - The maximum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb).
* ''Minimum Time Since Modified (String)'' - The minimum age of a file to be deleted, based on the modified time. This can be specified in seconds, minutes, hours and days (e.g. 10s, 5m, 24h, 2d).
* ''Recursive (Boolean)'' - Whether files in subdirectories of the configured directories should be checked for matching files.

=== Customization ===
If you wish to tweak or customize behaviour of this job, it can be subclassed. The following methods may be overridden or extended by calling ''super'' methods:

* ''onStart'' - Called on job startup.
* ''onEnd'' - Called on job end, regardless of success or failure.
* ''shouldDelete'' - Determines if a file should be deleted.
* ''deleteMatchingFile'' - Deletes a matching file and saves a job result for its path.
* ''matchesAge'' - Determines if a file matches any age conditions (i.e. ''Minimum Time Since Modified''), or true if none are configured.
* ''matchesMask'' - Determines if a file matches any configured file masks, or true if none are configured.
* ''matchesSize'' - Determines if a file matches size conditions, or true if none are configured.
* ''processDirectory'' - Enumerates files in configured directories and calls ''shouldDelete'' and ''deleteMatchingFile'' as necessary.

'''Sample Configuration'''

[[Image:FileCleanup.png]]

== File Archive Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.FileArchiveJob</code>

''Introduced in version 2.0''

This job archives files passed in via a chained job's saved results. Therefore, it is intended to be used as a chained job only. One or more accessible absolute file paths can be passed in via job results called 'file'. Each one will be processed for archiving. For example, if you have a job that generates two files called 'customers.txt' and 'orders.txt', you will use <code>Context.saveJobResult(String, Object)</code> to save a value for each absolute file path (e.g. 'C:/customers.txt' and 'C:/orders.txt').

It supports the following configuration options:

* ''Archive Directory (1 or more Strings)'' - A directory to where an archive copy is placed.
* ''Rename Pattern (String)'' - How should we name the archive file? Rename patterns support the following tokens delimited by < and >:
** <code><filename></code> is the full original file name (e.g. 'abc.v1.txt')
** <code><basename></code> is the file with the last extension stripped (e.g. 'abc.v1')
** <code><ext></code> is the last file extension (e.g. 'txt')
** <code><ts:dateformat></code> corresponds to a timestamp formatted in the supplied SimpleDateFormat pattern (e.g. <code><ts:yyyy-MM-dd-HH-mm:ss></code>)
** other literals outside of < or >, or inside of < and > but not matching any preceding tokens.
** For example, to archive a GZIP version of a file with a timestamp with the extension 'gz', you can use the rename pattern <code><basename>.<ts:yyyy-MM-dd-HH-mm-ss>.<ext>.gz</code>.
** To maintain the original name, simply use the pattern <code><filename></code>.
* ''Delete Original File (Boolean)'' - Should we remove the original file after archiving?
* ''GZIP (Boolean)'' - Should the target archive file be compressed using GZIP?
* ''Overwrite Target File (Boolean)'' - If the archive file to be created already exists, should we overwrite it, or fail instead?
* ''File Size Minimum (String)'' - The minimum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb). As of Obsidian 6.0.1
* ''File Size Maximum (String)'' - The maximum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb). As of Obsidian 6.0.1
* ''Minimum Time Since Modified (String)'' - The minimum age of a file to be deleted, based on the modified time. This can be specified in seconds, minutes, hours and days (e.g. 10s, 5m, 24h, 2d). As of Obsidian 6.0.1

=== Customization ===
If you wish to tweak or customize behaviour of this job, it can be subclassed. The following methods may be overridden or extended by calling ''super'' methods:

* ''onStart'' - Called on job startup.
* ''onEnd'' - Called on job end, regardless of success or failure.
* ''determineArchiveFilename'' - Determines the name of the archive file based on the configured "Rename Pattern".
* ''processFile'' - For each input file, determines the archive file name and copies the original file to the archive.
* ''processDelete'' - If the original file is to be deleted, this method handles deleting the original file. If deletion fails, the job will fail, so if you wish to change his behaviour, you can override this method.

'''Sample Configuration'''

[[Image:FileArchiveJobConfig.png]]

== File Scanner Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.FileScannerJob</code>

''Introduced in version 2.2''

This job locates files in a directory matching one or more file masks (using Java regular expressions) and stores the result via source job results stored under the name <code>file</code> as absolute paths (Strings).

This job is intended to be conditionally chained to a job that knows how to process the results.

''Go File Pattern'' may used to ensure that files in the configured ''Directory'' are only picked up and saved if an expected token file exists. If ''Delete Go File'' is set to true, any found token files will be deleted. If this deletion fails, the job will abort and no <code>file</code> results are saved. Successfully deleted go files are stored as job results under the name <code>deletedGoFile</code>.

The job supports the following configuration options:

* ''Directory (String)'' - A directory to scan for files.
* ''File Pattern (1 or more Strings)'' - One or more file patterns (using <code>java.util.regex.Pattern</code>) that a file name must match to be considered a match. If any one of the configured patterns is a match, the file is considered a match.
* ''Go File Pattern (String)'' - A file pattern (using <code>java.util.regex.Pattern</code>) that must match at least one file in in the ''Go File Directory'' (or main ''Directory'' if not supplied) in order for files to be processed and saved as job results.
* ''Go File Directory (optional String)'' - The directory where we look for files matching the ''Go File Pattern''. If missing, the value for ''Directory'' is used.
* ''Delete Go File (Boolean)'' - If we find one or more go files, should we delete them? If deletion fails, the job will fail.
* ''File Size Minimum (String)'' - The minimum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb). As of Obsidian 6.0.1
* ''File Size Maximum (String)'' - The maximum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb). As of Obsidian 6.0.1
* ''Minimum Time Since Modified (String)'' - The minimum age of a file to be deleted, based on the modified time. This can be specified in seconds, minutes, hours and days (e.g. 10s, 5m, 24h, 2d). As of Obsidian 6.0.1

=== Customization ===
If you wish to tweak or customize behaviour of this job, it can be subclassed. The following methods may be overridden or extended by calling ''super'' methods:

* ''onStart'' - Called on job startup.
* ''onEnd'' - Called on job end, regardless of success or failure.
* ''listFiles'' - Lists files within the directory using the supplied patterns.
* ''postProcessFiles'' - This is a hook method called after all job results are saved and go files are deleted if applicable. It is called with all valid files that were found.
* ''deleteGoFiles'' - Deletes all found go files, saving a result if successful and throwing a RuntimeException if failing. This can be overriden to customize handling of failures.

'''Sample Configuration'''

[[Image:FileScannerConfig.png]]

= Maintenance Jobs =

These jobs are provided to help maintain the Obsidian installation. Automatic schedule configuration can be disabled via <code>com.carfey.obsidian.standardOutputStreamsEventHook.enabled=true</code> configuration.

== Job History Cleanup Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.JobHistoryCleanupJob</code>

This job will delete job history and related records beyond a configurable age in days. This is useful for keeping the database compact and clearing out old, unneeded data.

The value for <code>maxAgeDays</code> corresponds to the maximum age for records to retain. By default it is set to 365, but you may configure it to any desired value.

As of 3.0.1, the value for <code>maxAgeScheduleDays</code> corresponds to the maximum age for expired job schedules to retain. If this isn't specified, expired job schedules won't be deleted.

As of 3.4.0, the value for <code>maxAgeDays</code> is used to prune expired job schedules and <code>maxAgeScheduleDays</code> is no longer used.

'''Note:''' We recommend high volume users schedule the job weekly or less frequently and to schedule it for a non-peak time.

'''As of Obsidian 5.2.1''', this job is configured during new installations to run '@daily' keeping the last 380 days of history.

== Log Cleanup Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.LogCleanupJob</code>

This job will delete log database records beyond a configurable age in days. This is useful for keeping the database compact and clearing out old, unneeded data.

The value for <code>maxAgeDays</code> corresponds to the maximum age for records to retain. By default it is set to 365, but you may configure it to any desired value.

The value for <code>level</code> corresponds to the logging level of events to delete. You may specify multiple values, and the "ALL" option will result in all records matching the age setting being deleted. Valid levels to configure are: <code>FATAL</code>, <code>ERROR</code>, <code>WARNING</code>, <code>INFO</code>, <code>DEBUG</code>, and <code>TRACE</code>.

It is common to only delete lower severity level events, such as <code>INFO</code>, <code>DEBUG</code>, and <code>TRACE</code>, but retain higher severity messages.

'''Note:''' We recommend high volume users schedule the job weekly or less frequently and to schedule it for a non-peak time.

'''As of Obsidian 5.2.1''', this job is configured during new installations as follows:
* 1:00 AM for DEBUG/TRACE keeping the last 30 days of event logs.
* 1:30 AM for INFO keeping the last 60 days of event logs.
* 2:00 AM for WARNING/ERROR keeping the last 120 days of event logs.
* 2:30 AM for FATAL keeping the last 185 days of event logs.

== Notification Cleanup Job ==

''Introduced in Obsidian 4.9.0''

'''Job Class:''' <code>com.carfey.ops.job.maint.NotificationCleanupJob</code>

This job will delete notification database records beyond a configurable age in days. Optionally you may constrain this to specific subscribers. This is useful for keeping the database compact and clearing out old, unneeded data.

The value for <code>maxAgeDays</code> corresponds to the maximum age for records to retain. By default it is set to 365, but you may configure it to any desired value.

The value for <code>subscriber</code> corresponds to the subscriber address(es) of whose notifictaions should be deleted. No validation is performed against this value to allow for subscriber changes without requiring corresponding job configuration changes.

'''Note:''' We recommend high volume users schedule the job weekly or less frequently and to schedule it for a non-peak time.

'''As of Obsidian 5.2.1''', this job is configured during new installations to run at 3:30 AM on the 1st of the month keeping the last 120 days of history.

== Disabled Job Cleanup Job ==

''Introduced in Obsidian 3.7.0''

'''Job Class:''' <code>com.carfey.ops.job.maint.DisabledJobCleanupJob</code>

This job cleans up jobs that have been disabled for the last configured number of days and have no future non-disabled schedule windows.

The value for <code>maxDisabledDays</code> corresponds to how many days in the past a job must have been disabled to be a candidate for being deleted.

'''Note:''' We recommend high volume users schedule the job weekly or less frequently and to schedule it for a non-peak time.

'''As of Obsidian 5.2.1''', this job is configured during new installations to run at 3:00 AM on the 1st of the month keeping the last 185 days of history.

= Script Job =
This job is a convenience job to execute any script, command or other executable file on any platform.

'''Job Class:''' <code>com.carfey.ops.job.script.ScriptFileJob</code>

''Introduced in Obsidian 2.3.1''

This job enables you to specify an existing script, command or other executable to invoke/execute. Validation of the file's existence and executable state is done only at runtime. You must ensure that the file exists or is accessible via environment variables and in an executable state on all Obsidian Hosts in the cluster or restrict the job to the necessary [[Admin_Jobs#Advanced_Options|Fixed Hosts]]. This job uses [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html ProcessBuilder], so refer to it for expected behaviour.

As of ''Obsidian 3.8.0'', this job supports best-effort interruption as an [[Implementing_Jobs#Interruptable_Jobs|Interruptable job]]. It is best effort in that it only destroys the underlying process that invoked the script, but cannot ensure that anything the script has invoked has terminated.

* ''Script with Arguments (1 or more Strings)'' - The first value is a path to the execution script (or other executable), which is typically fully qualified, or relative to the working directory. The additional values are any required arguments for the command. On *nix, if you are invoking a script, you may need to prefix the command with "./", e.g. <code>./script.sh</code>. Corresponds to the [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html#ProcessBuilder(java.lang.String...) ProcessBuilder(java.lang.String...) constructor].
* ''Copy Obsidian Process' Environment (Boolean)'' - Do you want the runtime environment to be copied from that which is running the Obsidian process? Defaults to ''true''. If set to ''false'', the environment is cleared. See [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html#environment() ProcessBuilder.environment()].
* ''Success Exit Code (Integer)'' - The exit code that designates success. Any exit code not matching this value will result in a job failure. Defaults to ''0''.
* ''Working Directory (String)'' - The desired working directory for the script. If no special working directory is required, set to the directory containing the target script. See [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html#directory() ProcessBuilder.directory()].
* ''Environment Parameter Key Value Pairs (0 or more pairs of Strings)'' - Key/Value pairs to be set on the execution environment. These values are set just before execution and will override any existing values copied from the Obsidian Process if ''Copy Obsidian Process' Environment'' was set to true. See [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html#environment() ProcessBuilder.environment()].

'''Sample Configuration'''

[[Image:ScriptFileJobConfig.png]]

== Note on Windows ==
When running the job on Windows, users often encounter an error like the following:

<pre>Cannot run program "run.bat" (in directory "C:\test"): CreateProcess error=2, The system cannot find the file specified.</pre>

This normally means you need to run the command through the Windows command interpretor, using <code>cmd /C</code>.

To do this, instead of supplying the file to execute as a first value for ''Script with Arguments'', the supply the values "cmd" and "/C" as separate values, then any others you require, as illustrated below.

<pre>
Script with Arguments:
cmd
/C
run.bat
</pre>

= MySqlBackupJob =

''Introduced in version 2.4''

This is a convenience job to utilize the mysqldump utility to extract a backup and store on the filesystem. A timestamp is appended to the filename prefix specified to protect against overwrites. The optional mysqldump options are not validated and will result in runtime failures if they are invalid. Likewise, all paths specified are not verified and are only required to be available on the scheduler host at runtime. If the mysqldump executable is not found at runtime, change the ''mysqldump Executable'' to have the fully qualified path.
* ''Fully qualified export path (String)'' - The directory where you want the backups stored.
* ''Filename prefix (String)'' - The filename prefix to use for the backup files.
* ''Username (String)'' - The user for the mysqldump command.
* ''Password (String)'' - The user's password for the mysqldump command.
* ''Database (String)'' - The database to backup.
* ''Hostname or IP Address (optional String)'' - The host of the MySQL database. If not provided, assumes localhost.
* ''GZip file? (Boolean)'' - Determines whether the backup file is compressed using GZip.
* ''mysqldump option (0 or more Strings)'' - Any number of desired mysqldump options can be specified.
* ''mysqldump Executable (String)'' - Fully qualified path to mysqldump executable.

'''Sample Configuration'''

[[File:MySqlBackupJobConfig.png]]

= Shell Script Jobs =
'''Deprecated as of Obsidian 2.3.1.''' Use [[#Script_Job|Script Job]] instead.

These jobs are provided to give convenient access to shell scripting. ''Not supported on Windows-based platforms.''

== Shell Script Job ==

'''Deprecated as of Obsidian 2.3.1.''' Use [[#Script_Job|Script Job]] instead.

'''Job Class:''' <code>com.carfey.ops.job.script.ShellScriptJob</code>

''Introduced in version 2.0''

This job enables you to specify the actual contents of a shell script and have it execute on the runtime host. At runtime, the script will be written to disk, marked as executable and then executed. The script is then cleaned up. The shell script provided should be completely self-sufficient with any desired interpreter directives included and no assumptions or expectations of environment variables.

== Shell Script Execution Job ==
'''Deprecated as of Obsidian 2.3.1.''' Use [[#Script_Job|Script Job]] instead.

'''Job Class:''' <code>com.carfey.ops.job.script.ShellScriptExecutionJob</code>

''Introduced in version 2.0''

This job enables you to specify an existing shell script to execute. Validation of the script's existence and executable state is done only at runtime. You must ensure that the script exists in an executable state on all Obsidian Hosts in the cluster or restrict the job to the necessary [[Admin_Jobs#Execution_.26_Pickup|Fixed Hosts]].

= Miscellaneous Jobs =

== Database File Export Job ==

'''Job Class:''' <code>com.carfey.ops.job.db.DatabaseFileExportJob</code>

''Introduced in Obsidian 5.1.0''

This job produces a file export based on a database connection and a query.

The job supports the following configuration options:

* ''SQL Query (String)'' - The source query that produces the desired export results.
* ''JDBC Connection Provider (optional Class)'' - A class implementation of [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/db/DatabaseConnectionProvider.html DatabaseConnectionProvider] that provides a connection - allows for use of an existing connection pool or other means of obtaining a connection. If not used, must used the URL/username/password configuration for connections.
* ''JDBC DB URL (optional String)'' - JDBC URL. Relies on JDBC driver class being available on the classpath. If not used, must used the JDBC Connection Provider for connections.
* ''JDBC DB username (optional String)'' - JBDC database username. Relies on JDBC driver class being available on the classpath. If not used, must used the JDBC Connection Provider for connections.
* ''JDBC DB password (optional String)'' - JBDC database password. Relies on JDBC driver class being available on the classpath. If not used, must used the JDBC Connection Provider for connections.
* ''File type (String)'' - One of CSV, JSON, XML.
* ''File name pattern (String)'' Filename patterns for the generated filename support the following tokens delimited by < and >:
** <code><custom:paramname></code> is a means of automatically substituting in other parameters defined on the job.
** <code><ext></code> is the last file extension (e.g. 'txt')
** <code><ts:dateformat></code> corresponds to a timestamp formatted in the supplied SimpleDateFormat pattern (e.g. <code><ts:yyyy-MM-dd-HH-mm:ss></code>)
** other literals outside of < or >, or inside of < and > but not matching any preceding tokens.
* ''CSV Delimiter (optional String)'' - If CSV export is selected, can choose an alternative delimiter other than comma (,). Single character.
* ''CSV Quote Character (optional String)'' - If CSV export is selected, can choose an alternative quote character other than double quotes ("). Single character.
* ''CSV Escape Character (optional String)'' - If CSV export is selected, can choose an alternative escape character other than double quotes ("). Single character.
* ''CSV Line End String (optional String)'' - If CSV export is selected, can choose an alternative line end string other than newline (\n).
* ''Datetime format (String)'' - SimpleDateFormat format applied to java.sql.Timestamps.
* ''Date format (String)'' - SimpleDateFormat format applied to java.sql.Dates.

== REST Invocation Job ==

'''Job Class:''' <code>com.carfey.ops.job.rest.RESTInvocationJob</code>

''Introduced in Obsidian 5.1.0''

This job calls a REST endpoint using the designated method and payload, if applicable. Expects the response code to be in the 2xx series to be a success, all others are treated as failures. Expects payload and response to always be Strings. Supports basic authentication. Response is saved to job results to allow for use by chained jobs.

The job supports the following configuration options:

* ''URL Target (String)'' - Endpoint URL.
* ''REST API Method (String)'' - GET, PUT, POST, DELETE supported.
* ''Payload (optional String)'' - Required for PUT/POST, not permitted for GET/DELETE.
* ''Basic Authentication Username (optional String)'' - If wanting to add basic authentication, provide username and password.
* ''Basic Authentication Password (optional String)'' - If wanting to add basic authentication, provide username and password.

== Obsidian Execution Statistics Job ==

'''Job Class:''' <code>com.carfey.ops.job.schedule.ObsidianExecutionStatisticsJob</code>

''Introduced in Obsidian 6.4.0''

This job runs against the job activity stored in Obsidian to collect execution statistics. These statistics are then available via the UI, the [[REST_API|REST API]] and [[Embedded_API|Embedded API]].

The job supports the following configuration options:

* ''durationUnit (String)'' - What statistics unit to calculate. Valid values: seconds, minutes, hours. Defaults to minutes. Multiple allowed.
* ''maximumDurationLookback (String)'' - How far back to collect statistics. One of day, two day, three day, five day, week, month, two month, three month, six month, year. Defaults to three month. Large durations will calculate and store stats for smaller durations; e.g. two day includes day.

[[File:Obsidian-6.4.0-Obsidian-Execution-Job-Statistics-Config.png]]

File:Obsidian-6.4.0-Obsidian-Execution-Job-Statistics-Config.png

2025-11-26T22:47:09Z

Craig:

File:Obsidian-6.4.0-Job-Stats-Across-Hosts.png

2025-11-26T22:46:39Z

Craig:

Admin Job Stats

2025-11-25T14:41:43Z

Craig: Created page with "Coming soon!"

Coming soon!

Admin Web Application Guide

2025-11-25T14:41:33Z

Craig:

'''Important: This guide is for Obsidian 4.0 and newer versions. See the [[Admin_Web_Application_Guide_(3.x.x_and_earlier)|old guide]] for prior versions.

Obsidian's administration web application lets you manage scheduler settings, monitor job execution, create and update jobs, and manage various notification settings.

It uses a sidebar on the left hand side of each page for primary navigation. This sidebar has parent menu items which are expanded by clicking on them. The sidebar can be hidden via the arrow at the bottom of the menu, or the hamburger icon on the right side of the screen.

It supports modern browsers including Chrome, Firefox, Edge, and more. It is a responsive mobile application, so you can use it on your phone or tablet.

'''Note:''' Though Obsidian is fully functional in other browsers, we recommend you use browsers such as Chrome or Firefox since they provide a better user experience and vastly superior performance.

[[Image:ObsidianNav_4.0.png|400px]]

To set up the web application, see '''[[Getting Started]]'''.

Screens available in Obsidian's web application are discussed on the following pages:

* '''[[Admin Login|Login]]'''
* '''[[Admin Job Activity|Job Activity]]'''
* '''[[Admin Jobs|Jobs]]'''
* '''[[Admin Job Stats|Job Stats]]'''
* '''[[Admin Global Parameters|Job Global Parameters]]'''
* '''[[Admin Schedule Aliases|Schedule Aliases]]'''
* '''[[Admin Job Run Time Preview|Job Run Time Preview]]'''
* '''[[Admin Job Conflicts|Job Conflicts]]'''
* '''[[Admin Job Chains|Job Chains]]'''
* '''[[Admin Custom Calendars|Calendars]]'''
* '''[[Admin Logs|Logs]]'''
* '''[[Admin Notifications|Sent Notifications]]'''
* '''[[Admin Subscribers|Subscribers ]]'''
* '''[[Admin Templates|Email Templates]]'''
* '''[[Admin Scheduler Settings|Scheduler Settings]]'''
* '''[[Admin Host Status|Host Status]]'''
* '''[[Admin User Management|User Management (including MFA)]]'''

Built-in Jobs

2025-11-25T14:34:01Z

Craig: /* Obsidian Execution Statistics Job */

Obsidian comes bundled with free [[Admin_Jobs|jobs]] for common tasks. These are provided in addition to [[Scripting Jobs]] to reduce implementation and testing time for common job functions.

As of '''Obsidian 2.7.0''', we have open-sourced our built-in convenience jobs under the [[https://opensource.org/license/mit/ MIT License]]. In the root of the installation folder, you can find the source in <code>obsidian-builtin-job-src.jar</code>.

= File Processing Jobs =

These jobs are provided to provide common basic file operations, such as file cleanup (deletion) and archiving. These jobs can be used to reduce the amount of code your organization needs to write.

== File Cleanup Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.FileCleanupJob</code>

''Introduced in version 2.0''

This job deletes files in specified paths based on one or more file masks (using regular expressions).

It supports the following configuration options:

* ''Directory (1 or more Strings)'' - A directory to scan for files. If recursive processing is enabled, child directories are also scanned.
* ''File Mask (0 or more Strings)'' - A regular expression that files must match to be deleted. This is based on <code>java.util.regex.Pattern</code>. To match all files, remove all configured values or use ".*" without quotes. If multiple values are used, files are eligible for deletion if they match any of the file masks.
* ''Abort on Deletion Failure (Boolean)'' - If deletion fails, should we fail the job?
* ''File Size Minimum (String)'' - The minimum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb).
* ''File Size Maximum (String)'' - The maximum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb).
* ''Minimum Time Since Modified (String)'' - The minimum age of a file to be deleted, based on the modified time. This can be specified in seconds, minutes, hours and days (e.g. 10s, 5m, 24h, 2d).
* ''Recursive (Boolean)'' - Whether files in subdirectories of the configured directories should be checked for matching files.

=== Customization ===
If you wish to tweak or customize behaviour of this job, it can be subclassed. The following methods may be overridden or extended by calling ''super'' methods:

* ''onStart'' - Called on job startup.
* ''onEnd'' - Called on job end, regardless of success or failure.
* ''shouldDelete'' - Determines if a file should be deleted.
* ''deleteMatchingFile'' - Deletes a matching file and saves a job result for its path.
* ''matchesAge'' - Determines if a file matches any age conditions (i.e. ''Minimum Time Since Modified''), or true if none are configured.
* ''matchesMask'' - Determines if a file matches any configured file masks, or true if none are configured.
* ''matchesSize'' - Determines if a file matches size conditions, or true if none are configured.
* ''processDirectory'' - Enumerates files in configured directories and calls ''shouldDelete'' and ''deleteMatchingFile'' as necessary.

'''Sample Configuration'''

[[Image:FileCleanup.png]]

== File Archive Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.FileArchiveJob</code>

''Introduced in version 2.0''

This job archives files passed in via a chained job's saved results. Therefore, it is intended to be used as a chained job only. One or more accessible absolute file paths can be passed in via job results called 'file'. Each one will be processed for archiving. For example, if you have a job that generates two files called 'customers.txt' and 'orders.txt', you will use <code>Context.saveJobResult(String, Object)</code> to save a value for each absolute file path (e.g. 'C:/customers.txt' and 'C:/orders.txt').

It supports the following configuration options:

* ''Archive Directory (1 or more Strings)'' - A directory to where an archive copy is placed.
* ''Rename Pattern (String)'' - How should we name the archive file? Rename patterns support the following tokens delimited by < and >:
** <code><filename></code> is the full original file name (e.g. 'abc.v1.txt')
** <code><basename></code> is the file with the last extension stripped (e.g. 'abc.v1')
** <code><ext></code> is the last file extension (e.g. 'txt')
** <code><ts:dateformat></code> corresponds to a timestamp formatted in the supplied SimpleDateFormat pattern (e.g. <code><ts:yyyy-MM-dd-HH-mm:ss></code>)
** other literals outside of < or >, or inside of < and > but not matching any preceding tokens.
** For example, to archive a GZIP version of a file with a timestamp with the extension 'gz', you can use the rename pattern <code><basename>.<ts:yyyy-MM-dd-HH-mm-ss>.<ext>.gz</code>.
** To maintain the original name, simply use the pattern <code><filename></code>.
* ''Delete Original File (Boolean)'' - Should we remove the original file after archiving?
* ''GZIP (Boolean)'' - Should the target archive file be compressed using GZIP?
* ''Overwrite Target File (Boolean)'' - If the archive file to be created already exists, should we overwrite it, or fail instead?
* ''File Size Minimum (String)'' - The minimum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb). As of Obsidian 6.0.1
* ''File Size Maximum (String)'' - The maximum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb). As of Obsidian 6.0.1
* ''Minimum Time Since Modified (String)'' - The minimum age of a file to be deleted, based on the modified time. This can be specified in seconds, minutes, hours and days (e.g. 10s, 5m, 24h, 2d). As of Obsidian 6.0.1

=== Customization ===
If you wish to tweak or customize behaviour of this job, it can be subclassed. The following methods may be overridden or extended by calling ''super'' methods:

* ''onStart'' - Called on job startup.
* ''onEnd'' - Called on job end, regardless of success or failure.
* ''determineArchiveFilename'' - Determines the name of the archive file based on the configured "Rename Pattern".
* ''processFile'' - For each input file, determines the archive file name and copies the original file to the archive.
* ''processDelete'' - If the original file is to be deleted, this method handles deleting the original file. If deletion fails, the job will fail, so if you wish to change his behaviour, you can override this method.

'''Sample Configuration'''

[[Image:FileArchiveJobConfig.png]]

== File Scanner Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.FileScannerJob</code>

''Introduced in version 2.2''

This job locates files in a directory matching one or more file masks (using Java regular expressions) and stores the result via source job results stored under the name <code>file</code> as absolute paths (Strings).

This job is intended to be conditionally chained to a job that knows how to process the results.

''Go File Pattern'' may used to ensure that files in the configured ''Directory'' are only picked up and saved if an expected token file exists. If ''Delete Go File'' is set to true, any found token files will be deleted. If this deletion fails, the job will abort and no <code>file</code> results are saved. Successfully deleted go files are stored as job results under the name <code>deletedGoFile</code>.

The job supports the following configuration options:

* ''Directory (String)'' - A directory to scan for files.
* ''File Pattern (1 or more Strings)'' - One or more file patterns (using <code>java.util.regex.Pattern</code>) that a file name must match to be considered a match. If any one of the configured patterns is a match, the file is considered a match.
* ''Go File Pattern (String)'' - A file pattern (using <code>java.util.regex.Pattern</code>) that must match at least one file in in the ''Go File Directory'' (or main ''Directory'' if not supplied) in order for files to be processed and saved as job results.
* ''Go File Directory (optional String)'' - The directory where we look for files matching the ''Go File Pattern''. If missing, the value for ''Directory'' is used.
* ''Delete Go File (Boolean)'' - If we find one or more go files, should we delete them? If deletion fails, the job will fail.
* ''File Size Minimum (String)'' - The minimum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb). As of Obsidian 6.0.1
* ''File Size Maximum (String)'' - The maximum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb). As of Obsidian 6.0.1
* ''Minimum Time Since Modified (String)'' - The minimum age of a file to be deleted, based on the modified time. This can be specified in seconds, minutes, hours and days (e.g. 10s, 5m, 24h, 2d). As of Obsidian 6.0.1

=== Customization ===
If you wish to tweak or customize behaviour of this job, it can be subclassed. The following methods may be overridden or extended by calling ''super'' methods:

* ''onStart'' - Called on job startup.
* ''onEnd'' - Called on job end, regardless of success or failure.
* ''listFiles'' - Lists files within the directory using the supplied patterns.
* ''postProcessFiles'' - This is a hook method called after all job results are saved and go files are deleted if applicable. It is called with all valid files that were found.
* ''deleteGoFiles'' - Deletes all found go files, saving a result if successful and throwing a RuntimeException if failing. This can be overriden to customize handling of failures.

'''Sample Configuration'''

[[Image:FileScannerConfig.png]]

= Maintenance Jobs =

These jobs are provided to help maintain the Obsidian installation. Automatic schedule configuration can be disabled via <code>com.carfey.obsidian.standardOutputStreamsEventHook.enabled=true</code> configuration.

== Job History Cleanup Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.JobHistoryCleanupJob</code>

This job will delete job history and related records beyond a configurable age in days. This is useful for keeping the database compact and clearing out old, unneeded data.

The value for <code>maxAgeDays</code> corresponds to the maximum age for records to retain. By default it is set to 365, but you may configure it to any desired value.

As of 3.0.1, the value for <code>maxAgeScheduleDays</code> corresponds to the maximum age for expired job schedules to retain. If this isn't specified, expired job schedules won't be deleted.

As of 3.4.0, the value for <code>maxAgeDays</code> is used to prune expired job schedules and <code>maxAgeScheduleDays</code> is no longer used.

'''Note:''' We recommend high volume users schedule the job weekly or less frequently and to schedule it for a non-peak time.

'''As of Obsidian 5.2.1''', this job is configured during new installations to run '@daily' keeping the last 380 days of history.

== Log Cleanup Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.LogCleanupJob</code>

This job will delete log database records beyond a configurable age in days. This is useful for keeping the database compact and clearing out old, unneeded data.

The value for <code>maxAgeDays</code> corresponds to the maximum age for records to retain. By default it is set to 365, but you may configure it to any desired value.

The value for <code>level</code> corresponds to the logging level of events to delete. You may specify multiple values, and the "ALL" option will result in all records matching the age setting being deleted. Valid levels to configure are: <code>FATAL</code>, <code>ERROR</code>, <code>WARNING</code>, <code>INFO</code>, <code>DEBUG</code>, and <code>TRACE</code>.

It is common to only delete lower severity level events, such as <code>INFO</code>, <code>DEBUG</code>, and <code>TRACE</code>, but retain higher severity messages.

'''Note:''' We recommend high volume users schedule the job weekly or less frequently and to schedule it for a non-peak time.

'''As of Obsidian 5.2.1''', this job is configured during new installations as follows:
* 1:00 AM for DEBUG/TRACE keeping the last 30 days of event logs.
* 1:30 AM for INFO keeping the last 60 days of event logs.
* 2:00 AM for WARNING/ERROR keeping the last 120 days of event logs.
* 2:30 AM for FATAL keeping the last 185 days of event logs.

== Notification Cleanup Job ==

''Introduced in Obsidian 4.9.0''

'''Job Class:''' <code>com.carfey.ops.job.maint.NotificationCleanupJob</code>

This job will delete notification database records beyond a configurable age in days. Optionally you may constrain this to specific subscribers. This is useful for keeping the database compact and clearing out old, unneeded data.

The value for <code>maxAgeDays</code> corresponds to the maximum age for records to retain. By default it is set to 365, but you may configure it to any desired value.

The value for <code>subscriber</code> corresponds to the subscriber address(es) of whose notifictaions should be deleted. No validation is performed against this value to allow for subscriber changes without requiring corresponding job configuration changes.

'''Note:''' We recommend high volume users schedule the job weekly or less frequently and to schedule it for a non-peak time.

'''As of Obsidian 5.2.1''', this job is configured during new installations to run at 3:30 AM on the 1st of the month keeping the last 120 days of history.

== Disabled Job Cleanup Job ==

''Introduced in Obsidian 3.7.0''

'''Job Class:''' <code>com.carfey.ops.job.maint.DisabledJobCleanupJob</code>

This job cleans up jobs that have been disabled for the last configured number of days and have no future non-disabled schedule windows.

The value for <code>maxDisabledDays</code> corresponds to how many days in the past a job must have been disabled to be a candidate for being deleted.

'''Note:''' We recommend high volume users schedule the job weekly or less frequently and to schedule it for a non-peak time.

'''As of Obsidian 5.2.1''', this job is configured during new installations to run at 3:00 AM on the 1st of the month keeping the last 185 days of history.

= Script Job =
This job is a convenience job to execute any script, command or other executable file on any platform.

'''Job Class:''' <code>com.carfey.ops.job.script.ScriptFileJob</code>

''Introduced in Obsidian 2.3.1''

This job enables you to specify an existing script, command or other executable to invoke/execute. Validation of the file's existence and executable state is done only at runtime. You must ensure that the file exists or is accessible via environment variables and in an executable state on all Obsidian Hosts in the cluster or restrict the job to the necessary [[Admin_Jobs#Advanced_Options|Fixed Hosts]]. This job uses [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html ProcessBuilder], so refer to it for expected behaviour.

As of ''Obsidian 3.8.0'', this job supports best-effort interruption as an [[Implementing_Jobs#Interruptable_Jobs|Interruptable job]]. It is best effort in that it only destroys the underlying process that invoked the script, but cannot ensure that anything the script has invoked has terminated.

* ''Script with Arguments (1 or more Strings)'' - The first value is a path to the execution script (or other executable), which is typically fully qualified, or relative to the working directory. The additional values are any required arguments for the command. On *nix, if you are invoking a script, you may need to prefix the command with "./", e.g. <code>./script.sh</code>. Corresponds to the [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html#ProcessBuilder(java.lang.String...) ProcessBuilder(java.lang.String...) constructor].
* ''Copy Obsidian Process' Environment (Boolean)'' - Do you want the runtime environment to be copied from that which is running the Obsidian process? Defaults to ''true''. If set to ''false'', the environment is cleared. See [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html#environment() ProcessBuilder.environment()].
* ''Success Exit Code (Integer)'' - The exit code that designates success. Any exit code not matching this value will result in a job failure. Defaults to ''0''.
* ''Working Directory (String)'' - The desired working directory for the script. If no special working directory is required, set to the directory containing the target script. See [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html#directory() ProcessBuilder.directory()].
* ''Environment Parameter Key Value Pairs (0 or more pairs of Strings)'' - Key/Value pairs to be set on the execution environment. These values are set just before execution and will override any existing values copied from the Obsidian Process if ''Copy Obsidian Process' Environment'' was set to true. See [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html#environment() ProcessBuilder.environment()].

'''Sample Configuration'''

[[Image:ScriptFileJobConfig.png]]

== Note on Windows ==
When running the job on Windows, users often encounter an error like the following:

<pre>Cannot run program "run.bat" (in directory "C:\test"): CreateProcess error=2, The system cannot find the file specified.</pre>

This normally means you need to run the command through the Windows command interpretor, using <code>cmd /C</code>.

To do this, instead of supplying the file to execute as a first value for ''Script with Arguments'', the supply the values "cmd" and "/C" as separate values, then any others you require, as illustrated below.

<pre>
Script with Arguments:
cmd
/C
run.bat
</pre>

= MySqlBackupJob =

''Introduced in version 2.4''

This is a convenience job to utilize the mysqldump utility to extract a backup and store on the filesystem. A timestamp is appended to the filename prefix specified to protect against overwrites. The optional mysqldump options are not validated and will result in runtime failures if they are invalid. Likewise, all paths specified are not verified and are only required to be available on the scheduler host at runtime. If the mysqldump executable is not found at runtime, change the ''mysqldump Executable'' to have the fully qualified path.
* ''Fully qualified export path (String)'' - The directory where you want the backups stored.
* ''Filename prefix (String)'' - The filename prefix to use for the backup files.
* ''Username (String)'' - The user for the mysqldump command.
* ''Password (String)'' - The user's password for the mysqldump command.
* ''Database (String)'' - The database to backup.
* ''Hostname or IP Address (optional String)'' - The host of the MySQL database. If not provided, assumes localhost.
* ''GZip file? (Boolean)'' - Determines whether the backup file is compressed using GZip.
* ''mysqldump option (0 or more Strings)'' - Any number of desired mysqldump options can be specified.
* ''mysqldump Executable (String)'' - Fully qualified path to mysqldump executable.

'''Sample Configuration'''

[[File:MySqlBackupJobConfig.png]]

= Shell Script Jobs =
'''Deprecated as of Obsidian 2.3.1.''' Use [[#Script_Job|Script Job]] instead.

These jobs are provided to give convenient access to shell scripting. ''Not supported on Windows-based platforms.''

== Shell Script Job ==

'''Deprecated as of Obsidian 2.3.1.''' Use [[#Script_Job|Script Job]] instead.

'''Job Class:''' <code>com.carfey.ops.job.script.ShellScriptJob</code>

''Introduced in version 2.0''

This job enables you to specify the actual contents of a shell script and have it execute on the runtime host. At runtime, the script will be written to disk, marked as executable and then executed. The script is then cleaned up. The shell script provided should be completely self-sufficient with any desired interpreter directives included and no assumptions or expectations of environment variables.

== Shell Script Execution Job ==
'''Deprecated as of Obsidian 2.3.1.''' Use [[#Script_Job|Script Job]] instead.

'''Job Class:''' <code>com.carfey.ops.job.script.ShellScriptExecutionJob</code>

''Introduced in version 2.0''

This job enables you to specify an existing shell script to execute. Validation of the script's existence and executable state is done only at runtime. You must ensure that the script exists in an executable state on all Obsidian Hosts in the cluster or restrict the job to the necessary [[Admin_Jobs#Execution_.26_Pickup|Fixed Hosts]].

= Miscellaneous Jobs =

== Database File Export Job ==

'''Job Class:''' <code>com.carfey.ops.job.db.DatabaseFileExportJob</code>

''Introduced in Obsidian 5.1.0''

This job produces a file export based on a database connection and a query.

The job supports the following configuration options:

* ''SQL Query (String)'' - The source query that produces the desired export results.
* ''JDBC Connection Provider (optional Class)'' - A class implementation of [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/db/DatabaseConnectionProvider.html DatabaseConnectionProvider] that provides a connection - allows for use of an existing connection pool or other means of obtaining a connection. If not used, must used the URL/username/password configuration for connections.
* ''JDBC DB URL (optional String)'' - JDBC URL. Relies on JDBC driver class being available on the classpath. If not used, must used the JDBC Connection Provider for connections.
* ''JDBC DB username (optional String)'' - JBDC database username. Relies on JDBC driver class being available on the classpath. If not used, must used the JDBC Connection Provider for connections.
* ''JDBC DB password (optional String)'' - JBDC database password. Relies on JDBC driver class being available on the classpath. If not used, must used the JDBC Connection Provider for connections.
* ''File type (String)'' - One of CSV, JSON, XML.
* ''File name pattern (String)'' Filename patterns for the generated filename support the following tokens delimited by < and >:
** <code><custom:paramname></code> is a means of automatically substituting in other parameters defined on the job.
** <code><ext></code> is the last file extension (e.g. 'txt')
** <code><ts:dateformat></code> corresponds to a timestamp formatted in the supplied SimpleDateFormat pattern (e.g. <code><ts:yyyy-MM-dd-HH-mm:ss></code>)
** other literals outside of < or >, or inside of < and > but not matching any preceding tokens.
* ''CSV Delimiter (optional String)'' - If CSV export is selected, can choose an alternative delimiter other than comma (,). Single character.
* ''CSV Quote Character (optional String)'' - If CSV export is selected, can choose an alternative quote character other than double quotes ("). Single character.
* ''CSV Escape Character (optional String)'' - If CSV export is selected, can choose an alternative escape character other than double quotes ("). Single character.
* ''CSV Line End String (optional String)'' - If CSV export is selected, can choose an alternative line end string other than newline (\n).
* ''Datetime format (String)'' - SimpleDateFormat format applied to java.sql.Timestamps.
* ''Date format (String)'' - SimpleDateFormat format applied to java.sql.Dates.

== REST Invocation Job ==

'''Job Class:''' <code>com.carfey.ops.job.rest.RESTInvocationJob</code>

''Introduced in Obsidian 5.1.0''

This job calls a REST endpoint using the designated method and payload, if applicable. Expects the response code to be in the 2xx series to be a success, all others are treated as failures. Expects payload and response to always be Strings. Supports basic authentication. Response is saved to job results to allow for use by chained jobs.

The job supports the following configuration options:

* ''URL Target (String)'' - Endpoint URL.
* ''REST API Method (String)'' - GET, PUT, POST, DELETE supported.
* ''Payload (optional String)'' - Required for PUT/POST, not permitted for GET/DELETE.
* ''Basic Authentication Username (optional String)'' - If wanting to add basic authentication, provide username and password.
* ''Basic Authentication Password (optional String)'' - If wanting to add basic authentication, provide username and password.

== Obsidian Execution Statistics Job ==

'''Job Class:''' <code>com.carfey.ops.job.schedule.ObsidianExecutionStatisticsJob</code>

''Introduced in Obsidian 6.4.0''

This job runs against the job activity stored in Obsidian to collect execution statistics. These statistics are then available via the UI, the [[REST_API|REST API]] and [[Embedded_API|Embedded API]].

The job supports the following configuration options:

* ''durationUnit (String)'' - What statistics unit to calculate. Valid values: seconds, minutes, hours. Defaults to minutes. Multiple allowed.
* ''maximumDurationLookback (String)'' - How far back to collect statistics. One of day, two day, three day, five day, week, month, two month, three month, six month, year. Defaults to three month. Large durations will calculate and store stats for smaller durations; e.g. two day includes day.

Built-in Jobs

2025-11-25T03:16:55Z

Craig:

Obsidian comes bundled with free [[Admin_Jobs|jobs]] for common tasks. These are provided in addition to [[Scripting Jobs]] to reduce implementation and testing time for common job functions.

As of '''Obsidian 2.7.0''', we have open-sourced our built-in convenience jobs under the [[https://opensource.org/license/mit/ MIT License]]. In the root of the installation folder, you can find the source in <code>obsidian-builtin-job-src.jar</code>.

= File Processing Jobs =

These jobs are provided to provide common basic file operations, such as file cleanup (deletion) and archiving. These jobs can be used to reduce the amount of code your organization needs to write.

== File Cleanup Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.FileCleanupJob</code>

''Introduced in version 2.0''

This job deletes files in specified paths based on one or more file masks (using regular expressions).

It supports the following configuration options:

* ''Directory (1 or more Strings)'' - A directory to scan for files. If recursive processing is enabled, child directories are also scanned.
* ''File Mask (0 or more Strings)'' - A regular expression that files must match to be deleted. This is based on <code>java.util.regex.Pattern</code>. To match all files, remove all configured values or use ".*" without quotes. If multiple values are used, files are eligible for deletion if they match any of the file masks.
* ''Abort on Deletion Failure (Boolean)'' - If deletion fails, should we fail the job?
* ''File Size Minimum (String)'' - The minimum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb).
* ''File Size Maximum (String)'' - The maximum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb).
* ''Minimum Time Since Modified (String)'' - The minimum age of a file to be deleted, based on the modified time. This can be specified in seconds, minutes, hours and days (e.g. 10s, 5m, 24h, 2d).
* ''Recursive (Boolean)'' - Whether files in subdirectories of the configured directories should be checked for matching files.

=== Customization ===
If you wish to tweak or customize behaviour of this job, it can be subclassed. The following methods may be overridden or extended by calling ''super'' methods:

* ''onStart'' - Called on job startup.
* ''onEnd'' - Called on job end, regardless of success or failure.
* ''shouldDelete'' - Determines if a file should be deleted.
* ''deleteMatchingFile'' - Deletes a matching file and saves a job result for its path.
* ''matchesAge'' - Determines if a file matches any age conditions (i.e. ''Minimum Time Since Modified''), or true if none are configured.
* ''matchesMask'' - Determines if a file matches any configured file masks, or true if none are configured.
* ''matchesSize'' - Determines if a file matches size conditions, or true if none are configured.
* ''processDirectory'' - Enumerates files in configured directories and calls ''shouldDelete'' and ''deleteMatchingFile'' as necessary.

'''Sample Configuration'''

[[Image:FileCleanup.png]]

== File Archive Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.FileArchiveJob</code>

''Introduced in version 2.0''

This job archives files passed in via a chained job's saved results. Therefore, it is intended to be used as a chained job only. One or more accessible absolute file paths can be passed in via job results called 'file'. Each one will be processed for archiving. For example, if you have a job that generates two files called 'customers.txt' and 'orders.txt', you will use <code>Context.saveJobResult(String, Object)</code> to save a value for each absolute file path (e.g. 'C:/customers.txt' and 'C:/orders.txt').

It supports the following configuration options:

* ''Archive Directory (1 or more Strings)'' - A directory to where an archive copy is placed.
* ''Rename Pattern (String)'' - How should we name the archive file? Rename patterns support the following tokens delimited by < and >:
** <code><filename></code> is the full original file name (e.g. 'abc.v1.txt')
** <code><basename></code> is the file with the last extension stripped (e.g. 'abc.v1')
** <code><ext></code> is the last file extension (e.g. 'txt')
** <code><ts:dateformat></code> corresponds to a timestamp formatted in the supplied SimpleDateFormat pattern (e.g. <code><ts:yyyy-MM-dd-HH-mm:ss></code>)
** other literals outside of < or >, or inside of < and > but not matching any preceding tokens.
** For example, to archive a GZIP version of a file with a timestamp with the extension 'gz', you can use the rename pattern <code><basename>.<ts:yyyy-MM-dd-HH-mm-ss>.<ext>.gz</code>.
** To maintain the original name, simply use the pattern <code><filename></code>.
* ''Delete Original File (Boolean)'' - Should we remove the original file after archiving?
* ''GZIP (Boolean)'' - Should the target archive file be compressed using GZIP?
* ''Overwrite Target File (Boolean)'' - If the archive file to be created already exists, should we overwrite it, or fail instead?
* ''File Size Minimum (String)'' - The minimum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb). As of Obsidian 6.0.1
* ''File Size Maximum (String)'' - The maximum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb). As of Obsidian 6.0.1
* ''Minimum Time Since Modified (String)'' - The minimum age of a file to be deleted, based on the modified time. This can be specified in seconds, minutes, hours and days (e.g. 10s, 5m, 24h, 2d). As of Obsidian 6.0.1

=== Customization ===
If you wish to tweak or customize behaviour of this job, it can be subclassed. The following methods may be overridden or extended by calling ''super'' methods:

* ''onStart'' - Called on job startup.
* ''onEnd'' - Called on job end, regardless of success or failure.
* ''determineArchiveFilename'' - Determines the name of the archive file based on the configured "Rename Pattern".
* ''processFile'' - For each input file, determines the archive file name and copies the original file to the archive.
* ''processDelete'' - If the original file is to be deleted, this method handles deleting the original file. If deletion fails, the job will fail, so if you wish to change his behaviour, you can override this method.

'''Sample Configuration'''

[[Image:FileArchiveJobConfig.png]]

== File Scanner Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.FileScannerJob</code>

''Introduced in version 2.2''

This job locates files in a directory matching one or more file masks (using Java regular expressions) and stores the result via source job results stored under the name <code>file</code> as absolute paths (Strings).

This job is intended to be conditionally chained to a job that knows how to process the results.

''Go File Pattern'' may used to ensure that files in the configured ''Directory'' are only picked up and saved if an expected token file exists. If ''Delete Go File'' is set to true, any found token files will be deleted. If this deletion fails, the job will abort and no <code>file</code> results are saved. Successfully deleted go files are stored as job results under the name <code>deletedGoFile</code>.

The job supports the following configuration options:

* ''Directory (String)'' - A directory to scan for files.
* ''File Pattern (1 or more Strings)'' - One or more file patterns (using <code>java.util.regex.Pattern</code>) that a file name must match to be considered a match. If any one of the configured patterns is a match, the file is considered a match.
* ''Go File Pattern (String)'' - A file pattern (using <code>java.util.regex.Pattern</code>) that must match at least one file in in the ''Go File Directory'' (or main ''Directory'' if not supplied) in order for files to be processed and saved as job results.
* ''Go File Directory (optional String)'' - The directory where we look for files matching the ''Go File Pattern''. If missing, the value for ''Directory'' is used.
* ''Delete Go File (Boolean)'' - If we find one or more go files, should we delete them? If deletion fails, the job will fail.
* ''File Size Minimum (String)'' - The minimum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb). As of Obsidian 6.0.1
* ''File Size Maximum (String)'' - The maximum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb). As of Obsidian 6.0.1
* ''Minimum Time Since Modified (String)'' - The minimum age of a file to be deleted, based on the modified time. This can be specified in seconds, minutes, hours and days (e.g. 10s, 5m, 24h, 2d). As of Obsidian 6.0.1

=== Customization ===
If you wish to tweak or customize behaviour of this job, it can be subclassed. The following methods may be overridden or extended by calling ''super'' methods:

* ''onStart'' - Called on job startup.
* ''onEnd'' - Called on job end, regardless of success or failure.
* ''listFiles'' - Lists files within the directory using the supplied patterns.
* ''postProcessFiles'' - This is a hook method called after all job results are saved and go files are deleted if applicable. It is called with all valid files that were found.
* ''deleteGoFiles'' - Deletes all found go files, saving a result if successful and throwing a RuntimeException if failing. This can be overriden to customize handling of failures.

'''Sample Configuration'''

[[Image:FileScannerConfig.png]]

= Maintenance Jobs =

These jobs are provided to help maintain the Obsidian installation. Automatic schedule configuration can be disabled via <code>com.carfey.obsidian.standardOutputStreamsEventHook.enabled=true</code> configuration.

== Job History Cleanup Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.JobHistoryCleanupJob</code>

This job will delete job history and related records beyond a configurable age in days. This is useful for keeping the database compact and clearing out old, unneeded data.

The value for <code>maxAgeDays</code> corresponds to the maximum age for records to retain. By default it is set to 365, but you may configure it to any desired value.

As of 3.0.1, the value for <code>maxAgeScheduleDays</code> corresponds to the maximum age for expired job schedules to retain. If this isn't specified, expired job schedules won't be deleted.

As of 3.4.0, the value for <code>maxAgeDays</code> is used to prune expired job schedules and <code>maxAgeScheduleDays</code> is no longer used.

'''Note:''' We recommend high volume users schedule the job weekly or less frequently and to schedule it for a non-peak time.

'''As of Obsidian 5.2.1''', this job is configured during new installations to run '@daily' keeping the last 380 days of history.

== Log Cleanup Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.LogCleanupJob</code>

This job will delete log database records beyond a configurable age in days. This is useful for keeping the database compact and clearing out old, unneeded data.

The value for <code>maxAgeDays</code> corresponds to the maximum age for records to retain. By default it is set to 365, but you may configure it to any desired value.

The value for <code>level</code> corresponds to the logging level of events to delete. You may specify multiple values, and the "ALL" option will result in all records matching the age setting being deleted. Valid levels to configure are: <code>FATAL</code>, <code>ERROR</code>, <code>WARNING</code>, <code>INFO</code>, <code>DEBUG</code>, and <code>TRACE</code>.

It is common to only delete lower severity level events, such as <code>INFO</code>, <code>DEBUG</code>, and <code>TRACE</code>, but retain higher severity messages.

'''Note:''' We recommend high volume users schedule the job weekly or less frequently and to schedule it for a non-peak time.

'''As of Obsidian 5.2.1''', this job is configured during new installations as follows:
* 1:00 AM for DEBUG/TRACE keeping the last 30 days of event logs.
* 1:30 AM for INFO keeping the last 60 days of event logs.
* 2:00 AM for WARNING/ERROR keeping the last 120 days of event logs.
* 2:30 AM for FATAL keeping the last 185 days of event logs.

== Notification Cleanup Job ==

''Introduced in Obsidian 4.9.0''

'''Job Class:''' <code>com.carfey.ops.job.maint.NotificationCleanupJob</code>

This job will delete notification database records beyond a configurable age in days. Optionally you may constrain this to specific subscribers. This is useful for keeping the database compact and clearing out old, unneeded data.

The value for <code>maxAgeDays</code> corresponds to the maximum age for records to retain. By default it is set to 365, but you may configure it to any desired value.

The value for <code>subscriber</code> corresponds to the subscriber address(es) of whose notifictaions should be deleted. No validation is performed against this value to allow for subscriber changes without requiring corresponding job configuration changes.

'''Note:''' We recommend high volume users schedule the job weekly or less frequently and to schedule it for a non-peak time.

'''As of Obsidian 5.2.1''', this job is configured during new installations to run at 3:30 AM on the 1st of the month keeping the last 120 days of history.

== Disabled Job Cleanup Job ==

''Introduced in Obsidian 3.7.0''

'''Job Class:''' <code>com.carfey.ops.job.maint.DisabledJobCleanupJob</code>

This job cleans up jobs that have been disabled for the last configured number of days and have no future non-disabled schedule windows.

The value for <code>maxDisabledDays</code> corresponds to how many days in the past a job must have been disabled to be a candidate for being deleted.

'''Note:''' We recommend high volume users schedule the job weekly or less frequently and to schedule it for a non-peak time.

'''As of Obsidian 5.2.1''', this job is configured during new installations to run at 3:00 AM on the 1st of the month keeping the last 185 days of history.

= Script Job =
This job is a convenience job to execute any script, command or other executable file on any platform.

'''Job Class:''' <code>com.carfey.ops.job.script.ScriptFileJob</code>

''Introduced in Obsidian 2.3.1''

This job enables you to specify an existing script, command or other executable to invoke/execute. Validation of the file's existence and executable state is done only at runtime. You must ensure that the file exists or is accessible via environment variables and in an executable state on all Obsidian Hosts in the cluster or restrict the job to the necessary [[Admin_Jobs#Advanced_Options|Fixed Hosts]]. This job uses [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html ProcessBuilder], so refer to it for expected behaviour.

As of ''Obsidian 3.8.0'', this job supports best-effort interruption as an [[Implementing_Jobs#Interruptable_Jobs|Interruptable job]]. It is best effort in that it only destroys the underlying process that invoked the script, but cannot ensure that anything the script has invoked has terminated.

* ''Script with Arguments (1 or more Strings)'' - The first value is a path to the execution script (or other executable), which is typically fully qualified, or relative to the working directory. The additional values are any required arguments for the command. On *nix, if you are invoking a script, you may need to prefix the command with "./", e.g. <code>./script.sh</code>. Corresponds to the [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html#ProcessBuilder(java.lang.String...) ProcessBuilder(java.lang.String...) constructor].
* ''Copy Obsidian Process' Environment (Boolean)'' - Do you want the runtime environment to be copied from that which is running the Obsidian process? Defaults to ''true''. If set to ''false'', the environment is cleared. See [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html#environment() ProcessBuilder.environment()].
* ''Success Exit Code (Integer)'' - The exit code that designates success. Any exit code not matching this value will result in a job failure. Defaults to ''0''.
* ''Working Directory (String)'' - The desired working directory for the script. If no special working directory is required, set to the directory containing the target script. See [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html#directory() ProcessBuilder.directory()].
* ''Environment Parameter Key Value Pairs (0 or more pairs of Strings)'' - Key/Value pairs to be set on the execution environment. These values are set just before execution and will override any existing values copied from the Obsidian Process if ''Copy Obsidian Process' Environment'' was set to true. See [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html#environment() ProcessBuilder.environment()].

'''Sample Configuration'''

[[Image:ScriptFileJobConfig.png]]

== Note on Windows ==
When running the job on Windows, users often encounter an error like the following:

<pre>Cannot run program "run.bat" (in directory "C:\test"): CreateProcess error=2, The system cannot find the file specified.</pre>

This normally means you need to run the command through the Windows command interpretor, using <code>cmd /C</code>.

To do this, instead of supplying the file to execute as a first value for ''Script with Arguments'', the supply the values "cmd" and "/C" as separate values, then any others you require, as illustrated below.

<pre>
Script with Arguments:
cmd
/C
run.bat
</pre>

= MySqlBackupJob =

''Introduced in version 2.4''

This is a convenience job to utilize the mysqldump utility to extract a backup and store on the filesystem. A timestamp is appended to the filename prefix specified to protect against overwrites. The optional mysqldump options are not validated and will result in runtime failures if they are invalid. Likewise, all paths specified are not verified and are only required to be available on the scheduler host at runtime. If the mysqldump executable is not found at runtime, change the ''mysqldump Executable'' to have the fully qualified path.
* ''Fully qualified export path (String)'' - The directory where you want the backups stored.
* ''Filename prefix (String)'' - The filename prefix to use for the backup files.
* ''Username (String)'' - The user for the mysqldump command.
* ''Password (String)'' - The user's password for the mysqldump command.
* ''Database (String)'' - The database to backup.
* ''Hostname or IP Address (optional String)'' - The host of the MySQL database. If not provided, assumes localhost.
* ''GZip file? (Boolean)'' - Determines whether the backup file is compressed using GZip.
* ''mysqldump option (0 or more Strings)'' - Any number of desired mysqldump options can be specified.
* ''mysqldump Executable (String)'' - Fully qualified path to mysqldump executable.

'''Sample Configuration'''

[[File:MySqlBackupJobConfig.png]]

= Shell Script Jobs =
'''Deprecated as of Obsidian 2.3.1.''' Use [[#Script_Job|Script Job]] instead.

These jobs are provided to give convenient access to shell scripting. ''Not supported on Windows-based platforms.''

== Shell Script Job ==

'''Deprecated as of Obsidian 2.3.1.''' Use [[#Script_Job|Script Job]] instead.

'''Job Class:''' <code>com.carfey.ops.job.script.ShellScriptJob</code>

''Introduced in version 2.0''

This job enables you to specify the actual contents of a shell script and have it execute on the runtime host. At runtime, the script will be written to disk, marked as executable and then executed. The script is then cleaned up. The shell script provided should be completely self-sufficient with any desired interpreter directives included and no assumptions or expectations of environment variables.

== Shell Script Execution Job ==
'''Deprecated as of Obsidian 2.3.1.''' Use [[#Script_Job|Script Job]] instead.

'''Job Class:''' <code>com.carfey.ops.job.script.ShellScriptExecutionJob</code>

''Introduced in version 2.0''

This job enables you to specify an existing shell script to execute. Validation of the script's existence and executable state is done only at runtime. You must ensure that the script exists in an executable state on all Obsidian Hosts in the cluster or restrict the job to the necessary [[Admin_Jobs#Execution_.26_Pickup|Fixed Hosts]].

= Miscellaneous Jobs =

== Database File Export Job ==

'''Job Class:''' <code>com.carfey.ops.job.db.DatabaseFileExportJob</code>

''Introduced in Obsidian 5.1.0''

This job produces a file export based on a database connection and a query.

The job supports the following configuration options:

* ''SQL Query (String)'' - The source query that produces the desired export results.
* ''JDBC Connection Provider (optional Class)'' - A class implementation of [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/db/DatabaseConnectionProvider.html DatabaseConnectionProvider] that provides a connection - allows for use of an existing connection pool or other means of obtaining a connection. If not used, must used the URL/username/password configuration for connections.
* ''JDBC DB URL (optional String)'' - JDBC URL. Relies on JDBC driver class being available on the classpath. If not used, must used the JDBC Connection Provider for connections.
* ''JDBC DB username (optional String)'' - JBDC database username. Relies on JDBC driver class being available on the classpath. If not used, must used the JDBC Connection Provider for connections.
* ''JDBC DB password (optional String)'' - JBDC database password. Relies on JDBC driver class being available on the classpath. If not used, must used the JDBC Connection Provider for connections.
* ''File type (String)'' - One of CSV, JSON, XML.
* ''File name pattern (String)'' Filename patterns for the generated filename support the following tokens delimited by < and >:
** <code><custom:paramname></code> is a means of automatically substituting in other parameters defined on the job.
** <code><ext></code> is the last file extension (e.g. 'txt')
** <code><ts:dateformat></code> corresponds to a timestamp formatted in the supplied SimpleDateFormat pattern (e.g. <code><ts:yyyy-MM-dd-HH-mm:ss></code>)
** other literals outside of < or >, or inside of < and > but not matching any preceding tokens.
* ''CSV Delimiter (optional String)'' - If CSV export is selected, can choose an alternative delimiter other than comma (,). Single character.
* ''CSV Quote Character (optional String)'' - If CSV export is selected, can choose an alternative quote character other than double quotes ("). Single character.
* ''CSV Escape Character (optional String)'' - If CSV export is selected, can choose an alternative escape character other than double quotes ("). Single character.
* ''CSV Line End String (optional String)'' - If CSV export is selected, can choose an alternative line end string other than newline (\n).
* ''Datetime format (String)'' - SimpleDateFormat format applied to java.sql.Timestamps.
* ''Date format (String)'' - SimpleDateFormat format applied to java.sql.Dates.

== REST Invocation Job ==

'''Job Class:''' <code>com.carfey.ops.job.rest.RESTInvocationJob</code>

''Introduced in Obsidian 5.1.0''

This job calls a REST endpoint using the designated method and payload, if applicable. Expects the response code to be in the 2xx series to be a success, all others are treated as failures. Expects payload and response to always be Strings. Supports basic authentication. Response is saved to job results to allow for use by chained jobs.

The job supports the following configuration options:

* ''URL Target (String)'' - Endpoint URL.
* ''REST API Method (String)'' - GET, PUT, POST, DELETE supported.
* ''Payload (optional String)'' - Required for PUT/POST, not permitted for GET/DELETE.
* ''Basic Authentication Username (optional String)'' - If wanting to add basic authentication, provide username and password.
* ''Basic Authentication Password (optional String)'' - If wanting to add basic authentication, provide username and password.

== Obsidian Execution Statistics Job ==

'''Job Class:''' <code>com.carfey.ops.job.schedule.ObsidianExecutionStatisticsJob</code>

''Introduced in Obsidian 6.4.0''

This job runs against the job activity stored in the Obsidian to collect execution statistics. These statistics are then available via the UI, the [[REST_API|REST API]] and [[Embedded_API|Embedded API]].

The job supports the following configuration options:

* ''durationUnit (String)'' - What statistics unit to calculate. Valid values: seconds, minutes, hours. Defaults to minutes. Multiple allowed.
* ''maximumDurationLookback (String)'' - How far back to collect statistics. One of day, two day, three day, five day, week, month, two month, three month, six month, year. Defaults to three month. Large durations will calculate and store stats for smaller durations; e.g. two day includes day.

2025-10-15T23:25:20Z

Craig: /* Bug Fixes */

Please review our [[Upgrading_Obsidian|Upgrade Instructions]].

Read about our [[Planned_Releases|Planned Releases]].

Looking for old release notes? See [[Release_Notes_-_Older_Releases|Release Notes - Older Releases]].

<div class="toclimit-2">__TOC__</div>

== Obsidian 6.3.2 ==
To Be Released October 2025

=== Enhancements ===
* Notification failures now trigger Dispatch category Error level event on first failure. For use in log alerts and Event Hooks.

=== Bug Fixes ===

* Notification failures no longer log on every failure reducing chatty failure logs.
* No-arg constructors added to multiple JSON serializable candidate POJOs missing them. Addresses GSON's workaround use of sun.misc.Unsafe.

== Obsidian 6.3.1 ==
Released August 2025

=== Bug Fixes ===

* Fix failure response codes on [[REST_Endpoints#GET_health_details_on_an_existing_scheduling_host|REST health endpoint]]
* Fix automatic upgrade issue from 6.1.0 to any of 6.2.0, 6.2.1, 6.3.0
* Fix auth issue when [[Admin_User_Management#Multi-Factor_Authentication_.28MFA.29|MFA]] is enabled that allows REST access when account has been locked out due to MFA not being setup. [[Contact_the_Obsidian_Scheduler_Team|Contact us]] if you need workaround details for earlier versions.
* Fix native auth issue that allows REST access when account has been flagged as inactive.

== Obsidian 6.3.0 ==
Released July 2025

=== Features / Enhancements ===

* Cron day of month expansion for [[Cron#Special_Character_Usage|day of week proximity]] using [[Cron#Examples|~]]
* Annotation based job and chain configuration [[Initializing_and_Restoring#Annotation_Initialization|initialization]]
* Health endpoint with details for Job Queuer and Job Spawner - [[REST_Endpoints#GET_health_details_on_an_existing_scheduling_host|REST API]] or Embedded API [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#getHealth(java.lang.String) by hostname] or [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#getHealth(long) by host id]
* JDBC URL construction from parts [[Advanced_Configuration#Database_Properties|host/port/databaseName/dbType/oracleSid]]

== Obsidian 6.2.1 ==
Released June 2025

=== Bug Fixes ===

* Certain recoveries greater than 24 hours using new day of month proximity patterns introduced in 6.2.0 would result in no jobs spawning.
* Migrations targeting 6.0.0 and greater that start earlier than 5.0.0 skip the 5.0.0 migration. Migrating to any 5.x version first and then to 6.0.0 or later works around this issue.

== Obsidian 6.2.0 ==
Released May 2025

=== Features / Enhancements ===

* Cron day of month expansion for [[Cron#Special_Character_Usage|day of week proximity]] using [[Cron#Examples|< > ≥ ≤]]
* Cron day of month expansion for [[Cron#Special_Character_Usage|weekday proximity]] using [[Cron#Examples|< > ≥ ≤]]
* [[Admin_Global_Parameters#Using_Global_Parameters_in_Jobs|Global Parameters]] reference in job edit page support mouseover/title display of actual value when permissions allow
* Host time displayed in [[Admin_Host_Status|hosts status]] in UI
* [[Admin_Job_Runtime_Preview|Runtime Preview]] optimizations for large date ranges in both UI and APIs.

=== Bug Fixes ===

* Combination of table prefix, sorting by clob column and Oracle metadata load failure no longer results in sql error. This occurred in the UI when viewing raw job history results and in API calls for job runtime results.

== Obsidian 6.1.1 ==
Released March 2025

=== Features / Enhancements ===

* [[Authenticator#Implementation_of_a_Custom_Authenticator|Authenticator]] supports optional <code>authenticateREST()</code> method.

=== Bug Fixes ===

* Native authentication REST logins do not apply 'last login' timestamps. Avoids noisy error that was appearing in logs.

== Obsidian 6.1.0 ==
Released March 2025

=== Features / Enhancements ===

* Native authentication now disables users after 4 invalid login attempts, either password or MFA code if applicable. Invalid attempts threshold is configurable.
* Native authentication last login datetime displayed on list user screen.
* Stronger licensing controls. Site and hardware licenses as of this version must be regenerated by Carfey Software and every 2 years. Contact us at licensing [[Image:atSymbol.png]] obsidianscheduler.com.

=== Bug Fixes ===

* Native authentication password complexity pattern properly created and no longer overwritten on restart.

== Obsidian 6.0.1 ==
Released February 2025

=== Features / Enhancements ===

* [[Built-in_Jobs#File_Archive_Job|File Archive Job]] and [[Built-in_Jobs#File_Scanner_Job|File Scanner Job]] both now support min/max file sizes and minimum age.

=== Bug Fixes ===

* Native authentication user updates now support long passwords.

== Obsidian 6.0.0 ==
Released December 27, 2024

=== Features / Enhancements ===

* Jakarta Servlet 5.0
** Servlet container for Web Admin must support Jakarta Servlet 5.0 (e.g. Tomcat 10, Jetty 11)
* [[Micronaut_Integration|Micronaut]] integration support
* [[Advanced_Configuration#Dependent_Libraries|Groovy 4]] support
* [[Advanced_Configuration#Properties.2FYaml_File|Yaml]] configuration support<ref>

If you are using automated installer files from previous releases, you will need to add an additional configuration item to choose between yaml and properties formats in UserInputPanel.0.
<pre>
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.0">
<userInput>
......snip......
<entry key="config.format" value="yaml" />
OR
<entry key="config.format" value="properties" />
......snip......
</userInput>
</com.izforge.izpack.panels.UserInputPanel>
</pre></ref>
* Native authentication supports customizable [[Admin_Login#Password_Complexity|password complexity]] requirements
* XML support deprecated across the product including XML UI downloads, XML runner configurations and XML license leases.
** '''Starting January 1st 2027, XML license lease requests will stop being processed. All Obsidian instances running using internet-verified licenses (including licence key proxies) will be required to use release 6.0.0 or later as of January 1st 2027.'''
** Above noted XML support will be removed in the first Obsidian version released in 2027.
* License leases use JSON payloads.

== Obsidian 5.5.1 ==
Released December 16, 2024

=== Bug Fixes ===

* Admin only (no scheduler) UI no longer generates event hook errors while running nor during shutdown
* Quick start installer file no longer generates errors during installation
* A few small web UI enhancements

== Obsidian 5.5.0 ==
Released October 2024

=== Features / Enhancements ===

* Event Hooks management available in [[Admin_Host_Status#Event_Hook_Status|UI]], [[Embedded_API#Event_Hook_Resume_or_Pause|Embedded API]] and [[REST_Endpoints#POST_event_hook_pause_or_resume|REST API]].
* [[Installation_Guide#Additional_configuration_items|Installer]] supports custom add on configurations '''Potential breaking change to automated installer files.''' <ref>

If you are using automated installer files from previous releases, you will need to add a new section of xml as of Obsidian 5.5.0 to handle a new UserInputPanel. Immediately after the UserInputPanel.17 closing brace, add the following:
<pre>
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.18">
<userInput>
<entry key="extra.log4j2.properties.1" value=""/>
<entry key="extra.log4j2.properties.2" value=""/>
<entry key="extra.log4j2.properties.3" value=""/>
<entry key="extra.log4j2.properties.4" value=""/>
<entry key="extra.log4j2.properties.5" value=""/>
<entry key="extra.log4j2.properties.6" value=""/>
<entry key="extra.log4j2.properties.7" value=""/>
<entry key="extra.log4j2.properties.8" value=""/>
<entry key="extra.log4j2.properties.9" value=""/>
<entry key="extra.log4j2.properties.10" value=""/>
<entry key="extra.log4j2.properties.11" value=""/>
<entry key="extra.log4j2.properties.12" value=""/>
<entry key="extra.log4j2.properties.13" value=""/>
<entry key="extra.log4j2.properties.14" value=""/>
<entry key="extra.log4j2.properties.15" value=""/>
<entry key="extra.log4j2.properties.16" value=""/>
<entry key="extra.log4j2.properties.17" value=""/>
<entry key="extra.log4j2.properties.18" value=""/>
<entry key="extra.log4j2.properties.19" value=""/>
<entry key="extra.log4j2.properties.20" value=""/>
<entry key="extra.carfey.properties.1" value=""/>
<entry key="extra.carfey.properties.2" value=""/>
<entry key="extra.carfey.properties.3" value=""/>
<entry key="extra.carfey.properties.4" value=""/>
<entry key="extra.carfey.properties.5" value=""/>
<entry key="extra.carfey.properties.6" value=""/>
<entry key="extra.carfey.properties.7" value=""/>
<entry key="extra.carfey.properties.8" value=""/>
<entry key="extra.carfey.properties.9" value=""/>
<entry key="extra.carfey.properties.11" value=""/>
<entry key="extra.carfey.properties.10" value=""/>
<entry key="extra.carfey.properties.12" value=""/>
<entry key="extra.carfey.properties.13" value=""/>
<entry key="extra.carfey.properties.14" value=""/>
<entry key="extra.carfey.properties.15" value=""/>
<entry key="extra.carfey.properties.16" value=""/>
<entry key="extra.carfey.properties.17" value=""/>
<entry key="extra.carfey.properties.18" value=""/>
<entry key="extra.carfey.properties.19" value=""/>
<entry key="extra.carfey.properties.20" value=""/>
</userInput>
</com.izforge.izpack.panels.UserInputPanel>
</pre>
</ref>

=== Bug Fixes ===

* Certain Cron expressions that fail to generate text descriptions no longer impact scheduling.
* Text database columns were previously restricted to maximum length of MySQL implementation. Corrected to validate length via DB implementation.

== Obsidian 5.4.0 ==
Released June 2024

=== Features / Enhancements ===

* Event Hooks available in [[Embedded_API#List_Event_Hooks|Embedded API]] and [[REST_Endpoints#GET_event_hooks|REST API]].
* [[Advanced_Configuration#Dependent_Libraries|GSON library]] upgrade to support Java 21

=== Bug Fixes ===

* Oracle identifier no longer too long when using prefixes.

== Obsidian 5.3.0 ==
Released March 2024

=== Features / Enhancements ===

* New [[Admin_Host_Status#Event_Hook_Status| Event Hooks Status]] available in the UI.

=== Bug Fixes ===

* Some improvements throughout the [[Admin_Web_Application_Guide|Admin Web Application]] for autofocus of fields.
* Additional classes and interfaces added to [https://web.obsidianscheduler.com/obsidianapi/ javadoc].
* Some cleanup in [https://web.obsidianscheduler.com/obsidianapi/ javadoc] documenation.

== Obsidian 5.2.1 ==
Released January 2024

=== Features / Enhancements ===

* [[Built-in_Jobs#Maintenance_Jobs|Maintenance Jobs]] are now scheduled by default in new installations. Can be disabled via [[Advanced_Configuration#Miscellaneous_Properties|Configuration]] property.
* New [[Event_Hooks#Standard_Output.2FError_Streams_Event_Hook | Standard Output/Error Streams Event Hook]].

=== Bug Fixes ===

* Schedule descriptions are now updated after edits are applied in all UI screens and APIs.

== Obsidian 5.2.0 ==
Released December 2023

=== Features / Enhancements ===

* [[Cron]] & [[Cron#Recurrence|Recur]] patterns along with any use of [[Admin_Schedule_Aliases|Schedule Aliases]] now support plain language description of the patterns throughout the [[Admin_Web_Application_Guide|UI]], visible while hovering patterns, and in [[REST_Endpoints|REST]] and [[Embedded_API|Embedded]] API responses.
* All screens supporting UI exports now support JSON ([[Admin_Job_Activity#Exporting_Results|Job Activity]], [[Admin_Jobs#Exporting_Results|Jobs]], [[Admin_Job_Runtime_Preview#Exporting_Results|Runtime Previews]], [[Admin_Job_Chains#Job_Chain_Listing|Job Chains]], [[Admin_Logs#Exporting_Results|Logs]], [[Admin_Notifications#Exporting_Results|Sent Notifications]], [[Admin_User_Management#Exporting_Results|Users]], [[Admin_Custom_Calendars#Calendar_Listing|Calendars]])
* All screens supporting UI exports and search criteria and/or inline filters now include any specified search criteria and filter text in Excel, XML and JSON downloads ([[Admin_Job_Activity#Exporting_Results|Job Activity]], [[Admin_Jobs#Exporting_Results|Jobs]], [[Admin_Job_Runtime_Preview#Exporting_Results|Runtime Previews]], [[Admin_Job_Chains#Job_Chain_Listing|Job Chains]], [[Admin_Logs#Exporting_Results|Logs]], [[Admin_Notifications#Exporting_Results|Sent Notifications]], [[Admin_User_Management#Exporting_Results|Users]])
* Support for [[Installation_Guide#Choosing_Email_Support|Jakarta EE mail]] '''Potential breaking change to automated installer files.''' <ref>

If you are using automated installer files from previous releases and had email configured, you will need to add a new section of xml as of Obsidian 5.2.0 to handle a new UserInputPanel. Immediately after the UserInputPanel.16 closing brace, add the following:
<pre>
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.17">
<userInput>
<entry key="mail.type.selection" value="javax"/>
</userInput>
</com.izforge.izpack.panels.UserInputPanel>
</pre>
</ref>
* New [[Event_Hooks#REST_Endpoint_Event_Hook|REST Endpoint Event Hook]]
* [[Key_Server_Proxy|Key Server proxy]] artifact obtained via web download during installation

=== Bug Fixes ===

* Time picker buttons (hour, minute, AM/PM) in [[Admin_Job_Activity#Filtering|Job Activity filtering]] no longer change other elements of the selected time.
* Cron pattern with [[Cron#Special_Character_Usage|LW]] and any other non-L value in day position no longer also incorrectly evaluates to last day.

== Obsidian 5.1.1 ==
Released June 2023

=== Bug Fixes ===

* [[Authenticator|Native authentication]] no longer fails when user deletes are attempted from the UI.
* Built in maintenance job [[Built-in_Jobs#Job_History_Cleanup_Job|Job History Cleanup]] no longer leaves deletion candidate CHAIN SKIPPED records in the JOB_HISTORY table in rare circumstances.

== Obsidian 5.1.0 ==
Released April 2023

=== Features / Enhancements ===

* [[Admin_Schedule_Aliases#Schedule_Alias_Fragments|Schedule Aliases]] now support fragments for configuration-time substitutions.
* New convenience job [[Built-in_Jobs#Database_File_Export_Job|Database File Export Job]] for generating basic file extracts from database queries.
* New convenience job [[Built-in_Jobs#REST_Invocation_Job|REST Invocation Job]] for making simple REST calls and storing results.
* Performance improvements in job failure handling.

== Obsidian 5.0.4 ==
Released February 2022

=== Features / Enhancements ===
* Log4j2 2.17.1 as fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.17.1 RCE vulnerability] where attackers can modify log4j configuration.
* Restore missing default log4j2 configuration in installation artifacts.

== Obsidian 5.0.3 ==
Released December 2021

=== Features / Enhancements ===
* Log4j2 2.17.0 as fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.17.0 DOS vulnerability]
* Fix native login issue showing as inactive on some databases.

== Obsidian 5.0.2 ==
Released December 2021

=== Features / Enhancements ===
* Log4j2 2.16.0 as permanent fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.16.0 RCE vulnerability]

== Obsidian 5.0.1 ==
Released December 2021

=== Features / Enhancements ===
* Log4j2 2.15.0 as fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.15.0 RCE vulnerability]

=== Bug Fixes ===
* Fix sporadic native login issue on some databases.
* Formatting fix in quick installer file

== Obsidian 5.0.0 ==
Released August 2021.

=== Features / Enhancements ===
* Java 11 (minimum Java version)
* [[Admin_Schedule_Aliases|Schedule Aliases]] including support in [[REST_Endpoints#Schedule_Alias_Endpoints|REST API]] and [[Embedded_API#ScheduleAliasManager_API|Embedded API]]
* [[Admin_User_Management#Multi-Factor_Authentication_.28MFA.29|MFA Support]] for UI logins
* New [[Admin_User_Management#User_Rights|Author and Operator]] roles
* Convention-based role permissions by [[Admin_User_Management#Job_Folder_Rights|root job folder]] for Write, Author and Operator.<ref>
There is a possibility of a breaking change to Embedded or REST API use due to the need to change the [[Embedded_API#Enumerations|User Role enumeration]] from a Java enum to an enum-style class to support this feature. Bringing in the upgraded Obsidian library and compiling should reveal any such broken use of these enumerations. Needed changes should be minor and self-explanatory.</ref>
* Bundled Jetty 10.0.2
* Legacy Embedded API (from Obsidian 1.5) dropped
* Signal handler disabled by default. Enabled only via [[Advanced_Configuration#Miscellaneous_Properties|configuration]].
* Many [[Advanced_Configuration#Dependent_Libraries|library upgrades]].
* UI javascript library updates.

== Footnotes ==
<references/>