Jobs¶
A job applies one tested change to many sites as a single controlled operation. It is an ordered list of steps that the Hub works through at each site in a fixed list of sites: for example, import a configuration file, restart the channels it changed, and check that they run. A job is prepared, approved and run from the Hub console, and each site reports its own result.
How a Job Works¶
A person whose role holds the Jobs grant at the target sites prepares the job as a draft. The draft holds the configuration file to import, the steps, the tags whose sites it reaches, and two limits: how many sites may work through their steps at once, and how many failed sites stop it. A job reaches only the sites where its preparer holds the Jobs grant: when it is submitted, a site that carries a chosen tag but where the preparer does not hold the grant is left out of it.
A job reaches sites through tags, never through single sites. The one exception is a rerun, which reaches the sites the job it reruns did not run (see Copying and Rerunning a Job).
Submitting the draft checks it and fixes its site list. A job that reaches more sites than the Hub's approval threshold then waits for a second person to approve it. Once it is ready, its preparer or approver starts it.
The Hub then moves each site through the steps, a few sites at a time. Every step at every site is sent as its own signed statement: a short-lived message, signed by the Hub, that allows one action at one site. It names the person who prepared the job, and the person who approved it when there is one. The site checks the statement and runs the step as the preparer's Hub user, with the role its own Role Map gives the preparer's Hub role. Waits and checkpoints are kept at the Hub and are never sent to a site.
When a site fails a step, that site stops and the Hub records why. Once the number of failed sites reaches the job's failure limit, no new site starts. A site the job's import was sent to can be rolled back from the job's details once its part has ended.
The Life of a Job¶
| State | Meaning |
|---|---|
| Draft | Being prepared; only its preparer sees and edits it |
| Awaiting approval | Submitted, reaching more sites than the approval threshold, and waiting for a second person |
| Ready to start | Submitted and approved, or needing no approval |
| Running | The Hub is moving its sites through their steps |
| Paused | No site starts a new step until it is resumed |
| Finished | Every site has ended |
| Stopped | A person stopped it, or its preparer or approver was disabled or deleted at the Hub |
| Halted | Failed sites reached the failure limit, and every site has since ended |
| Rejected | The approver rejected it; a rejected job never runs |
A submitted job is never edited. To change one, withdraw it to a draft before it starts, or copy it into a new draft.
What a Site Needs¶
A site takes part in a job only when all of these are true:
- The site runs a QIE version that runs job steps, and has reported its Hub settings to the Hub. A site reports them when its tunnel connects, and again while the tunnel is up whenever they change.
- Use Hub is on, on the Hub Sign-In tab of the site's Remote Management Hub dialog in System Configuration, and the site's Role Map maps the preparer's Hub role to a role at the site. See the site's Hub sign-in settings.
- The preparer, and the approver when there is one, hold the Jobs grant for the site at the Hub. Grants are given to roles, for tags, in the Site Access section of the role on the Manage Roles page, and a Hub administrator needs the grant through their role too. See Site Access Grants and Tags.
- When a step starts channels, the site does not have a developer license.
Submitting leaves out every site where the preparer does not hold the Jobs grant. A site that fails one of these when the job reaches it, a grant lost since the job was submitted included, is skipped and reported as not run; see Job Site Outcomes.
Within those limits, the site applies its own permissions. An import needs edit rights in each zone it writes, and creating a zone needs an administrator role at the site. Steps that change channels need the manage right in the channel's zone. Nothing a job's steps do themselves can change the site's users, roles or other administrator settings; a channel the job imports or starts still runs its own scripts, as any channel does.
Job Pages¶
- Jobs Page lists the jobs each person can see and who sees which ones.
- Preparing a Job covers the draft editor: the configuration file, the key password, the limits, the tags the job reaches and what stops a draft being submitted.
- Job Steps lists the step types and the step editor.
- Job Import Step describes the import, its options and what a site refuses before it writes anything.
- Job Channel Steps covers starting, stopping, pausing, resuming and restarting channels.
- Job Check Step describes the five checks.
- Job Waits and Checkpoints covers waiting for a time, until a clock time, and until someone continues.
- Job Approval covers submitting, the approval threshold, approving, rejecting and withdrawing.
- Running a Job covers starting, pausing, continuing and stopping, and how the Hub paces sites.
- Job Site Outcomes explains each site's status and how its part ended.
- Job Details describes the dialog that shows a job's sites, results and actions.
- Rolling Back a Job Site describes undoing an import at one site.
- Copying and Rerunning a Job covers new drafts made from a submitted job.
- Job Retention covers how long the Hub keeps files, records and statements.
- What a Site Records for a Job describes the site's own record of each step.
AI assistants signed in at the Hub can also list, prepare, submit, start, pause, resume, continue, stop and rerun jobs as the person; approving and rolling back stay in the console. Working on a job this way needs the MCP grant as well as the Jobs grant. See the Hub's MCP server.