samply/directory_sync_service

目录同步服务

镜像概述和主要用途

运行在生物样本库站点的目录同步服务，用于保持BBMRI Directory与样本库中的样本数量等信息同步，同时从Directory更新本地FHIR存储中的联系详情等信息。若运行Bridgehead，目录同步已预装，无需单独部署（详见https://github.com/samply/bridgehead?tab=readme-ov-file#directory-sync-tool%EF%BC%89%E3%80%82

该服务需访问包含患者、样本信息及生物样本库详情的FHIR存储，数据需符合GBA profile。若运行https://github.com/samply/bridgehead%EF%BC%8C%E5%88%99%E5%B7%B2%E5%8C%85%E5%90%AB%E5%9F%BA%E4%BA%8Ehttps://github.com/samply/blaze%E7%9A%84%E5%90%88%E9%80%82FHIR%E5%AD%98%E5%82%A8%E3%80%82

服务支持通过Quartz以cron语法定时启动同步，若无cron配置，则仅运行一次。需提供Directory的URL、用户名、密码及本地FHIR存储的URL。

核心功能和特性

• 双向数据同步：将样本库的样本数量等信息同步至BBMRI Directory，同时从Directory更新本地FHIR存储的联系详情
• 定时同步机制：支持cron语法配置同步间隔，无配置时仅执行一次
• 集合处理策略：可通过Specimen资源扩展指定集合ID，或设置默认集合ID（适用于未分配集合的样本）
• 失败重试机制：可配置最大重试次数和重试间隔，应对FHIR存储启动延迟等场景
• 元数据导入功能：可从Directory导入生物样本库和集合的元数据
• 模拟运行模式：启用后不实际连接Directory，返回模拟数据便于测试
• 星型模型支持：可配置生成并发送星型模型摘要信息（需数据保护组审核）

使用场景和适用范围

适用于运行生物样本库且需要与BBMRI Directory保持数据同步的站点，特别是未使用Bridgehead（已预装该服务）的场景。需具备符合GBA profile的FHIR存储，用于存储患者、样本及生物样本库信息。

详细使用方法和配置说明

环境变量配置

以下环境变量用于配置服务，建议存储在.env文件中：

注意：

• DS_DIRECTORY_USER_NAME和DS_DIRECTORY_USER_PASS为必填项，需联系Directory管理员获取登录凭证
• 若ETL未为样本分配Directory集合ID，需指定DS_DIRECTORY_DEFAULT_COLLECTION_ID
• 启用DS_DIRECTORY_ALLOW_STAR_MODEL前，建议咨询本地数据保护组
• DS_TIMER_CRON未指定或为-时，服务执行一次后终止
• DS_DIRECTORY_MOCK为'True'时仍需提供登录凭证（但会被忽略）

Docker部署示例

.env文件示例

env
DS_DIRECTORY_URL=https://bbmritestnn.gcc.rug.nl
DS_DIRECTORY_USER_NAME=foo@foomail.com
DS_DIRECTORY_USER_PASS=qwelmqwldmqwklmdLKJNJKNKJN
DS_FHIR_STORE_URL=http://store:8080/fhir

使用docker run运行

bash
docker run --env-file .env samply/directory_sync_service

使用docker-compose运行

仓库中包含示例docker-compose.yml文件，启动命令：

bash
docker-compose up

独立构建和运行（非Docker方式）

前提条件

• 运行环境：Linux
• 安装依赖：git、Java 19、Maven
• 克隆仓库并进入目录

构建

bash
mvn clean install

运行

设置环境变量后，执行：

bash
java -jar target/directory_sync_service*.jar

测试

单元测试

使用JaCoCo工具测量单元测试覆盖率：

bash
mvn clean verify

测试结果位于：

target/site/jacoco/index.html

用浏览器打开查看，第5列显示行覆盖率（未覆盖行数/总行数，覆盖率计算公式：(总行数-未覆盖行数)/总行数×100%）。

集成测试

ci目录包含集成测试所需文件，用于GitHub CI流水线。手动运行步骤：

1. 进入ci目录
2. 设置数据集环境变量（数据集列表见ci/data/input）
3. 清理并启动测试环境：

bash
cd ci
export DATASET=1patient_1collection
docker volume rm -f store-db-data # 清空Blaze存储
docker-compose up --abort-on-container-exit
docker-compose down
bash compare_test_results_with_reference.sh $DATASET

测试将启动Blaze FHIR存储，加载测试数据，运行目录同步，将结果转储到文件并与ci/data/output中的参考数据比较。

许可证

Copyright 2024 The Samply Community

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.