Product Documentation

calendar calendar_name

This directive is used to determine which business calendar is used in date computations. If no calendar directive is present, the calendar specified in the behavior setting named RULES_DEFAULT_CALENDAR is used. If this is not set to a valid calendar name, the 24_BY_7 calendar is used for date computations.

clone

This directive is used to execute rules and assignments during the clone process. For example, you can set the value, or reset the value of fields before the cloned record is saved to the database

debug

Logs rule activity and includes ExtraView internal values. Primarily for use by ExtraView support. All statements from the point where the directive is found, and forward from there, send deugging information to the application server log file

end

Stops parsing of the rule file. If this directive is encountered in the rules file, ExtraView stops further actions and ignores the remainder of the rules.

Only the rules in the current business area stop executing. If you have also have rules in the global area then they will also execute, unless an <== end ==> directive also exists within there.

This is useful in debugging your rules, as you can enter this directive at different points in your rules file as you test successive sections of rules.

info

Causes log entries to verify that rules are being executed. Minimal details are listed

link

Linking Issues between Business Areas

This directive is used to specify how to connect linked issues from one business area to a different one, thereby creating a relationship between two business areas.

For example, you can find one or more related issues in a different business area, from which a value is to be retrieved:

<== link customer ==> AREA=’Customer’, CUSTOMER=CUSTOMER

is interpreted that a rule action like:

ASSIGNED_TO=(customer).OWNER

which is used to set the Assigned To field in an Issue record to the OWNER field in a Customer record. If the link returns many records, and you only want to return a specific one, you can use a subscript as follows:

ASSIGNED_TO=(customer[nn]).OWNER

where nn is an integer which refers to the number of the record you want returned, starting with zero.

Linking Relationship Groups

The link directive can also be used to link related issue groups. For example:

<== link rglink ==> RG(RG_NAME = MY_RG, RG_TYPE = PARENTS)

where MY_RG is the name of an existing relationship group and RG_TYPE is one of PARENTS, CHILDREN, MEMBERS. If multiple records are referenced by the link, only the first one returned will be used for data assignments. For operations such as UPDATE all records will be processed. You may add an expression to the related issue link to form the link. For example:

<== link rglink ==> RG(RG_NAME = MY_RG, RG_TYPE = PARENTS), STATUS != Closed

will only form the relationship for issues that are not in the Closed status.

Relationship Group links are not order dependent; the type and name may appear in either order, and the RG_ may be omitted, so RG(TYPE=CHILDREN, NAME=xxxx) will work identically to RG(RG_NAME=xxx, RG_TYPE=CHILDREN). Also, the keywords may be eliminated entirely, giving RG(xxxx, CHILDREN) as a valid link. Note that GREATGRANDCHILDREN and GREAT-GRANDCHILDREN are only supported in links, and are not supported at this time by RelationshipGroup code.

{NULL} and {NOT NULL} may also be used within link conditions. For example:

<== link AREA='Licenses', LICENSE_TYPE='License', COMPONENT={NULL} ==>

You may also add the {EXISTS} as a qualifier to a clause in a link directive. This will check the link, before execution, to find whether the value is present, or is a null value. For example, consider:

<== link cousinLink ==>AREA='Functionality', BROTHER_ID = PARENT_ID.{EXISTS}

If the .{EXISTS} was not present, all records with no value for the BROTHER_ID will be selected if the PARENT_ID is null.

You may also add a parameter of DISABLE_LINK to a LINK directive. This has the effect of suppressing the drilldown into the issue on the link. For example, the following is correct syntax.

<LINK AREA='Bugs' DISABLE_LINK>

If the value of the behavior setting named ITEM_ID_DISPLAY is ID, then the link uses the ID field to connect the linked issues.  If the value is ALT_ID, then the ALT_ID field value is used in the links.

Linking with Wildcards

By default, reference to a link value returns the first value in the result list for an assignment statement.  However, a subscripted value (such as (linkname[n]).ID may be specified, returning the nth value in the result list for an assignment statement.  With this feature, all values in the list can be returned by specifying a wildcard subscript such as (linkname[*]).ID. This convention will return all values in the result list separated by semicolons.

Relationship Group Reference ID Feature

The RG link references currently permit the specification of RG_NAME and RG_TYPE. With this feature, you can specify RG_REF_ID, which specifies a field name containing the ID (or ALT_ID) of the relationship.  For example, the following rules:

<== link rgParentIssueLink ==> RG(RG_NAME=MY_GROUP, RG_TYPE=PARENTS, RG_REF_ID=MY_TEXTFIELD)
<== load ==>
MY_TEXTFIELD = 12345;
MY_TEXTAREA = (rgParentIssueLink[*]).ID;

populate a semicolon-separated list of the parents of issue 12345 from MY_GROUP into the MY_TEXTAREA field.

load

Called before the Add or Edit screen is rendered. Rules following this directive are executed before the screen is displayed. Therefore you can set values of fields before the screen loads.

Note that the load rules are only executed when the Add or Edit screen is first loaded. If the user changes the Business Area field or the Project field thereby generating a screen refresh, the load rules are not run again

log

From the point where the directive is encountered, information is inserted into the application server log, for administrators to verify rule execution. The log file shows conditional evaluations and assignments. The nolog directive ends the logging

mail

Mail directives are used to notify users of updates using the standard notification layouts. They can either complement the existing inbuilt notification rules or replace the inbuilt rules, depending on the value of the behavior setting named SUPPRESS_STANDARD_EMAIL_LIST. The mail directive will always contain rules that generate the notification based on the notification layout for the issue being inserted or updated.

Note there is a key difference between the mail directive and the mail action rule which is typically used within the preupdate directive. The mail action is used to send an email based upon a template specified within the action.

nolog

This is the counterpart of the log directive and ends the logging set in progress with the log directive

object

This directive is used to define an object to be used as a link between two fields of different types. The most common purpose for this directive is to use it to enter a value into a text field, and have this value added to an existing list field.

Use the object directive to use a value entered in a text field to be inserted as a new value in a list field.

As an example, you may create directive rules similar to:

<== object cust ==> AREA='Customers', LINK=CUST_LIST, TITLE=SHORT_DESCR, PRIVACY=false

<== object cust.{guarantee} ==> AREA='Customers', LINK=CUST_LIST, TITLE=SHORT_DESCR, PRIVACY=false

<== object custpopup ==> AREA='Customers', PROJECT='Contacts', LINK=CUST_POPUP, TITLE=SHORT_DESCR, PRIVACY=false, DO_NOT_MIGRATE=true

This link may be used in a rule similar to:

if (CUST_LIST.{changed}) {
  CUST_CONTACT = (cust).CUST_CONTACT;
  EMAIL_ADDRESS = (cust).EMAIL_ADDRESS;
}

This is a list of all the parameters that may be used with the object directive:

LINK=<LIST or POPUP field name>

Required - contains the name of the field with the list entry to be added, modified, or deleted

TITLE=<TEXTFIELD field name>

Required - contains the name of the field containing the title or text to be added to the list entry

PARENT=<field name>

Optional - contains the name of the parent field of the LINK field in an allowed value relationship

AREA=<area title>

Required - specifies the area of the issue where the object rule is executed

PROJECT=<project title>

Optional - specifies the project within the AREA where the object rule is executed. If this is not defined, then the object directive is executed for all PROJECTS within the defined AREA

RG_NAME=<relationship group name>

Unused at present

PRIVACY=TRUE | FALSE

Optional - the option to add PRIVACY=true will add the customer to a privacy group with the same title, and add the current user to that privacy group.

DO_NOT_MIGRATE=TRUE|FALSE

Optional - if this is provded and has a value of TRUE, then all User Defined Field values created with the OBJECT rule are not migrated from one ExtraView instance to another via the XML Export / XML Import utilities.  This allows the addition of test data values within one instance using the OBJECT rule, but ensures the data is not migrated to the target instance.  Note that the UDF list utility will show which values were added with this parameter.

In summary, the link causes a value entered into the CUSTOMER field in the Customers business area to be automatically added to the list named CUST_LIST. This list is available in any other business area and is used in the rule to bring the values associated with the customer into the current screen, when a customer is chosen from its list.

The {guarantee} qualifier to the object rule allows an issue to be created when the rule is executed, but prevents the value to the title being added as a duplicate to the list.  If the value does not exist, it will be created but if the value exists, that will be used.

onchange or refresh

When a field on your layout has a rule that references it, and that the user changes the value of that field, then an onchange rule is triggered. For example, you may have two fields on a layout, named amount1 and amount2. You may have an onchange rule:

total = amount1 + amount2;

When the user changes either amount1 or amount2, the total field on the layout will be updated via an Ajax call to the server

In previous versions, this functionality was provided by the refresh directive, which also required an HTML modifier on the fields amount1 and amount2. If you are upgrading from ExtraView version 6.0 or a prior release, you should remove the HTML modifier on these fields as they will cause an unnecessary screen refresh

postupdate

Postupdate rules are executed subsequent to a database update on the add or edit screen

preupdate or database

Preupdate rules are executed prior to a database update. After you press the button to submit an issue to the database on the add screen, or you press the Update button on the edit screen, these rules are executed. The directives preupdate and database are synonymous. In the future, the term database may be deprecated as it is not fully descriptive of the purpose of the directive