Using MOM 2005 to Recover ports on BizTalk 2006

Neil Thompson — Tue, 25 Jul 2006 18:40:00 GMT

This will be a semi-fictitious case study. In using MOM 2005 to recover an errant SQL port. This scenario is common and I've been asked about it a lot. This approach is the simple meat and potatoes process. There are lots of areas that could be polished up but that kind of thing can clutter up an article with too much detail.

The basic steps will be as follows:

Define a rule to detect the error condition
Define a script to correct the error condition
Wire up the script to the rule so that the rule cant trigger it.

Define a rule to detect the error condition

For whatever reason (network down, SQL down) the port was unable to commmunicate with SQL and BizTalk shut it down. This will create an event log entry similar to the following

Type:Error
EventID:5649
Source: BizTalk Server 2004/2006

The receive location "SQL://<sql name/info>" is shutting down. Details:"The error threshold has been exceeded. The receive location is shutting down."

You will setup a MOM Rule to detect this condtion. This is not a total MOM tutorial so I won't go over the details here, but the basic process is to create a new rule and use the criteria tab to specify as many details as possible from the above event log entry. Be sure the rule is using the application event log as a source.

Define a script to correct the error condition

I would normally like to use managed code, but it is nice to remove dependencies from the .NET framework version (i.e. 2.0 might not be installed) and I also like being able to issue changes without having to recompile. This is good and bad for several reasons I don't want to get into. The script that I use targets a specific port and tries to enable it. The script (written in vbscript) is the following: (it is bacially a lift from the BizTalk SDK)

'-------------------------------------------------------------------------
'
' WMI script to enable/disable the receive locations
'
'---------------------------------------------------

Option Explicit

EnableReceiveLocation "ReceivePort1", "ReceiveLocation1", "TRUE"

Sub EnableReceiveLocation(strReceivePortName, strReceiveLocationName, sEnable)

    'error handling is done by explicity checking the err object rather than using
    'the VB ON ERROR construct, so set to resume next on error.
    On Error Resume Next


    Dim objInstSet, objInst, strQuery


    'set up a WMI query to acquire a list of receive locations with the given Name and
    'ReceivePortName key values. This should be a list of zero or one Receive Locations.
    strQuery = "SELECT * FROM MSBTS_ReceiveLocation WHERE ReceivePortName =""" & strReceivePortName & """AND Name =""" & strReceiveLocationName & """"
    Set objInstSet = GetObject("Winmgmts:!root\MicrosoftBizTalkServer").ExecQuery(strQuery)

    'Check for error condition before continuing.
    If Err <> 0    Then
        PrintWMIErrorThenExit Err.Description, Err.Number
    End If

    'If Receive Location found, enable it, otherwise print error and end.
    If objInstSet.Count > 0 then
        For Each objInst in objInstSet

            'Now enable /disable receive location
            if sEnable= "TRUE" then
                objInst.Enable
            else
                objInst.Disable
            end if
            If Err <> 0    Then
                PrintWMIErrorThenExit Err.Description, Err.Number
            End If
            if sEnable = "TRUE" then
                 return 100
            else
                return 101
            end if
        Next
    Else
        WScript.Echo "No Receive Location was found matching that Name."
    End If

End Sub

'This subroutine deals with all errors using the WbemScripting object. Error descriptions
'are returned to the user by printing to the console.
Sub    PrintWMIErrorThenExit(strErrDesc, ErrNum)
    On Error Resume    Next
    Dim    objWMIError    : Set objWMIError =    CreateObject("WbemScripting.SwbemLastError")

    If ( TypeName(objWMIError) = "Empty" ) Then
        wscript.echo strErrDesc & " (HRESULT: "    & Hex(ErrNum) & ")."
    Else
        wscript.echo objWMIError.Description & "(HRESULT: "    & Hex(ErrNum) & ")."
        Set objWMIError    = nothing
    End    If

    'bail out
    wscript.quit 0
End    Sub

Sub PrintUsage()
    WScript.Echo "Usage:" + Chr(10) + Chr(10) + _
                 "cscript enabledisableallrecloc [enable/disable]" + _
                 Chr(10) + "       Example to enable all receive locations: enabledisableallreclo enable "+ Chr(10) + Chr(10)

End Sub

Wire the script to the rule

You have to go to the Response tab of the rule and use the “Execute command or batch file” option. Assuming that you have copied your vbscript file to the %PROGRAM FILES% directory on your biztalk server you can execute the following as part of your response:

Check the “Use Windows command interpreter“ (if it is appropriate for your environment)
Command line:cscript myscriptfile.vbs
Initial Directory: %PROGRAMFILES%

Common Mistakes

If your script works when executed locally but fails when triggered by MOM you probably have not set your Agent Action account . Go to the MOM adminstration console then go to Administration >> Computers >> Agent-Managed Computers. Right click on the machine in question and select “Update Agent Settings“. Choose a domain account that has the appropriate permissions (i.e. BizTalk Administrator/Operator for starting or stopping ports“
Consider the fact that this might start an infinite loop. Say SQL really is down. Then the port goes down, then MOM starts it, then it goes back down, then MOM starts it etc. Limit the retries with the Repeat count (look under advanced in the criteria tab for the rule). If you really want to get fancy, use a regular expression to define different responses based on ranges the retry count (i.e first time run script immediately, 1-5 times run script every 10 minutes, > 5 times notify operators)

MOM 2005 Category added

Neil Thompson — Thu, 20 Jul 2006 14:18:00 GMT

As fate would have it, I'm going to be delving back into MOM 2005. I figure I may as well blog on it, so I've added it as another category. I'll be talking about MOM 2005 within the context of MOM monitoring BizTalk Server 2006. There are of course, many other applications but I'll start focused and try to be alot of use to a small group of people.

I'm going to be covering the management packs, initial setup, using the agents, configuring and responding to alerts, and also writing scripts for Mom to execute when an alert condition is detected.

I'm also taking requests, so if you have questions about MOM 2005 let me know and I'll do my best to answer them.

Microsoft MOM 2005

Using MOM 2005 to Recover ports on BizTalk 2006

MOM 2005 Category added