The Zenith Infotech Advanced Scripting Engine (A.S.E.) provides a framework for deploying scripts written in Zenith’s OEM version of Automise 3 Professional. Scripts can be deployed once on demand or, using templates, on a recurring schedule.

A.S.E. scripting is still fairly new in the Zenith offering, and definitely takes some getting used to. Here are a few things that I’ve learned along the way. I’ll cover five topics:

Script Parameters
INI Files
Helper Scripts
ITS Variables and the SAAZ Extended Database
When Scripts Run
MD5 Checksums

Script Parameters

The Zenith agent runs Automise scripts using Automise’s ATCMD command-line utility. One powerful feature of command-line execution is the ability to initialize script variables using command-line parameters.

For example, let’s say you write a script to send an email. Rather than hard-code the SMTP host, port sender, recipient, etc., you want to use parameters to supply that information.

1. In Automise, define the parameters as normal variables, e.g. SMTPHost, SMTPPort, SMTPSender, etc.
2. When creating the Send Email action, use the parameters in the appropriate fields, e.g. in the Host field type %SMTPHost%. If the field is a drop-down (like SMTP Port), you’ll have to add code manually. With the Send Email action highlighted, click on the Script Editor tab, then on the Before Action tab. Add the following line:
   Action.Port = CInt(SMTPPort)
3. To test the script, you can either supply default values to the parameter variables and run from inside Automise, or you can use ATCMD to run the script from a command line. This ATCMD example sends output to a text file and sets two variables (parameters):
   atcmd /PSendEmail.zatz3 /LSendEmail.txt /VSMTPHost=”smtp.myserver.com”;SMTPPort=25
4. When defining the script in the SAAZ portal, add one Command Line Parameter for each variable that you want to pass in to the script. Add the parameters in this format:
   SMTPHost="smtp.myserver.com"

Parameter Length

When running scripts on demand, I have yet to encounter a limitation on how many parameters can be supplied or how long they can be. However, the same script that works fine on demand may fail when run from a template. In the ACM Execution Health Status report, on the Success/Failure Details tab, you will see this message:

Postprocessing:Exit with return code: 14 (ERRORSETTINGVARIABLE)

If you hunt down the text log of the script execution in the C:\Program Files\SAAZOD\AutomiseLogs directory, you will see a short log listing a few of your variables and ending with the line:

Error - variable doesn't exist:

At this point you may already suspect that the command line was truncated, which would mean that the script could not initialize all of your variables. Further sleuthing will lead you to C:\Program Files\SAAZOD\ApplicationLog\SAAZScheduler.log. Search for the name of the failed script and you should see the truncated command line. You can see command lines for upcoming scheduled executions in C:\Program Files\SAAZOD\Configuration\SAAZScheduler.ini.

Zenith support tells me that the command line limit was 300 characters. On one machine where I had this issue, they installed an updated SAAZScheduler.exe (version 5.0.0.6 dated 5/11/09) that reportedly allows command lines up to 1000 characters. The new version did in fact solve the problem.

Update 6/5/2009: Zenith deployed the updated components to all agents a couple weeks ago. Since then, I haven’t had any parameter length issues.

INI Files

Another way to set script variables is to retrieve them from an INI file using the Load Variables from INI action. How do you get them into the INI file in the first place? With the Save Variables to INI action.

For example, you could write a script to store all the needed SMTP variables in an INI file. Run that script on each computer you manage, and each computer will have a copy of your custom INI file. Then you can retrieve those variables from the INI file whenever you need to send an email.

Helper Scripts

One very interesting feature of Automise is the ability to “call” scripts from other scripts. These are referred to as helper scripts, support scripts, or dependent scripts.

In Automise, you call the helper script using the Include Project action. You can pass variables from the calling script to the helper script.

In Zenith, you first define the helper script as a stand-alone script. The script can have its own parameters. Then you define the calling scripts, and under Additional Script File Name, choose the helper script from the drop-down list.

I use a helper script to send email. The helper script is responsible for retrieving SMTP variables from an INI file and sending the email. The calling script passes the message subject, message body, and optionally the attachment name to the helper script.

Where Is That Script?

In order to call a helper script, you’ll need to know where the SAAZ agent stores it after downloading it. If you look for scripts in the SAAZ agent directory, you may find them in this folder:

C:\Program Files\SAAZOD\ProcessedScripts

In a script built from the SAAZBaseScript, that folder is available as a variable named “Agent-downloaded-script-directory”. However, Zenith support pointed out that scripts are only stored in this directory when they are scheduled using templates. On-demand scripts are never stored there, so references to scripts in that directory may fail.

It turns out that for on-demand execution, the Zenith agent temporarily stores the primary and helper scripts in this directory:

C:\Program Files\SAAZOD\ATCMDExecutables

I say “temporarily” because I was only able to determine this by listing the contents of this directory from inside a script. Once the script completed, the directory was empty again.

The good news is that in both cases, the helper scripts are in the same directory as the primary script. This means that you can use Automise’s built-in “PROJECTDIR” variable. This variable identifies where the calling script is running, so it is also the location of the helper scripts. To specify the helper script, in the Include Project action, use PROJECTDIR plus the script name, for example:

%PROJECTDIR%\SendEmail.zatz3

ITS Variables and the SAAZ Extended Database

Each script can optionally upload the contents one or more variables to the SAAZ Extended Database, which can be a handy way to check the output from scheduled scripts. Just create a variable with a name starting with “ITS_”. When the custom action Post ITS Variables to SAAZ Data Center runs, the variable’s contents will be uploaded to the SAAZ Extended Database. (Post ITS Variables to SAAZ Data Center is part of the SAAZBaseScript, which you use as a starting point for all your scripts.)

For example, if I create a variable named “ITS_AVStatus”, in the SAAZ Extended Database screen, for each machine that runs the script, I will see a variable named “AVStatus” and whatever value was supplied by the script. Values are limited to 100 characters.

Some gotchas on ITS variables:

• As of this writing, you cannot delete variables once they are in the SAAZ Extended Database. Use sparingly!
  Update 6/5/2009:  ITS Variables can now be deleted. (Thanks Zenith!)
• Scripts cannot download ITS variables. This means you cannot access yesterday’s value from the SAAZ Extended Database when you run the script today. (The Get SAAZ Variables action at the beginning of the SAAZBaseScript sets local variables; it does not get values from the SAAZ Extended Database.) If you need to access data from the previous script execution, you’ll need to store the data on the local machine. One easy way to do that is using INI files (see above).

When Scripts Run

When you schedule an on-demand script, you give it a time window starting from now to any point in the future (even years from now). The script will run one time. If the target machine is not online, the script will run when it is turned on and checks in, as long as it checks in before the Till Date.

On the other hand, when you schedule recurring scripts using templates, you define a specific time for the script to run. If the machine is offline at that time, that execution is skipped

MD5 Checksums

If you are writing and updating a lot of scripts, you will need to calculate lots of MD5 checksums for publishing the script in the Zenith portal. Zenith includes an MD5 tool, but a faster approach is to use the free BullZip MD5 Calculator:  just right-click on a script in Explorer to get the MD5 checksum.