Cross-filter
This section provides information about filtering by referenced fields that are filtered by other reference fields.
Overview
You can cross-filter to filter values of a different entity's fields. That is, you can filter by a referenced field that is filtered by another reference field.
You can filter defects by any defect attributes (reference fields), such as listing defects that are detected in a specific release:
GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?query="detected_in_release EQ {id EQ 1004}"
The following cross-filter will correctly list defects whose Severity matches ID number 1003.
GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?query="Severity EQ {id EQ 1003}"
The following cross-filter does not work. It attempts to list defects whose Severity matches name High, but you can reference only the ID field when cross-filtering list value fields.
GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?query="Severity EQ 'High'"
Note: Defects, user stories, epics, and features are subtypes of work items (work_item). Work item IDs are unique across all workspaces in a space. You do not need to explicitly state which work item subtype you are looking for when querying or query with a cross-filter.
Nested cross-filtering
There is no limit to the number of cross-filters you can nest in a query.
Example: You can create a cross-filter to filter defects by any of its field, such as listing defects that are in a specific sprint of a specific release:
GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?query="detected_in_release EQ {sprints EQ {id EQ 1006}}"
Cross-filter on lists
You can use the REST API to filter on lists, phases, and metaphases. For example, you may want to display all defects with a High or Very High severity.
There are two methods for filtering for lists: Query by logical name and Query by label name.
Query by logical name
To use this method, you must first look up the logical name for the value you want to query by. You can do this using the Settings UI or by getting list_node values.
To see all lists and their values:
GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes?query="logical_name EQ ^*high^}"
To see all defects whose severity matches high:
GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/work_items?query="subtype EQ ^defect^; severity EQ {logical_name EQ ^list_node.severity.high^}"
Query by label name
To see all lists that have a value that exactly matches the value high:
GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes?query="name EQ ^high^"
To see all defects whose severity is high:
GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/work_items?query="subtype EQ ^defect^;severity EQ {name EQ ^high^}"
To see all lists that have a value that contains the value high, using wildcards:
GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes?query="name EQ ^*high^"
To see all defects whose severity contains the value high, using wildcards. This will return defects whose severity is high, very high, or, for example, extremely high.
GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/work_items?query="subtype EQ ^defect^; severity EQ {name EQ ^*high^}"
Tip: Querying by label name is only supported in English. However, you can specify your query in English, and the results are displayed in your language.
Cross-filter on user fields
When creating cross-filters on user-type entity fields, you can only reference the ID field.
The following table shows some examples of user-type fields by entity.
Entity | User-type fields in the entity |
---|---|
Defects |
author detected_by owner qa_owner |
Tests |
designer author owner |
Runs |
run_by author |
The following cross-filter will correctly list defects whose QA owner field matches ID number 1003.
GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?query="qa_owner EQ {id EQ 1003}"
The following cross-filter does not work. It attempts to list defects whose QA owner field matches the name Ann. However, you can only reference the ID field when using cross-filtering user-type fields.
GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?query="qa_owner EQ {name EQ 'Ann*'}"
See also: