# 4. Frequently Asked Questions and Troubleshooting¶

### 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
------------------------+---------+------------+------------------------------------------------------------
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');
^


### 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.
----------------
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"


### 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.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.