Plan jobs endpoints

Use the /plan_jobs endpoint to view details about plan jobs you have run.

GET /plan_jobs

List the known plan jobs sorted by name and in descending order.

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. One of either owner, timestamp, environment, name, or state. Orderings requesting owner are applied to the login subfield of owner.
order Indicates whether results are returned in ascending or descending order. One of either asc or desc. Defaults to asc.
results Whether to include or exclude the plan output for each plan in the list. The default is include.
min_finish_timestamp Returns only the jobs given at or after a given UTC timestamp.
max_finish_timestamp Returns only the jobs given at or before a given UTC timestamp.

Response format

The response is a JSON object that contains a list of the known plan jobs, and information about the pagination.

Key Definition
items An array of all the plan jobs.
id An absolute URL to the given plan job.
name The ID of the plan job.
state The current state of the plan job: running,success, or failure
options Information about the plan job: description, plan_name, parameters, scheduled_job_id,and environment.
description The user-provided description for the plan job.
plan_name The name of the plan that was run, for example package::install.
parameters The parameters passed to the plan for the job.
scheduled_job_id The scheduled_job_id if the plan was run as a scheduled job.
environment The environment the plan was run in.
result The output from the plan job.
owner The subject ID and login for the user that requested the job.
timestamp The time when the plan job last changed.
created_timestamp The time the plan job was created.
finished_timestamp The time the plan job finished.
duration The number of seconds the plan job has been running, or total duration of the plan run.
events A link to the events for a given plan job.
status A hash of jobs that ran as part of the plan job, with associated lists of states and their enter and exit times.
userdata An object of arbitrary key/value data supplied to the job.
pagination Contains the 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 (zero based).
total The total number of items in the collection, ignoring limit and offset.

For example:

{ "items": [ { "finished_timestamp": "2020-09-23T18:00:13Z", "name": "38", "events": { "id": "https://orchestrator.example.com:8143:8143/orchestrator/v1/plan_jobs/38/events" }, "state": "success", "result": [ "orchestrator.example.com: CentOS 7.2.1511 (RedHat)" ], "id": "https://orchestrator.example.com:8143:8143/orchestrator/v1/plan_jobs/38", "created_timestamp": "2020-09-23T18:00:08Z", "duration": 123.456, "options": { "description": "just the facts", "plan_name": "facts::info", "parameters": { "targets": "orchestrator.example.com" }, "sensitive": [], "scheduled_job_id": "116", "project" : { "project_id": "myproject_id", "ref": "524df30f58002d30a3549c52c34a1cce29da2981" } }, "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 }, "userdata": { "servicenow_ticket": "INC0011211" } }, { "finished_timestamp": null, "name": "37", "events": { "id": "https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/37/events" }, "state": "running", "id": "https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/37", "created_timestamp": "2018-06-06T20:22:08Z", "duration": 123.456, "options": { "description": "Testing myplan", "plan_name": "myplan", "parameters": { "nodes": [ "orchestrator.example.com" ] }, "sensitive": ["secret"], "environment": "production", "scheduled_job_id": "5" }, "owner": { "email": "", "is_revoked": false, "last_login": "2018-06-06T20:22:06.327Z", "is_remote": false, "login": "admin", "is_superuser": true, "id": "42bf351c-f9ec-40af-84ad-e976fec7f4bd", "role_ids": [ 1 ], "display_name": "Administrator", "is_group": false }, "result": null, "userdata": {} }, { "finished_timestamp": null, "name": "36", "events": { "id": "https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/36/events" }, "state": "running", "id": "https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/36", "created_timestamp": "2018-06-06T20:22:08Z", "duration": 123.456, "options": { "description": "Testing myplan", "plan_name": "myplan", "parameters": { "nodes": [ "orchestrator.example.com" ] }, "sensitive": [], "environment": "production", "scheduled_job_id": null }, "owner": { "email": "", "is_revoked": false, "last_login": "2018-06-06T20:22:06.327Z", "is_remote": false, "login": "admin", "is_superuser": true, "id": "42bf351c-f9ec-40af-84ad-e976fec7f4bd", "role_ids": [ 1 ], "display_name": "Administrator", "is_group": false }, "result": null, "userdata": {} }, { "finished_timestamp": null, "name": "35", "events": { "id": "https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/35/events" }, "state": "running", "id": "https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/35", "created_timestamp": "2018-06-06T20:22:07Z", "duration": 123.456, "options": { "description": "Testing myplan", "plan_name": "myplan", "parameters": { "nodes": [ "orchestrator.example.com" ] }, "sensitive": [], "environment": "dev", "scheduled_job_id": null }, "owner": { "email": "", "is_revoked": false, "last_login": "2018-06-06T20:22:06.327Z", "is_remote": false, "login": "admin", "is_superuser": true, "id": "42bf351c-f9ec-40af-84ad-e976fec7f4bd", "role_ids": [ 1 ], "display_name": "Administrator", "is_group": false }, "result": null, "userdata": {} }, { "finished_timestamp": null, "name": "34", "events": { "id": "https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/34/events" }, "state": "running", "id": "https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/34", "created_timestamp": "2018-06-06T20:22:07Z", "duration": 123.456, "options": { "description": "Testing myplan", "plan_name": "myplan", "parameters": { "nodes": [ "orchestrator.example.com" ] }, "sensitive": [], "environment": "production", "scheduled_job_id": null }, "owner": { "email": "", "is_revoked": false, "last_login": "2018-06-06T20:22:06.327Z", "is_remote": false, "login": "admin", "is_superuser": true, "id": "42bf351c-f9ec-40af-84ad-e976fec7f4bd", "role_ids": [ 1 ], "display_name": "Administrator", "is_group": false }, "result": null, "userdata": {} }, { "finished_timestamp": null, "name": "33", "events": { "id": "https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/33/events" }, "state": "running", "id": "https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/33", "created_timestamp": "2018-06-06T20:22:07Z", "duration": 123.456, "options": { "description": "Testing myplan", "plan_name": "myplan", "parameters": { "nodes": [ "orchestrator.example.com" ] }, "sensitive": [], "environment": "production", "scheduled_job_id": null }, "owner": { "email": "", "is_revoked": false, "last_login": "2018-06-06T20:22:06.327Z", "is_remote": false, "login": "admin", "is_superuser": true, "id": "42bf351c-f9ec-40af-84ad-e976fec7f4bd", "role_ids": [ 1 ], "display_name": "Administrator", "is_group": false }, "result": null, "userdata": {} } ], "pagination": { "limit": 6, "offset": 3, "total": 40 } }

GET /plan_jobs/:job-id

List all the details of a given plan job.

Response format

The response is a JSON object that lists all details of a given plan job. The following keys are used:

Key Defintion
id An absolute URL to the given plan job.
name The ID of the plan job.
state The current state of the plan job: running,success, or failure
options Information about the plan job: description, plan_name, and any parameters.
description The user-provided description for the plan job.
plan_name The name of the plan that was run, for example package::install.
parameters The parameters passed to the plan for the job.
result The output from the plan job.
owner The subject ID and login for the user that requested the job.
timestamp The time when the plan job state last changed.
created_timestamp The time the plan job was created.
finished_timestamp The time the plan job finished.
events A link to the events for a given plan job.
status A hash of jobs that ran as part of the plan job, with associated lists of states and their enter and exit times.
userdata An object of arbitrary key/value data supplied to the job.

For example:

{ "id": "https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/1234", "name": "1234", "state": "success", "options": { "description": "This is a plan run", "plan_name": "package::install", "parameters": { "foo": "bar" } }, "result": { "output": "test\n" }, "owner": { "email": "", "is_revoked": false, "last_login": "YYYY-MM-DDT17:06:48.170Z", "is_remote": false, "login": "admin", "is_superuser": true, "id": "42bf351c-f9ec-40af-84ad-e976fec7f4bd", "role_ids": [ 1 ], "display_name": "Administrator", "is_group": false }, "timestamp": "YYYY-MM-DDT16:45:31Z", "status": { "1": [ { "state": "running", "enter_time": "YYYY-MM-DDT18:44:31Z", "exit_time": "YYYY-MM-DDT18:45:31Z" }, { "state": "finished", "enter_time": "YYYY-MM-DDT18:45:31Z", "exit_time": null } ], "2": [ { "state": "running", "enter_time": "YYYY-MM-DDT18:44:31Z", "exit_time": "YYYY-MM-DDT18:45:31Z" }, { "state": "failed", "enter_time": "YYYY-MM-DDT18:45:31Z", "exit_time": null } ] }, "events": { "id": "https://localhost:8143/orchestrator/v1/plan_jobs/1234/events" }, "userdata": {} }

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 plan job does not exist, the server returns a 404 response.