ACME Tulip Care
0.1.0

Data Exchange

This page describes how each use-case scenario is realised as a FHIR R4 exchange, identifying the actors involved, the HTTP interaction, and the profiles that carry the data.

Scenario 1 – Register a New Tulip Variety

Actor flow: Farmer → Farmer Client Application → TulipCare FHIR Server

When a farmer adds a new cultivar to the catalogue, the Farmer Client Application constructs a new resource conforming to the TulipVariety profile and POSTs it to the server.

Step Interaction Profile / Resource
Client sends variety data POST /Basic (TulipVariety-profiled) TulipVariety
Server validates class code Internal call (or $validate-code to Terminology Service) TulipClass-lm CodeSystem / ValueSet
Server returns success HTTP 201 with assigned resource ID TulipVariety

The TulipVariety resource carries:

  • identifier — server-assigned variety ID.
  • code — variety name and class.
  • ext-bloomSeason extension — coded bloom season (bound to BloomSeason-lm ValueSet).
  • ext-heightRangeMin / ext-heightRangeMax extensions — height range in inches.
  • ext-flowerColour extension — free-text flower colour.
  • ext-varietyRecordedDate extension — server-populated creation date.

The server validates the tulip class code against the TulipClass-lm ValueSet before persisting the record.

Scenario 2 – Register a Bulb Batch Linked to a Variety

Actor flow: Farmer → Farmer Client Application → TulipCare FHIR Server

When a farmer logs a new bulb shipment, the Farmer Client Application constructs a resource conforming to the TulipBulb profile and POSTs it to the server. The resource must reference an existing TulipVariety record.

Step Interaction Profile / Resource
Client sends bulb batch data POST /Basic (TulipBulb-profiled) TulipBulb
Server validates status code and reference Internal validation BulbStatus-lm ValueSet; TulipVariety (referenced)
Server returns success HTTP 201 with assigned resource ID TulipBulb

The TulipBulb resource carries:

  • identifier — farmer-assigned batch ID (system: https://fake-acme.org/fhir/TulipCare/bulb-id).
  • subject or extension reference — link to the parent TulipVariety resource.
  • quantity — number of bulbs.
  • ext-supplier extension — supplier name (free text).
  • ext-acquisitionDate extension — date bulbs were received.
  • ext-plantingLocation extension — field/bed identifier.
  • ext-bulbStatus extension — coded status (bound to BulbStatus-lm ValueSet); initial value In Storage.
  • ext-recordedDate extension — server-populated creation date.

The server validates the status code against the BulbStatus-lm ValueSet and confirms the variety reference resolves before persisting.

Scenario 3 – Search Inventory by Variety or Class

Actor flow: Farmer → Farmer Client Application → TulipCare FHIR Server

The farmer uses the inventory search screen to find bulb batches by variety or tulip class. The Farmer Client Application issues a FHIR search request; the server returns a Bundle.

Step Interaction Profile / Resource
Client issues search GET /Basic?... with search parameters (e.g., variety name, tulip class code) —
Server returns matching resources HTTP 200 with searchset Bundle TulipBulb (entries); linked TulipVariety (included or referenced)

The response Bundle contains zero or more TulipBulb resources. Each entry exposes variety name, quantity (from ext- fields), planting location, and status so the client can render the inventory list. Linked TulipVariety resources may be included as _include results to avoid additional round-trips.

Scenario 4 – Update Bulb Batch Status (e.g., Planted)

Actor flow: Farmer → Farmer Client Application → TulipCare FHIR Server

When the farmer plants a batch, the Farmer Client Application updates the existing TulipBulb resource. Either a full PUT or a PATCH interaction may be used depending on client capability.

Step Interaction Profile / Resource
Client sends updated resource PUT /Basic/{id} or PATCH /Basic/{id} TulipBulb
Server validates new status Internal validation BulbStatus-lm ValueSet
Server returns updated resource HTTP 200 TulipBulb

The update modifies:

  • ext-bulbStatus extension — new status value (e.g., Planted), validated against BulbStatus-lm ValueSet.
  • ext-plantingDate extension — optionally set to the planting date (must not precede acquisition date).
  • Server updates meta.lastUpdated to reflect the modification time.

Valid status transitions supported by the BulbStatus-lm CodeSystem are: In Storage → Planted → Bloomed → Harvested or Discarded.

Scenario 5 – View Variety Catalogue

Actor flow: Farmer → Farmer Client Application → TulipCare FHIR Server

The farmer browses all registered varieties. The Farmer Client Application issues a search against the variety endpoint; the server returns a Bundle of TulipVariety resources.

Step Interaction Profile / Resource
Client requests catalogue GET /Basic?... (optionally filtered by bloom season) —
Server returns variety list HTTP 200 with searchset Bundle TulipVariety (entries)

Each TulipVariety entry in the Bundle includes variety name, tulip class (from TulipClass-lm ValueSet), bloom season (from BloomSeason-lm ValueSet), height range (ext-heightRangeMin / ext-heightRangeMax), and flower colour (ext-flowerColour). Optional filtering by bloom season allows the farmer to narrow the catalogue view to a particular growing period.

Summary: Scenario → Profile Mapping

Scenario Operation Primary Profile Supporting Terminology
1 – Register Variety POST (create) TulipVariety TulipClass-lm, BloomSeason-lm
2 – Register Bulb Batch POST (create) TulipBulb BulbStatus-lm
3 – Search Inventory GET (search) → Bundle TulipBulb, TulipVariety TulipClass-lm
4 – Update Bulb Status PUT / PATCH (update) TulipBulb BulbStatus-lm
5 – View Variety Catalogue GET (search) → Bundle TulipVariety TulipClass-lm, BloomSeason-lm