Patient Journey Intelligence cookbook

Patient Journey Intelligence is easier to learn through clinical workflows than through a feature list. This library documents the paths that take raw clinical data to the things people are actually accountable for: a registry submission, a feasibility answer for a sponsor, an outreach worklist a nurse will trust, a de-identified corpus a partner is entitled to, an outcomes study a reviewer will accept.

Start from the outcome you owe someone, not from the module list.

Pick your starting point

If you need to…	Start here
Turn scanned reports and narrative notes into structured, abstractable fields	Turn clinical documents into curated, reviewable data
Answer a trial feasibility question and hand the study team a working list	Screen patients for clinical trial eligibility
Turn a FHIR R4 bundle into OMOP CDM records, with or without NLP	Ingest FHIR R4 into OMOP CDM, with or without NLP
Bring an OMOP repository you already maintain into Patient Journey Intelligence	Connect an existing OMOP CDM database
Produce a care-gap worklist your care managers will trust	Run care gap analysis on a patient cohort
Release clinical notes to a collaborator or a model training set	De-identify clinical notes with human review
Run registry abstraction with named reviewers and an audit trail	Run registry abstraction with an audit-ready evidence trail
Convert a guideline update into a measurable population	Turn a clinical guideline into measurable cohort criteria
Verify an extracted value against the document it came from	Verify any clinical value against its source document
Package a de-identified corpus for an external partner under an agreement	Prepare a de-identified dataset for third-party sharing
Process FHIR files that carry no reliable patient identifier	Ingest external FHIR documents without patient linkage
Process CDA or HL7 documents from an exchange or a prior vendor	Ingest external HL7 CDA documents without patient linkage
Run a real-world outcomes study from cohort definition through cost availability	Run an end-to-end HEOR outcomes study
Link a batch of uploaded documents to the right patients and visits	Link document batches to patients with structured OMOP metadata

Recipes and scenarios

A recipe is one repeatable operation, such as building a dataset or running a de-identification job. A scenario chains recipes into a complete piece of work someone is accountable for.

Scenario pages carry the full walkthrough and, where one exists, a video. Recipe pages cover a single building block you will reuse across several scenarios, so you do not have to read a whole workflow to find one step.

Every page follows the same shape: who it is for, why the workflow matters, what you gain, what has to be in place first, the numbered steps, and the limitations worth knowing before you commit to it.

The dependency chain

Most workflows follow the same order. If a step produces nothing, the cause is usually an unmet prerequisite two stages upstream rather than a failure in the step you are looking at.

Ingestion -> Cohort -> Dataset -> Information Extraction
                              -> Data Curation
                              -> De-Identification
                              -> Review -> Export, share, or follow-up analysis

Two paths skip parts of that chain:

Ingestion -> Dataset from ingestion filters -> Extraction, Curation, or De-Identification
Structured FHIR -> OMOP CDM -> Cohort, Patient Journey, Database Explorer

The rules behind the diagram:

• Ingest data before anyone can search, curate, or analyze it.
• A cohort is a reusable patient population. A dataset is the working set of patients, documents, and images that a specific job reads.
• Data Curation and De-Identification both require a dataset. A cohort alone is not enough.
• Information Extraction can run before Data Curation to rank documents and narrow what curation processes. See Focus curation on the documents that matter.
• Structured FHIR ingestion can populate OMOP directly when the source bundle already carries the coded clinical facts you need.
• Document-first ingestion skips the patient layer entirely, for files with no reliable patient identifier.

Scenario library

Scenario	Use case	Workflow	Video
Turn clinical documents into curated, reviewable data	Structured, evidence-linked fields out of clinical documents	S3 ingestion -> Cohort -> Dataset -> Data Curation	Yes
Screen patients for clinical trial eligibility	Trial feasibility, pre-screening, and recruitment planning	Trial Match -> Cohort -> Dataset	Yes
Ingest FHIR R4 into OMOP CDM, with or without NLP	OMOP CDM records from a FHIR R4 bundle, with an optional NLP pass over the notes it carries	FHIR ingestion -> OMOP CDM -> Patient Journey	Yes
Connect an existing OMOP CDM database	Patient Journey workflows on an OMOP CDM you already maintain	PostgreSQL connection -> Connection test -> Import -> Patient Journey Gold OMOP	Yes
Run care gap analysis on a patient cohort	Care-gap worklists computed against the full clinical record, with evidence behind each gap	Cohort -> Care Gap -> Patient Timeline	Yes
De-identify clinical notes with human review	Reviewed de-identified clinical text, with the review documented	Assistant cohort -> Dataset -> De-Identification	Yes
Run registry abstraction with an audit-ready evidence trail	Registry abstraction with named reviewers and an evidence trail	Registry Project -> Case Finding -> Curation -> Export	-
Turn a clinical guideline into measurable cohort criteria	Published guidance translated into an auditable cohort definition	Guideline Question -> Cohort Criteria -> Care Gap	Yes
Verify any clinical value against its source document	Verification of any extracted value against its source document	Patient Timeline -> Source Document Review -> Correction or Escalation	Yes
Prepare a de-identified dataset for third-party sharing	A de-identified package prepared for sharing under an agreement	Dataset -> De-Identification -> External Sharing Package	Yes
Ingest external FHIR documents without patient linkage	FHIR files with no reliable patient identifier, processed as documents	Local Upload -> Document-first ingestion -> Dataset -> Curation, Extraction, or De-Identification	Yes, 2
Ingest external HL7 CDA documents without patient linkage	CDA and HL7 documents from exchanges, referrals, and prior-vendor archives	Local Upload -> Document-first ingestion -> Dataset -> Curation, Extraction, or De-Identification	Yes
Run an end-to-end HEOR outcomes study	Real-world outcomes research from cohort definition to cost availability	Assistant -> Guidelines -> Terminology -> Cohort -> Timeline -> Clinical Measures -> Database Explorer	Yes
Link document batches to patients with structured OMOP metadata	Deterministic patient, visit, and provider linkage for a document batch	Batch Upload -> Structured Metadata -> OMOP CDM -> Patient Journey	Yes

Videos are visual screen walkthroughs without audio narration. All of them are on the Patient Journey Intelligence playlist.

Recipe library

Core building blocks

Every scenario in the library is assembled from these.

Recipe	What it produces
Ingest clinical documents from an S3 source	Clinical documents available for cohort, dataset, and curation workflows
Create a patient cohort with the Assistant	A named, reusable patient population built from a plain-language question
Build a dataset from a cohort or ingestion results	The scoped working set that curation, extraction, and de-identification require
Start Data Curation from a dataset	Structured fields with an evidence span behind every value
Focus curation on the documents that matter	A curation run that processes the informative notes instead of the whole chart
Use Information Extraction results to guide Data Curation	A narrowed dataset, read cheaply before the expensive pass

Curating facts that OMOP cannot hold

The building blocks above mostly move and reshape data the OMOP Common Data Model already holds. These recipes use Data Curation to pull clinically decisive facts that live only in free-text notes and have no native home in OMOP's coded domains. Each defines a custom registry rather than using a built-in preset, and the field lists on those pages are illustrative starting points rather than shipped presets.

Recipe	The fact it captures
Curate reason for medication discontinuation or switch	Why a drug was stopped, which a coded exposure record cannot represent
Curate implanted-device and UDI details	Make, model, and lot number, so a recall becomes a query rather than a chart review
Curate cancer recurrence events	Recurrence date, type, and site, which reuse the original diagnosis code in claims
Curate family history with pedigree detail	Relative, condition, and age at onset, which hereditary risk criteria turn on

Secondary-use rigor applies to all four: version the custom registry so a run is reproducible, keep evidence spans so every value links back to its source sentence, treat "not documented" as absence of documentation rather than absence of the fact, map free-text terms back to standard concepts before joining curated output to a cohort, and put a human in the loop before any research, safety, or quality decision.

Who each workflow is for

Role	Most relevant workflows	Typical starting point	What you end up with
Clinician	Assistant cohort creation, guideline questions, care-gap review, Patient Timeline review	A clinical question or a patient list	A cohort, a care-gap list, and the patient context behind both
Data curator	Dataset creation, Information Extraction, Data Curation, De-Identification	A cohort or a set of ingestion-filtered documents	Reviewed extracted fields and de-identified packages
Registrar	Registry project setup, case finding, curation, validation, export	A registry project and a patient cohort	Reviewed registry cases, ready for submission
Data engineer	Source setup, ingestion, ingestion monitoring, dataset readiness	Source files or a configured data source	Ingested documents and usable patient and document assets
Researcher or HEOR analyst	Cohort definition, patient journeys, clinical measures, utilization and cost review	A study question and an inclusion definition	An evidence-linked study output with stated data limitations
Privacy officer	De-identification review, external sharing packages	A dataset scoped to an approved release	A documented review a signatory can stand behind
Administrator	User access, configuration, audit, readiness checks	Deployment or team setup	A governed Patient Journey Intelligence workspace

Feature-to-use-case mapping

Feature	What you use it for	Typical user
Data Sources	Bring clinical files, FHIR resources, and external OMOP databases into the platform	Data engineer, administrator
Ingestion Jobs	Monitor, retry, and validate data loading, including structured FHIR and external OMOP ingestion	Data engineer, administrator
Assistant	Ask clinical data questions and create cohorts in plain language	Clinician, analyst
Cohort Builder	Save reusable patient populations	Analyst, researcher
Dataset Builder and Explorer	Prepare the input that curation, extraction, and de-identification require	Data curator, analyst
Information Extraction	Find targeted facts in documents, and rank documents before curation	Data curator, subject matter expert
Data Curation	Produce structured, evidence-linked fields	Data curator, registrar
De-Identification	Review and remove sensitive information before sharing	Privacy officer, data curator
Clinical Trial Matcher	Create cohorts from trial eligibility criteria	Research coordinator
Care Gap Analyzer	Identify patients missing recommended care	Quality team, care manager
Clinical Guidelines	Ask guideline questions and get cited answers	Clinician, medical affairs
Patient Timeline	Review patient history and the documents behind it	Clinician, registrar, analyst
Patient Registry	Manage case finding, abstraction, review, validation, and export	Registrar, reviewer
Standard and Custom Registries	Define or manage abstraction requirements	Registry administrator, subject matter expert
Medical Terminology	Resolve clinical terms and support criteria building	Analyst, clinician
Clinical Measures	Compute outcome indicators across a cohort	Researcher, quality analyst
Database Explorer	Validate data and inspect analysis outputs	Analyst, administrator
Evidence and version history	Provide source-linked provenance and reproducible runs	Data curator, registrar, auditor
Administration, access, and audit	Manage users, permissions, compliance, and configuration	Administrator

What varies by deployment

The steps in this library are reference paths. In a live deployment some steps may be skipped, renamed, or handled by a different role depending on configuration, data readiness, and governance requirements. A few differences are worth confirming before you commit to a workflow in a project plan:

• Cost analysis depends on the OMOP cost table being populated in your environment.
• Outcome review depends on which clinical measures are configured for the target disease.
• Care-gap results depend on the source data each condition requires. A gap can read as open when the supporting document was never ingested.
• Information Extraction handoff into a curation job, and de-identification export and save behavior, both vary by deployment.
• Registry export may be available where direct submission to an external registry is not configured.

Frequently asked questions

A cohort is a reusable patient population saved for use across workflows. A dataset is the working set of patients, documents, and images built from a cohort or from ingestion filters. Data Curation, Information Extraction, and De-Identification all require a dataset, not just a cohort. See Build a dataset from a cohort or ingestion results.

You need a dataset. A cohort defines the patient population; a dataset adds the document, image, and note-type scope those jobs read. A dataset can be built from a cohort or directly from ingestion filters, so a cohort is not always the starting point. See Build a dataset from a cohort or ingestion results.

Yes. Enabling Augment with Information Extraction passes extraction findings into curation as additional evidence, and the Filter documents control that opens beneath it narrows which notes curation processes. Both depend on Information Extraction completing and on deployment configuration. See Focus curation on the documents that matter.

Use structured FHIR ingestion when the source bundle already carries the coded clinical facts you need: conditions, medications, observations, procedures, encounters, and visits map into OMOP CDM without NLP. Facts that exist only in narrative notes still require document ingestion and clinical NLP. Most production deployments run both paths and merge, and a single ingestion job can do it. See Ingest FHIR R4 into OMOP CDM, with or without NLP.

Use document-first ingestion, which processes the files without assigning a patient or creating an OMOP person record, then build a dataset directly from the ingestion job. This is the right path for partner bundles, evaluation corpora, and exchange documents about people who are not in your database. See Ingest external FHIR documents without patient linkage and the CDA variant.

Supply structured OMOP metadata alongside the batch. metadata.json and person.json are required for patient linkage; visit, provider, care-site, location, and measurement files are optional and included only when the source data holds that context. Linkage is deterministic through matching source values rather than inferred from document text. See Link document batches to patients with structured OMOP metadata.

Confirm the dataset scope matches the approved release, review every detected identifier against the original document, and validate the outputs before delivery. Export and save behavior varies by deployment, so confirm what is enabled before promising a complete handoff. See Prepare a de-identified dataset for third-party sharing.

Four: medication discontinuation reasons, implanted-device and UDI details, cancer recurrence events, and family history with pedigree detail. Each lives only in free-text notes and has no native OMOP field, so each defines a custom registry in Data Curation. See the "Curating facts that OMOP cannot hold" section above.