Skip to content

Managing Device Groups

A Device Group is a named collection of Windows deployment targets, each represented by a UNC Path. When you assign a Profile to a device group, ntkDeploy deploys the resulting Artifact to every path in that group.

This tutorial covers creating and deleting groups, managing UNC paths, configuring destination rules, running preflight checks, and understanding the device ownership grid.

Prerequisites

1. Navigate to Device Groups

Click Device Groups in the left navigation sidebar. The screen splits into two panels:

  • Left panel (320 px) — The Device Groups list, with an inline New Group Name / Description form at the top.
  • Right panel — Shows the paths and quick-add form for the selected group, or a prompt to select a group.

2. Create a Device Group

  1. In the left panel, type a name in the New Group Name field (for example, Building-A-Workstations).
  2. Optionally add a Description (optional) for context.
  3. Click Create Group.

The new group appears in the list below and is automatically selected, revealing the paths panel on the right.

Validation: If New Group Name is left empty, the create action is blocked and a snackbar reads "Enter a group name."

3. Add UNC Paths to a Group

UNC paths are the individual deployment targets within a group.

  1. Select a group from the left panel.
  2. In the right panel's path-entry row, type the full UNC path in the UNC Path field (for example, \\server\share\dept-configs).
  3. Optionally add a human-readable Label (optional) such as Building A – Floor 2.
  4. Click Add (or press Enter).

The path appears in the list below with a folder icon and its optional label.

UNC path validation errors

Error Cause Fix
Invalid UNC path: … Path does not start with \\ or is otherwise malformed Ensure the path begins with \\ and follows the format \\server\share[\subpath].
Snackbar with error detail Path field is blank or only whitespace Enter a valid UNC path before clicking Add.

Remove a path

Click the ✕ icon on the right of any path card to remove it immediately. There is no confirmation dialog — removal takes effect at once.

4. Configure a Group (Detail View)

For advanced configuration, click the Configure button (⚙️) in the group's paths-panel header. This opens the Device Group Detail screen with three tabs:

  • Device Paths
  • Destination Rules
  • Pre-Flight Checks

Tab 1: Device Paths

This tab lists all configured UNC paths with full ownership and status detail.

Path properties

Property Description
Status icon Shows the last-known reachability state. Grey (schedule) = never checked; green ✅ = reachable; red ❌ = unreachable or failed; orange 🔒 = permission denied.
UNC Path The path displayed in monospace font.
Label Optional human-readable label set when the path was added.
Last checked Relative time since the last preflight check (Just now, 5m ago, Never checked).
Ownership badge Displays one of: Assigned (a person is linked), Assigned – person unavailable (person record no longer resolvable), or No owner (unassigned).
Deploy blocked chip A red warning chip labelled Deploy blocked appears when a path has no owner. Deployment to this path is blocked until an owner is assigned — see Device Enrollment.
Owner display The display name and Peer ID of the assigned person, or Unassigned.

Assign a person to a path

Click Assign person… under any path to open the Assign person dialog. Use the Person Picker to search and select the responsible owner, then click Assign.

Bulk path operations

Use the toolbar buttons at the top of the Device Paths tab:

Button Action
Bulk Import Import a list of UNC paths from a file.
Assign People (bulk) Opens the Assign People (bulk) menu with three options: Assign selected/all (pick a person for all checked paths, or all paths if none are selected); Assign by label (match paths by exact label, assign one person); Import ownership CSV (upload a .csv mapping device keys to Peer IDs).
Check All Paths Runs a preflight reachability and write-permission check on every path in the group sequentially.

Select individual paths using the checkbox on the right of each card before using Assign selected/all.

Tab 2: Destination Rules

Destination rules control exactly where and how the Artifact file is written within each UNC path. Each path has its own rule card.

Field Description Example
Destination Folder Sub-folder relative to the UNC path root. Leave empty to write at root. Supports the {environment} token. \configs or \configs\{environment}
Destination Filename Filename for the written artifact. Supports {profile_name} and {environment} tokens. Defaults to appconfig.json. {profile_name}.json
Backup Strategy What to do with an existing file before overwriting. None, Backup (.bak), Rotate (keep 3 versions)
Overwrite Strategy When to overwrite an existing file. Always, If Newer, Never

After adjusting the fields for a path, click Save Rules on that card. A snackbar confirms "Destination rules updated".

Tip: Using {environment} in the Destination Folder lets you deploy profiles from multiple environments to the same share without filename collisions.

Tab 3: Pre-Flight Checks

Preflight checks verify that each path is reachable over SMB and is writable before deployment. Running these checks before a rollout prevents partially-completed deployments caused by network or permission issues.

Running preflight checks

  • Click Run All Checks (top-right of the tab) to test every path in the group sequentially.
  • Or click the ↻ (refresh) icon on an individual path card in the Device Paths tab to check that path alone.

Each check performs two steps:

  1. Reachability — Confirms the UNC path resolves on the network.
  2. Write permission — Confirms ntkDeploy can write a test file to the path.

When all checks complete, a snackbar reads "All preflight checks completed".

Interpreting results

Status value Icon Meaning
reachable / success ✅ green Path is accessible and writable — deployment can proceed.
unreachable / failed ❌ red Path is not accessible. Check network connectivity and share availability.
permission_denied 🔒 orange Path is reachable but the running user lacks write access. Review SMB share and NTFS permissions.
(never checked) ⏱ grey No check has run yet. Run a check before scheduling a deployment.

For persistent reachability failures see Connectivity Issues. Note that the connectivity gate must also be open before any deployment can proceed.

5. Edit a Group Name or Description

Group names and descriptions are set at creation time through the inline form. To rename a group:

  1. Delete the existing group (see below).
  2. Re-create it with the new name.
  3. Re-add the UNC paths.

Note: In-place rename is not currently available. Deletion and re-creation is the supported workflow.

6. Delete a Device Group

⚠️ Deletion removes the group and all its associated UNC paths. Existing Assignments referencing this group may be affected.

  1. In the left panel, click the Delete icon (🗑️) on the group card.
  2. A confirmation dialog reads:

    Delete Device Group
    "Are you sure you want to delete <name>? This will remove N UNC path(s) associated with this group."

  3. Click Delete to confirm or Cancel to abort.

Next Steps