How to Report Package Installation Status
By Bruce Jones, Microsoft Corporation
On This Page
Overview
Customizing Your Installation Routing to Create Status MIFs
ismifx.exe Syntax
Viewing PCM Status MIF Results
Creating Reports
Overview
To determine which workstations have successfully installed software through a run command on Workstation Job, access the Jobs window, select the appropriate job, click the Status button in the Jobs Detail window, and select Details. Workstations where the job has not yet run will display None under Status. Workstations that have successfully launched the Package Command Manager (PCM) command line (whether or not the package install finished) will show up as Complete. Workstations that fail to carry out the command will display Retrying under Status. When the site components have stopped retrying, the workstations will display Failed under Status.
After Package Command Manager (PCM) carries out the command, the word Complete under Status indicates that PCM successfully ran the command line but it does not indicate whether installation failed. To obtain this information, Systems Management Server creates PCM status MIFs during and after the installation process to provide custom information. Systems Management Server provides this information in PCM status MIFs that are available during and after installation.
The status MIF is created in the Windows directory of the client. PCM will pick up.mif files in the Windows directory that have a date\time stamp after PCM launches the job on the client. Therefore, you must create the MIF after PCM runs the job, but before it finishes. The Microsoft BackOffice Resource Kit includes a program that can create an MIF called Ismif32.exe (or Ismif16.exe for 16-bit platforms). But because Systems Management Server only tracks "failure events," it is necessary to specify the –s 0 parameter. Through using logical conditions when calling Ismif32.exe, a specific description can be created for each type of failure. In addition, a failure event can be created to report a successfully completed installation. Through creating a query on Systems Manager Server events, you can view the exact status of your workstation installs.
Note: You should be aware that although this process is not harmful, it will cause the job status details for workstations to display Retrying as described in the Microsoft Knowledge Base article 166833, "Failed Status MIF Does Not Update Job Status." In addition, if the package execution fails before the execution of the first ISMIF32, the job status will display as Complete. This status is incorrect. It is suggested that you consider the status as a failed job and investigate the problem.
Customizing Your Installation Routing to Create Status MIFs
To create the installation routine for your software:
Decide beforehand what conditions you will check to obtain details on why a particular installation failed.
Create your package, including ismif32.exe or ismif16.exe as appropriate, from the Microsoft BackOffice Resource Kit in the Source directory.
Ensure that your package installs correctly using PCM to carry out your command.
Create a batch file, System Management Server Installer script, or other routine that will call your command.
Include in the installation routine tests for the failure conditions you want to report with a corresponding call to ismif32.exe. Each failure condition will have its own file name and description. Be sure to begin each description with the same string because you will use this later in your select query. In the following example, "Status:" is used. Use different file names or each successive call to ismif32.exe will produce an MIF that will overwrite the previous MIF.
ismifx.exe Syntax
ismif32 -f filename -s 0 -d "description"
-f Filename
Specifies the name of the MIF file that will be created. An .mif extension is automatically appended.The default name is SETUP.MIF. If you use a different file name for each logical condition, you can create multiple MIFs reporting more than one type of failure.
-s Success
Zero or one. One means success. You want to specify failure because the description attribute is used only if the status is Failed (see page 133 of the Microsoft Systems Management Server Resource Guide).
-d Description
This option specifies a text string that corresponds to the vSMSEvent view as the column String_3. Specifies why the installation failed.
Note: The other text strings documented on page 188 of the Microsoft Systems Management Server Resource Guide Supplement are not used with failure MIFs.
Sample Installation Routine Using a Batch File
REM This batch file assumes that ISMIF32.EXE from the BackOffice Reskit REMwas included in the package REM Call the installation executable for the application REM (this batch file uses the same name for all status MIFs as the logic prevents REM more than one MIF from being written.) REM (this batch file assumes an application, install.exe, that installs first.txt, REM middle.txt, and last.txt) INSTALL.EXE REM Check to see if we finished installing all files IF EXIST C:\test\last.txt GOTO :ALLFILES REM Check to see if the first file was installed IF NOT EXIST C:\test\ first.txt GOTO FIRST REM Check to see if half the files were installed IF NOT EXIST C:\test\middle.txt GOTO BEFORMID REM Check to see if we failed after midpoint and before we installed all our files IF NOT EXIST C:\test\last.txt GOTO AFTERMID :ALLFILES ismif32 -f status -s 0 -d "Status: All files successfully installed" GOTO DONE :FIRST ismif32 -f status -s 0 -d "Status: Failed before installing first file" GOTO DONE :BEFORMID ismif32 -f status -s 0 -d "Status: Failed after installing first file, before midpoint" GOTO DONE :AFTERMID ismif32 -f status -s 0 -d "Status: Failed installing files after midpoint" GOTO DONE :DONE
Installation Routine Using the Systems Management Server Installer
The Systems Management Server Installer makes generating status MIFs fairly easy. Other checks, such as successful .ini updates, service installation, and so on can be done in the same manner. This script is capable of generating multiple status MIFs for a single installation because each condition creates an MIF with a different name. In the example, if both the registry update and a file copy fail, both would be reported. The following sample script checks for successful file installation and registry updates.
Notes for Systems Management Server Installer Script
Lines 1 through 2: These lines are a necessary part of any script.
Line 3: It is necessary to include ismif32.exe somewhere in the path. Either put it in each package or install it once in the System32 directory. This directory is in the local machine path.
Lines 4 through 6: Install the application files.
Line 7: Obtains the currently logged on user environment variable and assigns it to a variable. To view available environment variables, type set at a command prompt.
Line 8: Obtains the computer name from the registry and assigns it to a variable.
Line 9: Registry values can be added by selecting the User Configuration and Registry Keys options in the Installation Expert dialog box, or by selecting the Edit Registry Action in the Script Editor dialog box.
Line 11: This line can be commented out but was used during testing to display the variable value. To comment out, click the /* button on the toolbar.
Lines 12 through 16: Test to see if the registry update in line 3 failed.
Line 13: After each test, keep track of whether or not the preferred action failed. This record will indicate whether, at the end of the script, a PCM status MIF needs to be created including a description of whether it was successful. In this example, the variable was arbitrarily named STATUS to FAILED if the registry Value Name testvalue was not found.
Line 14: If you failed to update the registry, have the Installer run ismif32.exe with the appropriate parameters. Notice that you can include the variables in the description parameter, and that the Wait for Program to Exit check box is selected.
Line 16: Use the Script Editor Action Item End Block to end the check and see if the registry was updated.
Line 17: Use the Script Editor Action Item Check If File/Dir Exists to see if the application files were installed.
Line 19: Notice that you change the name of the status MIF to "files." This prevents overwriting any MIF generated if a registry update failed, and both MIFs will be reported if both failure conditions are met.
Line 21: Use the Script Editor Action Item Else Statement.
Line 29: If no tests failed, execute ISMIF32.EXE with a description that confirms a successful installation.
Note: After version 1.00.07.000, SMS Installer executables refresh their status MIF just prior to exiting. This prevents any status MIF created manually (i.e. a registry key wasn't updated and you tested for this in the Installer Script, and ran ISMIF32 if it was not what it should have been...) from being the newest file. The results in it is ignored (PCM always picks up the latest one - the one generated automatically at exit).
PCMWIN.LOG displays the following:
Executed process terminated, cleaning up
No error was detected while attempting to run the job
Need to report with DMTF MIF: C:\WINNT\mif
Writing status information to \\SMSLOGONSERVER\SMS_SHRx\despoolr.box
This has been fixed in the newer versions of the SMS Installer.
Viewing PCM Status MIF Results
There are three steps that need to be completed to view the results of PCM status MIFs in the Systems Management Server Administrator user interface (UI): creating the query, creating the query result format, and executing the query. Notice that for this process to be successful, the description parameter for all status MIFs must begin with "Status:"
To create the query
Open the Queries window.
On the File menu, click New.
Type the properties as follows:
Query Name: Status of Run Command Jobs
Comment: Provides a detailed list from the PCM Status MIF of the installation status of a particular Run Command Job.
Architecture: SMSEvent
Find all 'SMSEvent' items where: MICROSOFT|IDENTIFICATION|1.0:String_3 is like 'Status:%'
(Select Add AND, String_3, Operator 'is like', enter Value 'Status:%' - do not include the single quotes, click OK)
You may want to add Find all items where JobID is <prompt for identification> (selected from the dropdown box)
To create the query results format
Open the Define Query Results Format window.
Type the properties as follows:
Architecture: SMSEvent
(Select New)
NameStatus of Run command jobs.
(From the available columns, select the following, and click Add to Format in whatever order you desire. You can rearrange with the Up, Down buttons)
JobID: The Job ID of the job you are tracking.
Time: The time the MIF was created at the target computer.
String_1: The SMSID of the target computer.
String _3: The description entered by ismif32.exe in the mifmkr.bat file.
Note: The selections for MachineName and SMSID do not refer to the target; PackageID does not return a value.
Click OK to save the format.
To execute the query
Select the query you created called Status of Run Command Jobs.
On the File menu, click Execute Query.
Select the query result format you created called Status of Run Command Jobs.
Enter the JobID when prompted, if you selected this option, or '%' will return all jobs (do not enter the single quotes).
Creating Reports
You may be responsible for providing reports showing the results of your package distributions. Systems Management Server provides you with a variety of options for creating your reports. You can create reports using SQL queries, MSAccess, Crystal Reports, or any other tool that can access the views Systems Management Server provides.
Creating Views in the Database
If you have tried to create reports based on the existing tables in your Systems Management Server database, you may have had difficulty trying to determine the relationships among the tables. Microsoft provides a utility with Systems Management Server called SMS SQL View Generator. This utility creates views that combine information from various tables into a single view. These views can be accessed like a table, and provide an intuitive source for your reports. It is important to run this utility after there have been changes made to the tables by adding new groups (a new MIF Entry Form group that displays as a new icon in your computer properties). If the utility isn't run, these new groups will not be added to your view (see pages 303-305 in the Administrators Guide).
SQL Queries for Creating Package Distribution Reports
The following queries will help you create meaningful reports for your package distributions. Some of these queries depend upon your having followed the instructions for PCM status MIFs earlier in this document. Specifically, you must have included "Status:" at the beginning of your description parameter.
Query for PCM Status MIF Information from Each Workstation
PRINT " Detailed Status Report of Run Command Package Installations" PRINT "" ---Reports totals for PCM Status MIFs. These are event MIFs created ---after the command line has run. This will report errors that occur ---even after a status of 'complete' appears in the job details. These ---events must be customized by the installation routine for the package, --- in conjunction with the BackOffice Reskit utility ISMIF32.exe. The --- description string must begin with 'Status:'. SELECT JobID0 JobID, String_1 SMSID, String_3 Status, Time FROM vSMSEvent WHERE String_3 LIKE "Status:%" ORDER BY JobID0, String_3, String_1, Time
Sample Output
Detailed Status Report of Run Command Package Installations JobID SMSID Status Time ---------- ----------------------------------------------------------------------------------- S010004C S0100001 Status: All files successfully installed Oct 15 1997 12:24PM S010004C S010000A Status: Failed after halfway point Oct 14 1997 3:49PM S010004F S010000A Status: All files successfully installed Oct 15 1997 1:57PM S010004F S0100001 Status: Failed after first file, before midpoint Oct 15 1997 3:17PM S010004F S010000D Status: Failed after first file, before midpoint Oct 15 1997 3:10PM S010004F S010000C Status: Failed after installing first file Oct 15 1997 3:22PM
Query for Summary of PCM Status MIF Information
PRINT " Summary Status Report of Run Command Package Installations" PRINT "" --- Reports totals for PCM Status MIFs. These are event MIFs created --- after the command line has run. This will report errors that occur --- even after a status of 'complete' appears in the job details. These --- events must be customized by the installation routine for the package, --- in conjunction with the BackOffice Reskit utility ISMIF32.exe. The --- description string must begin with 'Status:'. SELECT JobID0 JobID, COUNT(String_3) total, String_3 Status FROM vSMSEvent WHERE String_3 LIKE "Status:%" GROUP BY JobID0, String_3
Sample Output
Summary Status Report of Run Command Package Installations JobID total Status -------- ----------- ----------------------------------------------------- S010004C 1 Status: All files successfully installed S010004C 1 Status: Failed after halfway point S010004F 1 Status: All files successfully installed S010004F 2 Status: Failed after first file, before midpoint S010004F 1 Status: Failed after installing first file
Query for Same Information that Appears In Job Details for Workstations
PRINT " Detailed Status Report of Run Command Package Distributions" PRINT "" --- Reports whether the package arrived at the workstation, whether the --- Command line executed on the workstation, or is retrying because of --- a failure to run the command line. SELECT JobID, Status, DetailData, Time FROM vJobDetails WHERE DetailData LIKE "%|%" GROUP BY JobID, Status, DetailData, Time
Sample Output
Detailed Status Report of Run Command Package Distributions JobID Status DetailData Time -------- ----------- ---------------------------------------------- S0100046 6 NCPSTSMS|S010000A Oct 14 1997 8:08AM S0100047 0 NCPSTSMS|S0100009 (null) S0100047 0 NETWARE|S0101000 (null) S0100047 4 NCPSTSMS|S0100001 Oct 14 1997 12:47PM S0100047 4 NCPSTSMS|S010000A Oct 14 1997 12:15PM S0100047 4 NCPSTSMS|S010000C Oct 14 1997 8:51AM S0100047 6 NCPSTSMS|S010000D Oct 14 1997 8:33AM S010004A 0 NCPSTSMS|S0100009 (null) S010004A 6 NCPSTSMS|S010000A Oct 14 1997 9:02AM S010004B 0 NCPSTSMS|S0100009 (null) S010004B 4 NCPSTSMS|S010000A Oct 14 1997 9:11AM S010004C 0 NCPSTSMS|S0100009 (null) S010004C 0 NETWARE|S0101000 (null) S010004C 4 NCPSTSMS|S0100001 Oct 15 1997 3:00PM S010004C 4 NCPSTSMS|S010000D Oct 15 1997 3:07PM S010004C 6 NCPSTSMS|S010000A Oct 15 1997 12:24PM S010004C 6 NCPSTSMS|S010000C Oct 15 1997 3:02PM S010004F 0 NCPSTSMS|S0100009 (null) S010004F 0 NETWARE|S0101000 (null) S010004F 6 NCPSTSMS|S0100001 Oct 15 1997 3:17PM S010004F 6 NCPSTSMS|S010000A Oct 15 1997 1:57PM S010004F 6 NCPSTSMS|S010000C Oct 15 1997 3:22PM S010004F 6 NCPSTSMS|S010000D Oct 15 1997 3:10PM
Query for Summary of Information that Appears in Job Details for Workstations
PRINT " Summary Status Report of Run Command Package Distributions" PRINT "" PRINT "0 = None, 1 = Pending, 2 = Active, 3 = Canceled, 4 = Complete, 5 = Failed, 6 = Retrying" PRINT "" --- Reports totals per Job as to whether the package arrived at the workstation, --- whether the command line executed on the workstation, or is retrying because of --- a failure to run the command line. SELECT JobID, Status, COUNT (Status) total FROM vJobDetails WHERE DetailData LIKE "%|%" GROUP BY JobID, Status
Sample Output
Summary Status Report of Run Command Package Distributions 0 = None, 1 = Pending, 2 = Active, 3 = Canceled, 4 = Complete, 5 = Failed, 6 = Retrying JobID Status total -------- ----------- ----------- S0100047 0 2 S0100047 4 3 S0100047 6 1 S010004A 0 1 S010004A 6 1 S010004B 0 1 S010004B 4 1 S010004C 0 2 S010004C 4 2 S010004C 6 2 S010004F 0 2 S010004F 6 4
Simple Reports Using ISQL /w
ISQL /w is a simple query tool included with Microsoft SQL Server. Its icon can be found in the SQL Server Group. You may need to set up an Open Database Connectivity (ODBC) connection first. Instructions are included on pages 224-225 in the Getting Started manual for Systems Management Server. You can select from a variety of format options, including comma-separated to allow easy importing into a spreadsheet.
To Create a Report Using ISQL /w
Start ISQL /w.
On the File menu, click Connect, and select the server where your Systems Management Server database is located, and then click Connect again.
In the DB dropdown box, select your Systems Management Server database.
On the Query menu, click Set Options.
Cut the query you want from the samples provided and paste into the Query box.
Click the Format Options tab, and select the output format you want.
On the File menu, click Save, and save the query with a meaningful name. In the future, you can select this query by clicking Open on the File menu.
Select the query to highlight it, and click the green arrow.
(You should now have your query results. You may need to scroll to the right to see every column)
With the focus on the Results window, on the File menu, click Save As, and name your report. Then click Save.
You should now have an .rpt file you can open with a text editor or spreadsheet depending on the format options you chose.
Creating Complex Reports with Crystal Reports
Crystal Reports is a powerful reporting tool that is included as a setup option with Systems Management Server. You can reference more information on this tool in Appendix F of the Getting Started manual, and as well as through online Help. Crystal Reports is a product of Crystal Computer Services, Inc. and, therefore, Microsoft does not provide support services for Crystal Reports.
The following two sample reports were created using Crystal Reports. They are used as examples only.