diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000000000000000000000000000000000000..6622047ff2c485db7c0999fb89d2f1bbe49724e6 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,75 @@ +## Code of Conduct + +### Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +### Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Calls for violence, vilification and advertising +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +### Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +### Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +### Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at OSPO@gematik.de. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +### Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ \ No newline at end of file diff --git a/README.md b/README.md index aa1e56f233943db5e47660b367c33377591a6dc3..8a759de46b5a3efd6ac71f26a824ffc54db9a831 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,37 @@ -# bfarm-package-download +<img align="right" width="250" height="47" src="images/Gematik_Logo_Flag_With_Background.png"/> <br/> + +# zts-api-client-examples -Innerhalb des Repositories wird eine Reihe von Beispiel-Clients und -Konfigurationen bereitgestellt, die den automatiserten Download von FHIR-Packages aus der BfArM Package Registry (https://terminologien.bfram.de/packages/...) demonstrieren: +<details> + <summary>Table of Contents</summary> + <ol> + <li><a href="#about-the-project">About The Project</a></li> + <li><a href="#getting-started">Getting Started</a></li> + <li><a href="#license">License</a></li> + <li><a href="#contact">Contact</a></li> + </ol> +</details> -- **[curl](./curl/README.md)** - Beispiel-Skript für das automatisierte Downloaden von FHIR-Packages über curl. Der Client unterstützt verschiedene Anwendungsszenarien im Kontext des Content-Syndication (z.B. Download der als "latest" getaggten Paketversionen, Download aller Paketversionen) -- **[npm](./npm/README.md)** - Beispielkonfiguration/-anleitung für die Nutzung von npm zum Download von FHIR-Packages. -- **[sushi-wrap](./sushi-wrap/README.md)** - Beispiel-Skript für die Integration mit Sushi +## About The Project +This repository provides a series of example clients and configurations that demonstrate the automated download of FHIR packages from the BfArM Package Registry (https://terminologien.bfarm.de/packages): + +### Release Notes +See [ReleaseNotes.md](./ReleaseNotes.md) for all information regarding the (newest) releases. + +## Getting Started +The following example clients/configurations are currently provided: + +- **[curl](./curl/README.md)** — Example script for the automated download of FHIR packages using curl. The client supports various application scenarios in the context of content syndication (e.g., downloading package versions tagged as "latest", downloading all package versions). +- **[npm](./npm/README.md)** — Example configuration/instructions for using npm to download FHIR packages. +- **[sushi-wrap](./sushi-wrap/README.md)** — Example wrapper script to integrate an automated package download into Sushi workflows. + +For more in-depth documentation, please refer to the referenced README files of the individual tools. + +## License +See [LICENCE.md](./LICENCE.md) for all information regarding licencing. + +## Contact +We take open source license compliance very seriously. We are always striving to achieve compliance at all times and to improve our processes. +This software is currently being tested to ensure its technical quality and legal compliance. Your feedback is highly valued. +If you find any issues or have any suggestions or comments, or if you see any other ways in which we can improve, please reach out to: [https://terminologien.bfarm.de/kontakt.html](https://terminologien.bfarm.de/kontakt.html) + diff --git a/ReleaseNotes.md b/ReleaseNotes.md new file mode 100644 index 0000000000000000000000000000000000000000..2f43f5cbc7bb059889c9e94bc60164d533b07829 --- /dev/null +++ b/ReleaseNotes.md @@ -0,0 +1,10 @@ +<img align="right" width="250" height="47" src="images/Gematik_Logo_Flag_With_Background.png" /> +<br/> + +# Release Notes zts-api-client-examples + +## Release 1.0.0 (2025-03-25) + +### changed + +- initial release with examples for downloading terminology packages using curl, npm and sushi diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000000000000000000000000000000000000..367917e6975a303d88538a6aa52dbab4047647a0 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,6 @@ +# Security Policy + +Since this software is not a productive version, please submit an issue or pull request for any bugs or vulnerabilities you find. + +In case of a responsible disclosure, please follow instructions +on https://www.gematik.de/datensicherheit#c1227. \ No newline at end of file diff --git a/curl/README.md b/curl/README.md index 94130bfc779e1f9cc859f6f38dab77fc2923a2e4..617fabc3b12e33aa8f23911b3135f57b109d6e83 100644 --- a/curl/README.md +++ b/curl/README.md @@ -1,35 +1,51 @@ -# curl-basiertes Download-Skript +<img align="right" width="250" height="47" src="../images/Gematik_Logo_Flag_With_Background.png"/> <br/> + +# curl-based Download Script -## Voraussetzung -Folgende Pakete werden zur Ausführung des Download-Skripts benötigt: +<details> + <summary>Table of Contents</summary> + <ol> + <li><a href="#about-the-project">About The Project</a></li> + <li><a href="#prerequisites">Prerequisites</a></li> + <li><a href="#preliminary-note">Preliminary Note</a></li> + <li><a href="#usage">Usage</a></li> + </ol> +</details> -- **curl** (command line tool and library for transferring data with URLs) - [Website](https://curl.se/) -- **jq** (leightweight and flexible command-line JSON processor) - [Website](https://jqlang.github.io/jq/) +## About The Project +Example script for the automated download of FHIR packages using curl. The client script supports various application scenarios in the context of content syndication (e.g., downloading package versions tagged as "latest", downloading all package versions). -## Vorbemerkung -Die vom ZTS angebotenen Inhalte unterliegen Downloadbedingungen, welche unter [https://terminologien.bfarm.de/download-conditions.html](https://terminologien.bfarm.de/download-conditions.html) eingesehen werden können. Bitte stellen Sie sicher, dass Sie die jeweils geltenden Bedingungen akzeptieren, bevor Sie das angebotenen Skript nutzen. Die Annahme der Bedingungen ist über den Kommandozeilenparameter ```-c``` zu bestätigen. +## Prerequisites +The following packages are required to run the download script: -## Kommandozeilenparameter -Folgende Kommandozeilenparameter werden durch das Tool unterstützt: +- **curl** (command-line tool and library for transferring data with URLs) - [Website](https://curl.se/) +- **jq** (lightweight and flexible command-line JSON processor) - [Website](https://jqlang.github.io/jq/) -- ```-c``` consent to download conditions - valid values: ```true```, ```false``` - default value: ```false``` -- ```-i``` packages to INCLUDE - valid values: ```ALL``` (for all available packages), ```{packagelist}``` (package names separated by ',') - e.g. ```bfarm.terminologien.icd10gm,bfarm.terminologien.ops``` - default: ```ALL``` -- ```-e``` packages to EXCLUDE from download - valid values: ```{packagelist}``` (package names separated by ',') - e.g. ```bfarm.terminologien.loinc,bfarm.terminologien.ucum``` - default: -- ```-l``` download only latest version of the package - valid values: ```true```, ```false``` - default: ```true``` -- ```-o``` output directory (location where downloaded packages will be stored) - e.g. ```./content``` - default: ```./packages``` +## Preliminary Note +The content offered by ZTS is subject to download conditions, which can be viewed at [https://terminologien.bfarm.de/download-conditions.html](https://terminologien.bfarm.de/download-conditions.html). Please ensure that you accept the applicable terms before using the provided script. Acceptance of the terms must be confirmed via the command-line parameter ```-c``` (see below). -## Beispiel-Nutzung -Das hier angebotene Skript ermöglicht die Umsetzung verschiedener Anwendungsfälle in Bezug auf den Download von Terminologiepaketen: +## Usage -**Download der jeweils aktuellen Version eines namentlich bekannten Pakets** +### Command-Line Parameters +The following command-line parameters are supported by the tool: + +- ```-c``` consent to download conditions — valid values: ```true```, ```false``` — default value: ```false``` +- ```-i``` packages to INCLUDE — valid values: ```ALL``` (for all available packages), ```{packagelist}``` (package names separated by ',') — e.g., ```bfarm.terminologien.icd10gm,bfarm.terminologien.ops``` — default: ```ALL``` +- ```-e``` packages to EXCLUDE from download — valid values: ```{packagelist}``` (package names separated by ',') — e.g. ```bfarm.terminologien.loinc,bfarm.terminologien.ucum``` — default: (none) +- ```-l``` download only the latest version of the package — valid values: ```true```, ```false``` — default: ```true``` +- ```-o``` output directory (location where downloaded packages will be stored) — e.g., ```./content``` — default: ```./packages``` + +### Example Usage +The provided script enables various use cases regarding the download of terminology packages: + +**Download the latest version of a specific named package** ```./download.sh -c [true|false] -i bfarm.terminologien.icd10gm -l true -o ./icd10gm``` -**Download ALLER Version eines namentlich bekannten Pakets** +**Download ALL versions of a specific named package** ```./download.sh -c [true|false] -i bfarm.terminologien.ops -l false -o ./ops``` -**Download ALLER Version ALLER vom ZTS verwalteten Pakete** - -```./download.sh -c [true|false] -i ALL -l false -o ./packages``` +**Download ALL versions of ALL packages managed by ZTS** +```./download.sh -c [true|false] -i ALL -l false -o ./packages``` \ No newline at end of file diff --git a/curl/download.sh b/curl/download.sh index 74f885548b63d53d92fff4f68216cd0c576433e5..112202738d5159642179005869ee54ce9b2b1071 100755 --- a/curl/download.sh +++ b/curl/download.sh @@ -1,43 +1,44 @@ #!/bin/bash # ==================================================================================================================================== -# Konfiguration +# Configuration # ==================================================================================================================================== -# Für die Verwendung des Skripts, muss explizit bestätigt werden, dass die jeweils geltenden Downloadbedingungen akzeptiert wurden -# vgl. https://terminologien.bfarm.de/download-conditions.html +# To use the script, you must explicitly confirm that the applicable download conditions have been accepted +# see https://terminologien.bfarm.de/download-conditions.html ACCEPTED_DOWNLOAD_CONDITIONS=false -# Pakete die heruntergeladen werden sollen. Diese können als Komma-separierte Liste angegeben werden. Wird der Wert 'ALL' gesetzt, werden alle Pakete heruntergeladen +# Packages to be downloaded. These can be specified as a comma-separated list. +# If the value 'ALL' is set, all available packages will be downloaded. INCLUDE_PACKAGES=ALL -# Pakete die NICHT heruntergeladen werden sollen. Diese müssen als Komma-separierte Liste angegeben werden +# Packages that should NOT be downloaded. These must be specified as a comma-separated list. EXCLUDE_PACKAGES= -# Beschränken des Downloads auf die als "latest" gekennzeichnete Version +# Limit the download to the version marked as "latest" LATEST_ONLY=true -# Der Wert der im User-Agent-Header gesetzt werden soll +# The value to be set in the User-Agent header USER_AGENT=example-zts-client/1.0 -# Endpunktadressen der ZTS-API +# Endpoint addresses of the ZTS API CATALOG_API_ENDPOINT=https://terminologien.bfarm.de/packages/catalog PACKAGE_API_ENDPOINT=https://terminologien.bfarm.de/packages TOKEN_API_ENDPOINT=https://terminologien.bfarm.de/api/generate-token -# Ausgabeverzeichnis, in welchem heruntergeladenen Paketversionen gespeichert werden +# Output directory where downloaded package versions will be stored OUTPUT_DIR=./packages -# Pfad-/Dateinamen für temporäre Arbeitsdateien +# Path/filenames for temporary working files CATALOG_METADATA_FILE=catalog.json PACKAGE_METADATA_FILE=response.json CURRENT_DIR=$(pwd) # ==================================================================================================================================== -# Hilfsfunktionen +# Helper functions # ==================================================================================================================================== -# Ausgabe der Verwendung des Skripts +# Display usage instructions for the script usage() { echo "$0 -c [true|false] -i [ALL|{packagelist}] -e {packageList} -l [true|false] -o [outputDir]" echo "Command Line Parameters:" @@ -59,10 +60,10 @@ usage() { } # ==================================================================================================================================== -# Verarbeitung der Kommandozeilenparameter (inkl. Validierung) +# Processing of command-line parameters (including validation) # ==================================================================================================================================== -# Kommandozeilenparameter verarbeiten +# Processing of command-line parameters while getopts "c:i:e:l:o:" opt; do case $opt in c) ACCEPTED_DOWNLOAD_CONDITIONS="$OPTARG" ;; @@ -74,110 +75,109 @@ while getopts "c:i:e:l:o:" opt; do esac done -# Prüfen, ob die Downloadbedingungen übernommen wurden +# Check if the download conditions have been accepted if [ "$ACCEPTED_DOWNLOAD_CONDITIONS" != true ]; then echo "Die Downloadbedingungen müssen bestätigt werden" usage fi -# Prüfen, ob die INCLUDE_PACKAGE Wert korrekt ist +# Check if the INCLUDE_PACKAGE value is correct if [[ ! "$INCLUDE_PACKAGES" =~ ^ALL$|^[a-z0-9]+(\.[a-z0-9]+)+(,[a-z0-9]+(\.[a-z0-9]+)+)*$ ]]; then echo "Fehler bei der Angabe der zu inkludierenden Pakete: '$INCLUDE_PACKAGES'" usage fi -# Prüfen, ob der EXCLUDE_PACKAGE Wert korrekt ist +# Check if the EXCLUDE_PACKAGE value is correct if [[ ! "$EXCLUDE_PACKAGES" =~ ^$|^[a-z0-9]+(\.[a-z0-9]+)+(,[a-z0-9]+(\.[a-z0-9]+)+)*$ ]]; then echo "Fehler bei der Angabe der zu exkludierenden Pakete: '$EXCLUDE_PACKAGES'" usage fi -# Prüfen, ob der LATEST_ONLY Wert korrekt ist +# Check if the LATEST_ONLY value is correct # ==================================================================================================================================== -# Vorbereiten der Umgebung +# Preparing the environment # ==================================================================================================================================== -# Anlegen eines (temporären) Ausgabeverzeichnisses +# Create a (temporary) output directory mkdir -p $OUTPUT_DIR # ==================================================================================================================================== -# Abruf der Liste unterstützten Pakete +# Retrieving the list of supported packages # ==================================================================================================================================== -# Catalog API nach Liste der unterstützten Terminologien anfragen - Das Ergebnis wird in eine Datei geschrieben +# Request the Catalog API for a list of supported terminologies — the result will be written to a file echo "Downloading ZTS-Gesamtkatalog" curl --user-agent "{$USER_AGENT}" -X GET "{$CATALOG_API_ENDPOINT}" -H "Accept: application/json" -sS -o $CATALOG_METADATA_FILE -# Iterieren über alle Einträge des Katalogs +# Iterate over all entries in the catalog jq -r '.[].name' $CATALOG_METADATA_FILE | while read name; do - # Nur wenn die INCLUDE und EXCLUDE-Kriterien eingehalten werden, laden wir überhaupt Inhalte herunter + # Only if the INCLUDE and EXCLUDE criteria are met, content will be downloaded if [[ "$INCLUDE_PACKAGES" == *"$name"* || "$INCLUDE_PACKAGES" == "ALL" ]] && [[ ! "$EXCLUDE_PACKAGES" == *"$name"* ]]; then - # Paketmetadaten herunterladen + # Download package metadata curl --user-agent "{$USER_AGENT}" -sS -X GET "{$PACKAGE_API_ENDPOINT}/{$name}" -H "Accept: application/json" -o $PACKAGE_METADATA_FILE - # Downloadbedingungen des Pakets akzeptieren - # Wichtig: Informieren Sie sich vorab über die jeweils gültigen Downloadbedingungen. Dies kann über die Webseite erfolgen. + # Accept the package's download conditions + # Important: Please make sure to review the applicable download conditions in advance. This can be done via the website. DOWNLOAD_TOKEN=$(curl --user-agent "{$USER_AGENT}" -sS -X POST -H "Content-Type: application/json" -d "{\"packages\":[\"$name\"]}" $TOKEN_API_ENDPOINT | jq -r '.token') if [[ "$LATEST_ONLY" == true ]]; then - # Wir laden nur die als 'latest' gekennzeichnete Version des Pakets herunter + # We only download the version of the package marked as 'latest' - # latest version mit "jq" aus Datei extrahieren + # Extract the latest version from the file using "jq" PACKAGE_VERSION_LATEST=$(jq -r '."dist-tags".latest' $PACKAGE_METADATA_FILE) - # Wechsel ins Ausgabeverzeichnis + # Change to the output directory cd $OUTPUT_DIR - # Erwarteten Dateinamen berechnen + # Calculate the expected filename EXPECTED_FILE_NAME="$name-$PACKAGE_VERSION_LATEST.tar.gz" - # Paketversionen werden nur heruntergeladen, wenn es sie noch nicht gibt + # Package versions are only downloaded if they do not already exist if [ -f $EXPECTED_FILE_NAME ]; then echo "$EXPECTED_FILE_NAME existiert bereits. Es wird kein erneuter Download dieser Paketversion durchgeführt." else - # Latest Paketversion herunterladen (und Dateinamen aus Content-Disposition Header übernehmen) + # Download the latest package version (and take the filename from the Content-Disposition header) echo "Downloading $name#$PACKAGE_VERSION_LATEST" curl --user-agent "{$USER_AGENT}" -X GET "{$PACKAGE_API_ENDPOINT}/{$name}/{$PACKAGE_VERSION_LATEST}" -H "Authorization: Bearer $DOWNLOAD_TOKEN" -sS -O --remote-header-name fi - # Wechsel ins ursprüngliches Arbeitsverzeichnis + # Change back to the original working directory cd $CURRENT_DIR else - # Wir laden alle vorhandenen Versionen des Pakets herunter + # We download all available versions of the package jq -r '.versions | keys[]' $PACKAGE_METADATA_FILE | while read version; do - # Wechsel ins Ausgabeverzeichnis + # Change to the output directory cd $OUTPUT_DIR - # Erwarteten Dateinamen berechnen + # Calculate the expected filename EXPECTED_FILE_NAME="$name-$version.tar.gz" - # Paketversionen werden nur heruntergeladen, wenn es sie noch nicht gibt + # Package versions are only downloaded if they do not already exist if [ -f $EXPECTED_FILE_NAME ]; then echo "$EXPECTED_FILE_NAME existiert bereits. Es wird kein erneuter Download dieser Paketversion durchgeführt." else - # Latest Paketversion herunterladen (und Dateinamen aus Content-Disposition Header übernehmen) + # Download the package version (and take the filename from the Content-Disposition header) echo "Downloading $name#$version" curl --user-agent "{$USER_AGENT}" -X GET "{$PACKAGE_API_ENDPOINT}/{$name}/{$version}" -H "Authorization: Bearer $DOWNLOAD_TOKEN" -sS -O --remote-header-name fi - # Wechsel ins ursprüngliches Arbeitsverzeichnis + # Change back to the original working directory cd $CURRENT_DIR done fi - # Heruntergeladene Metadaten des Pakets löschen + # Delete the downloaded metadata of the package rm $PACKAGE_METADATA_FILE fi done -# Heruntergeladenen Katalog löschen +# Delete the downloaded metadata of the package rm $CATALOG_METADATA_FILE - diff --git a/images/Gematik_Logo_Flag_With_Background.png b/images/Gematik_Logo_Flag_With_Background.png new file mode 100644 index 0000000000000000000000000000000000000000..a3c929317c0f07ee752cafac1567e547b77c961c Binary files /dev/null and b/images/Gematik_Logo_Flag_With_Background.png differ diff --git a/npm/README.md b/npm/README.md index 2b56439b2a5ec86cbf8cd30e07d2542a10194f1c..c1633d156874a0649d14da19e4ec1b369bdc77f4 100644 --- a/npm/README.md +++ b/npm/README.md @@ -1,26 +1,41 @@ +<img align="right" width="250" height="47" src="../images/Gematik_Logo_Flag_With_Background.png"/> <br/> + # npm -## Voraussetzung +<details> + <summary>Table of Contents</summary> + <ol> + <li><a href="#about-the-project">About The Project</a></li> + <li><a href="#prerequisites">Prerequisites</a></li> + <li><a href="#preliminary-note">Preliminary Note</a></li> + <li><a href="#usage">Usage</a></li> + </ol> +</details> -Folgende Pakete werden zur Ausführung des Skripts benötigt: +## About The Project +Example configuration/instructions for using npm to download and extract FHIR packages. + +## Prerequisites +The following packages are required to run the script: - **npm** (node package manager) - [Website](https://www.npmjs.com/) -- **curl** (command line tool and library for transferring data with URLs) - [Website](https://curl.se/) -- **jq** (leightweight and flexible command-line JSON processor) - [Website](https://jqlang.github.io/jq/) +- **curl** (command-line tool and library for transferring data with URLs) - [Website](https://curl.se/) +- **jq** (lightweight and flexible command-line JSON processor) - [Website](https://jqlang.github.io/jq/) -## Vorbemerkung -Die vom ZTS angebotenen Inhalte unterliegen Downloadbedingungen, welche unter [https://terminologien.bfarm.de/download-conditions.html](https://terminologien.bfarm.de/download-conditions.html) eingesehen werden können. Bitte stellen Sie sicher, dass Sie die jeweils geltenden Bedingungen akzeptieren, bevor Sie das angebotenen Skript nutzen. Technisch wird das Akzeptieren der Downloadbedingungen durch die Verwendung eines Access Tokens zum Ausdruck gebracht, welches in der NPM-Konfigurationsdatei `.npmrc` hinterlegt werden kann. +## Preliminary Note +The content offered by ZTS is subject to download conditions, which can be viewed at [https://terminologien.bfarm.de/download-conditions.html](https://terminologien.bfarm.de/download-conditions.html). Please ensure that you accept the applicable terms before using the provided script. Technically, acceptance of the download conditions is expressed by using an access token, which can be stored in the NPM configuration file `.npmrc`. -## Erstellen der ```npm``` Konfiguration -Voraussetzung für die Verwendung von ```npm``` ist das Erstellen einer passenden Konfigurationsdatei, die u.a. die für den Zugriff auf die Registry erforderlichen Credentials (in Form eines Download Token) beinhaltet. Die Erstellung einer Konfigurationsdatei kann dabei sehr einfach über das beigefügte Skript ```create_npm_config.sh``` erfolgen. +## Usage +### Creating the ```npm``` Configuration +To use ```npm```, a suitable configuration file must be created, which includes, among other things, the credentials required for accessing the registry (in the form of a download token). Creating a configuration file can be done easily with the provided script ```create_npm_config.sh```. -Bevor das Skript gestartet werden kann, sind Anpassungen an dessen Inhalt erforderlich. Hierzu müssen in der Konfigurationsvariable ```ACCEPTED_DOWNLOAD_CONDITIONS``` alle Pakete aufgeführt werden, für die der Nutzer die Downloadbedingungen (s.o.) akzeptiert. +Before running the script, adjustments are required. The configuration variable ```ACCEPTED_DOWNLOAD_CONDITIONS``` must list all packages for which the user has accepted the download conditions (see above). -Über ```./create_npm_config.sh``` kann das Skript gestartet werden. Für die hinterlegten Pakete wird nun ein Download Token erzeugt und mit einer Vorlagendatei (```.npmrc.template```) kombiniert. +The script can be started using ```./create_npm_config.sh```. A download token will then be generated for the listed packages and combined with a template file (```.npmrc.template```). -## Download von Paketen über ```npm``` -Über folgendes Kommando kann der Download eines bestimmten Pakets (hier ICD-10-GM in der aktuellen Version) über ```npm```angestoßen werden: +### Downloading Packages via ```npm``` +The download of a specific package (e.g., ICD-10-GM in its current version) can be initiated using the following command: ```npm --registry https://terminologien.bfarm.de/packages install bfarm.terminologien.icd10gm --userconfig ./.npmrc --prefix ./.packages``` -Im Ergebnis wird ein Verzeichnis ```.packages```angelegt in welchem das entpackte FHIR-Package in der 'latest'-Version zu finden ist. \ No newline at end of file +As a result, a directory named ```.packages``` will be created, where the unpacked FHIR package in its 'latest' version can be found. diff --git a/npm/create_npm_config.sh b/npm/create_npm_config.sh index b66424dc0c36b1cb2556ef97de39efb83d9fa0f5..e8b6887a8b2652ab951df42a46f182ad8b597939 100755 --- a/npm/create_npm_config.sh +++ b/npm/create_npm_config.sh @@ -1,42 +1,42 @@ #!/bin/bash # ==================================================================================================================================== -# Konfiguration +# Configuration # ==================================================================================================================================== -# Liste der akzeptierten Downloadbedingungen, e.g. 'bfarm.terminologien.abc,bfarm.terminologien.xyz' -# Die Liste der akzeptierten Downloadbedingungen kann über die Webseite (https://terminologien.bfarm.de) eingesehen werden. +# List of accepted download conditions, e.g. 'bfarm.terminologien.abc,bfarm.terminologien.xyz' +# The list of accepted download conditions can be viewed on the website (https://terminologien.bfarm.de). ACCEPTED_DOWNLOAD_CONDITIONS=bfarm.terminologien.abc,bfarm.terminologien.xyz -# Der Endpunkt der Token-API +# The endpoint of the token API TOKEN_API_ENDPOINT=https://terminologien.bfarm.de/api/generate-token -# Der Wert der im User-Agent-Header gesetzt werden soll +# The value to be set in the User-Agent header USER_AGENT=example-zts-client/1.0 # ==================================================================================================================================== -# Struktur für Request an TOKEN_API_ENDPOINT generieren +# Generate structure for the request to TOKEN_API_ENDPOINT # ==================================================================================================================================== -# Iterieren über die Liste der gemäß Konfiguration akzeptierten Downloadbedingungen +# Iterate over the list of accepted download conditions as defined in the configuration IFS=',' read -ra items <<< "$ACCEPTED_DOWNLOAD_CONDITIONS" PACKAGE_ARRAY="[" for item in "${items[@]}"; do PACKAGE_ARRAY+="\"$item\"," done -# Letztes Komma entfernen und Array schließen +# Remove the trailing comma and close the array PACKAGE_ARRAY="${PACKAGE_ARRAY%,}]" -# Request Body für Anfrage an Token-API erstellen +# Create request body for the request to the token API REQUEST_BODY="{\"packages\":$PACKAGE_ARRAY}" # ==================================================================================================================================== -# Token für den Download generieren +# Generate token for the download # ==================================================================================================================================== -# Downloadbedingungen des Pakets akzeptieren -# Wichtig: Informieren Sie sich vorab über die jeweils gültigen Downloadbedingungen. Dies kann über die Webseite erfolgen. +# Accept the package's download conditions +# Important: Make sure to review the applicable download conditions in advance. This can be done via the website. DOWNLOAD_TOKEN=$(curl --user-agent "{$USER_AGENT}" -sS -X POST -H "Content-Type: application/json" -d "$REQUEST_BODY" $TOKEN_API_ENDPOINT | jq -r '.token') echo "Download Token: $DOWNLOAD_TOKEN" if [[ -z "$DOWNLOAD_TOKEN" ]] || [[ "$DOWNLOAD_TOKEN" == "null" ]]; then @@ -45,10 +45,10 @@ if [[ -z "$DOWNLOAD_TOKEN" ]] || [[ "$DOWNLOAD_TOKEN" == "null" ]]; then fi # ==================================================================================================================================== -# Konfigurationsdatei für npm erstellen +# Create configuration file for npm # ==================================================================================================================================== -# Erstellen der Konfigurationsdatei aus dem Template +# Create the configuration file from the template cat .npmrc.template | \ sed "s/{{DOWNLOAD_TOKEN}}/$DOWNLOAD_TOKEN/g" > .npmrc echo "Konfigurationsdatei erstellt" \ No newline at end of file diff --git a/sushi-wrap/BfArM-Package-Test/sushi-wrap.sh b/sushi-wrap/BfArM-Package-Test/sushi-wrap.sh index 71b724bb4a36961b52de43ff3eb3201b42cb11fa..5ed79c34eca7b7d4897b72df4ffafd0505114fa9 100755 --- a/sushi-wrap/BfArM-Package-Test/sushi-wrap.sh +++ b/sushi-wrap/BfArM-Package-Test/sushi-wrap.sh @@ -1,72 +1,72 @@ #!/bin/bash # ==================================================================================================================================== -# Konfiguration +# Configuration # ==================================================================================================================================== -# Liste der akzeptierten Downloadbedingungen, e.g. 'bfarm.terminologien.abc,bfarm.terminologien.xyz' -# Die Liste der akzeptierten Downloadbedingungen kann über die Webseite (https://terminologien.bfarm.de) eingesehen werden. +# List of accepted download conditions, e.g. 'bfarm.terminologien.abc,bfarm.terminologien.xyz' +# The list of accepted download conditions can be viewed on the website (https://terminologien.bfarm.de). ACCEPTED_DOWNLOAD_CONDITIONS=bfarm.terminologien.abc,bfarm.terminologien.xyz -# Der Wert der im User-Agent-Header gesetzt werden soll +# The value to be set in the User-Agent header USER_AGENT=example-zts-client/1.0 -# Endpunktadressen der ZTS-API +# Endpoint addresses of the ZTS API CATALOG_API_ENDPOINT=https://terminologien.bfarm.de/packages/catalog PACKAGE_API_ENDPOINT=https://terminologien.bfarm.de/packages TOKEN_API_ENDPOINT=https://terminologien.bfarm.de/api/generate-token -# Pfad-/Dateinamen für temporäre Arbeitsdateien +# Path/filenames for temporary working files CATALOG_METADATA_FILE=catalog.json FHIR_HOME=~/.fhir OUTPUT_DIR=$(uuidgen) CURRENT_DIR=$(pwd) -# Dies und Das +# This and that DEBUG=false # ==================================================================================================================================== -# Hilfsfunktionen +# Helper functions # ==================================================================================================================================== -# Funktion, die prüft, ob ein Element in einem Array enthalten ist +# Function that checks if an element is present in an array contains_element() { local element="$1" shift local array=("$@") for e in "${array[@]}"; do if [[ "$e" == "$element" ]]; then - return 0 # gefunden + return 0 # found fi done - return 1 # nicht gefunden + return 1 # not found } # ==================================================================================================================================== -# Vorbereiten der Umgebung +# Preparing the environment # ==================================================================================================================================== -# Anlegen eines (temporären) Ausgabeverzeichnisses +# Create a (temporary) output directory mkdir $OUTPUT_DIR -# Umwandeln der Liste der akzeptierten Downloadbedingungen in ein Array +# Convert the list of accepted download conditions into an array IFS=',' read -ra accepted_conditions_packages <<< "$ACCEPTED_DOWNLOAD_CONDITIONS" echo "Pakete für die Downloadbedingungen akzeptiert wurden: ${accepted_conditions_packages[@]}" # ==================================================================================================================================== -# Abruf der Liste unterstützten Pakete +# Retrieve the list of supported packages # ==================================================================================================================================== -# Catalog API nach Liste der unterstützten Terminologien anfragen - Das Ergebnis wird in eine Datei geschrieben +# Request the Catalog API for a list of supported terminologies — the result will be written to a file curl --user-agent "{$USER_AGENT}" -X GET "{$CATALOG_API_ENDPOINT}" -H "Accept: application/json" -sS -o $CATALOG_METADATA_FILE -# Katalog in Array umwandeln, welches die Namen der unterstützten Pakete enthält. Das sind die Pakete, die auf dem ZTS verfügbar sind und heruntergelden werden können. +# Convert the catalog into an array containing the names of supported packages. These are the packages available on the ZTS and can be downloaded. available_packages=($(jq -r '.[].name' "$CATALOG_METADATA_FILE")) if [[ "$DEBUG" == "true" ]]; then echo "Auf ZTS verwaltete Pakete: ${available_packages[@]}" fi -# Schnittmenge zwischen den akzeptierten Paketen und den auf dem ZTS verfügbaren Paketen bilden. Das sind die Pakete, die heruntergeladen werden dürfen. +# Create the intersection between the accepted packages and the packages available on the ZTS. These are the packages that can be downloaded. downloadable_packages=() for item in "${accepted_conditions_packages[@]}"; do for element in "${available_packages[@]}"; do @@ -81,16 +81,16 @@ if [[ "$DEBUG" == "true" ]]; then fi # ==================================================================================================================================== -# Abhängigkeiten verarbeiten +# Process dependencies # ==================================================================================================================================== -# Abhängigkeiten aus der Konfigurationsdatei extrahieren und in ein Array umwandeln +# Extract dependencies from the configuration file and convert them into an array dependencies=($(yq '.dependencies' sushi-config.yaml | sed 's/:.*//')) if [[ "$DEBUG" == "true" ]]; then echo "Definierte Paketabhängigkeiten: ${dependencies[@]}" fi -# Schnittmenge zwischen den benötigten Paketen und den herunterladbaren Paketen bilden +# Create the intersection between the required packages and the downloadable packages final_packages=() for item in "${dependencies[@]}"; do for element in "${downloadable_packages[@]}"; do @@ -105,44 +105,44 @@ if [[ "$DEBUG" == "true" ]]; then fi # ==================================================================================================================================== -# Struktur für Request an TOKEN_API_ENDPOINT generieren +# Generate structure for the request to TOKEN_API_ENDPOINT # ==================================================================================================================================== -# Array für Anfrage Body vorbereiten +# Prepare array for request body PACKAGE_ARRAY="[" for item in "${downloadable_packages[@]}"; do PACKAGE_ARRAY+="\"$item\"," done -# Letztes Komma entfernen und Array schließen +# Remove trailing comma and close the array PACKAGE_ARRAY="${PACKAGE_ARRAY%,}]" -# Request Body für Anfrage an Token-API erstellen +# Create request body for the request to the Token API REQUEST_BODY="{\"packages\":$PACKAGE_ARRAY}" # ==================================================================================================================================== -# Token für den Download generieren +# # Generate token for the download # ==================================================================================================================================== -# Downloadbedingungen des Pakets akzeptieren -# Wichtig: Informieren Sie sich vorab über die jeweils gültigen Downloadbedingungen. Dies kann über die Webseite erfolgen. +# Accept the package's download conditions +# Important: Please make sure to review the applicable download conditions in advance. This can be done via the website. DOWNLOAD_TOKEN=$(curl --user-agent "{$USER_AGENT}" -sS -X POST -H "Content-Type: application/json" -d "$REQUEST_BODY" $TOKEN_API_ENDPOINT | jq -r '.token') if [[ "$DEBUG" == "true" ]]; then echo "Download Token: $DOWNLOAD_TOKEN" fi # ==================================================================================================================================== -# Download der Pakete +# Download Packages # ==================================================================================================================================== -# Iterieren über die definierten Paketabhängigkeiten +# Iterate over the defined package dependencies yq '.dependencies' sushi-config.yaml | while read package_version; do - # Paketname und Paketversion extrahieren + # Extract package name and package version name=$(echo $package_version | sed 's/:.*//' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//') version=$(echo $package_version | sed 's/.*://' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//') - # Nur wenn das Paket in der Liste der herunterladbaren Pakete enthalten ist, wird es heruntergeladen + # The package will only be downloaded if it is included in the list of downloadable packages if contains_element $name "${downloadable_packages[@]}"; then echo "Downloading $name#$version" curl --user-agent "{$USER_AGENT}" -sS -X GET "{$PACKAGE_API_ENDPOINT}/{$name}/{$version}" -H "Authorization: Bearer $DOWNLOAD_TOKEN" -O --remote-header-name --output-dir $OUTPUT_DIR @@ -152,27 +152,27 @@ yq '.dependencies' sushi-config.yaml | while read package_version; do done # ==================================================================================================================================== -# Heruntergeladene Pakete verarbeiten und in das FHIR-Verzeichnis verschieben +# # Process downloaded packages and move them to the FHIR directory # ==================================================================================================================================== cd $OUTPUT_DIR for file in *.tar.gz; do - # Paketname und Paketversion extrahieren + # Extract package name and package version export PACKAGE_NAME=$(echo $file | sed 's/-.*//') export PACKAGE_VERSION=$(echo $file | sed 's/.*-\([0-9.]*\)\..*/\1/') - # Verzeichnis für das Paket anlegen + # Create directory for the package mkdir $PACKAGE_NAME#$PACKAGE_VERSION - # Entpacken des Pakets + # Extract the package tar -xzf $file -C $PACKAGE_NAME#$PACKAGE_VERSION - # Paketdatei löschen + # Delete the package file rm $file - # Verschieben des entpackten Pakets in das FHIR-Verzeichnis + # Move the extracted package to the FHIR directory if [ -d $FHIR_HOME/packages/$PACKAGE_NAME#$PACKAGE_VERSION ]; then echo "Das Paket $PACKAGE_NAME#$PACKAGE_VERSION existiert bereits." else @@ -180,13 +180,13 @@ for file in *.tar.gz; do fi done -# Wechsel ins ursprüngliche Arbeitsverzeichnis und Aufräumen +# Change back to the original working directory and clean up cd $CURRENT_DIR rm -rf $OUTPUT_DIR rm $CATALOG_METADATA_FILE # ==================================================================================================================================== -# Sushi aufrufen +# Call sushi # ==================================================================================================================================== sushi . diff --git a/sushi-wrap/README.md b/sushi-wrap/README.md index 71b9d7e1bc721e10f3b5bac76a6e8f7fae250cc7..4040e41576496d4038c26e8a0eae542790a5a2c8 100644 --- a/sushi-wrap/README.md +++ b/sushi-wrap/README.md @@ -1,32 +1,47 @@ +<img align="right" width="250" height="47" src="../images/Gematik_Logo_Flag_With_Background.png"/> <br/> + # sushi-wrap -## Voraussetzung +<details> + <summary>Table of Contents</summary> + <ol> + <li><a href="#about-the-project">About The Project</a></li> + <li><a href="#prerequisites">Prerequisites</a></li> + <li><a href="#preliminary-note">Preliminary Note</a></li> + <li><a href="#structure-and-functionality">Structure and Functionality</a></li> + <li><a href="#usage">Usage</a></li> + </ol> +</details> -Folgende Pakete werden zur Ausführung des Skripts benötigt: +## About The Project +Example wrapper script to integrate an automated package download into Sushi workflows. -- **curl** (command line tool and library for transferring data with URLs) - [Website](https://curl.se/) -- **yq** (lightweight and portable command-line YAML processor) - [Website](https://github.com/mikefarah/yq/) -- **jq** (leightweight and flexible command-line JSON processor) - [Website](https://jqlang.github.io/jq/) +## Prerequisites +The following packages are required to run the script: -## Vorbemerkung -Die vom ZTS angebotenen Inhalte unterliegen Downloadbedingungen, welche unter [https://terminologien.bfarm.de/download-conditions.html](https://terminologien.bfarm.de/download-conditions.html) eingesehen werden können. Bitte stellen Sie sicher, dass Sie die jeweils geltenden Bedingungen akzeptieren, bevor Sie das angebotenen Skript nutzen. Technisch wird das Akzeptieren der Downloadbedingungen durch die Verwendung eines Access Tokens zum Ausdruck gebracht, welches während der Ausführung des Wrapper-Skripts erzeugt wird. +- **curl** (command-line tool and library for transferring data with URLs) - [Website](https://curl.se/) +- **yq** (lightweight and portable command-line YAML processor) - [Website](https://github.com/mikefarah/yq/) +- **jq** (lightweight and flexible command-line JSON processor) - [Website](https://jqlang.github.io/jq/) -## Struktur und Funktionsweise -Das Verzeichnis ```/BfArM-Package-Test``` enthält eine "normales" Sushi-Beispiel-Projekt, welches um ein Wrapper-Skript (```sushi-wrap```) ergänzt wurde. Dieses Skript funktioniert dabei nach folgendem Muster: +## Preliminary Note +The content offered by the ZTS is subject to download conditions, which can be viewed at [https://terminologien.bfarm.de/download-conditions.html](https://terminologien.bfarm.de/download-conditions.html). Please ensure that you accept the applicable terms and conditions before using the provided script. Technically, acceptance of the download conditions is expressed by using an access token, which is generated during the execution of the wrapper script. -1. Abruf der Liste vom ZTS unterstützter Pakete über die Catalog API -2. Abgleich der heruntergeladenen Liste mit Liste der akzeptierten Downloadbedingungen -3. Parsen der Datei ```sushi-config.yaml```mittels ```yq``` -4. Herunterladen aller Abhängigkeiten, die vom ZTS bereitgestellt werden und für die die Downloadbedingungen akzeptiert wurden -5. Entpacken der heruntergeladenen Paket-Versionen und verschieben der Dateien in das FHIR-Home-Verzeichnis -6. Aufräumen -7. Ausführen von ```sushi``` +## Structure and Functionality +The directory ```/BfArM-Package-Test``` contains a "normal" Sushi example project, which has been supplemented with a wrapper script (```sushi-wrap.sh```). This script works according to the following pattern: -Das Wrapper-Skript kann in beliebigen sushi-Projekten zum Einsatz kommen. +1. Retrieve the list of packages supported by ZTS via the Catalog API +2. Compare the downloaded list with the list of accepted download conditions +3. Parse the ```sushi-config.yaml``` file using ```yq``` +4. Download all dependencies provided by ZTS for which the download conditions have been accepted +5. Unpack the downloaded package versions and move the files to the FHIR home directory +6. Clean up +7. Execute ```sushi``` -## Notwendige Anpassungen am Wrapper-Skript -Bevor das Wrapper-Skript genutzt werden kann, sind Anpassungen an dessen Inhalt erforderlich. Hierzu müssen in der Konfigurationsvariable ```ACCEPTED_DOWNLOAD_CONDITIONS``` alle Pakete aufgeführt werden, für die der Nutzer die Downloadbedingungen (s.o.) akzeptiert. +The wrapper script can be used in any sushi project. -## Starten des Wrapper-Skripts -Durch den Aufruf von ```./sushi-wrap.sh```aus dem ```/BfArM-Package-Test```-Verzeichnis heraus, kann das Wrapper-Skript gestartet werden. +## Usage +### Required Adjustments to the Wrapper Script +Before the wrapper script can be used, adjustments are required. In particular, the configuration variable ```ACCEPTED_DOWNLOAD_CONDITIONS``` must include all packages for which the user has accepted the download conditions (see above). +### Starting the Wrapper Script +The wrapper script can be started by executing ```./sushi-wrap.sh``` from within the ```/BfArM-Package-Test``` directory. \ No newline at end of file