FHIR MapBuilder

August 26, 2025 · View on GitHub

FHIR MapBuilder is a Visual Studio Code extension designed to facilitate the edition of FHIR StructureMap resources using FHIR Mapping Language (FML).

For a detailed explanation of what this extension does, check out the functional description in the extension's README.

📂 Project Structure

This repository contains two interconnected projects:

  1. vscode-extension – A Visual Studio Code (VS Code) extension written in TypeScript.
  2. fhir-mapbuilder-validation – A Java Spring Boot REST API that provides backend validation.

The VS Code extension relies on the JAR file generated by the Spring Boot application.

fhir-mapbuilder/
│── vscode-extension/           # VS Code extension (TypeScript)
│   ├── src/
│   ├── package.json
│   ├── tsconfig.json
│   ├── ...
│   ├── target/                 # This is where the JAR file should be placed
│── fhir-mapbuilder-validation/ # Spring Boot REST API (Java)
│   ├── src/
│   ├── pom.xml
│   ├── ...
│── README.md

🛠 Setup & Installation

Clone the Repository

git clone https://github.com/aphp/fhir-mapbuilder.git
cd fhir-mapbuilder

Java 21 Requirement

This application requires Java Development Kit (JDK) version 21 to run. Please ensure that Java 21 is installed and correctly added to your system's PATH.

Build & Package the Java Application

cd fhir-mapbuilder-validation
mvn clean package

After running this command, the JAR file fhir-mapbuilder-validation.jar will be generated in the target/ folder.

Move the JAR File to the Extension Project

cd ..
mkdir vscode-extension/target
mv fhir-mapbuilder-validation/target/fhir-mapbuilder-validation.jar vscode-extension/target

Install Dependencies & Package the VS Code Extension

cd vscode-extension
npm install
vsce package --baseImagesUrl=https://raw.githubusercontent.com/aphp/fhir-mapbuilder/refs/heads/main/vscode-extension

This command will generate a .vsix file, which can be installed in VS Code.

🚀 Running the Applications

Start the Java Spring Boot Application

cd fhir-mapbuilder-validation
mvn spring-boot:run

Run the VS Code Extension

  1. Open vscode-extension in VS Code.
  2. Press F5 to start a new Extension Development Host.

⚙️ GitHub Workflows

Several GitHub Actions workflows have been set up to automate key parts of the project:

  • Test Workflow (test.yml)

This workflow runs automatically on every push or pull request targeting the main branch. It installs dependencies, compiles TypeScript, and runs the extension's test suite to ensure code quality.

  • Release Workflow (release.yml)

This workflow is triggered automatically when a new Git tag matching the pattern v* (e.g., v1.0.0) is created. It packages the VS Code extension into a .vsix file and attaches it to the corresponding GitHub Release on the Releases page.

  • Publish Workflow (publish.yml)

A dedicated workflow to automatically publish the VS Code extension to the Visual Studio Marketplace. This workflow can be triggered manually via the GitHub Actions tab and uses a secure token to authenticate the publishing process.

📜 License

This project is licensed under the MIT License.