Understanding scopes

A scope helps determine when a script runs during a session. For example, if you want the script to run when a specific page loads, set the script to run when the page scope is entered.

A scope defines context in the connection to the host.

Scope types

There are 5 default scope types: global, beforeSession, session, template/page, and field. There is also a custom scope type.

Some scopes can be active at the same time. For example, the global scope is always active. Active scopes are organized using a scope stack, for example:

field

template

session

global

When a scope is entered, it is added to the top of the stack and any scripts linked to it run. The scope stack helps determine which scripts have priority. See the section on Event Handlers below for more information.

Scopes are entered in the following order:

1.The global scope is never entered, but is always present at the bottom of the scope stack. Since the global scope is never entered, you can't link a script to run when it is entered. However, event handlers (described below) can be added to the global scope. The global scope is named "global".

2.When the Client initiates a connection to a host, the beforeSession scope is entered. This scope is used for handling events before the host connection is made. For example, use a script to change the host address before connecting. (For more information on the beforeSession scope and the Preconnect event, see the WLEvent.on() function.) The beforeSession scope is exited before the session scope becomes active. The beforeSession scope is named "beforeSession".

3.A session scope is entered when a session begins. The session scope is named “session”.

4.A page (web) or template (TE) scope is specific to a page sent from the host. When the page loads, the scope is entered. Only one page or template scope is active at a time.

•A page scope is entered when a specific URL is loaded. A page scope is named after the path without the hostname or port. For example, if the URL of the page is https://www.ivanti.com/wl/help/velocity.htm, use the page scope: “@wl/help/velocity.htm”

• A template scope is entered when a page sent from the host matches a formatting template. A template scope is named after the template, for example: “@T1”.

5.A field scope is entered when the cursor enters a field on the screen. For TE, a field scope is named after the template and component ID. For example: “@T1:input-000900034”. For web, the field scope is only entered when Velocity.enterField() is called.

A custom scope is entered when you use the WLEvent.enterScope() function. You can have more than one custom scope active at a time.

Using event handlers

If you want to use scripting for a specific event, create an event handler using the WLEvent.on() function. An event handler waits for an event to happen and then executes. For example, if you want to append a Tab keypress to scan data during the session, create an event handler that fires when scan data is received. If you attach the event handler to the session scope, it will fire for all scan data during the session. If you attach the event handler to a field scope, it will only fire when scan data is received while the cursor is in that particular field.

When a scope is entered, it is added to the top of the scope stack. When an event fires, the handlers in the top-most scope are processed first. If the event handler returns false then no other handlers are processed. For example, if you have an event handler for scan data attached to both the field scope and the template scope, the handler for the field scope runs first. If the first handler returns false, the second handler never runs. If the first handler returns a value other than false, then the second handler runs.

When a scope is exited, any event handlers associated with it are discarded.

Linking a script to a scope

Unless the scripts you use are part of a customized Rapid Modernization project, you need to link the scripts to a scope in order for them to run.

For information on creating a script or adding a Library script to your project, see Adding or editing a script.

To link an existing script to a scope

1.From the Advanced Configuration screen, select the script and then click Link in the Scope column.

2.Type the scope you want the script to run in and click OK.

After a script has been linked to a scope, you can modify the parameters for it.