openEHR VAQM Assistant

VAQM is a configuration format used by DIPS in their openEHR systems to define reusable, versioned queries written in AQL (Archetype Query Language). VAQM files package AQL queries, data bindings, format expressions, and metadata into a single, version-controlled XML file that can be deployed across openEHR applications.

A VS Code extension for extracting and assembling openEHR VAQM configuration files.

Features

• Extract VAQM Files: Break down .vaqm XML files into editable components
• Extract All VAQM Files: Batch extract all .vaqm files in a folder at once
• Extract All VAQMs and Forms: Extract all VAQMs and Forms in the workspace in one operation
• Assemble VAQM Files: Rebuild .vaqm files from components with automatic version bumping
• AI-Powered Version Comments: GitHub Copilot integration for generating version change descriptions
• Version Management: Semantic versioning with mandatory version bumps and BasedOnVersion tracking
• Component Organization: Clean directory structure for AQL queries and calc expressions
• Format Expressions: Full support for FormatExpressions with WhenExpression extraction
• Proper XML Formatting: Professional XML output with correct encoding and indentation

Installation

From VS Code Marketplace

1. Open VS Code
2. Go to Extensions view (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "VAQM Assistant"
4. Click "Install"

From VSIX File

1. Download the latest vaqm-assistant-X.X.X.vsix file from the releases page
2. Open VS Code
3. Go to Extensions view (Ctrl+Shift+X / Cmd+Shift+X)
4. Click the "..." menu at the top of the Extensions view
5. Select "Install from VSIX..."
6. Browse to and select the downloaded .vsix file
7. Restart VS Code if prompted

Prerequisites

• VS Code 1.85.0 or higher
• GitHub Copilot extension (optional, for AI-powered version comments)

The extension includes all required dependencies:

• @xmldom/xmldom - XML parsing and DOM manipulation
• xpath - XPath queries for XML navigation
• he - HTML entity encoding/decoding
• xml-formatter - Professional XML formatting

Usage

Extract VAQM File

1. Right-click a .vaqm file in the explorer
2. Select "VAQM: Extract VAQM File"
3. Components are extracted to definition/vaqm-components/{vaqm-name}/

Extracted structure:

definition/vaqm-components/My-VAQM/
├── META/
│   ├── vaqm-metadata.json       # VAQM root attributes
│   ├── version-info.txt         # Current version
│   └── extraction-info.json     # Extraction metadata
├── vaqm.xml                     # Formatted original VAQM
├── aql-bindings/
│   └── {binding-name}/
│       ├── base-query.aql       # AQL query with headers
│       ├── paths.xml
│       ├── where-expressions.xml
│       ├── order-by-expressions.xml
│       ├── predicates.xml
│       └── key-values.xml
└── data-elements/
    └── {element-oid}/
        ├── metadata.json
        ├── display-format.calc  # Calc expressions
        ├── sort-format.calc     # (decoded from HTML entities)
        ├── range-format.calc
        ├── x-format.calc
        ├── y-format.calc
        ├── key-values.xml
        └── format-expressions/  # FormatExpressions subfolder
            ├── format-expressions.xml
            ├── when-expression-0.calc
            └── when-expression-1.calc

Assemble VAQM File

1. Right-click a VAQM component directory
2. Select "VAQM: Assemble VAQM File"
3. Choose version bump: Patch, Minor, Major, or Custom
4. Choose how to add version comment:
   • Generate with Copilot - AI analyzes file changes and suggests comment
   • Enter manually - Type your own description
   • Skip - No version comment
5. Assembled .vaqm file saved to src/vaqms/

Version bumping is mandatory - you cannot keep the same version. The BasedOnVersion attribute is automatically updated.

Extract All VAQM Files

1. Right-click a folder containing .vaqm files (e.g., src/vaqms)
2. Select "VAQM: Extract All VAQM Files"
3. All VAQM files in the folder are extracted sequentially
4. Progress is shown with a summary of successful and failed extractions

Extract All VAQMs and Forms

1. Right-click the workspace root, src/, or definition/ folder
2. Select "VAQM: Extract All VAQMs and Forms"
3. The extension recursively scans for all .vaqm files in the workspace
4. Extracts all VAQMs and calls the Form Assistant extension to extract forms
5. Shows unified progress and summary for both operations

Note: If the Form Assistant extension is not installed, you'll be prompted to continue with VAQMs only.

Show VAQM Information

Right-click a component directory and select "VAQM: Show VAQM Information" to view:

• VAQM metadata (name, version, OID)
• Component counts (bindings, elements)
• Extraction information

Configuration

Configure the extension in VS Code settings:

{
  "vaqmAssistant.extractionPath": "definition/vaqm-components",
  "vaqmAssistant.outputPath": "src/vaqms",
  "vaqmAssistant.defaultVersionBump": "patch",
  "vaqmAssistant.formatXml": true,
  "vaqmAssistant.addCommentHeaders": true,
  "vaqmAssistant.openAfterExtract": "directory",
  "vaqmAssistant.openAfterAssemble": "file"
}

Technical Details

HTML Entity Handling

The extension automatically:

• Decodes entities when extracting (readable .calc files)
• Encodes entities when assembling (valid XML)

Version Management

• Semantic versioning (X.Y.Z format)
• Mandatory version bumping on assembly
• BasedOnVersion attribute automatically tracks previous version
• AI-generated version comments via GitHub Copilot integration
• Git diff detection shows what changed since extraction
• Validation ensures new version > current version
• Version tracked in META/version-info.txt

XML Formatting

• Professional formatting with xml-formatter library
• Proper indentation (2 spaces)
• All attributes preserved (RangeFormat, XFormat, YFormat, etc.)

Known Limitations

• No syntax validation for AQL/calc expressions yet
• No code completion or IntelliSense for calc expressions
• Validation command not yet fully implemented

License

See LICENSE file

Contributing

This extension is part of openEHR Norway's openEHR tooling ecosystem.