Ruby

Ruby scripts and applications can merge templates and manage the template storage through the gem txtextcontrol-reportingcloud. It provides the class TXTextControl::ReportingCloud::ReportingCloud, whose methods send the requests of the Web API with Ruby's standard library and return the parsed results. A script that merges the demo template shows the gem at work, and a table maps each of its methods to its endpoint.

The gem has had no release since March 2019. It authenticates with the user name and password of the account only, returns documents as Base64 strings and has no methods for the thumbnails of a document, sharing or tracked changes. For these, call the Web API directly, as Web API in Getting Started shows with curl.

Ruby in Getting Started builds a first script with the gem step by step.

Gem and Requirements

Add the gem to the Gemfile of your application and run bundle, or install it with RubyGems:

gem install txtextcontrol-reportingcloud

Installing an SDK has the details and a first call that checks the installation.

Authentication

The gem sends every request with Basic authentication. It has no option for an API key, so it needs the user name and password of your ReportingCloud account. The constructor is ReportingCloud.new(username, password, base_url = nil); without base_url, the requests go to https://api.reporting.cloud. The instance has the attributes username, password, base_uri, api_version, which is "v1", and read_timeout, the timeout of a request in seconds, which is 10. Authentication explains Basic authentication and why API keys are recommended for the Web API.

Merge a Template

The following script merges sample_invoice.tx, the demo template in the template storage of every trial account, with one invoice record and saves invoice.pdf. It reads the credentials from the environment variables REPORTINGCLOUD_USERNAME and REPORTINGCLOUD_PASSWORD:

require "base64"
require "txtextcontrol/reportingcloud"
require "txtextcontrol/reportingcloud/merge_body"
require "txtextcontrol/reportingcloud/merge_settings"

# The Ruby SDK authenticates with the user name and password of the account
reporting_cloud = TXTextControl::ReportingCloud::ReportingCloud.new(
  ENV["REPORTINGCLOUD_USERNAME"], ENV["REPORTINGCLOUD_PASSWORD"])

# One record with the fields and the item block of sample_invoice.tx
merge_data = [
  {
    "invoice_no" => "778723",
    "billto_name" => "Joey Montana",
    "billto_companyname" => "Montana, LLC",
    "item" => [
      { "qty" => "1", "item_no" => "1", "item_description" => "Item description 1", "item_total" => "2130.40" },
      { "qty" => "1", "item_no" => "2", "item_description" => "Item description 2", "item_total" => "5543" }
    ],
    "total" => "8210.538"
  }
]

merge_settings = TXTextControl::ReportingCloud::MergeSettings.new
merge_settings.document_title = "Invoice 778723"
merge_body = TXTextControl::ReportingCloud::MergeBody.new(merge_data, merge_settings)

begin
  # Merge the stored template; the documents come back as Base64 strings
  documents = reporting_cloud.merge_document(merge_body, "sample_invoice.tx", :pdf)
  File.binwrite("invoice.pdf", Base64.strict_decode64(documents[0]))
  puts "invoice.pdf has been written."
rescue RuntimeError => error
  # The message is the response body of the failed request
  puts error.message
end

The code works as follows:

• require "txtextcontrol/reportingcloud" loads the main class. MergeBody and MergeSettings are in files of their own and are required separately.
• MergeBody.new(merge_data, merge_settings = nil, template = nil) takes the records as a non-empty array of hashes, whose keys are the merge field names; a nested array such as item fills a merge block. template, a Base64-encoded template, replaces the template name. Merge Data describes the structure.
• merge_document(merge_body, template_name = nil, return_format = :pdf, append = false, test = false) sends the request to POST /v1/document/merge. Passing a template name together with template data, or neither, raises an ArgumentError.
• The method returns an array of Base64 strings, one for each created document, which Base64.strict_decode64 turns into the binary file.

A new MergeSettings has remove_empty_fields, remove_empty_blocks, remove_empty_images and remove_trailing_whitespace set to true and merge_html set to false, and the gem sends all five. remove_empty_images is therefore true, while the Web API's default is false. There is no attribute for the culture. The other attributes are those of DocumentSettings: author, creator_application, document_subject, document_title, user_password, creation_date and last_modification_date. Merge Settings describes every setting.

ReportingCloud Methods

Return formats and image formats are symbols, such as :pdf, :docx or :png. Documents and templates go in and come back as Base64 strings.

append_documents, convert_document and find_and_replace take a test argument as well. The API key methods manage the keys of the account; the gem itself still signs in with the user name and password.

Errors

When the Web API answers with an error, a method raises a RuntimeError whose message is the response body; the HTTP status code isn't part of it. Arguments the gem rejects before sending, such as merge data that isn't an array of hashes or an empty text for check_text, raise an ArgumentError. Errors and Status Codes lists the status codes and their causes.

API Documentation and Source

• API documentation. The YARD documentation describes every class, attribute and method of the gem. The README in the repository shows how to build it with yard doc.
• Source code. The repository TextControl/txtextcontrol-reportingcloud-ruby holds the source under a BSD license, with RSpec tests. Its code was last changed on March 4, 2019, for version 1.2.1; a change to the README followed in December 2020.

Related Pages

• SDKs: the SDKs compared, with their status.
• Installing an SDK: the installation of each SDK.
• Ruby in Getting Started: a first script that merges a template to PDF.
• Web API: the first document without an SDK.
• Authentication: API keys and Basic authentication.
• Web API reference: the endpoints the methods call.