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)