Creating a Collection

You use SMS_Collection to define the attributes of a collection, such as the membership rules and the refresh schedule. The MemberClassName property contains the system generated class name that contains the members of the collection.

Members of the collection are specified using direct rules, query rules, or both. Direct rules define an explicit resource, whereas query rules define a dynamic collection that is regularly evaluated based on the current state of the site.

You use the SMS_CollectionRuleDirect class to define direct rules. This approach is used for resources that are static in nature. For example, if you have a limited number of licenses for a particular software application, you should use direct rules to advertise to specific computers or users.

You use the SMS_CollectionRuleQuery class to define query rules. The query you specify must be valid (see ValidateQuery). You can use the query to specify that the collection contains resources such as "All computers running Windows NT 4 Service Pack 3 (SP3) with at least 16 MB of RAM," or "All users in the Corporate domain." You can use the query as a guarantee that a program is targeted for software distribution to all computers that meet the criteria. As the site changes and the collection is reevaluated, members of the collection are automatically added and deleted.

Rules are added to a collection using the AddMembershipRule or AddMembershipRules methods. For information on the membership methods, see Adding, Deleting, and Refreshing Members of a Collection.

The following example creates a collection of engineering clients using the OrganizationalUnit property that was created by the example in Adding New Properties to an Existing Resource Type.

    Dim instCollection As SWbemObject            'Instance of SMS_Collection
    Dim instCollectionPath As SWbemObjectPath    'Path to the created collection
    Dim instCollToSubColl As SWbemObject         'Instanc of SMS_CollectToSubCollect_a
    Dim clsQueryRule As SWbemObject              'SMS_CollectionRuleQuery class method
    Dim instQueryRule As SWbemObject             'Instance of SMS_CollectionRuleQuery
    Dim instDirectRule As SWbemObject            'Instance of SMS_CollectionRuleDirect
    Dim Rules() As Variant                       'Array of rules for AddMembershipRules
    Dim Query As String
    Dim ValidQuery As Boolean
    Dim i As Integer

    'Create the collection.
    Set instCollection = Services.Get("SMS_Collection").SpawnInstance_
    instCollection.Comment = "This is the root engineering collection that contains all engineering clients."
    instCollection.Name = "All Engineering Clients"
    instCollection.OwnedByThisSite = True
    Set instCollectionPath = instCollection.Put_    'Save the collection path for later

    'Add a query rule and a direct rule for the collection. Always validate the query
    'before adding it to the collection rules. If it is important to your design,
    'you may want to validate the query before creating an instance of the collection.
    'Note that OrganizationalUnit was added to the SMS_R_System class in a previous
    'example. For details, see the link preceeding this example. You can substitute
    'OrganizationalUnit for any valid SMS_R_System property. For example, substituting
    'SystemRoles = "SMS Client Access Point" creates a collection of CAPs defined for
    'the site.

    Query = "SELECT * FROM SMS_R_System WHERE OrganizationalUnit = 'Engineering'"
    Set clsQueryRule = Services.Get("SMS_CollectionRuleQuery")
    ValidQuery = clsQueryRule.ValidateQuery(Query)

    If ValidQuery Then
        ReDim Rules(1)  '(0 to 1) array must contain exact number of objects
        i = 0

        'Create the query rule.
        Set instQueryRule = clsQueryRule.SpawnInstance_
        instQueryRule.QueryExpression = Query
        instQueryRule.RuleName = "All Engineering Clients"

        Set Rules(i) = instQueryRule
        i = i + 1

        'Create the direct rule.
        Set instDirectRule = Services.Get("SMS_CollectionRuleDirect").SpawnInstance_
        instDirectRule.ResourceClassName = "SMS_R_System"
        instDirectRule.ResourceID = <ID>

        Set Rules(i) = instDirectRule

        'Add the rules to the collection
        Set instCollection = Services.Get(instCollectionPath)
        instCollection.AddMembershipRules Rules

        'After you have added all the membership rules, call RequestRefresh to initiate
        'the collection evaluator.
        instCollection.RequestRefresh False

        'You must define to what collection the new collection is subordinate.
        'If you do not specify the relationship, the collection will not be visible
        'in the console. Also, populating SMS_CollectToSubCollect_a populates
        'SMS_CollectToSubCollect. Which one you populate is arbitrary.
        Set instCollToSubColl = Services.Get("SMS_CollectToSubCollect").SpawnInstance_
        instCollToSubColl.parentCollectionID = "COLLROOT"
        instCollToSubColl.subCollectionID = CStr(instCollectionPath.Keys("CollectionID"))
        instCollToSubColl.Put_
    End If