Using scripts to extend custom server extensions to run in script and asynchronous mode

You can use shell scripts or Jython scripts to extend a custom server template (CST).

Fix Pack 8When these are used, then script-based discovery is performed where TADDM copies the user-defined scripts (ASDMAINSCRIPT/ASDSCRIPT) to the target system, run the scripts, and returns the output files to the TADDM server. The output generated by these script files needs to be parsed by a Jython script file, that must be created by the user which will be configured via the SCRIPT tag in the directive file. Only the model objects if any, created and returned by this script file will get stored.

In the case of Asynchronous discovery mode (ASD), the user can generate a request package and these scripts configured with ASDMainScript and ASDScript tags, will get bundled in it. Users can then run the package at target and get a result file generated like the ASD process for other sensors. This result file will be copied to the asdd directory on the TADDM server by the user, and then when ASD discovery is invoked via the Discovery Management Console, it will process these files. The Jython script (tagged with SCRIPT tag) mentioned in the directive file will process the output result and will generate result objects as per user coding in that Jython script. Hence, in this mode of extension define one main script (ASDMAINSCRIPT) for a given custom server template. If required, more than one additional scripts (ASDSCRIPT) that are used by the main script can be defined as well. Along with these, define another Jython script (SCRIPT), that will parse the outputs of the scripts run on targets and create model objects and return them for storage.

Fix Pack 8Important: Extending custom server extensions by using Shell and Jython script make it run as a script-based sensor. This extension is also available in asynchronous discovery mode. However, in this mode of extension, only the model objects created and returned by the Jython script file will get stored. This implies there is <bold>no</bold> basic discovery result object comprising of listening port, runtime information, etc, will get generated because of custom server templates which is present in other types of extensions..

To start a custom server template using a script, define one main script for a given custom server template. If required, you can define one or more additional scripts which are used by the main script.

Definition of CST extended with scripts

A CST can have a command file defined in $COLLATION_HOME/etc/templates/commands directory. The command file name has the same name as the CST name. Add the following commands to the command file to extend the CST with scripts:
ASDMAINSCRIPT
This command specifies the main script file name. It specifies the script to be copied and started on the target system.
ASDSCRIPT
This command specifies additional script file names if required. It specifies scripts to be copied and used by the main script on the target system.
Fix Pack 8SCRIPT
This command specifies the Jython script file name. It specifies the script that parses the outputs of scripts run on targets and creates model objects as well. Only the model objects, if any, created and returned by the Jython script file will get stored.

For Asynchronous discovery, the directive filename or the custom server template name must not have space in its name.

Command syntax

Add the following commands to the command file:
ASDMAINSCRIPT:os_discriminator:script_relative_path
The variable os_discriminator defines the operating system where you can run the script. The following values are valid:
  • AIX
  • LINUX
  • SOLARIS
  • UNIX
  • WINDOWS
  • ALL: Use this value to indicate all operating systems.

The variable script_relative_path defines a relative path to a script starting from the $COLLATION_HOME directory. Place the scripts in a subdirectory of $COLLATION_HOME/etc/templates/commands directory.

ASDSCRIPT:os_discriminator:script_relative_path
The same definitions as described previously also apply to the ASDSCRIPT command.

Example of a command file

A script set is a set of scripts defined with the same os_discriminator attribute. Each script set must have one main script (ASDMAINSCRIPT) and can have if required one or more additional scripts (ASDSCRIPT). The CST extended by scripts chooses the most specific script set for the discovered operating system.

The following example shows a command file for a CST extended with scripts:

ASDMAINSCRIPT:AIX:etc/templates/commands/scripts/scriptAix.sh
ASDSCRIPT:AIX:etc/templates/commands/scripts/myTest3.sh
ASDMAINSCRIPT:UNIX:etc/templates/commands/scripts/scriptUnix.sh
ASDSCRIPT:UNIX:etc/templates/commands/scripts/myTest.sh
ASDSCRIPT:UNIX:etc/templates/commands/scripts/myTest2.sh
SCRIPT: etc/templates/commands/scripts/myOutputParser.py
This command file defines two script sets: one for AIX® only, and one for UNIX and similar operating systems.

Fix Pack 8In the ASDMAINSCRIPT file, to invoke the other script for example, myTest.sh, follow the pattern as used in the normal script sensors, for example, echo SCRIPT:myTest.sh, only the file name must be mentioned without any directory path.

Script generated files

TADDM copies the defined scripts to the target system and runs the main script. The main script is started in the root system directory, but it is located in a temporary directory. To get the actual script location, use the dirname $0 command.

The scripts and files generated by the script, which are stored in the temporary location on the target system, are returned to the TADDM server. The files are placed in the $COLLATION_HOME/var/asdd/{runId}/{targetIp}/{sensorOsgiId} directory. The sensorOsgiId name consists of the custom application server sensor (CustomAppSever) identifier and the template name. For example, com.ibm.cdb.discover.sensor.app.customappserver_7.1.0.JavaServer for a JavaServer CST.

Add a Jython extension to a CST extended with scripts

To parse data gathered by a CST extended with scripts, you can call Jython scripts (.py extension) automatically during a discovery. To add a Jython extension to a script file, you must add the following command to the directive file:
SCRIPT:jythonscript_relative_path
The directive file must have the same name as the CST and must be stored in the following directory: $COLLATION_HOME/etc/templates/commands
TADDM passes the context of the custom application server sensor to the script language using a hashmap or script target map. This method enables Jython to manipulate Java™ objects. The script target map has predefined objects that can be used by the script for processing and for passing back results. The following objects are available in the script target map for a CST extended with scripts:
  • outputs - the List <OutputDataSet> object
  • systeminfo - the system information object
  • seed - the CustomAppServerSeed object
  • result - the CustomAppServerResult object
  • environment - the Java HashMap environment object containing the Map <String, String> object
The following example shows a sample of Jython source code: 
...

log = LogFactory.getLogger("com.ibm.cdb.discover.sensor.CustomAppServerScriptSensor")

result = scripttargets.get("result")
seed = scripttargets.get("seed");
env = scripttargets.get("environment")
systeminfo = scripttargets.get("systeminfo")
outputDataSetList = scripttargets.get("outputs")

# just print the content of output data set list
for outputDataSet in outputDataSetList:
    if not outputDataSet.isValid():
        log.error("Not valid output data set")
        continue
    for outputData in outputDataSet.iterator():
        if not outputData.isValid():
            log.error("Not valid output data")
        try:
            log.info(outputData.getValue())
        except ExecutionException, e:
            log.error("ExecutionException", e)

...

Fix Pack 8For information on how to create model objects using extensions, refer to Creating new objects and relationships through custom server extensions.

Tip: For more examples of using the Jython script to extend a discovery scope, see Extending sensor discovery scope with Simplified Model.