How to upgrade from iText DITO 1.5 to iText DITO 2.0?

Introduction

This quick guide aims to help you upgrade to iText DITO 2.0 without losing any of the templates you have created in version 1 of the product. Please note that the upgrade path iText supports is from version 1.5 to version 2.0. If you are using version 1.0-1.4, please upgrade to version 1.5 first.

Export your iText DITO 1.5 templates

An important aspect of updating to iText DITO 2.0 is to make sure that rework on existing template is minimal. For that reason, step one of the process is to make sure that you have the necessary *.dito files to import all the data samples, templates, images and stylesheets from your current iText DITO projects. Probably you have *.dito files for all your projects in the folder structure of your SDK instance(s). If you are working on a template iText DITO Editor, you can create a *.dito from it by choosing the Export option from the Project menu. (Working with Projects)

Optimize your *.dito files for import

*.dito files are ready for import into iText DITO Manager if they contain one single data sample. They can contain multiple templates that are associated with that data sample and multiple resources (images, stylesheets, fonts).

Projects that contain multiple samples are not ready for import. There are two ways to address this problem:

Using iText DITO Editor

Import a *.dito project with multiple data samples in iText DITO Editor.
Determine which template(s) in the project is/are associated with which data sample.
Choose a data sample to keep and remove all other data samples.
Delete all templates that are not associated with the sample you chose to keep.
Save and export the package with a new name.
Repeat the above steps for a different sample in the project file, until you end up with multiple *.dito files, each of which have only one data sample

Using file explorer

Rename a *.dito project with multiple data samples to *.zip.
Unpack the *.zip archive
Determine which *.html template(s) in the templates subdirectory is/are associated with which *.json file in the data subdirectory.
Choose a *.json to keep and remove all other *.json files from the data subdirectory.
Delete all template files from the templates subdirectory that are not associated with the *.json file you chose to keep.
Select the data, templates and resources subdirectory and add them to a compressed *.zip archive with a new name.
Change the file extension of the new file from *.zip to *.dito.
Repeat the above steps for a different *.json file in the original archive, until you end up with multiple *.dito files, each of which contains only one *.json file in the data subdirectory.

Deploy iText DITO 2.0

Follow the instructions on Installation Guidelines to deploy your new iText DITO 2.0 environment.

Configure your iText DITO 2.0 workspace

Open iText DITO Manager and login with the global administrator credentials you provided during the deployment. The workspace initialization wizard will start automatically to take you through the workspace set-up process. Follow the steps on {{WORKSPACE INITIALIZATION}} to prepare iText DITO Manager for first use.

Import your templates

Choose Import template in the Template Management section of iText DITO Manager. Import all your optimized *.dito projects. The import process will automatically create:

a data collection and a data sample from the detected sample;
a standard template from each of the detected templates;
an image resource from each of the detected images;
a stylesheet resource from each of the detected stylesheets.

Font resources will not be imported from the *.dito files you upload. There is no longer any need to upload *.ttf font files as resources in the individual templates and declare fonts in a stylesheet. In iText DITO 2.0, you can simply create a font resource in iText DITO Manager, and the uploaded font will be available for all templates in the workspace.

Upon import, when items are discovered in a *.dito package which already exist in iText DITO Manager, you will be presented with two options:

Either you create a new version of the already existing item;
Or, you create a new item with a different name.

Define a promotion path

All the imported templates are created in the SDK instance with the development role. In order to promote them to other instances with different roles (UAT, production, etc) you need to create a {{PROMOTION PATH}}.

You can then {{PROMOTE VERSIONS OF YOUR TEMPLATES}} along the stages of the promotion path.

Update your PDF generation code

Where-ever you are using the iText DITO 1.5 Java SDK or the iText DITO 1.5 REST API for Docker, update your code to target the endpoints of the iText DITO 2.0 REST SDK for Docker. For detailed information on how to use the REST SDK please check the REST API Reference.