Getting Started

Ready to dive into Ignifyr? Explore our tutorial section to familiarize yourself with key concepts and terms, and follow step-by-step video guides that showcase the tool’s functionality with clear, detailed explanations.

Project

In Ignifyr, a project serves as the foundation for your work, acting as a container for multiple ETL pipelines, referred to as jobs. Each job encompasses all the essential configurations and definitions needed to execute the mapping process from start to finish.

Schema

Schemas define the metadata for the source data format and act as a validation framework to ensure the input data meets the required standards before mapping begins. You can infer them from files and SQL tables, import them from a REDCap data dictionary, or define them by hand.

Target Profile or Table

A target profile is the FHIR profile that the output of a mapping must conform to, such as US Core, the International Patient Summary or your own common data model. Import profiles from a FHIR server or a ZIP file of StructureDefinitions, and choose one, with its version, for each mapping. With Ignifyr Enterprise, the tables of the OMOP CDM, versions 5.3, 5.4 and 6.0, are built in and can be chosen as the target in the same way.

Mapping

Mappings define the transformation rules for converting source data into the desired FHIR resources or OMOP CDM rows. They are created using HL7 FHIR® resource templates written in a format and template language specific to Ignifyr, which supports standard FHIRPath expressions alongside Ignifyr-specific methods. A single mapping definition can include multiple mappings, allowing for one-to-many and many-to-many transformation scenarios. Additionally, mappings can leverage multiple data source schemas and contexts, providing extensive flexibility and customization to meet diverse use cases.

Mapping Context

A mapping context provides additional information used to enhance the mapping process. Concept maps translate codes between systems, and unit conversions convert values between units, both defined as simple CSV files. Mapping contexts are referenced within mappings to support more dynamic and context-aware transformations.

Terminology Service

Ignifyr integrates with FHIR terminology services to ensure accurate and standardized data representation. This integration supports two modes:

  • Remote FHIR Terminology Service: Connect to external terminology servers to utilize established clinical concepts and their translations, promoting interoperability and adherence to standards.
  • Local Terminology Service: Define and manage custom code systems, value sets and their code translations tailored to your organization's unique requirements, ensuring precise and context-specific data representation.

Job

Jobs act as ETL pipelines, encompassing all the necessary definitions to execute the data transformation process. When a job is run, the following components are utilized:

  • Data Source Settings: Configuration details for connecting to the source data.
  • Mappings: Detailed instructions for transforming source data into the desired FHIR resources.
  • Sink Settings: Where the results go, a FHIR server, an OMOP CDM database, or NDJSON, CSV, Parquet or Delta Lake files.
  • Terminology and Identity Services: The services used during mapping for consistent coding and identifiers.
  • Execution Options: Run the job once, on a cron schedule, as a stream, or in batches for very large sources.

Execution

Every run of a job is an execution. Ignifyr records the number of FHIR resources created and the errors of each mapping, so that you can find and fix faulty records. You can stop running executions and reschedule jobs. Enterprise deployments also send execution logs to Elasticsearch and Kibana.

Tutorial

Eleven short videos take you through the Ignifyr web interface, from creating a project to managing terminologies. Click a video to play it.

These videos were recorded when Ignifyr was still called toFHIR, so you will see the old name on screen. The workflow and the concepts are the same in Ignifyr.

  • 01 Creating Project: The initial step

    Welcome to the very first Ignifyr tutorial! This video walks you through creating a new project in Ignifyr, including steps like setting a project name and defining project-specific configurations.

  • The goal of a schema definition is to describe the data source (its shape such as field names, data types etc.) to the system. Data source schemas are provided to the engine as a configuration of FHIR StructureDefinition resources. The tutorial explains how schemas are defined and how they provide metadata and validation for input data, ensuring the mapping process starts with well-defined data structures.

    Related reading

  • This video guides you through the process of creating mappings, using HL7 FHIR resource templates and the Ignifyr-specific template language. It highlights the importance of FHIRPath expressions and custom functions as the foundation for defining mappings. You'll learn how to effectively use FHIRPath and Ignifyr methods to design precise and efficient mappings.

    Related reading

  • This tutorial demonstrates how to connect and work with data sources featuring various relationships using Ignifyr. Learn how to efficiently handle complex EHR data and explore different use cases where Ignifyr simplifies the process.

  • Mapping variables in Ignifyr enable users to create and reuse repetitive expressions efficiently. This feature enhances the flexibility and reusability of your mappings, making your overall mapping process more streamlined. Follow along with the video to understand how mapping variables can optimize your Ignifyr workflows.

  • Ignifyr empowers users to set preconditions for mappings, acting as filters to determine whether a mapping should be executed based on specific conditions. By setting clear criteria based on the source data, you can filter out records that do not meet the specified conditions. In this tutorial video, you'll explore the process of defining a precondition for an example mapping, gaining a comprehensive understanding of how preconditions enhance mapping process.

  • Mapping contexts in Ignifyr, which are simple CSV files, are categorized as concept-map and unit-conversion. The objective of a mapping context is to provide a term/concept mapping or unit conversion by defining these in separate CSV files instead of embedding into the mapping scripts depicted with FHIRPath. These contexts play a vital role in facilitating the exchange and mapping of healthcare data. Concept-maps enable the mapping of concept codes between different systems, while unit-conversion focuses on mappings between different healthcare data units. In this tutorial video, you'll learn how to define a mapping context and effectively utilize it within your mappings, expanding your capabilities in Ignifyr.

    Related reading

  • Jobs serve as complete ETL pipelines, bringing together essential definitions such as schemas, mappings etc. When executing a job, Ignifyr seamlessly orchestrates the entire process, from reading the specified data to executing the defined mappings and writing the results to the designated sink, a FHIR server or files. In this tutorial video, you'll learn the step-by-step process of defining a job, including configuring data source settings, setting up sink settings, and selecting mappings to be executed.

    Related reading

  • Ignifyr provides a separate panel for the execution of jobs. After executing a job, users can easily access valuable information such as the number of successfully created FHIR resources and any encountered errors. Learn how to monitor results for any faulty resources and take appropriate actions to ensure optimal mapping outcomes. This video tutorial demonstrates how to execute a job seamlessly within the GUI and provides guidance on analyzing the execution results.

  • Ignifyr offers a built-in testing feature that lets you test your mapping definitions during development. With this feature, you can ensure your mappings work as expected and that the generated FHIR resources meet desired standards, including validation against the target profiles inside Ignifyr. In this video, you'll learn how to test and validate your mappings, as well as how to identify and fix errors in Ignifyr.

    Related reading

  • Ignifyr supports remote FHIR terminology services and enables you to create and manage your own local terminology service. This tutorial guides you through building a local terminology service from scratch, helping you ensure precise data representation and seamless concept exchange. You'll also learn how to integrate the local terminology service into your mappings, enhancing healthcare data integration effectively.

    Related reading

Beyond the Videos

Some features are newer than the videos. These guides and posts cover them.

Map to US Core and other profiles

Import profile StructureDefinitions and select a target profile for each mapping.

Read the FAQ

Map to or from the OMOP CDM

Pick a built-in OMOP CDM table as the target or source of a mapping, and write the rows to your CDM database.

Read the blog post

Infer schemas automatically

Let Ignifyr read a file or SQL table and propose the schema for you.

Read the blog post

REDCap to FHIR

Turn REDCap instruments into schemas and map saved forms to FHIR in real time.

Read the blog post

Very large sources

Split sources with millions of rows into parameterised batches.

Read the blog post

Scheduled and streaming jobs

Run jobs on a cron schedule with incremental pulls, or continuously from folders and Kafka topics.

Read the documentation

Quick Start with Ignifyr Community

The videos use the web interface of Ignifyr Enterprise. With the open-source Community edition, you work from the command line instead.

1 Build the engine

You need JDK 11 and Apache Maven.

git clone https://github.com/srdc/ignifyr-community.git
cd ignifyr-community
mvn -B -DskipTests install

The standalone jar is created at ignifyr-cli/target/ignifyr-engine-standalone.jar.

2 Check the installed plugins

List the connectors and sinks that the jar contains.

java -jar ignifyr-cli/target/ignifyr-engine-standalone.jar list-plugins

The Community edition lists connector-file, connector-sql, core, sink-fhir and sink-file.

3 Lay out your definitions

Keep schemas, mappings, mapping contexts and jobs as JSON and CSV files in these folders.

my-project/
├── schemas/            source schemas (FHIR StructureDefinitions)
├── mappings/           mapping definitions
├── mapping-contexts/   concept maps and unit conversions (CSV)
└── mapping-jobs/       mapping jobs

The formats are described in the README on GitHub.

4 Run a job

Start the engine from your project folder and point it at a mapping job.

cd my-project
java -jar /path/to/ignifyr-engine-standalone.jar run --job mapping-jobs/my-job.json

To use other folders, set them in a configuration file and start the engine with -Dconfig.file=ignifyr.conf. Without run, the engine opens an interactive command line where you can load and run jobs.

What's next?

See the whole workflow at a glance, learn how others use Ignifyr, or ask us for a demo on your own data.

How It Works Explore Use Cases Request Demo