# Ruby > Use the txtextcontrol-reportingcloud gem from Ruby: Basic authentication, merge_document with hashes and Base64 results, errors and the endpoint of each method. - **Product:** ReportingCloud - **Section:** Documentation - **Kind:** Topic - **Path:** ReportingCloud > SDKs > Ruby - **2741 words** - **Web URL:** https://docs.textcontrol.com/reporting-cloud/sdks/ruby/ - **LLMs URL:** https://docs.textcontrol.com/reporting-cloud/sdks/ruby/llms.txt - **LLMs-Full URL:** https://docs.textcontrol.com/reporting-cloud/sdks/ruby/llms-full.txt --- 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](https://docs.textcontrol.com/reporting-cloud/getting-started/web-api/llms-full.txt) in Getting Started shows with curl. [Ruby](https://docs.textcontrol.com/reporting-cloud/getting-started/ruby/llms-full.txt) in Getting Started builds a first script with the gem step by step. ### Gem and Requirements | Gem | Version | Released | Ruby | Runtime dependencies | |---|---|---|---|---| | [txtextcontrol-reportingcloud](https://rubygems.org/gems/txtextcontrol-reportingcloud) | 1.2.1 | March 4, 2019 | No minimum version declared | None; the gem uses `net/http`, `json`, `uri`, `cgi`, `ostruct` and `date` of the standard library | Add the gem to the *Gemfile* of your application and run `bundle`, or install it with RubyGems: ```bash gem install txtextcontrol-reportingcloud ``` [Installing an SDK](https://docs.textcontrol.com/reporting-cloud/installation/sdks/#ruby) 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](https://docs.textcontrol.com/reporting-cloud/document-processing/authentication/llms-full.txt) 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`: ```ruby 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](https://docs.textcontrol.com/reporting-cloud/mail-merge/data-sources/llms-full.txt) 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](https://docs.textcontrol.com/reporting-cloud/reference/web-api/document/merge/post/llms-full.txt). 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](https://docs.textcontrol.com/reporting-cloud/mail-merge/settings/llms-full.txt) 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. | Method | Web API endpoint | Returns | |---|---|---| | `merge_document` | [POST /v1/document/merge](https://docs.textcontrol.com/reporting-cloud/reference/web-api/document/merge/post/llms-full.txt) | An array of Base64 strings | | `append_documents` | [POST /v1/document/append](https://docs.textcontrol.com/reporting-cloud/reference/web-api/document/append/post/llms-full.txt) | A Base64 string, one document from an `AppendBody` | | `convert_document` | [POST /v1/document/convert](https://docs.textcontrol.com/reporting-cloud/reference/web-api/document/convert/post/llms-full.txt) | A Base64 string | | `find_and_replace` | [POST /v1/document/findandreplace](https://docs.textcontrol.com/reporting-cloud/reference/web-api/document/findandreplace/post/llms-full.txt) | A Base64 string | | `upload_template` | [POST /v1/templates/upload](https://docs.textcontrol.com/reporting-cloud/reference/web-api/templates/upload/post/llms-full.txt) | Nothing | | `list_templates` | [GET /v1/templates/list](https://docs.textcontrol.com/reporting-cloud/reference/web-api/templates/list/get/llms-full.txt) | An array of `Template` objects | | `get_template_count` | [GET /v1/templates/count](https://docs.textcontrol.com/reporting-cloud/reference/web-api/templates/count/get/llms-full.txt) | An integer | | `template_exists?` | [GET /v1/templates/exists](https://docs.textcontrol.com/reporting-cloud/reference/web-api/templates/exists/get/llms-full.txt) | `true` or `false` | | `get_template_info` | [GET /v1/templates/info](https://docs.textcontrol.com/reporting-cloud/reference/web-api/templates/info/get/llms-full.txt) | A `TemplateInfo` object | | `get_template_page_count` | [GET /v1/templates/pagecount](https://docs.textcontrol.com/reporting-cloud/reference/web-api/templates/pagecount/get/llms-full.txt) | An integer | | `get_template_thumbnails` | [GET /v1/templates/thumbnails](https://docs.textcontrol.com/reporting-cloud/reference/web-api/templates/thumbnails/get/llms-full.txt) | An array of Base64 images, one per page | | `download_template` | [GET /v1/templates/download](https://docs.textcontrol.com/reporting-cloud/reference/web-api/templates/download/get/llms-full.txt) | A Base64 string | | `delete_template` | [DELETE /v1/templates/delete](https://docs.textcontrol.com/reporting-cloud/reference/web-api/templates/delete/delete/llms-full.txt) | Nothing | | `get_account_settings` | [GET /v1/account/settings](https://docs.textcontrol.com/reporting-cloud/reference/web-api/account/settings/get/llms-full.txt) | An `AccountSettings` object | | `get_api_keys`, `create_api_key`, `delete_api_key` | [GET /v1/account/apikeys](https://docs.textcontrol.com/reporting-cloud/reference/web-api/account/apikeys/get/llms-full.txt), [PUT](https://docs.textcontrol.com/reporting-cloud/reference/web-api/account/apikey/put/llms-full.txt) and [DELETE /v1/account/apikey](https://docs.textcontrol.com/reporting-cloud/reference/web-api/account/apikey/delete/llms-full.txt) | An array of `APIKey` objects, the new key or nothing | | `list_fonts` | [GET /v1/fonts/list](https://docs.textcontrol.com/reporting-cloud/reference/web-api/fonts/list/get/llms-full.txt) | An array of font names | | `check_text` | [GET /v1/proofing/check](https://docs.textcontrol.com/reporting-cloud/reference/web-api/proofing/check/get/llms-full.txt) | An array of `IncorrectWord` objects | | `get_available_dictionaries` | [GET /v1/proofing/availabledictionaries](https://docs.textcontrol.com/reporting-cloud/reference/web-api/proofing/availabledictionaries/get/llms-full.txt) | An array of dictionary names | | `get_suggestions` | [GET /v1/proofing/suggestions](https://docs.textcontrol.com/reporting-cloud/reference/web-api/proofing/suggestions/get/llms-full.txt) | An array of suggestions | `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](https://docs.textcontrol.com/reporting-cloud/document-processing/errors/llms-full.txt) lists the status codes and their causes. ### API Documentation and Source - **API documentation.** The [YARD documentation](https://textcontrol.github.io/txtextcontrol-reportingcloud-ruby/) 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](https://github.com/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](https://docs.textcontrol.com/reporting-cloud/sdks/llms-full.txt): the SDKs compared, with their status. - [Installing an SDK](https://docs.textcontrol.com/reporting-cloud/installation/sdks/llms-full.txt): the installation of each SDK. - [Ruby](https://docs.textcontrol.com/reporting-cloud/getting-started/ruby/llms-full.txt) in Getting Started: a first script that merges a template to PDF. - [Web API](https://docs.textcontrol.com/reporting-cloud/getting-started/web-api/llms-full.txt): the first document without an SDK. - [Authentication](https://docs.textcontrol.com/reporting-cloud/document-processing/authentication/llms-full.txt): API keys and Basic authentication. - [Web API reference](https://docs.textcontrol.com/reporting-cloud/reference/web-api/llms-full.txt): the endpoints the methods call. --- ## Nearby - **Previous:** [Java](https://docs.textcontrol.com/reporting-cloud/sdks/java/llms-full.txt) - **Next:** [Troubleshooting](https://docs.textcontrol.com/reporting-cloud/troubleshooting/llms-full.txt)