EP HL7 Translator

The EBSCO HL7 translation service converts HL7 requests into queries that our medical databases understand.

Creating EBSCOhost Infobuttons

Infobuttons should call our translation URL using the parameters described below. The base URL is

http://medical.ebscohost.com/HL7Translator/HL7/hl7request/:db

:db is the database to send the translated query to. Supported values are:

dme - DynaMed
dmp - DynaMed Plus
perc - Patient Education Reference Center (PERC)
nrc - Nursing Reference Center (NRC)
nup - Nursing Reference Center Plus (NRCP)
rrc - Rehabilitation Reference Center (RRC)

For example, the base URL to search Dynamed Plus is

http://medical.ebscohost.com/HL7Translator/HL7/hl7request/dmp

Note:

The database can also be specified by the db parameter. Prior to version 3.7 of the HL7 Translator the parameter was the only way to specify the database. The preferred method now is to include in the base URL.

When the database is included in the base URL the db parameter is ignored.

URLs are case-sensitive.

Validation

To verify that the request parameters are valid, we provide a validation tool. To get a report on the request status the only thing that needs to be changed is the base URL to the one below:

http://medical.ebscohost.com/HL7Translator/HL7/validate

Authentication Important

HL7 requests are authenticated by IP only. No credentials are required in the parameters and will be removed if provided.

Supported HL7 Parameters

Main Search Criteria - mainSearchCriteria.v.ot

This specifies the main term to be used in the search.

Note:

Some implementations use the parameter mainSearchCriteria.v.dn instead of mainSearchCriteria.v.ot . We support both and will use either one as the search term but only consider mainSearchCriteria.v.ot if both are present.

Code System - mainSearchCriteria.v.cs

This specifies the code system to be used in the search. If a code system is specified, a value code is required in the Value Code parameter. Supported values are:

ICD-9: 2.16.840.1.113883.6.2
ICD-9-CM Diagnostic: 2.16.840.1.113883.6.103
ICD-9-CM Procedure: 2.16.840.1.113883.6.104
ICD-10: 2.16.840.1.113883.6.3
ICD-10-CM: 2.16.840.1.113883.6.90
ICD-10-PCS: 2.16.840.1.113883.6.4
LOINC: 2.16.840.1.113883.6.1
NDC: 2.16.840.1.113883.6.69
RXNORM: 2.16.840.1.113883.6.88
SNOMED-CT: 2.16.840.1.113883.6.96

Notes:

If a code that has a corresponding associated topic is passed, no other parameters will be used. If there is no mapping for this code, the rest of the parameters will be used to conduct the search.
ICD-9 and ICD-10 searches are disabled in DynaMed. The queries can be passed, but no results will be returned. ICD-9-CM, ICD-10-CD, and ICD-10-PCS codes are functional in all databases.

Multiple Codes

To pass multiple codes on the same search use the HL7 standard for multiple values, appending an index for each additional parameter starting at 1. For example, if the search is for ICD9CM = 001.0 and ICD10CM = A00.1 the parameters would be:

mainSearchCriteria.v.cs=2.16.840.1.113883.6.103
mainSearchCriteria.v.c=001.0
mainSearchCriteria.v.cs1=2.16.840.1.113883.6.90
mainSearchCriteria.v.c1=A00.1

If passing multiple codes for the same code system use the same convention, repeating the code system for each code. For example, to search for ICD9CM 001.0 and 001.1 use:

mainSearchCriteria.v.cs=2.16.840.1.113883.6.103
mainSearchCriteria.v.c=001.0
mainSearchCriteria.v.cs1=2.16.840.1.113883.6.103
mainSearchCriteria.v.c1=001.1

And an example with multiple codes (001.0 and 001.1) for ICD9CM and one code (A00.1) for ICD10CM:

mainSearchCriteria.v.cs=2.16.840.1.113883.6.103
mainSearchCriteria.v.c=001.0
mainSearchCriteria.v.cs1=2.16.840.1.113883.6.103
mainSearchCriteria.v.c1=001.1
mainSearchCriteria.v.cs2=2.16.840.1.113883.6.90
mainSearchCriteria.v.c2=A00.1

Value Code - mainSearchCriteria.v.c

This specifies the value for the code to be searched according to the Code System used.

Age - age.v.v

This specifies the age of the patient and will filter the results accordingly. Our databases are filtered using age groups. However, the HL7 translator works with ages passed as years or months, depending on the Age Unit. If the received value is not a number the request will fail. The mapping is listed below:

Age Group	Age Span	Example Param (age.v.v)
Infant, Newborn	0 to 1 month (0 to 1/12 years)	0.05
Infant	1 to 23 months (1/12 to 23/12 years)	1.5
Child, Preschool	2 to 5 years	1
Child	6 to 12 years	7
Adolescent	13 to 18 years	15
Adult	19 to 44 years	35
Middle Age	45 to 64 years	60
Aged 65+ years	65 to 80 years	70
Aged, 80 and over	80+	90

Age Unit - age.v.u

This specifies the unit of the age passed. If the unit is months, the passed number will be divided by 12.0 to map to the age groups defined above:

a Years
mo Months

Gender - patientPerson.administrativeGenderCode.c

This specifies the gender of the patient and will filter the results accordingly. Supported values are:

F Female
M Male

EBSCOhost Parameters

In addition to HL7 parameters, some additional parameters are required to specify the mode of the search and the type of result desired.

Mode - mode

This specifies what search service to use. Supported values are:

eit - The search is translated and redirected to EIT
prod - The search is translated and redirected to EBSCOhost

Database - db

This specifies what database to use. Supported values are:

dme - DynaMed
dmp - DynaMed Plus
perc - Patient Education Reference Center (PERC)
nrc - Nursing Reference Center (NRC)
nup - Nursing Reference Center Plus (NRCP)
rrc - Rehabilitation Reference Center (RRC)

The preferred method of specifying the database is to include it in the base URL. This parameter should not be used in new Infobutton installations.

Customer ID - custID

If your institution uses a shared IP address, use the CustID field to ensure proper authentication into the appropriate account.

Exact Match - exact

This specifies if the search should return results that match the search query exactly. For example, if the query is: heart attack, an exact search will use the query "heart attack", while a non-exact search will use 'heart OR attack'. The default value is 'true', so if the 'exact' parameter is not passed, the search will use an exact match query.