Using the Relational Grid Widget

The relational grid enables you to replace Single and Multi-Relational field controls on custom state and transition forms with an embedded listing report that displays the related items and their fields (as opposed to viewing only the Value display format for related items). This enables users to view relevant information without having to navigate away from the form.

The report can be:

Defined in SBM Composer as a report of related items based on specific relational fields.
Defined in SBM Work Center or the SBM User Workspace.

In a state form, users can view the list of related items and view specific fields on those items in a columnar format (depending on the fields that are defined in the report definition).

In a transition form, users can select an item using a radio button control for Single-Relational fields, or they can select multiple items using check boxes for Multi-Relational fields, which updates the underlying relational field when the transition is finished.

For a report that is defined in SBM Composer, you can choose which fields to display, what search filter to apply to limit candidate records, and query at runtime values that enable dynamic filtering of related items at runtime.

Setting up a Relational Grid

Before you begin, determine the application and table that are associated with the relational field that you want to display using the grid. You can find these details on the Options tab of the relational field.

To set up a relational grid:

Create a Report Definition in SBM Composer.
1. In the application you noted earlier, right-click on the associated table, and then select Create new Report Definition for this table.
2. Drag fields from the Report Palette to define the columns that you want to display, the sort order to apply, and create a search filter to limit the items that are returned in the report.
3. Optionally, use a query at runtime parameter in your search filter to dynamically filter the results at runtime.
Alternatively, create a report in SBM Work Center or the SBM User Workspace.
1. In SBM Work Center or the SBM User Workspace, create the report you want to reference.
2. Save the report, and in the Save As section on the page, type a report name in the Title box, and type a reference name in the Reference Name box. The reference name must be unique within an application, but can be the same as the report title.
  Restriction:
  - The Reference Name box is only present if you have "Regular User" product access with the Remote Administration privilege (granted in SBM Application Administrator) or if you have "Managed Administrator" product access with the Deploy privilege (granted in SBM Application Repository).
  - This box is disabled if the Privilege Category is Private.
3. In the confirmation message, click Reference Link. A message opens that contains the report URL.
4. Press CTRL+C to copy the report URL to the Windows Clipboard.
Configure the relational grid widget.
1. Drag and drop a Relational Grid widget on to your form.
2. On the General tab, click Configure.
3. Select the relational field and report definition that you defined earlier, or paste the report URL if you created a report in SBM Work Center or the SBM User Workspace. If the target table is in a different process app and the application has not been referenced, you must add an application reference to make the report available. For details, see Creating Application References.
4. Select Automatically bind compatible parameters to have SBM Composer attempt to map query at runtime parameters for you.
5. Click OK to finish.
Configure the report query to filter results.
1. Open the Query tab.
2. Select a project constraint to limit results to a particular project.
3. Map controls to the widget to enable dynamic filtering. You can add EditBox and Button controls to the form, and then map a query at runtime field in your report to the EditBox. This creates a search field that exposes the query at runtime capability. For example, if your report contains a search filter like:
```
Title contains '(Query at runtime)'
```
  Add an EditBox (named EscalatedIssue in this example), and then map it to the Title field:
4. Open the Refresh tab, select the button control that you added, and then select On click to refresh the widget when the button is clicked.

At runtime, when a user enters text in the search field and clicks the button, the results will be filtered by the text that is entered.

Using Selected Values in the Relational Grid

This section provides a brief example that demonstrates how you can use values in selected items in the grid.

In transition forms, you can map the value or values of selected records to populate other controls. For example, you can add a Text control that displays the currently selected Severity values in the target table.

On the Refresh tab of the Text control, type { in the Display text field, and then select the relational grid and field:

Select On data change to have the text field contents update whenever the search button is clicked.

For Single Relational fields, because the display text of the text control can contain multiple references, you can construct any string from the contents of the related fields.

If the relational grid is associated with a Multi-Relational field, {GridWidgetName.ColumnName} is replaced by a comma-separated list of the values from the referenced field.

Considerations for State Forms

On state forms, the relational grid displays records that are not selected in the relational field unless you filter the results in the grid to only display records that are referenced by the relational field.

You can accomplish this by creating a relational field in the child item that points back to the parent item. You can then create a report that displays only the selected records by using a query such as:

Title contains (Query at runtime)
AND
ParentItem in (Query at runtime)

In the widget's Query tab, add the parent's record ID to restrict the results:

ParentItem: {_RecordId}

This ensures that the relational grid displays only the records contained in the Multi-Relational field when it is used on a state form.

Using the Relational Grid Widget

Setting up a Relational Grid

Using Selected Values in the Relational Grid

Considerations for State Forms

Related Topics