5.0 XML Document Description

Each instance of Desktop Automation Services is driven by an XML document that describes the available actions.

The following table describes the elements that might be used to compose a Desktop Automation Services XML input document.

Unless otherwise specified, all XML attributes listed for a given element are required for that element.

Table 5-1 Desktop Automation Services XML Description

Registry Setting

Description

application-runner-script

This is the parent element for an Desktop Automation Services input document.

application-runner-script has no attributes.

application-runner-script can contain any number of action elements.

application-runner-script Example: <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="sample-action"> <map-drive drive-letter="o:" remote-name="\\172.16.5.251\sys"/> </action></application-runner-script>

action-triggers

This element is a parent (container) for action-trigger elements ( on-nds-login, on-hot-key, and on-screen-saver).

action-triggers enables Desktop Automation Services executables to respond to workstation events by triggering specified actions as defined in the input document.

action-triggers has no attributes.

action-triggers can contain any of the following child elements:

  • on-nds-login

  • on-ldap-login

  • on-hot-key

  • on-screen-saver

  • on-cardmon

action-triggers Example: <action-triggers> <on-nds-login action-name="LoginInAction" tree="NCCD_TREE_1"/> </action-triggers>

on-nds-login

This element defines an action trigger to poll for a workstation user logging in to the eDirectory™ instance identified by the tree attribute. The authentication is through the Novell® Client32™ GINA. If a user logs in to the tree, an action trigger invokes Desktop Automation Services. It tests the primary connection to see if the current tree matches the configuration. If it matches, then Desktop Automation Services executes the configured action identified by the action name attribute value.

on-nds-login element must be contained by an action-triggers the parent element.

on-nds-login has two attributes:

  • action-name: The name of an action defined in the input document that is executed when a user logs in to the tree named by the tree attribute. The action-name must be contained in double quotes.

  • tree: Connections are tested periodically to see if they are linked to the tree named by this network name. The tree name must be contained in double quotes.

on-nds-login Example: <action-triggers> <on-nds-login action-name="LoginInAction" tree="NCCD_TREE_1"/> </action-triggers>

on-ldap-login

This element defines an action trigger to poll for a workstation user logging in to the directory through the Novell SecureLogin identified by the server attribute.

Desktop Automation Services tests the primary connection to check whether the current server matches the server attribute specified in the configuration. If the current server matches the configuration, then Desktop Automation Services executes the configured action identified by the action-name attribute value.

on-ldap-login must be contained by an action-trigger parent element.

on-ldap-login has two attributes:

  • server: The connections are tested periodically to check if they are linked to the tree named by this name.

  • action-name: The name of an action defined in the input document that is executed when a user logs in to the tree named by the tree attribute.

on-ldap-login Example: <action-triggers> <on-ldap-login action-name="LoginInAction" server="192.168.1.255"/> </action-triggers>

on-hot-key

This element installs an action trigger. The action trigger responds to the user typing the specified hot key sequence (see the example below) by invoking Desktop Automation Services to execute the input document action that has the same name as the action-name attribute value. on-hot-key elements must be contained by an action-triggers parent element.

on-hot-key has three attributes:

  • virtual-key: The hex value of the key based on the virtual key map. This element specifies that it is the second component of the hot key sequence.

  • modifiers: The modifiers indicate the keys that are pressed in together with the virtual-key to cause the hot-key event. The hex value might be a combination of one or more of the following, separated by a plus sign (+):

    • alt indicates the Alt key

    • ctrl indicates the Ctrl key

    • shift indicates the Shift key

    • win indicates the Windows key

    This element specifies that it is the first component of the hot key sequence.

  • action-name: The name of an action defined in the input document that is executed when the hot-key sequence is detected.

on-hot-key Example: <action-triggers> <on-hot-key virtual-key="h" modifiers="ctrl+shift" action-name="HKeyAction"/> </action-triggers>A virtual-key value of ‘h’ and a modifiers value of ‘ctrl+shift’ produces a Control-Shift-H HotKey sequence.

on-screen-saver

This element causes an action to be called when the workstation enters the screensaver mode. on-screen-saver elements must be contained by an action-triggers parent element.

on-screen-saver has the following attributes:

  • action-name: The name of the action defined in the input document that is executed when the workstation has entered the screensaver mode and that the specified interval has elapsed.

  • interval: This is the amount of time in milliseconds that the ARSControl waits before running the specified action after a screensaver event is triggered.

on-screen-saver Example: <action-triggers> <on-screen-saver action-name="action2" interval="1000"/> </action-triggers>

action

This is the parent element for all the commands that constitute an action.

action has one attribute:

action: The name can be any arbitrary string value. The character case in the name used by a caller to invoke an action must match the case used where the action is defined. The action-name must be contained in double quotes.

action can contain any number of the following child elements:

  • run-application

  • test-app-running

  • kill-app

  • kill-all-apps

  • map-drive

  • map-home-drive

  • map-location-drive

  • test-logged-in

  • test-ldap-logged-in

  • test-nds-attr-val

  • test-ip-subnet

  • test-env-variable

  • message-box

  • nds-logout

  • ldap-logout

action Example: <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="sample-action"> <map-drive drive-letter="o:" remote-name="\\172.16.5.251\sys"/> </action></application-runner-script>

run-application

This command element provides information that enables Desktop Automation Services to run an application and respond when the application is closed.

  • application: The name of the application.

  • parameters: A parameter lists the strings to pass to the application. For example, a normal DOS parameter syntax.

  • serial: If an application is launched using this command with the serial set to true (in synchronous mode), then the execution of the parent action does not continue until the application is closed or the interval timeout has expired.

  • interval: The timeout interval is used only when if the serial is true. If the application has not returned by timeout, then Desktop Automation Services stops waiting for a return and executes the action.

run-application has one optional attribute:

  • on-exit-action: When the application started by this element is closed, the specified action is called.

run-application cannot have any child elements.

run-application Example: <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="sample-action"> <run-application application="write" parameters="" on-exit-action=”launchSomethingElseAction” serial="true" interval="500"/> </action></application-runner-script>

test-app-running

test-app-running command element provides information that enables Desktop Automation Services to test whether an application is running or not.

test-app-running can have only one attribute:

  • application: The name of the application as it is found in the process list.

Because the test-app-running is a test command, it can contain either one or both of the following child elements:

  • if-true: An element containing the command operations to perform if the test returns a true value.

  • if-false: An element containing the command operations to perform if the test returns a false value.

test-app-running Example: <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="sample-action"> <test-app-running application="notepad.exe"> <if-true> <kill-app application="xmlspy.exe"/> <kill-all-apps exclude-apps="notepad.exe:xmlspy.exe"/> <map-drive drive-letter="F:" remote-name="\\172.16.5.250\sys"/> </if-true> <if-false> <map-drive drive-letter="G:" remote-name="\\172.16.5.251\sys"/> </if-false> </test-app-running> </action></application-runner-script>

kill-app

kill-app command element provides information that enables Desktop Automation Services to close an application.

kill-app has one essential attribute:

  • application: The name of the application to close, as found in the process list.

kill-app has one optional attribute:

  • interval: This is the amount of time in milliseconds that Desktop Automation Services waits after sending a close command to the application before killing the process. The default interval value is 1000.

kill-app cannot contain any child element.

kill-app Example: <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="sample-action"> <kill-app application="xmlspy.exe"/> </action></application-runner-script>

kill-all-apps

This command element provides information that enables Desktop Automation Services to kill all the running applications except those specified in the exclude-apps.

kill-all-apps has one essential attribute:

  • exclude-apps: The names of the applications that must not be killed. The application names are separated by a colon (:) character. The name of an application listed in this attribute must match the name of the application listed in the Processes tab of the Task Manager.

kill-all-apps has one optional attribute:

  • interval: The amount of time in milliseconds that Desktop Automation Services waits after sending a close command to an application before killing the process. Because each process is closed in a sequential order, a large interval significantly increases the amount of time the command takes to execute. The default value is 0.

kill-all-apps cannot have any child elements.

kill-all-app Example: <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="sample-action"> <kill-all-apps exclude-apps="notepad.exe:xmlspy.exe"/> </action></application-runner-script>

map-drive

This command element provides information that enables Desktop Automation Services to do a normal drive mapping.

map-drive has two essential attributes:

  • drive-letter: Specifies the drive letter to assign to the new mapped drive.

  • remote-name: Specifies the UNC file specification for a remote volume to be mapped.

map-drive cannot not contain child elements.

map-drive Example: <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="sample-action"> <map-drive drive-letter="G:" remote-name="\\172.16.5.251\sys"/> </action></application-runner-script>

map-home-drive

This command element provides information that enables Desktop Automation Services to map a drive to a home directory as defined by the homedrive attribute in the user’s eDirectory object.

map-home-drive has two essential attributes:

  • drive-letter: Specifies the drive letter to assign to the new mapped drive.

  • tree: Specifies the tree containing the object with the home directory information.

map-home-drive cannot contain any child elements.

map-home-drive Example: <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="sample-action"> <map-home-drive drive-letter="I:" tree="TestTree"/> </action></application-runner-script>

map-location-drive

This command element provides information that enables Desktop Automation Services to map a drive based on a properties file.

map-location-drive has four attributes:

  • drive-letter: Specifies the drive letter to assign to the new mapped volume.

  • tree: Specifies the tree containing the object with the location information.

  • attribute: Specifies the key to be used to obtain a value from the properties file.

  • file-name: Specifies the file system path to a properties file containing information for the map-location-drive operation. This file contains property information in the form of key or value pairs. The property key is located on the left of the equals to symbol (=) in a property item and the value is on the right side. For example: here=\\137.65.60.39\Share2 there=\\137.65.60.39\Share3

map-location-drive cannot contain any child elements.

map-location-drive Example: <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="sample-action"> <map-location-drive drive-letter="T:" tree="TestTree2" file-name="c:\yourFile.c" attribute="yourAttribute"/> </action></application-runner-script>

test-logged-in

This command element provides information that enables Desktop Automation Services to test whether the user is logged in to a particular eDirectory server or not.

test-logged-in can have only one attribute:

  • tree: The name of the tree for which the logged in state has to be tested.

Because the test-logged-in is a test command, it can contain either one or both of the following child elements:

  • if-true: An element containing the command operations to perform if the test returns a true value.

  • if-false: An element containing the command operations to perform if the test returns a false value.

test-logged-in Example: <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="sample-action"> <test-logged-in tree="TestTree"> <if-true> <run-application application="explorer.exe" parameters="" serial="false" interval="1000"/> <map-home-drive drive-letter="I:" tree="TestTree"/> </if-true> <if-false> <map-location-drive drive-letter="J:" tree="TestTree" file-name="c:\myFile.c" attribute="myAttribute"/> </if-false> </test-logged-in></action></application-runner-script>

test-ldap-logged-in

This command element provides information that enables Desktop Automation Services to test whether the user is logged in to a particular LDAP server or not. This command must only be used when using the LDAP GINA and Novell client32 is not used for authentication.

test-ldap-logged-in can have only one attribute:

  • server: The name of the server for which the logged-in state must be tested.

Because test-ldap-logged-in is a test command, it can contain either one or both of the following child elements:

  • if-true: An element containing the command operations to perform if the test returns a true value.

  • if-false: An element containing the command operations to perform if the test returns a false value.

test-ldap-logged-in Example: <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="sample-action"> <test-ldap-logged-in server="192.168.1.255"> <if-true> <run-application application="explorer.exe" parameters="" serial="false" interval="1000"/> </if-true> <if-false> <run-application application="iexplore.exe" parameters="" serial="false" interval="1000"/> </if-false> </test-logged-in></action></application-runner-script>

nds-logout

This test command element provides information that enables Desktop Automation Services to log out of the primary NDS® connection.

nds-logout cannot not have any attributes.

nds-logout cannot have any child attributes.

nds-logout Example: <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="sample-action"> <nds-logout/> </action></application-runner-script>

ldap-logout

This test command element provides information that enables Desktop Automation Services to log out of Novell SecureLogin.

ldap-logout can have one optional attribute:

  • gina: Can have either true or false values. If the value is true, the login dialog box for Novell SecureLogin is displayed after logging out of Novell SecureLogin. If the value is false, no action is taken. The default value is true.

ldap-logout cannot have any child elements.

ldap-logout Example: <action name="logoff"> <pause interval="100"/> <kill-all-apps exclude-apps="slbroker.exe:slwinsso.exe:slproto.exe:explorer.exe:"/> <ldap-logout gina="true"/></action>

test-nds-attr-val

This test command element provides information that enables Desktop Automation Services to test whether or not an NDS account contains a particular directory attribute with a particular value.

test-nds-attr-val has four attributes:

  • tree: The name or IP address of the tree containing the account to be searched for the attribute value.

  • attr-name: The name of the attribute to be tested in the NDS account.

  • attr-syntax: The syntax of the attribute to be tested in the NDS account.

    The acceptable attr-syntaxes are:

    • string

    • integer

    • boolean

  • attr-val: The value to be searched in the target attribute in the NDS account. The values for the Boolean syntax attribute must be either true or false.

NOTE:If the attribute syntax is string, then the comparison between the value retrieved from the eDirectory and the value of the attr-val is case sensitive.

Because the test-nds-attr-val is a test command, it can contain either one or both of the following child elements:

  • if-true: An element containing the command operations to perform if the test returns a true value.

  • if-false: An element containing the command operations to perform if the test returns a false value.

test-nds-attr-val Example: <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="sample-action1"> <test-nds-attr-val tree="TestTree" attr-name="cn" attr-syntax="string" attr-val="larry"> <if-true> <kill-app application="george.exe"/> <run-application application="fred.exe" parameters="" serial="true" interval="250"/> </if-true> <if-false> <map-drive drive-letter="S:" remote-name="\\172.16.5.253\sys"/> </if-false> </test-nds-attr-val </action> <action name="sample-action2"><test-nds-attr-val tree="TestTree" attr-name="cn" attr-syntax="integer" attr-val="123"> <if-true> <!—any commands may be inserted here--> </if-true> <if-false> <!—any commands may be inserted here--> </if-false> </test-nds-attr-val> </action> <action name="sample-action3"> <test-nds-attr-val tree="TestTree" attr-name="cn" attr-syntax="boolean" attr-val="true"> <if-true> <!—any commands may be inserted here--> </if-true> <if-false> <!—any commands may be inserted here--> </if-false> </test-nds-attr-val> </action><application-runner-script>

test-ip-subnet

This test command is useful for enabling an action to determine if the workstation resides on a particular network or not. This can be critical if the action is deciding whether to launch a particular application that is available or effective in a given network.

When invoked, the test-ip-subnet command executes the child commands if the current subnet of the workstation and the command’s addr attribute value are the same.

test-ip-subnet has two attributes:

  • addr: An IP subnet to compare with the local IP addresses of the machine.

  • subnet: The subnet mask (in the form of 255.255.255.0) is applied to the addr attribute and the local IP addresses, which are then compared. If the network portion matches, the test returns a true value.

Because the test-ip-subnet is a test command, it can contain either one or both of the following child elements:

  • if-true: An element containing the command operations to perform if the test returns a true value.

  • if-false: An element containing the command operations to perform if the test returns a false value.

test-ip-subnet Example: <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="sample-action"> <test-ip-subnet addr="192.168.1.0" subnet="255.255.255.0"> <if-true> <run-application application="write" parameters="" serial="true" interval="500"/> </if-true> <if-false> <run-application application="notepad" parameters="" serial="true" interval="500"/> </if-false> </test-ip-subnet> </action></application-runner-script>

test-env-variable

This test command element enables Desktop Automation Services to test whether an environment variable matches a specific value or not.

test-env-variable has two attributes:

  • var-name: The case-sensitive environment variable name. If the variable does not exist, the test returns a false value.

  • var-value: The value used for case-insensitive comparison with the actual variable value.

Because the test-env-variable is a test command, it can contain either one or both of the following child elements:

  • if-true: An element containing the command operations to perform if the test returns a true value.

  • if-false: An element containing the command operations to perform if the test returns a false value.

test-env-variable Example: <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="sample-action"> <test-env-variable var-name="Testvar" var-value="testvalue"> <if-true> <run-application application="write" parameters="" serial="true" interval="500"/> </if-true> <if-false> <run-application application="notepad" parameters="" serial="true" interval="500"/> </if-false> </test-env-variable> </action></application-runner-script>

message-box

This command element provides information that enables Desktop Automation Services to display a message box containing the text from the element’s caption attribute.

message-box has two attributes:

  • caption: The text to be displayed in the dialog box.

  • window-name: The title for the dialog box window.

message-box cannot have any child elements.

message-box Example: <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="sample-action"> <message-box caption="HotKey Control+H was pressed." window-name="HotKey Event"/> </action></application-runner-script>

execute-user-action

This command directs Desktop Automation Services to access the currently logged-in user and read a custom attribute ( ARSUserConfiguration) on that user. The value of this attribute must have the same layout as the standard XML used to configure Desktop Automation Services.

NOTE:The XML stored in the user object can contain actions. Triggers are not supported.

execute-user-action has one attribute:

  • action-name: The name of the configured action read from the user object.

Example value for the ARSUserConfiguration attribute <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="userAction"> <!--. . Any actions may be inserted here. . --> </action></application-runner-script>

execute-user-action Example: <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="sample-action"> <execute-user-action action-name="userAction"/> </action></application-runner-script>

if-true

This is one of the two allowed types of child elements for a test type of command. The other element is if-false.

if-true contains all the commands that must be performed if the test returns a true value. So, if-true can also be a parent element for all the commands that constitute an action.

if-true does not have any attribute values.

if-true can contain any number of the following child elements:

  • run-application

  • test-app-running

  • kill-app

  • kill-all-apps

  • map-drive

  • map-home-drive

  • map-location-drive

  • test-logged-in

  • test-ldap-logged-in

  • test-nds-attr-val

  • test-ip-subnet

  • test-env-variable

  • message-box

  • nds-logout

  • ldap-logout

  • execute-user-action

if-true Example: <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="sample-action"> <test-env-variable var-name="Testvar" var-value="testvalue"> <if-true> <run-application application="write" parameters="" serial="true" interval="500"/> </if-true> <if-false> <run-application application="notepad" parameters="" serial="true" interval="500"/> </if-false> </test-env-variable> </action></application-runner-script>

if-false

This is one of the two allowed types of child elements for a test type of command. The other element is if-true.

if-false contains all the commands that must be performed if the test resolves to false. if-false can also be a parent element for all the commands that constitute an action.

if-value does not have attribute value.

if-value can contain any number of the following child elements:

  • run-application

  • test-app-running

  • kill-app

  • kill-all-apps

  • map-drive

  • map-home-drive

  • map-location-drive

  • test-logged-in

  • test-ldap-logged-in

  • test-nds-attr-val

  • test-ip-subnet

  • test-env-variable

  • message-box

  • nds-logout

  • ldap-logout

  • execute-user-action

if-false Example: <?xml version="1.0"?><!DOCTYPE application-runner-script SYSTEM "ARS_1.0.dtd"><application-runner-script> <action name="sample-action"> <test-env-variable var-name="Testvar" var-value="testvalue"> <if-true> <run-application application="write" parameters="" serial="true" interval="500"/> </if-true> <if-false> <run-application application="notepad" parameters="" serial="true" interval="500"/> </if-false> </test-env-variable> </action></application-runner-script>