Skip to main content
Skip table of contents

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
URIMethodsNotes
/api/pdf-producerPOST - creates PDFs from one of the template package's templates and data and writes it to work directory.
Acceptable request types:
  • application/json - production work directory request descriptor
Response type:
  • application/json - production response descriptor
Response codes:
    200 OK - PDF successfully created; 400 Bad Request - one of the descriptor parameters is invalid
    Default one.
    Isn't available if work directory is read only.
    Report returned in the request is not cached
    POST - creates PDFs from one of the template package's templates and data.
    Acceptable request types:
    • application/json - production request descriptor
    Response type:
    • application/pdf - created PDF
    Response codes:
      200 OK - PDF successfully created; 400 Bad Request - one of the descriptor parameters is invalid
      application/pdf should be specified in request Accept header to use this method.
      Can still return application/json on bad requests.
      Is available even if work directory is read only.
      Response contains X-DITO-Producer-Report-ID header, which can be used to access cached production report.
      Response can contain X-DITO-Producer-Highest-Severity header with highest severity level if report is not empty
      Production request descriptor
      NameTypeDescription
      templateProjectPathstring (path)Path to the template project (relative to shared work directory)
      templateNamestringName of the template inside the template project
      templateAlias
      Since 1.5.7
      stringAlias of the deployed template. Must be used instead of `templateProjectPath` and `templateName` for deployed templates.
      datajson
      optional
      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:
        
              {}
          
      propertiesproduction properties descriptor
      optional
      The PDF production properties
      Production work directory request descriptor
      NameTypeDescription
      ...same as production request descriptor......same as production request descriptor......same as production request descriptor...
      pathstring (path)
      optional
      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
              
      Production response descriptor
      NameTypeDescription
      pathstring(path)Path to the produced PDF relative to work directory.
      report
      Since 1.4.1
      production report descriptorContains some meta information about created PDF
      Production properties descriptor
      NameTypeDescription
      pdfVersionstring (enum)
      optional
      Target PDF version. Valid values are:
      • 1.7 (default)
      • 2.0
      encryptionencryption properties descriptor
      optional
      If present specifies PDF encryption. No encryption by default:
      bookmarksbookmarks properties descriptor
      optional
      If present specifies properties for bookmarks generation. By default bookmark generation settings are fetched from template settings
      Encryption properties descriptor
      NameTypeDescription
      ownerPasswordstring (password)String used as owner password. Must be not empty
      userPasswordstring (password)
      optional
      String used as user password. Treated as absent if empty.
      printingAllowedboolean
      optional
      Allow printing when PDF is opened in user mode:
      • true (default)
      • false
      contentCopyingAllowedboolean
      optional
      Allow copying content when PDF is opened in user mode:
      • true (default)
      • false
      editingAllowedboolean
      optional
      Allow editing content (including editing annotations) when PDF is opened in user mode:
      • true
      • false (default)
      screenReaderAccessAllowedboolean
      optional
      Allow screen reader access when PDF is opened in user mode:
      • true (default)
      • false
      Bookmarks properties descriptor
      NameTypeDescription
      enabledbooleanFlag that determine whether bookmarks should be generated, must be "true" or "false"
      Production report descriptor
      NameTypeDescription
      idstring (uuid)
      autogenerated
      The ID of report
      pageCountinteger (64 bit)Number of pages in produced PDF
      templateRepairReportprocessing report descriptorObject containing information regarding fixed problems in template used for production
      pdfProductionReportprocessing report descriptorObject containing information regarding raised DITO related log messages during PDF production
      highestSeveritystring (enum)
      optional
      The highest severity level from both repair and production reports.
      Is
      null
      if both reports are empty.
      Possible values (from lowest to highest):
      • trace
      • debug
      • info
      • warn
      • error
      timestamp (Since 1.5.5)ISO-8601 formatted stringRepresents time when report was put in cache
      Processing report descriptor
      NameTypeDescription
      entrieslistList of report entry descriptors
      Report entry descriptor
      NameTypeDescription
      messagestringDescription of this entry
      severitystring (enum)String describing entry's severity.
      Possible values (from lowest to highest):
      • trace
      • debug
      • info
      • warn
      • error

      Pdf producer report resource

      Actions
      URIMethods
      /api/pdf-producer/report/{id}GET- gets cached report with specified as path parameter id
      Response type:
      application/json - production report descriptor
      Response codes:
      200 OK
      404 Not Found
      Since 1.5.5
      URIMethods
      /api/pdf-producer/reports/{id}GET- gets cached report with specified as path parameter id
      Response type:
      application/json - production report descriptor
      Response codes:
      200 OK
      404 Not Found
      URIMethods
      /api/pdf-producer/reportsGET- gets cached reports within specified timestamp
      Query params:
      • startTimestamp - date to start from
      • endTimestamp - end date (exclusive), can be optional (current date is a default value)
      Timestamps are ISO-8601 formatted dates (e.g. 2020-01-01T00:00:00Z)

      Response type:
      application/json - production report descriptors
      Response codes:
      200 OK
      400 Bad request

      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.

      URIMethods
      /api/deploymentsPOST- Deploy the template project with specified template and save it under the specified alias
      Query params:
      • forceReplace - true/false(default) - if true will replace template deployment with same alias if present.
      Request types:
      multipart/form-data Parts:
      • descriptor - application/json - template alias deployment request descriptor
      • templateProject - application/octet-stream - the content of template project
      Response type:
      application/json - added alias as template deployment response descriptor
      Response codes:
      200 OK
      401 Unauthorized
      400 Bad request
      400 Bad request
      /api/deploymentsGET- Returns list of all currently deployed templates with aliases
      Response type:
      application/json - list of template deployment response descriptors
      Response codes:
      200 OK
      401 Unauthorized
      /api/deployments/{alias}GET- Returns detailed information about deployed template with specified alias
      Response type:
      application/json - template deployment response descriptor
      Response codes:
      200 OK
      401 Unauthorized
      404 Not found
      /api/deployments/{alias}DELETE- Undeploy current template alias
      Response type:
      application/json - removed alias as template deployment response descriptor
      Response codes:
      200 OK
      401 Unauthorized
      404 Not found
      Template deployment request descriptor
      NameTypeDescription
      templateNamestringName of the template inside template project
      aliasstringAlias of the template deployment which can be later used during production
      metajsonAn additional JSON filed that is stored and can be retrieved when requesting template deployment.
      Can be an array, obejct, or leaf element.
      Template deployment response descriptor
      NameTypeDescription
      aliasstringAlias of the template deployment which can be later used during production
      metajsonAn additional JSON filed that is stored and can be retrieved when requesting template deployment.
      Can be an array, object, or leaf element.

      Registration resource

      Actions

      Only single user can be registered at ones.

      URIMethods
      /api/admin/registerPOST - Registers new user and returns authorization token.
      Only single user can be registered at one specific moment.
      Unable to register new user if there are any deployed templates with alias.
      Request type:
      application/json - the token request descriptor
      Response type:
      application/json - the token response descriptor
      Response codes:
      200 OK
      400 Bad request
      /api/admin/unregisterPOST - Unregisters user and returns authorization token.
      Unable to unregister user if there are any deployed templates with alias. They must be undeployed first.
      Request type:
      none
      Response type:
      application/json - the token response descriptor
      Request headers:
      Authorization: Bearer {token}
      Response codes:
      204 No Content
      400 Bad request
      401 Unauthorized
      /api/admin/statusGET - Verify passed authorization token and returns it.
      Request type:
      none
      Response type:
      application/json - the token response descriptor
      Request headers:
      Authorization: Bearer {token}
      Response codes:
      204 No Content
      400 Bad request
      401 Unauthorized
      Token request descriptor
      NameTypeDescription
      subjectstringSomething identifying the future user of Docker SDK.
      Token response descriptor
      NameTypeDescription
      tokenstringThe token that should be used for authorization.

      License resource

      Actions
      URIMethods
      /api/licenseGET- gets loaded license info
      Response type:
      application/json - license descriptor
      Response codes:
      200 OK
      License descriptor
      NameTypeDescription
      expirationDatedateExpiration UTC date in format:
      yyyy-MM-dd
      remainingdictionaryDictionary from limit type to long number of remaining events. Possible limit types:
      • document
      • page

      Status resource

      Actions
      URIMethods
      /api/statusGET- gets server status
      Response type:
      application/json - status descriptor
      Response codes:
      200 OK
      Status descriptor
      NameTypeDescription
      sdkVersionstringVersion of the iText DITO SDK in the format:
      major.minor.build
      apiVersionsAPI versions descriptorInformation about API versions.
      healthdictionaryThe dictionary with server health checks
      features
      Since 2.0.1
      objectStores information about different features which are enabled. Present if at least one feature information is present.
      userConfiguration
      Since 1.4.1
      objectStores information about user configuration used. Is in same format as application configuration file mentioned in the beginning of this ReadMe
      Features

      Description of different features which features section can be contained of

      templateDeployment
      FieldTypeDescription
      instanceRegisteredbooleanDetermines whether instance has registered user
      hasDeploymentsbooleanDetermines whether instance has deployed templates
      API versions descriptor

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

      NameTypeDescription
      defaultstringThe default API version that will be used if the X-DITO-API-Version header is not specified.
      maximumSupportedstringThe 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.
      minimumSupportedstringThe 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
      RequestResponse
      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
      RequestResponse
      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
      RequestResponse
      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
      RequestResponse
      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
      RequestResponse
      GET localhost:42/api/license
      200 OK
      Content-Type application/json
      Body
      {
          "expirationDate": "2020-09-23",
          "remaining": {
              "page": 999980
          }
      }
      User registration
      RequestResponse
      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


      RequestResponse
      POST localhost:42/api/deployments
      Content-Type multipart/form-data
      Authorization Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0In0.1DI6IZUGvCx_K_oxZ8lFuFBTHe-7shhqz77jSw18xkc
      Body
      Content-Type: multipart/form-data

      Content-Disposition: form-data; name="descriptor" Content-Type: application/json {"alias":"best template", "templateName":"output", "meta":{"version":"for tests"}}

      Content-Disposition: form-data; name="template_project" bytes of template project

      200 OK
      Content-Type application/json
      Body
      {
      "alias": "best template",
      "meta": {
      "version": "for tests"
      }
      }
      Produce PDF as stream from alias
      RequestResponse
      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.

      JavaScript errors detected

      Please note, these errors can depend on your browser setup.

      If this problem persists, please contact our support.