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:

"interval": {
      "units": "seconds",
      "value": 86400
    }

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:

"parameters": {
      "param_one": "some_value"
    }

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:

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: