ESSO Scripting Language ESSO Scripting Language Introduction The scripting language used is a full ECMAScript interpreter. Nevertheless, it's not a Javascript interpreter as it's used on web browsers. It only has the core elements of ECMAScript (Objects, Arrays, String, etc.) and a set of objects and functions specially designed for its purpouse. When the script is run, the elements matched, either window or HTML components, with a ref-as tag will be declared as global variable. Additionally, in the case of web applications, a global variable named document contains the reference to the full HTML document. Here are the supported functions and classes: Global functions ESSO SendKeys syntax secretStore object SystemInfo object Window class Document class Element class Collection class File class Directory class MailService class NetworkResource class Registry class ServerInfo class Hll class (version 1.4.0) 1. Global functions Global functions can be used in an action element: debug text: string Sends a message to the debug console. sleep millis: int Stops script execution for the specified milliseconds. Never stops the execution of the application. env text: string returns string Gets the value of an environment variable. exec text: string [Dir: string] Run an external application. Optionally, you can specify a directory to change to. execWait text: string [Dir: string] Executes external application and waits for its completion. Optionally, you can specify a directory to change to. sendKeys text: string Simulates the pressing of the keys indicated. You can see more information on the ESSO sendKeys syntax page. sendText text: string Simulates keystroke typed text. Unlike the SendKeys function, the text is sent, verbatim, without any interpretation. alert text: string Displays a confirmation message to the user. progress text: string Displays a progress message without confirmation from the user. cancelProgress Hide progress message. alertNoWait text: string A message, but does not expect the user confirmation. 1.1. ESSO SendKeys syntax SendKeys syntax The sendKeys function aims to perform as the user pressing keystrokes. Thus, the function SendKeys ("ABC") simulates to press those three letters. The keystrokes will be done independently of the application that generates them. Thus, it is possible to press keys that change the focused control or even the active application using sendKeys. To mimic the action of pressing to keys simultaneously, you can make use of modifiers. The available modifiers are listed at the attached table. So, to send the character ':' you can execute sendKeys("+."). This combination will simulate pressing the Shift key along with '.'. In order to allow a simpler syntax, you can use parentheses to specify more than one key affected by modifiers. Thus, the function SendKeys ("+ (hello)") generates the word HELLO in upper case. Modifier Key @ WINDOWS + SHIFT ^ CTRL % ALT It should be noted that this method can not get accented letters as a parameter, but the combination necessary to generate the desired letter. This method has a big drawback. The combination of keys needed to get a letter can be different depending of the current keyboard layout. So, in order to send arbitrary text characters, it is recommended to use the function sendText. Additionally, the sendKeys function supports this “virtual keystrokes” that do not correspond to a specific key but an actual action do be done: Tag Action taken. VKEY {X} The virtual code key (VKEY) will be sent. It is useful to use non-standard keys. XY {BEEP} A sound with a frequency X during Y time (in milliseconds). {DELAY X} X milliseconds pause. {DELAY = X} Make a dealy of X milliseconds between each simulated keystrokes. {AppActivate WindowTitle} Bring foreground and activates the application with the specified title. To send function keys, you can use the following codes: Key Tag Key Tag Backspace {BACKSPACE} or {BS} F1 {F1} Break {BREAK} F2 {F2} CapsLock {CAPSLOC} F3 {F3} Delete {DELETE} or {DEL} F4 {F4} Down arrow {DOWN} F5 {F5} End {END} F6 {F6} Enter {ENTER} or ~ F7 {F7} Ex {ESC} F8 {F8} Help {HELP} F9 {F9} Home {HOME} F10 {F10} Lnsert {INS} F11 {F11} Left arrow {LEFT} F12 {F12} Num Lock {NUMLOCK} F13 {F13} Next page {PGDN} F14 {F14} Previous page {PGUP} F15 {F15} Print screen {PRTSC} F16 {F16} Right Arrow {RIGHT} ^ {CARET} Scroll Lock {SCROLL} ~ {Tilde} Tab {TAB} { {LEFTBRACE} Up arrow {UP} } {RIGHTBRACE} + (Numeric keypad) {ADD} ( {LEFTPAREN} - (Numeric keypad) {SUBSTRCT} ) {RIGHTPAREN} * (Numeric keypad) {Multiply} windows (left) {LWIN} or {RWIN} / (Numeric keypad) {DIVIDE} windows (right) {RWIN} + {PLUS} context menu {APPS} @ {AT} Here are a few small examples : sendKeys parameter Effect {DELAY=50} 1. Specifies a pause of 50 milliseconds between keystrokes. @R 2. Click Windows + R to invoke the run dialog command. notepad~ 3. Enter notepad and pressed enter. hello world! 4. Write "Hello world!". %ua 5. Click the button to Alt + u, to show the About dialog box ... {Delay = 100} 1. Specifies a pause of 100 milliseconds between keystrokes. {AppActivate Calculator} 2. Turn the calculator. {ESC} 3. Click ESC to clear the contents. 5*7~ 4. Write 5 * 7 and pressed Enter. {beep 1000 500} 5. Makes noise. ^C 6. Press Control-C to copy the contents. {appactivate Notepad} 7. Switch to notepad. ^E 8. Click to e-control dial all. {DEL} 9. Click Delete to delete the contents. Result of 5 * 7 is: 10. Writes "The result is 5 * 7". ^V 11. Click control-v hold the result.. {DELAY=500}{NUMLOCK}{CAPSLOCK}{SCROLL} 1. Turn numbers, uppercase and scroll on in order. {SCROLL}{CAPSLOCK}{NUMLOCK} 2. Turn them off in the reverse order. {DELAY=500} 1. Specifies a pause of 500 milliseconds between keystrokes. %? 2. Click Alt-Space. {DOWN 5} 3. Click the down arrow five times. 2. secretStore object Introduction This object is always visible from any action, and provides access to the user's passwords and secrets. User passwords are always related to a system account. This is the object used to retrieve user and password in order to inject credentials into applications. Methods getSecret text: string returns string Gets the value of a secret. getAccounts system: string returns string [] Gets the list of accounts available for a given systemsecretStore object. getAccount system: string returns string Gets the account to use a particular system. If more than one are available, the system will prompt the user for the one to use. If the user cancels the dialog box, an exception will be thrown. If no account is available, the undefined value will be returned. getPassword system: string account: string returns string Gets the password bound to the account on the system requested. setPassword system: string account: string newPassword: string Changes the password at the password vault (version 1.4) setSecret name: string value: string Sets the value of a secret at the password vault (version 1.4) generatePassword system: string account: string returns string Generates a random password suitable for the selected account (version 1.4) 3. SystemInfo object Introduction The SystemInfo object is always visible from any action, and provides access to information about the machine. Attributes os string Specifies the name of the operating system: Windows / Ubuntu oSVersion string Indicates the version of the operating system. osDistribution string Distributor operating system: Microsoft / Ubuntu / RedHat / .... hostName string Return the team name. clientHostName string For remote connections, returns the name of the source host. fileSeparator string Separator files depending on the platform: / Linux \ For Windows username string Operating system user name. It can be different from Soffid user name. 4. Window class Introduction When an action is bound with a user interface application, it creates an object of class Window for each component at the XML descriptor with a ref-as attribute. Those components have the following methods: Methods getText returns string Gets the text value of the component. setText text: string Change the text value of a component. click Acts as if the user clicks on the component. It's suitable on button components. setFocus Move the focus to the component. 5. Document class Introduction When an action is associated with a Web application, it creates a document that identifies the full HTML document. This object assigned to the document variable. Thus, scripts can access the web contents and its DOM tree in runtime. The document object implement a subset of the standard DOM HtmlDocument. Attributes url string Full URL of the document. domain string Contains the domain of the page. title string Title of the document. cookie string Contains cookies that are bound to this document. anchors Collection Contains elements of type A. forms Collection Contains items of type FORM. images Collection Contains items from IMG. links Collection Contains elements of type A and AREA. documentElement Item Contains the root element. Methods getElementById id: string Element returns Find the first element with the specified ID. getElementsByTagName tag: string returns Collection Find all elements with the specified tag. write text: string Add content to the document. writeln text: string Add content and new line to the document. autofill text: string Proceed with smart auto fill engine, allowing end user to select and or save accounts. The mandatory parameter sets the domain where to look for accounts. 6. Element class Introduction The objects of type Element are created for each input element with a ref-as attribute, or are obtained from the Document itself. It implements a subset of the DOM class HtmlElement. Attributes childNodes Collection Vector of children elements. disabled bool Indicator whether the element is disabled or not. id string Id attribute of the element. tagName string Element's tag. parentNode Item Parent element. Methods getAttribute name: string returns string Gets the attribute value of the element. setAttribute name: string value: string Updates the attribute value. removeAttribute name: string Removes an attribute. getElementsByTagName tag: string returns Collection Find all children with the specified tag. click Acts as if the user had clicked on the button. blur Remove focus. focus Grants focus. submit Send form contents. 7. Collection class Introduction The collection object implements a subset of the standard DOM HTMLCollection Attributes length Long Number of items in collection. Methods item id: long returns Element Find the element with id order number. The first element is 0. namedItem id: string returns Element Search for an item with the given name. First search an element with matching Id attribute. If none is found, search for an element with matching Name attribute. 8. File class Introduction It allows easy manipulation of files using the File class. Constructor File file: string mode: string Create an object of type File for the specified file. If mode is “r”, the file will be opened in read mode. If mode is “w”, the file will be opened in write mode. If the mode is “a”, the file will be open in append mode. Methods read byte int (1000) returns string Reads at most the specified number of bytes. When no numer is specified, 1000 bytes will be read at most. readLine returns string Reads untill end of line. write text: string Writes the specified text. WriteLine text: string Writes text with and end of line. close Closes the file. flush Flush all buffers to disk. eof returns boolean Returns true if the end of file has been reached. (static) methods and attributes Additionally, the File object has the following (static) methods and attributes: mkdir directory: string Creates the specified directory. stdin File Attribute that contains a File object associated with standard input. stdout File Attribute that contains a File object associated with standard output. stderr File Attribute that contains a File object associated with the standard error output. copy source: string target: string Copy selected file. This method is not able to copy directories. delete file: string Deletes a file or directory. move source: string target: string Moves (or renames) a file or directory. isDirectory f: string returns boolean Returns true if the specified file is a directory. canRead f: string returns boolean Returns true if the file can be read. canWrite f: string returns boolean Returns true if the file can be written. getParent f: string returns string Returns the parent directory of a file. 9. Directory class Introduction This class is able to look for directories content. A directory object has the following attributes and methods: Constructor Directory file: string Creates a directory object bound to the specified path. Methods length returns int Indicates the number of files in the directory. item return string Specifies the name of the file content. 10. MailService class Introduction Simple tool to send emails. The MailService object has the following methods. Constructor MailService Create an object of type MailServer. Methods setServer server: string Specifies the name of the mail server. setFrom from: String Specifies the name of the sender. Setter to: string Specifies the name of the recipient. send text: string Send the message indicated. 11. NetworkResource class Introduction Connect and disconnect network services (disks and printers). Constructor NetworkResource Creates an object of type NetworkResource. Methods connectPrinter resource: string model: string Connects a remote printer to the local spooler. connectDrive localDrive: string resource: string password: string (optional) user: string (optional) Connects a network drive. disconnectAllPrinters Disconnects all remote printers. disconnectPrinter name: string Disconnects a remote Printer. disconnectDrive localName: string Disconnects a remote drive. 12. Registry class Introduction Manipulate the windows registry. Constructor Registry path: string Create an object of type Registry Global objects Registry.HKEY_LOCAL_MACHINE Tree Key LOCAL_MACHINE Registry.HKEY_CURRENT_USER Tree CURRENT_USER key Registry.HKEY_USERS Tree Key USERS Registry.HKEY_CLASSES_ROOT Tree Key CLASSES_ROOT Registry.HKEY_LOCAL_MACHINE32 Tree LOCAL_MACHINE 32-bit keys Registry.HKEY_CURRENT_USER32 Tree CURRENT_USER key 32bit Registry.HKEY_USERS32 Tree 32bit key USERS Registry.HKEY_CLASSES_ROOT32 Tree CLASSES_ROOT 32-bit keys Methods openKey path: string returns Registry Opens a registry subkey. createKey path: string returns Registry Creates a registry subkey. getValue entryName: string Object returns Reads registry value. setValue entryName: string value: Object type: string Updates a registry value. Type (optional) can be: - REG_SZ - REG_EXPAND_SZ - REG_BINARY - REG_DWORD - REG_MULTI_SZ 13. ServerInfo class Introduction This helper class allows the script to query information stored at Soffid console. Constructor ServerInfo path: string Queried the server returning an object of type ServerInfo. Methods length returns int Returns the number of rows obtained. row n: int object returns Returns information about the n-throw from. The objects returned depend on the path indicated.14. Hll class (version 1.4.0) Introduction The Hll class gives the script engine access to Hll terminal emulators. When a hll pattern matches the emulator screen, a hll object of class Hll will be crated and can be used by the action script. Attributes sessionId string Full URL of the document. sessionName string Contains the domain of the page. columns int Numer of columns. rows int Number of rows. Methods getCursorLocation returns object with row and column attributes Gets the cursor location. setCursorLocation row: integer column: integer Changes cursor location. getContent returns String Gets the terminal emulator screen content. sendText text: string Send text to host. sendKeys keys:string Send text, possibly containing escape sequences. Escape sequence The following escape sequence are defined: Mnemonic Meaning 3270 5250 VT @B Left Tab Yes Yes No @C Clear Yes Yes No @D Delete Yes Yes No @E Enter Yes Yes No @F Erase EOF Yes Yes No @H Help No Yes No @I Insert Yes Yes No @J Jump (Set Focus) Yes Yes No @L Cursor Left Yes Yes Yes @N New Line Yes Yes Yes @O Space Yes Yes Yes @P Print Yes Yes Yes @R Reset Yes Yes No @T Right Tab Yes Yes Yes @U Cursor Up Yes Yes Yes @V Cursor Down Yes Yes Yes @X* DBCS (Reserved) Yes Yes No @Z Cursor Right Yes Yes Yes @0 Home Yes Yes No @1 PF1/F1 Yes Yes No @2 PF2/F2 Yes Yes No @3 PF3/F3 Yes Yes No @4 PF4/F4 Yes Yes No @5 PF5/F5 Yes Yes No @6 PF6/F6 Yes Yes Yes @7 PF7/F7 Yes Yes Yes @8 PF8/F8 Yes Yes Yes @9 PF9/F9 Yes Yes Yes @a PF10/F10 Yes Yes Yes @b PF11/F11 Yes Yes Yes @c PF12/F12 Yes Yes Yes @d PF13 Yes Yes Yes @e PF14 Yes Yes Yes @f PF15 Yes Yes Yes @g PF16 Yes Yes Yes @h PF17 Yes Yes Yes @i PF18 Yes Yes Yes @j PF19 Yes Yes Yes @k PF20 Yes Yes Yes @l PF21 Yes Yes No @m PF22 Yes Yes No @n PF23 Yes Yes No @o PF24 Yes Yes No @q End Yes Yes No @u Page Up No Yes No @v Page Down No Yes No @x PA1 Yes Yes No @y PA2 Yes Yes No @z PA3 Yes Yes No @A@C Test No Yes No @A@D Word Delete Yes Yes No @A@E Field Exit Yes Yes No @A@F Erase Input Yes Yes No @A@H System Request Yes Yes No @A@I Insert Toggle Yes Yes No @A@J Cursor Select Yes Yes No @A@L Cursor Left Fast Yes Yes No @A@Q Attention Yes Yes No @A@R Device Cancel (Cancels Print Presentation Space) Yes Yes No @A@T Print Presentation Space Yes Yes Yes @A@U Cursor Up Fast Yes Yes No @A@V Cursor Down Fast Yes Yes No @A@Z Cursor Right Fast Yes Yes No @A@9 Reverse Video Yes Yes No @A@b Underscore Yes No No @A@c Reset Reverse Video Yes No No @A@d Red Yes No No @A@e Pink Yes No No @A@f Green Yes No No @A@g Yellow Yes No No @A@h Blue Yes No No @A@i Turquoise Yes No No @A@j White Yes No No @A@l Reset Host Colors Yes No No @A@t Print (Personal Computer) Yes Yes No @A@y Forward Word Tab Yes Yes No @A@z Backward Word Tab Yes Yes No @A@- Field - No Yes No @A@+ Field + No Yes No @A@< Record Backspace No Yes No @S@E Print Presentation Space on Host No Yes No @S@x Dup Yes Yes No @S@y Field Mark Yes Yes No @W@C Edit Copy Yes Yes Yes @W@D Edit Clear Yes Yes Yes @W@E Edit Copy Append Yes Yes Yes @W@L Edit Copy Link Yes Yes Yes @W@N Edit Paste Next Yes Yes Yes @W@V Edit Paste Yes Yes Yes @W@X Edit Cut Yes Yes Yes @W@Z Edit Undo Yes Yes Yes @X@1 Display SO/SI Yes Yes No @X@5 Generate SO/SI No Yes No @X@6 Display Attribute No Yes No @X@7 Forward Character No Yes No @X@c Split Vertical Bar No Yes No @M@0 VT Numeric Pad 0 No No Yes @M@1 VT Numeric Pad 1 No No Yes @M@2 VT Numeric Pad 2 No No Yes @M@3 VT Numeric Pad 3 No No Yes @M@4 VT Numeric Pad 4 No No Yes @M@5 VT Numeric Pad 5 No No Yes @M@6 VT Numeric Pad 6 No No Yes @M@7 VT Numeric Pad 7 No No Yes @M@8 VT Numeric Pad 8 No No Yes @M@9 VT Numeric Pad 9 No No Yes @M@- VT Numeric Pad - No No Yes @M@, VT Numeric Pad , No No Yes @M@. VT Numeric Pad . No No Yes @M@e VT Numeric Pad Enter No No Yes @M@f VT Edit Find No No Yes @M@i VT Edit Insert No No Yes @M@r VT Edit Remove No No Yes @M@s VT Edit Select No No Yes @M@p VT Edit Previous Screen No No Yes @M@n VT Edit Next Screen No No Yes @M@a VT PF1 No No Yes @M@b VT PF2 No No Yes @M@c VT PF3 No No Yes @M@d VT PF4 No No Yes @M@h VT HOld Screen No No Yes @M@(space) Control Code NUL No No Yes @M@A Control Code SOH No No Yes @M@B Control Code STX No No Yes @M@C Control Code ETX No No Yes @M@D Control Code EOT No No Yes @M@E Control Code ENQ No No Yes @M@F Control Code ACK No No Yes @M@G Control Code BEL No No Yes @M@H Control Code BS No No Yes @M@I Control Code HT No No Yes @M@J Control Code LF No No Yes @M@K Control Code VT No No Yes @M@L Control Code FF No No Yes @M@M Control Code CR No No Yes @M@N Control Code SO No No Yes @M@O Control Code SI No No Yes @M@P Control Code DLE No No Yes @M@Q Control Code DC1 No No Yes @M@R Control Code DC2 No No Yes @M@S Control Code DC3 No No Yes @M@T Control Code DC4 No No Yes @M@U Control Code NAK No No Yes @M@V Control Code SYN No No Yes @M@W Control Code ETB No No Yes @M@X Control Code CAN No No Yes @M@Y Control Code EM No No Yes @M@Z Control Code SUB No No Yes @M@u Control Code ESC No No Yes @M@v Control Code FS No No Yes @M@w Control Code GS No No Yes @M@x Control Code RS No No Yes @M@y Control Code US No No Yes @M@z Control Code DEL No No Yes @Q@A VT User Defined Key 6 No No Yes @Q@B VT User Defined Key 7 No No Yes @Q@C VT User Defined Key 8 No No Yes @Q@D VT User Defined Key 9 No No Yes @Q@E VT User Defined Key 10 No No Yes @Q@F VT User Defined Key 11 No No Yes @Q@G VT User Defined Key 12 No No Yes @Q@H VT User Defined Key 13 No No Yes @Q@I VT User Defined Key 14 No No Yes @Q@J VT User Defined Key 15 No No Yes @Q@K VT User Defined Key 16 No No Yes @Q@L VT User Defined Key 17 No No Yes @Q@M VT User Defined Key 18 No No Yes @Q@N VT User Defined Key 19 No No Yes @Q@0 VT User Defined Key 20 No No Yes @Q@a VT Backtab No No Yes @Q@r VT Clear Page No No Yes @Q@s VT Edit No No Yes @@ @ Yes Yes Yes @$ Alternate Cursor (The Presentation Manager Interface only) Yes Yes Yes @< Backspace Yes Yes Yes @:@s Screen Reverse Yes Yes Yes @:@n Bidi Layer Yes Yes Yes @:@l Latin Layer Yes Yes Yes @:@F Field Reverse Yes Yes No @:@p Push Yes No No @:@e End Push Yes No No @:@a Auto Push Yes No No @:@r Auto Reverse Yes No No @:@d CSD Yes No No @:@f Final Yes No No @:@i Isolated Yes No No @:@m Middle Yes No No @:@t Initial Yes No No @:@h Field Shape Yes No No @:@u Field Base Yes No No @:@b Base No Yes No @:@o Close No Yes No @:@K Column Heading No No Yes @:@B Cursor Direction No No Yes @:@D Encoding Mode No No Yes @:@M VT Change Display Mode No No Yes (Hebrew only) ESSO Scripting examples 1. Run an application like notepad exec ("notepad.exe"); 2. Automatic application update if (SystemInfo.os == "Linux") { exec ("(mkdir /tmp/google-chrome-updates && " + " wget -O /tmp/google-chrome-updates/google-chrome-stable_current_amd64.deb " + " -c https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb " + " && apt-get update && sudo apt-get install libappindicator1 " + " && sudo dpkg -i /tmp/google-chrome-updates/google-chrome-stable_current_amd64.deb " + " && sudo apt-get install google-chrome-stable) " + " >/var/log/google-chrome-stable_current_amd641.log 2>&1 " ); } 3. account = secretStore.getAccount("soffid.org-ldap"); debug("Account = "+account); u.setAttribute("value", account); password = secretStore.getPassword("soffid.org-ldap", account); debug("Password = "+password); p.setAttribute("value", password); sleep(100); debug("Clicking"); b.click(); debug("Clicked");