Inera Core Implementation Guide
0.2.0 - ci-build Sweden

Inera Core Implementation Guide - Local Development build (v0.2.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Search Parameters

Search Parameters

This page describes how TKB service contract request parameters are implemented as FHIR search parameters, and lists the search parameters defined or used by this Implementation Guide.

Swedish TKB (Tjänstekontrakt Beskrivning) service contracts define input parameters for retrieving clinical information. In FHIR, these request parameters are implemented using RESTful search parameters.

Design Principles

When migrating from TKB services to FHIR APIs, the following principles apply:

  1. Patient Identification: TKB patientId parameters map to FHIR patient or patient.identifier search parameters
  2. Time Filtering: TKB timePeriod or datePeriod parameters map to date-based search parameters with prefixes (ge, le)
  3. Organization Filtering: TKB careUnitId parameters map to organization or performer search parameters
  4. Code Filtering: TKB code-based filters map to code, category, or resource-specific search parameters
  5. Status Filtering: TKB status parameters map to clinical-status or status search parameters

Common TKB Parameter Patterns

TKB services typically require three fields for patient identification:

  • patientId (or similar): The actual identifier value
  • patientIdRoot: OID identifying the identifier system
  • patientIdExtension: The identifier value (redundant with patientId)

TKB Example (GetActivities):

<patientid>191212121212</patientid>
<patientidroot>1.2.752.129.2.1.3.1</patientidroot>
<patientidextension>191212121212</patientidextension>

FHIR Equivalent:

GET [base]/CarePlan?patient.identifier=https://terminology.hl7.se/sid/se-personnummer|191212121212

Alternative using patient resource reference (if patient resource known):

GET [base]/CarePlan?patient=Patient/191212121212

Supported Identifier Systems:

  • Personnummer: https://terminology.hl7.se/sid/se-personnummer (OID: 1.2.752.129.2.1.3.1)
  • Samordningsnummer: https://terminology.hl7.se/sid/se-samordningsnummer (OID: 1.2.752.129.2.1.3.3)
  • HSA-ID Person: https://terminology.hl7.se/sid/se-hsa-personalid (OID: 1.2.752.129.2.1.4.1)
  • HSA-ID Organization: https://terminology.hl7.se/sid/se-hsa-vardenhetsid (OID: 1.2.752.129.2.1.4.3)

For complete identifier system reference, see Conformance.

Time Period Filtering

TKB services often use date/time period parameters to limit results:

TKB Example (GetCareContacts):

<dateperiod>
  <start>2024-01-01</start>
  <end>2024-12-31</end>
</dateperiod>

FHIR Equivalent - Using date range prefixes:

GET [base]/Encounter?date=ge2024-01-01&date=le2024-12-31

Common Date Search Parameters by Resource:

  • Encounter: date (period of encounter)
  • MedicationStatement: effective (when medication was/is taken)
  • Condition: onset-date (when condition began)
  • Observation: date (observation effective time)
  • Procedure: date (procedure performed date)
  • CarePlan: date (time period of care plan)

Date Prefix Operators:

  • ge - Greater than or equal (start of period)
  • le - Less than or equal (end of period)
  • gt - Greater than
  • lt - Less than
  • eq - Equal (default if no prefix)

Care Unit Filtering

TKB services may filter by care unit using HSA-ID:

TKB Example (GetActivities):

<careunitid>
  <root>1.2.752.129.2.1.4.1</root>
  <extension>SE2321000131-E000000000123</extension>
</careunitid>

FHIR Equivalent:

GET [base]/CarePlan?performer.identifier=https://terminology.hl7.se/sid/se-hsa-vardenhetsid|SE2321000131-E000000000123

Or using organization reference:

GET [base]/CarePlan?performer=Organization/SE2321000131-E000000000123

Implementation Examples

Example 1: GetActivities (Care Plans and Activities)

TKB Request Parameters:

  • patientId: Patient identifier
  • careUnitId: Optional care unit filter
  • activityStatus: Optional status filter

FHIR Search Implementation:

GET [base]/CarePlan?patient.identifier=http://electronichealth.se/identifier/personnummer|191212121212
                   &performer.identifier=https://terminology.hl7.se/sid/se-hsa-vardenhetsid|SE2321000131-E000000000123
                   &status=active
                   &_include=CarePlan:performer
                   &_revinclude=Provenance:target

Search Parameters Used: | Parameter | Type | Description | |———–|——|————-| | patient.identifier | token | Patient identifier (chained search) | | performer.identifier | token | Care unit HSA-ID (chained search) | | status | token | CarePlan status (active, completed, etc.) | | _include | special | Include referenced performer organizations | | _revinclude | special | Include provenance for audit trail |

Example 2: GetMedicationHistory

TKB Request Parameters:

  • patientId: Patient identifier
  • timePeriod.start: Start of time period
  • timePeriod.end: End of time period
  • medicationId: Optional NPL medication code

FHIR Search Implementation:

GET [base]/MedicationStatement?patient.identifier=http://electronichealth.se/identifier/personnummer|191212121212
                               &effective=ge2024-01-01
                               &effective=le2024-12-31
                               &code=http://hl7.org/fhir/sid/npl|123456
                               &_include=MedicationStatement:medication

Search Parameters Used: | Parameter | Type | Description | |———–|——|————-| | patient.identifier | token | Patient identifier | | effective | date | When medication was/is taken (supports prefixes) | | code | token | NPL or ATC code for medication | | _include | special | Include referenced Medication resources |

Example 3: GetCareContacts (Encounters)

TKB Request Parameters:

  • patientId: Patient identifier
  • datePeriod.start: Start date
  • datePeriod.end: End date

FHIR Search Implementation:

GET [base]/Encounter?patient.identifier=http://electronichealth.se/identifier/personnummer|191212121212
                    &date=ge2024-01-01
                    &date=le2024-12-31
                    &_include=Encounter:location
                    &_include=Encounter:participant

Search Parameters Used: | Parameter | Type | Description | |———–|——|————-| | patient.identifier | token | Patient identifier | | date | date | Encounter period (start/end) | | _include | special | Include locations and participants |

Example 4: GetDiagnosis (Conditions)

TKB Request Parameters:

  • patientId: Patient identifier
  • timePeriod: Optional time filter
  • diagnosisCode: Optional ICD-10 code

FHIR Search Implementation:

GET [base]/Condition?patient.identifier=http://electronichealth.se/identifier/personnummer|191212121212
                    &onset-date=ge2024-01-01
                    &code=http://hl7.org/fhir/sid/icd-10|E11
                    &clinical-status=active

Search Parameters Used: | Parameter | Type | Description | |———–|——|————-| | patient.identifier | token | Patient identifier | | onset-date | date | When condition began | | code | token | ICD-10-SE diagnosis code | | clinical-status | token | active, inactive, resolved |

Example 5: GetAlertInformation (Allergies and Warnings)

TKB Request Parameters:

  • patientId: Patient identifier
  • alertLevel: Optional severity filter

FHIR Search Implementation:

GET [base]/AllergyIntolerance?patient.identifier=http://electronichealth.se/identifier/personnummer|191212121212
                              &clinical-status=active
                              &criticality=high

Search Parameters Used: | Parameter | Type | Description | |———–|——|————-| | patient.identifier | token | Patient identifier | | clinical-status | token | active, inactive, resolved | | criticality | token | low, high, unable-to-assess |

Advanced Search Patterns

Composite Searches

Combine multiple search parameters to replicate complex TKB filters:

GET [base]/Observation?patient.identifier=http://electronichealth.se/identifier/personnummer|191212121212
                      &category=vital-signs
                      &code=http://loinc.org|85354-9
                      &date=ge2024-01-01
                      &date=le2024-12-31
                      &_sort=-date

Chained Searches

Use chained searches to filter by referenced resource properties:

GET [base]/CarePlan?patient.identifier=http://electronichealth.se/identifier/personnummer|191212121212
                   &performer.type=http://terminology.hl7.org/CodeSystem/organization-type|prov

Result Includes

Use _include and _revinclude to fetch related resources in a single request:

GET [base]/MedicationStatement?patient=Patient/191212121212
                               &_include=MedicationStatement:medication
                               &_revinclude=Provenance:target
                               &_revinclude=DocumentReference:related

Pagination

Handle large result sets with pagination parameters:

GET [base]/Observation?patient=Patient/191212121212&_count=50&_offset=0

Performance Considerations

Indexed Parameters

EHR systems SHOULD index the following commonly used search parameters for performance:

  • patient and patient.identifier (all clinical resources)
  • date, effective, onset-date (temporal searches)
  • code, category (code-based filtering)
  • status, clinical-status (status filtering)
  • identifier (Organization, Practitioner)

Search Optimization

When implementing TKB-equivalent searches:

  1. Use resource references over chained searches when patient resource is known
    • Prefer: patient=Patient/123
    • Over: patient.identifier=system|value
  2. Limit includes to necessary resources only
    • Avoid excessive _include and _revinclude operations
  3. Use _summary or _elements for large result sets
    • _summary=true returns abbreviated resources
    • _elements=status,code,subject returns only specified fields
  4. Implement proper pagination
    • Use _count to limit result size
    • Support continuation tokens for large datasets

Search Parameter Definitions

The following search parameters are defined or used by this Implementation Guide:

See Also