Docs Grey arrow pointing right Puppet Enterprise Grey arrow pointing right Orchestrating Puppet runs, tasks, and plans Grey arrow pointing right Orchestrator API v1 endpoints Grey arrow pointing right Jobs endpoints Grey arrow pointing right

Jobs endpoints

Sections

ExpandCollapse

Use the /jobs endpoint to examine orchestrator jobs and their details.

GET /jobs

List all of the jobs known to the orchestrator.

Parameters

The request accepts the following query parameters:

Parameter Definition
limit Return only the most recent n number of jobs.

offset

Return results offset n records into the result set.
order_by Return results ordered by a column. Ordering is available on owner, timestamp, environment, name, and state. Orderings requested on owner are applied to the login subfield of owner.
order Indicates whether results are returned in ascending or descending order. Valid values are "asc" and "desc". Defaults to "asc"
type Indicates the type of job. Matches the command that created the job, which is either deploy, task, or plan_task
task An optional task name to match against. Partial matches are supported. If type is specified, the task option is only allowed for task and plan_task types.

For example:

https://orchestrator.example.com:8143/orchestrator/v1/jobs/352/jobs?limit=20&offset=20Copied!

Response format

The response is a JSON object that lists orchestrator jobs and associated details and pagination information.

For information about jobs, the following keys are used:

Key Definition
items Contains an array of all the known jobs.
id An absolute URL to the given job.
name The name of the given job.
state The current state of the job: new , ready, running, stopping, stopped, finished, or failed.
command The command that created that job.
type The type of job. Either deploy, task, plan_task, plan_script, plan_upload, plan_command, plan_wait, plan_apply, plan_apply_prep
options All of the options used to create that job. The schema of options might vary based on the command.
owner The subject id and login for the user that requested the job.
description (deprecated) A user-provided description of the job. For future compatibility, use the description in options.
timestamp The time when the job state last changed.
created_timestamp The time the job was created.
finished_timestamp The time the job finished.
duration The number of seconds the job took to run.
environment (deprecated) The environment that the job operates in.
node_count The number of nodes the job runs on.
node_states

A JSON map containing the counts of nodes involved with the job by current node state. Unrepresented states are not displayed. This field is null when no nodes exist for a job.
nodes A link to get more information about the nodes participating in a given job.
report A link to the report for a given job.
events A link to the events for a given job
userdata An object of arbitrary key/value data supplied to the job.
For information about pagination, the following keys are used:
Key Definition
pagination Contains information about the limit, offset, and total number of items.
limit The number of items the request was limited to.
offset The offset from the start of the collection. Offset begins at zero.
order_by Either owner, timestamp, environment, name, or state.
order Either asc or desc.
total The total number of items in the collection, ignoring limit and offset
type The type of job filtered on, if any. Either deploy, task, or plan_task.

For example:

{
  "items": [
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234",
      "name": "1234",
      "state": "finished",
      "command": "deploy",
      "type": "deploy",
      "node_count": 5,
      "node_states": {
        "finished": 2,
        "errored": 1,
        "failed": 1,
        "running": 1
      },
      "options": {
        "concurrency": null,
        "noop": false,
        "trace": false,
        "debug": false,
        "scope": {},
        "enforce_environment": true,
        "environment": "production",
        "evaltrace": false,
        "target": null,
        "description": "deploy the web app"
      },
      "owner" : {
        "email" : "admin@example.com",
        "is_revoked" : false,
        "last_login" : "2020-05-05T14:03:06.226Z",
        "is_remote" : true,
        "login" : "admin",
        "inherited_role_ids" : [ 2 ],
        "group_ids" : [ "9a588fd8-3daa-4fc2-a396-bf88945def1e" ],
        "is_superuser" : false,
        "id" : "751a8f7e-b53a-4ccd-9f4f-e93db6aa38ec",
        "role_ids" : [ 1 ],
        "display_name" : "Admin",
        "is_group" : false
      },
      "description": "deploy the web app",
      "timestamp": "2016-05-20T16:45:31Z",
      "started_timestamp": "2016-05-20T16:41:15Z",
      "finished_timestamp": "2016-05-20T16:45:31Z",
      "duration": "256.0",
      "environment": {
        "name": "production"
      },
      "report": {
        "id": "https://localhost:8143/orchestrator/v1/jobs/375/report"
      },
      "events": {
        "id": "https://localhost:8143/orchestrator/v1/jobs/375/events"
      },
      "nodes": {
        "id": "https://localhost:8143/orchestrator/v1/jobs/375/nodes"
      },
      "userdata": {
        "servicenow_ticket": "INC0011211"
      }
    },
    {
      "description": "",
      "report": {
        "id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1235/report"
      },
      "name": "1235",
      "events": {
        "id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1235/events"
      },
      "command": "plan_task",
      "type": "plan_task",
      "state": "finished",
      "nodes": {
        "id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1235/nodes"
      },
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1235",
      "environment": {
        "name": ""
      },
      "options": {
        "description": "",
        "plan_job": 197,
        "noop": null,
        "task": "facts",
        "sensitive": [],
        "scheduled-job-id": null,
        "params": {},
        "scope": {
          "nodes": [
            "orchestrator.example.com"
          ]
        },
        "project": {
          "project_id": "foo_id",
          "ref": "524df30f58002d30a3549c52c34a1cce29da2981"
        }
      },
      "timestamp": "2020-09-14T18:00:12Z",
      "started_timestamp":  "2020-09-14T17:59:05Z",
      "finished_timestamp":  "2020-09-14T18:00:12Z",
      "duration": "67.34",
      "owner": {
        "email": "",
        "is_revoked": false,
        "last_login": "2020-08-05T17:54:07.045Z",
        "is_remote": false,
        "login": "admin",
        "is_superuser": true,
        "id": "42bf351c-f9ec-40af-84ad-e976fec7f4bd",
        "role_ids": [
          1
        ],
        "display_name": "Administrator",
        "is_group": false
      },
      "node_count": 1,
      "node_states": {
        "finished": 1
      },
      "userdata": {}
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "order": "asc",
    "order_by": "timestamp",
    "total": 2,
    "type": ""
  }
}Copied!

Error responses

For this endpoint, the kind key of the error displays the conflict.

Key Definition
puppetlabs.orchestrator/validation-error If the limit parameter is not an integer, the server returns a 400 response.

GET /jobs/:job-id

List all details of a given job.

Response format

The response is a JSON object that lists all details of a given job, and uses these keys:

Key Definition
id An absolute URL to the given job.
name The name of the given job.
state The current state of the job: new, ready, running, stopping, stopped, finished, or failed.
command

The command that created that job.
type The type of job. Either deploy, task, plan_task, plan_script, plan_upload, plan_command, plan_wait, plan_apply, or plan_apply_prep
options All of the options used to create that job.
owner The subject id and login for the user that requested the job.
description (deprecated) A user-provided description of the job.
timestamp The time when the job state last changed.
environment The environment that the job operates in.
node_count The number of nodes the job runs on.
nodes A link to get more information about the nodes participating in a given job.
report A link to the report for a given job.
events A link to the events for a given job.
status The various enter and exit times for a given job state.
userdata An object of arbitrary key/value data supplied to the job.
For example:
{
  "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234",
  "name" : "1234",
  "command" : "deploy",
  "type": "deploy",
  "state": "finished",
  "options" : {
    "concurrency" : null,
    "noop" : false,
    "trace" : false,
    "debug" : false,
    "scope" : {
      "application" : "Wordpress_app" },
    "enforce_environment" : true,
    "environment" : "production",
    "evaltrace" : false,
    "target" : null
  },
  "node_count" : 5,
  "owner" : {
    "email" : "admin@example.com",
    "is_revoked" : false,
    "last_login" : "2020-05-05T14:03:06.226Z",
    "is_remote" : true,
    "login" : "admin",
    "inherited_role_ids" : [ 2 ],
    "group_ids" : [ "9a588fd8-3daa-4fc2-a396-bf88945def1e" ],
    "is_superuser" : false,
    "id" : "751a8f7e-b53a-4ccd-9f4f-e93db6aa38ec",
    "role_ids" : [ 1 ],
    "display_name" : "Admin",
    "is_group" : false
  },
  "description" : "deploy the web app",
  "timestamp": "2016-05-20T16:45:31Z",
  "started_timestamp": "2016-05-20T16:41:15Z",
  "finished_timestamp": "2016-05-20T16:45:31Z",
  "duration": "256.0",
  "environment" : {
    "name" : "production"
  },
  "status" : [ {
    "state" : "new",
    "enter_time" : "2016-04-11T18:44:31Z",
    "exit_time" : "2016-04-11T18:44:31Z"
  }, {
    "state" : "ready",
    "enter_time" : "2016-04-11T18:44:31Z",
    "exit_time" : "2016-04-11T18:44:31Z"
  }, {
    "state" : "running",
    "enter_time" : "2016-04-11T18:44:31Z",
    "exit_time" : "2016-04-11T18:45:31Z"
  }, {
    "state" : "finished",
    "enter_time" : "2016-04-11T18:45:31Z",
    "exit_time" : null
  } ],
  "nodes" : { "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234/nodes" },
  "report" : { "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234/report" },
  "userdata": {}
}Copied!

Error responses

For this endpoint, the kind key of the error displays the conflict.

Key Definition
puppetlabs.orchestrator/validation-error If the job-id in the request is not an integer, the server returns a 400 response.
puppetlabs.orchestrator/unknown-job If the job does not exist, the server returns a 404 response.

GET /jobs/:job-id/nodes

List all of the nodes associated with a given job.

Request format

The request accepts the following optional query parameters:
Key Definition
limit Returns only the most recent n number of node results in a job.
offset Returns results offset n records into the result set.
order_by Returns results ordered by a column. Ordering is available on name, duration, state, start_timestamp, and finish_timestamp.
order Indicates whether results should be returned in ascending (asc) or descending (desc) order. Defaults to asc.
state Returns only the nodes in the state supplied. One of either new, ready, running, stopping, stopped, finished, or failed,

Response format

The response is a JSON object that details the nodes associated with a job.

next-events is an object containing information about where to find events about the job. It has the following keys:

Key Definition
id The url of the next event.
event

The next event id.

items: a list of all the nodes associated with the job, where each node has the following keys:

Key Definition
timestamp (deprecated) The time of the most recent activity on the node. Prefer start_timestamp and finish_timestamp.
start_timestamp

The time the node starting running or nil if the node hasn't started running or was skipped.
finish_timestamp

The time the node finished running or nil if the node hasn't finished running or was skipped.
duration The duration of the puppet run in seconds if the node has finished running, the duration in seconds that has passed after the node started running if it is currently running, or nil if the node hasn't started running or was skipped
state The current state of the job.
transaction_uuid (deprecated) The ID used to identify the nodes last report.
name The hostname of the node.
details information about the last event and state of a given node.
result The result of a successful, failed, errored node-run. The schema of this varies.

For example:

{
  "next-events": {
    "id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/3/events?start=10",
    "event": "10"
  },
  "items" : [ {
    "timestamp" : "2015-07-13T20:37:01Z",
    "start_timestamp" : "2015-07-13T20:36:13Z",
    "finish_timestamp" : "2015-07-13T20:37:01Z",
    "duration" : 48.0,
    "state" : "state",
    "transaction_uuid" : :uuid,
    "name" : "wss6c3w9wngpycg.example.com",
    "details" : {
      "message": "Message of latest event"
    },
    "result": {
      "output_1": "success",
      "output_2": [1, 1, 2, 3,]
    }
  },{
  ...
  } ]
}Copied!

Results

The result field is available after a node finishes, fails, or errors and contains the contents of the details of the corresponding event. In task jobs this is the result of executing the task. For puppet jobs it contains metrics from the puppet run.

For example:

An error when running a task:

"result" : {
  "msg" : "Running tasks is not supported for agents older than version 5.1.0",
  "kind" : "puppetlabs.orchestrator/execution-failure",
  "details" : {
    "node" : "copper-6"
   }
}Copied!

Raw stdout from a task:

"result" : {
  "output" : "test\n"
}
Copied!

Structured output from a task:

"result" : {
  "status" : "up to date",
  "version" : "5.0.0.201.g879fc5a-1.el7"
}Copied!

Error output from a task:

"result" : {
  "error" : "Invalid task name 'package::status'"
}
Copied!

Puppet run results:

"result" : {
  "hash" : "d7ec44e176bb4b2e8a816157ebbae23b065b68cc",
  "noop" : {
    "noop" : false,
    "no_noop" : false
  },
  "status" : "unchanged",
  "metrics" : {
    "corrective_change" : 0,
    "out_of_sync" : 0,
    "restarted" : 0,
    "skipped" : 0,
    "total" : 347,
    "changed" : 0,
    "scheduled" : 0,
    "failed_to_restart" : 0,
    "failed" : 0
  },
  "environment" : "production",
  "configuration_version" : "1502024081"
}Copied!
Using puppet apply as part of a plan results:
"result" : {
  "noop": false,
  "status" : "unchanged",
  "metrics" : {
    "corrective_change" : 0,
    "out_of_sync" : 0,
    "restarted" : 0,
    "skipped" : 0,
    "total" : 347,
    "changed" : 0,
    "scheduled" : 0,
    "failed_to_restart" : 0,
    "failed" : 0
  }
}Copied!

Details

The details field contains information based on the last event and current state of the node and can be empty. In some cases it can duplicate data from the results key for historical reasons.

If the node state is finished or failed the details hash can include a message and a report-url. (deprecated) for jobs started with the run command it also duplicates some information from the result.

{
  "items" : [ {
    "timestamp" : "2015-07-13T20:37:01Z",
    "state" : "finished",
    "transaction_uuid" : :uuid,
    "name" : "wss6c3w9wngpycg.example.com",
    "details" : {
      "report-url" : "https://peconsole.example.com/#/cm/report/a15bf509dd7c40705e4e1c24d0935e2e8a1591df",
      "message": "Finished puppet run on wss6c3w9wngpycg.example.com - Success!"
    }
    "result" : {
      "metrics" : {
        "total" : 82,
        "failed" : 0,
        "changed" : 51,
        "skipped" : 0,
        "restarted" : 2,
        "scheduled" : 0,
        "out_of_sync" : 51,
        "failed_to_restart" : 0
      },
  },{
  ...
  } ]
}Copied!

If the node state is skipped or errored, the service includes a :detail key that explains why a node is in that state.

{
  "items" : [ {
    "timestamp" : "2015-07-13T20:37:01Z",
    "state" : "failed",
    "transaction_uuid" : :uuid,
    "name" : "wss6c3w9wngpycg.example.com",
    "details" : {
      "message": "Error running puppet on wss6c3w9wngpycg.example.com: java.net.Exception: Something went wrong"
    }
  },{
  ...
  } ]
}Copied!

If the node state is running, the service returns the run-time (in seconds).

{
  "items" : [ {
    "timestamp" : "2015-07-13T20:37:01Z",
    "state" : "running",
    "transaction_uuid" : :uuid,
    "name" : "wss6c3w9wngpycg.example.com",
    "details" : {
      "run-time": 30,
      "message": "Started puppet run on wss6c3w9wngpycg.example.com..."
    }
  },{
  ...
  } ]
}Copied!

Error responses

For this endpoint, the kind key of the error displays the conflict.

Key Definition
puppetlabs.orchestrator/validation-error If the job-id in the request is not an integer, the server returns a 400 response.
puppetlabs.orchestrator/unknown-job If the job does not exist, the server returns a 404 response.

GET /jobs/:job-id/report

Returns a report for a given job.

Response format

The response is a JSON object that reports the status of a job, and uses these keys:

Key Definition
items An array of all the reports associated with a given job.
node The hostname of a node.
state The current state of the job.
timestamp The time when the job was created.
events Any events associated with that node during the job.

For example:

{
  "items" : [ {
    "node" : "wss6c3w9wngpycg.example.com",
    "state" : "running",
    "timestamp" : "2015-07-13T20:37:01Z",
    "events" : [ ]
  }, {
  ...
  } ]
}Copied!

Error responses

For this endpoint, the kind key of the error displays the conflict.

Key Definition
puppetlabs.orchestrator/validation-error If the job-id in the request is not an integer, the server returns a 400 response.
hpuppetlabs.orchestrator/unknown-job If the job does not exist, the server returns a 404 response.