Document Merge Service

A document template merge service providing an API to manage templates and merge them with given data.

Getting started

Installation

Requirements

docker
docker-compose

After installing and configuring those, download docker-compose.yml and run the following command:

docker-compose up -d

You can now access the api at http://localhost:8000/api/v1/ which includes a browsable api.

Usage

Upload templates using the following:

curl --form template=@docx-template.docx --form name="Test Template" --form engine=docx-template http://localhost:8000/api/v1/template/

And merge template with:

curl -H "Content-Type: application/json" --data '{"data": {"test": "Test Input"}}' http://localhost:8000/api/v1/template/test-template/merge/ > output.docx

Additionally you can also convert output to pdf or other types supported by unoconv:

curl -H "Content-Type: application/json" --data '{"data": {"test": "Test Input"}, "convert": "pdf"}' http://localhost:8000/api/v1/template/test-template/merge/ > output.pdf

For this unoconv service needs to be configured.

Supported engines

Following template engines are currently supported:

Configuration

Document Merge Service is a 12factor app which means that configuration is stored in environment variables. Different environment variable types are explained at django-environ.

Common

SECRET_KEY: A secret key used for cryptography. This needs to be a random string of a certain length. See more.
ALLOWED_HOSTS: A list of hosts/domains your service will be served from. See more.

Database

Per default Sqlite3 is used as database for simple deployment. To scale service a different database storage is needed. Any database supported by Django can be used.

DATABASE_ENGINE: Database backend to use.
DATABASE_HOST: Host to use when connecting to database
DATABASE_PORT: Port to use when connecting to database
DATABASE_NAME: Name of database to use
DATABASE_USER: Username to use when connecting to the database
DATABASE_PASSWORD: Password to use when connecting to database

Unoconv

UNOCONV_URL: url to tfk-api-unoconv service (e.g. http://localhost:3000)
UNOCONV_ALLOWED_TYPES: list of types allowed to convert to. See supported formats (default: ['pdf'])

Authentication / Authorization

Per default no authentication is needed. To protect api, integrate it with your IAM supporting Open ID Connect. If not availbale you might consider using Keycloak.

REQUIRE_AUTHENTICATION: Force authentication to be required (default: False)
GROUP_ACCESS_ONLY: Force visibility to templates of group only. See also OIDC_GROUPS_CLAIM. (default: False)
OIDC_USERINFO_ENDPOINT: Url of userinfo endpoint as described
OIDC_GROUPS_CLAIM: Name of claim to be used to define group membership (default: document_merge_service_groups)
OIDC_BEARER_TOKEN_REVALIDATION_TIME: Time in seconds before bearer token validity is verified again. For best security token is validated on each request per default. It might be helpful though in case of slow Open ID Connect provider to cache it. It uses cache mechanism for memorizing userinfo result. Number has to be lower than access token expiration time. (default: 0)

Cache

CACHE_BACKEND: cache backend to use (default: django.core.cache.backends.locmem.LocMemCache)
CACHE_LOCATION: location of cache to use

Contributing

Look at our contributing guidelines to start with your first contribution.

License

Code released under the MIT license.

open-dynaMIX / document-merge-service