Collections

Collections is the umbrella menu group for eight reusable libraries that feed the rest of the product. Scripts, Jobs, Sensors, and Custom Fields are the programmable building blocks — small units you assemble into larger behaviours. App Hub, Application Control, and Device Control are catalogues — curated lists of packages, application rules, and USB devices. Software Deployment is an execution engine that stitches App Hub entries into ad-hoc rollouts.

8.0 How Collections relates to Policies

Five of the eight Collections sub-sections are also referenced from inside Policy Settings. That pairing is consistent: this chapter documents the library — how you author and manage the building blocks — while Chapter 6 documents attachment — how a policy picks from the library and which devices end up running or enforcing the result.

Scripts, Custom Fields, and Software Deployment have no policy-tab counterpart — they are either called from inside another Collections feature (Scripts by Jobs and Sensors) or stand alone (Custom Fields, Software Deployment).

8.1 Scripts

Manage Scripts at /manage_scripts is the library of code snippets that Jobs, Sensors, and Custom Fields draw on.

The list columns: Name, Description, Platform, Shell, Author, Date.

Create and edit a script

Two dialogs handle the lifecycle — Add Script for a new script and Edit Script for an existing one. Both share the same field set:

• Name — required.
• Description — free text.
• Default timeout — the script's default wall-clock timeout, in minutes (1 to 9999). The agent terminates the script if the timeout expires.
• Platform — one of Windows, Linux, MacOS, or System.
• Shell — gated on Platform.

Platform and Shell pair up exactly as follows; other combinations are not supported:

The System platform runs server-side database operations — typically used by SQL-backed Custom Fields and certain reporting workflows — not endpoint scripts.

The editor

The body of each dialog is a Monaco code editor with language-specific syntax highlighting driven by the selected shell. Two helpers sit next to the editor:

• Templates dropdown — starter examples for the current shell. Picking a template replaces the editor contents.
• AI Assistant — shown only when AI is enabled in Settings → AI/LLM. Opens a chat panel that can draft or refactor the script in place.
• Insert variable — a searchable menu of the device built-ins, the manual custom fields, their per-level forms and the write-back helper calls; a click inserts the token at the cursor. Disabled for the System platform.
• Preview for device — in the button row of the dialog; renders the script for a chosen device and shows the resolved variables, the prelude line and the delivered text.

Variables are written as {{namespace.key}} and are resolved per device when the script is handed out. See Script variables and custom fields in scripts.

Community Scripts

The Scripts library has a community-sharing surface. Five dialogs cover it:

• Community Scripts browser — lists scripts published to the community repository. Filter by platform, shell, or keyword; preview the source; click Import to copy a script into your library.
• Import from GitHub — imports directly from a GitHub URL when the script is not in the community repository.
• Publish — pushes one of your own scripts to the community repository. Requires community permissions and the script must have a description.
• Report — reports a community script as abusive or incorrect.
• View — detailed metadata view for a community script before import.

Imports land as standard entries in your Scripts library — they are regular scripts from that moment on, editable like any other.

Tip: Set Default timeout conservatively. A runaway script that never terminates ties up an agent until it hits the limit; a five-minute default is safer than the maximum.

How Scripts are used

• Jobs pick a Script as the thing to execute on a schedule. See 8.2.
• Sensors reference a Script in two ways — as the monitoring source for the PowerShell / Python3 / Bash / Zsh categories, and as the action script to run when thresholds are breached. See 8.3.
• Custom Fields reference a Script indirectly, via the Job whose output the field parses. See 8.4. A script can also read custom field values through variables and write values back with Set-NetLockField / nl_field_set; see Script variables and custom fields in scripts and Write custom field values from a script.

Scripts are not called from Automations (Automations assign policies and add sensors and jobs, which in turn reference scripts — see Chapter 5) and are not used by Software Deployment (deployment jobs execute install scripts stored on the App Hub entry, not library Scripts).

Permissions (Scripts)

• collections_enabled — master Collections flag.
• collections_scripts_enabled — see the Scripts page.
• collections_scripts_add — create a script.
• collections_scripts_edit — edit an existing script.
• collections_scripts_delete — delete a script.

8.2 Jobs

Manage Jobs at /manage_jobs is the library of scheduled tasks. A Job wraps a Script with a schedule and a platform. The Script is the "what"; the Job is the "when".

List columns: Name, Description, Platform, Type, Author, Date, and a hidden-status icon column (shown only on hidden jobs, with tooltip "Hidden — not shown in Events").

Create and edit a job

The Add Job and Edit Job dialogs share these fields:

• Name, Description.
• Timeout — 1 to 9999 minutes. Independent of the underlying Script's default timeout; the Job's value wins.
• Schedule — dropdown of 12 options (see below).
• Platform — Windows, Linux, or MacOS.
• Type — PowerShell, Bash, Zsh, or Python3; the dropdown is filtered to what the selected Platform supports.
• Script — the Script to execute, populated from matching scripts in your library.
• Hidden — toggle. Hidden jobs do not appear in the Events view. The standard use case is a background collection job that feeds a Custom Field — you do not want it cluttering operational events.

The twelve schedule types

Jobs support twelve scheduling patterns. The same set is used by Sensors (see 8.3). Each is an entry in the Schedule dropdown:

1. System Boot — runs once per device on boot.
2. Date/Time — one-shot execution at a specific date and time.
3. Every X seconds — recurring interval in seconds.
4. Every X minutes — recurring interval in minutes.
5. Every X hours — recurring interval in hours.
6. Starting on Date, every X seconds — seconds-recurring interval that begins at a specified date.
7. Starting on Date, every X minutes — minutes-recurring interval that begins at a specified date.
8. Starting on Date, every X hours — hours-recurring interval that begins at a specified date.
9. On specific days at time — a single time plus Monday-through-Sunday checkboxes, so the job runs at the chosen time on each enabled weekday.
10. On specific days every X seconds — seconds-recurring on selected weekdays only.
11. On specific days every X minutes — minutes-recurring on selected weekdays only.
12. On specific days every X hours — hours-recurring on selected weekdays only.

Intervals in seconds exist for tight monitoring-style jobs; day-limited intervals are the usual choice for maintenance tasks that should only run during business hours.

Jobs vs Scripts

A Script is a reusable piece of code. A Job is a scheduling wrapper that picks a Script. You can point many Jobs at the same Script with different schedules — for example a "hourly quick disk check" and a "daily deep disk audit" both running the same underlying script with different timeouts and cadences.

Attachment

Jobs attach to policies via the Jobs tab of Policy Settings — see Chapter 6.11 — or to the devices an automation rule matches, on top of their policy — see Chapter 5.6. A job with neither attachment exists in the library but does not run anywhere. Deleting a job removes it from every policy and every automation rule that uses it; a rule left without any action is switched off.

Permissions (Jobs)

• collections_enabled, collections_jobs_enabled, collections_jobs_add, collections_jobs_edit, collections_jobs_delete.

8.3 Sensors

Manage Sensors at /manage_sensors is the library of monitoring sensors. A Sensor samples a metric on a schedule, evaluates thresholds, and optionally runs an action Script when the breach is severe.

List columns: Name, Description, Platform, Category, Sub-Category, Severity, Author, Date.

Severity takes one of four values: Critical, High, Moderate, Low. Severity is assigned at the sensor and is the label surfaced on notifications and on the Dashboard.

Create and edit a sensor

The Add Sensor and Edit Sensor dialogs share the core fields — Name, Description, Platform, Severity, Schedule (the same twelve options Jobs use), Category. The dialog then renders a conditional Sub-Category and Rule block based on the chosen category.

The nine categories

Sensors come in nine categories:

1. Utilization — host-level metrics. Six sub-categories:

   • Processor — CPU usage threshold.
   • RAM — memory usage threshold.
   • Drive — disk space or IO threshold.
   • Process CPU Usage (%) — CPU percentage consumed by a named process.
   • Process RAM Usage (%) — memory percentage consumed by a named process.
   • Process RAM Usage (MB) — memory bytes consumed by a named process.

   Rule configuration uses a threshold slider (5 to 100 percent, step 5) for the Processor / RAM / Drive variants, and a Process Name field plus a Notification Threshold Max value (0 to 9999) for the Process-CPU / Process-RAM variants.

2. Windows Eventlog — match entries in the Windows event log against a query. Useful for specific event IDs that represent failures you care about.

3. PowerShell — the data source is a PowerShell script. The agent runs the script on schedule; the script's numeric output is the sample value.

4. Python3 — same model, Python3 as the language.

5. Bash — same model, Bash as the language.

6. Zsh — same model, Zsh as the language.

7. Service — the state of a Windows or Linux service. Breaches when the service is not in the expected state.

8. Ping — ICMP reachability of a host. Breaches on loss.

9. SNMP — SNMP GET, Walk, or Monitor operation against a network device. The sensor stores credentials and queries per-sensor.

Path placeholders in file, directory and registry sensors

The path fields of the file and directory sensors in the Other category (File change, Directory change, File exists, File age, File size, Directory size, Directory files count, Directory permission drift, Equal folder, Last log keyword, Log directory keyword) accept two kinds of placeholders, and the key path of the Registry change watch sensor accepts a third one. All of them are resolved on the device by the agent when the sensor runs; the value stored in the sensor stays as you typed it.

Environment variables

• %NAME% works on every platform, including names with parentheses such as %ProgramFiles(x86)%.
• $env:NAME (PowerShell style) and ${NAME} work on every platform as well. A bare $NAME is not expanded, so a $ inside a file name is left alone.
• Only the path fields are expanded. User names, passwords, patterns and keywords are taken literally.
• A variable that is not set is left in the path unchanged; the sensor then reports the path as not existing, and the unresolved token is visible in the event text.
• The agent runs as SYSTEM on Windows and as root on Linux and macOS. User-specific variables such as %APPDATA%, %USERPROFILE%, %LOCALAPPDATA% or ${HOME} therefore resolve to the system account, not to the user who is signed in. For per-user paths use the {user_profiles} placeholder below.

{user_profiles}

A path that starts with {user_profiles} is checked once for every local user profile on the device, with the rest of the path appended to each profile root:

• Windows: the profiles listed under HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList for real user accounts (S-1-5-21-…), typically C:\Users\<name>. Service and system profiles are not included.
• Linux: the home directories of the accounts in /etc/passwd with a uid between 1000 and 65533.
• macOS: the directories under /Users, without Shared, Guest and hidden or service entries.

Rules:

• The placeholder must be the first segment of the path and may appear only once. {user_profiles} alone, {user_profiles}\<rest> and {user_profiles}/<rest> are valid; C:\{user_profiles}\x is rejected with an error event. It is not case-sensitive.
• Environment variables in the remainder are expanded before the profile roots are joined.
• Directory change, File change, File exists, File age and File size support the placeholder. Directory size, Directory files count, Directory permission drift, Equal folder, Last log keyword and Log directory keyword do not and report "The {user_profiles} placeholder is not supported by this sensor."
• Directory change and File change keep a separate baseline per profile. A profile whose folder or file does not exist is skipped without an alarm and gets no baseline; a profile that appears later (a new user signs in) is baselined silently on the next run; a profile that disappears drops out of the baseline without an alarm. A folder or file that existed when the baseline was recorded and is gone on a later run raises an alarm once. With {user_profiles}, an empty folder is not an error (for a single path it still is). A change is reported for exactly the profile it happened in, with the usual added / removed / changed lists.
• File exists with {user_profiles} alarms when any profile is in the unexpected state (file missing while it should exist, or present while it should be absent) and lists the affected profiles.
• File age and File size evaluate the matches of all profiles together against the configured thresholds.
• Editing the path, the pattern or the recursion of a Directory change or File change sensor records a fresh baseline on the next run instead of comparing the new location against the old baseline.
• Unauthenticated UNC paths and the placeholder cannot be combined, because the placeholder has to be the first segment.

Example: watch all autostart entries

Two Directory change sensors cover the per-user and the all-users startup folders on Windows:

1. Path {user_profiles}\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup — one baseline per user; a shortcut dropped into one user's Startup folder raises an event naming that user.
2. Path %ProgramData%\Microsoft\Windows\Start Menu\Programs\Startup — the all-users startup folder.

On Linux the equivalent per-user location is {user_profiles}/.config/autostart.

{user_sids}

A key path of the Registry change watch sensor that starts with {user_sids} is watched once in every user hive that is currently loaded under HKEY_USERS, with the rest of the path appended to each SID:

• Windows only. The hives of real user accounts are used: local and domain accounts (S-1-5-21-…) and Entra ID accounts (S-1-12-1-…).
• The service hives (.DEFAULT, S-1-5-18, S-1-5-19, S-1-5-20), the per-user class stores (<SID>_Classes) and the .bak leftovers of a profile repair are not included.
• Each SID is resolved to its account name (DOMAIN\user or MACHINE\user). When the account cannot be looked up - a deleted account or an unreachable domain controller - the profile folder name is shown instead, and if that is unavailable too the raw SID. The resolved name is remembered per sensor, so the lookup normally runs once per user.

Rules:

• The placeholder must be the first segment of the key path and may appear only once. {user_sids}\<rest> is valid; SOFTWARE\{user_sids}\x is rejected with an error event. It is not case-sensitive.
• The hive selection of the sensor is implied by the placeholder and ignored, because HKEY_USERS\<SID> is by definition the root of a user hive. The event body names the key that was actually watched.
• Only hives that are currently loaded can be read. A user who is signed off has no hive under HKEY_USERS; those profiles are listed in the event as not evaluated, so it is visible who was left out. The agent never mounts a NTUSER.DAT of its own.
• Each user keeps a separate baseline. A hive seen for the first time (a user signs in) is baselined silently; a hive that is no longer loaded (the user signs off) is reported for information and keeps its baseline for the next sign-in. Neither raises an alarm.
• A change is reported for exactly the user it happened in, with the usual added / removed / modified lists. All users share one event.
• The value limit applies per user hive, not to the run as a whole. A hive over the limit is reported on its own and the remaining hives are still evaluated.
• Changing the hive, the key path, the recursion or the value limit of a Registry change watch sensor records a fresh baseline on the next run instead of comparing the new location against the old baseline. This applies to a single key as well as to {user_sids}.
• Environment variables are not expanded in a registry key path.
• An agent that is too old to know the placeholder reports The registry key was not found: <hive>\{user_sids}\…, so the unsupported construct is visible in the message.

Example: watch the autostart entries of every signed-in user

A Registry change watch sensor with the key path {user_sids}\Software\Microsoft\Windows\CurrentVersion\Run covers the per-user Run key of everyone who is signed in; an entry added for one user raises an event naming that user. The machine-wide counterpart is a second sensor with the hive HKEY_LOCAL_MACHINE and the key path SOFTWARE\Microsoft\Windows\CurrentVersion\Run.

Thresholds and actions

Every sensor defines two threshold levels:

• Notification Threshold Max — when the sampled value exceeds this, a notification is generated.
• Action Threshold Max — when the sampled value exceeds this, the configured action Script runs in addition to the notification.

The action section exposes a Script dropdown, populated from Scripts that match the sensor's Platform and runtime. When the sensor breaches the action threshold, the agent executes the selected script on the device that reported the breach. This is the canonical pattern for "when disk hits 95%, run the cleanup script".

Sensor readings are one of the Dashboard's queryable data sources (see Chapter 2), and sensor breaches appear in Events (see Chapter 12).

Attachment

Sensors attach to policies via the Sensors tab of Policy Settings — see Chapter 6.10 — or to the devices an automation rule matches, on top of their policy — see Chapter 5.6. Sensors the SNMP discovery manages cannot be added through a rule. Deleting a sensor removes it from every policy and every automation rule that uses it; a rule left without any action is switched off.

Permissions (Sensors)

• collections_enabled, collections_sensors_enabled, collections_sensors_add, collections_sensors_edit, collections_sensors_delete.

8.4 Custom Fields

Manage Custom Fields at /manage_custom_fields is the library of Custom Field definitions. Unlike a traditional RMM that exposes a handful of text inputs as "custom fields", NetLock RMM's Custom Fields compose entire tabs and sections of the device detail page, populated from multiple data sources.

List columns: Name, Description, Author, Date, Tabs (count of tabs this definition contributes).

The builder dialog

A single dialog — the Custom Field Builder — handles both Add and Edit. The builder is a multi-panel visual editor, not a simple form; it designs an entire device-detail-page fragment in one place.

The builder has the following structure.

Definition panel (top). Name and Description of the Custom Field set.

Header Action Buttons. A list of buttons injected into the device detail header next to the standard controls (Screen Control, Shell, and so on). Each button has:

• Label — what the button says.
• Type — URL Handler or SQL Execute.
• Icon — autocomplete over the icon set.

URL Handler buttons open a URL template. The template supports placeholder tokens {device_id} and {field_key}, which are substituted at click time. SQL Execute buttons run a SQL statement on the server; the statement supports the {device_id} placeholder and has a Require confirmation checkbox for destructive actions.

Tabs. The top-level containers on the device detail page that this definition contributes to. Each tab has:

• Target — New Tab, Existing Tab, or Existing Section. New Tab creates a fresh tab; the other two inject into a tab or section that already exists elsewhere in the detail page.
• Tab Name and Icon — shown for New Tab.

Sections. Inside each tab, one or more sections — each with a Section Name — appear as labelled blocks on the device page.

Fields. Inside each section, one or more fields. Every field has:

• Key — the programmatic identifier used in placeholders and in scripts. A key starts with a lowercase letter and continues with lowercase letters, digits and underscores, at most 64 characters, and it must be unique across all definitions. The builder rejects a new or renamed key that breaks either rule. Keys created before this rule are kept and stay reachable in scripts through their environment name (NL_FIELD_ plus the key in upper case, with every other character turned into an underscore); the builder reports them when the definition is saved. When two definitions share a key, scripts read and write the definition that was created first.
• Label — the human-readable name.
• Type — one of Text, Multiline, Table, or Secret. Secret is available with the Manual data source only; see Secrets below.
• Data Source — one of Manual, Job Result, or SQL Select.
• Inheritable — a checkbox for Manual fields. An inheritable field can hold values on group, location, tenant and global level, and a device without a value of its own inherits the nearest one. See Scope and inheritance below.

Data sources in detail:

• Manual — the field is free for users to edit on the device detail page. The value is stored per device.
• Job Result — the value is auto-populated from a Job's output. The builder asks for a Job Name; if you need to pluck part of the output, supply a Parse Regex. Jobs used to feed Custom Fields are typically flagged Hidden to keep them out of the Events view (see 8.2). The result of agents that run with a German system language (they report a finished job as fertiggestellt) is parsed as well. For a value a script computes itself, the write-back helper is the more direct route; see Write custom field values from a script.
• SQL Select — the value is the result of a SQL query. Two modes:
  • Visual Query Builder — pick a table, pick columns (with aggregates COUNT, SUM, AVG, MIN, MAX, DISTINCT), add joins (INNER, LEFT, RIGHT), add WHERE filters with device_id already available as a placeholder, set ORDER BY and LIMIT.
  • Raw SQL — gated by a "God Mode" toggle. Lets you enter SQL directly, with {device_id} as the available placeholder.

Section Action Buttons. Each section can carry its own buttons, with the same shape as Header Action Buttons but scoped to the section. Useful when an action is only meaningful in the context of the data shown in that section.

Scope and inheritance

Values are stored per device: every device that lands under a Custom Field definition has its own value set, and the field metadata (keys, labels, types, queries) is shared.

A Manual field marked Inheritable can additionally hold one value per tenant, per location, per group, and one global value. A device reads the first value found in this order: its own value, then its group, its location, its tenant, and finally the global value. A field without the flag has device values only. The device page shows an inherited value greyed out, with an icon whose tooltip names the level it comes from. The same effective value, with its level, is what a script variable and the public API receive; see Script variables and custom fields in scripts and X.9 — Public API.

Removing a value deletes its row. On the device page, Remove device value in the editor of the field deletes the device's own row after a confirmation, so the device inherits again; Clear value in a level editor deletes that level's row.

Level values are edited where the level lives:

• Tenant: the Custom Fields section on the Tenant Settings page (Tenants → tenant → Manage).
• Location: the Custom Fields section on the Location Settings page of the location.
• Group: the Custom Fields section in the group's edit dialog.
• Global: Settings → Custom Fields, tab Global values.

Note: On the Location Settings page the section is shown only to accounts that hold tenants_locations_edit or tenants_locations_delete; the tenant page and the group dialog have no such condition.

All four places show the same editor: one row per inheritable manual field with the definition, the field, the key, the value on this level, the effective value with its source, who changed it last and when, and the row actions Set value, Reveal secret / Hide secret (secret fields only) and Clear value. A key that predates the naming rule is marked with the environment name scripts have to use.

Viewing a level needs collections_custom_fields_enabled and access to the tenant; changing a value needs collections_custom_fields_edit; the Global values tab needs settings_custom_fields_enabled in addition. Every change is written to the audit log with the level and the field, never with the value.

Changing a value on any level marks the affected devices for a policy re-sync, so jobs and sensors that use the value through a script variable pick it up at the next check-in: a device value marks that device, a level value the devices below it, a global value every device. When an automation rule compares the field (Chapter 5.2.1), the rules are evaluated again for the affected devices and the online ones are pushed at once; this applies to values written on the device page, on a level, by a script and through the public API. Deleting a tenant, a location, a group or a definition removes the values stored for it.

Secrets

A field of type Secret holds a value that should not be readable in the console by default: an enrolment token, an API key, a password an install script needs. Secret fields are Manual fields only, and they can be inheritable like any other manual field.

• Values are stored encrypted, on devices and on every level.
• The device page, the level editors and the script preview show a mask. A new value is typed into an empty password field.
• Reveal secret shows the stored value to accounts with collections_custom_fields_reveal_secrets. Every reveal writes an audit entry. The permission is granted under Users → account → Collections → Custom fields; administrator accounts receive it at the next start of the web console.
• The public API never returns the value of a secret field (value: null, isSecret: true).
• A script that refers to the field receives the plain text on the device; see the security notes.
• Changing a field's type from Secret to Text keeps the stored values encrypted. Enter them again after such a change.

Consumption

• The device detail page renders every tab, section, and field a Custom Field Definition declares — see Chapter 3. A manual field shows where its value comes from: an icon with the tooltip Inherited from … for a level value, and one with Set by script on … or Set by API on … for a value written by a script or the public API.
• Scripts read values through variables such as {{field.av_ou_id}} and can write values back with Set-NetLockField / nl_field_set. See Script variables and custom fields in scripts and Write custom field values from a script.
• The public API reads and writes device values and level values; see X.9 — Public API.
• Dashboard panels can query the same underlying storage via the Panel Builder's SQL query builder, which lets you aggregate custom-field data across the fleet.
• Reports do not expose custom-field values as a selectable data source in the Report Builder. Custom fields appear in Reports only as optional key-value entries on the cover-page footer of a brand template — a cosmetic integration, not a queryable one. To include custom-field data in a report, write a raw SQL query against the underlying storage in God Mode, if your role has it.

Permissions (Custom Fields)

• collections_enabled, collections_custom_fields_enabled, collections_custom_fields_add, collections_custom_fields_edit, collections_custom_fields_delete.
• collections_custom_fields_edit also gates changing values on devices and on tenant, location and group level; settings_custom_fields_enabled is needed in addition for the Global values tab.
• collections_custom_fields_reveal_secrets — reveal the stored value of a Secret field. Every reveal is written to the audit log.

8.5 App Hub

Manage Apps at /app_hub_manage_apps is the catalogue — the library of installable packages the product knows about. The App Hub is explicitly not a deployment engine. Deploying one of these apps to devices happens through Software Deployment (see 8.8); this page is where the list of available apps is maintained.

List columns: Icon, Name, Publisher, Version, Source (colour-coded chip: winget, flatpak, chocolatey, script), Target OS, and per-row Edit and Delete actions. Only one tab — "Apps" — is visible.

The three sources plus manual entries

Four catalogues feed the page:

• Winget — Windows Package Manager feeds, used for Windows apps.
• Flathub — the Flatpak catalogue, used for Linux apps.
• Chocolatey — Chocolatey feeds, used for Windows apps.
• Script — manual entries backed by install / update / uninstall / detection scripts you write.

Adding an app — manual entry

The Add_Manual_App dialog creates a catalogue entry by hand. Fields common to all sources:

• Name (required), Description, Version, Publisher, Author, License, Homepage, Target OS, and an icon upload.

Source-specific fields appear based on the source picker:

• Winget — Winget Package ID, Winget Source.
• Chocolatey — Chocolatey Package ID, Chocolatey Source.
• Flatpak — Flatpak App ID.
• Script — Install script, Update script, Uninstall script, Detection script, Detection window (seconds), and a Script Shell selector.

The Edit_App dialog presents the same fields pre-populated against an existing entry.

An install, update or uninstall script fails when it exits with a code other than 0, when its output starts with Error, or after 30 minutes — on Windows, Linux and macOS alike. Update and Uninstall are only offered for a script app that has the matching script.

The Detection script is optional and tells whether the app is installed: exit code 0 plus at least one line of output means installed, anything else not installed; the first output line should carry the installed version (for example 2.4.1). It runs before and after every install, update and uninstall, in the app's context (SYSTEM/root, or the signed-in user for apps without elevation on Windows) with a 5-minute timeout per run. Before the action, an install of an installed app and an update or uninstall of an app that is not installed are skipped (Skipped); a failing detection script lets the action run. After a successful action it is asked again (right away, after 5, 10, 20 and 30 seconds, then every 30 seconds) until it reports the expected state or the Detection window (default 300 seconds, 0 = no check after the action) ends; not confirmed means Failed, a detection that fails on every check means Detection error. The detected version drives Update available in the tray icon's App Hub and the auto-update of script apps, which only runs when the detected version is lower than the catalogue Version. See Deploy custom applications with scripts for a full walkthrough.

Adding an app — catalogue browsers

For Winget, Flathub, and Chocolatey there are dedicated browser dialogs — Winget_Catalog_Browser, Flathub_Catalog_Browser, and Chocolatey_Catalog_Browser. Each is a searchable table of the remote catalogue with a metadata preview pane. Select a row, click Add to Catalog, and the app is copied into your local App Hub with its identifiers pre-filled.

Refreshing the catalogues

The page has a Refresh catalogs button that triggers an asynchronous sync of all three remote catalogues. Progress is shown in the page's status area; the button reports when the sync completes. Refreshing updates the versions and metadata of apps already in your catalogue and lets newly browsed apps pick up the latest remote data.

The available_for_deployment flag

Every app entry has an available_for_deployment flag. Apps with this flag set are selectable inside the Software Deployment wizard (see 8.8). Apps without it are visible in the catalogue and in the policy-level App Hub tab, but cannot be picked as deployment targets.

How policies use App Hub

The App Hub tab inside Policy Settings (see Chapter 6.13) decides which catalogue apps are visible to end users in the tray icon under a given policy. This is catalogue curation, not deployment. Selecting apps in the policy does not install anything — it decides what the tray exposes.

Permissions (App Hub)

• collections_app_hub_enabled — see the App Hub page.
• collections_app_hub_add — add a manual app.
• collections_app_hub_browse_winget, collections_app_hub_browse_flathub, collections_app_hub_browse_chocolatey — use the respective catalogue browsers.
• collections_app_hub_manage — edit, delete, and refresh catalogues.

8.6 Application Control

Application Control is an allowlist system for executables on Windows devices. Rulesets live at /application_control_manage_rulesets. The ruleset detail page is at /application_control_ruleset.

The page has two tabs.

Rulesets tab

List columns: Name, Description, Author, Date.

Actions:

• Add Ruleset — create a ruleset (Name, Description).
• Edit Ruleset — rename or redescribe.
• Delete Ruleset — delete.

Click a ruleset to open its detail page, which lists the rules inside it. The detail page has Back, Save, Edit, and Delete affordances at the top and Add, Edit, Delete actions on the rule list.

Rules inside a ruleset

Each rule identifies one allowed executable by any combination of file and certificate attributes. The Add Rule and Edit Rule dialogs share these fields (Name is required; everything else is optional and combines with AND semantics when present):

File attributes:

• File Path — absolute or pattern path to the executable.
• File Company, File Product, File Copyright, File Brand — Windows version-info strings.
• File Product Version, File Version — Windows version-info numeric strings.
• File SHA256, File SHA512 — cryptographic hashes of the executable.

Certificate attributes (for signed executables):

• Certificate Owner, Certificate Issuer.
• Certificate Begin, Certificate End — validity window.
• Certificate Public Key, Certificate Serial Key.
• Certificate SHA1.

A rule matches when every specified attribute matches the running executable. Any executable not matched by any rule in a ruleset attached to a device is blocked.

Tip: A SHA256 or SHA512 hash rule is the strongest form and does not need other fields. Path-only rules are the weakest — any file at that path matches, regardless of its contents.

Blocked Applications tab

When the agent blocks a launch attempt, the attempt is logged and surfaces on the Blocked Applications tab. List columns: Policy (the ruleset name), Count (instance count for this blocked entry), Date, Device, Process, Path, Company, Product.

From this tab you operate on selections with two actions:

• Approve Selected — inserts the blocked entries as allowed rules into the associated ruleset. The server deduplicates by SHA512 so repeat approvals do not clutter the ruleset.
• Delete Selected — removes the log entries without whitelisting.

Every entry carries a status: Pending approval, Approved, or Dismissed. Approving moves an entry to Approved and adds a rule; dismissing moves it to Dismissed without adding a rule.

Attachment

Application Control rulesets attach to devices via the Windows → Application Control sub-section of Policy Settings — see Chapter 6.7. A ruleset with no policy attachment exists in the library but enforces nothing.

Permissions (Application Control)

• collections_application_control_enabled — see the page.
• collections_application_control_add, collections_application_control_edit, collections_application_control_delete — ruleset-level lifecycle.
• collections_application_control_manage — manage rulesets broadly (Approve Selected and similar).
• collections_application_control_rules_add, collections_application_control_rules_edit, collections_application_control_rules_delete — rule-level edits inside a ruleset.

8.7 Device Control

USB Device Control is an allowlist system for removable peripherals. The same page is reachable from two routes — /device-control/whitelist and /device-control/blocked — each opening with a different tab selected.

Whitelist tab

List columns: Device Name, Manufacturer, Device ID (truncated with a tooltip showing the full ID), Scope chip (device, tenant, location, group, or global), Scope Target, Author, Date, Status (enable/disable toggle), and a per-row Delete action.

The Device ID encodes vendor-id, product-id, and serial number — the three pieces of information that uniquely identify a specific USB device (or a specific model, depending on how you later choose to scope the entry).

Blocked Devices tab

When the agent blocks a USB device, the event lands on the Blocked Devices tab.

List columns: Count, Date, Reporting Device, USB Device, Manufacturer, Type (device class: Mouse, Keyboard, HID, USB, DiskDrive, WPD, CDROM, Media, Network, XboxComposite), Device ID, Actions Taken, Status chip (Pending, Approved, Dismissed), and a context-menu actions column.

Approving a device (the only way to add a whitelist entry)

There is no standalone dialog for creating a whitelist entry. Entries are added exclusively by approving a pending row on the Blocked Devices tab. Click the row's menu icon and pick:

• Approve for this device — the whitelist entry applies only to the specific device that reported the block.
• Approve for tenant — applies to every device in the tenant.
• Approve for location — applies to every device in the location.
• Approve for group — applies to every device in the group.
• Approve globally — applies to every device in the deployment.
• Dismiss — records that the block was reviewed but should not be whitelisted.

Approving at any of the five scopes inserts a row into the whitelist with the corresponding scope type and scope target. Dismissing closes the event without adding a whitelist row.

Matching granularity

A whitelist entry matches a USB device by vendor-id, product-id, and serial (encoded in Device ID), plus device class. Serial-level matching identifies one specific physical device; vendor-and-product-only matching accepts an entire model family. You choose this implicitly at approval time — the pending row carries the device's actual identifiers, and the resulting whitelist entry inherits them.

Attachment

USB Device Control is enabled per policy through the Windows → USB Device Control sub-section of Policy Settings — see Chapter 6.8. Approving an entry or toggling its status forces an immediate re-sync so endpoints pick up the change.

Permissions (Device Control)

• collections_device_control_enabled — the sole permission gating the page in the current release. There are no separate add/edit/delete flags for USB Device Control.

8.8 Software Deployment

Software Deployment is the execution engine that drives App Hub packages onto devices. Three routes make up the feature:

• Manage_Deployments at /software_deployment — the list of deployment jobs.
• New_Deployment at /software_deployment/new — the four-step creation wizard.
• Deployment_Detail at /software_deployment/{id} — the detail view for a single deployment job.

Software Deployment is ad-hoc, not policy-driven. A deployment is created, run, and tracked as a discrete job; there is no tab in Policy Settings that composes deployments.

The deployment list

List columns: ID, Name, Author, Created, Mode (interactive or bulk), Status (pending, running, completed, completed_with_errors, cancelled), Progress (format succeeded/failed of target_count, with an error chip when failures exist), and Actions (View, Cancel, Retry, Rename, Clone, Delete).

The New Deployment wizard

The wizard has four steps.

Step 1 — Packages. Autocomplete-search the App Hub catalogue. Only apps flagged available_for_deployment = 1 are selectable. Each added package has an action dropdown — install, uninstall, or update; for a script app without an update or uninstall script that action is disabled. A single deployment may include multiple packages with mixed actions. When the deployment is saved, every package is read from its App Hub app: the script of the chosen action, the detection script and the detection window.

Step 2 — Targets. Choose the devices that should receive the deployment. You can add devices directly, or select groups, locations, or tenants; a dynamic-membership flag keeps a group target live as devices enter or leave the group.

Step 3 — Config. Per-deployment settings:

• Mode — interactive (real-time feedback in the Console) or bulk (background).
• Schedule start time — when execution may begin.
• Expiry — when unstarted targets are abandoned.
• retry_max — maximum retry attempts per target on failure.
• retry_backoff_min — minimum minutes between retries.
• Force reinstall — install even if the detection script reports the package as installed. Only the check before an install is skipped; the check after the install still runs.
• Abort on first failure — stop the entire deployment when any target fails.

Step 4 — Review and Submit. A summary view of the chosen packages, targets, and configuration. Confirming creates the deployment. If Schedule start time is in the past or unset, the deployment begins running immediately.

The detail page

The detail view shows four info cards across the top — Status, Progress, Author & Created, Scheduled / Expires — followed by a per-device results table. Action buttons at the top of the page: Back, Cancel (available while status is pending or running), Retry (available when any target has failed), Rename, Clone, Delete.

Each row in the per-device table is a target device; its inner data is an attempt history surfaced through the per-device results dialog.

Per-device result detail

The per-device results dialog shows every attempt the deployment made on one device. Per attempt it displays:

• Job Item ID, Attempt number.
• Outcome — Success, Failed, Skipped, Detection error, Timeout or Cancelled. Skipped means the detection before the action decided there was nothing to do (the app is already installed for an install, not installed for an update or uninstall); it counts as a success. Failed also covers a script that succeeded while the detection script did not confirm the result within the detection window. Timeout means the script ran longer than 30 minutes, or a step without elevation got no result from the tray icon in time.
• The detection state next to the outcome — Detected, Not detected or Detection failed — when a detection script ran.
• Exit code, Duration, Started and Finished timestamps.
• Error summary — an alert block if the attempt raised a specific error.
• stdout tail and stderr tail — trimmed output from the script. Lines starting with [detection] explain what the detection script decided before and after the action.

A step without elevation on Windows runs in the signed-in user's session through the tray icon; the deployment waits for its result and reports it like every other step.

This is the primary forensic view when a deployment has failures — exit codes and stderr tails tell you whether the failure is a package problem, a permissions problem, or a transient network issue.

Retry and the Retry button

The Retry button on the detail page re-queues every failed target in the deployment. Retries respect retry_max and retry_backoff_min from the original configuration and increment the attempt counter. Successful targets are not touched. This is the standard remediation workflow — fix whatever caused the failure, then press Retry.

Ad-hoc single-device deployment

The Deploy Software dialog is a compact single-device flavour of the wizard, launched from outside the main Software Deployment page (for example from a device detail view). It carries the selected device's identity along with a package autocomplete and an action dropdown. Run Now creates the job and starts it immediately without the full wizard.

Relationship to App Hub

App Hub is the catalogue of what can be installed; Software Deployment is how it gets installed. A deployment pulls metadata from App Hub (package identifiers per source, install / detection scripts, elevation requirement) and wraps it in a job with targets, scheduling, retry rules, and per-device tracking. The two features are intentionally separate.

Permissions (Software Deployment)

• collections_software_deployment_enabled — see the Software Deployment pages.
• collections_software_deployment_view — view deployment lists and detail pages.
• collections_software_deployment_add — create a new deployment.
• collections_software_deployment_manage — cancel, retry, rename, clone, and delete deployments.

Related chapters

• Core Concepts — Collections as reusable building blocks.
• Chapter 5 — Automations — the policy routing layer; event-driven reactions live with Sensors, scheduled work with Jobs.
• Chapter 6 — Policies — attachment points for Jobs, Sensors, App Hub, Application Control, and Device Control.
• Chapter 7 — Patch Management — the approval queue for OS and package updates, separate from Software Deployment.
• Chapter 12 — Events & Audit — where script, job, sensor, and deployment outcomes surface.
• Chapter 13 — AI Chat — generating scripts for the Scripts library with AI assistance.
• Chapter 15 — Community — the community repository the Scripts library publishes to and imports from.