TaskList Component

TaskList displays Spark Tasks on a page. Its base data scope comes from a Filter saved in Task Designer, and it reuses task permissions, task fields, task details, and runtime query capabilities.

After reading this guide, you will be able to:

• Use a Task Filter to define the base task scope of a TaskList
• Use a Task Form to render advanced query conditions
• Add system and custom fields as table columns
• Adjust column order, title, width, sorting, fixed position, and ellipsis
• Configure Task Key or another column as a task link
• Control the filter bar, column settings, and page size
• Verify query behavior for Assignee, Select, Date, and DateTime fields

1. When to use TaskList

TaskList is suitable when you need to:

• Display one task type or a set of tasks on a business page
• Use TQL to fix a task type, status, step, or other base condition
• Let users narrow results by title, assignee, time, and custom fields
• Open task details by clicking a task key or business field in the list
• Display task system fields and business custom fields in the same table

TaskList, DataList, and ProTable have different data boundaries:

Component	Primary data	Query definition	Typical use
TaskList	Spark Tasks	Task Filter + runtime conditions	Task lists, approval lists, and business work queues
DataList	Business Object	DQL + model filters	Object data such as orders, customers, and devices
ProTable	Custom URL or model data source	HTTP request parameters or model query	Third-party APIs, aggregated data, and custom pagination protocols

If the page does not display tasks, use DataList or ProTable instead.

2. Prerequisites and sample source

TaskList displays process tasks from Spark Tasks. Before configuring it, we recommend that you:

1. Read the Process Designer overview to understand the relationships among Task Type, fields, forms, steps, workflows, and permission schemes.
2. Complete Quick Start: Procurement Approval Workflow and confirm that you can create and process a Purchase Request in DEV.

This guide directly reuses the procurement approval workflow configured in that quick start and does not recreate its process assets. The quick start provides the following foundation:

Asset	Sample configuration
Task Type	PURCHASE / Purchase Request
Workflow	Purchase Approval
Custom fields	Procurement fields including Finance Review Result, Department Review Result, and Required Date
Runtime data	Purchase Requests created in DEV and verified through different approval branches

On top of those process assets, this guide configures the list assets and page properties required by TaskList:

Asset or property	Configuration in this guide
Task Filter	All Purchase Request Tasks
Filter TQL	taskType = "PURCHASE" ORDER BY createdAt DESC
Query Form	purchaseQueryForm
Query Form fields	Assignee, Finance Review Result, Department Review Result, Required Date
Columns	Task Key, Title, Task Type, Current Step, Created At
Page Size	20
Show Filter Bar	On
Show Column Settings	On

3. Prepare the required assets

3.1 Prepare task assets

Confirm that the following assets are saved in the current application and design version:

1. The Task Type has a workflow, permission scheme, and required forms.
2. Custom fields that need to be displayed or queried have been added to the Task Type.
3. At least one Task Filter is available for TaskList to reference.
4. If advanced search is required, a dedicated Task Form has been created.

TaskList candidates are loaded for the current App + Version. In DEV, you can use task assets saved in the current development version. When validating in TEST or PROD, confirm that the corresponding version has been published to the target environment.

3.2 Create a Task Filter

Go to Task Designer → Data & Permission → Filters, create a Filter, and save its TQL. This guide uses:

taskType = "PURCHASE" ORDER BY createdAt DESC

After entering taskType =, select Purchase Request from the candidate list for the current version. TQL uses the stable Task Type Key PURCHASE; do not replace the key with its display name.

The Task Filter defines the base task scope of TaskList. Runtime users cannot remove this TQL, and a Filter never broadens task permissions. For syntax and permission boundaries, see Filters and TQL.

3.3 Create a Query Form

A Query Form is optional and is not required to display the query area. When Show Filter Bar is enabled, TaskList provides default query conditions even when no Query Form is selected:

• First-row quick conditions: Title, Status, Task Type, and Created At.
• Advanced conditions after clicking More: Current Step, SLA Status, Assignee, and Updated At.

Search remains the primary button on the right side of the query area. More and Reset are icon buttons immediately after it, followed by column settings at the end of the action group. After you configure a Query Form, TaskList keeps the default conditions and appends the Query Form's custom fields in the More area; the Query Form does not replace the default conditions. When Show Filter Bar is disabled, neither the default conditions nor the Query Form is displayed.

To add custom business query fields, create a dedicated Task Form that contains only the fields users actually need for searching. Do not directly copy a business form that contains many read-only detail or attachment fields.

This guide uses purchaseQueryForm:

Field	Field type	Runtime query control
Assignee	User	User selector
Finance Review Result	Select	Approved / Rejected select
Department Review Result	Select	Approved / Rejected select
Required Date	Date	Date range picker

A Query Form does not need to be bound to a specific Task Type for querying. Field definitions still come from the current application and version, so make sure that fields referenced by the form have not been deleted.

4. Add and configure TaskList

1. Open the target page in Page Designer.
2. Expand the Task group in the component palette.
3. Drag TaskList into a container that accepts it.
4. Select TaskList and complete its basic configuration in the property panel.

The main TaskList properties are:

Property	Required	Description
Task Filter	Yes	Selects a Filter saved in Task Designer; runtime loads its TQL by Filter Key
Query Form	No	Appends Task Form fields to the More area in addition to the default query conditions
Columns	No	Configures system and custom fields in order; default task-list columns are used when left empty
Show Filter Bar	No	Controls whether the entire query area is displayed
Show Column Settings	No	Controls the column settings entry at the upper right; it appears only when the filter bar is displayed
Page Size	No	Default number of rows per page; the default is 20 and the allowed range is 1 to 200

This guide uses:

Task Filter: All Purchase Request Tasks
Query Form: purchaseQueryForm
Show Filter Bar: On
Show Column Settings: On
Page Size: 20

When Show Filter Bar is disabled, the quick conditions, More, Search, Reset, and column settings entry are all hidden. Only the task table and pagination remain. This is suitable for pages with a fixed query scope where users should not adjust conditions.

5. Configure Columns

5.1 Add and reorder columns

Expand Columns under TaskList and click Add. Each addition creates an individual Task Column in the left tree instead of storing all columns in a multi-select control.

For each column:

1. Select a system or custom field in Task Field.
2. Review the automatically populated Column Title and change it to match the page context when needed.
3. Open Advanced and configure width, task link, sorting, fixed position, and ellipsis as needed.
4. Drag the Task Column in the left tree to change its runtime order.

The table header on the design canvas should update with Task Field, Column Title, and column order. Column Title already provides the displayed column name, so there is no need to maintain an additional Display Name.

5.2 Available fields

Task Field candidates are divided into two groups:

• System Fields: Task Key, Title, Task Type, Status, Current Step, Assignee, Creator, Created At, Updated At, SLA, and others.
• Custom Fields: Task fields defined in the current application and version, such as Amount, Category, Required Date, and Department Review Result.

A page author can explicitly add a custom field to TaskList even when it is not a default visible column in the standalone Worklist.

5.3 Advanced column properties

Property	Description
Width	Column width in pixels
Task Link	Opens the task when the column value is clicked
Enable Sorting	Allows users to sort by the column; applies only to fields supported by backend sorting
Fixed Column	Fixes the column to the left or right side of the table
Show Ellipsis	Shows an ellipsis when content exceeds the column width

When displayed, the SLA status column is always the first column. We recommend placing Task Key and Title immediately after it and enabling Task Link for both. Other business fields can also be task links. If Task Link is explicitly disabled for a column, that column is displayed as ordinary text.

Runtime column settings can temporarily hide configured columns or change their order. They do not modify the column structure or order in Page Designer.

6. Runtime query area

6.1 Quick query conditions

When Show Filter Bar is enabled, TaskList displays these quick conditions at the top by default:

• Title
• Status
• Task Type
• Created At

These controls describe their purpose with placeholders and do not repeat visible labels. Search, More, Reset, and column settings appear in that order on the right. More and Reset use icon buttons with tooltips. Query controls and the action group are vertically centered on the same horizontal line.

Clicking More displays:

• Current Step
• SLA Status
• Assignee
• Updated At
• Fields configured in the Query Form

Built-in advanced conditions also use placeholders without repeated labels. Query Form fields keep their own form labels and layout so that custom business conditions remain identifiable.

6.2 Search and Reset

• Search: Reads the current quick conditions and Query Form values, then queries again from the first page.
• More icon: Expands or collapses advanced conditions and the Query Form.
• Reset icon: Clears runtime conditions and Query Form values, then queries again.
• Enter: Pressing Enter in the Title input runs the query directly.

Empty values are not included in the query. The Task Filter, quick conditions, and Query Form conditions are combined with AND. Tenant, application, environment, and task browsing permissions are always enforced by the backend.

For example, the base Filter in this guide already limits tasks to taskType = "PURCHASE". After selecting an Assignee and Required Date, results must satisfy all of the following:

Purchase Request base scope
AND current Assignee
AND Required Date range
AND the current user's task browsing permissions

7. Query rules for Query Form fields

The query control is determined by the field's actual type, not inferred from its field name.

Field type	Query behavior
Text, Textarea, Rich Text, Markdown	Contains match
Select, Radio, Switch	Equality match
Multi-select fields	Collection match using IN
Number	Equality match
User, Assignee	The user selector submits a user ID while continuing to display the user name
Department	Department tree selector
Date, DateTime	Range query with both start and end boundaries included
Attachment	Not rendered in query mode

Hidden fields are excluded from the Query Form. A field's Required setting on a business form is not enforced in query mode; conditions without a value are ignored.

7.1 Assignee

Assignee searches the user directory available to the current application. After a user is selected, the query request uses the stable user ID, while the control continues to display the user's name or account. It must not change to a numeric ID after Search is clicked.

7.2 Select

A Select must render the Options configured for the field. In this guide, Department Review Result and Finance Review Result both display:

Approved
Rejected

The word Department in a field name does not turn a Select into a department selector. Only a field whose actual type is Department displays the department tree.

7.3 Date and DateTime

Date and DateTime fields in a Query Form use range pickers:

• Start value only: query field >= start
• End value only: query field <= end
• Both values: query field >= start AND field <= end

Both boundaries are inclusive. Date fields query by date value; DateTime fields allow a specific time to be selected.

8. Open tasks and page interactions

When Task Link is enabled for a column, clicking its value opens the task.

• No onTaskClick configured: opens the standard Spark task detail page in a new browser tab and keeps the current business page open.
• onTaskClick configured: runs the Page Designer interaction on the current page and provides task and record contexts; the standard task detail page is not opened automatically.
• Browser modifier click, such as Ctrl or Command click: preserves the browser's default link behavior.

To refresh TaskList from another button on the page, call this Component API on the component:

reloadTable

9. Sample validation checklist

Validate the following on the DEV runtime page used in this guide:

1. The list returns only Purchase Requests within the Filter scope.
2. Headers appear in the order Task Key, Title, Task Type, Current Step, and Created At.
3. Task Key and Title are both links, and each opens the corresponding task in a new browser tab.
4. Expanding More displays the four fields from purchaseQueryForm.
5. After selecting an Assignee and clicking Search, the control still displays the user name.
6. Department Review Result displays Approved / Rejected rather than a department tree.
7. A Required Date range that excludes a task's date removes that task from the results.
8. Reset restores the base results defined by the Task Filter.
9. Column settings can temporarily hide columns and toggle sortable fields.
10. The pagination area with its separator follows the last table row directly, without a large empty gap.

Next steps

• Filters and TQL
• Task Forms
• Task Permissions