Macros are made available to users in two ways; created by an administrator or recorded by users for their own private use. All advanced macros are associated with a session and they all accomplish the same goal, automating host interaction. The only difference between the two flavors is simply who can access them and who manages their creation and availability:
Macros created by administrators
Administrators create macros when they create the session. They are specific to a session and are available to all users who have access to the session from the Macro icon on the toolbar. Administrators can designate macros to run at startup or when the session connects or disconnects from the host.
Macros created by users
End-user macros are created by individuals for sessions they are authorized to access. The administrator grants permission to create macros by setting a User Preference Rule. Users can access the session under their own credentials or in a Guest role. Macros that Guest users create are available to all Guest users. Users who are logged in using their own credentials can only see macros that they have created.
Advanced macros are listed in alphabetical order in the drop down list available from the toolbar. Macros created by the end-user are listed first and followed by an indicator of three vertical grey dots, which when selected, displays the Edit and Delete options. Macros created by the administrator are listed without the indicator as those macros cannot be modified by the end-user.
Working with Macros
Follow these steps to record, edit, and run macros.
Click the Macro icon on the toolbar, and then click Record New Macro.
Navigate the host application to record the series of steps you want included in the macro.
Click on the toolbar to stop recording. The red dot pulses to indicate the recording is in process.
When prompted, type a name for the macro.
From the Macro drop-down list, select the macro you want to edit.
Click the three vertical dots to expand the field.
Click to open the Macro Editor (in the left panel).
To run a macro, choose the macro from the drop-down list and click .
You can also map keys that will automatically trigger an already recorded macro. In the Key Map settings dialog box, choose Run Macro from the Action drop down list. Choose a macro to associate with the key mapping from the Value list.
You can stop a macro before it completes from either the Macro Editor or the toolbar. Click to stop the macro. To rerun the macro, navigate back to the macro starting screen.
From the Macro drop down list, select the macro you want to delete.
Expand the field, by clicking the three vertical dot icon.
The Macro drop down list is available from the toolbar to all users who have permission to record macros or are accessing a session where macros have been pre-recorded by the administrator for use with that session.
Macros are listed under either MY MACROS or MACROS depending on how they were recorded.
All users, whether they are logged in using their credentials or as Guest, can see the macros associated with the session. Macros listed under the MY MACROS heading are listed in alphabetical order by name and are visible to those users that recorded them. Macros recorded by the administrator and attached to a session are listed alphabetically under MACROS.
To debug a macro:
Open the macro for editing. See Working with macros for instructions.
Open your browser’s development tools.
Browser Open debugger Mozilla Firefox 40.0.3
- From the toolbar, open the Menu, and choose Developer.
- From the Web Developer menu, choose Debugger. The debugger opens in a lower panel.
Google Chrome 45.0
- From the toolbar, open the Menu, and choose More tools.
- Choose Developer Tools to open the Debugger.
Microsoft Internet Explorer 11
- From the toolbar, open Settings, and choose F12 Developer Tools.
- Open the Debugger tab.
Use one of the these tools in your macro code, and run the code.
The most thorough approach to debugging is to use the
‘debugger;’statement. When you insert these statements into your macro code then run it, with the browser’s development tools open, the execution will stop on those lines. You can step through your macro, view the value of local variables and whatever else you need to check.
var hostCommand = menuSelection + ‘[enter]'; debugger; // <— Browser's debugger will stop here ps.sendKeys(hostCommand);
var hostCommand = menuSelection + ‘[enter]'; console.log('Command:' + hostCommand); // <— Will output the string to "Console" tab alert('Command:' + hostCommand); // Will pop up a small window containing the data ps.sendKeys(hostCommand);
var hostCommand = menuSelection + ‘[enter]'; ui.message('Command:' + hostCommand); // <— Will pop up a message window ps.sendKeys(hostCommand);
Keep in mind:
Stepping and “yields”
While the yield statements in macros make them easier to understand, they can make the code more challenging to step through with the debugger. Consider either using multiple debugger statements or carefully placed debugger statements of
console.log()calls to output the right debug information.
Debugging in Internet Explorer involves transformed code and may be more difficult than on other browsers.
Using the Macro API
The Macro API consists of a set of objects which you can use to interact with the host, wait for screen states, and interact with the user.
About promises and yields
Promises are patterns to help simplify functions that return their result asynchronously, at some point in the future. All ‘wait’ and ‘ui’ functions in the Macro API return promise objects.
Macros use the yield keyword to block the execution of the macro until a promise is resolved, or done. So putting yield in front of any ‘wait’ or ‘ui’ function makes the macro execution pause until that function has finished executing. You can place the yield keyword in front of any function that returns a promise, even your own custom functions.
The ability to make macro execution block by combining yield with promises is enabled by the
Errors are handled in macros using a try / catch statement. Some API functions may throw errors if, for example, conditions can’t be met or a timeout occurs. The thrown error is ‘caught’ in the catch statement. You can wrap smaller blocks of code in a try / catch statement to handle errors at a more granular level.
Macro developers can also throw errors by using
'throw new Error('Helpful error message');