A.9. Defining Macros

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:

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).

Using Macros in Expressions

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.



Release 18.2 - © ANSYS, Inc. All rights reserved.