DIPS Arena VAQM Assistant

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

Features

• Extract VAQM Files: Break down .vaqm XML files into editable components
• 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.

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 DIPS Arena tooling.