1.6 Script Management Interface

The Script Management interface provides methods for getting script information, launching other scripts and programs, and displaying informational messages and prompts to users. The methods are organized into the following sections:

1.6.1 Script Information and Helper Methods

The Script Information and Helper methods get information about a script (name, ID, and execution context) and provide general script helping functions such as creating a new unique ID for use in the script, generating trace messages for the script, and pausing the script for a specified amount of time.

string Query.ScriptName

Description:

Gets the name of the script. The name is derived from the Scripting policy name.

string Query.ScriptId

Description:

Gets the script identifier. The identifier is derived from the Scripting policy ID.

string Query.ScriptContext

Description:

Gets the context (user or system) in which the script is running.

string Query.UniqueID

Description:

Generates a unique identifier for use by the script.

void Action.Trace(string msg)

Description:

Sends trace messages to the user or service logs (depending on whether the script is running in the user context or system context). Each trace message has its script id concatenated to the message.

The trace messages can also be viewed in the Script Tracing dialog of the Endpoint Security Agent About box.

Parameters:

msg — The message string to log.

void Action.Sleep (int millisec)

Description:

Causes the script to sleep for a specified period of time.

Parameters:

millisec — The number of milliseconds the script sleeps before proceeding. The implementation wakes up on a regular interval to check if the script needs to be terminated early due to a policy change or agent restart. Control is returned only after the number of milliseconds has expired.

JScript Example

Action.Trace("");
Action.Trace(" ******** Script Information ********* ");
Action.Trace("UniqueID: " + Query.UniqueID);
Action.Trace("Script Name: " + Query.ScriptName);
Action.Trace("Script ID: " + Query.ScriptID);
Action.Trace("Script Context: " + Query.ScriptContext);

VBScript Example

Action.Trace ""
Action.Trace " ******** Script Information ********* "
Action.Trace "UniqueID: " & Query.UniqueID 
Action.Trace "Script Name: " & Query.ScriptName 
Action.Trace "Script ID: " & Query.ScriptID 
Action.Trace "Script Context: " & Query.ScriptContext 

1.6.2 Version Methods

The Version methods get information about the version of a namespace (Query, Action, Storage) or of the Endpoint Security Agent.

int Query.Version(string category, string component)

Description:

Gets the version of the specified namespace or of the Endpoint Security Agent.

Parameters:

category — One of the following four identifiers: query, action, storage, client.

component — The requested version component. The four identifiers are: major, minor, revision, build.

Returns:

An integer value for the requested component. If an invalid component is requested, -1 is returned.

JScript Example

Action.Trace("");
Action.Trace(" ******** Version Information ********* ");
Action.Trace("");
Action.Trace("Client: " + Query.Version("Client", "Major") + "." + Query.Version("Client", "Minor") + "." + Query.Version("Client", "Revision") + "." + Query.Version("Client", "Build"));
Action.Trace("Query: " + Query.Version("Query", "Major") + "." + Query.Version("Query", "Minor") + "." + Query.Version("Query", "Revision") + "." + Query.Version("Query", "Build"));
Action.Trace("Action: " + Query.Version("Action", "Major") + "." + Query.Version("Action", "Minor") + "." + Query.Version("Action", "Revision") + "." + Query.Version("Action", "Build"));
Action.Trace("Storage: " + Query.Version("Storage", "Major") + "." + Query.Version("Storage", "Minor") + "." + Query.Version("Storage", "Revision") + "." + Query.Version("Storage", "Build"));

VBScript Example

Function DisplayVersion (name)
    dim major
    dim minor
    dim revision
    dim build
 
    major = Query.Version(name, "Major")
    minor = Query.Version(name, "Minor")
    revision = Query.Version(name, "Revision")
    build = Query.Version(name, "Build")
    Action.Trace name & ": " & major & "." & minor & "." & revision & "." & build
End Function

Action.Trace "" 
Action.Trace " ******** Version Information ********* " 
Action.Trace "" 
DisplayVersion("Client")
DisplayVersion("Query")
DisplayVersion("Action")
DisplayVersion("Storage")

1.6.3 Trigger Event Methods

The Trigger Event methods get information about the event that caused the script to execute.

Trigger Reasons

The following table lists the reasons a script is triggered. Each trigger reason includes one or more indexes that are available for the trigger. The indexes listed for each trigger are guaranteed to be available. Other indexes, and even other reasons, might be available depending on the version of the Endpoint Security Agent.

Trigger Reason

Index

Description

Location change

reason

The trigger reason value. For a location change, the value is always location.

switch_from_id

The ID of the switched-from location.

switch_from

The name of the switched-from location.

switch_to_id

The ID of the switched-to location.

switch_to

The name of the switched-to location

change_reason

Reason for the location change that triggered the script; for reasons, see Data Types

Network environment change

reason

The trigger reason value. For a network environment change, the value is always network_environment.

Network connect

reason

The trigger reason value. For a network connection, the value is always network_connect.

device_id

The device ID of the adapter that detected the connection

Network disconnect

reason

The trigger reason value. For a network disconnection, the value is always network_disconnect.

device_id

The device ID of the adapter that detected the disconnect

Immediate

reason

The trigger reason value. For an immediate trigger, the value is always immediate.

caller

(Optional) The name of the script that initiated the trigger.

caller_ID

(Optional) The ID of the script that initiated the trigger,

caller_reason

(Optional) The reason the script initiated the trigger.

Timer

reason

The trigger reason value. For a time trigger, the value is always timer.

interval

The time interval (in minutes) that triggered the script

string Query.TriggerParameter(string index)

Description:

Gets the value of the requested index.

Parameters:

index — One of the index names listed in Trigger Reasons. For example, location or switch_from.

Returns:

The value of the requested index value. For example, if reason is the index, the value might be location or network_connect. If switch_from is the index, the value might be work or office.

If an index is out of range or invalid, an empty string is returned.

int Query.TriggerParameterCount

Description:

Gets the number of indexes for the trigger. For example, if Location change is the trigger, 6 or more indexes can be available.

Returns:

The number of indexes.

string Query.TriggerParameterName(int index)

Description:

Gets the name of the requested index.

Parameters:

index — The number of the index being requested. Index names are listed in Trigger Reasons. Index numbers are not listed because they can change from one script run to another. For example, the reason index might be 0 during one run and 4 during another.

Returns:

The name of the requested index. For example, switch_from_ID, deviceID, or reason.

string Query.TriggerParameterValue(int index)

Description

Gets the value of the requested index.

Parameters:

index — The number of the index being requested. Index names are listed in Trigger Reasons. Index numbers are not listed because they can change from one script run to another. For example, the reason index might be 0 during one run and 4 during another.

Returns:

The value of the requested index. For example, if switch_from is the requested index (based on its index number, not name), the value might be work or office.

JScript Example

Action.Trace("");
Action.Trace(" ******** Trigger Reasons ********* ");
Action.Trace("");
Action.Trace("Reason = " + Query.TriggerParameter("reason"));
Action.Trace("Parameter Count = " + Query.TriggerParameterCount);
for(var idx = 0; idx < Query.TriggerParameterCount; idx++)
{
    Action.Trace("Parameter: " + Query.TriggerParameterName(idx) + " -> " + Query.TriggerParameterValue(idx));
}
 
Action.Trace("Invalid trigger parm return: " + Query.TriggerParameter("-1"));

VBScript Example

Action.Trace "" 
Action.Trace " ******** Trigger Reasons ********* " 
Action.Trace "" 
Action.Trace "Reason = " & Query.TriggerParameter("reason") 
Action.Trace "Parameter Count = " & Query.TriggerParameterCount 
For idx = 0 to (Query.TriggerParameterCount - 1)
    Action.Trace "Parameter: " & Query.TriggerParameterName(idx) & " -> " & Query.TriggerParameterValue(idx)
Next
 
Action.Trace "Invalid trigger parm return: " & Query.TriggerParameter("-1")

1.6.4 Script Run Methods

The Script Run methods trigger or terminate another script in the system.

int Action.TriggerScript(string script, string reason)

Description:

Triggers another script in the system.

Parameters:

script — The name or ID of the script being requested to run.

reason — Passed along as part of the trigger parameter. The script that is called has the value stored as the caller_reason trigger parameter.

Returns:

The following are common return values. Other values are also possible:

  • 0 — The script was found and the trigger will be attempted.

  • 50 — The action is not supported; could be returned because the script is attempting to trigger itself.

  • 1168 — The script was not found in the system.

  • Other non-zero values — The script failed to run.

int Action.TerminateScript(string script, string reason)

Description:

Terminates another script in the system by name or id. This does not unload the script.

Parameters:

script — The name or ID of the script being requested to run.

reason — Passed along as part of the trigger parameter. The script that is called has the value stored as the caller_reason trigger parameter.

Returns:

The following are common return values. Other values are also possible:

  • 0 — The script was found and the trigger will be attempted.

  • 50 — The action is not supported; could be returned because the script is attempting to terminate itself.

  • 1168 — The script was not found in the system.

  • Other non-zero values — The script failed to run.

1.6.5 Program Launch/Execute Methods

The Launch/Execute methods provide ways to launch and execute programs. A launch method runs the program but does not wait for the program to finish and return an exit code. An execute method runs the program and waits for it to finish and return an exit code, or for the execution timeout to expire.

A launched or executed program runs in the same context (user or system) as the script, unless the script overrides the context by passing a new context.

Be aware that some Windows operating systems may not allow GUI applications to display in the system context.

int Action.Launch(string context, bool hide, string command, string parameters)

Description:

Starts a program in the requested context. The script continues without waiting for the program to return an exit code.

Parameters:

context — Valid inputs are user or system. Leave the parameter empty to run the program in the same context as the script. If the user context is requested and the primary user context is unavailable, an error code is returned and the request is dropped.

hide — If true, the command shell used to launch the program is not displayed. If false, the command shell is displayed.

command — The command to execute. If the command starts with http: or www., the link is launched using the default web browser.

parameters — Parameters to be passed to the command.

Returns:

The following are common return values. Other values are also possible:

  • 0 — Success

  • 31 — General failure. The launching of the program failed due to a file not found, the command failing, or other similar reason.

  • 1359 — The launch context (user or system) is not available.

int Action.Execute(string context, bool hide, string command, string parameters)

Description:

Starts a program in the requested context. The script pauses until the program returns an exit code.

Parameters:

context — Valid inputs are user or system. Leave the parameter empty to run the program in the same context as the script. If the user context is requested and the primary user context is unavailable, an error code is returned and the request is dropped.

hide — If true, the command shell used to execute the program is not displayed. If false, the command shell is displayed.

command — The command to execute. If the command starts with http: or www., the link is launched using the default web browser.

parameters — Parameters to be passed to the command.

Returns:

In addition to the exit code of the executed program, the following errors can be returned:

  • 31 — General failure. Execution failed due to a file not found, the command failing, or other similar reasons.

  • 1359 — The execute context (user or system) is not available.

int Action.ExecuteWithTimeout(string context, bool hide, string command, string parameters int timeout)

Description:

Starts a program in the requested context. The script pauses until the program returns an exit code or until the timeout is reached.

Parameters:

context — Valid inputs are user or system. Leave the parameter empty to run the program in the same context as the script. If the user context is requested and the primary user context is unavailable, an error code is returned and the request is dropped.

hide — If true, the command shell used to execute the program is not displayed. If false, the command shell is displayed.

command — The command to execute. If the command starts with http: or www., the link is launched using the default web browser.

parameters — Parameters to be passed to the command.

timeout — Number of seconds to wait for an exit code from the program.

Returns:

In addition to the exit code of the executed program, the following errors can be returned:

  • 31 — General failure. Execution failed due to a file not found, the command failing, or other similar reasons.

  • 121 — The command was successfully executed but did not complete before the timeout was reached.

  • 1359 — The execute context (user or system) is not available.

JScript Example

var ret;
 
ret = Action.Launch("user", false, "notepad", "");
Action.Trace("User: Launch notepad: " + ret);
 
ret = Action.Execute("user", false, "notepad", "");
Action.Trace("User: Execute notepad: " + ret);
 
ret = Action.ExecuteWithTimeout("user", false, "notepad", "", 5);
Action.Trace("User: Execute with Timeout, notepad: " + ret);

VBScript Example

dim ret

ret = Action.Launch("user", false, "notepad", "")
Action.Trace("User: Launch notepad: " & ret)
 
ret = Action.Execute("user", false, "notepad", "")
Action.Trace("User: Execute notepad: " & ret)
 
ret = Action.ExecuteWithTimeout("user", false, "notepad", "", 5)
Action.Trace("User: Execute with Timeout, notepad: " & ret)

1.6.6 Display Methods

The Display methods enable a message to be displayed to a user. The methods are valid only if the script is running in a user session.

The displayed message includes an OK button to dismiss the message. You can also set a timeout to automatically dismiss the message. The message does not pause the script; it continues to run while the message displays.

Display messages are intended for providing information to the user. If you need to display a message that requires the user to make a choice (such as OK or Cancel), you should use a message prompt. See Prompt Methods.

void Action.DisplayMessage(string title, string message, string icon, int timeout)

Description:

If a primary user process is running, displays a custom message to the user. If no primary user process is available, the message is dropped.

Parameters:

title — String displayed in the title bar.

message — The main message.

icon — The icon to display with the message. You can specify any of the following system icons or leave the string empty for no icon: error, app, hand, info, quest, warn, exclamation (or !), stop, asterisk (or *), default. Be aware that it is possible for no default system icon to exist.

timeout — The number of seconds for the message to display. Use 0 to display the message until the user closes the dialog box.

void Action.DisplayMessageWithLink(string title, string message, string icon, int timeout, string linkName, string linkCommand, string linkParameters)

Description:

If a primary user process is running, displays a custom message to the user. If no primary user process is available, the message is dropped.

Parameters:

title — String displayed in the title bar.

message — The main message.

icon — The icon to display with the message. You can specify any of the following system icons or leave the string empty for no icon: error, app, hand, info, quest, warn, exclamation (or !), stop, asterisk (or *), default. Be aware that it is possible for no default system icon to exist.

timeout — The number of seconds for the message to display. Use 0 to display the message until the user closes the dialog box.

linkName — The name of the link to be display on the dialog box.

linkCommand — The command to be executed when the link is clicked.

linkParameters — Parameters to be passed as part of the execution command.

void Action.DisplayMessageById(string id, string title, string message, string icon, int timeout)

Description:

If a primary user process is running, displays a custom message to the user. If no primary user process is available, the message is dropped.

Parameters:

id — Provides that ability for message suppression. If a message with the same id is already being displayed to the user, this message is dropped.

title — String displayed in the title bar.

message — The main message.

icon — The icon to display with the message. You can specify any of the following system icons or leave the string empty for no icon: error, app, hand, info, quest, warn, exclamation (or !), stop, asterisk (or *), default. Be aware that it is possible for no default system icon to exist.

timeout — The number of seconds for the message to display. Use 0 to display the message until the user closes the dialog box.

void Action.DisplayMessageByIdWithLink(string id, string title, string message, string icon, int timeout, string linkName, string linkCommand, string linkParameters)

Description:

If a primary user process is running, displays a custom message to the user. If no primary user process is available, the message is dropped.

Parameters:

id — Provides that ability for message suppression. If a message with the same id is already being displayed to the user, this message is dropped.

title — String displayed in the title bar.

message — The main message.

icon — The icon to display with the message. You can specify any of the following system icons or leave the string empty for no icon: error, app, hand, info, quest, warn, exclamation (or !), stop, asterisk (or *), default. Be aware that it is possible for no default system icon to exist.

timeout — The number of seconds for the message to display. Use 0 to display the message until the user closes the dialog box.

linkName — The name of the link to be display on the dialog box.

linkCommand — The command to be executed when the link is clicked.

linkParameters — Parameters to be passed as part of the execution command.

JScript Example

Action.DisplayMessage("Display Message", "Error icon", "Error", 2);
Action.Sleep(2000);

Action.DisplayMessageWithLink("Display Message With Link", "Error icon", "Error", 2, "novell", "www.novell.com", "");
Action.Sleep(2000);
 
Action.DisplayMessageById("2", "Display Message By Id", "Should See", "app", 5);
Action.Sleep(2000);
Action.DisplayMessageById("2", "Display Message By Id", "Should not see", "error", 2);
Action.Sleep(3000);
 
Action.DisplayMessageByIdWithLink("8", "Display Message By Id With Link", "Should See", "app", 5, "novell", "www.novell.com", "");
Action.Sleep(2000);
Action.DisplayMessageByIdWithLink("8", "Display Message By Id With Link", "Should not see", "error", 2, "novell", "www.novell.com", "");

VBScript Example

Action.DisplayMessage "Display Message", "Error icon", "Error", 2
Action.Sleep 2000

Action.DisplayMessageWithLink "Display Message With Link", "Error icon", "Error", 2, "novell", "www.novell.com", ""
Action.Sleep 2000
 
Action.DisplayMessageById "2", "Display Message By Id", "Should See", "app", 5
Action.Sleep 2000
Action.DisplayMessageById "2", "Display Message By Id", "Should not see", "error", 2
Action.Sleep 3000
 
Action.DisplayMessageByIdWithLink "8", "Display Message By Id With Link", "Should See", "app", 5, "novell", "www.novell.com", ""
Action.Sleep 2000
Action.DisplayMessageByIdWithLink "8", "Display Message By Id With Link", "Should not see", "error", 2, "novell", "www.novell.com", ""

1.6.7 Prompt Methods

The Prompt methods enable a message prompt to be displayed to a user. The methods are valid only if the script is running in a user session.

The prompt can include different response buttons, such as OK/Cancel or Abort/Retry/Ignore. You can also set a timeout to automatically close the prompt if the user doesn’t respond.

Message prompts are intended for prompting the user to make a choice. If you only need to display information to the user, you should use a display message. See Display Methods.

string Action.Prompt(string title, string message, string icon, int timeout, string buttons)

Description:

If a primary user process is running, displays a custom message prompt to the user. If no primary user process is available, the message prompt is dropped.

Parameters:

title — String displayed in the title bar.

message — The main message.

icon — The icon to display with the message. You can specify any of the following system icons or leave the string empty for no icon: error, app, hand, info, quest, warn, exclamation (or !), stop, asterisk (or *), default. Be aware that it is possible for no default system icon to exist.

timeout — The number of seconds for the message to display. Use 0 to display the message until the user closes the dialog box.

buttons — The buttons to display. Valid inputs are: ok, okCancel, abortRetryIgnore, yesNoCancel, yesNo, retryCancel. Inputs are not case-sensitive.

Returns:

One of the following:

  • “” — Empty string. The primary process is unavailable, no input received.

  • closed — Dialog box closed without input.

  • timeout — Dialog box timed out.

  • ok — OK button selected.

  • cancel — Cancel button selected.

  • abort — Abort button selected.

  • retry — Retry button selected.

  • ignore — Ignore button selected.

  • yes — Yes button selected.

  • no — No button selected.

  • cancel — Cancel button selected.

string Action.PromptWithLink(string title, string message, string icon, int timeout, string buttons, string linkName, string linkCommand, string linkParameters)

Description:

If a primary user process is running, displays a custom message prompt to the user. If no primary user process is available, the message prompt is dropped.

Parameters:

title — String displayed in the title bar.

message — The main message.

icon — The icon to display with the message. You can specify any of the following system icons or leave the string empty for no icon: error, app, hand, info, quest, warn, exclamation (or !), stop, asterisk (or *), default. Be aware that it is possible for no default system icon to exist.

timeout — The number of seconds for the message to display. Use 0 to display the message until the user closes the dialog box.

buttons — The buttons to display. Valid inputs are: ok, okCancel, abortRetryIgnore, yesNoCancel, yesNo, retryCancel. Inputs are not case-sensitive.

linkName — The name of the link to be display on the dialog box.

linkCommand — The command to be executed when the link is clicked.

linkParameters — Parameters to be passed as part of the execution command.

Returns:

One of the following:

  • “” — Empty string. The primary process is unavailable, no input received.

  • closed — Dialog box closed without input.

  • timeout — Dialog box timed out.

  • ok — OK button selected.

  • cancel — Cancel button selected.

  • abort — Abort button selected.

  • retry — Retry button selected.

  • ignore — Ignore button selected.

  • yes — Yes button selected.

  • no — No button selected.

  • cancel — Cancel button selected.

JScript Example

var ret;
ret = Action.Prompt("Prompt - Ok", "Hit ok", "Error", 0, "ok");
Action.Trace("Ok Result: " + ret);
ret = Action.Prompt("Prompt - OkCancel", "Hit ok", "", 0, "okCancel");
Action.Trace("Ok Result: " + ret);
ret = Action.Prompt("Prompt - Retry/Cancel", "Allow to timeout", "", 5, "retryCancel");
Action.Trace("timeout Result: " + ret);
 
ret = Action.PromptWithLink("Prompt - Retry/Cancel", "With link", "", 3, "retryCancel", "Novell", "www.novell.com", "");
Action.Trace("with link results: " + ret);

VBScript Example

dim ret
ret = Action.Prompt("Prompt - Ok", "Hit ok", "Error", 0, "ok")
Action.Trace("Ok Result: " & ret)
ret = Action.Prompt("Prompt - OkCancel", "Hit ok", "", 0, "okCancel")
Action.Trace("Ok Result: " & ret)
ret = Action.Prompt("Prompt - Retry/Cancel", "Allow to timeout", "", 5, "retryCancel")
Action.Trace("timeout Result: " & ret)
 
ret = Action.PromptWithLink("Prompt - Retry/Cancel", "With link", "", 3, "retryCancel", "Novell", "www.novell.com", "")
Action.Trace("with link results: " & ret)

1.6.8 Safe Arrays

A safe array indexes a list of objects. Safe arrays are native to VBScript and provide a way to enumerate all elements in the array. Safe arrays are not native to JScript; they must be converted using the native VBArray function provided by WScript.

Functions that return a safe array value end in Array (for example, EffectivePolicyArray). The followng VBScript and JScript examples use EffectivePolicyArray as a safe array.

JScript Example

Action.Trace(" ******** Array Access ****** ");
var a = new VBArray(Query.EffectivePolicyArray());
ret = a.toArray();
for (var i = 0; i < ret.length; i++) {
    var pol = ret[i];
    Action.Trace(" ******** Policy Information ********* ");
    Action.Trace("ID: " + pol.Id);
    Action.Trace("Version: " + pol.Version);
    Action.Trace("Name: " + pol.Name);
    Action.Trace("Type: " + pol.PolicyType);
    Action.Trace("Session: " + pol.Session);
}

VBScript Example

Dim obj, idx, max, pol
obj = Query.EffectivePolicyArray
Action.Trace VarType(obj)
Action.Trace IsArray(obj)
For Each pol in obj
    Action.Trace " ******** Policy Information ********* "
    Action.Trace "ID: " & pol.Id
    Action.Trace "Version: " & pol.Version
    Action.Trace "Name: " & pol.Name
    Action.Trace "Type: " & pol.PolicyType
    Action.Trace "Session: " & pol.Session
Next

1.6.9 Object Match Lists

Because JScript does not support the native importing of safe arrays, and does not support an array enumerator, ZENworks Endpoint Security Management provides an object called Object Match List to allow for index enumeration of a list to both VBScript and JScript. Functions that return this type of object end in List (for example, EffectivePolicyList). The object provides the following functions and properties for access to the objects in the container.

int Count

Description:

Returns the number of objects in the container.

object Item(int idx)

Description:

Returns a particular object from the container based on the index given. If the index is outside the count of container, a null/empty object is returned. The order of objects in the container is not guaranteed.

object Find(string value)

Description:

Returns an object that matches the value provided. If no matches are found in the container, a null/empty object is returned.

JScript Example

Action.Trace(" ******** List Access ****** ");
var ret = Query.EffectivePolicyList;
for(var i = 0; i < ret.Count; i++)
{
    var pol = ret.Item(i);
    Action.Trace(" ******** Policy Information ********* ");
    Action.Trace("ID: " + pol.Id);
    Action.Trace("Version: " + pol.Version);
    Action.Trace("Name: " + pol.Name);
    Action.Trace("Type: " + pol.PolicyType);
    Action.Trace("Session: " + pol.Session);
}

VBScript Example

set obj = Query.EffectivePolicyList
max = obj.Count
For idx = 0 to (max - 1)
    Action.Trace " ******** Policy Information ********* "
    set pol = obj.Item(idx)
    Action.Trace "ID: " & pol.Id
    Action.Trace "Version: " & pol.Version
    Action.Trace "Name: " & pol.Name
    Action.Trace "Type: " & pol.PolicyType
    Action.Trace "Session: " & pol.Session
Next