NhaxLib Documentation for Developers

Owned by Torben Nielsen
Last updated: Dec 10, 2024 by Anders Damkjaer Nielsen
4 min read

An NHAX file is a file format that is used to export/import data from Noah.

A NHAX file is mix of binary data and XML formatted data the so called sections. As the NHAX format is complex and hard to implement HIMSA has developed a standalone library that can be used by business system developers that must support the NHAX format.

 

Extension to Old NHAX Format

The data in NHAX sections is defined using XSD files. All data must validate with respect to the XSD when reading/writing NHAX files.

The Misc section is now used and is defined in and XSD file.

Link to binary NHAX format: Noah 4 Extended Native Format (Nhax and Enhax)

Link to XML Sections in NHAX Files: XML Sections in NHAX Files

 

Error Handling

NhaxLib functions returns a ValidateResult class:

public class ValidateResult
{
/// <summary>
/// Set to false if an error occurs
/// </summary>
public bool Validated { get; private set; }
// Error code
public ErrorCode ErrorCode { get; private set; }
/// <summary>
/// Textual description of the failing entity
/// </summary>
public string ErrorEntity { get; private set; }
/// <summary>
/// Textual description of the error
/// </summary>
public string ErrorDescription { get; private set; }
}

Furthermore functions may throw exceptions.

 

NHAX Writer

The NHAX writer writes Noah data to a NHAX file or a stream. When writing data to a file the NHAXWriter will either produce a number of files of a given max size or one file that contains all data or all data written to a stream.

/// <summary>
/// Write all data to one NHAX file.
/// </summary>
/// <param name="fullPath">Full path to NHAX file</param>
/// <param name="password">Password to access the file</param>
/// <param name="nhaxFileCreatedCallback">Function called when NHAX file is written. The function is called with the name of the file that is written. Can be set to null.</param>
/// <param name="overwriteExistingFiles">True existing files will be overwritten. If false an error will be reported if file exists.</param>
/// <param name="compressData">If true data are compressed</param>
public NhaxWriter(string fullPath, string password, NhaxFileCreatedCallback nhaxFileCreatedCallback = null, bool overwriteExistingFiles = false, bool compressData = true)

 

/// <summary>
/// NhaxWriter constructor that writes data to one or more NHAX files.
/// If more than one NHAX file are created the file will contain a Misc section containing al Misc data provided. The user section will only contain users that are referenced by patients or actions.
/// </summary>
/// <param name="path">Path where the files is stored</param>
/// <param name="filePrefix">The prefix of the NHAX file. The file name is "filePrefix-dddddd" where d is digit e.g. "file-000001", "file-000002"</param>
/// <param name="password">Password to access the file</param>
/// <param name="nhaxFileCreatedCallback">Function called when NHAX file is written. The function is called with the name of the file that is written. Can be set to null.</param>
/// <param name="overwriteExistingFiles">True existing files will be overwritten. If false an error will be reported if file exists.</param>
/// <param name="compressData">If true data are compressed</param>
/// <param name="maxFileSize">Max size of created file. When this size is reached a new NHAX file is created and data written to this file.</param>
/// <param name="maxPatients">Max patients written to file. When this size is reached new NHAX file is created and data written to this file.</param>
public NhaxWriter(string path, string filePrefix, string password, NhaxFileCreatedCallback nhaxFileCreatedCallback = null, bool overwriteExistingFiles = false, bool compressData = true, long maxFileSize = ConstMaxFileSize, int maxPatients=ConstMaxPatients)

 

When the NhaxWriter instance has been created WriteUsers and WriteMiscData must be called in order to add users and add Misc data to the NHAX file. These functions must be called before the WritePatient is called. Each call of WritePatient will add a patient to the NHAX file.

If using the constructor that takes maxFileSize argument a new NHAX file is created when the file size exceeds the maxFileSize after a patient is written. When start writing a new NHAX file the nhaxFileCreatedCallback is called with name of created NHAX file. The default size of maxFileSize is the advised size when generating NHAX file that is used when migrating to NoahES.

It is possible to call the WriteUsers multiple times. When writing patient data - WritePatient - the user referred from a patient data must be known.

IMPORTANT: Be aware that the NhaxWriter implements the idisposable interface. It is important that dispose is called in order to update the binary part of the NHAX file correctly.

 

NHAX Reader

The NHAX reader reads data from an NHAX file or a stream that contains an NHAX file. The NHAX reader can be initialized with file or a stream.

/// <summary>
/// Initializing NHAX file reader
/// </summary>
/// <param name="password">Password if NHAX file is encrypted</param>
public ValidateResult Initialize(string filePath, string password)

 

/// <summary>
/// Initializing NHAX stream reader
/// </summary>
/// <param name="inStream">Stream that contains NHAX formatted data</param>
/// <param name="password">Password if NHAX data is encrypted</param>
/// <returns></returns>
public ValidateResult Initialize(Stream inStream, string password)

Be aware that the NHAX reader implements the idisposable interface. It is important to called the dispose function.

When reading large NHAX files it is recommended to read a moderate number of patients.

 

NHAX Logger Interface

Logging in NhaxLib can be enabled either by implementing the NHAX logger interface INhaxLogger or create and use the simple logger that NhaxLib implements. The logger must be added using NhaxLogger.AddLogger.

Using the NhaxLib logger:

string logPath = @"c:\..."
INhaxLogger Logger = NhaxLogger.CreateLogger(logPath, true, 10 * 1024 * 1024);
NhaxLogger.AddLogger(Logger, NhaxLogLevel.Debug);

 

Sample

An example of a utility making use of the NhaxLib is available here: NHAX FileSplit (Preparing files for Migrator)

The sample code for it is provided under common SDK components at himsa.com

 

Â