If the scripts' users will be providing the necessary GPO information at the command line, having them input the hard-to-type GUID might not be an option. An alternative is to have the users provide the GPOs' friendly names; you can then obtain the corresponding GUID by using the GetGPObyName function, which Microsoft provides in the lib_commongpmcfunctions.js file in the Scripts folder. GetGPObyName uses the IGPMSearchCriteria interface to search all the GPOs in a domain and, on matching the friendly name entered, returns a GUID that the script can pass to GetGPO. However, GetGPObyName is a JScript function. If you'd rather use VBScript, you can write a VBScript version of GetGPObyName or use the GetGPOs, GPOName, and GPOGuid methods in the IADsTools COM object, which is part of the Win2K Support Tools. For more information about these methods, see the article "Scripting with IADsTools," April 2003, http://www.winnetmag.com, InstantDoc ID 38286.
Next, the script uses the GPMGPO object's GetSecurityInfo method to retrieve the permissions for the GPO. The GetSecurityInfo method returns a reference to a GPMSecurityInfo collection object, which the script assigns to the GPOSec variable. The GPMSecurityInfo object contains the set of permissions assigned to the GPO. The script then iterates through the collection and uses the GPMSecurityInfo object's Count property to count and return the number of permission entries in the collection.
To retrieve each permission entry, the script uses the GPMSecurityInfo object's Item property, which returns a reference to a GPMPermission object. After the script assigns this reference to the Ace variable, the script uses the GPMPermission object's Trustee property to access the GPMTrustee object. By calling the GPMTrustee object's TrusteeName property, the script determines the name of the user or group assigned to the current permission, then assigns the name to the PrincipalName variable.
The code at callout C in Listing 2 uses a Select Case statement to determine the security right assigned to that user or group. A GPO can have five different security rights, as defined in the IGPMConstants interface. The Select Case statement contains these five rights.
The first line in the Select Case statement tells the VBScript runtime engine to compare the Ace.Permission value (i.e., the GPMPermission object's Permission property value) to each case. When the Permission property value matches one of the five security rights, the script assigns a user-friendly description of that permission to the Perm variable. Finally, the script uses WSH's WScript.Echo command to output the user's or group's name and permission to the console screen.
Obtaining RsoP Reports
A useful feature of the GPMC is its ability to perform Group Policy logging and Group Policy planning. Using the GPMC interfaces, you can programmatically obtain the results from Group Policy—logging and Group Policy—planning sessions. For example, to obtain the results from a Group Policy—logging session, you need to use RSoP Windows Management Instrumentation (WMI) providers.
RSoPLogging.vbs, which Listing 3 shows, demonstrates how you can use the RSoP interfaces to execute a logging query and create a logging report in HTML format. The first few lines in the script create the GPM and GPMConstants objects. Next, the script uses the GPM object's GetRSOP method to create an instance of the GPMRSOP object. This method takes three parameters, the first of which specifies the RSoP mode. As the code at callout A in Listing 3 shows, one way you can provide this mode is to use the GPMConstants object's RSOPModeLogging property. If you were performing an RSoP planning session, you would use the RSOPModePlanning property instead. The second parameter specifies the path to the WMI namespace in which previous RSoP data reside. In this case, the parameter is a null string because no previous data exists. The last parameter is always 0.
After creating an instance of the GPMRSOP object, the script sets two properties—GPMRSOP object's LoggingComputer and LoggingUser properties—for the RSoP logging query. The LoggingComputer property specifies the name of the target machine (in this case, myworkstation), whereas the LoggingUser property specifies the name of the target user (in this case, Darren). Next, the script executes the logging query by calling the GPMRSOP object's CreateQueryResults method, which has no parameters.
Finally, the script calls the GPMRSOP object's GenerateReportToFile method, which takes two parameters. The first parameter specifies the type of report to generate (HTML or XML). The script uses the Constants object's ReportHTML property to specify an HTML report. If you prefer to receive an XML report, you can use the ReportXML property instead of the ReportHTML property. The second parameter specifies the pathname for the report.
The GenerateReportToFile method can return a reference to the GPMResult object. The GPMResult object has two properties—Result and Status—that you can use to determine when the report has finished running or failed to run successfully. However, in RSoPLogging.vbs, the generation of the report is the last task, so you don't need to know when the report is done. (You'll know the report is done when the script finishes executing.) Thus, the script doesn't store the reference to GPMResult.
GPMC Opens New Possibilities
The new GPMC interfaces are extremely flexible, powerful, and fairly well documented by Microsoft. They provide a lot more control over the Group Policy infrastructure than the Win2K native tools. If you create custom scripts and use them in conjunction with the scripts that Microsoft provides, you can automate most GPO management tasks.
End of Article
