Macros can be used in process definitions to automate certain tasks (see Scripts and Journals for more information on macros). They can be used in the following contexts:
to define common or complex logic used in expressions. Expressions are used to evaluate conditions such as validation of variables, continuation of iteration, and so on. If an expression requires logic that is too complex to express within the expression or is common to multiple expressions, you can remove the logic from the expression and put it in a macro. You can then reference the macro in any expression in your process definition. Macros that are used to evaluate expressions have access to all of the variables that are defined in the process as global variables.
to define commands executed by an auto node. When the process reaches an auto node, it will evaluate the associated macro and execute the commands defined in the macro.
to define custom dialog boxes for tasks. By default the dialog box for task completion and batch execution is automatically generated by EKM. But you can define custom dialog boxes if you want to control the layout or present the information in a different style.
to dynamically assign users and groups to a signoff request or task in a process
Macros are defined in the script element using a supported scripting
language. The script element has one optional attribute named
lang that specifies the scripting language used by the macros or
expressions in a process. It can take on two values: bsh for BeanShell
or py for Python. The default language is BeanShell which is taken if
the attribute is not specified.
BeanShell is a scripting language that can execute code written in standard Java syntax while providing scripting conveniences such as loose types. For more information on BeanShell and to see its detailed documentation, refer to http://www.beanshell.org. With BeanShell you have full access to all classes provided by Java’s JDK. EKM uses JDK 1.8, so you can use any of its classes in macros defined using BeanShell.
Python is a powerful and easy-to-use scripting language that is very popular. EKM uses Jython 2.7 to handle Python syntax. To learn more about Jython, refer to http://www.jython.org/index.html. To learn more about Python, refer to http://www.python.org. Jython 2.7 allows the use of Python 2.7 language features. In addition, you can use any Java classes offered by JDK 1.8.
The arguments that a macro can be passed, and the values that it can return, will depend on the context in which it is used.
Below is the bsh code for a sample
macro named incrementMacro.
incrementMacro() {
result = new HashMap();
result.put("index", index+1);
return result;
}
The macro increments a variable named index by one and will be used by an auto node in a process definition.
The following code snippet shows where incrementMacro macro name is defined for an auto-node.
<auto-node name="Add Node" description="" macro="incrementMacro" />
If you are defining a macro that will extract the name of an
assignee from a previous node in the process, the macro must take
an argument that is the node name, and must return a string that is
the name of the assignee. For example, you would specify foo(Run Analysis) when defining a macro named foo that will extract the assignee from a node named Run Analysis.
When you subsequently specify the assignee attribute for a node
or batch node, use $ followed by the macro
name (for example, $foo).
The sample macro shown below named hasDiscipline() utilizes a multi-valued String variable named Disciplines to evaluate whether the variable contains
a particular value. hasDiscipline() directly
references the Disciplines variable, which
is a global variable in the process definition. The macro will return
true only if one of the values of the Discipline variable is equal to the discipline passed as an argument to the
macro.
<script>
boolean hasDiscipline(String discipline) {
for (d : Disciplines) {
if (d.equals(discipline))
return true;
}
return false;
}
</script>
You can reference a macro in any expression in your process
definition. For example, hasDiscipline(‘Stress’) will call the macro with Stress as the argument
and it will evaluate to true only if the Disciplines variable contains Stress.
Note: Jython imposes a limit of 100 KB per script file. To avoid
process errors it is recommended that you create scripts using the EKM scripting
interface and store them in the /Administration/Configuration/Scripts folder. For details see Using EKM's Scripting Interface in the Administration Guide. Storing
scripts in a centralized library makes them available for any process,
lifecycle, or custom type. See Configuring a Common Scripts Library in the Administration
Guide for details.