{"id":22814583,"url":"https://github.com/kit-data-manager/mapping-service","last_synced_at":"2026-03-05T09:31:55.362Z","repository":{"id":42370707,"uuid":"436278508","full_name":"kit-data-manager/mapping-service","owner":"kit-data-manager","description":null,"archived":false,"fork":false,"pushed_at":"2024-11-27T13:36:37.000Z","size":1412,"stargazers_count":1,"open_issues_count":9,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-27T14:29:26.172Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/kit-data-manager.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":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-08T14:32:22.000Z","updated_at":"2024-11-18T21:30:04.000Z","dependencies_parsed_at":"2024-11-20T22:02:03.931Z","dependency_job_id":null,"html_url":"https://github.com/kit-data-manager/mapping-service","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kit-data-manager%2Fmapping-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kit-data-manager%2Fmapping-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kit-data-manager%2Fmapping-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kit-data-manager%2Fmapping-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kit-data-manager","download_url":"https://codeload.github.com/kit-data-manager/mapping-service/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229388355,"owners_count":18065252,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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-12T13:09:21.798Z","updated_at":"2026-03-05T09:31:55.310Z","avatar_url":"https://github.com/kit-data-manager.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mapping-Service\n\n[![Java CI with Gradle](https://github.com/kit-data-manager/mapping-service/actions/workflows/CI.yml/badge.svg)](https://github.com/kit-data-manager/mapping-service/actions/workflows/CI.yml)\n[![CodeQL](https://github.com/kit-data-manager/mapping-service/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/kit-data-manager/mapping-service/actions/workflows/codeql-analysis.yml)\n[![codecov](https://codecov.io/gh/kit-data-manager/mapping-service/branch/main/graph/badge.svg?token=XFhZruKFaE)](https://codecov.io/gh/kit-data-manager/mapping-service)\n[![License](https://img.shields.io/github/license/kit-data-manager/indexing-service.svg)](https://github.com/kit-data-manager/mapping-service/blob/c3ab1c96643b3409774eafd4c8f0843cb9ae2aa1/LICENSE)\n\nThe mapping-service provides a generic interface for mapping various documents. The tools required for this, such as Gemma, JOLT, XSLT, ... can be \nloaded into the mapping-service as plugins, regardless of the programming language in which they were developed. These tools are then made usable via the REST-API and a Web-UI. \nThe mapping schemas are stored in a database and can be managed via the REST-API and the Web-UI.\n\nThe Web-UI is accessible via the following URL: [http://\\\u003cIP or hostname\u003e:8095](http://localhost:8095)\nThe REST-API is documented at the following link: [http://\\\u003cIP or hostname\u003e:8095/swagger-ui/index.html](http://localhost:8095/swagger-ui/index.html)\n\n## How to build\n\nDependencies that are needed to build and are not being downloaded via gradle:\n\n- OpenJDK 17\n- Python 3\n- pip (runtime only)\n\n`./gradlew build`\n\n### Python Location\n\nCurrently, mapping-service requires Python to be installed in order to build and to run. At runtime, the Python executable is configured in \n`application.properties`(see below). For building the mapping-service Python executable is set to `/usr/bin/python3` by default. In case you want to build \nthe mapping-service on a machine on which the Python installation is located elsewhere, e.g., under Windows, you can provide the Python location \nused at compile time externally, i.e.:\n\n```\n.\\gradlew \"-DpythonExecutable=file:///C:/Python310/python.exe\" build\n```\n\n## How to start\n\nBefore you can start the mapping-service, you  first have to create an `application.properties` file in the source folder. As an example you may use `config/application.default.properties`\nand modify it according to your needs. Espacially the following properties (at the end of the file) are important:\n- `spring.datasource.url=jdbc:h2:file:/tmp/mapping-service/database`\nThe path points to the location of the database in which your configured mappings are stored.\n- `mapping-service.pythonExecutable=${pythonExecutable:'file:///usr/bin/python3'}` \\\nIf no pythonExecutable is provided externally (see above) the default `/usr/bin/python3` is used.\n- `mapping-service.pluginLocation=file:///tmp/mapping-service/plugins` \\\nThe local folder where available plugins are located.\n- `mapping-service.mappingsLocation:file:///tmp/mapping-service/` \\\nEnter the location where you want to store your mappings. This folder will be created if it does not exist yet.\n\nIn order to provide the mapping-service with mapping functionality, there are already some pre-compiled plugins available under in the `plugins` folder of this repository.\nCopy them to your configured `mapping-service.pluginLocation` to make them available to the mapping-service. \nThe source code of the gemma-plugin can be found [here](https://github.com/maximilianiKIT/gemma-plugin). The plugin shows how to integrate Python mappings easily.\n\nThere is also the possibility to add new plugins directly at the source tree and create a pluggable Jar out of them. Therefor, check \n`src/main/java/edu/kit/datamanager/mappingservice/plugins/impl`. Just add your new plugin, e.g., based on the `TestPlugin` example. \nIn order to make the plugin usable by the mapping service, you then have to build a plugin Jar out of it. In order to do that, just call:\n\n```\n./gradlew buildPluginJar\n```\n\nThis task creates a file `default-plugins-\u003cVERSION\u003e` at `build/libs` which has to be copied to `mapping-service.pluginLocation` to make it available. \n\nAfter doing this, the mapping-service is ready for the first start. This can be achieved by executing:\n\n`java -jar build/lib/mapping-service-\u003cVERSION\u003e.jar`\n\nThis assumes, that the command is called from the source folder and that your `application.properties` is located in the same folder. \nOtherwise, you may use:\n\n`java -jar build/lib/mapping-service-\u003cVERSION\u003e.jar --spring.config.location=/tmp/application.properties`\n\nIdeally, for production use, you place everything (`mapping-service-\u003cVERSION\u003e.jar`, `application.properties`, `mapping-service.pluginLocation`, `mapping-service.mappingsLocation`,\nand `spring.datasource.url`) in a separate folder from where you then call the mapping-service via: \n\n`java -jar mapping-service-\u003cVERSION\u003e.jar`\n\n## Installation\nThere are three ways to install metaStore2 as a microservice:\n- [Using](#Installation-via-GitHub-Packages) the image available via [GitHub Packages](https://github.com/orgs/kit-data-manager/packages?repo_name=mapping-service) (***recommended***)\n- [Building](#Build-docker-container-locally) docker image locally\n- [Building](#Build-and-run-locally) and running locally\n\n## Installation via GitHub Packages\n### Prerequisites\nIn order to run this microservice via docker you'll need:\n\n* [Docker](https://www.docker.com/) \n\n### Installation\nTypically, there is no need for locally building images as all version are accessible via GitHub Packages.\nHave a look of available images and their tags [here](https://github.com/orgs/kit-data-manager/packages?repo_name=mapping-service) \nJust follow instructions [below](#Build-docker-container).\n\n## Build docker container locally\n### Prerequisites\nIn order to run this microservice via docker you'll need:\n\n* [Docker](https://www.docker.com/) \n* [git](https://git-scm.com/) \n\n### Installation\n#### Clone repository\nFirst of all you'll have to clone this repository:\n```\nuser@localhost:/home/user/$ git clone https://github.com/kit-data-manager/mapping-service.git\nClone to 'mapping-service'\n[...]\nuser@localhost:/home/user/$ cd mapping-service\nuser@localhost:/home/user/mapping-service$\n```\n\n#### Create image\nNow you'll have to create an image containing the microservice. This can be done via a script.\nOn default the created images will be tagged as follows:\n\n*'latest tag'-'actual date(yyyy-mm-dd)'* (e.g.: 1.1.0-2023-06-27)\n\n```\nuser@localhost:/home/user/mapping-service$ bash docker/buildDocker.sh\n---------------------------------------------------------------------------\nBuild docker container ghcr.io/kit-data-manager/mapping-service:1.2.0-2023-06-27\n---------------------------------------------------------------------------\n[...]\n---------------------------------------------------------------------------\nNow you can create and start the container by calling ...\n---------------------------------------------------------------------------\nuser@localhost:/home/user/mapping-service$\n```\n\n#### Build docker container\nAfter building image you have to create (and start) a container for executing microservice:\n```\n# If you want to use a specific image you may list all possible tags first.\nuser@localhost:/home/user/mapping-service$ docker images ghcr.io/kit-data-manager/mapping-service --format {{.Tag}}\n1.2.0-2023-06-27\nuser@localhost:/home/user/mapping-service$ docker run -d -p8095:8095 --name mapping4docker ghcr.io/kit-data-manager/mapping-service:1.2.0-2023-06-27\n57c973e7092bfc3778569f90632d60775dfecd12352f13a4fd2fdf4270865286\nuser@localhost:/home/user/mapping-service$\n```\n\n#### Customize settings\nIf you want to overwrite default configuration of your docker container you have to\n'mount' a config directory containing 'application.properties' with your adapted settings.\nTherefor you have to provide an additional flag to the command mentioned before:\n```\n# Overwriting default settings\n# Create config folder\nuser@localhost:/home/user/mapping-service$ mkdir config\n# Place your own 'application.properties' inside the config directory\n# Create/run container\nuser@localhost:/home/user/mapping-service$ docker run -d -p8095:8095 -v `pwd`/config:/spring/mapping-service/config --name mapping4docker ghcr.io/kit-data-manager/mapping-service:1.2.0-2023-06-27\n57c973e7092bfc3778569f90632d60775dfecd12352f13a4fd2fdf4270865286\nuser@localhost:/home/user/mapping-service$\n```\n\n#### Stop docker container\nIf you want to stop container just type\n```\nuser@localhost:/home/user/mapping-service$ docker stop mapping4docker\n```\n\n#### (Re)start docker container\nIf you want to (re)start container just type\n```\nuser@localhost:/home/user/mapping-service$ docker start mapping4docker\n```\n\n## Build and run locally\n### Prerequisites\nIn order to run this microservice via docker you'll need:\n\n* [Java SE Development Kit \u003e= 17](https://openjdk.java.net/) \n* [git](https://git-scm.com/) \n\n### Installation\n#### Clone repository\nFirst of all you'll have to clone this repository:\n```\nuser@localhost:/home/user/$ git clone https://github.com/kit-data-manager/mapping-service.git\nClone to 'mapping-service'\n[...]\nuser@localhost:/home/user/$ cd mapping-service\nuser@localhost:/home/user/mapping-service$\n```\n#### Build service \nTo build service just execute the build.sh script:\n```\nuser@localhost:/home/user/mapping-service$bash build.sh /PATH/TO/EMPTY/INSTALLATION/DIRECTORY\n---------------------------------------------------------------------------\nBuild microservice of mapping-service at /PATH/TO/EMPTY/INSTALLATION/DIRECTORY\n---------------------------------------------------------------------------\n[...]\n---------------------------------------------------------------------------\nNow you can start the service by calling /PATH/TO/EMPTY/INSTALLATION/DIRECTORY/run.sh\n---------------------------------------------------------------------------\nuser@localhost:/home/user/mapping-service$\n```\n#### Customize settings\nIf you want to overwrite default configuration of your docker container you have to\nadd a file named 'application.properties' to the 'config' directory inside your installation\npath (/PATH/TO/EMPTY/INSTALLATION/DIRECTORY)selected before. The added file should\nonly contain your adapted settings. e.g. in case you want to change only the port to '1234' your\n'application.properties' should look like this:\n```\n# Overwriting default settings from ../application.properties\n# Server settings\nserver.port: 1234\n```\n\n## License\n\nSee [LICENSE file in this repository](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkit-data-manager%2Fmapping-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkit-data-manager%2Fmapping-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkit-data-manager%2Fmapping-service/lists"}