Skip to content

Home

Jump to bottom
Thomas Niccolo Reyes edited this page Oct 27, 2025 · 5 revisions

PH-RoadSafetyIG Wiki

Welcome! This is the developer and contributor guide for the PH-RoadSafetyIG FHIR Implementation Guide.

Table of Contents

  1. Introduction
  2. Prerequisites & Installation
  3. Project initialization (how this repo was created)
  4. Building & Validating Locally
  5. Continuous Integration & Publishing
  6. Contributing Workflow
  7. Modeling Guidelines
  8. Troubleshooting & FAQ
  9. References & Learning

Introduction

PH-RoadSafetyIG is a FHIR Implementation Guide (IG) for road safety and health information in the Philippines.
This guide helps you:

  • Build and preview the IG locally.
  • Contribute changes using a standardized GitHub workflow.
  • Learn best practices for modeling, identifiers, and documentation.

Prerequisites & Installation

A. Java

  • Install JDK 11+ (Java 11 or newer).
  • Set JAVA_HOME and ensure java -version works.

B. Node.js & SUSHI

  • Recommended: Use nvm-windows (Windows) or nvm (macOS/Linux).
  • Install Node.js 18 LTS: 
    nvm install 18
nvm use 18
  • Install SUSHI globally: 
    npm install -g fsh-sushi
  • Verify: 
    node -v
npm -v
sushi -h

C. Git

  • Install Git and configure your name/email: 
    git --version

D. Optional Tools

Project initialization

This project began from a SUSHI-generated skeleton. To reproduce or understand the initial setup, follow these notes.

What was run

sushi init
  • When prompted, the project was named: PH-RoadSafetyIG
  • Then accept the remaining defaults SUSHI offered.

What sushi init did (high-level)

  • Created a SUSHI project skeleton in the current folder:
    • sushi-config.yaml (project metadata)
    • input/ folder with example FSH files and a basic authoring layout (profiles, valuesets, instances)
    • .fshignore (if applicable) and other defaults
  • Left default metadata in sushi-config.yaml that should be reviewed and updated for this repository.

Files & locations you should review/add

  • sushi-config.yaml — review and edit canonical, package-id, version, fhirVersion, publisher, contact, status.
  • input/fsh/ — place your FSH profiles, value sets, extensions, and instances here.
  • input/fsh/instances or input/fsh/resources — add NamingSystem instance(s) and examples here (project conventions vary; keep consistent).

Recommended edits to sushi-config.yaml (replace example values)

name: PH-RoadSafetyIG
id: example.fhir.ph.roadsafety
canonical: https://build.fhir.org/ig/UPM-NTHC/PH-RoadSafetyIG
version: 0.1.0
status: draft
publisher: UP Manila NTHC
contact:
  - name: PH Road Safety IG Maintainers
    telecom:
      - type: url
        value: https://github.com/UPM-NTHC/PH-RoadSafetyIG
fhirVersion: 4.0.1

Notes:

  • canonical should be the published base URL for the IG (build.fhir.org, GitHub Pages, or your host).
  • fhirVersion should match the FHIR release you intend to target (R4, R5, etc.).

Quick reproduce/build after init

# from project root
sushi .                # generate FHIR artifacts into fsh-generated/
# then run the repo's publisher scripts:
# Windows
_updatePublisher.bat
_genonce.bat

# macOS / Linux
./_updatePublisher.sh
./_genonce.sh

# open output/index.html to preview

Commit and create the initial PR

git init
git add -A
git commit -m "initial commit"
git push origin -u feature/init-sushi
# create PR to main, follow repo's PR policy

Recommended immediate next steps after init

  1. Edit sushi-config.yaml (canonical, package-id, publisher, fhirVersion).
  2. Add real content under input/fsh/ (profiles, value sets, examples, naming systems).
  3. Add a NamingSystem instance for national identifiers (if applicable) under input/fsh/instances.
  4. Run sushi . and the publisher build to confirm output renders.
  5. Commit changes and open a PR for review (CI should build and the PR should pass checks).

Building & Validating Locally

1. Clone the Repository

git clone https://github.com/UP-Manila-SILab/PH-RoadSafetyIG
cd PH-RoadSafetyIG

2. Generate FHIR Resources

sushi .        # outputs to fsh-generated/

3. Update IG Publisher

  • Windows:
    Run _updatePublisher.bat
  • macOS/Linux:
    Run ./_updatePublisher.sh

4. Build the IG

  • Windows:
    Run _genonce.bat

  • macOS/Linux:
    Run ./_genonce.sh

  • Open output/index.html in your browser to preview.

Continuous Integration & Publishing

Option 1: HL7 Auto IG Builder

  • Install the FHIR IG Builder GitHub App.
  • Each push triggers a build; preview at:
    https://build.fhir.org/ig/:org/:repo/branches/:branch/

Option 2: GitHub Actions

Example workflow (.github/workflows/ci.yml):

name: Build IG
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: qligier/fhir-ig-action@v0.3.0
        with:
          ig-publisher: "latest"
          sushi: "3"

Contributing Workflow

Branching

Create issue:

  • Create branch from Github UI, copy the recommended commands OR
  • run terminal commands 
    git pull origin
git checkout {branch name generated}

ezgif-3fd3e4f7ee028e

Commit & PR

  • Make small, focused commits with clear messages.
  • Build and test locally before pushing.
  • Push your branch and open a Pull Request (PR) to main.

Pull Request Policy

  1. ✅ Only merge when CI is green.
  2. 📝 Merge notes required (unless history is self-explanatory).
  3. 🔄 Preferred merge method: Rebase and Merge.
  4. 🌿 Delete the feature branch after merge.
  5. ✅ Mark all files as reviewed in GitHub UI.

Reviewer Checklist

  • Does the IG build locally and in CI?
  • Are new artifacts linked in the IG?
  • Are identifiers and canonical URLs correct?
  • Are changes documented in PR notes?

Modeling Guidelines

Using NamingSystem for Identifiers

Example:

{
  "resourceType": "NamingSystem",
  "id": "nationia-national-patient-id",
  "name": "Nationia National Patient Identifier System",
  "status": "active",
  "kind": "identifier",
  "date": "2024-05-30",
  "publisher": "Nationia Ministry of Health",
  "responsible": "Nationia National Health Identifier Agency",
  "description": "Defines the various ways Nationia's National Patient Identifier can be referenced. The OID is the primary uniqueId.",
  "usage": "Used to identify patients uniquely across all healthcare services in Nationia.",
  "uniqueId": [
    {
      "type": "oid",
      "value": "urn:oid:1.2.3.4.5.6",
      "preferred": true,
      "comment": "Official OID for the National Patient ID"
    },
    {
      "type": "uri",
      "value": "http://ns.nationia.gov/identifiers/national-patient-id",
      "preferred": false,
      "period": { "start": "2020-01-01" }
    },
    {
      "type": "other",
      "value": "NPIA",
      "preferred": false,
      "comment": "Legacy system identifier"
    },
    {
      "type": "other",
      "value": "NNPID",
      "preferred": false,
      "comment": "Prefix used by the National Hospital Network"
    }
  ]
}
  • Use FSH for all profiles, extensions, value sets, and examples.
  • Keep canonical URLs stable and update versions as needed.

Troubleshooting & FAQ

  • SUSHI not found:
    Ensure Node 18 is active and npm install -g fsh-sushi was run.
  • Publisher fails:
    Re-run the update script; confirm Java 11+ is installed.
  • Terminology server errors:
    Builds may skip terminology checks if the server is down.
  • CI build not appearing:
    Check that the FHIR IG Builder GitHub App is installed and branch names are valid.

References & Learning

Video Learning Series

See the FHIR History and Modelling Video Series for a comprehensive background.

Thank you, and let's keep building together: saving lives, one commit at a time

Clone this wiki locally