{"id":23698165,"url":"https://github.com/samply/directory_sync_service","last_synced_at":"2026-03-06T18:13:57.626Z","repository":{"id":64985436,"uuid":"577801149","full_name":"samply/directory_sync_service","owner":"samply","description":"Standalone component that synchronizes biobank and collection information from a FHIR store to a Molgenis Directory instance.","archived":false,"fork":false,"pushed_at":"2026-03-03T08:14:58.000Z","size":55277,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-03-03T11:50:19.322Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samply.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-12-13T14:57:26.000Z","updated_at":"2026-03-03T08:14:48.000Z","dependencies_parsed_at":"2025-05-22T16:32:23.701Z","dependency_job_id":"6a461e75-22e0-4d67-b50e-de702f1629b1","html_url":"https://github.com/samply/directory_sync_service","commit_stats":null,"previous_names":[],"tags_count":76,"template":false,"template_full_name":null,"purl":"pkg:github/samply/directory_sync_service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samply%2Fdirectory_sync_service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samply%2Fdirectory_sync_service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samply%2Fdirectory_sync_service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samply%2Fdirectory_sync_service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samply","download_url":"https://codeload.github.com/samply/directory_sync_service/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samply%2Fdirectory_sync_service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30189743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T17:33:53.563Z","status":"ssl_error","status_checked_at":"2026-03-06T17:33:51.678Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-30T07:14:04.944Z","updated_at":"2026-03-06T18:13:57.600Z","avatar_url":"https://github.com/samply.png","language":"Java","readme":"# Directory sync service\n\nRuns a Directory sync service at a biobank site.\n\nThis service keeps the [BBMRI Directory](https://directory.bbmri-eric.eu/) up to date with the number of samples, etc.\nkept in the biobank. It also updates the local FHIR store with the latest contact\ndetails etc. from the Directory.\n\nIf you are running a Bridgehead, Directory sync already comes prepackaged, allowing you to skip the following sections. See\n[directory-sync-tool](https://github.com/samply/bridgehead?tab=readme-ov-file#directory-sync-tool) for more details.\n\nIt is assumed that you have access to a FHIR store containing information about patients\nand samples, as well as the details of your biobank. The data in this store should conform to\nthe [GBA profile](https://simplifier.net/bbmri.de/~resources?category=Profile).\n\nIf you are running a [Bridgehead](https://github.com/samply/bridgehead), then\nyou will already have a suitable store, running under [Blaze](https://github.com/samply/blaze).\n\nThe service is able to use Quartz to start synchronization at regular intervals. These are specified\nusing cron syntax. If no cron information is supplied, Directory sync will only be run once.\n\nYou need to provide URL, user and password for the Directory.\n\nAdditionally, you will need to supply a URL for the local FHIR store.\n\nSee below for ways to get these parameters to the application.\n\n## Collections\n\nIt is generally advised that you assign collections to all Specimens. This is best achieved\nusing an extension to the Specimen resource, which contains a reference to a collection,\nsee the FHIR profile. The IDs of these collections\nwill be passed on to the Directory during synchronization.\n\nHowever, for some biobanks\nit may not be feasible to assign individual specimens to a collection. A fallback\nsolution is available in this case: the default collection ID. This is a single ID\nthat will be assigned to all specimens without collection references. There are two possible\nways to specify this ID: either as environment variable (see DS_DIRECTORY_DEFAULT_COLLECTION_ID\nin the table below) or as an orphan collection in FHIR that has no references from\nany specimens but whose identifier is a collection ID. \n\n## Usage with Docker\n\nWe recommend using Docker for running Directory sync.\n\nFirst, you will need to set up the environment variables for this:\n\n| Variable                           | Purpose                                                                                                                                                              | Default if not specified               |\n|:-----------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------|\n| DS_DIRECTORY_URL                   | Base URL of the Directory                                                                                                                                            | https://directory-backend.molgenis.net |\n| DS_DIRECTORY_USER_NAME             | User name for logging in to Directory                                                                                                                                |                                        |\n| DS_DIRECTORY_USER_PASS             | Password for logging in to Directory                                                                                                                                 |                                        |\n| DS_DIRECTORY_DEFAULT_COLLECTION_ID | ID of collection to be used if not in samples                                                                                                                        |                                        |\n| DS_DIRECTORY_MIN_DONORS            | Minimum number of donors per star model hypercube                                                                                                                    | 10                                     |\n| DS_DIRECTORY_MAX_FACTS             | Max number of star model hypercubes to be generated                                                                                                                  |                                        |\n| DS_DIRECTORY_ALLOW_STAR_MODEL      | Set to 'True' to send star model info to Directory                                                                                                                   | False                                  |\n| DS_DIRECTORY_MOCK                  | Set to 'True' mock a Directory. In this mode, directory-sync will not contact the Directory. All Directory-related methods will simply return plausible fake values. | False                                  |\n| DS_DIRECTORY_ONLY_LOGIN            | Set to 'True' to log in to the Directory, without carrying out any further actions.                                                                                  | False                                  |\n| DS_FHIR_STORE_URL                  | URL for FHIR store                                                                                                                                                   | http://bridgehead-bbmri-blaze:8080     |\n| DS_TIMER_CRON                      | Execution interval for Directory sync, cron format                                                                                                                   |                                        |\n| DS_RETRY_MAX                       | Maximum number of retries when sync fails                                                                                                                            | 10                                     |\n| DS_RETRY_INTERVAL                  | Interval between retries (seconds)                                                                                                                                   | 20 seconds                             |\n| DS_IMPORT_BIOBANKS                 | Set to 'True' to import biobank metadata from Directory                                                                                                              | False                                  |\n| DS_IMPORT_COLLECTIONS              | Set to 'True' to import collection metadata from Directory                                                                                                           | False                                  |\n\nDS_DIRECTORY_USER_NAME and DS_DIRECTORY_USER_PASS are mandatory. If you do not specify these,\nDirectory sync will not run. Contact [Directory admin](directory@helpdesk.bbmri-eric.eu) to get login credentials.\n\nDS_DIRECTORY_DEFAULT_COLLECTION_ID is not mandatory, but you will need to specify it if your ETL does not assign Directory collection IDs to specimens.\n\nIf you set DS_DIRECTORY_ALLOW_STAR_MODEL to 'True', then the star model summary information\nfor your data will be generated and sent to the Directory. You are advised to talk to\nyour local data protection group before doing this.\n\nIf DS_TIMER_CRON is not specified at all, or if it has the value ```-```, then Directory sync will be executed just once, after which the\nprocess will terminate.\n\nThe DS_RETRY\\_ variables specify how Directory sync reacts to failure. RETRY_MAX should\nbe greater than zero. A typical case where retries may be necessary is when\nyou simultaneously start Directroy sync and FHIR store. It takes some time\nfor a FHIR store to start, whereas Directory sync starts immediately, so\nDirectory sync needs to have a way to poll the store until is ready.\n\nIf DS_DIRECTORY_MOCK is set to 'True', the Directory will not be contacted, but you will still need to specify login credentials (which will then be ignored).\n\nBy default, the synchronization with the Directory is one-way, i.e. from your site to the Directory. If you would also like to import metadata from the biobank and collections at the Directory, then you should set the environment variables DS_IMPORT_BIOBANKS and DS_IMPORT_COLLECTIONS to true.\n\nFor your convenience, we recommend that you store these variables in a .env file.\nThe file could look like this:\n\n```\nDS_DIRECTORY_URL=https://bbmritestnn.gcc.rug.nl\nDS_DIRECTORY_USER_NAME=foo@foomail.com\nDS_DIRECTORY_USER_PASS=qwelmqwldmqwklmdLKJNJKNKJN\nDS_FHIR_STORE_URL=http://store:8080/fhir\n```\n\nWith this configuration, the synchronization will be done just once, with the test\nDirectory server. The login details are fake, you will need to replace them with something\nsensible.\n\nTo run from Docker:\n\n```\ndocker run --env-file .env samply/directory_sync_service\n```\n\nAlternatively, you can use docker-compose. An example docker-compose.yml file has been\nincluded in this repository. To start:\n\n```\ndocker-compose up\n```\n\n## Standalone build and run\n\nYou can also build and run this service on your own computer, if Docker is not an option.\n\n### Prerequisites\n\nPlease run from within Linux.\n\nYou will need to install git, Java 19 and Maven. Clone this repository and cd into it.\n\n### Building\n\nFrom the command line, run:\n\n```\nmvn clean install\n```\n\n### Running\n\nYou need to provide the necessary parameters via environment variables, as documented above. These should be set in the same shell as the one that you use to run java.\n\nOnce you have done this, you can start the service directly from the command line:\n\n```\njava -jar target/directory_sync_service\\*.jar\n```\n\n## Testing\n\n### Unit tests\n\nThe pom.xml file has been set up so that you can use the [JaCoCo](https://www.eclemma.org/jacoco/) tool for measuring unit test coverage. On the command line, run:\n\n```\nmvn clean verify\n```\n\nOnce this has completed successfully, you can find the results in:\n\n```\ntarget/site/jacoco/index.html\n```\n\nThe best way to view this file it to open it in a browser.\n\nColumn 5 shows coverage in lines, which is more or less the standard measure for coverage. The first number of column 5 in the last row of\nthe table shows the number of lines *not* covered (missed). The second number shows the total number of lines. Percentage coverage is (total-missed)*100/total.\n\n### Integration tests\n\nThe directory \"ci\" contains everything needed for integration tests. It is used by a GitHub CI pipeline whenever a new version of Directory sync is released.\n\nYou can run integration tests by hand, if you wish. You will need to set an environment variable to tell the system which data source to use.\nYou can find a full list of data sources in ci/data/input.\nLet's say you would like to run an integration test with a small dataset, so that it completes quickly. Try this:\n\n```\ncd ci\nexport DATASET=1patient_1collection\ndocker volume rm -f store-db-data # start with empty Blaze store\ndocker-compose up --abort-on-container-exit\ndocker-compose down\nbash compare_test_results_with_reference.sh $DATASET\n```\n\nThe test uses docker-compose to start up a FHIR store (Blaze), load it with data, and then run Directory sync. Rather than pushing the results to\na running Directory instance, it dumps them into files. The contents of the generated files are then compared with reference data (located\nin ci/data/output).\n\n## License\n        \nCopyright 2024 The Samply Community\n        \nLicensed 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\n        \nhttp://www.apache.org/licenses/LICENSE-2.0\n        \nUnless 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.\n \n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamply%2Fdirectory_sync_service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamply%2Fdirectory_sync_service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamply%2Fdirectory_sync_service/lists"}