mbrindam/surescripts-sim

•Updated 6 months ago

Surescripts NCPDP SCRIPT 10.6 simulator for EHR development

Image

4.4K

mbrindam/surescripts-sim repository overview

⁠surescripts-sim

A lightweight simulator of the Surescripts NCPDP SCRIPT 10.6 network endpoint for local electronic prescribing (eRx) development and testing.

Drop it into any EHR dev environment that sends NCPDP SCRIPT NewRx messages. No Surescripts account, credentials, or VPN required.

Supports: linux/amd64 (Intel/AMD) and linux/arm64 (Apple Silicon, AWS Graviton)

⁠What it does

Accepts POST / with Content-Type: text/xml and a valid NCPDP SCRIPT 10.6 <Message> body
Parses patient, prescriber, pharmacy, and medication fields from the XML
Returns a deterministic NCPDP <Status> response based on a built-in scenario engine
Logs every transaction to stdout (newline-delimited JSON) and an in-memory store
Serves a real-time monitoring dashboard at http://localhost:8888⁠

⁠Quick start

Option 1: Using Docker Compose (recommended for dev)

docker compose up -d
# Dashboard: http://localhost:8888
# NCPDP endpoint: http://localhost:8888/ (or port 3001 if routing internally)

Option 2: Using Docker directly

docker run -d \
  --name surescripts_sim \
  -p 8888:3001 \
  mbrindam/surescripts-sim:latest

Then point your EHR backend at the simulator:

SURESCRIPTS_URL=http://localhost:8888

If running inside a Docker Compose network alongside your EHR backend:

# In your EHR's docker-compose.yml
services:
  surescripts-sim:
    image: surescripts-sim:latest   # or build: ./surescripts-sim
    container_name: surescripts_sim
    # No external port needed if only accessed by the backend container
    networks:
      - your_network

  your-backend:
    environment:
      - SURESCRIPTS_URL=http://surescripts-sim:3001

⁠Scenario engine

Scenarios are triggered deterministically by pharmacy NCPDP ID or DEA schedule — no random failures.

Pharmacy NCPDP ID	Scenario	HTTP	NCPDP Code
`0000000`	Pharmacy not found	422	900
`9999999`	Pharmacy inactive	422	900
`1111111`	Already dispensed	422	910
Any other	Approved	200	010

DEA Schedule (with a valid pharmacy)	Scenario	NCPDP Code	Note
`II`, `IIN`, `C-II`, `CII`, `2`	EPCS Schedule II	010	Audit trail note per 21 CFR Part 1311
`III`, `IV`, `V` and variants	Controlled III–V	010	Forwarding note added

⁠REST API

Method	Path	Description
`POST`	`/`	Submit NCPDP SCRIPT 10.6 message
`GET`	`/`	Monitoring dashboard (HTML)
`GET`	`/api/logs`	Transaction history (JSON, most recent first)
`DELETE`	`/api/logs`	Clear transaction history
`GET`	`/api/stats`	Aggregate counts and average latency
`GET`	`/health`	Health check

⁠Dashboard

The dashboard at http://localhost:8888⁠ shows:

Stats bar — total, processed (010), rejected (900/910), controlled, average response time
Transaction table — color-coded by outcome (green = approved, red = rejected, blue = controlled)
XML inspector — click any row to view full request and response XML side by side
Auto-refresh — polls every 3 seconds

⁠NCPDP SCRIPT 10.6 message format

The simulator expects a NewRx message. Minimal required fields:

<?xml version="1.0" encoding="UTF-8"?>
<Message TransactionDomain="SCRIPT" TransactionVersion="10.6"
         xmlns="http://www.ncpdp.org/schema/SCRIPT">
  <Header>
    <To Qualifier="P">SURESCRIPTS</To>
    <From Qualifier="D">YOUR_SYSTEM</From>
    <MessageID>unique-message-id</MessageID>
    <SentTime>2024-03-15T12:00:00</SentTime>
    <Security>
      <UsernameToken>
        <Username>your-api-key</Username>
        <Password>your-api-key</Password>
      </UsernameToken>
    </Security>
  </Header>
  <Body>
    <NewRx>
      <Patient>
        <HumanPatient>
          <Name><LastName>Smith</LastName><FirstName>John</FirstName></Name>
          <DateOfBirth><Date>19580314</Date></DateOfBirth>
          <Gender>M</Gender>
        </HumanPatient>
        <PatientID><Qualifier>MR</Qualifier><ID>MRN-001</ID></PatientID>
      </Patient>
      <Prescriber>
        <NonVeterinarian>
          <Name><LastName>Johnson</LastName><FirstName>Sarah</FirstName></Name>
          <PrescriberID><Qualifier>NP</Qualifier><ID>1234567890</ID></PrescriberID>
        </NonVeterinarian>
      </Prescriber>
      <Pharmacy>
        <Identification><NCPDPID>1234567</NCPDPID></Identification>
        <BusinessName>Springfield Pharmacy</BusinessName>
      </Pharmacy>
      <MedicationPrescribed>
        <DrugDescription>Metformin HCl 500 MG Oral Tablet</DrugDescription>
        <ProductCode><Qualifier>ND</Qualifier><Code>00093726701</Code></ProductCode>
        <Quantity><Value>60</Value></Quantity>
        <DaysSupply>30</DaysSupply>
        <NumberOfRefills>5</NumberOfRefills>
        <WrittenDate><Date>20240315</Date></WrittenDate>
        <SigText>Take 1 tablet by mouth twice daily with meals</SigText>
      </MedicationPrescribed>
    </NewRx>
  </Body>
</Message>

HTTP headers required:

Content-Type: text/xml; charset=UTF-8
SOAPAction: "NewRx"

⁠Log format

Stdout logs are newline-delimited JSON:

{"level":"info","timestamp":"2024-03-15T12:00:00.000Z","event":"ncpdp_transaction",
 "messageType":"NewRx","scenario":"approved","responseCode":"010",
 "drug":"Metformin HCl 500 MG","deaSchedule":"non-controlled",
 "pharmacy":"Springfield Pharmacy (NCPDP: 1234567)",
 "prescriber":"Sarah Johnson NPI:1234567890","processingMs":143}

⁠Connecting to real Surescripts

When production credentials are available, simply change the URL your backend points at:

SURESCRIPTS_URL=https://staging.surescripts.net/v10.6
SURESCRIPTS_KEY=your-real-api-key

The simulator is a drop-in replacement — no code changes needed in your EHR backend.

⁠Docker Hub

The image is published to Docker Hub⁠ and automatically built for multiple platforms whenever the code is pushed to the repository.

Available tags:

latest — most recent build from master branch
v1.0.0, 1.0.0, 1.0, 1 — released versions (semantic versioning)
master-<short-sha> — specific commit builds

Pull the latest image:

docker pull mbrindam/surescripts-sim:latest

The builds are created and published by GitHub Actions⁠ using docker/buildx, supporting both x86 (linux/amd64) and ARM (linux/arm64) architectures.

⁠Requirements

Docker (version 20+) and Docker Compose (version 2+) to run the image
No source code checkout required — pull directly from Docker Hub
No other dependencies

⁠License

MIT

Tag summary

Recent tags

Content type

Image

Digest

sha256:8703ca702…

Size

48.3 MB

Last updated

6 months ago

docker pull mbrindam/surescripts-sim:master-425ef7a