Related Issue Layouts

Related issues are displayed with layouts that use the naming convention RELATED_XXXXX. To create a new related issue layout, you first create a layout type where the name begins with RELATED_ Note that the usage of related issue displays must be Report. In the normal way for layouts, these may be inherited by any Business Area or Project which will use them. These are used to display the related records within add, edit and report layouts. The layout contains the fields you want to display when viewing the related issues. There is a single default related issue display layout within a new ExtraView installation, named RELATED_ISSUE_DISPLAY. The default fields on this layout are VIEW_BUTTON, QUICKEDIT_BUTTON, EDIT_BUTTON, RELATIONSHIP_GROUP_REMOVE_BTN, ID, STATUS, ASSIGNED_TO and SHORT_DESCR. You may change any of these fields to meet your requirements.

When you configure a related issue display layout to allow the creation of new related issues, you are able to place a button on a header to the display. This button may have any text, and when pressed will open a modal window where you can add the issue you are creating into the relationship with the current issue on the screen. On reports all related issues are displayed, allowing you to print the results clearly.

On add and edit screens, the related issues are placed within a scroll box whose dimensions are controlled by the layout cell attributes named SIZE and HEIGHT. If you do not provide a layout cell attribute for SIZE, then the default is 125 characters. Within the layout, you can also use a SIZE layout cell attribute on the individual fields to control their width. If you do not use a SIZE attribute on individual fields, then the width of each field floats and the user's browser will decide on the optimal width. The height of the related issue display is calculated automatically, to display all the records in the group unless a HEIGHT layout cell attribute is added to the related issue display, to provide a maximum height.

You can fix the position of the column titles of the related issue display with the layout cell attribute named RID FIX TITLES.  When you set this attribute it is not recommended that you use the SIZE attribute on fields within the related issue display layout.

Sample Rendering of Related Issue Display Layouts

Some sample layouts rendered on Add and Edit screens are:

Related issues on a report

Editing related issues on an add or edit screen

Adding new related issues on an add or edit screen

The modal popup to add a related issue

Related Issue Display Layouts

You may create any number of additional related issue display layouts, but you must begin the name of the layouts you create with RELATED_. For example, as well as RELATED_ISSUE_DISPLAY, and as an example, you may create another related issue layout named RELATED_SUPPLIERS. All the layouts to be used as related issue displays must be created with a display type of Report, even if they are to be embedded within an Add or Edit layout. Once you have created the layout type, you then include the layout on the Add, Edit or Detailed Report layouts.

For the above example, you would include LAYOUT.RELATED_SUPPLIERS on the layout. When you create a related issue layout, a new field is created automatically in the data dictionary, with the same name as your layout. In our example, the field RELATED_SUPPLIERS is created. The field has the usual PR_ADD_PROBLEM and PR_RESOLUTION permission keys, and these control visibility to the the related issue display layout on the add and edit layouts for the different roles in your installation.

The field RELATIONSHIP_GROUP_REMOVE_BTN is an inbuilt field with special treatment. It is defined in the data dictionary with a type of LABEL and a display type of BUTTON. Although it is placed on RELATED_ISSUE_DISPLAY layouts, it will only appear when the layout is rendered within an Add or Edit screen. It is ignored on report layouts and on the POST_EDIT_UPDATE layout. There is a security permission key named PR_RESOLUTION.RELATIONSHIP_GROUP_REMOVE_BTN to control the appearance of the Remove? checkboxes on the Add and Edit screens. Its function is to allow the end user to remove a related issue from the relationship group. The user may check any number of related issues and the checked issues will be removed from the relationship when the current issue is updated. Removing an issue from a relationship does not delete the issue.

Embedding Related Issue Display Layouts Within a Layout

As stated above, related issue display layouts are designed to be embedded within add, edit, report and other layouts which are then embedded within add, edit and report layouts. This screenshot shows a related issue display layout embedded within an edit layout:

 

 

Layout Cell Attributes for Related Issue Display Layouts

Over and above the standard layout cell attributes that can be applied to all cells on layouts, the following attributes allow configuration of embedded related issue display layouts.

Cell Attribute Purpose
BUTTON ACTION

The RID BUTTON ACTION attribute is applied as a cell attribute to the RID PREHEADER ADD BUTTON. The action defines what happens when the user presses the add button. This attribute is applied directly to the field's global attributes, defined within the data dictionary, as opposed to being set as a layout cell attribute on the related issue display layout.

  • Target Business Area - This defines the Business Area that will be used for the add screen displayed when the button is pressed
  • Target Project - This defines the Project that will be used for the add screen displayed when the button is pressed
  • Check Required Fields - If you check this option, then all required fields on the parent issue that will be required by the child issue, are checked that values are filled in, before the child window is displayed. This can be extremely useful if you are going to push down field values from the parent to the child issue, and you want to ensure that the child window is always initiated with a value within a field
  • Action after Submitting the Child Issue - This option allows you to select the action after the child issue is created. You can either have only the related issue display that contains the newly added issue updated, or you can have the parent issue updated and the entire screen updated. The latter is only required when there are some business rules that triggered changes to the parent issue when the child issue was submitted
  • Push Down Field List - Double click on the fields whose values you want to push down from the parent issue to the child issue. The selected fields are displayed in the right-hand list
  • Show Generate Script - This button is provided for advanced usage. It is possible to configure button actions that are more complex than can be done with the BUTTON ACTION utility. This option allows you to generate the JavaScript that is close to what you require. You can then copy this JavaScript into the RID ONCLICK_JS attribute, and modify it for your requirement. You should not save the BUTTON ACTION if you are using RID ONCLICK_JS and vice versa.

Note that you may define more than one BUTTON_ACTION on a single related issue display.

DRILLDOWN This attribute should only be applied to a field that contains the ID of the related issue. You can choose to set the drilldown to either a value of View or Edit according to the type of drilldown window you wish to open
HEIGHT This defines the maximum height of the related issue display when it is rendered within an add or edit layout. The height is input in rows, where each row is estimated to be 20 pixels. If the height required to render the issues is less than this value, then the related issue display is resized to only take the height required. If the height required is more than this value, a vertical scroll bar is placed on the related issue display.  The titles to the fields are always fixed in position, so that when the user scrolls the list of related issues, the titles remain visible.

The setting has no effect on reports where the entire contents of the related issue display will be rendered.

RID ACT ON FIELD CHANGE This attribute is not applied to a relationship layout, but is applied to the field (the RID LINK FIELD NAME above) that is used to link the result set from a search to a relationship issue display. When this attribute is present on the RID LINK FIELD NAME, along with an HTML modifier to trigger the action, a related issue display is refreshed, creating links from each issue ID within the RID LINK FIELD NAME, and displaying these issues in the related issue display. A full example of the use of this feature is provided in Example 4
RID FILTERS

This cell attribute allows the administrator to specify a set of filters to apply to the selection of the related issues to display. This filter is applied to only the related issue records so the user will only see a subset of the related issues. For example, this screenshot shows the administrator about to select values for filters for the Business Area and Status fields:

Note that beyond the selection of specific values to use for filters, there are several other possibilities:

  • * Any * - This value is not used.  Setting it is the same as not using the filter
  • * Ask at runtime * - The user will be prompted when the related issue display is being generated, to provide a value for the filter
  • * Value from issue * - The value to be used within the filter for the related issue display will be taken from the current value within the field of the same name, that is displayed to the the user on the screen
  • $$SYSDAY$$ or $$SYSDATE$$ - These may be used within day or date display type fields to filter on the current day or date.  It is not too practical to filter on aa field being equal to $$SYSDATE$$, as the date includes time to the millisecond, and it's unlikely that issues will match this.  Using operators of less than or greater than with date type fields is more useful.
RID FIX TITLES This attribute may only be set on Related Issue Display layouts within Add, Edit layouts, or sublayouts of these.  When this attribute is used in conjunction with the HEIGHT attribute, and a scroll bar appears after issues have been added, the title to the Related Issue Display is fixed as the user scrolls.

It is not recommended that you place SIZE layout cell attributes on the fields contained within the Related Issue Display layout when you use this attribute.  Likewise, it is not recommended that you use this option if you expect that the user will see text that wraps within the Related Issue Display.  The best results are obtained when the browser sizes all the columns and column titles.

RID GROUP REFERENCE FIELD The default for this attribute is the ID field. This attribute may be set to provide a different field for the relationship to be formed between the issues. The field must exist on both the layouts that are being related
RID LINK FIELD NAME This attribute is used when you are using a search layout on an add or edit layout to return one or more issues to relate them to the current issue. RID LINK FIELD NAME must be a field with a display type of text field or text area and the field is typically hidden within the add or edit layout and is used to transition the list of issued from the search results into the list of issues to be related. The list is a series of issue ID values, delimited by semi-colons. If the RID SINGLE SELECT attribute in this table is set, then there can only ever be a single issue ID in the list. Text fields are capable of storing 255 characters. The link field stores the ID's of all issues selected within the results, plus an extra character as a separator between each ID. They therefore store approximately 40 - 60 ID's. If you are likely to link more than this number of issues, make sure the RID LINK FIELD NAME has a display type of text area. These are highly scalable for this purpose.

Linking a Single Result to Populate Fields within the Current Issue

If you are using the RID LINK FIELD NAME to link the search results to a single issue and you then want to take fields within that issue and place their values within the current issue, you are likely to also configure a link and a refresh business rule to retrieve the field values you require from the search result. See Example 3.

Linking Multiple Search Results to Populate a Related Issue Display

If you are using the RID LINK FIELD NAME to link the search results to multiple issues that you want to relate to the current issue, and place these issues within a related issue display on the current layout, you are likely to also configure RID LINK FIELD NAME with these attributes:

  • RID ACT ON FIELD CHANGE - This attribute indicates that an action will be taken when this field is updated as a result of being linked to search results
  • RID RELATIONSHIP NAME - This is the name of the relationhip group into which the records from the search results are to be placed
  • RID RELATION TYPE - This is the type of the relationship. Usually this will be CHILDREN, but PARENTS may also be appropriate

See Example 4 for details on how to configure this.

RID ONCLICK_JS RID ONCLICK_JS is the JavaScript that is executed when the INCLUDE ADD BUTTON button is clicked. For most purposes, the script that is executed is created by the RID BUTTON ACTION cell attribute and you do not require to use the RID ONCLICK_JS attribute. The RID ONCLICK_JS attribute is provided for advanced configurations where the administrator wants to create JavaScript that goes beyond the capability of the RID BUTTON ACTION attribute. You must not configure both the RID BUTTON ACTION and the RID ONCLICK_JS attributes on the same button, as they will conflict with each other. The JavaScript for RID ONCLICK_JS should be carefully constructed, and there may be differences when wanting to use the JavaScript to initiate a popup to add a new issue when on the add and on the edit screens. If you want to add related issues on both the add and edit screens, you may need to configure a different INCLUDE ADD BUTTON in the data dictionary for each screen, each with the appropriate RID ONCLICK_JS value. It is possible to configure and place multiple buttons to add different types of issues on a single related issue display.

Basic Syntax

Substitutable values are possible in this string value. To create a modal popup window the basic JavaScript you use will be:

doEditAEActions(window.parent.extraview_app_home_url , '__SESSION_ID__', 
new Array('POPUP_MODAL_ADD', 'add_confirm_page=NO' + rgParameters(), 
'RELATIONSHIP_GROUP_REFRESH', '__LAYOUT_TYPE_ID__' ));

Note the two substitutable variables SESSION_ID and LAYOUT_TYPE_ID. They must be surrounded by double underlines. This provides the mechanism for ExtraView to substitute the variable at runtime. You set a value of YES or NO to the add_confirm_page parameter, depending on whether you want to display or suppress the verification layout or the ADD_CONFIRMATION layout that is typically shown to users after submitting a new issue. If you set NO, then the verification screen is never shown. There is a built-in method that generates the necessary relationship group parameters for the ADD operation. These are needed to force the insertion of the child issue into the correct Relationship Issue Display relationship group using the relation type of the Related Issue Display. This is rgParameters() and it is in scope from the button when the button is inserted into the header of the Related Issue Display.

Updating and Refreshing the Underlying Issue

There are use cases where you might want to update and refresh the parent Add or Edit screen, after you add a child issue. For example, while adding a child issue, Business Rules might execute that update the parent issue. If you want this behavior, there is an UPDATE_MAIN parameter. The workflow might be to go from an Add or Edit screen, add a child record in a modal popup window, submit the child issue within the modal popup (this executes Business Rules that update the parent issue), then close the modal popup and finally redisplay the updated parent issue, you will include the UPDATE_MAIN parameter as follows:

 
doEditAEActions(window.parent.extraview_app_home_url , '__SESSION_ID__',
new Array('UPDATE_MAIN','POPUP_MODAL_ADD', 'add_confirm_page=NO
&p_rg_relate_this_to=' + getValueFromParent('p_id') + rgParameters(),
'REFRESH_ID', getValueFromParent('p_id')));

Note that you do not require the RELATIONSHIP_GROUP_REFRESH and accompanying LAYOUT_TYPE_ID parameters, as the REFRESH_ID takes care of refreshing the entire parent issue. If this is executed from an Add screen, the parent issue is displayed within an Edit screen, as the underlying Business Rules submitted the parent issue to the database, thus meaning it is no longer in the add state, but it is now in a state where it can be updated. The p_rg_relate_this_to parameter and its value are used on the Add screen to identify the parent issue to which you want to relate the child issue you are adding, when you are including the UPDATE_MAIN parameter. It has no effect otherwise on Add screens, or Edit screens and may be omitted in these cases.

Setting Additional Parameters to Push Values from the Parent to the New Issue

Other parameters may be added to the array value immediately following the POPUP_MODAL_ADD entry. An example is to set the Business Area and Project of the issue to be added. To accomplish this, you will need to know the AREA_ID and PROJECT_ID where the issue is to be added. These can be found on the administration screens for these items. With rgParameters(), an example becomes:

 
doEditAEActions(window.parent.extraview_app_home_url, '__SESSION_ID__',
new Array('POPUP_MODAL_ADD', 'p_area=1&p_project=5&add_confirm_page=NO
&p_rg_relate_this_to=' + getValueFromParent('p_id') + rgParameters(),
'RELATIONSHIP_GROUP_REFRESH', '__LAYOUT_TYPE_ID__' ));

Note that the values for the p_area and the p_project parameters must correspond to the AREA_ID and PROJECT_ID into which you will add the related issue. These values can be seen on the list maintenance screens for the Business Area and the Project. Another possibility is that you might want to pass the values of one or more fields from the parent issue to the child issue you are creating. To achieve this, you may use either the pushDownFields('p_fld1;p_fld2;p_fld3;...') function to pass several fields at once or use the getValueFromParent() function to pass individual fields. For example, let's say that you want to pass the FIRST_NAME and LAST_NAME fields from the parent to the child. The string then becomes either:

doEditAEActions(window.parent.extraview_app_home_url , '__SESSION_ID__',
new Array('POPUP_MODAL_ADD', 'p_area=1&p_project=5
&p_rg_relate_this_to=' + getValueFromParent('p_id') +
pushDownFields('p_first_name;p_last_name') + '&add_confirm_page=NO' +
rgParameters(), 'RELATIONSHIP_GROUP_REFRESH', '__LAYOUT_TYPE_ID__' ));

or using individual parameters:

doEditAEActions(window.parent.extraview_app_home_url , '__SESSION_ID__', 
new Array('POPUP_MODAL_ADD', 'p_area=1&p_project=5
&p_rg_relate_this_to=' + getValueFromParent('p_id') + 
'&p_first_name=' + getValueFromParent('p_first_name') + 
'&p_last_name=' + getValueFromParent('p_last_name') + 
'&add_confirm_page=NO' + rgParameters(), 
'RELATIONSHIP_GROUP_REFRESH', '__LAYOUT_TYPE_ID__' ));

Note that if a field name that you pass within the pushDownFields() or the getValueFromParent() function does not exist, it will be ignored when the user presses the button to add the issue, and no error will be generated. This can be used to advantage in configurations where you want to use a single button for multiple purposes on different forms.

Opening the Modal Popup Window in Edit Mode

There is a feature within ExtraView that allows the user to open up a new issue in Edit mode, as opposed to the Add mode.  This configuration assigns an ID and / or an ALT_ID and saves the initial issue within the database before then placing the user within Edit mode on the screen.  This can be configured within the modal popup window, by altering the POPUP_MODAL_ADD parameter to POPUP_MODAL_OPEN_IN_EDIT.

Repeating Rows Fields

The function getValueFromParent may be modified to access repeating row field values. Repeating rows are indexed, beginning with zero, therefore to access the first repeating row, the call will look like:

 
getValueFromParent('p_fieldname', 0)

To access the third repeating row, the call will look like:

getValueFromParent('p_fieldname', 2)

Although you may target any repeating row to obtain a value from a field, the value will always be placed in the field on the first row of the child record. The following technique will allow you to get values from successive repeating row fields, and populate these into successive repeating rows within child records:

getValueFromParent('p_fieldname', 2); getValueFromParent('p_fieldname', 3)

This example gets the field value from the third repeating row and places the result in the first repeating row child record, and then gets the value in the fourth repeating row field and places its value in the second repeating row child record

RID PREHEADER This attribute adds a title to a related issue display header to contain an Add or other buttons. No title is added to the related issue display if this attribute is not defined. There is one special property of this field. If you use the value of TITLE in the value then the description of the related issue display layout will be used as the title in the pre-header. The reason why you might want to do this is solely if you need to provide a localized equivalent for the title in languages other than the base language of your system. The related issue display title may be localized, while layout cell attributes (with the exception of the ALTERNATIVE TITLE) may not be localized.

RID PREHEADER ADD BUTTON This attribute adds a button to the pre-header. This button is used to add new issues to a relationship. The button is a field that must already be created in the data dictionary. The button must be created on the Label tab within the data dictionary and must have a display type of Button. The title to the field will be used as the title to the button when it appears on the pre-header of the related issue display. You may add any number of Add buttons to a single Related Issue Display
RID PREHEADER REFRESH BUTTON This attribute is used when you are using a search layout on an add or edit layout to return one or more issues to relate them to the current issue. This places a button onto the related issue display pre-header bar that allows the user to refresh the list of results from the current set of search filters. The button has a default title of Get Filtered Results, but you can optionally provide a value to the attribute which will then appear as the label on the button
RID PREHEADER SUBMIT BUTTON This attribute is used when you are using a search layout on an add or edit layout to return one or more issues to relate them to the current issue. This places a button onto the related issue display pre-header bar that allows the user to submit the list of results from the current set of search filters. The button has a default title of Fetch Selected Record(s), but you can optionally provide a value to the attribute which will then appear as the label on the button
RID RELATIONSHIP NAME This is the name of the relationship group to which the related issues will be added. The relationship group must be created before you add the name to the cell attribute. If you do not set a value for this attribute, then the value in the behavior setting named RELATION_GROUP_DEFAULT will be used
RID RELATION TYPE This should be set to one of the following values:
  • MEMBERS - This is the default value for this attribute if you do not override it with one of the other values. In this case the related issue displaywill show all the members of the group(s), containing the reference issue, i.e. the reference issues parents, children, and other issues not directly related to the reference issues in the group(s).
  • CHILDREN - The related issue display will only contain issues that are the children of the reference issue
  • PARENTS - The related issue display will only contain issues that are the parents of the reference issue. Note that in the ExtraView data model it is possible to define more than one parent issue for a specific issue. See the section on Relationship Groups for more information.
  • RELATED - In this instance ExtraView will display the parents and the children of the reference issue within the specified group(s), within the related issue display. The parents and children of these related issues will not be displayed.
  • SIBLINGS - ExtraView will display all the issues at the same level in the hierarchy. For example, if a parent record has five children, and you create a related issue display with all the children, using a relationship group relation type of SIBLINGS, then you will see the four siblings to the current one.
  • GRANDPARENTS - This allows the display of the grand-parents to the current level in the hierarchy
  • GREATGRANDPARENTS - This allows the display of the parents of the grand-parents in the hierarchy
  • GREATGREATGRANDPARENTS - This allows the display of the parents of the great-grand-parents in the hierarchy
  • GRANDCHILDREN - This allows the display of the grand-children to the current level in the hierarchy
  • GREATGRANDCHILDREN - This allows the display of the children of the grand-children in the hierarchy
  • GREATGREATGRANDCHILDREN - This allows the display of the children of the great-grand-children in the hierarchy
  • LINKED - This type does not use a relationship type per se, but relies on the Related Issue Display filters to retrieve the associated issues. For example, you might have a filter that selects all the open issues for a particular product, and display these on a related issue display of each issue that you call up.

If you are using the related issue display to add new issues, the value should be CHILDREN or PARENTS. If you choose another relationship type then the issue will be added, but will not be displayed as the relationship is indeterminate

RID SEARCH FILTER LAYOUT This attribute is used when you are using a search layout on an add or edit layout to return one or more issues to relate them to the current issue. This field holds the name of the search layout that is being embedded on the same layout as the related issue display. Typically you will embed this search layout just above the related issue display layout
RID SINGLE SELECT This attribute is used when you are using a search layout on an add or edit layout to return one or more issues to relate them to the current issue. The default is that the search will allow you to return all the issues the user selects from the results. If you set this attribute, then the user will only allow a single issue to be selected to return the results into the related issue display
RID SORT ORDER This attribute determines a sort order, based on a field that is displayed on the related issue display. You can set the value to ASCENDING or DESCENDING
RID TRANSPOSE LAYOUT The default is that the related issues will be presented on the display by row. If you select this attribute, then the issues will be presented by column
SIZE This controls the width of the related issue display on add and edit screens. The size is an estimate of the number of characters to be displayed. If you do not provide a layout cell attribute for SIZE, then the default is 125 characters.

Beginning with version 10, you can no longer use a SIZE layout cell attribute on the individual fields within the related issue display to control their width. This allows the enabling of a new feature, to freeze the titles of the related issue display.  This is very beneficial when you have a significant number of related issues within the display, as the titles always remain visible.

VISIBLE IF This allows you to make the entire related issue display visible or not visible depending on the value of another field on the layout within which the related issue display is embedded

Order of Precedence on Related Issue Display Operations

Given that the end user may carry out a combination of operations on several, and sometimes independent, related issue displays with an add or edit screen, there might be some conflict in these operations, with records that might appear in more than a single related issue display. For example, what happens if you update an issue in one relationship, but remove the same issue in another relationship? The RELATIONSHIP_GROUP_REMOVE_BTN is given precedence over other transactions. Transactions are processed in the following order: removes, inserts, deletes (where the deletes are relationship group remove button transactions).