Companion Scripts

A companion script provides an easy way to deliver a command-probe and a script for it to run. It also ensures that the version of the script matches the version of the probe.

To deliver a script along with a probe, add a section to the probe as follows:

<tool:scriptname>
</tool:scriptname>

where scriptname is the name given to the companion script when it is written to disk. Currently, a probe can contain only one <tool> section.

Note: When the InterMapper server starts or when probes are reloaded, if a tool section appears for a probe, InterMapper creates a subdirectory of Tools with the canonical name of the probe and writes the script to that subdirectory, using scriptname as a file name. If a subdirectory of that name already exists, all non-hidden files are deleted before the script is written out. When InterMapper is ready to run the command line specified in the command-line probe, it will make the probe's subdirectory of Tools the current working directory. For this reason, you should avoid editing scripts directly in the subdirectories of InterMapper Settings/Tools directory.

For example, given the trivial example of a command-line probe where the canonical name is com.dartware.cmdline.test, where the cmd clause in the <command-line> section is:

cmd="python test.py"

or, using the ${PYTHON} macro:

cmd="$[PYTHON}  test.py"

and the tool section is:

<tool:test.py>
  # Trivial  example
  print "okay"
  raise SystemExit,  0
</tool:test.py>

When InterMapper starts or reloads probes, a subdirectory of Tools named com.dartware.cmdline.test is created if it doesn't exist, and (in this case) a file named "test.py" is written into it, containing the text between <tool:test.py> and </tool:test.py>.

The WMI probes provide a number of good examples of this feature.

Python Example

<!-- 
Companion Script Example in Python - testing the <tool:xxx> section (com.dartware.companionscript.python.txt) 
Please feel free to use this as a base for further development.
Original Version: 24 Nov 2009 
--> 

<header> 
   type         =   "cmd-line" 
   package      =   "com.dartware" 
   probe_name   =   "companionscript.python" 
   human_name   =   "Companion Script-Python" 
   version      =   "1.0" 
   address_type =   "IP" 
   display_name =   "Miscellaneous/Test/Companion Script-Python"
</header> 

<description> 
\GB\Companion Script Example in Python - Using the <tool:xxx> Section of a Probe\p\

This probe launches a trivial Companion Script -- a two-line Python script that's embedded within the probe. 

The script sets and returns two values ($val1 and $val2), and also shows how to set the probe's condition string.

In addition, the exit status (set to "1" in this example) sets the severity of the device.
</description> 

<parameters> 
</parameters> 

<command-line> 
   path=""
   cmd="${PYTHON}" 
   arg="test.py"
</command-line> 

<command-exit>
-- The full range of InterMapper status/exit codes
       down:   ${EXIT_CODE}=4
   critical:   ${EXIT_CODE}=3 
      alarm:   ${EXIT_CODE}=2 
       warn:   ${EXIT_CODE}=1 
       okay:   ${EXIT_CODE}=0 
</command-exit> 

<command-display> 
\b5\Companion Script Return Values\p0\ 
\4\  Value1:\0\ $val1
\4\  Value2:\0\ $val2
</command-display> 

<tool:test.py>
# Trivial example to return two values and a text condition string
print "\{ $val1 := 1, $val2 := 'abcdef' }Condition string - device should be yellow"

# Return code sets device status (Warn = 1)
raise SystemExit, 1
</tool:test.py>

Cscript Example

<!-- 
  Companion Script Example in VBScript - testing the <tool:xxx> section (com.dartware.companionscript.vbscript.txt) 
  Please feel free to use this as a base for further development.
  Original Version: 24 Nov 2009 
--> 

<header> 
   type         =   "cmd-line" 
   package      =   "com.dartware" 
   probe_name   =   "companionscript.vbscript" 
   human_name   =   "Companion Script-VBScript" 
   version      =   "1.0" 
   address_type =   "IP" 
   display_name =   "Miscellaneous/Test/Companion Script-VBScript"
</header> 

<description> 
\GB\Companion Script Example in VBScript - Using the <tool:xxx> Section of a Probe\p\

This probe launches a trivial Companion Script -- a two-line VB script that's embedded within the probe. 

The script sets and returns two values ($val1 and $val2), and also shows how to set the probe's condition string.

In addition, the exit status (set to "1" in this example) sets the severity of the device.
</description> 

<parameters> 
</parameters> 

<command-line> 
   path=""
   cmd="${CSCRIPT}" 
   arg="test.vbs"
</command-line> 

<command-exit>
-- The full range of InterMapper status/exit codes
       down:   ${EXIT_CODE}=4
   critical:   ${EXIT_CODE}=3 
      alarm:   ${EXIT_CODE}=2 
       warn:   ${EXIT_CODE}=1 
       okay:   ${EXIT_CODE}=0 
</command-exit> 

<command-display> 
\b5\Companion Script Return Values\p0\ 
\4\  Value1:\0\ $val1
\4\  Value2:\0\ $val2
</command-display> 

<tool:test.vbs>
  ' Trivial example to return two values and a text condition string
  wscript.Echo "\{ $val1 := 1, $val2 := 'abcdef' }Condition string - device should be yellow"

  ' Return code sets device status (Warn = 1)
  wscript.quit(1)
</tool:test.vbs>