Skip to content

Job Tools on a Hub

The Hub's MCP server offers tools to prepare and run jobs, so an AI assistant can take a tested change to many sites (see Jobs). The tools act as the person, through the same job service as the Jobs page. That service decides who may take each action, and its refusal comes back as operation_refused with the service's reason. Each tool answers with the job, or for list_jobs the jobs, as the person sees them on the Jobs page.

These tools run at the Hub. They take no site, and send nothing to a site themselves: the Hub sends the steps to the sites once the job runs.

The Grants They Need

Working on a job through an AI assistant needs the MCP grant as well as the Jobs grant (see Site Access Grants). The job service checks the Jobs grant, as it does for the Jobs page. The tools check MCP:

  • Every tool except list_jobs and create_job refuses a job unless the person's role holds MCP at every site the job reaches. The refusal is permission_denied: "Working on a job through an AI assistant needs the MCP grant, as well as the Jobs grant, at every site the job reaches, and your role does not hold MCP at all of them. Use the Jobs page at the Hub's console instead."
  • list_jobs leaves out every job that reaches a site where the person's role does not hold MCP.
  • create_job needs MCP at one or more sites. Otherwise it is refused with permission_denied and the same text as the note that list_sites gives (see Finding a Site).

A Hub administrator holds MCP and Jobs only through their role, like anyone else.

The Tools

Tool Access needed Does
list_jobs Read only Lists one page of the jobs the person sees, most recently changed first: each one's id, name, state and number of sites, who prepared and approved it, and whether the person may approve it at the console (see Listing Jobs). A job is listed only when the person's role holds MCP at every site it reaches
get_job Read only Reads one job as the person sees it: its steps, sites and limits, each site's progress, results, warnings and rollback, a draft's problems, and the actions the person may take now
create_job Full Prepares a draft from a configuration file's content (see Creating a Job)
submit_job Full Submits the person's draft. It then waits for approval at the console, or is ready to start when it needs none
start_job Full Starts a ready job the person prepared or approved, after the person confirms it
pause_job Manage Pauses a running job; sites running a step finish it first
resume_job Manage Resumes a paused job
continue_job Manage Lets every site waiting at the job's next checkpoint go on
stop_job Full Stops a job awaiting approval, ready or running, after the person confirms it. No new site begins, and a site working through its steps goes on to its next wait or checkpoint, or the end of its list; see Running a Job
rerun_job Full Makes a new draft of an ended job for the sites it did not run. Only someone who sees the whole job may

Every tool except list_jobs and create_job takes the job's id as jobId. The access is the one the person chose when they approved their AI assistant at the Hub.

Listing Jobs

list_jobs answers with one page of the jobs the person sees, most recently changed first, as the Jobs page lists them. Every argument is optional:

  • name: Part of the job's name.
  • state: One job state: DRAFT, AWAITING_APPROVAL, READY, RUNNING, PAUSED, FINISHED, STOPPED, HALTED or REJECTED.
  • showCompleted: true to include ended jobs, which are left out otherwise.
  • preparer: Part of the preparer's user id.
  • offset: Where the page starts in the list, 0 when it is not sent.
  • limit: How many jobs the page holds: 100 when it is not sent, and never more than 500.

The answer holds the page's jobs, its offset, and total, the number of jobs that match. A job that reaches a site where the person's role does not hold MCP is left out of the page but still counted in total, so a page can hold fewer jobs than its limit. To read the next page, ask again with offset moved on by limit.

Creating a Job

create_job prepares a draft, with the person as its preparer, from these arguments:

  • name: The job's name. Required.
  • exportFile: The configuration file's content in base64, as export_configuration returns it. Required.
  • fileName: The file's name, export.qie when it is not sent.
  • keyPassword: The password of the private keys in the file, when it holds any.
  • steps: The steps, in order. Required. Each step is an object with its type and only the fields that type uses, as the next list shows.
  • tags: The tags whose sites the job reaches, by name, matched ignoring case. A job reaches sites only through tags; it takes no single sites. A name no tag has is refused with not_found: "No tag is named '...' at this Hub."
  • inProgressLimit: How many sites may be in progress at once.
  • failureLimit: How many failed sites stop the job.

A draft cannot be submitted until each limit is 1 or more.

The step types and their fields:

  • IMPORT: importOptions, the import's options: overwriteEndpoints, importSampleMessages, overwriteConnAndVarNames, overwriteEditablePackageComponents, updateChannelCacheOnly, overrideExistingChannelCacheValues, skipKeysWithInvalidPasswords and zoneOverrides, a list of {sourceZone, destZone, createZone}. An option left out is off, except importSampleMessages and overwriteConnAndVarNames, which are on, as on the console's Import Configuration dialog. See Job Import Step.
  • START, STOP, PAUSE, RESUME and RESTART: channels, a list of {zone, channel}.
  • CHECK: channels, checks (any of RUNNING, VERSION, NOT_ERRORED_SINCE, ERROR_QUEUE_NOT_LARGER and RECEIVED_SINCE) and sinceStep.
  • WAIT: seconds.
  • WAIT_UNTIL: time, as HH:mm in each site's own time zone.
  • CHECKPOINT: No fields.

The answer is the new draft, including what still stops it being submitted. Jobs describes what each step does and what a draft needs.

A create_job call may be as large as the Hub's Package Ceiling (bytes) plus 1 MB, like the package tools (see MCP Listener). The configuration file passes through the AI assistant and its provider on its way to the Hub, as a package does when configuration is promoted between engines (see Promote Configuration).

Starting and Stopping

start_job and stop_job ask the person to confirm in their AI assistant before they act, as a site's irreversible tools do (see Confirmations). The question names the action and the job. If the job changes before the person answers, nothing is done and the call returns target_changed.

The Hub's MCP page does not show Require client confirmation. While the stored setting is on, which is the default, an assistant that cannot ask the person cannot start or stop a job. Each question and answer is recorded in the Hub's MCP audit log.

What Stays at the Console

No tool approves, rejects or withdraws a job, copies one to a draft, deletes a draft, rolls a site back or edits a draft. Those stay with people on the Jobs page (see Jobs).

A draft made by rerun_job has no key password. When the draft needs one, finish it on the Jobs page by entering the key password.