Heapselect

Heapselect is commonly used for list and form layout configuration.

Another case of using the heapselect tool is editing synthetically related lists on a record form. The heapselect allows changing the selection of records displayed in the list.

The best practice:

Configure the heapselect URL.
Create a URL Action using the heapselect URL or simply share the URL with other users.

When the user follows the link, the records displayed are always checked by the ACLs.

Using the heapselect

After heapselect URL configured, use the heapselect options following the steps below:

Use the URL to enter the form and select the desired records. The left box (Available) contains all the table fields excluding selected ones. The records of the right box (Selected) are selected for further script applying. Move elements by drag-and-dropping or using the and buttons.
- To remove or add all the fields, click the or buttons.
- To move several elements in a row, select them with the Shift key pressed and drag-and-drop from the Available box to the Selected one.
- To move several scattered elements at once, select them with the Ctrl key pressed and drag-and-drop from the Available box to the Selected one.
Click Save to apply the heapselect script to the records of the Selected box.

Heapselect URL configuration

How the heap-select works

The heapselect URL performs the following actions to the essence table:

The server returns lists of records by their sys_id in two boxes using GET-parameters:
1. In the left box – records filtered by the condition are available for manual selection by user.
2. In the right box – the custom script include (select_ids_script_id) returns specific table records by their sys_id.
(Optional) The title and the column value (display_value) displayed may be configured.
When clicking Save, the script_id script include applies to all the record selected.

To configure the heapselect URL, use the GET-parameters and the view below:

<your_instance_URL>/<page_name>/<table_name>?condition=<conditional_expression>
&selected_ids_script_id=<script_returning_sys_ids>
&script_id=<script_applied>
&display_value=<column_name>
&title=<some_text>
&field_name=<field_value>
&form_view=<form_view_name>

GET-parameters description

GET parameter	Description
essence	A system name of the source table.
condition	Build string conditions for table records filtering using the system condition operators and encoded URL characters. You can also simply apply the desired filter or the Condition Builder settings to the table in a list form, then copy the condition body from the browser URL and use it as the heapselect condition. Learn more about how the filter works.
select_ids_script_id	A custom Script Include that returns the list of the essence table records IDs (sys_ids) as operation results. When applying this script, the heapselect adds table records with the returned sys_ids in the right box (the Selected box) of the form.
script_id	This Script Include is applied to the essence table records contained in the right box (the Selected box) of the form.
display_value	Define the name of a column to be displayed as record names in the heapselect form.
title	Use this option to set the string title of the heapselect form. By default, the Select Items title displayed.
parent_id	Specify the ID of the record to be affected by the action applied.
parent_table	Specify the ID of the table to be affected by the action applied.
field_name	Set value to a specific field.
form_view	Use this option to set the view of the form or a list. All users will switch to the defined view regardless of their preferred view.

User case

Case:

Add a related Configuration Item list to an Employee table record, where the selection condition is Location is {current user Location}.

To configure the Related Lists with heapselect, perform the following steps:

Create a related list using the Scripted Related Lists tool. In our case, it is CI my Location.
Scripted Related List example
```
if(Boolean(parent.sys_id)){
  current.addQuery('location', parent.location.sys_id);
}
```

Create a script include. In our case, it is heapSelectExecute.

heapSelectExecute example

setResult(heapSelectExecute(essence, selectedIds));

function heapSelectExecute(essence, selectedIds) {
let selectedElements = []; 
let record = new SimpleRecord(essence);
  record.addQuery('sys_id', 'IN', selectedIds);
  record.query();
  record.setMultipleValue('location', parent.location.sys_id);
  record.updateMultiple();
}

Add a UI-action to the created related list with the following settings:

Field	Value
Table	The table displayed in this related list.
Conditions and Actions
Show Insert	'true'
Show Update	'true'
URL	Heapselect URL with all the necessary parameters. See the Heapselect URL configuration section of this article to learn more. /heap-select/sys_cmdb_ci?condition=(ci_status!=1)&select_ids_script_id=158764810812561263&script_id=158764868812483099&display_value=number&title=Edit CI Location
Position and Style
Use For	Related Lists
Scripted List	'true'
List Banner Button	'true'

As a result, there is an editable related list on the Employee record form. A user can add or remove records from the list of configuration items which have the same location as the employee.

Page tree

Using the heapselect

Heapselect URL configuration

GET-parameters description

User case

1 Comment

Anonymous