A.9. Defining Macros

Engineering Knowledge Manager

User's Guide | Appendix A. Defining a Process Template Using XML |

A.8. Defining Expressions |  | A.10. Defining Process Attributes
Prev |  | Next

## 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:

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

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

Contains proprietary and confidential information of ANSYS, Inc. and its subsidiaries and affiliates.

Prev | Up / Contents | Next

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