Thresholds and resources
- Synopsis
- Full Details
In briefA threshold is a named whole-number value that jobs can wait on; a resource is a named pool of units that jobs take while they run and give back when they finish. Jobs use both through their dependencies, so a threshold gates work on a count or a signal, and a resource caps how many jobs run against a shared system at once.
WhereDesign › Toolkit, on the Thresholds and Resources tabs. Each is created, edited and viewed in a dialog over its list. A resource's row menu also offers Current Allocations, which shows what holds its units in one environment right now and what is still available across every environment, and lets you release units an inactive or deleted environment still holds.
When
- Use a threshold to hold jobs until a value — set elsewhere — meets a condition.
- Use a resource to cap concurrency; use Use all on the dependency for a job that needs the whole resource to itself.
- To make one job wait on another job's outcome, use a job dependency instead.
How
- Open Toolkit, pick the Thresholds or Resources tab, and select New Threshold or New Resource.
- Give it a Name and a Value (a threshold) or a Total (a resource).
- Add a threshold or resource dependency to each job that should be gated by it. The full steps are in Use thresholds and resources.
- A job waiting on a threshold shows Waiting: Threshold Dependency; one waiting on a resource shows Waiting: Resource Dependency, and returns there if another job takes the last units first.
- A Force Start takes no units, so the job does not count against the resource while it runs.
- A resource's total is shared by every environment. Jobs in one environment can wait while another environment holds the units.
- Both are workspace-scoped; you see only those in workspaces your role can see. A workflow save checks that you can view each threshold or resource whose dependency it adds or changes.
- You cannot delete a threshold or resource that jobs still depend on; Cross Reference lists them so you can remove the dependencies first. A workflow last saved before this release may not be listed until it is saved again.
- Deleting a threshold or resource and creating another under its name does not move dependencies to the new one; their next save is refused until you restore it or re-pick.
- Lowering a resource's total while units are allocated can leave Available (all environments) negative until those jobs finish.
- Changing a threshold value or freeing units does not re-check waiting jobs at once; they move on a later pass.
Both are workspace-scoped. A new threshold or resource defaults to the General workspace.
Task walkthrough: Use thresholds and resources. This page is the full configuration and troubleshooting reference.
Thresholds and resources coordinate flow and capacity across jobs. Jobs reference them as dependencies.
- Thresholds
- Resources
- Current Allocations
- Managing Both in the Toolkit
- Troubleshooting
Thresholds
A threshold is a named numeric value used to gate jobs.
| Field | Notes |
|---|---|
| Name | Unique threshold name. 3–255 characters, following the platform naming rules. |
| Value | The current numeric value — a whole number, which can be negative. |
| Description | Optional. |
| Workspace | The workspace it belongs to. A new threshold defaults to General. |
A job with a threshold dependency waits until the threshold's current value satisfies the comparison the dependency sets — an operator and a value — a simple way to gate work on a count or a signal. See Threshold dependencies.
Resources
A resource is a named capacity pool that jobs reserve from and release back.
| Field | Notes |
|---|---|
| Name | Unique resource name. 3–255 characters, following the platform naming rules. |
| Total | Total capacity (a whole number, zero or more). |
| Description | Optional. |
| Workspace | The workspace it belongs to. A new resource defaults to General. |
A job with a resource dependency needs either a number of units of the resource or all of it — see Resource dependencies for the difference. Either way it gets them in two steps:
- The resource gate checks. While the job cannot have what it needs, it waits in Waiting: Resource Dependency. This step only looks — it reserves nothing.
- Dispatch takes the units, in a single step that both re-checks capacity and records the allocation, so two jobs dispatching at the same moment cannot both be told the last units are free.
A job refused its units at dispatch goes back to Waiting: Resource Dependency, naming the resources it could not get, rather than sitting in Wait to Start with nothing to explain it. That can happen legitimately: the gate reads one availability snapshot per sweep, so several jobs can pass it for the same last units, and only one of them gets them. The job is retried from the gate on the next sweep. A job that is late to start stays where it is — it has no route back into the waterfall, and its status already says it is late.
The units are released when the job completes, whatever kind of job it is: an agent job, a container job when its sub-workflow finishes, or a Null Job. Rebuilding a run with overwrite also releases the units its old jobs held. Each allocation is tracked per environment, workflow instance, and job.
Earlier builds did not release a container job's or a Null Job's units when it finished. The next job that needed the resource waited in Waiting: Resource Dependency for up to a minute, until the platform's periodic check freed them; after an overwrite rebuild, the old build's units could stay held for ten minutes or more.
One total for every environment
A resource is defined once, and its total is one pool that every environment draws on. The units jobs hold in all your environments together can never pass the total. So a job in one environment can wait in Waiting: Resource Dependency while jobs in another environment hold the units, even when nothing in its own environment is using the resource. A Use all dependency is met only when no environment holds any units.
Earlier builds counted only the units held in the job's own environment, so each environment could take the whole total, and two environments together could run twice as many jobs against the shared system as the total allows. Allocations made in several environments before this change can still add up to more than the total. New units are then refused until enough of them are released.
While a Use all job waits, the resource is reserved against jobs of the same or lower priority in every environment, so small jobs in another environment cannot keep it waiting for good. See A waiting Use All job reserves the resource. Earlier builds reserved it in the job's own environment only.
A Force Start skips the allocation: the job starts without taking any units, so it does not count against the resource's total while it runs.
Current Allocations
Seeing what holds a resource right now
The Resources tab's row menu offers Current Allocations — a view of who is holding the resource at this moment. Allocations are recorded per environment, so the view shows one environment at a time. It opens on the environment you are working in (or the first one listed), and the Environment list lets you pick another:
- It lists every environment, whatever its status. One that is not active is labelled with its status — (inactive), for instance.
- An environment that holds units of this resource says how many — · 3 in use.
- An environment that has been deleted but still holds units is listed as Deleted environment, followed by the start of its identifier.
For the chosen environment it reports:
| Part of the view | What it shows |
|---|---|
| Units in Use | Units allocated in the chosen environment, out of the resource's total, with the percentage used. The percentage is not shown while Available (all environments) is zero or less. |
| Available (all environments) | Total minus the units in use in every environment: what a job in any environment can take now. A negative number means more is allocated than the resource's total: a total that was lowered while allocations were live, or allocations made in several environments before the total applied to all of them. |
| The allocation table | One row per active allocation in the chosen environment: Job Name, Units, Allocated At, and the Workflow Instance holding it. |
Available can be lower than Units in Use suggests. On a resource with a total of 10, an
environment using 2 units shows 2 / 10 and 20% used. If your other environments hold 7 more,
Available (all environments) shows 1. Pick each environment in turn to find where the other
units are held.
The summary is always shown once you pick an environment, even when there are no allocations — so 0 / 10 with No active allocations for this resource in this environment is the normal reading of an idle resource, not a half-loaded view.
Units in Use is the resource's own total, not a count of the rows listed. The table shows up to 100 allocations, but the summary counts every live allocation, so it stays correct for a resource with more than 100 of them.
A failed load says so. If the environment list or the allocations can't be fetched you get an error, rather than the same empty state a tenant with no environments would see.
Releasing units an environment no longer uses
Units are normally released by the job that holds them, when it completes. A job in an environment that has stopped running — one that has gone inactive, or has been deleted — may never get the chance, and because the total is shared, those units are then missing from every environment.
- Deleting an environment releases its units. Every allocation it still holds is released as part of the delete. If that step fails, the delete still goes ahead, and the units stay listed under the deleted environment for you to release by hand.
- An inactive environment's units are not released for you, because its jobs may still be running. Release them yourself once you know they have stopped.
If your role has Resources Edit on the resource, each row of the allocation table carries a Release button, which releases that allocation at once — there is no confirmation. Release an allocation only when its job is no longer running. Earlier builds offered only active environments in the list and had no Release, so units held in an inactive or deleted environment could not be seen or freed, and drained the resource for every environment.
Managing Both in the Toolkit
Thresholds and resources each have a tab in the Toolkit, and each is created, edited and viewed in a dialog over its list — there is no separate detail page. Both carry Cross Reference, listing the jobs that depend on the object, and Delete checks those references before it removes anything: if the object is in use, the confirmation lists what depends on it and the delete cannot go ahead.
How a dependency holds on to its threshold or resource
A threshold or resource dependency stores the object's identity, with its name beside it, and every workflow save checks it:
- A renamed threshold or resource is still the one the dependency means. The job editor shows its new name as soon as you open the workflow, the build uses it in the job instance's dependency message, and exports carry it, without a save. The next save refreshes the stored name; an earlier version keeps the old one.
- An identity that names nothing in your tenant — one carried in from another environment, for instance — is pointed at the threshold or resource here that has the stored name.
- A deleted threshold or resource is never swapped for a new one of the same name. The save is refused — Threshold 'CORE_READY' is deleted. Restore it or use a different threshold. (or the same for a resource) — because a dependency on nothing could never be satisfied. Restore the deleted object, or pick the new one on the dependency. A dependency naming an object that does not exist at all is refused with Threshold 'CORE_READY' not found, or you do not have permission to view it.
Cross Reference and the delete check match dependencies by that stored identity. A workflow last saved before this release can hold an identity that was never checked, and is not listed against the threshold or resource it means until it is saved again — until then that object can be deleted while the workflow still depends on it. See Renaming or replacing an object a workflow uses.
Dependencies on a threshold or resource you cannot view
Thresholds and resources belong to workspaces, and a workflow save respects that. Each threshold or resource dependency the save adds or changes needs View on Thresholds (or Resources) in that object's workspace. Dependencies the save leaves as they are, or removes, are not checked, so you can always edit the rest of a workflow you can view, even when it already depends on a threshold or resource you cannot see.
| What your save does | When you cannot view the threshold or resource |
|---|---|
| Adds a dependency on it | Refused as though it did not exist: Threshold 'CORE_READY' not found, or you do not have permission to view it. (or the same for a resource). The answer is the same whether or not an object of that name exists, and whether or not it has been deleted. |
| Changes a dependency the workflow already has on it | Refused with the same answer: Threshold 'CORE_READY' not found, or you do not have permission to view it. |
| Removes a dependency the workflow already has on it | Allowed. |
| Leaves that dependency as it is | Not checked. The save goes through. |
| Removes a dependency on one that has since been deleted | Allowed, so the workflow can still be saved. |
A dependency counts as changed when its threshold or resource, its Operator or Value, or its Required units or Use all setting changes. Moving it to another job of the same workflow, or adding a second copy of it, counts as a change too. Renaming the job that holds it does not.
Copy Workflow keeps the original's dependencies as they are: a dependency carried over unchanged from the workflow you copied is not checked, so you can copy a workflow you can view even when it depends on a threshold or resource you cannot. A dependency you add or change in the copy is checked as on any save.
Earlier builds refused the removal of a dependency on a threshold or resource you could not view, and treated every dependency in a copy as new, so such a copy was refused.
Earlier builds looked thresholds and resources up across every workspace when a workflow was saved, so a dependency could be added on one you could not view.
- Use resources to cap concurrency against a shared system (e.g. only N jobs hitting the core at once). A job waits in Waiting: Resource Dependency until it can have what it needs, and returns there if another job takes those units before it is dispatched.
- Use Use all on the dependency for a job that must have the whole resource to itself. While it waits, the resource is reserved against jobs of the same or lower priority in every environment — see A waiting Use All job reserves the resource.
- A job waiting on a threshold sits in Waiting: Threshold Dependency until the value is reached.
- Both are workspace-scoped — the Toolkit and the job editor's dependency pickers list only the thresholds and resources in workspaces your role can see, and a workflow save refuses to add or change a dependency on one you cannot see. See Dependencies on a threshold or resource you cannot view.
Troubleshooting
| Symptom | Likely cause | Resolution |
|---|---|---|
| Jobs sit in Waiting: Resource Dependency and never get the resource | Not enough Total, or units aren't being released (held by stuck jobs) | Check the resource total, then use Current Allocations on the resource's row to see which jobs hold its units — see Seeing what holds a resource right now (Builder / Operator). |
| A resource is short of units, and Current Allocations shows them held in an inactive or deleted environment | Jobs there stopped without releasing their units | Once you know those jobs are no longer running, select Release on each row (Resources Edit). See Releasing units an environment no longer uses. |
| A job waits on a resource although nothing in its environment is using it | Jobs in another environment hold the units: the total is shared by every environment | In Current Allocations, compare Available (all environments) with Units in Use, then pick each other environment to see which jobs hold the units. Raise the total if every environment needs its share at the same time (Builder / Operator). See One total for every environment. |
| A threshold-gated job never runs | The threshold value isn't reaching the required level | Confirm what sets the threshold value and the dependency's required value (Builder). |
| A workflow save is refused with Threshold 'X' is deleted. Restore it or use a different threshold. (or Resource 'X' …), though one of that name exists | The dependency holds the deleted object's identity; a new object of the same name is not substituted | Restore the deleted object, or pick the new one on the dependency and save (Builder). See How a dependency holds on to its threshold or resource. |
| A workflow save is refused with Threshold 'X' not found, or you do not have permission to view it. (or Resource 'X' …) although you know it exists | It is in a workspace your role cannot view, and the save adds a dependency on it or changes one the workflow already has | Leave an existing dependency as it is, or ask an administrator for View on it in its workspace, or have someone who has it make the change (Builder / Administrator). See Dependencies on a threshold or resource you cannot view. |
| Cross Reference shows nothing for a threshold or resource a workflow uses | The workflow was last saved before this release with an identity that was never checked | Save the workflow once so the reference is repaired; until then the object is not protected from deletion (Builder). |
| Many jobs wait on thresholds or resources, and some take several passes to move after their value or units are available | Each pass re-checks a limited number of the jobs waiting at each of these gates, then moves on to the next ones on the following pass, so with many jobs waiting a job may not be re-checked for a few passes. Changing a threshold value or freeing units does not trigger a re-check on its own; the job moves when its turn comes. | Wait for the next passes. To shorten the wait, cancel or skip waiting jobs that can never clear (Operator). |