POST /v1/document/findandreplace
POST https://api.reporting.cloud/v1/document/findandreplace
Description
Replaces text in a template and returns the result as a document. The request body holds pairs of a text to find and its replacement; the template is a stored one, named in templateName, or one sent in the body as a Base64 string. Every occurrence is replaced, without regard to case and also inside words. The response is the document as a Base64 string, in the format returnFormat names, PDF by default. To fill merge fields with data, use POST /v1/document/merge instead. See Find and Replace.
Warning
Document Quota. Each successful request counts 1 against the document quota. On a trial account, a test run (
test=true) counts as well. Plans and Licensing lists the quota of each plan.
Examples
Request:
curl username:password \
"Content-Type: application/json" \
\
" \
{
\"findAndReplaceData\": [
[
\"%%Test%%\",
\"ReplacedString\"
]
],
\"template\": null,
\"mergeSettings\": null
}
" \
POST "https://api.reporting.cloud/v1/document/findandreplace?templateName=replace.tx"
Results:
"JVBERi0xLjQNJeLjz9MNMSAwIG9iago8PAovVH..."
Request:
using System;
using System.Collections.Generic;
using TXTextControl.ReportingCloud;
ReportingCloud rc = new ReportingCloud("username", "password");
FindAndReplaceBody body = new FindAndReplaceBody();
body.FindAndReplaceData = new List<string[]> {
new string[] { "Invoice", "ReplacedText" } };
byte[] bDocument = rc.FindAndReplaceDocument(body, "invoice.tx", ReturnFormat.HTML);
string sHtmlDocument = System.Text.Encoding.UTF8.GetString(bDocument);
Console.WriteLine(sHtmlDocument.Contains("ReplacedText"));
Results:
True
Request:
import com.textcontrol.reportingcloud.FindAndReplaceBody;
import com.textcontrol.reportingcloud.ReportingCloud;
import com.textcontrol.reportingcloud.ReturnFormat;
import javafx.util.Pair;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;
public class ReportingCloudSample {
public static void main(String[] args) throws IOException {
List<Pair<String, String>> findAndReplaceData = new ArrayList<>();
findAndReplaceData.add(new Pair<>("%%Test%%", "ReplacedString"));
ReportingCloud r = new ReportingCloud("username", "password");
byte[] pdfData = r.findAndReplace(new FindAndReplaceBody(findAndReplaceData), "replace.tx", ReturnFormat.PDF);
String pdfFileName = "replaced.pdf";
Files.write(Paths.get(pdfFileName), pdfData);
System.out.println("Document written to " + pdfFileName + ".");
}
}
Results:
Document written to replaced.pdf.
FindAndReplaceBody takes its pairs as javafx.util.Pair, so the sample needs JavaFX on the class path, as Java explains.
Request:
#!/usr/bin/env ruby
require "txtextcontrol/reportingcloud"
require "base64"
reporting_cloud = TXTextControl::ReportingCloud::ReportingCloud.new("username", "password")
find_and_replace_body = TXTextControl::ReportingCloud::FindAndReplaceBody.new([["%%Test%%", "ReplacedString"]])
find_and_replace_result = reporting_cloud.find_and_replace(find_and_replace_body, "replace.tx")
pdf_file_name = "replaced.pdf"
File.open(File.dirname(__FILE__) + "/#{pdf_file_name}", 'wb') do |f|
f.write(Base64.strict_decode64(find_and_replace_result))
end
puts "Document written to #{pdf_file_name}."
Results:
Document written to replaced.pdf.
Request:
require_once __DIR__ . '/vendor/autoload.php';
use TextControl\ReportingCloud\ReportingCloud;
$reportingCloud = new ReportingCloud([
'api_key' => (string) getenv('REPORTINGCLOUD_API_KEY'),
]);
$findAndReplaceData = [
'%%Test%%' => 'ReplacedString',
];
$destinationFilename = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'replace.pdf';
$binaryData = $reportingCloud->findAndReplaceDocument($findAndReplaceData, 'PDF', 'replace.tx');
file_put_contents($destinationFilename, $binaryData);
var_dump("Written document to {$destinationFilename}");
Results:
string(36) "Written document to /tmp/replace.pdf"
Authorization
This endpoint requires a "ReportingCloud-APIKey" or a "Basic" user authorization to access the user account, data and templates. Only one of these two methods is required.
API Keys describes how to create an API key, and Authentication explains both header forms.
ReportingCloud-APIKey
| Header field | Description |
|---|---|
| Authorization | Required. A valid ReportingCloud account is required. The Authorization field is constructed as follows: An API key needs to be generated in the portal or with PUT /v1/account/apikey. The authorization method and a space, "ReportingCloud-APIKey ", is then put before the actual API key string. For example: Authorization: ReportingCloud-APIKey oMDM4MrAqL9QEOpyzupnQW5NjvCNtvE5cVDaaLqxI |
Basic
| Header field | Description |
|---|---|
| Authorization | Required. A valid ReportingCloud account is required. The Authorization field is constructed as follows: The user name and password are combined into a string separated by a colon, for example username:password. The resulting string is encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line. The authorization method and a space, "Basic ", is then put before the encoded string. For example: Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l |
Request Parameters
| Name | Type | Value | Optional |
|---|---|---|---|
| returnFormat | String | A string that specifies the format of the created document. Possible values are: PDF, PDFA, RTF, DOC, DOCX, HTML, TXT and TX, in any letter case. The default value is PDF. PDFA requires an Extreme license. | yes |
| templateName | String | The name of the template in the template storage, with its file extension, in any letter case. If no template is specified, the template must be uploaded in the FindAndReplaceBody object of this request. If both are given, the template from the template storage is used and the uploaded one is ignored. | yes |
| test | Boolean | Specifies whether it is a test run or not. Created documents contain a "TEST MODE" watermark. Unlike a test run of convert or append, a test run of this endpoint is counted against the document quota of a trial account. Not possible using the Free license. The default value is false. | yes |
Request Payload
| Type | Value |
|---|---|
| ReportingCloud FindAndReplaceBody object | The FindAndReplaceBody object contains a JSON array of string arrays, a template encoded as a Base64 string and a ReportingCloud MergeSettings object. |
FindAndReplaceBody
| Name | Type | Value | Optional |
|---|---|---|---|
| findAndReplaceData | JSON array | The find and replace pair values as a JSON array of string arrays. In each pair, every occurrence of the first string, in any letter case and also inside words, is replaced by the second. If the second string is empty, the first is deleted. The find string must not be empty. | no |
| template | Base64 encoded string | The template encoded as a Base64 string. Supported formats are RTF, DOC, DOCX, TX, HTML, PDF, XLSX and plain text. If it is null or an empty string and no templateName is given, an empty document is returned. | yes |
| mergeSettings | ReportingCloud MergeSettings object | Optional merge settings to specify merge properties and document properties such as title and author. | yes |
MergeSettings
| Name | Type | Value | Optional |
|---|---|---|---|
| removeEmptyFields | Boolean | Specifies whether empty fields should be removed from the template or not. Has no effect on this endpoint. | yes |
| removeEmptyBlocks | Boolean | Specifies whether the content of empty merge blocks should be removed from the template or not. Has no effect on this endpoint. | yes |
| removeEmptyImages | Boolean | Specifies whether images which don't have merge data should be removed from the template or not. The default value is false. | yes |
| removeTrailingWhitespace | Boolean | Specifies whether trailing whitespace should be removed before saving a document. Has no effect on this endpoint. | yes |
| mergeHtml | Boolean | Specifies whether field data can contain formatted HTML content or not. The default value is false. HTML content must be enclosed in an <html> tag element. Only active in the Merge endpoint. | yes |
| author | String | Sets the document's author. | yes |
| creationDate | DateTime (String) | Sets the document's creation date which will be saved in the document. | yes |
| lastModificationDate | DateTime (String) | Sets the date the document is last modified. | yes |
| creatorApplication | String | Sets the application, which has created the document. | yes |
| documentSubject | String | Sets the document's subject string which will be saved in the document. | yes |
| documentTitle | String | Sets the document's title that will be saved in the document. | yes |
| userPassword | String | Specifies the password for the user to open the document. | yes |
| culture | String | Specifies the culture for the merge process for date and currency values. It must be a Language Culture Name of Microsoft's Table of Language Culture Names, Codes, and ISO Values. For French use "fr-FR", for German "de-DE". Default is English "en-US". Has no effect on this endpoint. | yes |
Success Response
| Status | Description |
|---|---|
| 200 | On success, the HTTP status code in the response header is 200 (OK). The response body contains the created document encoded as a Base64 encoded string. |
Error Response
| Status | Description |
|---|---|
| 400 | A 400 (Bad Request) is returned, if no data is found in the FindAndReplaceBody object, findAndReplaceData is null, a find and replace pair has only one string, an empty find string or a null replacement, the template is left out and no templateName is given, the template is not found in the template storage or returnFormat is not one of the possible values. |
| 403 | A 403 (Forbidden) is returned, if the user is not authorized, the document quota is exceeded or the return format PDFA is requested without an Extreme license. |
| 405 | A 405 (Method Not Allowed) is returned, if the request uses another HTTP method than POST. The Allow header of the response names POST. |
| 411 | A 411 (Length Required) is returned, if the request has neither a body nor a Content-Length header. |
| 415 | A 415 (Unsupported Media Type) is returned, if the request has a body but no Content-Type header, or a Content-Type such as text/plain that the endpoint doesn't read. Send Content-Type: application/json. |
| 500 | A 500 (Internal Server Error) is returned, if the request has no Authorization header, an empty one or one that is not the authorization method, a space and the credentials, or if the body is null or doesn't have the shape of a FindAndReplaceBody object, the template is not a valid Base64 string or returnFormat is empty. |
Timeout Limitation. The pure processing time is limited to a maximum of 60 seconds. After this period of time, the task is canceled.
A typical document should not take more than 5 seconds. If your request takes longer, reduce the size of the template.