REST Endpoints

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 Gson. If you wish to use these, please review bean classes for information on serialization of Obsidian's custom types.

Job Endpoints

GET a list of jobs

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

Response bean class: com.carfey.ops.api.bean.job.JobListing

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

Query String Parameters

Field	Required?	Notes
activeStatus	N	Restricts the preview to the selected statuses. See 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: GET http(s)://localhost/rest/jobs[?param_group=customer&param_group=order]

Sample Response

{
  "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
    }
  ]
}

GET details of an existing job

GET http(s)://localhost/rest/jobs/{jobId}

Response bean class: com.carfey.ops.api.bean.job.JobDetail

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

Sample Response (with inline comments)

{
  "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
    }
  ]
}

POST a new job

POST http(s)://localhost/rest/jobs

Request bean class: com.carfey.ops.api.bean.job.JobCreationRequest

Response bean class: com.carfey.ops.api.bean.job.JobDetail

Creates a new job with an initial schedule.

Sample Request

{
  "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
    }
  ]
}

Request Format

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 Enumerations.
state	Y	Initial schedule's job status as defined in Enumerations.
schedule	Y/N	If state is ENABLED, the mandatory cron-style schedule for the job. If not ENABLED, this should be omitted. 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 @Configuration annotation, a job will fail to create unless they are supplied. Otherwise, this field is optional. Parameter definitions must have values for "name", "type" and "value", where type is a valid parameter type outlined in Enumerations. To define multiple values for a single parameter name, simply include multiple items in the parameters collection.

Responses have the same format as GET.

PUT updates to an existing job

PUT http(s)://localhost/rest/jobs/{jobId}

Request bean class: com.carfey.ops.api.bean.job.JobUpdateRequest

Response bean class: com.carfey.ops.api.bean.job.JobDetail

Updates a job's configuration. Does not support schedule changes or additions. For schedule changes, see 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

{
  "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"
    }
  ]
}

Request Format

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 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 @Configuration annotation, a job will fail to create unless they are supplied. Otherwise, this field is optional. Parameter definitions must have values for "name", "type" and "value", where type is a valid parameter type outlined in Enumerations. To define multiple values for a single parameter name, simply include multiple items in the parameters collection.

Responses have the same format as GET.

DELETE an existing job

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

Response bean class: com.carfey.ops.api.bean.job.JobDetail

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

Query String Parameters

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

GET http(s)://localhost/rest/jobs/{jobId}/schedules[?start=1356987599000&end=1357510546000]

Response bean class: com.carfey.ops.api.bean.job.JobScheduleListing

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

Query String Parameters

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

{
  "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
}

POST a new schedule to an existing job

POST http(s)://localhost/rest/jobs/{jobId}/schedules

Request bean class: com.carfey.ops.api.bean.schedule.ScheduleCreationRequest

Response bean class: com.carfey.ops.api.bean.job.JobScheduleListing

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

{
  "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)
}

Request Format

Field	Required?	Notes
state	Y	The schedule's job status as defined in Enumerations.
schedule	Y/N	If state is ENABLED, the mandatory cron-style schedule for the job. If not ENABLED, this should be omitted. 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

GET http(s)://localhost/rest/global_parameters

Response bean class: com.carfey.ops.api.bean.job.GlobalParameterListing

Available as of version 2.5.

Lists the configured global parameters

Sample Response

{
   "parameters": [
      { 
         "name": "forceSSL",
         "type": "BOOLEAN",
         "values": ["false"]
      },
      { 
         "name": "hostNames",
         "type": "STRING",
         "values": ["example.com", "test.com"]
      }
   ]
}

PUT updates to global parameters

PUT http(s)://localhost/rest/global_parameters

Request bean class: com.carfey.ops.api.bean.job.GlobalParameterUpdateRequest

Response bean class: com.carfey.ops.api.bean.job.GlobalParameterListing

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

{
   "parameters": [
      { 
         "name": "forceSSL",
         "type": "BOOLEAN",
         "values": ["false"]
      },
      { 
         "name": "hostNames",
         "type": "STRING",
         "values": ["example.com", "test.com"]
      }
   ]
}

Request Format

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

GET http(s)://localhost/rest/job_folders

Response bean class: com.carfey.ops.api.bean.job.JobFolderListing

Available as of version 4.1.

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

Sample Response

  "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
    }
  ]
}

Runtimes Endpoints (i.e. Job History)

GET a list of scheduled runtimes (supports multiple jobs)

GET http(s)://localhost/rest/job_runtimes[?startKey=12345&status=RUNNING&host=host1&quantity=100&sort=asc]

Response bean class: com.carfey.ops.api.bean.history.RuntimeListing

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 sort parameter.

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

Query String Parameters

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 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 nextPageStartKey.
quantity	N	Indicates the maximum number of results to return. This overrides the maxRecords as configured in the scheduler settings screen. As of Obsidian 3.5.0.
sort	N	A 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)

{
  "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"
    }
  ]
}

GET a list of a job's scheduled runtimes

GET http(s)://localhost/rest/jobs/{jobId}/runtimes

Response bean class: com.carfey.ops.api.bean.history.RuntimeListing

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

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)

POST http(s)://localhost/rest/jobs/{jobId}/runtimes

Request bean class: com.carfey.ops.api.bean.history.RuntimeSubmissionRequest

Response bean class: com.carfey.ops.api.bean.history.RuntimeSubmissionResult

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. UNSCHEDULED_ACTIVE, ENABLED, or AD_HOC_ACTIVE).

Sample Request

{
  "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"
    }
  ]
}

Request Format

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 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 jobRuntimeId is only returned in the case of an ad hoc run.

Sample Response (with inline comments)

{
  "jobRuntimeId": 2, // only returned for ad hoc submission (no scheduled time supplied)
  "jobId": 36,
  "scheduledTime": "2013-01-06T16:37:00-0800"
}

GET details of an existing scheduled (or completed) job runtime

GET http(s)://localhost/rest/job_runtimes/{jobRuntimeId}

Response bean class: com.carfey.ops.api.bean.history.RuntimeResult

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

Sample Response

{
  "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
      }
    ]
  }
}

DELETE a future scheduled runtime

Since Obsidian 4.7.0

DELETE http(s)://localhost/rest/jobs/{jobId}/runtimes

Request bean class: com.carfey.ops.api.bean.history.OneTimeRunDeleteRequest

Response bean class: com.carfey.ops.api.bean.history.OneTimeDeletionResult

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

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

Request Format

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)

{
  "jobId": 2,
  "jobRuntimeId": 36389,
  "scheduledTime": "2021-02-01T19:00:00-0800"
}

POST a resubmission request for a failed job runtime

POST http(s)://localhost/rest/job_runtimes/{jobRuntimeId}/resubmissions

Response bean class: com.carfey.ops.api.bean.history.RuntimeResubmissionResult

Allows for resubmission of a failed job runtime.

Sample Response

{
  "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
  }
}

POST an interruption request to kill a running job

POST http(s)://localhost/rest/job_runtimes/{jobRuntimeId}/interrupts

Response bean class: com.carfey.ops.api.bean.history.JobInterruptResult

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 Interruptable Jobs for full details.

Sample Response

{
  "interruption": {
    "requester": "apiUserName",
    "requestTime": "2013-01-06T16:49:00-0800"
  }
}

POST async results

POST http(s)://localhost/rest/job_runtimes/{jobRuntimeId}/async_results

Request bean class: com.carfey.ops.api.bean.history.AsyncJobRuntimeResultsRequest

Response bean class: com.carfey.ops.api.bean.history.RuntimeResult

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 Async Job for full details.

Sample Request

{
	"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":[]}
}

Sample Response

{
    "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"
    }
}

GET a list of the latest scheduled runtime by job (supports multiple jobs)

GET http(s)://localhost/rest/job_runtimes/latest[?startKey=12345&host=host1&quantity=100&sort=asc]

Response bean class: com.carfey.ops.api.bean.history.JobDashboardListing

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 sort parameter.

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

Query String Parameters

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 nextPageStartKey.
quantity	N	Indicates the maximum number of results to return. This overrides the maxRecords as configured in the scheduler settings screen.
sort	N	A 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)

{
  "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"
    }
  ]
}

Runtime Preview Endpoints

GET a list of runtime previews (supports multiple jobs)

GET http(s)://localhost/rest/job_runtimes/previews[?jobId=1&jobId=2&start=1356987599000&end=1357510546000]

Response bean class: com.carfey.ops.api.bean.schedule.RuntimePreviewListing

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 maxRecords as configured in the scheduler settings screen). If you are hitting this condition, try limiting your date range or other parameters.

Query String Parameters

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

{
  "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"
    }
  ]
}

GET a list of runtime previews for an existing job

GET http(s)://localhost/rest/jobs/{jobId}/runtimes/previews

Response bean class: com.carfey.ops.api.bean.schedule.RuntimePreviewListing

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

Other than the jobId, 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

GET http(s)://localhost/rest/chains[?active=true&sourceJobId=123&targetJobId=456]

Response bean class: com.carfey.ops.api.bean.job.JobChainListing

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

Query String Parameters

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)

{
  "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
    }
  ]
}

GET details of an existing job chain

GET http(s)://localhost/rest/chains/{jobChainId}

Response bean class: com.carfey.ops.api.bean.job.JobChain

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)

{
   "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"]
     }
   ]
}

POST a new job chain

POST http(s)://localhost/rest/chains

Request bean class: com.carfey.ops.api.bean.job.JobChainUpdateRequest

Response bean class: com.carfey.ops.api.bean.job.JobChain

Creates a new job chain.

Sample Request

{
  "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
    }
  ]
}

Request Format

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 Enumerations. Note that CONDITIONAL and COMPLETED types cannot be used on the same chain.
resultConditions	Y/N	Conditions based on job results that apply to the CONDITIONAL trigger state. Must be supplied only when that state is used, in which case at least one condition must be supplied. Result conditions consist of a variableName, an operator as defined in Enumerations, and for most operators, a list of values. The EXISTS and NOT EXISTS operators do not use values, so they must not be supplied. Operators IN and NOT IN support one or more values, and all other operators accept a single value in the values list. Values for this field map to bean class com.carfey.ops.api.enums.JobChainConditionOperator.

Responses have the same format as GET.

PUT updates to an existing job chain

PUT http(s)://localhost/rest/chains/{jobChainId}

Request bean class: com.carfey.ops.api.bean.job.JobChainUpdateRequest

Response bean class: com.carfey.ops.api.bean.job.JobChain

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.

DELETE http(s)://localhost/rest/chains/{jobChainId}

Response bean class: com.carfey.ops.api.bean.job.JobChain

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

GET http(s)://localhost/rest/conflicts

Response bean class: com.carfey.ops.api.bean.job.ConflictListing

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 conflictJobs field.

Sample Response (with inline comments)

{
  "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
    }
  ]   
}

PUT updates to job conflicts

PUT http(s)://localhost/rest/conflicts

Request bean class: com.carfey.ops.api.bean.job.ConflictUpdateRequest

Response bean class: com.carfey.ops.api.bean.job.JobDetail

Replaces the current job conflict configuration with the supplied configuration.

Sample Request

{  

  // 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.
  ]
}

Request Format

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

GET http(s)://localhost/rest/jobs/{jobId}/conflicts

Response bean class: com.carfey.ops.api.bean.job.JobConflictListing

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)

{
  "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
    } 
}

Scheduling Hosts Endpoints

GET a list of known scheduling hosts

GET http(s)://localhost/rest/hosts

Response bean class: com.carfey.ops.api.bean.host.HostListing

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

{
  "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
    }
  ]
}

GET details on an existing scheduling host

GET http(s)://localhost/rest/hosts/{id}

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

Response bean class: com.carfey.ops.api.bean.host.HostDetail

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

Note: The name field corresponds to the host name, as described 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

{
  "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"
  }
}

GET health details on an existing scheduling host

As of Obsidian 6.3.0

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

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

Response bean class: com.carfey.ops.api.bean.host.HostDetail

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

{
    "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",
    }
}

GET licence details on an existing scheduling host

GET http(s)://localhost/rest/hosts/{id}/licence_health        Prior to 4.5: GET http(s)://localhost/rest/hosts/licenceHealthCheck/{id}

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

Response bean class: com.carfey.ops.api.bean.host.HostDetail

The intended use of this endpoint is as a health check. This endpoint is identical to the 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 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

{
  "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"
  }
}

PUT updates to an existing scheduling host

PUT http(s)://localhost/rest/hosts/{id}

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

Request bean class: com.carfey.ops.api.bean.host.HostUpdateRequest

Response bean class: com.carfey.ops.api.bean.host.HostDetail

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 here. Explicit host names should be set if you intend to rely known host names in this endpoint.

Sample Request

{
  "enabled": false
}

Request Format

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

GET http(s)://localhost/rest/event_hooks

Response bean class: com.carfey.ops.api.bean.host.EventHookListing

Returns all event hooks across the cluster.

Sample Response

{
  "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"
            }
        ]
    }
  ]
}

GET event hooks on host

GET http(s)://localhost/rest/hosts/{id}/event_hooks

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

Response bean class: com.carfey.ops.api.bean.host.EventHookListing

Returns all event hooks for the given host.

Sample Response

{
  "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
            }
        ]
    }
  ]
}

POST event hook pause or resume

As of Obsidian 5.5.0

POST http(s)://localhost/rest/event_hooks

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: com.carfey.ops.api.bean.host.UpdateEventHookRequest

Response bean class: com.carfey.ops.api.bean.host.EventHookListing

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

Sample Request

{
  "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"
}

Sample Response

{
  "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"
            }
        ]
    }
  ]
}

Custom Calendar Endpoints

As of Obsidian 2.0. Format revised in 2.3.

The following endpoints allow for managing of Custom Calendars.

GET a list of custom calendars

GET http(s)://localhost/rest/calendars

Response bean class: com.carfey.ops.api.bean.calendar.CustomCalendarListing

Returns a list of custom calendars.

Sample Response

{
  "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
    }
  ]
}

GET details on an existing custom calendar

GET http(s)://localhost/rest/calendars/{id}

Response bean class: com.carfey.ops.api.bean.calendar.CustomCalendar

As of Obsidian 2.3.

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

Sample Response

{
  "revision": 0,
  "dates": ["2013-01-01", "2013-02-18", "2013-04-01", "2013-05-20"],
  "name": "Corporate Holidays 2013",
  "customCalendarId": 1
}

POST a new custom calendar

POST http(s)://localhost/rest/calendars/

Request bean class: com.carfey.ops.api.bean.calendar.CustomCalendarUpdateRequest

Response bean class: com.carfey.ops.api.bean.calendar.CustomCalendar

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

Sample Request

{
   "name": "Cal1",
   "dates": ["2016-10-14" ,"2018-06-14"],
}

Request Format

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

PUT http(s)://localhost/rest/calendars/{id}

Request bean class: com.carfey.ops.api.bean.calendar.CustomCalendarUpdateRequest

Response bean class: com.carfey.ops.api.bean.calendar.CustomCalendar

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

Sample Request

{
    "name": "Cal2",
    "dates": ["2018-06-13","2016-10-13"]
}

Request Format

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.

DELETE http(s)://localhost/rest/calendars/{id}

Response bean class: com.carfey.ops.api.bean.calendar.CustomCalendar

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

GET http(s)://localhost/rest/subscribers

Response bean class: com.carfey.ops.api.bean.notification.SubscriberListing

Returns a list of configured notification subscribers.

Sample Response (with inline comments)

{  
   "subscribers": [  
      {  
         "id": 1,
         "emailAddress": "[email protected]",
         "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": "[email protected]",
         "active": false,
         "generalSubscriptions": [],
         "jobExecutionSubscriptions": []
      }
   ]
}

GET details of an existing subscriber

GET http(s)://localhost/rest/subscribers/{subscriberId}

Response bean class: com.carfey.ops.api.bean.notification.Subscriber

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)

{  
   "id": 1,
   "emailAddress": "[email protected]",
   "active": true,
   "generalSubscriptions": [  
      {  
         "active": true,
         "category": "QUEUE",
         "level": "ERROR"
      }
   ],
   "jobExecutionSubscriptions": [  
      {  
         "active": false,
         "allJobs": true,
         "jobs": [],
         "triggerStates": [ "DIED", "FAILED", "RECOVERY" ],
         "resultConditions": []
      }
   ]
}

POST a new subscriber

POST http(s)://localhost/rest/subscribers

Request bean class: com.carfey.ops.api.bean.notification.SubscriberUpdateRequest

Response bean class: com.carfey.ops.api.bean.notification.Subscriber

Creates a new notification subscriber.

Sample Request

{  
   "emailAddress": "[email protected]",
   "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.
            }
         ]
      }
   ]
}

Request Format

Field	Required?	Notes
emailAddress	Y	Valid email address of the subscriber. Must be unique.
active	N	Whether the subscription is active. Defaults to false.
generalSubscriptions	N	Zero or more general subscriptions. Each item contains a required subscription category and level as defined in Enumerations, an optional jobId and an optional active flag which defaults to false. Note: Only ERROR, WARNING AND INFO are valid values for level. Only JOB, JOB_CHAIN, JOB_CONFIG, JOB_RECOVERY, LICENCE, QUEUE, SYSTEM_PARAMETER and null are valid values for category.
jobExecutionSubscriptions	N	Zero or more job execution subscriptions. Each item contains a required triggerStates field containing at least one subscription job status as defined in Enumerations. Note that CONDITIONAL and COMPLETED types cannot be used on the same chain. If the CONDITIONAL state is selected, at least one condition must be supplied in the resultConditions field. Result conditions consist of a variableName, an operator as defined in Enumerations, and for most operators, a list of values. The EXISTS and NOT EXISTS operators do not use values, so they must not be supplied. Operators IN and NOT IN support one or more values, and all other operators accept a single value in the values list. Values for this field map to bean class com.carfey.ops.api.enums.JobSubscriptionConditionOperator. In addition, two additional optional fields control which jobs the subscription applies to. jobIds is used to specify specific jobs, while allJobs may be set to true to make it apply to all jobs. If jobIds is supplied and allJobs is set to true, jobIds will be ignored. Finally, the active flag may be supplied which defaults to true.

Responses have the same format as GET.

PUT updates to an existing subscriber

PUT http(s)://localhost/rest/subscribers/{subscriberId}

Request bean class: com.carfey.ops.api.bean.notification.SubscriberUpdateRequest

Response bean class: com.carfey.ops.api.bean.notification.Subscriber

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

Requests and responses have the same format as POST.

DELETE an existing subscriber

DELETE http(s)://localhost/rest/subscribers/{subscriberId}

Response bean class: com.carfey.ops.api.bean.notification.Subscriber

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

GET http(s)://localhost/rest/templates

Response bean class: com.carfey.ops.api.bean.notification.TemplateListing

Returns a list of configured templates.

Sample Response (with inline comments)

{  
   "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..."
      }
   ]
}

GET details of an existing template

GET http(s)://localhost/rest/templates/{templateId}

Response bean class: com.carfey.ops.api.bean.notification.Template

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)

{  
   "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..."
}

POST a new template

POST http(s)://localhost/rest/templates

Request bean class: com.carfey.ops.api.bean.notification.TemplateUpdateRequest

Response bean class: com.carfey.ops.api.bean.notification.Template

Creates a new template.

Sample Request

{
   "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..."
}

Request Format

Field	Required?	Notes
name	Y	Unique name of the template.
active	N	Whether the template is active. Defaults to false.
category	N	The category for the template as defined in Enumerations, or null if it is the default generic template. Supports multiple values. Not all categories are supported. Only JOB, JOB_CHAIN, JOB_CONFIG, JOB_RECOVERY, LICENCE, QUEUE, SYSTEM_PARAMETER and null are valid values.
defaultForJobs	N	For job-related categories, setting this to true allows for a template to be used as the default template when one isn't assigned to a particular job. Defaults to false.
jobIds	N	For job-related categories, specific jobs may be assigned to use this template.
subjectTemplate	Y	A valid Mustache template for the subject.
bodyTemplate	Y	A valid Mustache template for the body.

Responses have the same format as GET.

PUT updates to an existing template

PUT http(s)://localhost/rest/templates/{templateId}

Request bean class: com.carfey.ops.api.bean.notification.TemplateUpdateRequest

Response bean class: com.carfey.ops.api.bean.notification.Template

Requests and responses have the same format as POST.

DELETE an existing template

DELETE http(s)://localhost/rest/templates/{templateId}

Response bean class: com.carfey.ops.api.bean.notification.Template

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

GET http(s)://localhost/rest/notifications[?category=QUEUE&level=ERROR&start=1356987599000&end=1357510546000&startKey=123]

Response bean class: com.carfey.ops.api.bean.notification.NotificationListing

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 nextPageStartKey field in the response indicates that there were too many results to return (i.e. exceeded maxRecords as configured in the scheduler settings screen). To fetch the next page of results, invoke the same endpoint with the startKey query string parameter set to the returned nextPageStartKey.

Query String Parameters

Field	Required?	Notes
category	N	The category of the notifications as defined in Enumerations. Supports multiple values.
level	N	The logging level of the notifications defined in 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 nextPageStartKey.

Sample Response (with inline comments)

{
  "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": "[email protected]",
            "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": "[email protected]",
            "active": true
         }
      },
  ]
}

GET details of an existing notification

GET http(s)://localhost/rest/notifications/{id}

Response bean class: com.carfey.ops.api.bean.notification.Notification

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)

{  
   "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": "[email protected]",
      "active": true // current active state (not when triggered)
   }
}

Log Endpoints

As of Obsidian 3.0

GET a list of logs

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

Response bean class: com.carfey.ops.api.bean.log.LogListing

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 nextPageStartKey field in the response indicates that there were too many results to return (i.e. exceeded maxRecords as configured in the scheduler settings screen). To fetch the next page of results, invoke the same endpoint with the startKey query string parameter set to the returned nextPageStartKey.

Query String Parameters

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 Enumerations. Supports multiple values.
level	N	The logging level of the log as defined in 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 nextPageStartKey.

Sample Response

{
  "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."
	}
  ]
}

GET details of an existing log

GET http(s)://localhost/rest/logs/{logId}

Response bean class: com.carfey.ops.api.bean.log.Log

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

Sample Response (with inline comments)

{
   "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"
}

System Parameter Endpoints

As of version 3.0.

GET a list of system parameters

GET http(s)://localhost/rest/system_parameters

Response bean class: com.carfey.ops.api.bean.system.SystemParameterListing

Returns a list of system parameters which can be edited.

Sample Response (with inline comments)

{
  "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"
     }
  ]
}

GET details of a system parameter

GET http(s)://localhost/rest/system_parameters/{name}

Response bean class: com.carfey.ops.api.bean.system.SystemParameter

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)

{
   "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"
}

PUT updates to a system parameter

PUT http(s)://localhost/rest/system_parameters/{name}

Request bean class: com.carfey.ops.api.bean.system.SystemParameterUpdateRequest

Response bean class: com.carfey.ops.api.bean.system.SystemParameter

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

{
   "value": "60"
}

Request Format

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

GET http(s)://localhost/rest/users

Response bean class: com.carfey.ops.api.bean.user.UserListing

Returns a list of configured users.

Sample Response (with inline comments)

{
  "users": [
    {
        "id": 1,
        "userName": "admin",
        "active": true,
        "roles": ["ADMIN","API"]
    },
    {
	"id": 2
        "userName": "reader",
	"active": false,
	"roles": [] // no roles means read-only
    }
  ]
}

GET details of an existing user

GET http(s)://localhost/rest/users/{userId}

Response bean class: com.carfey.ops.api.bean.user.User

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)

{
   "id": 1,
   "userName": "admin",
   "active": true,
   "roles": ["ADMIN","API"]
}

POST a new user

POST http(s)://localhost/rest/users

Request bean class: com.carfey.ops.api.bean.user.UserCreationRequest

Response bean class: com.carfey.ops.api.bean.user.User

Creates a new user.

Sample Request

{
   "userName": "admin",
   "active": true,
   "roles": ["ADMIN","API"],
   "password": "changeme"
}

Request Format

Field	Required?	Notes
userName	Y	Unique user name used to log in.
active	N	Whether the user is enabled. Defaults to false.
roles	N	Zero or more roles as defined in 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

PUT http(s)://localhost/rest/users/{userId}

Request bean class: com.carfey.ops.api.bean.user.UserUpdateRequest

Response bean class: com.carfey.ops.api.bean.user.User

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

{
   "active": true,
   "roles": ["ADMIN","API"],
   "password": "changeme"
}

Request Format

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

DELETE http(s)://localhost/rest/users/{userId}

Response bean class: com.carfey.ops.api.bean.user.User

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.

GET http(s)://localhost/rest/users/mfa

Response bean class: com.carfey.ops.api.bean.user.MfaUserListing

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

Sample Response

{
  "userNames": [
    "admin",
    "john.doe",
    "operator"
  ]
}

PUT MFA user resets

As of version 5.0.

PUT http(s)://localhost/rest/users/mfa/reset

Request bean class: com.carfey.ops.api.bean.user.ResetMfaRequest

Response bean class: com.carfey.ops.api.bean.user.MfaUserListing

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

{
  "userNames": [
    "admin",
    "john.doe",
    "operator"
  ]
}

Request Format

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

{
  "userNames": [
    "admin",
    "john.doe",
    "operator"
  ]
}

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 for more details.

GET a system restore configuration

GET http(s)://localhost/rest/system_restores[?excludeItem=users&jobNickname=jobname]

Response bean class: com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration

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

Query String Parameters

Field	Required?	Notes
excludeItem	N	Allows filtering out of specific groups of system configuration items. Supported values are jobs, chains, conflicts, systemParameters, customCalendars, globalParameters, users, templates, subscribers. Filtering out jobs automatically also filters out chains and conflicts and drops any other job references (such as in templates and subscribers). 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)

{
   "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": "[email protected]",
         "active": true
      }
   ]
}

PUT a system restore configuration

PUT http(s)://localhost/rest/system_restores

Request bean class: com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration

Response bean class: com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration

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 Javadoc and the 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 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 Schedule Aliases for more details.

GET a list of schedule aliases

GET http(s)://localhost/rest/schedule_aliases

Response bean class: com.carfey.ops.api.bean.schedule.ScheduleAliasListing

Returns the system's schedule aliases.

Sample Response

{
    "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)
        }
    ]
}

PUT a schedule alias

PUT http(s)://localhost/rest/schedule_aliases/{alias}

Request bean class: com.carfey.ops.api.bean.schedule.ScheduleAliasUpdateRequest

Response bean class: com.carfey.ops.api.bean.schedule.ScheduleAlias

Sample Request

{
    "schedule": "5 11 * * 2"
}

Sample Response

{	"alias": "@1105AMTuesdays",
	"schedule": "5 11 * * 2",
	"schedule": "At 11:05AM on Tuesdays" (as of Obsidian 5.2.0)
}

GET a schedule alias

GET http(s)://localhost/rest/schedule_aliases/{alias}

Response bean class: com.carfey.ops.api.bean.schedule.ScheduleAlias

Sample Response

{	"alias": "@1105AMTuesdays",
	"schedule": "5 11 * * 2",
	"schedule": "At 11:05AM on Tuesdays" (as of Obsidian 5.2.0)
}

DELETE a schedule alias

DELETE http(s)://localhost/rest/schedule_aliases/{alias}

Response bean class: com.carfey.ops.api.bean.schedule.ScheduleAlias

Sample Response

{	"alias": "@1105AMTuesdays",
	"schedule": "5 11 * * 2"
}

Job Execution Statistics Endpoints

As of version 6.4.0.

To retrieve job execution statistics. Assumes Execution Statistics Job has run to completion at least once.

GET a list of job execution statistics

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]

Query String Parameters

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 Enumerations for valid values - case-insensitive. Supports multiple values.
unit	N	Allows targeting stats units. See Enumerations for valid values - case-insensitive. Supports multiple values.
status	N	Allows targeting stats terminal statuses. See 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: com.carfey.ops.api.bean.stats.StatsListing

Returns the cluster's job execution statistics.

Sample Response

{
	"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"
	]
}