4. Frequently Asked Questions and Troubleshooting¶
4.1. Frequently Asked Questions¶
4.1.1. How do I load a HL7v3 XML file in the database¶
Before loading the HDL and HDM modules in a database, it is necessary to know the Normative Edition of HL7v3 the message was created against. Once that is known, create a database with the RIM and vocabulary of that normative edition, as is described in section How do I create a RIM database?
Next you need to use a message parser created for the template ids used. Using a message parser is described in section Using a message parser to populate a RIM database.
4.1.2. How do I create a RIM database?¶
Section Creating a database contains examples that show how to load modules to create the datatypes and the RIM of a specific Normative Edition.
4.1.3. How do I view which healthcare modules and vocabularies are loaded?¶
When the modules and vocabularies are loaded with the extensions (see
Loading MGRID extensions in a database), it is possible to view the list in two ways.
The list of extensions is available in a pgadmin3, in the left pane,
in a subtree under the database labelled
‘Extensions’. From the command line,
use psql to connect to your database and issue
the \dx command.
4.1.3.1. View which healthcare modules are loaded in a database¶
lake=# \dx
List of installed extensions
Name | Version | Schema | Description
------------------------+---------+------------+------------------------------------------------------------
adminpack | 1.0 | pg_catalog | administrative functions for PostgreSQL
hl7 | 3.0 | hl7 | healthcare datatypes core
hl7basetable | 3.0 | hdl | healthcare datatypes base tables
hl7v3crud_edition2011 | 2.0 | public | hl7v3 edition2011 CRUD functions
hl7v3datatypes | 3.0 | hl7 | healthcare datatypes
hl7v3rim_edition2011 | 2.0 | public | hl7v3 edition2011 RIM schema
hl7v3vocab_edition2011 | 2.0 | hdl | hl7v3 edition2011 vocabulary
jsquery | 1.0 | public | data type for jsonb inspection
loinc_2_50 | 1.0 | public | loinc 2.50 vocabulary
plpgsql | 1.0 | pg_catalog | PL/pgSQL procedural language
snomedctvocab_20140131 | 1.0 | public | snomed-ct 20140131 vocabulary
tablefunc | 1.0 | public | functions that manipulate whole tables, including crosstab
ucum | 1.0 | hdl | Unified code for units of measure v1.8.2
(13 rows)
4.1.4. Which Normative Edition should I use?¶
To load messages in a RIM database, a RIM version must be chosen to
create the database with, as well as generate a message loader with.
Given a certain message, the question is which RIM to use for a
specific message. The first choice is to choose the RIM from the
Normative Edition from which the message was derived. For CDA R2
this means that the RIM from V3NE2005. However, the vocabulary
content from versions before V3NE2009 have omissions that inhibit
working with full vocabulary support. As the RIM is designed to be
backwards compatible, it is possible to load messages in a newer
version RIM than they were original designed for. As an example, in
V3NE2009, actionNegationInd
and valueNegationInd were introduced,
deprecating negationInd. The latter was not
removed, but is still present in the RIM, which allows storing
messages structured according to an older RIM, and benefit from the
vocabulary fixes of the later RIM. There are however changes between
RIM versions in datatypes. For instance,
Role.effectiveTime was IVL_TS in V3NE2010, and
changed to GTS in V3NE2011. Another example
is Document.versionNumer which is an int in
V3NE2010 and a ST in V3NE2011. A big change is from V3NE2011 to
V3NE2012, where the switch from R1 to R2 datatypes was made. For CDA
R2 messages, using a message parser generated with the V3NE2011 RIM,
and loading in the V3NE2011 RIM is the most practical choice.
4.1.5. Where are the Normative Editions before 2009?¶
These normative editions lack a complete vocabulary specification, that prevents loading the healthcare datatypes, which in turn prevents loading the RIM. Since the RIM is backwards compatible, it is advised to use the latest R1 datatypes based RIM 2011 to load messages with R1 datatypes.
4.1.6. Does MGRID HDM conform to <x>?¶
MGRID HDL, HDM and Messaging provide a set of modules and tools with which it is possible create RIM databases and load contents. Vocabulary and structure are checked. With these base modules it is possible to develop applications for certain use cases, such as a DSS or EHR, or a conformance checker: with MGRID HDM it is possible to write queries that would check for a certain conformance, for instance that codes are from a certain codesystem, or a template contains mandatory sub templates.
4.2. Troubleshooting¶
This section provides answers to common errors and warnings.
4.2.1. ERROR: required extension “name” is not installed¶
MGRID HDL and HDM consist of a set of modules, where some models
extend the functionality of others. The error message above
indicates that the extension the user wanted to load, requires the
extension called “name” to be loaded first. This can be achieved by
issuing CREATE EXTENSION <name>; first.
4.2.1.1. Solving ‘required extension “name” is not installed’¶
db=# create extension snomedctvocab_20140131;
ERROR: required extension "hl7" is not installed
db=# create extension hl7;
ERROR: required extension "hl7basetable" is not installed
db=# create extension hl7basetable;
CREATE EXTENSION
db=# create extension hl7;
ERROR: required extension "ucum" is not installed
db=# create extension ucum;
CREATE EXTENSION
db=# create extension snomedctvocab_20140131;
ERROR: required extension "hl7" is not installed
db=# create extension hl7;
CREATE EXTENSION
db=# create extension snomedctvocab_20140131;
CREATE EXTENSION
4.2.2. ERROR: type “<name>” does not exist¶
When this error is thrown, even when it is sure that the appropriate
extensions are loaded (see
How do I view which healthcare modules and vocabularies are loaded?), it probably means
that the search_path does not contain the
schemas hl7, hdl
and r1 (or r2). This can be solved by setting the
search_path in the current session:
lake=# select 'OBS'::cv('ActClass');
ERROR: type "cv" does not exist
LINE 1: select 'OBS'::cv('ActClass');
^
lake=# set search_path=public,hl7,hdl,r1,"$user";
SET
lake=# select 'OBS'::cv('ActClass');
cv
------------------------------------------------------------------------------
OBS:2.16.840.1.113883.5.6@2010-11-10:2.16.840.1.113883.1.11.11527@2010-11-10
(1 row)
To persist the search_path change across sessions, use
the ALTER DATABASE command:
4.2.2.1. Persist the search_path setting across sessions¶
ALTER DATABASE <dbname> SET search_path=public,hl7,hdl,r1,"$user";
4.2.3. ERROR: unacceptable schema name “hdl”¶
The hdl schema is setup by
the hl7basetable module. It is possible this
error is thrown, instead of the more informative error that the
required extension hl7basetable is not
loaded. Refer to How do I view which healthcare modules and vocabularies are loaded? to view which extensions are loaded. The solution is to load the
extension hl7basetable first, and then retry
loading the desired module.
4.2.4. ERROR: could not find oid <some oid>¶
The CV datatype depends on vocabulary contents in the hl7 base
tables. This error indicates that the oid was not found in the
vocabulary base tables, and should be added. When a vocabulary is
not available as extension, or the complete extent of the vocabulary
is not known, the oid of the codesystem can be added as an opaque
oid. The oid is called opaque since functions operating on the CV
datatype will have no knowledge of the contents of the codesystem,
nor the isa hierarchy. Hence for opaque oids, functions such
as implies and displayname do
not work or provide limited results.
lake=# set hdl.concept_input_mode to enforcing;
SET
lake=# select '409586006:1.2.3.4'::cv;
ERROR: could not find oid 1.2.3.4
LINE 1: select '409586006:1.2.3.4'::cv;
^
HINT: If the oid is correct, either load the appropriate extension, or use add_opaque_oid() to add the oid.
lake=# select add_opaque_oid('1.2.3.4');
add_opaque_oid
----------------
30001
(1 row)
For the effects of the opaque oid to be visible to CV, it is neccessary to create a new session to the database.
lake=# \c
You are now connected to database "lake" as user "hcuser".
lake=# set hdl.concept_input_mode to enforcing;
SET
lake=# select '409586006:1.2.3.4'::cv;
cv
-------------------
409586006:1.2.3.4
(1 row)
Note that in this example, a non-standard oid 1.2.3.4 was added as an opaque oid. It is not advised
to add standard oids such as the oid for SNOMED-CT with add_opaque_oid, because this will
prevent actually loading the vocabulary extension with the following error:
create extension snomedctvocab_20110731;
ERROR: duplicate key value violates unique constraint "pg_oid_oid_index"
DETAIL: Key (oioid)=(2.16.840.1.113883.6.96) already exists.
4.2.5. ERROR: could not find contextbinding for conceptdomain <name> (internal id <nr>)¶
This error is thrown when a CV value is instantiated that uses the
conceptdomain <name>, which exists in the base
table hdl.pg_conceptdomain, but a binding with a
valueset was not found in the base
table hdl.pg_cbinding. This is an error in the
vocabulary extension and should be fixed by the maintainer.
4.2.6. WARNING: code <code> not found in valueset(s) bound (no exceptions) to conceptdomain <name>¶
4.2.7. WARNING: unknown code <code> for codeSystem <oid> (<name>)¶
These warnings are thrown when hdl.concept_input_mode
is in the (default) permissive mode, and indicate that for a
codesystem that is loaded as vocabulary module, a code that does not
exist in the conceptdomain or codesystem, respectively, was not
found.
The hdl.concept_input_mode can be changed to give
ERRORs instead of WARNINGs with the following SET command:
lake=# set hdl.concept_input_mode to enforcing;
SET
lake=# select 'EV'::cv('ActMood');
ERROR: code 'EV' not found in valueset(s) bound (no exceptions) to conceptdomain ActMood
HINT: Set hdl.concept_input_mode to permissive or enforcing to get a warning or error for unknown codes.
lake=# set hdl.concept_input_mode to permissive;
SET
lake=# select 'EV'::cv('ActMood');
WARNING: code 'EV' not found in valueset(s) bound (no exceptions) to conceptdomain ActMood
HINT: Set hdl.concept_input_mode to permissive or enforcing to get a warning or error for unknown codes.
cv
--------------------------------------------------------------------------------
EV:2.16.840.1.113883.5.1001@2010-11-10:2.16.840.1.113883.1.11.10196@2010-11-10
(1 row)
The hdl.concept_input_mode is related to the binding
strength (CWE / CNE), as they both alter behavior when codes are not
found in a codesystem. The difference
between concept_input_mode and CWE, is that the binding
strength CWE is a setting in the source data, indicating that it is
valid to have a code that is not part of the valuesets bound to that
conceptdomain, and concept_input_mode does not change
the fact that there is a problem with the source data, but only
switches between raising an error or a warning:
select 'EV'::cv('ActMood','CWE');
cv
--------------------------------------------------------------------------------
EV:2.16.840.1.113883.5.1001@2010-11-10:2.16.840.1.113883.1.11.10196@2010-11-10
The option to turn errors into warnings with
the concept_input_mode is for development and staging
purposes only, to allow processing to continue with incomplete data.
4.2.8. ERROR: unknown input syntax for uuid: “b5c6a04b-2bf4-d194-8336-63abf83190eb1”¶
This error means that the string presented as uuid could not be parsed as an uuid. In this particular case, the uuid string has one digit too many in the last group.
4.2.9. ERROR: could not parse month¶
LINE 1: ...low := ivxb_tsinval(inclusive := 'true', value := '20903003'...
^
This error means that the string presented as date could not be parsed. In this case, the month named by the literal ‘30’ could not be parsed.
4.2.10. AttributeError: nsmap¶
python convert_xx.py some.xml
Traceback (most recent call last):
File "convert_xx.py", line 20, in module
root = parser.parse(sys.argv[1])
...
File "xx_parser.py"
, line 256, in find_attr_value_
namespace = node.nsmap.get(prefix)
AttributeError: nsmap
The cause of this error is that python lxml package is not
installed. On both CentOS and Ubuntu, this package is
called python-lxml.
4.2.11. Error: Package: mgridhdl3_94-3.0 Requires: postgresql94-server¶
--> Finished Dependency Resolution
Error: Package: mgridhdl3_94-3.0-449.x86_64 (mgrid_mgrid3)
Requires: postgresql94-server
You could try using --skip-broken to work around the problem
You could try running: rpm -Va --nofiles --nodigest
This error during installation of mgridhdl3 means that no repository contains the required package
postgresql94-server. Consult section Adding the PostgreSQL repository for more information.