7. Libraries

7.1. Msg2JSON

class lib.msg2json.Msg2JSON

Msg2JSON converts HL7v3 XML messages to JSON.

Parameters:
  • log – A python logger object that is used to emit progress as the dom is walked. All dom walking output is classed as DEBUG.
  • parser – A xsd2parser.py xml parser based on the mif xsd.
  • rim – A rimdb2py.sql rim map that contains rim version specific baseattributes, class inheritance, and inheritance attributes.
  • datatypes – A xml2dt.xsl list of all known datatype names for this rim version / HL7 normative edition.
  • knownmt – A list of known messagetypes as strings. These names will be used to find mt mif maps that were loaded as python modules a priori. Note that these modules can be generated by mif12py.xsl and mif22py.xsl.
  • knownin – A list of known interaction types as strings. These names will be used to find in mif maps that were loaded as python modules a priori. Note that these modules can be generated by inmif22py.xsl.
  • debug – Emit the resulting json structure in pretty print format.
Returns:

Msg2json object.
convert()

Convert the provided DOM instance into SQL inserts.

Parameters:root – a parsed message instance or fragment.
Returns:a string containing SQL inserts.

7.2. Msg2SQL

class lib.msg2sql.Msg2SQL

Msg2SQL converts HL7v3 XML messages to SQL inserts using MGRID HDL & HDM.

Parameters:
  • log – A python logger object that is used to emit progress as the dom is walked. All dom walking output is classed as DEBUG.
  • parser – A xsd2parser.py xml parser based on the mif xsd.
  • rim – A rimdb2py.sql rim map that contains rim version specific baseattributes, class inheritance, and inheritance attributes.
  • datatypes – A xml2dt.xsl list of all known datatype names for this rim version / HL7 normative edition.
  • knownmt – A list of known messagetypes as strings. These names will be used to find mt mif maps that were loaded as python modules a priori. Note that these modules can be generated by mif12py.xsl and mif22py.xsl.
  • knownin – A list of known interaction types as strings. These names will be used to find in mif maps that were loaded as python modules a priori. Note that these modules can be generated by inmif22py.xsl.
  • debug – Emit all inserts unconnected to each other. This is useful in database datatype development.
Returns:

Msg2SQL object.
convert()

Convert the provided DOM instance into SQL inserts.

Parameters:root – a parsed message instance or fragment.
Returns:a string containing SQL inserts.

7.3. MessageConverterFactory

class lib.messageconverterfactory.MessageConverterFactory(log, conversion, output=None)

MessageConverterFactory can build message converters on demand.

Parameters:
  • log – A python logger object that is forwarded to underlying converters.
  • conversion – A configuration dictionary that contains the rim module to be used and the interactions supported by this factory. An individual interaction is identified by a name, and contains a dictionary specifying the parser module, the message types used mt, the message types that need to be sought in other modules fixmt, and the interaction mif in to be loaded. Optionally conversion can also contain the key output with the value sql or json.
  • output – Select output to be sql or json.

Example for CDA use:

>>> from mgridenv import log
>>> from lib.messageconverterfactory import MessageConverterFactory
>>> import sys
>>> conversion = {
        'rim': 'rim229R1',
        'interactions': {
            'CDA_R2_NE2010' : {
                'parser' : 'generated.parser.CDA_R2_NE2010.CDA_parser',
                'mt': ['generated.mif.CDA_R2_NE2010.POCD_MT000040'],
                'fixmt': [],
                'in' : []
            }
        }
    }
>>> mcf = MessageConverterFactory(log, conversion, 'sql')
>>> print mcf.convert('CDA_R2_NE2010', open(sys.argv[1]).read())

or alternatively with output defined in the configuration dictionary:

>>> conversion = {
        'output': 'sql',
        'rim': 'rim229R1',
        'interactions': {
            'CDA_R2_NE2010' : {
                'parser' : 'generated.parser.CDA_R2_NE2010.CDA_parser',
                'mt': ['generated.mif.CDA_R2_NE2010.POCD_MT000040'],
                'fixmt': [],
                'in' : []
            }
        }
    }
>>> mcf = MessageConverterFactory(log, conversion)

When output is supplied both as parameter and in the configuration dictionary, the parameter output takes precedence.

convert(interaction, message)

Convert a message using a previously configured interaction specification.

Parameters:
  • interaction – A string identifying an interaction configured at class creation.
  • message – A string containing an HL7v3 XML message.
converter(interaction)

Return the converter for a previously configured interaction

7.4. Introspection

lib.introspectmap.introspectmap(log, msg2sql, rootinteraction, callback=None)

Check the extent of mif coverage for a given xml parser

Some standardisation groups only focus on xsds to define message formats. Typically mifs will be present, but when considered together with the xsd defining xml parser not map correctly. This tool determines where the mifs are underspecified with respect to the xml parser. In other words: what expressions can be made in the xml, that have no defined mapping to the used reference information model?

Parameters:
  • log – A python log object. Will emit detailed information on debug, and emit error for all unmappable constructs.
  • msg2sql – A preconfigured converter for this particular interaction.
  • rootinteraction – The interaction to be examined. This is also the entrypoint in the xml parser, so typically of the form REPC_IN001234UV01.

7.5. DBConverter

class lib.dbconverter.DBConverter

DBConverter exports stored HL7v3 messages or message fragments into XML statements.

Parameters:
  • cursor – A psycopg2 database cursor that will be used for database queries.
  • log – A python logger object that is used to emit progress as the dom is walked. All dom walking output is classed as DEBUG.
  • parser – A xsd2parser.py xml parser based on the mif xsd.
  • rim – A rimdb2py.sql rim map that contains rim version specific baseattributes, class inheritance, and inheritance attributes.
  • datatypes – A xml2dt.xsl list of all known datatype names for this rim version / HL7 normative edition.
  • knowmt – A list of known message type mifs as strings. These names will be used to find mif maps that were loaded as python modules a priori. Note that these modules can be generated by mif12py.xsl and mif22py.xsl.
convert()

Convert the provided object dictionary to the mifname.mifclass.

Parameters:
  • mifname – A mifname string.
  • mifclass – An object name for a cloneclass in the MIF.
  • obj – A python dictionary containing the object. Typically retrieved using retrieveobj().
Returns:

A DOM representation of input object.
export()

Convert the provided DOM representation of an object to an XML string.

Parameters:
  • xmlname – top xml tag.
  • indent – the amount of indentation required.
  • obj – A convert() DOM representation of the object.
  • namespacedef – An optional namespace for the top tag.
Returns:

An XML representation of the input object.
retrieveobj()

Retrieve a rim object from the database. Note that any relations that this object points to as defined in its source MIF will be traversed.

Parameters:
  • mifname – A mifname string.
  • objname – An objectname of a cloneclass in the MIF.
  • objid – An object id that identifies the start of the message (fragment).

The last two parameters are used internally to keep track of retriever state while walking the database object. These have defaults and need not be assigned in user calls:

Parameters:
  • state – current working tree in list representation.
  • knownobj – dictionary that keeps track of already traversed database objects.
Returns:

A python dictionary containing the requested object.

7.6. ParserTools

lib.parsertools.objfactory

Retrieve a new empty DOM object from its object factory embedded in the parser.

Parameters:
  • parser – A xsd2parser.py generated parser.
  • mifname – A mifname string.
  • objname – An objectname of a cloneclass in the MIF.
Returns:

An empty DOM object.
lib.parsertools.objfactoryf

Convenience function that returns an objfactory function tied to a specific parser and mif. The returned function can then be used to create objects using only a classname.

exception lib.parsertools.MapError

Exception raised for XML nodes with no known MIF mappings during message or database conversion.

7.7. Graft

lib.graft.improvexmldtout(module)

Add __str__ for complex types BL, CV, ST, TS, EN that output the expected literal value instead of the composite attributes that define that value.

Add empty exportAttributes functions to ADXP_* and EN_* to mute the output the generalized attribute partType.

Parameters:module – A xsd2parser.py generated parser.
Returns:None, the input parser is modified in place.

7.8. Typeconversion

Type conversion utility functions that convert database types to xml types. Most conversions depend on mgrid-hdl functions, and as such require a database connection.

Function api from hdl to xml-its type:

hdltype2xmlitstype(cursor, objfactory, s)

  • cursor: A psycopg2 database cursor.
  • objfactoryf: An parsertools objfactoryf, an object factory that is pretied to a parser and mif.
  • s: The source string
lib.typeconversion.IVL_TS2TS(cursor, objfactory, s)

Effective time can be expressed as TS in CDAs, and be upconverted on ingest into IVL_TS. This provides the reverse step i.e. demote an IVL_TS to a TS.

lib.typeconversion.ivl_pq2IVL_PQ(cursor, objfactory, s)

Convert a ivl_pq in literal form to IVXB_PQ XML ITS form. I.e. go from [0 g;1 g[ to <low value="0" unit="g"/><high value="1" unit="g" inclusive=false/>

lib.typeconversion.ivl_ts2IVL_TS(cursor, objfactory, s)

Convert a time interval in IVL_TS literal form to IVXB_TS XML ITS form. I.e. go from [2000;2001[ to <low>2000</low><high inclusive=false>2001</high>

lib.typeconversion.ivl_ts2TS(cursor, objfactory, s)

Effective time can be expressed as TS in CDAs, while at some points these are intended as IVL_TS. During message conversion the database will convert these. This provides the reverse step i.e. demote a ivl_ts to a TS.