Correcting Upgraded Additional Keys

  • Article

In Microsoft ISA Server, an event can be defined as a group of related subevents. Each subevent has an additional condition that must be fulfilled for the event to be signaled. For example, the Service started event is defined with subevents that are signaled when the individual ISA Server services are started. The names of the additional conditions for subevents are specified as strings in an array or table. The indices of the additional conditions in the table are called additional keys and are used to identify the individual subevents in an event definition. The additional key equal to 0 is reserved to indicate all of the subevents defined for an event. This way, additional keys can be used to define different alerts that are specific to the additional conditions for subevents or to define a single alert that is issued for any subevent without regard to the additional conditions.

If an event is defined with no subevents, its additional key should be –1 (the default value). When an ISA Server 2000 configuration is upgraded to ISA Server 2004, the additional key in the definition of an alert for an event that is defined with no subevents may be set to 0, instead of –1. This error must be corrected programmatically.

The Microsoft Visual Basic Scripting Edition (VBScript) code in ChangeAlertAdditionalKey.vbs (listed later in this Web page) provides an example of changing the additional key in an alert definition. The script changes the additional key of the alert specified by the user (for example, the Cached object discarded alert) from 0 to –1, if necessary, on a computer running ISA Server 2004 Standard Edition, or in all arrays of the enterprise for computers running ISA Server 2004 Enterprise Edition.

The script can be run on an ISA Server computer with the Microsoft Firewall service installed, a remote management computer, or a Configuration Storage server (Enterprise Edition). If the script needs to connect to an ISA Server computer with the Firewall service installed or to a Configuration Storage server, it prompts the user for the name of the applicable computer and uses the credentials of the user who is logged on to connect to it.

Usage:[CScript] ChangeAlertAdditionalKey.vbs AlertName

AlertName specifies the name of the alert whose additional key is to be changed.

Example:CScript ChangeAlertAdditionalKey.vbs "Cached object discarded"

To determine whether the script is running on an ISA Server computer, a remote management computer, or a Configuration Storage server:

  1. Declare an FPC object and an FPCArray object.

  2. Create an instance of the FPC COM object, which is known as the root object and provides access to the other ISA Server administration COM objects.

  3. Try to get the number of arrays in the arrays collection by retrieving the value of the Arrays.Count property of the root object:

    • If an E_FPC_NOT_CONNECTED_TO_ENTERPRISE (0xC00403A6) error is raised, the local computer is running ISA Server 2004 Enterprise Edition and is not connected to a Configuration Storage server. In this case, ask the user for the name of a Configuration Storage server, call the ConnectToConfigurationStorageServer method to connect to the Configuration Storage server specified by the user, and then call the subprocedure for changing the additional key in ISA Server 2004 Enterprise Edition.
    • If the number of arrays is equal to 0, the local computer may be a Standard Edition remote management computer or a Configuration Storage server that was set up in an enterprise in which no arrays are configured. In this case, call the Connect method with an empty string. If the local computer is a Configuration Storage server, an E_FPC_NOT_SUPPORTED_IN_EE_CENTRAL_MODE (0xC00403A0) error is raised, and the script should be terminated. If the local computer is a Standard Edition remote management computer, a different error is raised. Ignore this error and ask the user for the name of an ISA Server computer with the Firewall service installed, call the Connect method to connect to the ISA Server computer specified by the user, and then call the subprocedure for changing the additional key in ISA Server 2004 Standard Edition.
    • If the number of arrays is not equal to 0, the local computer may be a Standard Edition ISA Server computer with the Firewall service installed, an Enterprise Edition ISA Server computer that is connected to a Configuration Storage server, or a Configuration Storage server. Call the Arrays.Item method on the root object to get a reference to an array object, and then use the Type method to determine whether the local computer is running ISA Server 2004 Standard Edition or Enterprise Edition. If the local computer is running Standard Edition, call the subprocedure for changing the additional key in Standard Edition. If the local computer is running Enterprise Edition, call the subprocedure for changing the additional key in Enterprise Edition.

To change the additional key of an alert in ISA Server 2004 Enterprise Edition

  1. Declare an FPCArrays collection, an FPCArray object, and an FPCAlert object.

  2. Use the Arrays property of the root object to get a reference to the arrays collection.

  3. In a For loop, for each array in the collection, get a reference to the alert specified by the user. If the additional key in the alert definition is equal to 0, call the SetDefinitions method on the alert object to change the additional key to –1, and then call the Save method to write the new value to persistent storage.

To change the additional key of an alert in ISA Server 2004 Standard Edition

  1. Declare an FPCAlert object.

  2. Get a reference to the alert specified by the user.

  3. If the additional key in the alert definition is equal to 0, call the SetDefinitions method on the alert object to change the additional key to –1, and then call the Save method to write the new value to persistent storage.

Script Listing: ChangeAlertAdditionalKey.vbs

''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

' Copyright (c) Microsoft Corporation. All rights reserved.

' THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND. THE ENTIRE

' RISK OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE REMAINS WITH THE

' USER. USE AND REDISTRIBUTION OF THIS CODE, WITH OR WITHOUT MODIFICATION, IS

' HEREBY PERMITTED.

''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

' This script changes the additional key of the specified alert (for example,

' the "Cached object discarded" alert) from 0 to -1, if necessary, on a

' computer running ISA Server 2004 Standard Edition, or in all arrays of the

' enterprise for computers running ISA Server 2004 Enterprise Edition.

' The script can be run on an ISA Server computer with the Firewall service

' installed, a remote management computer, or a Configuration Storage server

' (Enterprise Edition). If the script needs to connect to an ISA Server

' computer with the Firewall service installed or to a Configuration Storage

' server, it prompts the user for the name of the applicable computer and uses

' the credentials of the user who is logged on to connect to it.

''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

Option Explicit

' Define the constants needed.

Const additionalKey = -1

Const Error_NotConnectedToCSS = &HC00403A6

Const Error_ConfigurationStorageServer = &HC00403A0

Const fpcTypeStandardEdition = 0

Main(WScript.Arguments)

Sub Main(args)

' Declare the objects needed.

Dim root ' The FPCLib.FPC root object

Dim isaArray ' An FPCArray object

Dim serverName ' A String

Dim num ' An Integer

If (args.Count <> 1) Then

Usage()

End If

' Create the root object.

Set root = CreateObject("FPC.Root")

' Try to get the number of arrays.

On Error Resume Next

num = root.Arrays.Count

If Err.Number = Error_NotConnectedToCSS Then

serverName = _

InputBox("Enter the name of a Configuration Storage server.")

' Connect to the specified Configuration Storage server.

Err.Clear

root.ConnectToConfigurationStorageServer serverName

CheckError

ChangeAlertAdditionalKeyEE root, args(0)

ElseIf num = 0 Then

serverName = ""

Set isaArray = root.Arrays.Connect(serverName)

If Err.Number = Error_ConfigurationStorageServer Then

WScript.Echo "No arrays are configured in the enterprise."

WScript.Quit

End If

Err.Clear

' Get the name of an ISA Server computer with the Firewall service

' installed.

serverName _

= InputBox("Enter the name of an ISA Server computer.")

Err.Clear

Set isaArray = root.Arrays.Connect(serverName)

If Err.Number = 0 Then

ChangeAlertAdditionalKeySE isaArray, args(0)

Else

WScript.Echo "The specified computer is not available " _

& "or does not have the Firewall service installed."

WScript.Quit

End If

Else

Set isaArray = root.Arrays.Item(1)

CheckError

If isaArray.Type = fpcTypeStandardEdition Then

ChangeAlertAdditionalKeySE isaArray, args(0)

Else

ChangeAlertAdditionalKeyEE root, args(0)

End If

End If

End Sub

Sub ChangeAlertAdditionalKeyEE(root, alertName)

' Declare the objects needed.

Dim isaArrays ' An FPCArrays collection

Dim isaArray ' An FPCArray object

Dim alert ' An FPCAlert object

Dim eventGUID ' A String

' Get a reference to the arrays collection.

Set isaArrays = root.Arrays

On Error Resume Next

For Each isaArray In isaArrays

' Get a reference to the alert object

Set alert = isaArray.Alerts(alertName)

If Err.Number = 0 Then

WScript.Echo "The current additional key is " _

& alert.AdditionalKey & "."

' Change the additional key if it is equal to 0.

If alert.AdditionalKey = 0 Then

WScript.echo "Changing the additional key to " _

& additionalKey & " in the " & isaArray.Name & " array..."

alert.SetDefinitions alert.EventGuid, , additionalKey

CheckError

alert.Save

CheckError

End If

Else

WScript.Echo "The " & alertName & " alert was not found in " _

& isaArray.Name & "."

Err.Clear

End If

Next

End Sub

Sub ChangeAlertAdditionalKeySE(isaArray, alertName)

' Declare the objects needed.

Dim alert ' An FPCAlert object

Dim eventGUID ' A String

' Get a reference to the alert object

On Error Resume Next

Set alert = isaArray.Alerts(alertName)

If Err.Number = 0 Then

WScript.Echo "The current additional key is " _

& alert.AdditionalKey & "."

' Change the additional key if it is equal to 0.

If alert.AdditionalKey = 0 Then

WScript.echo "Changing the additional key to " _

& additionalKey & "..."

alert.SetDefinitions alert.EventGuid, , additionalKey

CheckError

alert.Save

CheckError

End If

Else

WScript.Echo "The " & alertName & " alert was not found."

Err.Clear

End If

End Sub

Sub CheckError()

If Err.Number <> 0 Then

WScript.Echo "An error occurred: 0x" & Hex(Err.Number) & ". " _

& Err.Description

Err.Clear

WScript.Quit

End If

End Sub

Sub Usage()

WScript.Echo "Usage:" & VbCrLf _

& " " & WScript.ScriptName & " AlertName" & VbCrLf _

& "" & VbCrLf _

& " AlertName - Alert whose additional key is to be changed"

WScript.Quit

End Sub