将普通 ObjectScript 持久化类暴露为 FHIR 代码系统和值集
FHIR 术语服务规范描述了一组对 CodeSystem、ValueSet 和 ConceptMap 资源的操作。 在这些操作中,以下四种操作似乎是最为广泛采用的:
CodeSystem | ValueSet |
---|---|
$lookup $validate-code |
$expand $validate-code |
开发该规范的部分实现一直是探索 IRIS for Health 2020.1 中引入的全新 FHIR 框架的有效途径。 本实现包括上述四种操作,并支持与 CodeSystem 和 ValueSet 资源的读取和搜索交互。
需要注意的是,本实现使用普通 ObjectScript 持久化类作为源术语表。
安装和测试示例策略
下面列出了安装和基本测试步骤:
- 安装 IRIS for Health 2020.1 或更新版本。
- 使用门户的
System Administration
>Configuration
>System Configuration
>Namespaces
菜单或在 HSLIB 命名空间中运行命令do ##class(HS.HC.Util.Installer).InstallFoundation("<name for the new namespace>")
来建立一个新的命名空间。 然后从 intersystems-ru/fhir-terminology-service GitHub 仓库的 src/cls 和 samples/cls 文件夹导入类。 - 基于 R4 数据集以及在 dummy-search-parameters.json 中定义的附加搜索参数,创建一个自定义 FHIR 元数据集。 这可以使用
##class(HS.FHIRServer.ConsoleSetup).Setup()
交互实用工具或运行以下命令来完成:
do ##class(HS.FHIRServer.Installer).InstallMetadataSet("", "", "HL7v40", $lb("<directory with dummy-search-parameters.json>"), 1)
- 为了使
$expand
和$validate-code
操作支持 HTTP GET 请求,此步骤是必需的。 - 请注意,与 InterSystems IRIS 一起打包的 FHIR 元数据集文件位于
<installation directory>/dev/fhir/fhir-metadata
目录中。
- 基于新的元数据集和 Sample.iscru.fhir.fts.SimpleStrategy 类创建一个新的 FHIR 端点。 同样,这可以使用交互实用工具或运行以下命令来实现:
do ##class(HS.FHIRServer.Installer).InstallInstance("<web app URI, e.g. /csp/terminology>", "Sample.iscru.fhir.fts.SimpleStrategy", "")
- 允许对新端点进行未经身份验证的访问:使用交互实用工具或运行以下命令:
set strategy = ##class(HS.FHIRServer.API.InteractionsStrategy).GetStrategyForEndpoint("<web app URI>")
set config = strategy.GetServiceConfigData()
set config.DebugMode = 4
do strategy.SaveServiceConfigData(config)
do ##class(Sample.iscru.fhir.fts.model.CodeTable).Populate(10)
- 将 fhir-terminology-service.postman_collection.json 文件导入到 Postman 中,调整集合内定义的
url
变量,然后针对Sample.iscru.fhir.fts.model.CodeTable
(一个简单的持久化类)测试服务。
支持的 FHIR 交互
目前 CodeSystem 和 ValueSet 都支持的唯一搜索参数是 url
。
上述四种操作均支持 HTTP GET 和 HTTP POST 方法。
下表列出了一些针对 Sample.iscru.fhir.fts.model.CodeTable 类的可能 HTTP GET 请求。
URI (前面加上 http://<server>:<port><web app URI> ) |
描述 |
---|---|
/metadata | 获取端点的能力描述资源。 |
/CodeSystem/Sample.iscru.fhir.fts.model.CodeTable | 读取与 Sample.iscru.fhir.fts.model.CodeTable 类对应的 CodeSystem 资源。 |
/ValueSet/Sample.iscru.fhir.fts.model.CodeTable | 读取与 Sample.iscru.fhir.fts.model.CodeTable 类对应的 ValueSet 资源。 |
/CodeSystem?url=urn:CodeSystem:CodeTable | 通过 url 搜索 CodeSystem 资源。 |
/CodeSystem | 输出所有可用 CodeSystem 资源。 |
/ValueSet?url=urn:ValueSet:CodeTable | 通过 url 搜索 ValueSet 资源。 |
/ValueSet | 输出所有可用 ValueSet 资源。 |
/CodeSystem/$lookup?system=urn:CodeSystem:CodeTable&code=TEST | 在给定系统和代码的情况下,获取有关该概念的所有详细信息。 |
/ValueSet/$expand?url=urn:ValueSet:CodeTable | 展开 ValueSet。 |
/CodeSystem/Sample.iscru.fhir.fts.model.CodeTable/$validate-code?code=TEST | 验证某个代码是否在代码系统中。 |
创建自定义策略
为了将您自己的持久化类公开为 FHIR 代码系统/值集,您需要创建自定义策略类,方法是先将 iscru.fhir.fts.FTSStrategy 子类化,然后基于新的自定义策略创建 FHIR 端点(请参见上面的安装步骤 4)。
您的策略类必须覆盖一个类参数和至少三个方法:
StrategyKey
类参数应该被指定一个唯一值。 当前类的名称似乎是一个好选择。getCodeTablePackage()
类方法应该返回通过规范 URL 标识的给定代码系统(或值集)的包名称。 通常,所有术语类都属于一个包,因此该方法通常会返回一个相同的包名称,不管参数值如何。getCodePropertyName()
和getDisplayPropertyName()
类方法应该返回与code
和display
概念元素对应的类属性的名称。 不同的类可能有不同的属性映射到术语 code/display 元素。
iscru.fhir.fts.FTSStrategy 的其他可能适合覆盖的方法和参数如下:
listCodeTableClasses()
类方法需要覆盖,才能支持以返回所有可用代码系统(或值集)为结果的搜索请求。 此方法应该返回所有可用术语类的类名称列表。 Sample.iscru.fhir.fts.SimpleStrategy 包含此方法的以下基本实现:
/// 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
}
-
如果您的持久化类的任何特定属性都不应出现在 CodeSystem 资源中,则需要覆盖
isExcludedProperty()
类方法。 默认情况下,此方法会过滤掉Collection
、Identity
、Internal
、MultiDimensional
和Private
属性。 需要注意的是,对象引用和流属性当前不受框架支持并被忽略。 -
codeSystemUrlPREFIX
和valueSetUrlPREFIX
类参数以及getCodeSystemForClassname()
、getValueSetForClassname()
、determineCodeTableClassname()
和determineCodeSystemForValueSet()
方法控制类名称与规范 URL 相互映射的方式。 默认情况下,对规范 URL 使用以下命名方案:CodeSystem ValueSet urn:CodeSystem:<short class name>
urn:ValueSet:<short class name>
请注意,CodeSystem/ValueSet 资源的逻辑 id(也就是服务器 id)等于其对应类的全名。
待完成功能
目前缺少的是对代码系统版本管理、概念层次结构和 $subsumes
操作、ConceptMap 资源以及其他许多内容的支持。 欢迎发表意见和拉取请求!