Scheduled jobs endpoints

Use the scheduled_jobs endpoints to query, edit, and delete scheduled orchestrator jobs.

You can:
Tip: An environment job is a deployment, task, or plan that runs in a specific environment, such as your production environment.

GET /scheduled_jobs/environment_jobs

Retrieve information about scheduled environment jobs, which are deployments, tasks, or plans that run in a specific environment. Use parameters to narrow the response scope.

Request format

When Forming orchestrator API requests to this endpoint, you can append optional parameters to the end of the URI path, such as:
https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/environment_jobs?limit=50&type=task
These parameters are available:
Parameter Definition
limit Set the maximum number of scheduled jobs to include in the response. The point at which the limit count starts is determined by offset, and the job record sort order is determined by order_by and order.
offset Specify a zero-indexed integer at which to start returning results. For example, if you set this to 12, the response returns scheduled jobs starting with the 13th record. The default is 0.
order_by Specify one of the following categories to use to sort the results: next_run_time, environment, owner, name, or type. The default is next_run_time.
order Indicate whether results are returned in ascending (asc) or descending (desc) order. The default is asc.
type Specify a job type to query, either deploy, task, or plan.

Response format

The response is a JSON object containing an items array and a pagination object.

The items array contains a JSON object for each scheduled job. Each object can use these keys to provide job details:
Key Definition
id The job's absolute URL, which includes the job's numerical ID.
name The job's numerical ID as a stringified number.
enabled A Boolean indicating whether the job is enabled.
environment The environment that the job operates in.
owner The subject ID, email, and other details of the user that requested the job.
description A user-provided description of the job. This can be empty.
type The job's type, either plan, task, or deploy.
input An object describing options supplied to the job, including:
  • name: String-formatted project name of the task or plan.
  • parameters: An object containing key-value pairs of non-sensitive parameters and values supplied to the job.
  • sensitive_parameters: An array of names of sensitive parameters supplied to the job.
userdata An object containing arbitrary key-value pairs supplied by the initiating user, if any were supplied.
schedule An object describing the job's schedule, including:
  • start_time: An ISO-8601 timestamp indicating the first time the job ran (or will run).
  • interval: An object representing the frequency at which the job runs, such as every 1300 seconds.
next_run An object containing an ISO-8601 timestamp indicating the scheduled job's next run time.
last_run If the job has not yet run, this is null. If the job has run, this is an object containing an ISO-8601 timestamp of the scheduled job's most recent run time and a job object.

The job object can contains the submitted job's id or name if the job succeeded. If the job failed, it contains a submission_errorobject describing why the job failed.
The pagination object includes these keys:
  • total: The total number of job records in the collection, regardless of limit and offset.
  • limit, offset, order_by, order, and type: Reflects values supplied in the request. If you specified a value, these key shows the value you specified. If you did not specify a value, the key shows the default value, if there is one.
This sample response describes two scheduled jobs and the pagination information:
{
  "items": [
    {
      "id": "https://host.example.com:8143/orchestrator/v1/scheduled_jobs/environment_jobs/2",
      "name": "2",
      "environment":  "plan_testing_env",
      "owner": {
        "email": "fred@example.com",
        "login": "fred",
        "display_name": "Fred",
        "id": "784beba4-8cc8-414f-aab0-e9a29c9b65c2",
        "is_revoked": false,
        "last_login": "2020-05-08T15:57:28.444Z",
        "is_remote": true,
        "is_group": false,
        "is_superuser": false,
        "role_ids": [
          1
        ],
        "inherited_role_ids": [
          2
        ],
        "group_ids": [
          "9a588fd8-3daa-4fc2-a396-bf88945def1e"
        ]
      },
      "description": "Fred's scheduled environment plan",
      "type": "plan",
      "next_run": {
        "time": "2021-12-12T19:50:08Z"
      },
      "last_run": {
        "time": "2021-11-12T19:50:08Z",
        "job": {
          "id": "https://host.example.com:8143/orchestrator/v1/plan_jobs/42",
          "name": 42
        }
      },
      "schedule": {
        "start_time": "2018-10-05T19:50:08Z",
        "interval": {
          "value": 3600,
          "units": "seconds"
        }
      },
      "input": {
        "name": "plan_testing_env::example_plan",
        "parameters": {
          "param_1": "foo"
        },
        "sensitive_parameters" : ["password"]
      },
      "userdata": {
        "ticket": "TICKET-123"
      }
    },
    {
      "id": "https://host.example.com:8143/orchestrator/v1/scheduled_jobs/environment_jobs/1",
      "name": "1",
      "environment": "plan_testing_env",
      "owner": {
        "email": "user@example.com",
        "login": "user",
        "display_name": "User",
        "id": "06990bb9-df3a-4150-964f-88b9cf0f8eec",
        "last_login": "2019-07-08T15:57:28.444Z",
        "is_revoked": false,
        "is_remote": true,
        "is_group": false,
        "is_superuser": false,
        "role_ids": [
          1
        ],
        "inherited_role_ids": [
          2
        ],
        "group_ids": [
          "9a588fd8-3daa-4fc2-a396-bf88945def1e"
        ]
      },
      "description": "",
      "type": "plan",
      "schedule": {
        "start_time": "2018-10-05T19:50:08Z",
        "interval": null
      },
      "input": {
        "name": "plan_testing_env::example_plan",
        "parameters": {
          "param_1": "foo"
        },
        "sensitive_parameters" : []
      },
      "userdata": {
        "approval_reference": "442"
      },
      "start_time": "2020-10-05T19:50:08Z",
      "next_run": {
        "time": "2021-12-12T19:50:08Z"
      },
      "last_run": {
        "time": "2021-11-12T19:50:08Z",
        "job": {
          "submission_error": {
              "kind" : "puppetlabs.orchestrator/unknown-environment",
              "msg" : "Unknown environment doesnotexist",
              "details" : {
                "environment" : "doesnotexist"
            }
          },
          "name": 33
        }
      }
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "order": "asc",
    "order_by": "next_run_time",
    "total": 2,
  }
}

Error responses

This endpoint's error responses follow the usual format for Orchestrator API error responses.

The endpoint returns a 400 puppetlabs.orchestrator/query-error response if you don't have permission to run queries or there is a problem with a supplied parameter, such as the limit or offset parameters not being formatted as integers.

GET /scheduled_jobs/environment_jobs/<job-id>

Retrieve information about a specific scheduled environment job, which is deployment, task, or plan that runs in a specific environment.

Request format

When Forming orchestrator API requests to this endpoint, the URI path must include the ID of the scheduled job you want to query. For example, this request queries a scheduled job with ID 81:
https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/environment_jobs/81
You can use the GET /scheduled_jobs/environment_jobs endpoint to get scheduled job IDs.

Response format

The response is a JSON object that uses these keys to provide the scheduled job's details:
Key Definition
id The job's absolute URL.
name A stringified number identifying the job.
enabled A Boolean indicating whether the job is enabled.
environment The environment that the job operates in.
owner The subject ID, email, and other details of the user that requested the job.
description A user-provided description of the job. This can be empty.
type The job's type, such as plan, task, or deploy.
input An object describing options supplied to the job, including:
  • name: String-formatted project name of the task or plan.
  • parameters: An object containing key-value pairs of non-sensitive parameters and values supplied to the job.
  • sensitive_parameters: An array of names of sensitive parameters supplied to the job.
userdata An object containing arbitrary key-value pairs supplied by the initiating user, if any were supplied.
schedule An object describing the job's schedule, including:
  • start_time: An ISO-8601 timestamp indicating the first time the job ran (or will run).
  • interval: An object representing the frequency at which the job runs, such as every 1300 seconds.
next_run An object containing an ISO-8601 timestamp indicating the scheduled job's next run time.
last_run If the job has not yet run, this is null. If the job has run, this is an object containing an ISO-8601 timestamp of the scheduled job's most recent run time and a job object.

The job object can contains the submitted job's id or name if the job succeeded. If the job failed, it contains a submission_errorobject describing why the job failed.
For example:
{
  "name": "https://host.example.com:8143/orchestrator/v1/scheduled_jobs/environment_jobs/2",
  "id": "2",
  "environment": "production",
  "owner": {
    "email": "fred@example.com",
    "login": "fred",
    "display_name": "Fred",
    "id": "784beba4-8cc8-414f-aab0-e9a29c9b65c2",
    "is_revoked": false,
    "last_login": "2020-05-08T15:57:28.444Z",
    "is_remote": true,
    "is_group": false,
    "is_superuser": false,
    "role_ids": [
      1
    ],
    "inherited_role_ids": [
      2
    ],
    "group_ids": [
      "9a588fd8-3daa-4fc2-a396-bf88945def1e"
    ]
  },
  "description": "Fred's scheduled environment plan",
  "type": "plan",
  "next_run": {
    "time": "2021-12-12T19:50:08Z"
  },
  "last_run": {
    "time": "2021-11-12T19:50:08Z",
    "job": {
      "id": "https://host.example.com:8143/orchestrator/v1/plan_jobs/42",
      "name": 42
    }
  },
  "schedule": {
    "start_time": "2018-10-05T19:50:08Z",
    "interval": {
      "value": 3600,
      "units": "seconds"
    }
  },
  "input": {
    "name": "example_module::example_plan",
    "parameters": {
      "param_1": "foo"
    },
    "sensitive_parameters" : ["password"]
  },
  "userdata": {
    "ticket": "TICKET-123"
  }
}

Error responses

This endpoint's error responses follow the usual format for Orchestrator API error responses.

The endpoint returns a 400 puppetlabs.orchestrator/query-error response if you don't have permission to run queries or the job ID is invalid.

POST /scheduled_jobs/environment_jobs

Create an environment job to run in the future. An environment job is a deployment, task, or plan that runs in a specific environment, such as a Puppet run on nodes in your production environment.

Request format

When Forming orchestrator API requests to this endpoint, the content type is application/json. The body must be a JSON object using these required keys:
Key Definition
type Enumerated value indicating the type of action you want to schedule, either plan, task, or deploy.
input An object describing job parameters, scope, or targets. The contents depends on the type, as described in the input object section, below.
environment A string specifying the name of the relevant environment.

For task and plan jobs, this is the environment from which to load the task or plan.

For deploy jobs, this can be an empty string or the name of the environment to deploy.
schedule An object that uses the start_time and interval keys to describe the job's schedule.

The start_time key accepts an ISO-8601 timestamp indicating the first time that you want the job to run.

The interval key accepts either an object or null. To only run the job once, use null. To schedule a recurring job, supply an object containing value and units. The units key is an enum that must be set to seconds. The value key is an integer representing the number of units to wait between job runs. For example:
"interval": {
      "units": "seconds",
      "value": 86400
    }
description A string describing the job. You can supply an empty string.
userdata An object containing arbitrary key-value pairs supplied to the job, such as a support ticket number. You can supply an empty object.
For example, this request schedules the facts plan to run once on the node called node1.example.com in an environment called my_environment:
type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/scheduled_jobs/environment_jobs"
data='
   {
     "description": "run facts plan once on node1 in my_environment",
     "input": {
       "name": "sensitive_params::scheduled_jobs_storage",
       "parameters": {
         "primary": {
           "value": "example.delivery.puppetlabs.net"
         },
         "param_one": {
           "value": "first_value"
         }
       }
     },
     "environment": "my_environment",
     "schedule": {
       "start_time": "2022-01-28T09:35:56-08:00",
       "interval": null
     },
     "userdata": {
         "snow_ticket": "INC0011211"
     },
     "type": "plan"
   }
'

curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

The input object

The contents of the input object depends on the job's type (either plan, deploy, or task). The keys you can use in the input object for each job type are described below. Not all keys are required, but the input object itself is a required key.

The input object for plan jobs can contain:
  • name: String-formatted name of the plan to run.
  • parameters:An object containing a series of key-value pairs representing parameter inputs for the plan to use. Parameters either specify standard parameter inputs or node targets.
Standard parameter inputs are represented as a parameter name key with the value in an object. The value key accepts any data type as long as it is valid JSON. For example:
"parameters": {
      "param_one": {
        "value": "some_value"
      }
    }
The plan's node targets can be declared in the targets object. You can declare specific nodes in the value key, much like a standard parameter input, or you can declare a variable group of nodes by supply a PuppetDB query. To do this, you must supply a targets object that contain your query statement in the value key and "type": "query". For example:
"parameters": {
      "targets": {
        "type": "query",
        "value": "nodes[certname] { }"
      }
    }
Supplying "type": "query" instructs the orchestrator to interpret the value as a PuppetDB query and pass the resulting node lists as the parameter's value.
Here is a complete example of an input object for a plan job:
"input": {
    "name": "sensitive_params::scheduled_jobs_storage",
    "parameters": {
      "primary": {
        "value": "convex-swath.delivery.puppetlabs.net"
      },
      "targets": {
        "type": "query",
        "value": "nodes[certname] { }"
      }
    }
  }
You can use these keys in the input object for task jobs:
Key Description
name String-formatted name of the task to run.
parameters An object that can be empty or contain key-value pairs representing standard parameter inputs for the task to use.
Supply parameter name keys along with their corresponding values in a flat structure. The value key accepts any data type as long as it is valid JSON. For example:
"parameters": {
      "param_one": "some_value"
    }
scope An object containing exactly one key defining the nodes that you want the task to target:
  • nodes: A list of node names to target.
  • query: A PuppetDB query to use to generate a list of targeted nodes.
  • node_group: The ID of a classifier node group containing nodes to target.
For scope examples, refer to the request body examples in POST /command/deploy. Note that application is not a valid scope for a scheduled job.
targets An object containing connection information for SSH/WinRM targets.
noop A Boolean specifying whether to run the task in no-op mode. The default is false.
concurrency An integer specifying the maximum number of nodes to run at one time. The default, if unspecified, is unlimited.
timeout A positive integer specifying the maximum number of seconds allowed for a task to execute on any one node. Task execution on the node is forcibly ended if the timeout limit is reached. If unspecified, this key takes the value of default-plan-timeout, which is one of the Orchestrator and pe-orchestration-services parameters.
transport A string indicating the transport method over which to run the task.
Here is an example of a complete input object for a task job:
"input": {
    "name": "my_task",
    "scope": { "nodes": ["my_primary"]},
  }
You can use these keys in the input object for deploy jobs:
Key Description
scope Required. An object containing exactly one key defining the nodes that you want the deployment to target:
  • nodes: A list of node names to target.
  • query: A PuppetDB query to use to generate a list of targeted nodes.
  • node_group: The ID of a classifier node group containing nodes to target.
For scope examples, refer to the request body examples in POST /command/deploy.
concurrency An integer specifying the maximum number of nodes to run at one time. The default, if unspecified, is unlimited.
debug A Boolean specifying whether to use the --debug flag on Puppet agent runs.
enforce_environment A Boolean specifying whether to force agents to run in the specified environment. This key must be false if environment is an empty string.
evaltrace A Boolean specifying whether to use the --evaltrace flag on Puppet agent runs.
filetimeout An integer specifying the value of the --filetimeout flag on Puppet agent runs.
http_connect_timeout An integer specifying the value for the --http_connect_timeout flag on Puppet agent runs.
http_keepalive_timeout An integer specifying the value for the --http_keepalive_timeout flag on Puppet agent runs.
http_read_timeout An integer specifying the value for the --http_read_timeout flag on Puppet agent runs.
noop A Boolean specifying whether to run the deployment in no-op mode. The default is false.
no_noop A Boolean specifying whether to run the agent in enforcement mode. The default is false. This key overrides noop = true if set in the agent's puppet.conf file. This key can't be set to true if the noop key is also set to true in the same request.
ordering A string defining the value of the --ordering flag on Puppet agent runs.
skip_tags A string defining the value of the --skip_tags flag on Puppet agent runs.
tags A string defining the value of the --tags flag on Puppet agent runs.
trace A Boolean specifying whether to use the --trace flag on Puppet agent runs.
use_cached_catalog A Boolean specifying whether to use the --use_cached_catalog flag on Puppet agent runs.
usecacheonfailure A Boolean specifying whether to use the --usecacheonfailure flag on Puppet agent runs.
Here is an example of an input object for a deploy job:
"input": {
    "scope": { "nodes": ["my_primary"]},
  }

Response format

If the job is successfully scheduled, the server returns 200 and a JSON object containing these keys:
  • id: An absolute URL that links to the newly created job. You can use it with GET /scheduled_jobs/environment_jobs/<job-id> to retrieve information about the job.
  • name: A stringified number identifying the newly created job.
For example:
{
  "scheduled_job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/environment_jobs/2",
    "name" : "2"
  }
}

Error responses

If there is an error, Orchestrator API error responses provide error information in the kind key. Possible errors include:
Response code Value Definition
404 puppetlabs.orchestrator/unknown-environment The specified environment does not exist.
400 puppetlabs.orchestrator/empty-environment The specified environment contains no nodes.
400 puppetlabs.orchestrator/empty-target The specified scope or targets query resolves to an empty list of nodes.
400 puppetlabs.orchestrator/puppetdb-error The request specified a query for the scope or targets, and the orchestrator is unable to make a query to PuppetDB.
400 puppetlabs.orchestrator/query-error The request specified a query for the scope or targets, and the query is invalid or the user submitting the request does not have permission to run the query.
400 puppetlabs.orchestrator/invalid-time The supplied start_time timestamp is in the past.

PUT /scheduled_jobs/environment_jobs/<job-id>

Edit or delete scheduled environment jobs.

Request format

When Forming orchestrator API requests to this endpoint, the content type is application/json, the URI path must contain the ID of the job you want to edit, and the body must be a JSON object. The body can contain any of these top-level keys: input, environment, schedule, description, userdata, and enabled. Top-level keys specified in your request completely overwrite existing values for those keys. Omitted top-level keys are unchanged.

CAUTION:

If you supply a top-level key, the supplied value completely replaces the key's existing value for the scheduled job.

If you want to add new content to an existing value, such as adding a parameter to the input object, you must supply the key's entire current value and your additional new content.

For descriptions of keys and their contents, refer to POST /scheduled_jobs/environment_jobs. Pay particular attention to the input object, which can have a lot of nested values.

To make sure you aren't missing any values, you can use GET /scheduled_jobs/environment_jobs/<job-id> to get the job's current configuration.

While you can't delete a scheduled job, you can disable the job as a form of soft deletion. To disable a job, supply the following body in your request:
{
  "enabled": false
}

Response format

If the job is successfully edited, the server returns 200 and a JSON object containing the edited job's id and name. For example:
{
  "scheduled_job" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/environment_jobs/2",
    "name" : "2"
  }
}

Error responses

If there is an error, Orchestrator API error responses provide error information in the kind key. Possible errors include errors described on POST /scheduled_jobs/environment_jobs and 400 puppetlabs.orchestrator/disabled-scheduled-job if you try to edit a disabled job (where "enabled": false).

GET /scheduled_jobs (deprecated)

Prior to deprecation, this endpoint retrieved information about scheduled jobs.

Important: This endpoint is deprecated. Instead, use GET /scheduled_jobs/environment_jobs and GET /scheduled_jobs/environment_jobs/<job-id>. Tools using this deprecated endpoint must be upgraded to use the new endpoints.
While you can manually re-enable this endpoint, this is not recommended because this endpoint only returns an empty array. If you need to re-enable this endpoint, insert the following code in orchestrator.conf:
{
  orchestrator: {
    scheduled-jobs-v1-api: true;
  }
}
This also re-enables DELETE /scheduled_jobs/<job-id> (deprecated).

Request format

Prior to deprecation, when Forming orchestrator API requests to this endpoint, you could append parameters to the end of the URI path, such as:
https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs?limit=20&type=task
This endpoint accepted the same parameters as GET /scheduled_jobs/environment_jobs.

Response format

Because this endpoint is deprecated, the response is always a JSON object containing an empty items array.
 {
    "items": [ ]
  }

DELETE /scheduled_jobs/<job-id> (deprecated)

Prior to deprecation, this endpoint deleted scheduled jobs.

Important: This endpoint is deprecated. Instead, use PUT /scheduled_jobs/environment_jobs/<job-id>. Tools using this deprecated endpoint must be upgraded to use the new endpoint.
While you can manually re-enable this endpoint, this is not recommended because this endpoint can't find jobs to delete. If you need to re-enable this endpoint, insert the following code in orchestrator.conf:
{
  orchestrator: {
    scheduled-jobs-v1-api: true;
  }
}
This also re-enables GET /scheduled_jobs (deprecated).

Request format

Prior to deprecation, when Forming orchestrator API requests to this endpoint, the URI path must have included the ID of the scheduled job you wanted to delete. For example, this request deleted a scheduled job with ID 81:
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/scheduled_jobs/81"

curl --insecure --header "$auth_header" -X DELETE "$uri"

Response format

Because this endpoint is deprecated, the response is always 204 No Content.