Tutorial: Running macros

If the host session you're using has the Macro feature enabled and macros have already been created and saved, they can be executed with the sdk. Since macros are always associated with a session, a running session instance is first needed to get the macros available for it.

// get a reference to an open session
var aSession = zfe.getSessionManager().getSessions()[0];

// get a reference to the session's already configured macros and pick the first one
zfe.getMacroManager(aSession).getMacros().then(function(macros) {
    var aMacro = macros[0];
    console.log('Running macro', aMacro.getName());
    aMacro.run()
        .then(function () {
            console.log(aMacro.getName(), 'has completed');
        });
});

Passing arguments

Macros can take a single input argument, which will be made available inside the macro context as arg. Since JavaScript is dynamically typed, this argument can be anything you need, from a simple int or string, to an Object with nested named properties. Note that macros run by the user in the webclient will not have arg values, so as a best practice they should be checked before being used.

// simple String arg
var promptUser = 'Hello world!';
myMacro.run(promptUser)
  .then(function () {
    console.log('Macro has completed');
  });

// snippet from the macro code using this
if (arg) {
  ui.message('Input arg: ' + arg);
}

// object with named properties
var arg = {
  min: 7,
  max: 42
};
myMacro.run(arg)
  .then(function () {
    console.log('Macro has completed');
  });

// snippet from the macro code using this
var min = (arg && arg.min) ? arg.min : yield ui.prompt('Enter a min value');
var max = (arg && arg.max) ? arg.max : yield ui.prompt('Enter a max value');
// do something with min/max

Returning values

If the macro code run returns a value, it will be passed to the next funtion in the Promise chain.

// snippet from macro code returning a value
var screenText = session.getPresentationSpace().getText({row:19, col:3}, 35);
return screenText;

myMacro.run()
  .then(function (result) {
    console.log('Macro returned screen text from 19,3:', result);
  });