Guidelines for Writing Extension Rules

Identify Your Event

An event is an action or condition that happens on your model at run time. For example, you modify the value of an attribute. Oracle Configurator can run your extension rule when a predefined event happens at run time. You can use these events to start the rule.

Use This Event	To Call Your Extension Rule Immediately After the User
postConfigInit	Starts the session. Use this event to set values in your model as soon as your user starts configuring the item.
postConfigSave	Clicks Save.
postValueChange	Changes a value or makes a selection in a node. For example, you modify the value of a decimal feature.
preAutoComplete	Clicks Finish or clicks Finish and Review. This event happens immediately before Configurator does the autocomplete at run time. Use this event to set values in your model before you review the configuration, or before you save and finish the configuration.

Set the Base Node

You must specify at least one node as the base node.

If the base node contains an item, and if you end date that node, then Configurator won’t run the extension rule on or after that end date. To see the end date for the rule, go to the Edit Configurator Model page, click Rules, then examine the End Date attribute in the Details section.

Configurator automatically adds the path that locates the node in the model when you click Set as Base Node.

It adds this path to the Base Node attribute in the node's Detail section.
You can also manually enter the path in the Base Node attribute. If you do, and if the value that you enter contains a space character ( ), then you must use single quotation marks (' ') to enclose the entire text that you enter.
If you need to copy the path for some reason, click the Structure tab. In the Details area, copy the value in the Path attribute, then navigate back to the node's detail area and paste the value into the Base Node attribute. If the node's name is unique in the model, then you can type the node name into the Base Node attribute, save the model, and Configurator will add the entire path for you.

If the model can have more than one instance of the base node, then Configurator enables the Instantiation Scope attribute, and sets its default value to Instance. The instantiation scope is a filter that determines how to run the rule. It determines:

When to run the rule
Whether to create a separate instance of the rule for each instance of the base node, or to create a single instance of the rule for all of the base node's instances

Enter the Rule’s Text

Save the rule while you work on the rule’s text, even if it isn't complete or correct.
Click Undo or click Redo to undo or redo text edits.
Use Next and Previous to navigate text.
Click Find and Replace to find and replace text.
Enter a value in Go to Line, then click the magnifying glass to go to a line.
Use the scroll bars, Click Maximize, and click Collapse Pane to help navigate your text.
Enter unformatted text, and the text editor will format it for you, such as adding color to help identify keywords, literals, and comments.
Green brackets and parentheses means you correctly closed the phrase, which is good. Red means you haven't, and that's bad. Fix your code until its green.

Bind Your Events

Click Validate, and Configurator will populate the values that you can select in the Class attribute and the Method attribute with the classes and methods that you have defined in your rule’s text. Click Validate at any time, and Configurator will update these values according to the classes and methods that you have added or removed from your script.
If you haven't clicked Validate at least one time, then the lists for these attributes are empty.

Set these attributes when you bind the event:

Attribute	Description
Event	Select the event that will start the method.
Event Scope	Create a filter that specifies when to apply the event binding. Set it to: Global. Use the binding when you modify a value on any node. Base Node. Use the binding only when you modify a value on the base node. If the scope applies to any extension rule in the model, then Configurator will run all the methods that you have bound to that event.
Class	Select the class that contains the method you're binding. If you didn't define your method in a class, then select ScriptClass.
Method	Select the method that you're binding to the event. If you didn't define your method in a class, then select `run()`, which runs all methods that aren't in a class.

You can bind more than one method in an extension rule. If you do, then the sequence that you use to create them doesn't affect how Configurator runs the rule.
You must bind at least one event to each rule.

Bind Your Arguments

Configurator automatically adds each method argument that you define in the rule’s text to the Argument Bindings area.
Configurator lists each argument with its own Name, Specification, and Value attributes in the Argument Bindings area.

Use the Specification attribute to specify how the method gets the value for the argument.

Specification	What You Do
Literal	Enter a numeric or string value, without quotation marks.
Model Node	Make sure you select the argument's row in the Argument Bindings area. If you don't do this, then Configurator won't populate the Value attribute on this row. Expand the Structure section on the Rules tab. Expand the model in the Structure section. Right-click the node that will provide the value for the argument, then click Set as Argument Value. Verify that Configurator automatically populated the Value attribute on this row. If the node's name is unique in the model, then you can enter the node name directly into the Model Node attribute, and Configurator will automatically add the path to the Model Node attribute when you save the model.

Specification

What You Do

Literal

Enter a numeric or string value, without quotation marks.

Model Node

Make sure you select the argument's row in the Argument Bindings area. If you don't do this, then Configurator won't populate the Value attribute on this row.
Expand the Structure section on the Rules tab.
Expand the model in the Structure section.
Right-click the node that will provide the value for the argument, then click Set as Argument Value.
Verify that Configurator automatically populated the Value attribute on this row.

If the node's name is unique in the model, then you can enter the node name directly into the Model Node attribute, and Configurator will automatically add the path to the Model Node attribute when you save the model.

Make sure you bind each argument that Configurator displays in the Argument Bindings section.

Validate Your Rule

Click Validate to validate your rule's text and your bindings. Note that this validation is different than the validation that you do for a statement rule. The statement rule validates only the rule's text.
Click Validate at any time to validate your code. Validating doesn't save or affect your work.

Here are some of the more common validations that Configurator does for you. It makes sure:

The rule's text isn't empty.
Your Groovy syntax is correct.
Your Groovy script doesn't have any annotations.
The rule has at least one base node.
The rule binds at least one event.
If the Groovy method that you bind to an event has arguments, then validation makes sure you bind all the arguments.

If you modify an event binding, then validation makes sure your modification is correct. If it isn't correct, then validation adds an error icon to the event. For example, modifying the method's name makes the binding incorrect. If you have an incorrect binding, the Configurator ignores it when you test the model.

More

If you modify the name of a node that the rule references, then Configurator:

Displays a warning that identifies the original name of the node that you modified.
Changes the rule's Status attribute to Error.

You must change the node's name to its original value, or update your script so it uses the new node name.

You can test a model that contains a rule that isn't valid. You can't release a model that contains a rule that isn't valid. You can also disable a rule that isn't valid, and then release the model.