Classes and installation instructions have been adapted for IRIS for Health 2020.4 and 2021.1.
Implementation of FHIR Terminology Service specification to expose arbitrary persistent classes as FHIR value sets and code systems. Runs on InterSystems IRIS for Health 2020+.
The following list outlines installation and basic testing steps:
Clone/git pull the repo into any local directory, e.g.:
$ git clone https://github.com/intersystems-ru/fhir-terminology-service.git
Install IRIS for Health 2020.1 or newer.
Set up a new namespace using System Administration
> Configuration
> System Configuration
> Namespaces
menu of the Portal, or by running the command do ##class(HS.HC.Util.Installer).InstallFoundation("<name for the new namespace>")
in HSLIB namespace. Then import classes from src/cls and samples/cls folders of intersystems-ru/fhir-terminology-service GitHub repository.
Depending on the version of InterSystems IRIS for Health, either create a custom FHIR metadata set (2020.1-2020.3), or import FHIR metadata package (2020.4+) with custom search parameters. This step is a workaround needed for $expand
and $validate-code
operations to support HTTP GET requests.
3.1. InterSystems IRIS for Health 2020.1-2020.3: create custom FHIR metadata set based on R4 set with additional search parameters defined in dummy-search-parameters.json. This can be done either by using ##class(HS.FHIRServer.ConsoleSetup).Setup()
interactive utility or by running the command:
do ##class(HS.FHIRServer.Installer).InstallMetadataSet("<metadataSetKey>", "<metadata set description>", "HL7v40", $lb("<directory with dummy-search-parameters.json>"), 1)
<installation directory>/dev/fhir/fhir-metadata
directory.3.2. InterSystems IRIS for Health 2020.4+: import FHIR metadata package from package directory. This can be done either by using ##class(HS.FHIRServer.ConsoleSetup).Setup()
interactive utility, or via the Management Portal or by running the command:
do ##class(HS.FHIRMeta.Load.NpmLoader).importPackages("<local git directory>/fhir-terminology-service/src/fhir-search-parameters/package")
Create a new FHIR endpoint based on Sample.iscru.fhir.fts.SimpleStrategy class. Depending on the version of InterSystems IRIS for Health, either add imported metadata package to the endpoint (2020.4+), or use new metadata set when creating the endpoint (2020.1-2020.3). This can be achieved either by using the interactive utility or by running the following command.
4.1. InterSystems IRIS for Health 2020.1-2020.3
do ##class(HS.FHIRServer.Installer).InstallInstance("<web app URI, e.g. /csp/terminology>", "Sample.iscru.fhir.fts.SimpleStrategy", "<metadataSetKey>")
4.2. InterSystems IRIS for Health 2020.4+
do ##class(HS.FHIRServer.Installer).InstallInstance("<web app URI, e.g. /csp/terminology>", "Sample.iscru.fhir.fts.SimpleStrategy", $lb("fhir.dummy-search-params@1"))
In 2020.4+ you can also create the endpoint using Management Portal.
Allow unauthenticated access to the new endpoint: use the interactive utility or run the following commands:
set strategy = ##class(HS.FHIRServer.API.InteractionsStrategy).GetStrategyForEndpoint("<web app URI>")
set config = strategy.GetServiceConfigData()
set config.DebugMode = 4
do strategy.SaveServiceConfigData(config)
Populate Sample.iscru.fhir.fts.model.CodeTable:
do ##class(Sample.iscru.fhir.fts.model.CodeTable).Populate(10)
Import fhir-terminology-service.postman_collection.json file into Postman, adjust url
variable defined within the collection, and test the service against Sample.iscru.fhir.fts.model.CodeTable
which is a simple persistent class.
Currently the only supported search parameter for both CodeSystem and ValueSet is url
.
Both HTTP GET and HTTP POST methods are supported for the four operations listed above.
The table below lists some of the possible HTTP GET requests against Sample.iscru.fhir.fts.model.CodeTable class.
URI (to be prepended with http://<server>:<port><web app URI> ) |
Description |
---|---|
/metadata | Get endpoint's Capability Statement resource. |
/CodeSystem/Sample.iscru.fhir.fts.model.CodeTable | Read CodeSystem resource corresponding to Sample.iscru.fhir.fts.model.CodeTable class. |
/ValueSet/Sample.iscru.fhir.fts.model.CodeTable | Read ValueSet resource corresponding to Sample.iscru.fhir.fts.model.CodeTable class. |
/CodeSystem?url=urn:CodeSystem:CodeTable | Search CodeSystem resource by url. |
/CodeSystem | Output all avaliable CodeSystem resources. |
/ValueSet?url=urn:ValueSet:CodeTable | Search ValueSet resource by url. |
/ValueSet | Output all avaliable ValueSet resources. |
/CodeSystem/$lookup?system=urn:CodeSystem:CodeTable&code=TEST | Given system and code, get all the details about the concept. |
/ValueSet/$expand?url=urn:ValueSet:CodeTable | Expand the ValueSet. |
/CodeSystem/Sample.iscru.fhir.fts.model.CodeTable/$validate-code?code=TEST | Validate that a code is in the code system. |
In order to expose your own persistent classes as FHIR code systems/value sets, you would need to create your custom InteractionsStrategy class by subclassing iscru.fhir.fts.FTSStrategy. Additionally, for IRIS 2020.4 and newer, a custom RepoManager class has to be created.
One class parameter and at least three methods must be overridden by your custom InteractionsStrategy class:
StrategyKey
class parameter should be assigned some unique value. Name of the current class seems to be a good option.getCodeTablePackage()
class method should return package name for a given code system (or value set) identified by its canonical URL. Typically all terminology classes belong to one package, so this method would usually return one and the same package name regardless of argument values.getCodePropertyName()
and getDisplayPropertyName()
class methods should return names of class properties that correspond to code
and display
concept elements. Different classes may have different properties mapped to terminology code/display elements.Other methods and parameters of iscru.fhir.fts.FTSStrategy that you might find appropriate to override are as follows:
listCodeTableClasses()
class method needs to be overridden in order to support search requests that result in returning all available code systems (or value sets). This method is supposed to return a list of class names of all available terminology classes. Sample.iscru.fhir.fts.SimpleStrategy contains the following basic implementation of this method:
/// Returns a list of all available code table classes.
ClassMethod listCodeTableClasses() As %List
{
#dim sql As %String = "SELECT name FROM %Dictionary.ClassDefinition WHERE name LIKE '" _ ..#codeTablePACKAGE _ ".%' ORDER BY name"
#dim resultSet As %SQL.StatementResult = ##class(%SQL.Statement).%ExecDirect(, sql)
if (resultSet.%SQLCODE '= 0) && (resultSet.%SQLCODE '= 100) $$$ThrowStatus($$$ERROR($$$SQLError, resultSet.%SQLCODE, resultSet.%Message))
#dim return As %List = ""
while resultSet.%Next()
{
set return = return _ $lb(resultSet.name)
}
quit return
}
isExcludedProperty()
class method has to be overridden if any particular properties of your persistent classes should not show up in CodeSystem resources. By default, this method filters Collection
, Identity
, Internal
, MultiDimensional
and Private
properties out. Note that object reference and stream properties are currently not supported and ignored by the framework.
codeSystemUrlPREFIX
and valueSetUrlPREFIX
class parameters and getCodeSystemForClassname()
, getValueSetForClassname()
, determineCodeTableClassname()
and determineCodeSystemForValueSet()
methods control how class names are mapped to canonical URLs and vice versa. By default, the following naming scheme is used for canonical URLs:
CodeSystem | ValueSet |
---|---|
urn:CodeSystem:<short class name> |
urn:ValueSet:<short class name> |
Note that logical id (aka server id) of a CodeSystem/ValueSet resource equals full name of its corresponding class.
Currently lacking is support for versioning of code systems, concept hierarchies and $subsumes
operation, ConceptMap resource and plenty of other stuff. Ideas and pull requests are very welcome!
Classes and installation instructions have been adapted for IRIS for Health 2020.4 and 2021.1.
Updated version in module.xml
Fixed bug with incorrect handling of input parameters when operations were invoked via HTTP POST.
Fixed markdown in application description.
Application description changes.
Community article link has been added to application description.
Initial Release