Cross-filter

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/2002/workspaces/1003/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/2002/workspaces/1003/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/2002/workspaces/1003/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 shared 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/2002/workspaces/1003/defects?query="detected_in_release EQ {sprints EQ {id EQ 1006}}"

Cross-filter on user fields

When creating cross-filters on user-type entity fields, you can reference only 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

Note: tests are a technical preview. Until made public, send an HPECLIENTTYPE header with the value: HPE_REST_API_TECH_PREVIEW in your requests.

designer

author

owner

Runs

Note: runs are a technical preview. Until made public, send an HPECLIENTTYPE header with the value: HPE_REST_API_TECH_PREVIEW in your requests.

run_by

author

The following cross filter will correctly list defects whose QA owner field matches ID number 1003.

GET .../api/shared_spaces/2002/workspaces/1003/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 name Ann, but you can reference only the ID field when cross-filtering user-type fields.

GET .../api/shared_spaces/2002/workspaces/1003/defects?query="qa_owner EQ {name EQ 'Ann*'}"


See also: