Add User To Collection

Overview

Managing user 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 user it is two minutes. For two hundred users imported from a CSV, or for stacking inclusion rules across a dozen existing collections, the console approach quickly becomes the actual problem.

Add User To Collection (AUC) is a bulk wrapper around the three official SCCM membership rule mechanisms: direct member rules (one per user), 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 Device To Collection

AUC has a mirror tool that does the same thing for device collections instead of user 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 Device To Collection documentation for the device-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. AUC supports all three through dedicated tabs in the same window — pick the mechanism that matches your scenario.

AUC 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

AUC 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_User Read. Needed to resolve a SamAccountName or UserName to a ResourceID before adding it as a direct member.
• SMS_Collection (CollectionType = 1) 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 user 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, AUC 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, AUC picks them up automatically.

AUC 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 — AUC 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 User Collection picker. The picker queries SMS_Collection via WMI for collections with CollectionType = 1 (user 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 username per line. Accepted formats per line: plain SAM ("dnguyen"), DOMAIN\SAM ("CORP\dnguyen"), or any value that SCCM SMS_R_User accepts as UserName / UniqueUserName. Whitespace and blank lines are tolerated. Click Start and AUC processes the list sequentially — resolve to ResourceID, check for existing membership, add the direct rule, RequestRefresh, log.

Tab 2 — Paste User Names

For ad-hoc lookups: paste a list copied from Excel, an email body, or a ticket comment. Same accepted formats as Tab 1. 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", AUC 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 users 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 user who matches an include rule AND an exclude rule is excluded.

Pre-validation safety checks

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

• Idempotence For direct rules, AUC queries SMS_FullCollectionMembership: if the user is already in the target collection, the row is marked "⚠ Already In" and no rule is created. For include/exclude rules, AUC 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, AUC 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. AUC 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 user 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 username could not be resolved to a ResourceID via SMS_R_User. No write attempted. Common causes: typo, account in a different domain than the SCCM site code, or stale SCCM user 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

AUC writes a CMTrace-compatible log to C:\TEMP\AddUserToCollection.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

AUC 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 new business unit 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 AUC.

2. 2

   Click Select Collection and pick the target

   The User Collection picker opens. Filter by name, double-click the 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 foundational collections first

   For a new business unit, you typically want to inherit from broader groups. Pick "All Corporate Users" from the available list, move it to the right with >>, click Include Now. AUC creates the include rule and the target instantly inherits everyone in All Corporate Users.

4. 4

   Tab 4 — Exclude the carve-outs

   Move "Contractors", "Service Accounts", "Disabled Users" to the right and click Exclude Now. AUC creates three exclude rules; the target now contains "All Corporate Users minus those three buckets".

5. 5

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

   For users who must be in the target but who are NOT in the inherited collections (external auditors, on-loan staff, VIP guests), paste their SamAccountNames in Tab 2 and click Start. AUC creates one direct rule per user, the grid showing the per-user result.

6. 6

   Review the result grid and the CMTrace log

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

7. 7

   Verify in the SCCM console

   Because AUC 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. AUC 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 AUC 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 AUC — there is no concept of "multi-target campaign" in this tool.
• Sequential processing AUC processes one user (Tab 1/2) or one source collection (Tab 3/4) at a time. For a list of 500 users, 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.
• No AD lookup AUC takes usernames as-is and queries SMS_R_User directly. Unlike GPDEU/GPUED, it does not look up the user in Active Directory — there is no email resolution, no UPN-to-SAM conversion. The input must match what SCCM has discovered.

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. AUC uses native .NET System.Management to invoke WMI; no PowerShell shell-out, no Get-WmiObject indirection.
• RequestRefresh after every successful add AUC 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.
• User resolution fallback chain For direct rules, AUC tries three SMS_R_User queries in order: (1) UserName LIKE '%\\<sam>' to catch DOMAIN\sam values, (2) UserName = exact match, (3) UniqueUserName LIKE '%\\<sam>' as a last-resort fallback. The first non-empty result wins.
• 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 AUC 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).