Deploying iText Suite SDK/API on Amazon Web Services

These instructions are for subscribers of the iText Suite (BYOL) on AWS Marketplace.

Deploying

ECS Task Definition

Create a new ECS Task Definition with the following properties:

EC2 Compatibility

In container definitions, fill in the correct container image address (e.g. 709825985650.dkr.ecr.us-east-1.amazonaws.com/itext-software/itext7suite:8.0.0.0). Please make sure you are using the latest version.

Use the desired port mapping 8080(host): 8080 (container).

Enable AWS CloudWatch logs to gain visibility over the container output.

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 your .XML or .JSON (depending on the iText Suite version) license file
get the Base64 encoding
set it as the value for the ENCODED_LICENSE Environment variable

Starting the ECS Service

Create a new ECS service based on the newly created task definition. If everything is properly configured, a new ECS task will start and your iText Suite service will be up and running (if it doesn't, make sure that you force the Task to run on your newly created EC2 instance).

ECS Task Running

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:

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

job key payload (request on /api/job/)

JS

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

would get the reply:

JS

{
    "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:

JS

{
    "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

job key payload (request on /api/job/)

JS

{
	"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.

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

BASH

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"'

BASH

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

BASH

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