4.3 Application Definition Best Practices
The following are some of the best practice rules to follow when creating an application definition. These rules make reading the application definition easier and also help if you need to make modifications in the future.
4.3.1 Symbols Used
Table 4-1 Description of Symbols
|
Symbol |
Description |
|---|---|
|
< > |
Angle brackets represent an item. For example, text, variable, or value. |
|
[ ] |
Square brackets represent an optional item. If an item is not marked with square brackets, it is a compulsory item. |
|
|
Indicates a line break |
4.3.2 Blank Line Between Sections
NOTE:Always place the title after all other commands in the dialog block.
Leave a blank line between sections, for example, between the dialog block and the rest of the application definition.
|
Instead of |
Use |
|---|---|
# Logon Dialog Box Dialog Class #32770 Title "Log on" EndDialog Type $Username #1001 Type $Password #1002 Click #1 |
# Logon Dialog Box Dialog Class #32770 Title "Log on" EndDialog Type $Username #1001 Type $Password #1002 Click #1 |
4.3.3 Capitalization
Use capitalization where applicable.
Table 4-2 Capitalization
|
Instead of... |
Use... |
|---|---|
|
messagebox "some text" -yesno ?result |
MessageBox "Some text" -YesNo ?Result. |
4.3.4 Comments
Use comments throughout to explain what each section does and how it does it.
|
Instead of... |
Use... |
|---|---|
Dialog Class #32770 Title "Log on" EndDialog |
# Written by B. Smith 2004, modified C. Silvagni 2006 # Logon Dialog Box Dialog Class #32770 Title "Log on" EndDialog |
4.3.5 Indent Section
Indent sections between pairs of commands, for example Dialog, Repeat, and If. Use an indent of three spaces.
|
Instead of... |
Use... |
|---|---|
If -Text "Some text" #Do thisElse #Do This EndIf |
If -Text "Some text" #Do thisElse #Do this EndIf |
4.3.6 Password Policy Names
Password policy names must represent the program they are used for. Do not use numerical names.
|
Instead of... |
Use... |
|---|---|
|
PasswordPolicy3 |
GroupwisePasswordPolicy |
4.3.7 Quotation Marks
Always use quotation marks around segments of text in commands.
|
Instead of... |
Use... |
|---|---|
|
Type TextOrIf -Text Login |
Type "Text"OrIf -Text "Log on" |
4.3.8 Regular Expressions
Regular expressions are text patterns normally used for string matching. Regular expressions might contain a mix of plain text and special characters to indicate the kind of matching to be done.
For example, if you are searching for any numeric character, then the regular expression that you use for the search is, “[0-9]”.
The square [ ] brackets indicate that the character that is compared must match any one of the characters enclosed with in the brackets. The dash ( - ) between the zero (0) and nine (9) indicates that the range is between the number zero and nine.
If you need search for a special character, then you must use the backslash (\) before the special character.
If your regular expression does not match any controls on a particular application screen, SecureLogin will prompt you to check your regular expression and ensure the correct control is selected. Special characters in your regular expression might need to be escaped.
The following table briefly describes the characters that can be used in regular expressions within SecureLogin application definitions, in particular the RegSplit command detailed in RegSplit.
|
Character |
Description |
|---|---|
|
\ (Backslash) |
The \ is an escape character indicating that the next character must be used as a regular search character and not as a special character. For example, the regular expression “\” matches a single asterisk and the expression “\\” matches a single backslash. |
|
^ (Caret) |
The ^ is an anchor. If you use the ^ preceding any character, it searches the beginning character of any string. For example, the expression “A^” matches an “A” only at the beginning of the string. |
|
[^ (Square bracket and Caret) |
The ^ immediately following [, is used to exclude the characters within the square brackets from matching the target string. For example, the expression “[^0-9]” specifies that the target character must not be a numeral. |
|
$ (Dollar sign) |
The $ is an anchor. The $ matches the end of the string. For example, the expression “abc$” matches the substring “abc” only if it is at the end of the string. |
|
| (Vertical bar or pipe) |
The | allows the character on either side of the vertical bar (or pipe) to match the target string. For example, the expression “a|b” matches a as well as b. |
|
. (Period or full stop) |
The . matches any character. |
|
* (Asterisk) |
The * indicates that the character to the left of the asterisk in the expression must match at least zero or more times. |
|
+ (Plus sign) |
The + indicates that the character to the left of the plus symbol in the expression must match at least once. |
|
? (Question mark) |
The ? indicates that the character to the left of the question mark must match at least zero or more than once. |
|
( ) (Parentheses) |
The ( ) enclosing a set of characters affects the order of pattern evaluation and also serves as a tagged expression that can be used when replacing the matched substring with another expression. |
|
[ ] (Square brackets) |
The [ ] enclosing a set of characters indicates that any of the enclosed characters might match the target character. |
Capture Groups
If you are using the regular expressions to extract information rather than just match the text, use capture groups. You can use a captur egroup when using regular expressions to select credentials to be used based on a particular option from a common dialog box. For example, the name or IP address of a particular server to which you want to connect. In such a scenario, SecureLogin uses the capture group to make a unique name for a credential set and allows users to have different credentials for different servers.
For example, if a message indicating Welcome Kerry to the Corporate server is displayed, then Kerry is the name of the user and Corporate is the name of the server. If you want to match just the text, Welcome .+ to the .+ server. If you want to use the server name as the name of the credential set, so that you can create other credential sets for other servers, add a capture group to the same regular expression and get Welcome .+ to the (.+) server.
For more information about regular expressions and usage, see the Boost website.
NetIQ uses the Boost regular expression library (in Perl) when developing SecureLogin. While other reference sites provide detailed and comprehensive information about regular expressions, only the expressions listed in the tables are supported by NetIQ.
4.3.9 Switches
Switches are placed directly after the command, for example, Type -Raw, If -Text.
Table 4-3 Switches
|
Instead of... |
Use... |
|---|---|
|
Type $Username -Raw |
Type -Raw $Username |
4.3.10 Variables
All variable names start with a capital letter.
Table 4-4 Variables
|
Instead of... |
Use... |
|---|---|
|
Type $username |
Type $Username |
4.3.11 Writing Subroutine Sections
Write subroutine sections at the bottom of the application definition and not partway through.
The name of the subroutine should describe its function. Do not use a numeric name. The name should follow the capitalization rule.
Wherever possible, use the Include command to create generic application definitions for frequently used elements, for example password change procedures. For common processes within the same application definition, use subroutines.