collabreefhirdocumentation - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Medication Catalog

Collabree Medication Catalog Documentation

Profile Definition: MedicationProfile

Overview

Collabree supports medication catalogs from Switzerland and Saudi Arabia. Both countries use Open Medication Catalog FHIR R4 NDJSON releases imported via services/resource_updater. Catalogs are scoped in the app using OMC-native identifiers and status=active filters.

The legacy CollabreeMedication profile (Collabree country-code, data-provider-id, and GTIN extensions) applied only to the old Saudi Excel pipeline, which has been replaced by OMC NDJSON.

Profile Structure

Open Medication Catalog (CH and SA)

Medications imported from Open Medication Catalog are stored as-is and are not required to satisfy every CollabreeMedication profile constraint. Azure does not validate the profile on write.

Typical OMC fields used by the app:

• code.text: Display name
• status: active or inactive (inactive packages are excluded from search)
• form: Dose form coding
• ingredient: Ingredient name (strength often absent)
• amount.numerator: Package quantity when present
• OMC identifiers:
  • CH: https://fhir.openmedicationcatalog.org/sid/ch/swissmedic/authorisation
  • SA: https://fhir.openmedicationcatalog.org/sid/sa/sfda/register-number
• OMC extensions such as .../StructureDefinition/jurisdiction = CH or SA
• identifier with https://www.gs1.org/gtin for barcode lookup when present

Legacy CollabreeMedication Profile (deprecated)

The old Saudi Excel processor wrote Collabree identifiers (country-code|SA, data-provider-id|CHI_GOV_SAUDI_ARABIA, Collabree GTIN extension). These rows are removed.

Country-Specific Use Cases

Swiss Medication Catalog (Open Medication Catalog)

Source: Open Medication Catalog ch-enriched NDJSON release Import: static/medications/ch/Medication.ndjson via services/resource_updater Country Code: CH (via OMC jurisdiction extension) Key Characteristics:

1. Package-Focused: Many rows include package quantities
   • amount.numerator: Number of units (e.g., 30 tablets)
   • amount.denominator: Often {value: 1} only

2. Single display name: code.text (German in current release)

3. Regulatory metadata: Swissmedic authorisation/package identifiers, dose form, active/inactive status

4. GTIN barcode lookup: https://www.gs1.org/gtin identifier when present in the release

5. No medication images in OMC; the app falls back to the default medication icon

Example Use Case:

Open Medication Catalog NDJSON → resource_updater → FHIR Medication
- German display name in code.text
- Swissmedic identifiers for CH-scoped search
- status=active filters inactive packages from the picker

Saudi Arabian Medication Catalog (Open Medication Catalog)

Source: Open Medication Catalog SA NDJSON release Import: static/medications/sa/Medication.ndjson via services/resource_updater Country Code: SA (via OMC jurisdiction extension) Key Characteristics:

1. Package-Focused: Package description in code.text and OMC extensions

2. Regulatory metadata: SFDA register-number identifiers, dose form, active/inactive status

3. GTIN barcode lookup: https://www.gs1.org/gtin identifier when present

4. No medication images in OMC; the app falls back to the default medication icon

Example Use Case:

Open Medication Catalog SA NDJSON → resource_updater → FHIR Medication
- Display name in code.text
- SFDA register-number identifiers for SA-scoped search
- status=active filters inactive packages from the picker

Medication Catalog Retriever Implementation

Data Source Handling

The app uses country-specific OMC search because each catalog exposes a different scope identifier:

Open Medication Catalog (CH)

// Text search: OMC Swissmedic identifier + active status
MedicationSearchParameters(
  code: ':text=$query',
  status: 'active',
  identifier:
      'https://fhir.openmedicationcatalog.org/sid/ch/swissmedic/authorisation|',
);

// Barcode search (when GTIN is present)
MedicationSearchParameters(
  identifier: 'https://www.gs1.org/gtin|$barcode&'
      'https://fhir.openmedicationcatalog.org/sid/ch/swissmedic/authorisation|',
);

Open Medication Catalog (SA)

// Text search: OMC SFDA register-number identifier + active status
MedicationSearchParameters(
  code: ':text=$query',
  status: 'active',
  identifier:
      'https://fhir.openmedicationcatalog.org/sid/sa/sfda/register-number|',
);

// Barcode search (when GTIN is present)
MedicationSearchParameters(
  identifier: 'https://www.gs1.org/gtin|$barcode&'
      'https://fhir.openmedicationcatalog.org/sid/sa/sfda/register-number|',
);

Attribute Population Strategy

Both catalogs (OMC, imported as-is):

• OMC identifiers and extensions (no Collabree country-code / data-provider-id)
• code.text for display name
• status, form, ingredient, optional amount
• GTIN via https://www.gs1.org/gtin when available

Benefits for Catalog Retriever

1. Zero-touch imports: Drop in a new OMC NDJSON release without preprocessing
2. Consistent app UX: Same picker and barcode flow for CH and SA
3. Shared search logic: Both catalogs use OMC scope identifiers and GS1 GTIN barcodes

Implementation Considerations

Where Medications Come From

• Open Medication Catalog CH: static/medications/ch/Medication.ndjson via resource_updater
• Open Medication Catalog SA: static/medications/sa/Medication.ndjson via resource_updater

All match Collabree country-code and data-provider-id identifiers only. OMC rows are not affected.

Validation Rules

• OMC medications are not validated against CollabreeMedication on import
• The app reads code.text, status, OMC identifiers, and GS1 GTIN for search
• GTIN is optional but enables barcode lookup when present

This approach provides a flexible foundation for handling diverse medication catalogs while maintaining practical search behaviour for both countries.