Novice, Practiced, Mastered

    blue-button

    1.10.2 • Public • Published

    blue-button

    Blue Button JavaScript library

    NPM

    Build Status Coverage Status Dependency Status

    blue-button.js

    This library provides the following functionality

    • Parse XML documents
    • Sense type of data (CCDA, CMS, C32, etc.)
    • Parse CCDA into JSON representation
      • Parse CCDA elements (sections) into JSON representation
    • Parse C32 into JSON representation
      • Parse C32 elements (sections) into JSON representation
    • Parse CMS into JSON representation
    • Generate JSON object based on data model

    Actual implementation of sensing type of data and parsing CCDA and C32 reside in this repository. Implementation of other functionalities reside in

    In addition CCDA generation from blue-button JSON objects is available in blue-button-generate.

    This library is primarily implemented for node.js and is available via npm. A browser version is also available via bower. The browser version is created using browserify and can be used in the same way that you would use it in node.js.

    Usage

    Require blue-button module

    var bb = require("blue-button")

    Load some health data content. Currently CCDA (CCD), C32 and CMS are supported

    var data = "some CCDA.xml, C32.xml or CMS.txt here...";

    Generate JSON representation of the health data

    var doc = bb.parse(data);

    parse method senses the type of the health data, parses and converts it into JSON. All types of health data is converted into a common model. Validate doc according to the common model schema

    var valid = bb.validator.validateDocumentModel(doc);
    if (! valid) {
        throw new Error('failed');
    }

    Do changes to doc in your application

    doc.data.demographics.phone.number = "(555)555-5555";

    Create a CCDA (CCD) document that includes your changes

    var bbg = require("blue-button-generate")
    var modifiedDataCCD = bbg.generateCCD(doc);
    ## Data Model

    Blue Button library converts all types of health data (CCDA, C32, CMS) into a common model. Data model schema and validation implementation can be found in blue-button-model.

    API

    XML Utilities

    Blue Button library provides basic XML parsing and XPath functionality via libxmljs (node.js) and DomParser (browsers). All XML related API methods are inherited from blue-button-xml and available from xml object

    var xml = bb.xml;
    #### parse(src)

    Parses XML content string into an XML Object which can be used in other API methods. Details of the actual XML object can be found in the documentation of underlying libraries libxmljs (node.js) and DomParser (browsers).

    Arguments

    • src - XML content in string.
    • returns - XML Object.

    xpath(doc, p, ns)

    Finds the XML nodes that are specified by p.

    Arguments

    • doc - XML document or any parent XML node inside the document that is found by a previous xpath call.
    • p - A valid XPath string.
    • ns - XML namespace specifications. By default h: urn:hl7-org:v3" and xsi: http://www.w3.org/2001/XMLSchema-instance are used as they are the namespaces used in CCDA.
    • returns - XML object node.
    ### Sensing

    senseString(data)

    Senses the type of the string content.

    Arguments

    • data - String content for which the type is to be found.
    • returns - A result object. In the case of an error either null is returned or an error is thrown. Result object has the following properties
      • type - A string that identifies the type of the content. Currently can be ccda, c32, cda, xml, cms, va, format-x, json, blue-button.js, va, pdf or unknown.
      • xml - In the case of XML content (ccda, c32, cda, xml) this is set to the parsed XML object.
      • json - In the case of JSON content (blue-button.js, json) this is set to the passed JSON object.

    senseXml(data)

    Senses the type of an XML object.

    Arguments

    • data - XML object for which the type is to be found.
    • returns - A result object. In the case of an error either null is returned or an error is thrown. Result object has the following properties
      • type - A string that identifies the type of the content. Currently can be ccda, c32, cda, xml, unknown.

    JSON Generation

    #### parse(data, options)

    This is the primary method in Blue Button library that both senses the type of the input content and generates JSON out of it. Underneath it calls to other sensing and JSON generation methods.

    Arguments

    • data - Any string data content. Currently CCDA (CCD), C32 and CMS are supported.
    • options - The following properties are supported
      • component - Specifies a component of CCDA or C32 document; not used for CMS documents. data should only contain content for the component. The following CCDA (CCD) sections are supported: ccda_demographics, ccda_vitals, ccda_medications, ccda_problems, ccda_immunizations, ccda_results, ccda_allergies, ccda_encounters, ccda_procedures, ccda_social_history, ccda_plan_of_care, ccda_payers. The following C32 sections are supported: c32_demographics, c32_vitals, c32_medications, c32_problems, c32_immunizations, c32_results, c32_allergies, c32_encounters, c32_procedures. In addition individual entries in each section can also be specified (ccda_vitals_entry, ccda_medications_entry, ..., c32_vitals_entry, ...).
    • returns - JSON representation of the data.

    parseString(data, options)

    This is similar to parse but it assumes data to be valid XML.

    parseXml(data, options)

    This is similar to parse but it assumes data to be an XML object.

    parseText(data)

    This is similar to parse but it assumes data to be Text (ASCII) and options is not used. Currently only Text content in CMS format is supported.

    Examples

    See scripts in /example or /test directories that use the above API methods for CCDA, C32 and CMS examples.

    Goals

    • Full support of CCDA, C32 and CMS
    • Ability to extend to support other data formats
    • Solid, well-documented JSON-based data model for patient health data
    • Modularity - easy to extend (both parser and data model)
    • Node.js support
    • Browser support
    • Speed of parsing
    • Well tested on entire corpora of CCDA samples from https://github.com/jmandel/sample_ccdas

    Future Roadmap

    • Merge back into bluebutton.js repo
    • Refactoring into smaller components (sub-modules)

    Contributing

    Contributors are welcome. See issues https://github.com/amida-tech/blue-button/issues

    Release Notes

    See release notes here

    License

    Licensed under Apache 2.0

    Project was influenced by and used some code from:

    bluebutton.js library licensed under MIT

    Josh Mandel's ccda-to-json library licensed under Apache 2.0

    Install

    npm i blue-button

    DownloadsWeekly Downloads

    132

    Version

    1.10.2

    License

    Apache-2.0

    Last publish

    Collaborators

    • mmccall
    • rmharrison
    • jbregstone
    • austundag
    • mhiner
    • hrickards
    • b3rry
    • ekavs
    • jsachs13
    • sirctseb