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:
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.
|
|
Description: |
Gets the name of the script. The name is derived from the Scripting policy name. |
|
|
Description: |
Gets the script identifier. The identifier is derived from the Scripting policy ID. |
|
|
Description: |
Gets the context (user or system) in which the script is running. |
|
|
Description: |
Generates a unique identifier for use by the script. |
|
|
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. |
|
|
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. |
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);
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
The Version methods get information about the version of a namespace (Query, Action, Storage) or of the Endpoint Security Agent.
|
|
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. |
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"));
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")
The Trigger Event methods get information about the event that caused the script to execute.
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 Section 1.8.2, 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 |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
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"));
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")
The Script Run methods trigger or terminate another script in the system.
|
|
Descript ion: |
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:
|
|
|
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:
|
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 Windows Vista, Windows 7 and Windows Server 2008 do not allow GUI applications to display in the system context.
|
|
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:
|
|
|
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:
|
|
|
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:
|
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);
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)
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 Section 1.6.7, Prompt Methods.
|
|
Description: |
If a primary user process is running, displays a custom message to the user. If no primary user process is a vial able, 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. |
|
|
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. |
|
|
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. |
|
|
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. |
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", "");
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", ""
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 Section 1.6.6, Display Methods.
|
|
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:
|
|
|
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:
|
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);
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)
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.
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);
}
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
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.
|
|
Description: |
Returns the number of objects in the container. |
|
|
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. |
|
|
Description: |
Returns an object that matches the value provided. If no matches are found in the container, a null/empty object is returned. |
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);
}
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