Script basics

USE scripts are stored in <basedir>/system/config/use, and are ASCII files that can be created with any editor. Both UNIX and Windows end-of-line formats are supported but in certain circumstances, they may be automatically converted to UNIX end-of-line format.
Statements
Each statement in a USE script must be contained on a single line. Statements consist of a keyword followed by zero or more parameters separated by whitespace. The USE Reference Guide contains documentation for each statement.
Quotes and escapes
By default, a space, tab or newline will mark the end of a word in a USE script. To include whitespace in a word (for example to create a variable with a space in it) then double quotes - " - or an escape - \ - must be used to prevent the parser from interpreting the space as an end of word marker. Unless within double quotes, to specify a literal tab or space character it must be escaped by preceding it with a backslash character - \.
Examples:
1
"This quoted string is treated as a single word"  
2
var myname = "Eddy Deegan"  
3
This\ is\ treated\ as\ a\ single\ word
4
"The character \" is used for quoting"
Copied!
The following table summarises the behaviour:
Characters
Meaning
" ... "
Anything inside the quotes, except for a newline, is treated as literal text
\"
Whether within quotes or not, this is expanded to a double quote - " - character
\t
When used outside quotes, this is expanded to a TAB character
\
When used outside quotes, a space following the \ is treated as a literal character
\\
When used outside quotes, this is expanded to a backslash - \ - character
Comments
Comments in a USE script start with a # character that is either of
the first character of a line
the first character in a word
Comments always end at the end of the line they were started on
1
# This is a comment
2
set http_header "Content-Type: application/x-www-form-urlencoded"     # This is a comment
3
var usage#1 = Usage1   # The '#' in 'usage#1' does not start a comment
Copied!
Currently, comments should not be used on the same line as the encrypt statement as it will consider the comment as part of the value to encrypt
Variables
Overview
USE scripts often make use of variables. Variables have a name and a value. When a variable name is encountered on any given line during the execution of the script, the name is replaced with the value before the line is executed.
To reference a variable, the name should be preceded with ${ and followed by }. For example, to access the value of a variable called username, it should be written as ${username}.
The length (in characters) of a variable can be determined by appending LENGTH to the variable name when referencing it. Thus if a variable called result has a value of success then ${result.LENGTH} will be replaced with 7.
Creation
Variables may be explicitly declared using the var statement, or may be automatically created as a consequence of actions performed in the script. Additionally, a number of variables are automatically created before a script is executed.
For a list of variables created automatically please consult the article on the var statement
Encryption
It may be desirable to conceal the value of some variables (such as passwords) rather than have them represented as plain text in a USE script. This can be accomplished via the encrypt statement.
Publishing to the user interface
Variables may be exposed in the GUI by prefixing their declaration with the word public as follows:
1
public var username = username
2
public encrypt var password = something_secret
Copied!
Any variable so marked may be edited using a form in the GUI before the script is executed. If a public variable is followed by a comment on the same line, then the GUI will display that comment for reference. If there is no comment on the same line, then the line before the variable declaration is checked, and if it starts with a comment then this is used. Both variants are shown in the example below:
1
public var username = login_user  # Set this to your username
2
# Set this to your password
3
public var password = "<please fill this in>"
Copied!
If a variable declaration has both kinds of comment associated with it then the comment on the same line as the variable declaration will be used
Named buffers
A named buffer (also termed a response buffer) contains data retrieved from an external source, such as an HTTP or ODBC request. Buffers are created with the buffer statement.
Once created, a buffer can be referenced by enclosing its name in { and } as follows:
1
# Example of buffer creation
2
buffer token = http POST "https://login.windows.net/acme/oauth2/token"
3
​
4
# Examples of referencing a buffer
5
save {token} as "extracted\token.data"
6
discard {token}
Copied!
Buffer names may be up to 31 characters in length
Up to 128 buffers may exist simultaneously
Up to 2Gb of data can be stored in any given buffer (memory permitting)
Extracting data with Parslets
Parslets are used to extract data from from the contents of a named buffer.
Please refer to the full article on parslets for more information on parslets and their use.

Extractor templates

Parslets

Last modified 4mo ago

Export as PDF

Copy link

Contents

Publishing to the user interface

Named buffers

Extracting data with Parslets