Medication search returns FDB-only codings that don't resolve when used to create a MedicationStatement

[jayant-walvekar-falconeer]

We are integrating against the Medication FHIR search and then creating MedicationStatements from the returned FDB code, and we've hit two related behaviors we'd like guidance on.

1. Medication search returns entries with an FDB coding but no RxNorm coding

A text search on the Medication endpoint returns a mix of two kinds of results:

Entries whose coding[] contains both an FDB system (http://www.fdbhealth.com/) and an RxNorm system (http://www.nlm.nih.gov/research/umls/rxnorm) code.
Entries whose coding[] contains only the FDB system code (no RxNorm pairing), often with a display prefixed THSC ….
Example for "levothyroxine 50 mcg":

237361 → "levothyroxine 50 mcg tablet" — has FDB and RxNorm codings.
216187 → "THSC Levothyroxine Sodium 50 mcg tablet" — FDB coding only.
(Same pattern for HCTZ: 207776 "THSC Hydrochlorothiazide 25 mg tablet" is FDB-only.)

Questions:

Are the FDB-only / THSC-prefixed entries intended to be selectable search results, or should they be filtered out?
Is the presence of an RxNorm pairing the right signal for "this is a usable, resolvable medication"? If not, what's the recommended way to tell, from the search response, which entries are safe to use?
If DB-only / THSC-prefixed entries are to be ignored then is that documented anywhere? And what is the purpose of those entries in the search result?

2. Creating a MedicationStatement with an unresolvable FDB code is accepted silently

When we create a MedicationStatement using one of these FDB-only codes (e.g. 216187):

The create call returns success (HTTP 200/202).
The resulting command stays in state: staged (never committed).
The medication field comes back null.
In the chart, the row renders with a blank medication name (SIG/label present, no drug name).
With a paired code (e.g. 237361) the same flow commits and renders correctly.

Questions:

Is there a way to have the create API validate the fdb_code against the catalog and return an error, rather than accepting it and leaving the command staged with a null medication?
Is state: staged + medication: null the documented signal an integrator should poll for to detect this failure after a 200? Is there a more direct error/validation response we should be using?

More broadly: what's the recommended pattern to avoid submitting a code that Medication search itself returned but that the chart can't resolve?

It is consistently reproducible on the dev sandbox and in production using above mentioned sample medicines.

[jayant-walvekar-falconeer]

Need inputs on this ASAP. I have similar issue for Allergen. Logged as a separate ticket. Need response on both

[rmagier1]

Hi @jayant-walvekar-falconeer —

Thanks for the detailed write-up.

A couple of clarifying questions first

When we tested this on our end, the symptoms you describe didn't fully reproduce — so we want to make sure we're looking at the same thing before pointing you in the wrong direction:

• Are you creating these MedicationStatement records via the FHIR API (POST /MedicationStatement) or via the SDK / plugin path? The validation and rendering behave differently between them.
• Could you share the exact request payload you're sending and what you're observing on the response / in the chart? On our side, posting a MedicationStatement via FHIR with medicationCodeableConcept — including with the exact THSC code 216187 you mentioned — produced a fully-rendered command in the chart with the display text intact (not a blank medication name). So we'd like to see what's different in your case.

Two FHIR payload paths, by design

When using FHIR POST /MedicationStatement, there are two ways to reference the drug, and they have intentionally different validation:

• medicationReference: "Medication/fdb-216187" — fumage validates the FDB code against the chart's catalog. If the code isn't in that catalog (which is the case for THSC entries like 216187), you'll get a 422 with:

  {
    "resourceType": "OperationOutcome",
    "issue": [{
      "severity": "error",
      "code": "not-found",
      "details": {"text": "Unknown Medication resource 'fdb-216187'"}
    }]
  }

  Use this path if you want the API to reject codes the chart can't resolve.

• medicationCodeableConcept with the coding inline — fumage does not validate against the chart's catalog on this path, by design. The reason is that this path is what lets you capture historical or unstructured medications that wouldn't be in the chart's prescribable picklist (e.g. a med the patient reports being on from another country, an old formulation no longer in FDB, or anything you want recorded as a free-text concept). For example, you can post an entry like:

  {"medicationCodeableConcept": {"coding": [{"system": "UNSTRUCTURED", "code": "N/A", "display": "Whatever I want"}]}}

  and the record will be created and the command will render with "Whatever I want" as the medication name. The tradeoff is that for those unstructured/non-picklist records, you don't get an automatic interaction-check resolution or a clean handoff to refill — the next time someone goes to refill, they'll have to pick the matching picklist entry themselves before they can send to the pharmacy.

So the create endpoint isn't "silently failing" on the medicationCodeableConcept path — it's intentionally permissive there to support the unstructured-capture use case.

If you're using the SDK command module instead

If you're authoring these from a plugin via MedicationStatementCommand.originate(...), the behavior depends on the shape of the fdb_code you pass. The field accepts either a string or a Coding, and Canvas branches on the system:

• fdb_code = "216187" (bare string) — Canvas treats this as an FDB code and looks it up against the chart's picklist catalog. If the code isn't in the picklist (THSC entries aren't), the resolved medication is None and the command renders with a blank medication name.

• fdb_code = Coding(system=CodeSystems.FDB, code="216187", display="THSC ...") — same outcome as the bare string. Because the system is FDB, Canvas still runs the picklist lookup, and the display field is not used as a fallback if the lookup fails. So a Coding with system: FDB doesn't get you a freeform display the way medicationCodeableConcept does on the FHIR side — you still need a code that's in the picklist.

• fdb_code = Coding(system=CodeSystems.UNSTRUCTURED, code="anything", display="Whatever I want") — Canvas does not look up against the picklist on this path. The coding is used as-provided and the display is what renders in the chart. This is the SDK-side equivalent of the unstructured FHIR medicationCodeableConcept flow above — use it when you're capturing a historical or non-picklist medication.

So if you've been passing a string fdb_code (or a Coding with system: FDB) using a THSC code like 216187, that's exactly the path that would produce the blank-medication-name symptom you described, regardless of any display text you included.

This is the most likely path on which "MedicationStatement created, medication field null/blank in the chart" would consistently reproduce — which is why we'd like to confirm whether you're going through FHIR or the SDK. Either way, the fix is the same: look the code up against the chart's catalog before submitting, so you only ever pass FDB codes the resolver can bind; or use the UNSTRUCTURED system if you specifically want to capture something not in the picklist.

Recommended path forward: use the chart's catalog directly

The cleanest fix is to bypass FHIR /Medication for this lookup and call the same catalog the chart uses. We have a reference plugin in MSF that exposes that catalog as a SimpleAPI endpoint:

https://github.com/Medical-Software-Foundation/canvas/tree/main/data-migrations/data_migrations/plugins/coding_lookup

Once installed, the medication-search endpoint is:

GET /plugin-io/api/coding_lookup/medication_search?text=levothyroxine+50+mcg+tablet
Authorization: <your-api-key>

It also accepts rxnorm_code (alone or in combination with text) if you want to query by code:

GET /plugin-io/api/coding_lookup/medication_search?rxnorm_code=966225

Response is a clean {count, results} shape where every result includes the code (FDB med_medication_id) and any paired RxNorm coding, in a form Canvas's chart can resolve:

{
  "count": 1,
  "results": [
    {
      "text": "levothyroxine 50 mcg tablet",
      "value": 237361,
      "coding": [
        {"code": 237361, "display": "levothyroxine 50 mcg tablet", "system": "http://www.fdbhealth.com/"},
        {"code": "966224", "display": "levothyroxine 50 mcg tablet", "system": "http://www.nlm.nih.gov/research/umls/rxnorm"}
      ]
    }
  ]
}

Under the hood

The plugin is a thin wrapper around our SDK's pre-authenticated ontologies HTTP client, canvas_sdk.utils.http.ontologies_http. Its /medication_search endpoint translates your text / rxnorm_code query into a call to the same ontologies endpoint the in-chart medication picker uses, then normalizes the response into the {count, results} shape above. The actual call it makes is:

from urllib.parse import urlencode
from canvas_sdk.utils.http import ontologies_http

# text search → equivalent of /medication_search?text=…
ontologies_http.get_json(
    f"/fdb/grouped-medication/?{urlencode({'search': 'levothyroxine 50 mcg tablet'})}"
).json()

# rxnorm lookup → equivalent of /medication_search?rxnorm_code=…
ontologies_http.get_json(
    f"/fdb/grouped-medication/?{urlencode({'rxnorm_rxcui': '966225'})}"
).json()

/fdb/grouped-medication/ is the curated catalog that backs the chart's autocomplete — that's what makes the results consistent with what providers see in the UI and ensures the codes resolve cleanly when used in a MedicationStatement. SDK docs for ontologies_http: https://docs.canvasmedical.com/sdk/utils/#making-requests-to-the-ontologies-service

So you have two equivalent options:

• Install the MSF plugin as-is if you want the ready-made {count, results} API surface and don't want to author your own plugin code.
• Call ontologies_http directly from your own plugin if you'd rather avoid the dependency or shape the response differently — the plugin's medications_api.py is short and is a good template to crib from.

Either way, the underlying lookup is the same, and the results will match what the chart's medication picker shows.

Summary

• If you want to capture historical / unstructured medications that wouldn't necessarily be in the chart's catalog, the medicationCodeableConcept path is the right tool. It's intentionally permissive about codes.
• If you want a prescribable, refill-ready medication that the chart will resolve and treat consistently with what providers see in the UI, use the MSF plugin's /medication_search endpoint (or replicate its call yourself) to look up the code, and submit it either as medicationReference (which will 422 if anything's wrong) or as medicationCodeableConcept with the picklist-derived coding.
• Aligning the FHIR /Medication search endpoint with the chart's catalog so it doesn't return entries that can't be resolved later is a separate engineering item we'll take as a feature request and follow up on.

And please share what you're seeing on your end (payload + chart screenshot) — we couldn't reproduce the blank-medication-name symptom with the THSC code in our testing, so we want to make sure we're solving the same problem you're hitting.

[jayant-walvekar-falconeer]

Hi @rmagier1 — thanks for the detailed write-up, this clarifies the model behind the two paths.

Quick context first: the FHIR-vs-SDK split has been a real source of overhead for us. We've ended up writing code that crosses both surfaces because each one is missing something the other has — we raised the broader pattern in #1686. These incompatibilities cost us multiple days of investigation per case, and they don't move our core product forward. Anything that converges the two surfaces — or even just documents, per resource, which path is the source of truth for which field — would meaningfully help.

Where we are on the medication path

Our custom medication-handling plugin (separate from the MSF coding_lookup plugin you pointed us at) already requires that any entry returned by GET /Medication?_text=... carry both an FDB coding and an RxNorm coding before we treat it as usable. Entries with only an FDB coding (THSC and similar) are rejected before submission. The final write goes through this plugin using the resolved FDB code.

This is essentially the same discriminator your reply describes, so it's reassuring we landed on the same model independently.

Where we are on the allergen path

For allergens, our main path already requires FDB plus either RxNorm or SNOMED. The SNOMED branch is needed because the clinically critical category-level allergens (Penicillins, Sulfa, Latex, Shellfish, Fish, Egg Derived) are FDB+SNOMED paired, not RxNorm.

On one of our other call sites, we query /fdb/allergy/ directly and pass dam_allergen_concept_id_type straight into the SDK AllergenType(...). Looking at the allergy code in the MSF plugin you pointed at, the raw value coming back from /fdb/allergy/ is in the {1, 104, 110} space and your plugin remaps it to {2, 6, 1} (medication / ingredient / allergy group) before using it as the SDK type. Two questions on that:

• Is the 1/104/110 → 2/6/1 mapping the canonical one integrators should apply when going from /fdb/allergy/ directly to the SDK AllergenType?
• Does a concept_type mismatch on AllergyCommand produce the same "command staged, name blank" outcome as the THSC medication case, or does it fail differently?

Two follow-ups

1. Catalog-resolvability signal on GET /Medication. Until the FHIR catalog alignment lands as a feature, would it be possible to mark (or omit) entries the chart can't resolve? Today the only way an integrator can tell is to apply the pair filter themselves, which requires having had this exchange first.
2. Plugin-vs-FHIR field parity — the broader theme in #1686. A per-resource note of which path is canonical for which field would let us stop reinventing this analysis for every new feature.

Thanks again for the thorough write-up and for the ontologies_http / MSF coding_lookup pointer.

[jayant-walvekar-falconeer]

Wanted to put the real problem upfront, then confirm a few things before
committing to the plugin path.

We receive med-name programmatically (via our API) as strings like this from external agency chart:

"Albuterol-Budesonide Inhalation Aerosol 90-80 MCG/ACT (Albuterol-Budesonide)"

and we ultimately need to match it to FDB 613572:

"albuterol 90 mcg-budesonide 80 mcg/actuation HFA aerosol inhaler"  (FDB+RxNorm)

That is the whole process we go through. Canvas' existing APIs are not directly of use so we have to write a lot of code around Canva's API and the issues too.

Neither /Medication?_text=... nor the plugin's /medication_search?text=...
does a general semantic match like that — both look like literal substring
matches over FDB displays — so we are spending real effort working around it.

Concrete cases I am seeing:

1. Hyphenated combination names return 0 on FHIR even though the entry exists
   in the UI catalog and the space-separated form works:

   GET /Medication?_text=albuterol-budesonide   -> total=0
   GET /Medication?_text=albuterol budesonide   -> total=1
      fdbhealth 613572  "albuterol 90 mcg-budesonide 80 mcg/actuation HFA aerosol inhaler"
   

   Same for albuterol-ipratropium and fluticasone propionate-salmeterol.
   By contrast _text=hydrocodone-acetaminophen returns 21 and
   _text=sulfamethoxazole-trimethoprim returns 3 — the cases where the FDB
   display literally contains the hyphenated string. So combinations whose
   display interleaves dose info between ingredients
   (albuterol 90 mcg-budesonide 80 mcg) are unreachable via the hyphenated
   query.

2. Chart-style strings with extra context tokens don't match either source.
   albuterol 5 mg/ml (0.5 %) nebulizer solution returns 0 on both
   /Medication?_text=... and the plugin's /medication_search?text=...,
   even though FDB 286546 is reachable via shorter variants. To resolve
   strings like this today we already had to add an extra step that
   generates several normalized search-term variants (A, B, C, D), fans out
   those calls, and a second step that picks the best of the N results
   against the original.

We are ending up spending a lot of time overcoming these problems in our
code.

We face the same class of problem on the allergen side when we receive
strings like chocolate (ingredient) or dairy digestive — the UI surfaces
FDB 19561 / 3944 but /Allergen?_text=... does not.

While coding_lookup will solve one problem of getting codes for exactly what appears in the Canvas UI, we still need significant effort to get from:

Input: Albuterol-Budesonide Inhalation Aerosol 90-80 MCG/ACT (Albuterol-Budesonide)
to
Output: FDB 613572 — albuterol 90 mcg-budesonide 80 mcg/actuation HFA aerosol inhaler

I have spent a lot of effort tweaking my code to handle these. If the plugin solves one issue, great, but switching means a full retest, so I want to be sure first.

If _text= (or an equivalent endpoint) did semantic/fuzzy matching instead of literal substring match, that would be the solution for us.

[jayant-walvekar-falconeer]

The logic of selecting only those meds that have FDB and RxNorm code is failing for at least 1 medicine cranberry 450 mg tablet

[rmagier1]

Hi Jayant,

Thanks for the detailed follow-ups — and apologies for the runaround; you've clearly put a lot of effort into this. Let me try to tie all of the threads together, because most of them turn out to share one root cause, and I have a concrete correction on the allergen mapping that should save you some grief.

The one model that explains almost everything

The key thing we didn't make clear last time: the FHIR /Medication search and the chart's medication picker query two different catalogs through two different matchers. They are not the same data source.

• FHIR GET /Medication?_text= searches the entire FDB medication table (every FDB entry, including the THSC / FDB-only ones) using a literal case-insensitive substring match. The search string is split on whitespace and each term must appear as a substring of the medication description (logical AND).
• The chart's autocomplete (and the MSF coding_lookup plugin / the grouped-medication endpoint) search a curated, prescribable catalog using Postgres full-text search (whitespace-tokenized, prefix matching).

So FHIR /Medication is broader (returns things that aren't prescribable, like THSC entries) and matches differently (literal substring vs. tokenized). That single fact explains the THSC entries, the hyphen behavior, and the cranberry case all at once. Walking through each:

1. The right "is this usable?" signal is catalog membership — not RxNorm pairing (and the cranberry case)

This is the most important correction, and it's exactly what your cranberry 450 mg tablet example exposed.

Requiring an RxNorm pairing is the wrong discriminator. It happens to correlate with "prescribable" most of the time, but it's not the actual signal — supplements and herbals (cranberry, many vitamins) are legitimately prescribable in Canvas but simply have no RxNorm concept, so they're FDB-only. Filtering on "has RxNorm" wrongly rejects them. That's the cranberry failure.

The actual signal is whether the code is in the chart's prescribable catalog — i.e. whether it comes back from the grouped-medication endpoint (which is what the MSF plugin's /medication_search wraps, and what the chart autocomplete uses). THSC entries (e.g. 216187) live in the broad FDB table that FHIR /Medication searches, but they are not in that prescribable catalog — which is why medicationReference: "Medication/fdb-216187" 422s and why the command renders blank. Cranberry, by contrast, is in the prescribable catalog despite having no RxNorm.

Recommendation: drop the FDB+RxNorm filter entirely and use the prescribable catalog as your source of truth. If grouped-medication (or the MSF plugin) returns the code, it's resolvable — submit it, RxNorm or not. If it doesn't, don't. That single rule handles both THSC (rejected) and cranberry (accepted) correctly, without you having to maintain a pairing heuristic.

2. Hyphenated combination names (albuterol-budesonide, etc.)

Your diagnosis is essentially right. The cause is that neither search treats - as a word separator — it's kept as a literal character inside a single token.

• On FHIR /Medication, the matcher is literal substring, so albuterol-budesonide only matches if that exact hyphenated string appears in the description. For hydrocodone-acetaminophen and sulfamethoxazole-trimethoprim the FDB display literally contains the hyphenated form, so they match (your 21 / 3 hits). For albuterol-budesonide, the real display interleaves dose info (albuterol 90 mcg-budesonide 80 mcg…), so the literal substring albuterol-budesonide is absent → 0 hits.
• The space-separated form works because the string is split on whitespace into albuterol AND budesonide, both of which are present.

Reliable fix, and it works on both endpoints: normalize - → space in your query text before searching. Both the FHIR endpoint and the grouped-medication endpoint tokenize on whitespace, so albuterol budesonide resolves cleanly on either.

On your specific questions:

• Does the MSF plugin / grouped-medication resolve these? With the space-normalized query, yes — it's the same catalog the chart autocomplete uses and the UI offers these drugs. I want to be straight with you: the plugin doesn't fix the hyphen issue by virtue of being the plugin — it's a different search engine (full-text vs. substring), but it's also not treating - as a separator, so the dependable thing is to normalize the hyphen on your side regardless of which endpoint you hit.
• Is it 1:1 with the UI autocomplete? grouped-medication is the catalog that backs the chart's medication picker, so it's as faithful a match as exists — and much closer than FHIR /Medication, which (as above) searches a broader, non-prescribable superset. I wouldn't promise byte-identical ranking in every case, but it's the same catalog and the same matcher the picker uses.

3. Allergens — there's an important correction here (and I do owe you a response on your other discussion post that is specific to Allergies)

First: yes, there's an allergen equivalent in the same plugin. The MSF coding_lookup plugin exposes /allergy_search (accepts text or rxnorm_code) alongside /medication_search. So you don't need a separate plugin — it's already there.

Now the mapping question — and I think this is the source of the confusion. There are two different FDB allergen endpoints, and they use two different type-numbering schemes:

Scheme	Where you hit it	Type field	Numbering
DAM pick-list	/fdb/allergy/ (queried directly) — also what AllergyCommand resolves against, and what the SDK uses	dam_allergen_concept_id_type	1 = allergy group, 2 = medication, 6 = ingredient
External-vocabulary	GET /Allergen (the FHIR endpoint) — it proxies internally to ontologies /fdb/allergen/; this scheme is what's used for the RxNorm/SNOMED lookups	evd_fdb_vocabulary_type_identifier	1 = medication, 104 = ingredient, 110 = allergy group

The SDK AllergenType enum is ALLERGEN_GROUP = 1, MEDICATION = 2, INGREDIENT = 6 — i.e. identical to the DAM pick-list scheme.

So:

• When you query /fdb/allergy/ directly, dam_allergen_concept_id_type is already in the SDK's {1, 2, 6} space. Pass it straight into AllergenType(...) with no remap. (1→allergy group, 2→medication, 6→ingredient — identical to the enum.) Your "pass dam_allergen_concept_id_type straight into AllergenType(...)" call site is actually correct for this endpoint.
• The {1, 104, 110} → {2, 6, 1} remap is for the FHIR GET /Allergen path (which internally is ontologies /fdb/allergen/), whose evd_fdb_vocabulary_type_identifier uses the {1, 104, 110} scheme. That's the path the MSF plugin's RxNorm branch applies the remap on, and it's canonical there. (For reference, this exact correspondence — vocab 1↔DAM 2, 104↔6, 110↔1 — is the same one our FHIR layer uses internally to translate between the two.)

So to state it plainly for the FHIR endpoint: a type value coming out of GET /Allergen is in the {1, 104, 110} scheme and must be remapped to {2, 6, 1} before you hand it to AllergyCommand / AllergenType. One convenience: the FHIR Allergen resource id is formatted fdb-{1|2|6}-{concept_id} — the middle segment is already the {1,2,6} SDK value, so if you parse the id you can skip the remap entirely.

Does a concept_type mismatch on AllergyCommand produce the same "staged + blank" outcome as the THSC medication case? Yes — same failure mode. The command resolves the allergen by the (concept_id, concept_type) pair against /fdb/allergy/. If that pair doesn't match a row (e.g. right id, wrong type), the resolved allergen is None, and the command stays staged with a blank allergen name — exactly analogous to the THSC medication behavior. So a type mismatch fails the same silent way, which is all the more reason to make sure you're using the {1,2,6} values when talking to the command.

For the allergen text-search/UI discrepancies you noted (chocolate, dairy digestive): the /fdb/allergy/ text search and the /Allergen FHIR search apply vocabulary-type filters that can exclude some concepts, so that's a related-but-separate behavior.

4. Your two broader asks

1. A catalog-resolvability signal on GET /Medication (so an integrator can tell which entries the chart can resolve without having had this conversation). You're right that today there's no such flag — the entries that 422 on create are indistinguishable in the search response. This would have to filed to our Product team to see if this is something we want to add to the roadmap.
2. Plugin-vs-FHIR field parity / source-of-truth per resource (Consistency between SDK and FHIR APIs #1686). This is a fair and recurring theme; I won't pretend convergence is a quick fix, but documenting, per resource, which surface is canonical for which field is something we can pursue more concretely. There's already adjacent work to document the usable ontology endpoints. I'll make sure your specific examples (medication search catalog, allergen type schemes) are attached to that effort.

TL;DR

• Use the prescribable catalog (grouped-medication / the MSF plugin) as your source of truth for medications, and stop filtering on RxNorm presence — that's what fixes both the THSC entries and cranberry.
• Normalize - → space in search text to fix the hyphenated combinations.
• For allergens: /fdb/allergy/ already returns {1,2,6} — pass it straight to AllergenType with no remap. The {1,104,110}→{2,6,1} remap is for the FHIR GET /Allergen path (internally /fdb/allergen/) — that's the surface whose values you must remap before AllergyCommand. (Or just parse the {1,2,6} value out of the FHIR Allergen id, fdb-{1|2|6}-{concept_id}.) A type mismatch on AllergyCommand fails the same "staged + blank" way as the THSC medication case.