Order Sets | Medplum
Order sets
Order sets allow you to embed a pre-configured prescribing widget for a group of medications defined in a ScriptSure orderset. The orderset can be mapped to a Medplum PlanDefinition resource or referenced directly by its ScriptSure ID.
Before rendering an order set, ensure ordersets have been synced via scriptsure-orderset-sync-bot (ongoing sync) or imported via scriptsure-orderset-import-bot (one-time backfill).
React hook: useScriptSureOrderSet
Package: @medplum/scriptsure-react · GitHub Source Code
Calls POST /fhir/R4/PlanDefinition/$order-set-url to resolve the authenticated iFrame URL for the order set prescribing widget. The hook stays idle until patientId is set.
import { useScriptSureOrderSet } from '@medplum/scriptsure-react';
function OrderSetTab({ patientId, planDefinitionId }: { patientId: string; planDefinitionId: string }) {
const { url, loading, error } = useScriptSureOrderSet({ patientId, planDefinitionId });
if (loading) return <div>Loading...</div>;
if (error) return <div>Error loading order set</div>;
if (!url) return null;
return <iframe src={url} width="100%" height="800px" />;
}
Options:
| Option | Type | Description |
|---|---|---|
patientId |
`string | undefined` |
planDefinitionId |
string |
Medplum PlanDefinition ID — bot resolves this to a ScriptSure orderset ID. |
scriptSureOrdersetId |
number |
ScriptSure orderset ID directly. Use when no PlanDefinition exists. |
appId |
string |
Optional app identifier. |
Either planDefinitionId or scriptSureOrdersetId must be provided.
Returns:
| Field | Type | Description |
|---|---|---|
url |
`string | undefined` |
loading |
boolean |
true while the URL is being fetched. |
error |
unknown |
Set if the request fails. |
refresh |
`() => Promise<string | undefined>` |
Creating an order set
An order set is a PlanDefinition resource with type.coding[0].code = "order-set", plus one ActivityDefinition per medication line. Each PlanDefinition.action references its ActivityDefinition by canonical URL.
The bundle below is a minimal working example–a geriatric type 2 diabetes starter pack. The bundle type is collection; convert it to a transaction bundle before posting:
import { convertToTransactionBundle } from '@medplum/core';
import orderSetBundle from './order-set-example-bundle.json';
const result = await medplum.executeBatch(convertToTransactionBundle(orderSetBundle));
const pdId = result.entry?.find((e) => e.response?.location?.startsWith('PlanDefinition/'))?.response?.location?.split('/')[1];
Transaction behavior depends on the transaction-bundles project feature.
If the transaction-bundles feature flag is not enabled on your project, the transaction bundle is silently processed as a batch. Entries execute independently with no atomicity, so a failed entry does not roll back the others and can leave a partial order set behind. See FHIR Batch Requests for details.
Example order set bundle (PlanDefinition + ActivityDefinition)
{
"resourceType": "Bundle",
"type": "collection",
"identifier": {
"system": "https://medplum.com/demo-export",
"value": "orderset/geriatric-t2dm-starter/1.0.1"
},
"entry": [
{
"resource": {
"resourceType": "ActivityDefinition",
"url": "https://medplum.com/ActivityDefinition/metformin-500-mg-tablet",
"version": "1.0.1",
"status": "active",
"kind": "MedicationRequest",
"title": "Metformin 500 mg tablet",
"productCodeableConcept": {
"coding": [{ "system": "http://www.nlm.nih.gov/research/umls/rxnorm", "code": "861007" }],
"text": "Metformin 500 mg tablet"
},
"quantity": { "value": 60, "unit": "Tablet" },
"dosage": [{
"text": "Take 1 tablet by mouth twice daily with meals.",
"doseAndRate": [{ "doseQuantity": { "value": 1, "unit": "Tablet" } }],
"timing": { "repeat": { "frequency": 2, "period": 1, "periodUnit": "d" } }
}]
}
},
{
"resource": {
"resourceType": "PlanDefinition",
"url": "https://medplum.com/PlanDefinition/geriatric-t2dm-starter",
"version": "1.0.1",
"name": "GeriatricT2dmStarter",
"title": "Geriatric Type 2 Diabetes Starter Pack",
"status": "active",
"type": {
"coding": [{ "system": "http://terminology.hl7.org/CodeSystem/plan-definition-type", "code": "order-set" }]
},
"action": [
{
"title": "Metformin 500 mg tablet",
"definitionCanonical": "https://medplum.com/ActivityDefinition/metformin-500-mg-tablet|1.0.1"
}
]
}
}
]
}
After importing, sync the PlanDefinition to ScriptSure via scriptsure-orderset-sync-bot with the resource ID.
See the full three-medication example bundle (Metformin + Empagliflozin + Sitagliptin) in the Medplum Provider demo app. The provider app's Get Started page includes an Import Order Set button ( GetStartedPage.tsx) that converts the collection bundle, posts it as a transaction, and syncs the resulting PlanDefinition — useful as a reference implementation for your own import flow.