<== link link_name ==>

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.

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-list
  • contains any value-list
  • contains none value-list

where 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’ ==>

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.

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.

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.

Link Rules with Multi-Valued Field Filters

Link rules may use a contains clause on multi-valued field filters.
 
Thus, a link rule like:
 
<== link idTextfieldLink==> ID != MY_TEXTFIELD,MULTI_MAIN contains MULTI_MAIN 
 
can be written to retrieve the items where any of the values in the MULTI_MAIN UDF exist in the issue’s values for MULTI_MAIN.
 
You can use any of the following where MVA is a multi-valued field and <values> is a collection of potential values for MVA.
  • MVA.{contains any <values>}MVA.{contains all <values>}
  • MVA.{contains none <values>}
  • MVA.{contains <values>}
  • MVA.{excludes <values>}
The same operators also work with link rules as follows.
  • <== link mva1Link ==> AREA='Simpsons',MVA = MVA
  • <== link mva2Link ==> AREA='Simpsons',MVA contains MVA
  • <== link mva3Link ==> AREA='Simpsons',MVA excludes MVA
  • <== link mva4Link ==> AREA='Simpsons',MVA contains any MVA
  • <== link mva5Link ==> AREA='Simpsons',MVA contains all MVA
  • <== link mva6Link ==> AREA='Simpsons',MVA contains none MVA

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.

Linking Issues using ID’s Stored within a Text Field

It can be useful to link issues stored with a delimited list of ID’s to the current issue.  Let’s say that you have a text field named ISSUES_TO_LINK.  This may have a content such as 123;456;789.  You might want to perform an update operation on all issues linked together.  The syntax of the link rule would be:

<== link linkFieldIDs ==> ID = RELATED_ISSUES_TO_LINK
    ISSUES_TO_LINK = '123;456;789';
    {UPDATE: linkFieldIDs STATUS='Approved'};

As a result of executing the link directive, the issues with IDs of 123, 456 and 789 will be updated with a STATUS of Approved.