Appending Documents

A cover letter in front of an invoice, terms and conditions after a contract, a set of reports in one PDF: the append endpoint of the DocumentProcessing Web API combines several documents into one. You list the documents in order, choose for each how it is separated from the one before it, and receive the combined document in the format you need.

How Appending Works

The endpoint is POST /documentprocessing/document/append. Its JSON body, the AppendBody, has two properties:

Each AppendDocument has these properties:

The query parameter returnFormat sets the format of the result: PDF, PDFA, DOCX, DOC, RTF, HTML, TX or TXT, with PDF as the default. The response is the combined document as a Base64 string in a JSON string. A body without documents is refused with 400.

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.

Append Documents With curl

The following commands put document.docx, a cover letter, in front of invoice.pdf and start the invoice in a new section:

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

# Build the AppendBody from the two documents
jq -n \
  --rawfile first <(base64 -w 0 document.docx) \
  --rawfile second <(base64 -w 0 invoice.pdf) \
  '{documents: [{document: $first}, {document: $second, documentDivider: 3}]}' > append.json

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

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

The commands work as follows:

• Each --rawfile reads the Base64 string of one file into a jq variable, and the filter writes the documents array with them to append.json.
• The first document needs no divider. documentDivider: 3 on the second one inserts a new section before it.
• jq -r . removes the quotes of the response, and base64 -d decodes the combined document.

Append Documents With .NET

In the package TXTextControl.DocumentServices.DocumentProcessing, the body is an AppendBody with an array of AppendDocument objects:

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);

var appendBody = new AppendBody
{
    Documents = new[]
    {
        new AppendDocument { Document = await File.ReadAllBytesAsync("document.docx") },
        new AppendDocument
        {
            Document = await File.ReadAllBytesAsync("invoice.pdf"),
            DocumentDivider = DocumentDivider.NewSection
        }
    }
};

byte[] combined = await documentProcessing.Append(appendBody, ReturnFormat.PDF);
await File.WriteAllBytesAsync("combined.pdf", combined);

The code works as follows:

• AppendDocument.Document takes a document as a byte array; the package encodes it.
• DocumentDivider takes the values None, NewParagraph and NewSection of the enumeration of the same name.
• Append returns the combined document as a byte array. The overload without a ReturnFormat takes the AppendBody alone and creates PDF.

Choose the Divider

The divider decides how a document continues the one before it:

A section is a part of a document with its own page settings, such as the page size, the margins and the headers and footers. Sections of TX Text Control .NET Server explains how sections divide a document.

Set the Document Properties

The optional documentSettings object sets the properties of the combined document:

Add the object to the filter of the jq command:

jq -n \
  --rawfile first <(base64 -w 0 document.docx) \
  --rawfile second <(base64 -w 0 invoice.pdf) \
  '{
    documents: [{document: $first}, {document: $second, documentDivider: 3}],
    documentSettings: {documentTitle: "Invoice", author: "Sales Department"}
  }' > append.json

In C#, set the DocumentSettings property of the AppendBody to a DocumentSettings object with the properties DocumentTitle, DocumentSubject, Author, CreatorApplication, CreationDate, LastModificationDate and UserPassword:

appendBody.DocumentSettings = new DocumentSettings
{
    DocumentTitle = "Invoice",
    Author = "Sales Department"
};

Combine Merged Documents

The documents to append can come from other endpoints. For example, merge a template with the merge endpoint in the TX format, then append a cover letter in front of the merged document and create the PDF in the same request. Each document in the response of the merge endpoint is a Base64 string, so it goes into the document property of an AppendDocument as it is.

Next Steps

• Merging Templates: create the documents to combine from a template and data.
• Converting Documents: convert a single document to another format.
• Thumbnails: render page images of the combined document.
• Errors and Status Codes: what to do when a request is refused.