iText DITO Docker API (iText_DITO 2.0)

The iText DITO SDK for Docker image allows you to use iText DITO conveniently from various environments. It enables you to produce PDFs from your output templates.

How to use the iText DITO SDK for Docker image

First, you'll need to pull the image. Note: you need to specify the version explicitly when using the pull command, e.g.:

docker pull itext/dito-sdk:{version}

For the full list of available versions go to Tags tab.

Start the SDK

To start the docker image run the following command:

docker run -it --name dito-sdk-instance
         -v {path to config directory}:/etc/opt/dito/shared
         -v {path to work directory}:/var/opt/dito
         -v {path to log directory}:/var/log/dito
         -p {port on host}:8080
         itext/dito-sdk:{version}

config directory - the directory that contains iText DITO license and application configuration file.

iText DITO License file

License file provided by iText. Must be present in config directory. Expected default name is license.xml, but it can be overridden by setting the DITO_LICENSE_FILE environment variable during run, for example:

docker run {other options} -e DITO_LICENSE_FILE=dito.xml itext/dito-sdk:{version}

Note: If you're using Azure, you may get an error message that the license key cannot be found. To resolve this, you will need to enable volume mounting using the WEBSITES_ENABLE_APP_SERVICE_STORAGE=true environment variable.

Application configuration file

YML file with application configuration, in form of:

pdfProducerReportCache:
  maxSize: 1000
  expireAfterWrite: P1D
templateDeploymentFeature:
  enabled: true
  timeout:
      eachOperationRetryMillis: 500
      eachOperationRetryCount: 10
      allBlockWaitMillis: 5000

pdfProducerReportCache - configures how many and how long cached production reports are stored in memory.

• maxSize - integer (64 bit) specifying how many reports can be stored simultaneously.

• expireAfterWrite - string in ISO-8601 subset (Days, Hours, Minutes, Seconds, e.g. P1DT2H3M4S) specifying for how long the reports can be stored

templateDeploymentFeature - configures the template deployment feature with registering/unregistering and template deployment/undeployment.

• enabled - enables the feature, is false by default.
• timeout - configures template operation wait timeouts.
  • eachOperationRetryMillis - configures how much time we wait before next retry to do such operations as deploy, undeploy and PDF produce
  • eachOperationRetryCount - configures how many times we do retry before timeout for such operations as deploy, undeploy and PDF produce
  • allBlockWaitMillis - configures how much time we wait before timeout for such operations as register and unregister

File can be optionally present in config directory. If not present the default one will be used. Expected default name for YML file is user.config.yml, but it can be overridden by setting the DITO_USER_CONFIG environment variable during run, for example:

docker run {other options} -e DITO_USER_CONFIG=config.yml itext/dito-sdk:{version}

Stop the SDK

To stop SDK service gracefully, run the standard command:

docker kill --signal=SIGTERM {containerId}

You can also use another standard command:

docker stop -t 30 {containerId}

This command sends the SIGTERM signal to the SDK process inside the Docker container, then waits for the specified time in seconds (10 by default). If the SDK doesn't manage to finish its shutdown within that time period, SIGKILL is sent to the kernel and the SDK process is killed.

Web API reference

Note: For consistency in API behaviour when updating to a newer version of the SDK it is strongly recommended specifying the desired API version in X-DITO-API-Version header for all requests. For more info see API versions descriptor documentation.

PDF Producer Resource

Actions

Production request descriptor

  
        {}
    

Production work directory request descriptor

    
            yyyy-MM-dd-HH.mm.ss.nnnnnnnnn.pdf
        

Production response descriptor

Production properties descriptor

Encryption properties descriptor

Bookmarks properties descriptor

Production report descriptor

null

Processing report descriptor

Report entry descriptor

Pdf producer report resource

Actions

Since 1.5.5

Template deployment resource

Actions

Only registered user can perform actions in this resource.
The Authorization HTTP header with Bearer type and token from registration endpoint must be used.

Template deployment request descriptor

Template deployment response descriptor

Registration resource

Actions

Only single user can be registered at ones.

Token request descriptor

Token response descriptor

License resource

Actions

License descriptor

Status resource

Actions

Status descriptor

Features

Description of different features which features section can be contained of

templateDeployment

API versions descriptor

Each request can specify the desired API version in the X-DITO-API-Version header.

Examples

Running SDK

On Windows

docker run -it --name dito-sdk-example
         -v D:\docker\dito\config:/etc/opt/dito/shared
         -v D:\docker\dito\work:/var/opt/dito
         -v D:\docker\dito\log:/var/log/dito
         -p 42:8080
         itext/dito-sdk:1.1.8

D:\docker\dito\config - a folder with license.xml file.

D:\docker\dito\work - a working folder where all project files and data samples should be placed.

D:\docker\dito\log - a log folder where service logs will be placed.

On Linux

docker run -it --name dito-sdk-example
         -v /home/docker/dito/config:/etc/opt/dito/shared
         -v /home/docker/dito/work:/var/opt/dito
         -v /home/docker/dito/log:/var/log/dito
         -p 42:8080
         itext/dito-sdk:1.1.8

/home/docker/dito/config - a folder with license.xml file.

/home/docker/dito/work - a working folder where all project files and data samples should be placed.

/home/docker/dito/log - a log folder where service logs will be placed.

Requests

For next requests all paths are relative to working directory (/home/docker/dito/work on Linux or D:\docker\dito\work on Windows assuming service is run with commands above) The dummy.dito is an example iText DITO project that is placed in the working directory. The sample.json is a data sample for it that is placed in the same working directory.

Produce PDF from project file and data in working directory

POST localhost:42/api/pdf-producer

Content-Type application/json

Body
{
    "templateProjectPath": "dummy.dito",
    "templateName": "output",
    "data": "sample.json"
}

200 OK

Content-Type application/json

Body
{
    "path": "2019-09-23-13.00.44.472000000.pdf",
    "report": {
        "pageCount": 1,
        "templateRepairReport": {
            "entries": []
        },
        "pdfProductionReport": {
            "entries": []
        },
        "id": "65fff9f3-db63-4c6d-ad0f-81418b4376b7",
        "highestSeverity": null
    }
}

Produce PDF with 2.0 version and custom output path from project file in working directory and data embedded in the request

POST localhost:42/api/pdf-producer

Content-Type application/json

Body
{
    "templateProjectPath": "dummy.dito",
    "templateName": "output",
    "data": {
        "bind": "from request"
    },
    "path": "custom/path/to/file.pdf",
    "properties": {
        "pdfVersion": "2.0"
    }
}

200 OK

Content-Type application/json

Body
{
    "path": "custom/path/to/file.pdf",
    "report": {
        "pageCount": 1,
        "templateRepairReport": {
            "entries": [
                {
                    "message": "Encountered unexpected empty attribute: \"data-dito-bind\"",
                    "severity": "warn"
                }            
            ]
        },
        "pdfProductionReport": {
            "entries": []
        },
        "id": "65fff9f3-db63-4c6d-ad0f-81418b4376b7",
        "highestSeverity": "warn"
    }    
}

Produce PDF as stream

POST localhost:42/api/pdf-producer

Content-Type application/json

Accept application/pdf

Body
{
    "templateProjectPath": "dummy.dito",
    "templateName": "output",
    "data": {
        "bind": "from request"
    }
}

200 OK

Content-Type application/pdf

X-DITO-Producer-Report-ID 65fff9f3-db63-4c6d-ad0f-81418b4376b7

X-DITO-Producer-Highest-Severity warn

Body
bytes of generated PDF

Get cached PDF producer report

GET localhost:42/api/pdf-producer/report/65fff9f3-db63-4c6d-ad0f-81418b4376b7

Content-Type application/json

200 OK

Content-Type application/json

Body
{
    "pageCount": 1,
    "templateRepairReport": {
        "entries": [
            {
                "message": "Encountered unexpected empty attribute: \"data-dito-bind\"",
                "severity": "warn"
            }            
        ]
    },
    "pdfProductionReport": {
        "entries": []
    },
    "id": "65fff9f3-db63-4c6d-ad0f-81418b4376b7",
    "highestSeverity": "warn"
}

Get loaded license info

GET localhost:42/api/license

200 OK

Content-Type application/json

Body
{
    "expirationDate": "2020-09-23",
    "remaining": {
        "page": 999980
    }
}

User registration

POST localhost:42/api/admin/register

Content-Type application/json

Body
{
    "subject": "best name"
}

200 OK

Content-Type application/json

Body
{
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0In0.1DI6IZUGvCx_K_oxZ8lFuFBTHe-7shhqz77jSw18xkc"
}

Template deployment

POST localhost:42/api/deployments

Content-Type multipart/form-data

Authorization Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0In0.1DI6IZUGvCx_K_oxZ8lFuFBTHe-7shhqz77jSw18xkc

Body
Content-Type: multipart/form-data

200 OK

Content-Type application/json

Body
{
"alias": "best template",
"meta": {
"version": "for tests"
}
}

Produce PDF as stream from alias

POST localhost:42/api/pdf-producer

Content-Type application/json

Accept application/pdf

Body
{
    "templateAlias": "best template",
    "data": {
        "bind": "from request"
    }
}

200 OK

Content-Type application/pdf

X-DITO-Producer-Report-ID 65fff9f3-db63-4c6d-ad0f-81418b4376b7

X-DITO-Producer-Highest-Severity warn

Body
bytes of generated PDF

Extending from DITO SDK Docker image

In some cases you may want to extend from DITO SDK Docker image. Here are some inner detail on base image that may help you do it. To extend from DITO SDK Docker image start you Dockerfile with FROM itext/dito-sdk:{version} e.g.

FROM itext/dito-sdk:1.4.2

What is needed to run base image

The main thing you need is license file in the config directory and DITO projects in the working directory.

License file

License file is expected to be stored at /etc/opt/dito/shared/$DITO_LICENSE_FILE where DITO_LICENSE_FILE is a predefined environment variable equal by default to license.xml.

So if you want to avoid providing volume mapping for folder with license file, it is possible to do so by extending base image and adding

COPY path/on/local/machine/to/license/file.xml /etc/opt/dito/shared/$DITO_LICENSE_FILE

NOTE: Be careful with sharing images that have license files in them.

Optional user config

Optional user configuration is expected at same folder as license config file at /etc/opt/dito/shared/$DITO_USER_CONFIG, where DITO_USER_CONFIG is a predefined environment variable equal by default to user.config.yml. So it can be provided similarly to license file

COPY path/on/local/machine/to/config/user.yml /etc/opt/dito/shared/$DITO_USER_CONFIG

Work directory

In order to produce PDF you'll need to have some .dito project files in working directory. There is a special predefined environment variable DITO_WORK_DIR equal by default to /var/opt/dito

So if you want to avoid providing volume mapping for work directory, you can copy all required .dito projects in your Dockerfile:

COPY path/on/local/machine/to/project1.dito path/on/local/machine/to/project2.dito $DITO_WORK_DIR/

NOTE: If at some point before running base entrypoint working directory was changed it should be restored to DITO work directory. This can be done in Dokerfile:

WORKDIR $DITO_WORK_DIR

Logs directory

The logs are always stored at /var/log/dito on the container and are kept for 30 days. The volume mapping to log directory can be omitted, that way the log files would be stored only on container. You can still access them though with e.g. docker cp command.

Running image

The script that runs dito application is stored at /opt/dito/startup.sh there is no need to write

ENTRYPOINT ["/opt/dito/startup.sh"]

Since the base one will be taken instead, but if you want to do something before running DITO application in container you may put it in your own script and call /opt/dito/startup.sh in the end.

Full example of Dockerfile for image that doesn't require any volume mappings

FROM itext/dito-sdk:1.4.2
COPY license.xml /etc/opt/dito/shared/$DITO_LICENSE_FILE
COPY user.config.yml /etc/opt/dito/shared/$DITO_USER_CONFIG
COPY project1.dito project2.dito $DITO_WORK_DIR/

Note: When running such image you would still need to map 8080 container port.