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
Note: you need to specify the version explicitly when using the pull command, e.g.:
docker pull itext/dito-sdk:{version}
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, by default it will look for license.xml file, but you can override it 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: For consistency in API behaviour when updating to a newer version of the SDK it is advised to specify the desired API version in X-DITO-API-Version header for all requests. For more info see API versions descriptor documentation. 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.
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
PDF Producer Resource
Actions
|
URI |
Methods |
|---|---|
|
/api/pdf-producer |
POST - creates PDFs from one of the template package's templates and data.
Response type:
Response codes: |
Production request descriptor
|
Name |
Type |
Description |
|---|---|---|
|
templateProjectPath |
string (path) |
Path to the template project (relative to shared work directory) |
|
templateName |
string |
Name of the template inside the template project |
|
data |
json
|
Data used for production. If specified as string than it is treated as path to data file (relative to shared work directory), otherwise is treated as direct template data. If not specified then empty data is is sent: {} |
|
path |
string (path)
|
The suggested path to the resulting PDF file, relative to the work directory. If a file already exists than a new path will be generated. All intermediate directories are created. If not specified, then file names are generated automatically from defaultVersion UTC data in the format: yyyy-MM-dd-HH.mm.ss.nnnnnnnnn.pdf |
|
properties |
production properties descriptor
|
The PDF production properties |
Production response descriptor
|
Name |
Type |
Description |
|---|---|---|
|
path |
string(path) |
Path to the produced PDF relative to work directory. |
Production properties descriptor
|
Name |
Type |
Description |
|---|---|---|
|
pdfVersion |
string (enum)
|
Target PDF version. Valid values are:
|
|
encryption |
encryption properties descriptor
|
If present specifies PDF encryption. No encryption by default: |
Encryption properties descriptor
|
Name |
Type |
Description |
|---|---|---|
|
ownerPassword |
string (password) |
String used as owner password. Must be not empty |
|
userPassword |
string (password)
|
String used as user password. Treated as absent if empty. |
|
printingAllowed |
boolean
|
Allow printing when PDF is opened in user mode:
|
|
contentCopyingAllowed |
boolean
|
Allow copying content when PDF is opened in user mode:
|
|
editingAllowed |
boolean
|
Allow editing content (including editing annotations) when PDF is opened in user mode:
|
|
screenReaderAccessAllowed |
boolean
|
Allow screen reader access when PDF is opened in user mode:
|
License resource
Actions
|
URI |
Methods |
|
/api/license |
GET- gets loaded license info
|
License descriptor
|
Name |
Type |
Description |
|---|---|---|
|
expirationDate |
date |
Expiration UTC date in format:
|
|
remaining |
dictionary |
Dictionary from limit type to long number of remaining events. Possible limit types:
|
Status resource
Actions
|
URI |
Methods |
|---|---|
|
/api/status |
GET- gets server status
|
Status descriptor
|
Name |
Type |
Description |
|---|---|---|
|
sdkVersion |
string |
Version of the iText DITO SDK in the format:
|
|
apiVersions |
API versions descriptor |
Information about API versions. |
|
health |
dictionary |
The dictionary with server health checks |
API versions descriptor
Each request can specify the desired API version in the X-DITO-API-Version header.
|
Name |
Type |
Description |
|---|---|---|
|
default |
string |
The default API version that will be used if the X-DITO-API-Version header is not specified. |
|
maximumSupported |
string |
The maximum supported API version. If the version specified in X-DITO-API-Version header is newer than the maximum supported version the request will fail. |
|
minimumSupported |
string |
The minimum supported API version. If the version specified in X-DITO-API-Version header is older than the minimum supported version the request will fail. |
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
|
Request |
Response |
|---|---|
|
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" } |
Produce PDF with 2.0 version and custom output path from project file in working directory and data embedded in the request
|
Request |
Response |
|---|---|
|
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" } |
Get loaded license info
|
Request |
Response |
|---|---|
|
GET localhost:42/api/license |
200 OK Content-Type application/json Body { "expirationDate": "2020-09-23", "remaining": { "page": 999980 } } |