Architecture

What happens between your application's request to ReportingCloud and the PDF that comes back? The service has three public parts, the Web API, the ReportingCloud portal and the status page, and the Web API and the portal share one template storage per account. Knowing how they connect, and which part runs where, helps you decide where templates live and what your own code has to do. The sections below follow a merge request through the service.

Architecture at a Glance

Your side                                    Text Control, hosted on Microsoft Azure

Backend, script or SDK  --HTTPS, JSON---->   Web API  https://api.reporting.cloud/v1/
                                               |
                                               +--> TX Text Control document engine
                                               |
                                               +--> Template storage of your account
                                                      ^
                                                      |
Browser: you and your   --HTTPS---------->   Portal  https://portal.reporting.cloud/
template designers                             template editor, datasource excerpts,
                                               API keys, transactions, statistics

Browser                 --HTTPS---------->   Status page  https://status.reporting.cloud

• Only your client runs on your side. Your backend, a script or one of the SDKs sends the requests. The document engine, the storage and the portal run at Text Control.
• One account, one storage. A template that you upload or design in the portal is the template that a merge request names, and a template uploaded with the Web API appears in the portal.
• HTTPS everywhere. The Web API, the portal and the status page are reached over HTTPS.

The Web API

The Web API is a REST API at the base address https://api.reporting.cloud/. Every endpoint is below the version path /v1/, for example https://api.reporting.cloud/v1/document/merge, and is called with one of the HTTP methods GET, POST, PUT or DELETE. The reference groups the endpoints like this:

How requests and responses are built:

• JSON in and out. A request body is JSON: a body object such as MergeBody, or a document as a Base64 string. A response carries documents and images as Base64 strings, for example an array with one string per merged document.
• Query parameters set the options of a request, such as returnFormat, templateName and test.
• HTTPS only. The Web API is served over HTTPS. A plain HTTP connection to api.reporting.cloud on port 80 isn't answered.
• Authentication. Every request carries an Authorization header, either with an API key (ReportingCloud-APIKey) or with the user name and password of the account (Basic). Authentication shows both.
• CORS. The Web API answers with the header Access-Control-Allow-Origin: *, so JavaScript on a web page of any origin may call it. A script in the browser has to send your credentials, though, which makes them visible to the users of the page. Data Security and Privacy explains how to keep them on your server.
• Limits. The endpoints that create documents or thumbnails limit the processing time of a request to 60 seconds and cancel the task after that. A typical document takes less than 5 seconds. A merge request is refused when more than two requests of the same account come in at the same time. Errors and Status Codes lists the responses.

The Portal

The portal at https://portal.reporting.cloud/ is where you manage what the Web API uses. Its dashboard shows your recent activities, the service status and your quota usage. In the portal, you:

• upload, create, edit and delete the templates of your storage, and copy samples from the Sample Template Gallery into it;
• design templates in the template editor, the MS Word compatible editor of TX Text Control, which takes its lists of merge fields and merge blocks from a datasource excerpt;
• create and edit datasource excerpts, sample JSON in the format of your merge data;
• manage your subscription and your API keys, and see your quota settings;
• follow the transactions of the current month in the Transaction Monitor and the monthly usage in Statistics.

With the Extreme plan, you can also create groups of templates and invite external template designers into them. Portal describes each page.

Template Storage

Each account has a template storage that the Web API and the portal share. A merge or find and replace request takes its template from the storage or from its own body:

Text Control recommends the storage for templates that you merge again and again. The other endpoints of the Document group, POST /v1/document/convert, POST /v1/document/append and POST /v1/document/thumbnails, as well as the tracked changes endpoints, take the document in the request body and don't use the storage. Template Storage covers the storage in the portal, and Managing Templates covers its endpoints.

How a Merge Request Is Processed

A merge is the most common request. It runs through these steps:

1. Your application sends POST /v1/document/merge with the returnFormat parameter and either the templateName parameter or the template in the request body. The mergeData property of the body holds the data: a JSON array with one object per record, or a single object for one record.
2. ReportingCloud loads the template from your storage, or decodes the template that came with the request.
3. The engine fills each merge field with the value of the JSON property of the same name, and repeats each merge block for the items of the array of the same name.
4. The response is a JSON array of Base64 strings. By default, the documents of all records are appended into one; with append=false, every record becomes a document of its own.
5. The merge data and the created documents are not kept. ReportingCloud logs the metadata of the transaction, from which the portal shows the transaction and counts your document quota.

Overview in the Mail Merge section describes merging in detail.

SDKs

The SDKs for .NET, PHP, Java and Ruby are wrappers around the Web API: they send the HTTP requests the reference describes and give you classes and methods to manage templates and merge documents. The endpoints, limits and quotas described above apply to them in the same way. SDKs compares them, and Installing an SDK installs them.

Hosting and Availability

• Microsoft Azure. ReportingCloud is hosted on Microsoft Azure. Where your data is processed is described in Data Security and Privacy.
• Status page. https://status.reporting.cloud shows the availability of three areas, the Web API, the portal and the backend, and lists reported incidents with their updates.
• Maintenance. In the services agreement, Text Control commits to reasonable efforts to keep the service available 24 hours a day, 7 days a week, and states that maintenance, updates and repairs can interrupt it.
• Hosting it yourself. The services agreement asks you to contact Text Control if you want to host your own ReportingCloud service. For document processing on your own servers, Text Control offers DS Server.

Based on TX Text Control

The Web API and the portal run on TX Text Control, and the portal's template editor is the HTML5 editor of TX Text Control .NET Server. Text Control has moved the service to new TX Text Control releases: X14 Service Pack 1 reached the portal and the Web API in February 2017, X15 in January 2018 and X16 in January 2019. It has been updated since: the PDF documents that the service created in October 2026 name tx_pdf 28.0.353.500, TX Text Control 28.0, as their producer. The blog article ReportingCloud: Backend Updated to TX Text Control X16 describes the upgrade to X16, and Older Versions in What's New lists what each one brought.

Next Steps

• Supported File Formats: the formats each endpoint reads and returns.
• Data Security and Privacy: what the service stores and where it runs.
• Authentication: the two ways a request authenticates.
• Portal: the pages of the portal.
• Web API: every endpoint with its parameters and responses.