Deploying iText Suite SDK/API on Amazon Web Services

These instructions are for subscribers of the iText Suite (BYOL) on AWS Marketplace. You will need to subscribe to the service before following the steps below.

Deploying

We will be using eu-central-1 for these examples. Please adjust according to your area.

Clusters

The first step to deploying the Service is setting up the required environment. To begin setting up this environment, you will need to set up a Cluster within the Amazon Elastic Container Service. You can find this configuration at the following URL:

https://eu-central-1.console.aws.amazon.com/ecs/v2/clusters?region=eu-central-1

The most important configuration for your Cluster is to use Amazon EC2 Instances. It is important to select an appropriate ECS Instance Type that can accommodate your expected transaction volume.

Cluster configuration and Infrastructure

ECS Task Definition

After you’ve defined where to run the Service, you need to create an ECS Task definition to specify what you will be running. The URL for the ECS Task definition should be:

https://eu-central-1.console.aws.amazon.com/ecs/v2/task-definitions?region=eu-central-1

Your task definition will define the environment in which the iText Suite Docker container will be executed. You can see an example of a definition in the screenshot below. Some of the arguments that you should be aware of::

Launch type: Amazon ECS instances, as defined in your Cluster.
Network mode: Docker uses bridge by default under Linux, but we specify it anyway.
Task size: Out of the ECS instance you have defined on your Cluster configuration, how much of it should be used by the Docker container.

Container Specific Configurations

Container Image URI

Below you will find Container specific configurations.

For the Container Image URI, you should use the URL for the version you would like to use that you were provided with when you subscribed on the Marketplace. At the time of writing, the latest version is:

709825985650.dkr.ecr.us-east-1.amazonaws.com/itext-software/itext7suite:8.0.5.0

This address should always follow this format; itext7suite:8.0.5.x
The latest available iText version (in this example: 8.0.5), followed by a .x (in this example: .0).

This enables you to make adjustments specific to this Docker container, and not to the product itself.

Port mappings

The Docker container will listen by default on port 8080 (Container port), so make sure you expose that port on your instance (Host port). You can choose whatever port you want, it is important to make sure to remember it when you make the requests for this service.

iText License Key

And finally, very importantly, this is where you will set your iText License key.

The way you do it is by setting up an Environment Variable called ENCODED_LICENSE, where its value is a Base64 encoded string of a zip of the license key. So:

zip the JSON license file,
get the Base64 encoding (of the ZIP file, not the license key itself),
set it as the value for the ENCODED_LICENSE Environment variable.

Container configuration and Environment variables (license key)

Create Cluster Service

After the Cluster and the Task is defined, all that’s left to do is to fire up the Service that will bring everything together.

Launch Type: use EC2, as specified in your Cluster (don’t forget to pick the Cluster you’ve configured earlier)
Application Type: this would typically be a Service, as it will be waiting for requests to come in

Environment and Deployment configuration

After this step, you need to wait a few minutes, and your Service should be up and running!

You should then be able to check the Infrastructure that was deployed by your configured Cluster, so you get access to the IP address.

Using the iText Suite HTTP API

After the iText Suite REST API has been deployed, you can access the Swagger documentation from /api/swagger-ui.html which should look something like this:

You can also get access to this documentation by posting the content of the file api-docs.json to https://editor.swagger.io/.

Generally speaking, all of the available requests operate in a similar fashion:

you upload a file and specify what you want to do with it,
you query the system to see if the process has already been completed,
you download the end result.

Examples

Converting PDF to Image

request on /api/job/

Request Payload (PDF to Image conversion)

CODE

{"request": {
"type":"PDF_TO_IMAGES",
"imageType":"JPEG",
"pageNumbers":"1",
"defaultPageScaling":1
},
"sourceFiles":
[{
"checksum":"0f96c60805d8df8d57b8411f17d03925",
"fileType":"application/pdf",
"fileSize":76478,
"fileName":"Demo invoice.pdf"}]
}

Expected Reply (PDF to Image conversion)

CODE

{
    "id": "7a970947-9e44-4e20-956d-be9d42cecea5",
    "status": "PROCESSING",
    "sourceFiles": [
        {
            "id": "cdb3f514-219b-443e-8869-0671281ac753",
            "checksum": "0f96c60805d8df8d57b8411f17d03925",
            "fileType": "application/pdf",
            "fileSize": 76478,
            "fileName": "Demo invoice.pdf"
        }
    ],
    "request": {
        "type": "PDF_TO_IMAGES",
        "imageType": "JPEG",
        "pageNumbers": "1",
        "pageScaling": 1.0
    }
}

Check the job status on (/api/job/{id}) until it has FINISHED:

CODE

{
    "id": "7a970947-9e44-4e20-956d-be9d42cecea5",
    "status": "FINISHED",
    "resultFile": {
        "id": "23269d9f-9282-4d3b-90de-7725c8f1741e",
        "checksum": "2499414f1b25ea19519af713bbfbd2ec",
        "fileType": "application/zip",
        "fileSize": 39287
    },
    "request": {
        "type": "PDF_TO_IMAGES",
        "imageType": "JPEG",
        "pageNumbers": "1",
        "pageScaling": 1.0
    }
}

and then you can get the actual file (/api/job/{id}/file/result)

Converting HTML to PDF

request on /api/job/

Request Payload (HTML to PDF conversion)

CODE

{
	"sourceFiles": [
		{
			"id": "6970e33b-4818-4971-901a-8e176d4eab47",
			"checksum": "df0d9090d1905886aa6ebc5dd91299d4",
			"fileType": "text/html",
			"fileSize": 2140,
			"fileName": "html-to-pdf.html"
		}
	],
	"request": {
		"type": "HTML_TO_PDF"
	}
}

and then just follow the workflow described above for "Converting PDF to Image" (checking job status, and downloading the resulting file).

If you use Postman, you can also load this collection for some examples. This should save you some time.

For curl users, here are some examples around the HTML to PDF actions:

curl command for HTML to PDF action

CODE

curl --location --request POST 'http://url/api/job/' \
--form 'job="{
	\"sourceFiles\": [
		{
			\"id\": \"6970e33b-4818-4971-901a-8e176d4eab47\",
			\"checksum\": \"e7b71a73bd854d1aa35bfeba856e02a6\",
			\"fileType\": \"text/html\",
			\"fileSize\": 15,
			\"fileName\": \"html-to-pdf.html\"
		}
	],
	\"request\": {
		\"type\": \"HTML_TO_PDF\"
	}
}";type=application/json' \
--form 'file=@"html-to-pdf.html"'

And then you can retrieve the status of your action

BASH

curl --location --request GET 'http://url/api/job/8ee09bd0-1fab-48b6-a5cc-ab30847e59bf'

And finally the result of your action

BASH

curl --location --request GET 'http://url/api/job/8ee09bd0-1fab-48b6-a5cc-ab30847e59bf/file/result'