How You Create Extension Rules

You can extend the functionality of your configurator model by creating extension rules, which use code that you write in the Groovy scripting language.

The essential tasks in creating an extension rule are:

• Creating the rule and assigning a base node

• If necessary, selecting an instantiation scope

• Entering rule text

• Adding event bindings

• If necessary, adding argument bindings

• Validating the rule and testing it

Prerequisites

The following things are required when defining an extension rule.

• The model node that's to be the base node for the extension rule must already exist.

  Note: If the model node is an item type that might be end dated, then the extension rule will become invalid upon the end date of the item. The end date of the extension rule is displayed in the End Date field of the Details region of the Rules tab of the Edit Configurator Model page.

Creating Extension Rules and Assigning the Base Node

1. On the Rules tab of the Edit Configurator Model page, select Create Extension Rule from the Rules toolbar.

2. Enter a name and optional description for the extension rule.

3. Open the model tree in the Structure pane, and select the model node that's to be the base node of the extension rule.

   You can associate an extension rule with any type of node, within the model containing the rule.

4. Right-click the model node and select Set as Base Node from the context menu. The fully-qualified node name path of the model node is inserted in the Base Node field.

   You can also enter the node path directly as plain text, in the Base Node field Any node names that contain spaces must be delimited with single quotation marks. You can copy a node path from the Path field on the Details region of the Structure tab for the model .If the node's name is unique within the model, then you can type the node name (but not description) directly into the Base Node field. When you save the model, the full node path will be added for you.

5. If the base node can have multiple instances, then the Instantiation Scope control is enabled. The default selection is Instance.

Entering the Rule Text

The rule text defines the behavior of the extension rule.

1. Enter the text of a valid Groovy script into the Rule Text field. Click Save to save the rule text and the rest of the rule definition.

   Tip: You can save the rule as you work on the rule text, even if it's not complete or correct.

2. To ensure that the extension rule, and the rule text, are valid, click Validate, at any point during the definition.

Adding Event Bindings

Add at least one event binding to the rule.

1. In the Event Bindings table, click Create

2. In the new row for the event binding, from the Event list, select the event to bind.

3. From the Event Scope list, select the event scope in which the event is to be evaluated.

4. From the Class list, select the class that contains the method that you're binding to the event.

   If no classes are defined in the script, select ScriptClass, which contains globally-defined methods.

   Tip: Click Validate to refresh the Class and Method lists after any changes to the script to add classes or methods. If you haven't yet clicked Validate, then the lists will be empty.

5. From the Method list, select the method that you're binding to the event.

   If no methods are explicitly defined in the script, select run(), which executes globally-defined methods.

You can create multiple event bindings for an extension rule. The sequence in which you create them isn't significant for the execution of the rule.

Adding Argument Bindings

When you select a method with arguments for the event binding, the Argument Bindings table is automatically populated with a row for each argument. The Name column for each argument contains the read-only name of the argument, copied from the method definition in the rule text.

1. Select a row in the Argument Bindings table.

2. From the Specification column for each argument, select the specification for how the method obtains the argument value.

3. If you select a specification of Literal, then enter a numeric or string value, without quotation marks.

4. If you select a specification of Model Node, then open the model tree in the Structure pane, and select the model node that provides the value for the argument. Then right-click the node and select Set as Argument Value. If the node's name is unique within the model, then you can type the node name (but not description) directly into the Model Node field. When you save the model, the full node path will be added for you.

5. Repeat the argument binding for each argument in the Argument Bindings table.

6. Click Validate, to validate both the rule text and the rest of the rule.

7. Click Save, Save and Compile, or Save and Close.

Validating Extension Rules

You can ensure that the entire extension rule (both rule text and bindings) is valid, by clicking Validate, at any time during the definition. (In contrast, the Validate button for statement rules only validates the rule text.)

You can validate the rule at any point while you're defining it. Some of the requirements that are commonly reported by validation are the following

• An extension rule must have a base node.

• The rule text can't be empty.

• An extension rule must have at least one event binding.

• If your Groovy method bound to the event has arguments, you must bind the arguments.

• Groovy annotations aren't allowed.

• Your Groovy script must be syntactically correct. Any Groovy syntax and programming errors are reported.

• If you change your script in a way that makes existing event bindings invalid, then the invalid events are marked with an error icon. For example, changing the name of a method invalidates any even bindings using that method. A rule with invalid bindings becomes invalid and is ignored when testing the model