The mapping-service provides a generic interface for mapping various documents. The tools required for this, such as Gemma, JOLT, XSLT, ... can be loaded 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. The mapping schemas are stored in a database and can be managed via the REST-API and the Web-UI.

The Web-UI is accessible via the following URL: http://<IP or hostname>:8095 The REST-API is documented at the following link: http://<IP or hostname>:8095/swagger-ui/index.html

Dependencies that are needed to build and are not being downloaded via gradle:

• OpenJDK 17
• Python 3
• pip (runtime only)

./gradlew build

Currently, mapping-service requires Python to be installed in order to build and to run. At runtime, the Python executable is configured in 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 the mapping-service on a machine on which the Python installation is located elsewhere, e.g., under Windows, you can provide the Python location used at compile time externally, i.e.:

.\gradlew "-DpythonExecutable=file:///C:/Python310/python.exe" build

Before 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 and modify it according to your needs. Espacially the following properties (at the end of the file) are important:

• spring.datasource.url=jdbc:h2:file:/tmp/mapping-service/database The path points to the location of the database in which your configured mappings are stored.
• mapping-service.pythonExecutable=${pythonExecutable:'file:///usr/bin/python3'}
  If no pythonExecutable is provided externally (see above) the default /usr/bin/python3 is used.
• mapping-service.pluginLocation=file:///tmp/mapping-service/plugins
  The local folder where available plugins are located.
• mapping-service.mappingsLocation:file:///tmp/mapping-service/
  Enter the location where you want to store your mappings. This folder will be created if it does not exist yet.

In 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. Copy them to your configured mapping-service.pluginLocation to make them available to the mapping-service. The source code of the gemma-plugin can be found here. The plugin shows how to integrate Python mappings easily.

There is also the possibility to add new plugins directly at the source tree and create a pluggable Jar out of them. Therefor, check src/main/java/edu/kit/datamanager/mappingservice/plugins/impl. Just add your new plugin, e.g., based on the TestPlugin example. In 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:

./gradlew buildPluginJar

This task creates a file default-plugins-<VERSION> at build/libs which has to be copied to mapping-service.pluginLocation to make it available.

After doing this, the mapping-service is ready for the first start. This can be achieved by executing:

java -jar build/lib/mapping-service-<VERSION>.jar

This assumes, that the command is called from the source folder and that your application.properties is located in the same folder. Otherwise, you may use:

java -jar build/lib/mapping-service-<VERSION>.jar --spring.config.location=/tmp/application.properties

Ideally, for production use, you place everything (mapping-service-<VERSION>.jar, application.properties, mapping-service.pluginLocation, mapping-service.mappingsLocation, and spring.datasource.url) in a separate folder from where you then call the mapping-service via:

java -jar mapping-service-<VERSION>.jar

There are three ways to install metaStore2 as a microservice:

• Using the image available via GitHub Packages (recommended)
• Building docker image locally
• Building and running locally

In order to run this microservice via docker you'll need:

• Docker

Typically, there is no need for locally building images as all version are accessible via GitHub Packages. Have a look of available images and their tags here Just follow instructions below.

In order to run this microservice via docker you'll need:

• Docker
• git

First of all you'll have to clone this repository:

user@localhost:/home/user/$ git clone https://github.com/kit-data-manager/mapping-service.git
Clone to 'mapping-service'
[...]
user@localhost:/home/user/$ cd mapping-service
user@localhost:/home/user/mapping-service$

Now you'll have to create an image containing the microservice. This can be done via a script. On default the created images will be tagged as follows:

'latest tag'-'actual date(yyyy-mm-dd)' (e.g.: 1.1.0-2023-06-27)

user@localhost:/home/user/mapping-service$ bash docker/buildDocker.sh
---------------------------------------------------------------------------
Build docker container ghcr.io/kit-data-manager/mapping-service:1.2.0-2023-06-27
---------------------------------------------------------------------------
[...]
---------------------------------------------------------------------------
Now you can create and start the container by calling ...
---------------------------------------------------------------------------
user@localhost:/home/user/mapping-service$

After building image you have to create (and start) a container for executing microservice:

# If you want to use a specific image you may list all possible tags first.
user@localhost:/home/user/mapping-service$ docker images ghcr.io/kit-data-manager/mapping-service --format {{.Tag}}
1.2.0-2023-06-27
user@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
57c973e7092bfc3778569f90632d60775dfecd12352f13a4fd2fdf4270865286
user@localhost:/home/user/mapping-service$

If you want to overwrite default configuration of your docker container you have to 'mount' a config directory containing 'application.properties' with your adapted settings. Therefor you have to provide an additional flag to the command mentioned before:

# Overwriting default settings
# Create config folder
user@localhost:/home/user/mapping-service$ mkdir config
# Place your own 'application.properties' inside the config directory
# Create/run container
user@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
57c973e7092bfc3778569f90632d60775dfecd12352f13a4fd2fdf4270865286
user@localhost:/home/user/mapping-service$

If you want to stop container just type

user@localhost:/home/user/mapping-service$ docker stop mapping4docker

If you want to (re)start container just type

user@localhost:/home/user/mapping-service$ docker start mapping4docker

In order to run this microservice via docker you'll need:

• Java SE Development Kit >= 17
• git

First of all you'll have to clone this repository:

user@localhost:/home/user/$ git clone https://github.com/kit-data-manager/mapping-service.git
Clone to 'mapping-service'
[...]
user@localhost:/home/user/$ cd mapping-service
user@localhost:/home/user/mapping-service$

To build service just execute the build.sh script:

user@localhost:/home/user/mapping-service$bash build.sh /PATH/TO/EMPTY/INSTALLATION/DIRECTORY
---------------------------------------------------------------------------
Build microservice of mapping-service at /PATH/TO/EMPTY/INSTALLATION/DIRECTORY
---------------------------------------------------------------------------
[...]
---------------------------------------------------------------------------
Now you can start the service by calling /PATH/TO/EMPTY/INSTALLATION/DIRECTORY/run.sh
---------------------------------------------------------------------------
user@localhost:/home/user/mapping-service$

If you want to overwrite default configuration of your docker container you have to add a file named 'application.properties' to the 'config' directory inside your installation path (/PATH/TO/EMPTY/INSTALLATION/DIRECTORY)selected before. The added file should only contain your adapted settings. e.g. in case you want to change only the port to '1234' your 'application.properties' should look like this:

# Overwriting default settings from ../application.properties
# Server settings
server.port: 1234

See LICENSE file in this repository.