NetLock RMMNetLock RMM Docs
II — Console Reference

Collections

Scripts, Jobs, Sensors, Custom Fields, App Hub, Application Control, Device Control, and Software Deployment.

Collections

Collections is the menu group for eight reusable libraries used across the product. Scripts, Jobs, Sensors and Custom Fields are programmable building blocks that you combine into larger tasks. App Hub, Application Control and Device Control are catalogues of packages, application rules and USB devices. Software Deployment rolls out App Hub entries to devices on demand.

Collections menu with all eight sub-pages listed

8.0 How Collections relates to Policies

Five of the eight Collections sub-sections are also referenced from inside Policy Settings. This chapter documents the library, that is how you author and manage the building blocks. Chapter 6 documents how a policy picks from the library and which devices run or enforce the result.

Collections subsectionRelated policy tab
JobsJobs tab (Chapter 6.11)
SensorsSensors tab (Chapter 6.10)
App HubApp Hub tab (Chapter 6.13)
Application ControlWindows → Application Control (Chapter 6.7)
Device ControlWindows → USB Device Control (Chapter 6.8)

Scripts, Custom Fields and Software Deployment have no policy tab. Scripts are called by Jobs and Sensors; Custom Fields and Software Deployment stand alone.

Labels, selection and bulk delete (Scripts, Jobs, Sensors)

The lists of Scripts, Jobs and Sensors share three list features:

  • Label. Every script, job and sensor can carry one free-text label of up to 64 characters, set in the add, edit and duplicate dialogs. The field suggests the labels already used in the same list; any other text becomes a new label, an empty field removes it. The label only organises the list: it is not part of what the agents receive, and changing only the label does not make the devices re-sync.
  • Grouping. As soon as one entry has a label, the list is grouped by label (case-insensitive, entries without a label last, each group collapsible). A Filter by label selector next to the search shows one label or only the entries without a label; the search also matches the label.
  • Selection. Accounts with the edit or the delete permission of the list see a checkbox per row, one in the header for all visible entries and one per label group. While entries are selected, the toolbar shows the number selected and Set label (edit permission; sets or, when left empty, removes the label of all selected entries), Delete selected (delete permission) and Deselect all. Only visible entries stay selected: changing the search or the label filter drops the hidden ones from the selection.

Delete selected asks once for all selected entries. For scripts the question also says how many jobs and sensors use them: those keep their settings but run no script until another one is set. Deleted jobs and sensors are removed from the automation rules that add them, exactly as with a single delete. Each entry is deleted on its own, so one that fails does not stop the others; the result message says how many of the selected entries were deleted.

8.1 Scripts

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

Manage Scripts list with columns Name, Description, Platform, Shell, Author, Date

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

Create and edit a script

Add Script creates a new script and Edit Script changes an existing one. Both dialogs share the same fields:

  • 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:

PlatformAllowed Shells
WindowsPowerShell, Python3
LinuxBash, Python3
MacOSZsh, Python3
SystemMySQL

The System platform runs server-side database operations, not endpoint scripts. It is typically used by SQL-backed Custom Fields and some reporting workflows.

Python3 scripts run in Python's isolated mode (python3 -I): PYTHONPATH, the user site folder and modules placed next to the script are not loaded, so import only what the interpreter ships or what is installed machine-wide (pip install as administrator or root into the interpreter's own installation), or extend sys.path inside the script. On Windows the agent uses a machine-wide Python from the registry (HKLM\SOFTWARE\Python\PythonCore) or the py launcher; per-user installations under C:\Users are not used. On Linux the interpreter is /usr/bin/python3 or /usr/local/bin/python3, on macOS /usr/bin/python3, /opt/homebrew/bin/python3 or /usr/local/bin/python3.

The editor

The body of each dialog is a Monaco code editor with language-specific syntax highlighting driven by the selected shell. These 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 can share scripts with the community. 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. It is started from the script's edit dialog, so it needs collections_scripts_edit, 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.

Imported scripts are regular entries in your Scripts library and can be edited like any other.

Tip: Set Default timeout conservatively. A script that never ends ties up the agent until the limit is reached, so 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".

Manage Jobs list with hidden-job icon visible on one row

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 typical use is a background collection job that feeds a Custom Field and should not fill the Events view.

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. Several Jobs can use the same Script with different schedules, for example an "hourly quick disk check" and a "daily deep disk audit" that run the same script with different timeouts and intervals.

Attachment

Jobs attach to policies through the Jobs tab of Policy Settings (see Chapter 6.11), or to the devices an automation rule matches, in addition to 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 can run an action Script when a threshold is reached. Sensors of the category Server are the exception: the NetLock server evaluates them itself when something happens on the server side, and they never reach a device (see Server sensors below).

Manage Sensors list with Category and Severity columns

List columns: Name, Description, Platform, Category, Sub-Category, Severity, Author, Date. A server sensor shows Server as its platform and its kind as the sub-category.

Severity takes one of four values: Critical, High, Moderate, Low. Severity is set on the sensor and shown 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) and Category. Below them, the dialog shows the Sub-Category and Rule fields of the chosen category.

The categories

Sensors come in eleven categories. The first ten run on the device; the eleventh, Server, is evaluated by the NetLock server:

  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 for the Process-CPU / Process-RAM variants. The Notification Threshold Max value (0 to 9999) is not a usage limit but the number of consecutive hits after which the notification is sent, as described under Thresholds and actions below.

  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.

  10. Other: ready-made checks picked from a template catalogue, among them the file, directory and registry sensors described in the next section.

  11. Server: events the NetLock server raises about devices: Unauthorized device and Device country. See Server sensors.

Server sensors

A server sensor is not run by an agent. The NetLock server evaluates it at the moment the event happens: when a new device registers, an authorized device is reinstalled, a device reports a changed hardware ID or the license limit takes an authorization away, or when a device connects from a country that the country restriction does not list. Server sensors have two kinds, Unauthorized device and Device country.

Creating one. In the Add Sensor dialog, choose the platform Server, or pick the template Unauthorized device (server) or Device country (server) from the template catalogue; the template appears whatever platform is selected. The dialog then shows the server sensor form:

  • Name, Description, Label, Severity and the notification channels, as for every sensor. Without a channel the event only appears on the Events page.
  • The kind.
  • Triggers: the situations the sensor reports. At least one is required.
  • The tenants the sensor covers, or All tenants (including tenants created later). Only accounts that are assigned to every existing tenant can select all tenants.
  • Schedule, thresholds, action script, suppression, the live test and the AI assistant do not apply and are not shown.

A server sensor is active as soon as it is saved; to stop it, delete it. A new or changed sensor takes effect within a minute. The kind of a saved server sensor cannot be changed, and a server sensor cannot be turned into an agent sensor or the other way round; duplicating one keeps its kind and triggers.

What every server sensor has in common.

  • It reports devices of the tenants it covers. A device without a tenant is never reported.
  • Each sensor that matches a device writes its own event with its own severity, notification channels and sensor id. Several matching sensors therefore write several events. Without a matching sensor, no event is written.
  • The events are delivered through the notification channels like any other sensor event.
  • Server sensors are never assigned to policies or automation rules and are never sent to agents. The Sensors tab of a policy does not offer them.
  • An account restricted to some tenants only selects tenants within its access. A server sensor that covers tenants outside the account's access shows a lock instead of its actions and cannot be edited or deleted by that account.
  • The public API lists server sensors read-only with serverSensor { allTenants, triggers }; they are created and changed in the web console (see X.9.9).

Unauthorized device

Writes an event of the type Device authorization when a new device registers, an authorized device is reinstalled, a device reports a changed hardware ID or the license limit takes an authorization away. The triggers, all selected for a new sensor:

  • New device awaiting authorization: a new device registered and waits in the unauthorized devices list (see Chapter 3.2).
  • Authorized device reinstalled (new access key): a reinstalled agent took over an authorized device under a new access key.
  • Hardware ID changed: an authorized device reported a different hardware ID; the server stores the new ID and the device stays authorized.
  • License limit reached: the license limit check took the authorization away.

A device that ends up authorized automatically is not reported, and neither is a device an administrator deauthorizes by hand. Hardware ID changed is the one trigger of this kind whose device stays authorized, and its event says so; the other events name the device, its tenant and where to approve it.

Device country

Reports devices by the country of the address they connect from. The measure is the server list of the country restriction under Settings → Security → Country restriction; the sensor has no country list of its own. The form shows the current server list read-only as flags, states whether the restriction for the server is on or off, and offers a link to the settings page to accounts that may open it. Addresses from private networks are never looked up and never count, for any trigger.

The triggers:

  • Device connects from a country outside the list (restriction off): outside_countries. For the monitoring mode: the server list is maintained, but its switch is off. A device that checks in from a country outside the list keeps working, and an event is written. This shows which devices a restriction would cut off before it is turned on. An address the GeoIP database has no country for counts as outside only when Allow addresses the GeoIP database has no country for is off; the event then names the country as unknown.

  • Device refused by the country restriction (restriction on): refused. The switch of the server list is on and the server refused a request because of its country. The server identifies the device from the refused request: its access key and hardware ID must match an authorized device. The request is answered with 403 at once; the event is written in the background. A refusal event is only written while the restriction for the server is on. The event states that the device cannot sync until its country is added to the server list or the restriction is turned off.

    Requests without such an identity (browsers, the Relay App, the Console App, unknown or unauthorized devices) produce no event and are visible only in the log and in the connection statistics. A device installed in a refused country for the first time has never registered with the server and therefore cannot be reported.

  • Country of the device changed: country_changed. Independent of any list; see below.

A new sensor has the first two triggers selected. country_changed is not selected by default, because roaming laptops and phones report many changes. While the server list is empty, outside_countries and refused cannot fire and the form shows a warning; country_changed still reports.

Reporting once, not on every check-in. Each device is reported once per country and trigger: a device that stays outside the list is not reported again at every check-in. The report is re-armed when the device checks in from a listed country. Even then, the same country is reported again no earlier than 24 hours after the last event for it, so a laptop that switches its VPN back and forth is reported at most once a day. A move to another country outside the list is reported at once. When an administrator turns the restriction on for a device already reported as outside, the refusal is reported again, because the device now stops working.

Country changed. The server keeps the last known country of every device and compares each check-in with it; a refused request of an identified device is compared as well.

  • Only a country the GeoIP database resolves counts. A check-in from a private network or from an address without a country is not a change and leaves the last known country as it is, so Germany → (office LAN) → Germany reports nothing, and Germany → (VPN into the server network) → United States reports one change.
  • The first check-in with a known country records the country without an event. A newly registered device and a reinstalled agent also only record their country.
  • A move back and forth between the same two countries is reported once per 24 hours: Germany → United States reports, United States → Germany and further moves between these two within 24 hours do not; after 24 hours the next move between them is reported once. Germany → United States → France reports both moves.
  • An update of the GeoIP database can assign an address to another country; affected devices then report one change.

A device that moves into a country outside the list, covered by a sensor with both country_changed and outside_countries (or refused), raises two separate events: the change from the old to the new country and the fact that the new country is not listed.

The state is kept per device, not per sensor. A sensor created after a device has been reported does not report that device again for the same country; the first sensor created reports devices that are already outside the list at their next check-in.

The events have the type Device country and are reported by Device country. Their titles read, followed by the sensor name in brackets:

  • Device connected from a country outside the allowed list: United States (US).
  • Device refused by the country restriction: United States (US).
  • Device changed country: Germany (DE) → United States (US).

The description lists the reason, the sensor, the new and the previous country, the external IP address, the allowed countries and the state of the restriction (or the tenant and location for a country change), the platform, the operating system and the agent version. Device country events also appear on the device's Events tab.

Update the Web Console before the server; until then the server evaluates no device country 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) gets its baseline on the next run without an alarm. 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) gets its baseline without an alarm; 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.
  • Agents without support for the placeholder report The registry key was not found: <hive>\{user_sids}\…; update the agent.

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 thresholds. Neither is a value limit: both count how many times in a row the sensor's condition has to be met (a hit) before something happens.

  • Notification Threshold Max: the number of consecutive hits after which the event is raised and the notifications are sent. 0 or 1 means on the first hit, 3 means on the third consecutive hit.
  • Action Threshold Max: the number of consecutive hits after which the configured action Script runs, counted the same way and independently of the notification threshold.

A run in which the sensor does not trigger ends the streak and resets both counters to zero, so a threshold of 3 only fires after three consecutive runs with a hit; a hit, a miss and two further hits do not reach it. Windows Eventlog sensors count each matched event as one hit, so several matching events found in one run advance the counters by that number; the action script itself still runs at most once per run.

The action section exposes a Script dropdown, populated from Scripts that match the sensor's Platform and runtime. When the action threshold is reached, the agent executes the selected script on the device that reported the hits. This is the usual pattern for "when the disk reaches 95%, run the cleanup script": the percentage is the sensor's own condition, the thresholds decide after how many consecutive breaches the script runs.

Sensor threshold configuration with Notification and Action Threshold fields

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

Attachment

Agent sensors attach to policies through the Sensors tab of Policy Settings (see Chapter 6.10), or to the devices an automation rule matches, in addition to 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. Server sensors are not attached anywhere; they apply to the tenants they cover.

Permissions (Sensors)

  • collections_enabled, collections_sensors_enabled, collections_sensors_add, collections_sensors_edit, collections_sensors_delete. Server sensors use the same permissions, limited to the tenants of the account as described under Server sensors.

8.4 Custom Fields

Manage Custom Fields at /manage_custom_fields is the library of Custom Field definitions. Custom Fields can add whole tabs and sections to the device detail page, filled from several data sources.

Manage Custom Fields list with Tabs count column

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

The builder dialog

One dialog, the Custom Field Builder, handles both Add and Edit. The builder is a visual editor with several panels in which you design a whole part of the device detail page.

Custom Field Builder with left panel, tab list, and section editor

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.
  • 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.

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 outside this rule 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). 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.
    • Direct SQL: lets you enter SQL directly, with {device_id} as the available placeholder (bound as a parameter).

    Both modes, and the preview in the builder, run only over the MySQL user configured under Settings → SQL access; the visual builder lists exactly the tables and columns that user can read. On save, the statement is checked with EXPLAIN over that user and MySQL's message is shown when it is refused. Without SQL access, the builder shows a notice with a link to Settings → SQL access and offers neither the query builder, the SQL field nor the AI SQL assistant, and existing SQL fields show (SQL access not configured) on the device page. Creating and editing such fields needs collections_custom_fields_add / collections_custom_fields_edit. See Set up SQL access for reports, dashboards and custom fields.

Section Action Buttons. Each section can carry its own buttons, with the same shape as Header Action Buttons but scoped to the section. Use them for actions that belong to the data shown in that section.

Scope and inheritance

Values are stored per device: every device covered by 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 Manage tenant page (Tenants → tenant → Manage).
  • Location: the Custom Fields section on the Manage location page of the location.
  • Group: the Custom Fields section in the group's edit dialog.
  • Global: Settings → Custom Fields, section Global values.

Custom field values on tenant level with effective value and source

Note: On the Manage location 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 outside the naming rule is marked with the environment name scripts 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 section 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 hold it.
  • 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 shows 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. This needs SQL access.
  • Reports do not expose custom-field values as a selectable data source in the Report Builder. Custom fields appear in Reports only as optional, cosmetic key-value entries on the cover-page footer of a brand template. To include custom-field data in a report, write a direct SQL query against the underlying storage; this needs SQL access (see Chapter 11.3).

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 of installable packages. This page maintains the list of available apps; Software Deployment installs them on devices (see 8.8).

Manage Apps catalogue with source chips (winget, flatpak, chocolatey, script)

List columns: Icon, Name, Publisher, Version, Source (colour-coded chip: winget, flatpak, chocolatey, script, file), Target OS, and per-row Edit and Delete actions. A file app whose file is missing on the File Server or was changed there outside of NetLock RMM is marked File missing or File changed next to its source chip.

For winget, Chocolatey and Flathub apps the Version column shows the current version from the synced catalogue, not the version recorded when the app was added; hovering the version shows the recorded one when the two differ. Apps that are not in the catalogue (for example a winget app from the msstore source or a Chocolatey app from a private feed) keep the recorded version, shown dimmed. Script and file apps always show their own Version.

Sources

Five sources 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.
  • File from the file server: manual entries that run an installer file uploaded to the File Server (.msi, .exe, .msu, .ps1, .deb, .rpm, .sh, .pkg) with parameters per action, a required detection script and the SHA-512 of the file pinned in the app. See Deploy an installer file from the file server.

Adding an app manually

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.
  • File from the file server: Choose file (with its SHA-512), Install arguments, Update arguments, Uninstall (None, This file with arguments, Script) with Uninstall arguments or the uninstall script, the Detection Script (required) and the detection window. The target system follows the file type. Choosing or changing the file needs file_server_enabled; such apps always run with elevation.

The Edit App dialog presents the same fields pre-populated against an existing entry. The Version field is only shown for script apps; for winget, Chocolatey and Flathub apps the version follows the catalogue.

On Windows, Linux and macOS, 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. 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 and 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). The script 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, the script runs 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. A result that is 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 from a catalogue browser

Winget, Flathub and Chocolatey each have a browser dialog: 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.

Winget Catalog Browser with a selected app previewed

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 pulls the latest catalogues from NetLock; the catalogue browsers and the Version column of package-manager apps then show the new data. The catalogues are only used for browsing and display: agents install and update winget, Chocolatey and Flatpak apps with the newest version the package manager offers on the device, unless a software deployment pins a version.

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. Selecting apps in the policy only decides what the tray offers; it does not install anything.

Permissions (App Hub)

  • collections_app_hub_enabled: see the App Hub page.
  • collections_app_hub_add: add a manual app. A file app additionally needs file_server_enabled.
  • 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.

Application Control Rulesets tab with three rulesets listed

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 buttons 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). A process is allowed as soon as one attribute of a rule matches, and only attributes whose filter is active in the policy count, so a value in a field whose filter is off has no effect:

File attributes:

  • File Path: exact absolute path to the executable, or a folder rule ending in \* (see Folder rules).
  • 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 at least one attribute that is filled in and whose filter is active equals the value of the running executable. Empty fields and - are skipped. Path and hash values ignore upper and lower case; version-info values are case-sensitive and ignore leading and trailing spaces; Certificate Owner and Certificate Issuer match when the rule's value is contained in the certificate's. Certificate Begin, Certificate End, Certificate Public Key and Certificate Serial Key are stored with the rule for information and are not compared. Any executable not matched by any rule in a ruleset attached to a device is blocked.

Saving a ruleset, approving blocked applications into it and deleting it sync the devices of the policies that use the ruleset right away.

Tip: A SHA256 or SHA512 hash rule is the strongest form and does not need other fields. Path-only rules are the weakest, because any file at that path matches, whatever its contents. File Product and File Company are tolerant of updates but weaker than a hash or a certificate, because whoever builds a file can set these values freely.

Folder rules

A File Path value ending in \* covers the folder and all its subfolders, for example C:\Program Files\*. C:\Program Files and C:\Program Files (x86) are separate folders and need one rule each. A value without \* stays one exact path. No other wildcards exist.

Folder rules require agent 3.3.0.11 or later. Older agents treat the value as an exact path that never matches, so they keep blocking.

Both exact paths and folder rules are compared in normalized form: short (8.3) names, .., forward slashes and the \\?\ prefix make no difference. Machine-wide environment variables such as %ProgramFiles% are expanded. Variables of a user profile such as %LOCALAPPDATA% are not supported, because the agent runs as SYSTEM and would resolve them to its own profile.

The agent ignores a folder rule on a drive root (C:\*), on a network share root, or in \Users\. It writes the reason to its Application Control log, which is only written in debug mode, and a blocked application's event states how many rules were ignored.

A folder rule does not allow a file if the file or any folder from there up to the rule's folder can be changed by non-administrators, or if these permissions cannot be read.

Accounts that count as administrators are SYSTEM, the local Administrators group, TrustedInstaller, the built-in Administrator, Domain Admins and Enterprise Admins. An owner outside this list counts as a non-administrator, because an owner can always change the permissions. Some applications create subfolders below Program Files that normal users can write to; a file there is blocked unless another rule allows it, and the event names the folder rule that was not applied. A change of these permissions takes effect within five minutes, or when the agent loads the ruleset again.

Blocked Applications tab

When the agent blocks a launch attempt, the attempt is logged and appears 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 through 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.

Device Control Whitelist tab with approved entries at various scopes

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.

Entries a device learned during its learning period have the scope device and the author Auto-Whitelist (Agent: <device name>); see Chapter 6.8. The author shows the device's current name, so it follows a rename of the device the same way Scope Target does; for an entry whose device was deleted, the name the device had when the entry was learned is shown.

The Device ID encodes vendor-id, product-id and serial number. Together they identify a specific USB device, or a specific model, depending on how the entry is scoped.

Re-learning connected devices on several devices

Re-learn connected devices above the whitelist opens a list of the devices a re-learn can be requested for: the Windows computers of your tenants whose policy has Device Control on. Search by device, tenant, location or policy, tick the devices or use Select all shown, then start the re-learn with Re-learn on N device(s). Each selected device learns the devices connected to it again, for the learning period of its policy, starting at its next policy sync. This works like Re-learn connected devices on the USB Devices tab of a single device.

A run takes at most 500 devices. After the confirmation and, where it is set up, the additional sign-in confirmation, each selected device is checked against your tenant access before its re-learn is stored. Devices that are no longer Windows computers with Device Control on in their policy are skipped. The first 25 devices are told to sync right away; the others start at their own next regular policy sync, so not every device learns at the same moment. The button shows the progress, and a summary names how many devices were requested, skipped and delayed. Each device that got the re-learn is written to the audit log. The button is shown only with the permission devices_usb_learning.

Blocked Devices tab

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

Blocked Devices tab with pending rows and the approval menu open

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 (disabled, disabled_pending_reboot, disable_failed, logged; their meaning is in Chapter 6.8), Status chip (Pending, Approved, Dismissed), and a context-menu actions column.

Approving a device

Whitelist entries cannot be created in a dialog of their own. They are added in two ways: a device learns the devices connected to it during its learning period (see Chapter 6.8 and the USB Devices tab of a device), or an administrator approves 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. Offered only to accounts with access to all tenants.
  • 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. The choice follows from the approval: the pending row carries the device's actual identifiers, and the resulting whitelist entry takes them over.

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_enabled and collections_device_control_enabled: open the page with both tabs.
  • collections_device_control_manage: approve a blocked device and switch a whitelist entry on or off.
  • collections_device_control_delete: delete whitelist entries and dismiss blocked devices.
  • devices_usb_learning: re-learn and end learning on a device from its USB Devices tab (see Chapter 3.3), and re-learn on several devices at once from the Whitelist tab (see above). This permission belongs to the Devices group.

8.8 Software Deployment

Software Deployment installs, updates and removes App Hub packages on devices. The feature has three routes:

  • Software Deployment at /software_deployment: the list of deployment jobs.
  • New Deployment at /software_deployment/new: the four-step creation wizard.
  • The deployment detail page at /software_deployment/{id}: the detail view for a single deployment job.

Deployments are started on demand, not by policies. Each deployment is created, run and tracked as a job of its own; Policy Settings has no deployment tab.

The deployment list

Manage Deployments list with progress and error chips

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 that are available for deployment appear in the wizard; apps added in the console always are. 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.

New Deployment wizard Step 1 — Packages

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: Options. Per-deployment settings:

  • Start date (optional) and Start time: when execution may begin.
  • Expires at (optional) and Expires time: when unstarted targets are abandoned.
  • 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 remaining packages on first failure: on a device, skip the remaining packages after the first package that fails.
  • Max attempts per device: the most attempts a target gets, the first one included.
  • Backoff between retries (minutes): minimum minutes between retries.

The wizard creates deployments that run in the background (bulk). Deployments with real-time feedback (interactive) come from the single-device Deploy Software dialog.

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

The detail page

Deployment detail page with four status cards and per-device table

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 the 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 attempt history is shown in the per-device results dialog. The items table lists the packages of the deployment with their action; its Arguments column shows the arguments of a file item and the winget switches of a winget item.

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 (the file of a file app: 60 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.

Use this view to analyse failed deployments. Exit codes and stderr tails show whether the failure is a package problem, a permissions problem or a temporary network issue.

Retry and the Retry button

The Retry button on the detail page re-queues every failed target in the deployment. Retries respect Max attempts per device and Backoff between retries (minutes) from the original configuration and increment the attempt counter. Successful targets are not touched. To recover from failures, fix the cause, then press Retry.

Ad-hoc single-device deployment

The Deploy Software dialog is a compact single-device version 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 defines what can be installed; Software Deployment installs it. A deployment takes the metadata from App Hub (package identifiers per source, install and detection scripts, elevation requirement) and adds targets, scheduling, retry rules and per-device tracking.

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.