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.
The more generalized description is that link rules have the form:
<== link link_name ==> link_condition1[, link_condition2]...[, link_conditionn]
The link_condition parameters may use the = operator to provide an exact match with the link, or may use one of the following operators:
contains value-list or contains all value-listcontains any value-listcontains none value-listwhere value-list is of the form:
value1[; value2] ... [;valuen]
Note: contains value-list and contains all value-list are equivalent, namely, contains value-list has the same meaning as contains all value-list.
Examples:
<== link AREA='Licenses', LICENSE_TYPE='License', COMPONENT='ABC' ==>
<== link AREA='Licenses', MULTI_VALUED_UDF contains ‘MV1’;’MV2’ ==>
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.
Link directives may also utilise a contains clause on a multi-valued field filter. For example, a rule like:
<== link idTextFieldLink ==>ID != TEXTFIELD_1, TEXTFIELD_2 contains TEXTFIELD_2
will retrieve all the issues where all the values in the UDF field TEXTFIELD_2 exist in the issue's values for TEXTFIELD_2.
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.
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.