Converting Documents

A DOCX upload that has to be archived as PDF, an HTML page that should become a Word document, an RTF file from an old system: the convert endpoint of the DocumentProcessing Web API turns a document into another format in one request. You send the document as a Base64 string, name the format you want in the returnFormat parameter and receive the converted document, again as Base64.

How Converting Works

The endpoint is POST /documentprocessing/document/convert:

The body is the JSON string alone, not an object around it. A JSON object as the body is refused with 400 "One or more validation errors occurred.", and the error names the cause: "The JSON value could not be converted to System.String." The source can be RTF, DOC, DOCX, HTML, PDF or TX, the TX Text Control format.

Every request needs an access token, as Authentication describes. The samples use the service URL http://localhost:5000 and the token in the variable TOKEN.

Convert a Document With curl

The following commands convert document.docx to PDF:

DS=http://localhost:5000
TOKEN="<access_token>"

# Wrap the Base64 string of the document in a JSON string
base64 -w 0 document.docx | jq -Rs . > document.json

curl --request POST "$DS/documentprocessing/document/convert?returnFormat=PDF" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data-binary @document.json \
  --output converted.json

# Decode the Base64 string of the response
jq -r . converted.json | base64 -d > document.pdf

The commands work as follows:

• base64 -w 0 encodes the file without line breaks, and jq -Rs . turns the encoded text into a JSON string with quotes. Writing the body to a file keeps large documents out of the command line.
• --data-binary @document.json sends the file unchanged as the request body.
• jq -r . removes the quotes of the JSON string in the response, and base64 -d decodes it into the PDF file.

On an unlicensed server, the endpoint answers 400 with the text "DS Server is not registered." instead of a document. Licensing shows how to register the server.

Convert a Document With .NET

The package TXTextControl.DocumentServices.DocumentProcessing sends the same request from C#. The following console application converts document.docx to PDF:

using TXTextControl.DocumentServices.DocumentProcessing;
using TXTextControl.DocumentServices.DocumentProcessing.OAuth;

var oauthSettings = new OAuthSettings("<client ID>", "<client secret>");
var documentProcessing = new DocumentProcessing("http://localhost:5000", oauthSettings);

byte[] document = await File.ReadAllBytesAsync("document.docx");

// Convert the document and save the result
byte[] pdf = await documentProcessing.Convert(document, ReturnFormat.PDF);
await File.WriteAllBytesAsync("document.pdf", pdf);

The code works as follows:

• The DocumentProcessing constructor takes the service URL and the OAuth settings and requests an access token with the credentials of the security profile.
• Convert takes the document as a byte array and returns the converted document as a byte array. The package does the Base64 encoding and decoding.
• ReturnFormat names the target format, with the same values as the returnFormat parameter of the Web API.

Convert has three overloads: with the document only, which returns PDF, with a ReturnFormat, and with a ReturnFormat and the flattenFormFields value. Install the package with dotnet add package TXTextControl.DocumentServices.DocumentProcessing; ASP.NET Core lists its methods.

Choose the Target Format

Set returnFormat to the format your application needs:

For example, ?returnFormat=DOCX converts an HTML page into a Word document. When DS Server runs on Linux, it supports the document formats DOCX, HTML, PDF and XLSX only, so DOC, RTF, TX and TXT are outside its documented support. Supported File Formats lists the formats per endpoint and the limits of Linux.

For a PDF with a digital signature, embedded files, passwords or access permissions, use the pdf/create endpoint instead, described in PDF Documents.

Flatten Form Fields

A document with form fields, such as a filled-in application form, keeps its fields when it is converted. To replace every form field by its current value, add flattenFormFields=true:

curl --request POST "$DS/documentprocessing/document/convert?returnFormat=PDF&flattenFormFields=true" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data-binary @document.json \
  --output converted.json

In C#, pass the value as the third argument of Convert:

byte[] pdf = await documentProcessing.Convert(document, ReturnFormat.PDF, true);

PDF Form Fields reads the fields of an existing PDF form.

Convert in Other Languages

The request is plain HTTP with a JSON body, so any language that sends HTTP requests converts documents the same way: read the file, encode it as Base64, send it as a JSON string with the Authorization header and decode the Base64 string of the response. Keep the client secret and the token on the server; don't send these requests from code that runs in a browser.

Next Steps

• Merging Templates: create documents from a template and JSON data.
• Appending Documents: combine several documents into one.
• PDF Documents: create PDF and PDF/A documents with signatures and attachments.
• Errors and Status Codes: what to do when a request is refused.