---
id: JNY-PFM-QRY-005
title: Configure a search field and look up records
feature: FEAT-PFM-QRY-06
product_area: platform
module: queries
revision: 1
status: draft
product_intent: proposed
implementation_evidence: partially-observed
supersedes: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
actor: ACT-PFM-007
goal: Publish a search-field configuration and use it to find supported records.
capabilities:
  - CAP-PFM-QRY-017
  - CAP-PFM-QRY-016
screens:
  - '/console/{tenantId}'
steps:
  - 'n': 1
    surface: listQuickSearchFields
    action: Request the available contact search fields.
    capability: CAP-PFM-QRY-017
    expected: 'The evidenced response describes a standard field’s label, type and origin.'
    provenance: test
    source: >-
      services-platform:modules/quick-search/tests/e2e/quick-search-configurations.e2e.spec.js#offers a
      standard field with its label, data type and origin
  - 'n': 2
    surface: replaceQuickSearchConfiguration
    action: Add an eligible custom field to the second search tier and replace the configuration.
    capability: CAP-PFM-QRY-017
    expected: The response identifies the rebuild job associated with the saved change.
    provenance: test
    source: >-
      services-platform:modules/quick-search/tests/e2e/quick-search-configurations.e2e.spec.js#answers the
      rebuild job the change owes, so a client can watch it
  - 'n': 3
    surface: rebuildQuickSearchIndex
    action: Follow the rebuild until its replacement generation is published.
    capability: CAP-PFM-QRY-017
    expected: >-
      The documented lifecycle marks the new generation ready after rebuilding while retaining the prior
      search generation.
    provenance: documented
    source: 'services-platform:docs/quick-search.md#3.3 Rebuilds'
  - 'n': 4
    surface: '/console/{tenantId}'
    action: 'Type a value from the added field, then enter phone digits in the search box.'
    capability: CAP-PFM-QRY-016
    expected: The proposed interaction finds contacts through the configured terms and normalized phone digits.
    provenance: inferred
    source: >-
      services-platform:modules/quick-search/tests/unit/services/indexing/build-documents.spec.ts#searches a
      phone number as it is stored and by its digits, so a typed run of digits finds it
    note: >-
      The cited evidence supports a service result or a related interaction. This screen sequence requires its
      own browser proof.
  - 'n': 5
    surface: '/console/{tenantId}'
    action: Enable inclusion of inactive records.
    capability: CAP-PFM-QRY-016
    expected: The search filter permits both inactive and archived contacts.
    provenance: observed
    source: 'react-console:lib/quick-search/search.ts:statusFilterFor'
alternates:
  - from_step: 2
    condition: An ineligible long-text field is included.
    path: Reject the replacement and identify the unsupported field.
    outcome: The configuration stays unchanged and no rebuild is admitted.
    provenance: test
    source: >-
      services-platform:modules/quick-search/tests/e2e/quick-search-configurations.e2e.spec.js#refuses a field
      whose data type Quick Search cannot hold as a term
failures:
  - from_step: 4
    condition: The caller lacks permission to read contacts.
    path: Refuse a search credential for that record type.
    outcome: The caller receives no credential with which to query its index.
    provenance: test
    source: >-
      services-platform:modules/quick-search/tests/e2e/quick-search-access.e2e.spec.js#refuses a caller
      holding the lookup but not the record type’s own permission
rules_in_play:
  - BR-CAP-PFM-QRY-017-03
  - BR-CAP-PFM-QRY-017-04
  - BR-CAP-PFM-QRY-016-01
  - BR-CAP-PFM-QRY-016-09
  - BR-CAP-PFM-QRY-016-10
assertions:
  - id: AS-JNY-PFM-QRY-005-01
    statement: The documented rebuild lifecycle makes the changed field list available after publication.
    provenance: documented
    source: 'services-platform:docs/quick-search.md#3.3 Rebuilds'
  - id: AS-JNY-PFM-QRY-005-02
    statement: The default status filter excludes archived contacts; the inactive-record option permits them.
    provenance: observed
    source: 'react-console:lib/quick-search/search.ts:statusFilterFor'
e2e_policy: optional
e2e_reason: >-
  Service and unit evidence covers configuration, credential refusal and term normalization. A browser
  scenario should demonstrate publication of the changed field and a subsequent typed lookup.
evidence:
  - 'Pinned reference: react-console:lib/quick-search/search.ts'
  - 'Pinned reference: services-platform:docs/quick-search.md'
  - 'Pinned reference: services-platform:modules/quick-search/tests/e2e/quick-search-access.e2e.spec.js'
  - 'Pinned reference: services-platform:modules/quick-search/tests/e2e/quick-search-configurations.e2e.spec.js'
  - >-
    Pinned reference:
    services-platform:modules/quick-search/tests/unit/services/indexing/build-documents.spec.ts
proved_by: []
---

# Configure a search field and look up records

## Story

An administrator chooses an eligible contact field and saves the replacement search configuration. The returned job identifies the rebuild to follow. After publication, a staff member uses typed field values or phone digits to look up contacts. The inactive-record option broadens the status filter. The complete configuration-to-search interaction is a proposed journey supported by separate service, indexing and console observations.