Add Device To Collection

Overview

Managing device collection membership in SCCM by clicking through the console is a per-record exercise: open the collection, Add Resource, search, select, confirm, repeat. For one workstation it is two minutes. For two hundred devices imported from a CSV, or for stacking inclusion rules across a dozen existing collections, the console approach quickly becomes the actual problem.

Add Device To Collection (ADC) is a bulk wrapper around the three official SCCM membership rule mechanisms: direct member rules (one per device), include-collection rules (pull in every member of another collection), and exclude-collection rules (push out every member of another collection). Each addition is preceded by idempotence and circular-reference checks, every operation is logged in CMTrace format, and the collection is refreshed immediately so changes are visible in the SCCM console within seconds.

Sister tool — Add User To Collection

ADC has a mirror tool that does the same thing for user collections instead of device collections. The two are sold separately and licensed independently, but they share the same architecture, the same UI structure, and the same credentials.

See the Add User To Collection documentation for the user-side workflow. Mature SCCM teams license both to cover user-centric and device-centric campaigns from the same workstation.

The three types of membership rules

SCCM exposes three official mechanisms for adding members to a collection. ADC supports all three through dedicated tabs in the same window — pick the mechanism that matches your scenario.

ADC writes all three using the same SMS_Collection.AddMembershipRule() method documented by Microsoft, and calls RequestRefresh() on the target collection immediately after each successful add. Members appear in the SCCM console within seconds, not at the next scheduled collection evaluation cycle.

Prerequisites

Required SCCM permissions

ADC writes to SCCM collections — it is not a read-only tool, so the signed-in Windows user needs broader rights than for the lookup tools in the suite. The recommended grant pattern is the built-in "Operations Administrator" role scoped to the security scope that contains the target collections, OR a custom role with the following effective rights:

• SMS_R_System Read. Needed to resolve a device hostname to a ResourceID before adding it as a direct member.
• SMS_Collection (CollectionType = 2) Read + Modify Resource (the WMI permission that gates AddMembershipRule). The role must apply to the specific target collection or to a parent security scope.
• SMS_FullCollectionMembership Read. Needed for the idempotence pre-check (is this device already a member?).
• SMS_CollectionRuleDirect, SMS_CollectionRuleIncludeCollection, SMS_CollectionRuleExcludeCollection Read. Needed for the "rule already exists" idempotence check and for the circular-reference BFS walk on include rules.

Initial configuration

On first launch, ADC verifies the license, then asks for SCCM credentials via the standard TontonTools credentials dialog. Credentials are shared across the suite — if you already configured them for another tool on the same workstation and user profile, ADC picks them up automatically.

ADC only needs the SCCM section of the credentials dialog:

The SCCM Auto-detect button scans the local registry and WMI for a previously-configured SCCM console; if found, it pre-fills both fields automatically. See the Delete Device Everywhere documentation for the full SCCM auto-detect cascade. The Microsoft Graph and Active Directory sections of the credentials dialog can be left empty — ADC does not use them.

Main features

Select Target Collection (the first action of every session)

Above the tabs, a single "Select Collection" button opens the Device Collection picker. The picker queries SMS_Collection via WMI for collections with CollectionType = 2 (device collections), shows them in a searchable filtered list, and returns the chosen collection. This target collection is the destination for every operation in the session — File adds, Paste adds, Include rules, Exclude rules — until you change it.

Tab 1 — Import from File

Browse to a CSV or TXT file with one device name per line. Plain hostnames are expected ("WS-MIL36-042"); FQDN suffixes are tolerated and stripped automatically. Whitespace and blank lines are tolerated. Click Start and ADC processes the list sequentially — resolve to ResourceID, check for existing membership, add the direct rule, RequestRefresh, log.

Tab 2 — Paste Device Names

For ad-hoc lookups: paste a list copied from Excel, a ticket comment, or the output of a previous PowerShell query. Plain hostnames, one per line. Click Start to process. Results land in a separate grid from Tab 1 — you can build a session that mixes Tab 1, Tab 2, Tab 3, and Tab 4 against the same target collection, with each tab keeping its own results visible.

Tab 3 — Include Collections

Two side-by-side lists: "Available collections" (everything except the target itself) and "Selected for inclusion". Click >> to move a collection to the right; click << to remove it. When you click "Include Now", ADC iterates the right-hand list, runs both pre-validation checks per collection (rule already exists? circular reference?), then creates SMS_CollectionRuleIncludeCollection rules and refreshes the target.

From the moment the rule is created, SCCM keeps the target collection in sync with the source: new devices added to the source collection appear in the target at the next collection evaluation cycle, and removals propagate too.

Tab 4 — Exclude Collections

The mirror of Tab 3. Same side-by-side picker, same Include Now button (labelled "Exclude Now" here), but the result is SMS_CollectionRuleExcludeCollection. Exclude rules take precedence over include rules in SCCM: a device that matches an include rule AND an exclude rule is excluded.

Pre-validation safety checks

Before every write, ADC runs two pre-validation checks:

• Idempotence For direct rules, ADC queries SMS_FullCollectionMembership: if the device is already in the target collection, the row is marked "⚠ Already In" and no rule is created. For include/exclude rules, ADC scans the target collection's existing CollectionRules: if a rule pointing to the same source already exists, the row is marked "⚠ Already Included" or "⚠ Already Excluded".
• Circular-reference detection (include rules only) Before adding an include rule, ADC walks the include-graph rooted at the source collection using a breadth-first search bounded at depth 5. If the BFS reaches the target collection, adding the rule would create a cycle — SCCM refuses cycles silently with a generic WMI error. ADC catches it earlier with a clear "⚠ Circular Reference" status and skips the operation.

The nine result statuses

Every row in the result grid carries one of nine statuses, with consistent emoji prefixes that scan well in CMTrace logs and screen reading:

• ✅ Added Direct rule created successfully.
• ✅ Included Include-collection rule created successfully.
• 🚫 Excluded Exclude-collection rule created successfully.
• ⚠ Already In Direct rule skipped — the device is already a member of the target collection.
• ⚠ Already Included Include rule skipped — a rule pointing to this source already exists on the target.
• ⚠ Already Excluded Exclude rule skipped — a rule pointing to this source already exists on the target.
• ⚠ Circular Reference Include rule refused — adding this rule would create a cycle in the include graph. No write attempted.
• ❓ Not Found The device hostname could not be resolved to a ResourceID via SMS_R_System. No write attempted. Common causes: typo, device not yet discovered by SCCM, or stale SCCM heartbeat discovery.
• ❌ Error A WMI exception occurred during the write — typically a permission issue. The CMTrace log captures the verbatim WMI error message for troubleshooting.

CMTrace logging

ADC writes a CMTrace-compatible log to C:\TEMP\AddDeviceToCollection.log. Every operation is logged with timestamp, executing Windows user, severity, and verbatim WMI response. Open with CMTrace.exe (shipped with SCCM) for coloured real-time viewing. The log is cumulative across sessions — useful for an audit trail of membership changes spanning multiple campaigns.

License & read-only mode

ADC follows the TontonTools licensing model: 7-day cache + 7-day offline grace, then read-only mode. In read-only mode, every write button is disabled — Start (File), Start (Paste), Include Now, Exclude Now. The credentials dialog and the collection picker remain accessible so you can review your configuration. A persistent banner offers to enter a license key or contact support.

For the full licensing model — Trial mechanics, machine and tenant binding, moving a license between workstations, subscription cancellation behavior — see the Licensing reference.

Typical workflow — provisioning a patch wave collection

1. 1

   Configure credentials once

   Click 🔑 Credentials, fill in SCCM Site Server FQDN and Site Code. Use Auto-detect if you have the SCCM console installed locally. The Graph and AD sections can stay empty for ADC.

2. 2

   Click Select Collection and pick the target

   The Device Collection picker opens. Filter by name, double-click the new "Patch Wave 3" target collection, OK. The target name is now displayed above the tabs and will receive every operation in this session.

3. 3

   Tab 3 — Include the broader cohort

   For a patch wave, you typically inherit from a larger workstation group. Pick "All Windows 11 Workstations" from the available list, move it to the right with >>, click Include Now. ADC creates the include rule and the target instantly inherits everyone in All Windows 11 Workstations.

4. 4

   Tab 4 — Exclude what must not be patched yet

   Move "Pilot Machines (Wave 2)", "VIP Executives", "Lab Workstations" to the right and click Exclude Now. ADC creates three exclude rules; the target now contains "All Windows 11 Workstations minus those three buckets".

5. 5

   Tab 1 or Tab 2 — Add hand-picked machines on top

   For specific devices that must be in the wave but were not discovered yet by SCCM as part of the broader cohort (new hardware, recently re-imaged machines), paste their hostnames in Tab 2 and click Start. ADC creates one direct rule per device, the grid showing the per-device result.

6. 6

   Review the result grid and the CMTrace log

   Each tab keeps its own result grid for the session. Open C:\TEMP\AddDeviceToCollection.log in CMTrace for the full audit trail — every WMI call, every status, every error verbatim.

7. 7

   Verify in the SCCM console

   Because ADC calls RequestRefresh after every successful add, the SCCM console reflects all your changes within seconds. Open the target collection's Membership Rules tab — you should see your direct rules, include rules, and exclude rules side by side.

Limitations and design choices

• No query-based membership rules SCCM supports a fourth rule type — query-based rules with WQL filters. ADC does not create or manage query rules; for those, use the SCCM console or a PowerShell script. Direct/Include/Exclude rules cover the vast majority of bulk-membership scenarios.
• No rule removal ADC is an additive tool. It does not remove existing direct, include, or exclude rules from a target collection. For that, use the SCCM console or PowerShell. Future versions may add a remove path; for now, the design choice was to keep destructive operations explicit and out of scope for this entry-level tool.
• One target collection per session Every operation in a session writes to the same target collection. To populate multiple collections, run multiple sessions of ADC — there is no concept of "multi-target campaign" in this tool.
• Sequential processing ADC processes one device (Tab 1/2) or one source collection (Tab 3/4) at a time. For a list of 500 devices, expect a few minutes of run-time. Sequential processing keeps the CMTrace log readable and avoids overwhelming the SCCM SMS Provider with parallel writes.
• Circular-reference detection is bounded at depth 5 The BFS that detects cycles before include-rule creation walks up to 5 collection levels deep. In environments with extreme nesting (six or more cascaded include rules), a cycle might escape detection — but SCCM itself will refuse to evaluate the cycle and you will see a WMI error at write time. In practice, real SCCM environments rarely nest beyond 2-3 levels.
• Device must be discovered by SCCM first ADC resolves hostnames against SMS_R_System, which contains only devices that SCCM has already discovered via heartbeat, network discovery, or AD system discovery. A brand-new machine that has never reported in to SCCM cannot be added as a direct member by ADC. For provisioning fresh records, see Create Device In SCCM.

Technical notes

• WMI write method All three rule types are created using SMS_Collection.AddMembershipRule(rule) — the Microsoft-supported method documented in the SCCM SDK. ADC uses native .NET System.Management to invoke WMI; no PowerShell shell-out, no Get-WmiObject indirection.
• RequestRefresh after every successful add ADC calls SMS_Collection.RequestRefresh() immediately after each successful AddMembershipRule(). The target collection re-evaluates within seconds, so changes appear in the SCCM console without waiting for the next scheduled evaluation cycle.
• Device resolution For direct rules, ADC queries SMS_R_System with a single direct match: WHERE Name = '<hostname>'. Case-insensitive at the SQL Server backend. FQDN suffixes are stripped on input before query, so "WS-001" and "WS-001.corp.contoso.com" produce the same result.
• Circular-reference algorithm Breadth-first search starting from the source collection ID, following SMS_CollectionRuleIncludeCollection rules only (exclude rules cannot create cycles in this sense). Bounded at depth 5, visited HashSet to short-circuit re-visits. If the target collection ID is encountered during the walk, the rule is refused with status "⚠ Circular Reference".
• Credential storage DPAPI-encrypted under the current Windows user profile at %AppData%\TontonTools\credentials.dat — shared across all TontonTools products on the same user account on the same workstation.
• No telemetry, no agent ADC runs entirely from the administrator workstation. The only outbound connections are RPC to the SCCM site server and api.lemonsqueezy.com for license validation (at most weekly).