Installing an SDK

Text Control publishes SDKs for .NET, PHP, Java and Ruby that send the requests of the ReportingCloud Web API for you: you create a ReportingCloud object with your credentials and call its methods instead of building HTTP requests and JSON. The .NET SDK comes from nuget.org, the PHP SDK from Packagist and the Ruby SDK from RubyGems; the Java SDK is built from its source code. Each section below installs one SDK and checks the installation with a first request to your account.

An SDK is optional. Any HTTP client can call the Web API, as the Web API tutorial does with curl. Requirements lists the runtime each SDK needs, and SDKs compares what they offer.

.NET

The package TXTextControl.ReportingCloud contains builds for .NET Framework 4.5 or later, .NET Core and .NET 5 or later, and .NET Standard 1.3. Its classes are in the namespace TXTextControl.ReportingCloud.

Install the Package

• .NET CLI: run the following command in the folder of your project:

  dotnet add package TXTextControl.ReportingCloud
  

• Visual Studio: choose Manage NuGet Packages... from the Project menu, select nuget.org as the Package source, search for TXTextControl.ReportingCloud and install it. In the Package Manager Console, the command is:

  Install-Package TXTextControl.ReportingCloud
  

Up to November 2018, the .NET Core version of the SDK was the separate package TXTextControl.ReportingCloud.Core, and TXTextControl.ReportingCloud contained the .NET Framework build only. Since version 1.200.500, TXTextControl.ReportingCloud contains all three builds, and TXTextControl.ReportingCloud.Core is no longer updated. Use TXTextControl.ReportingCloud for new projects.

Check the Installation

Create a console application, add the package and run a first request:

dotnet new console -o ReportingCloudCheck
cd ReportingCloudCheck
dotnet add package TXTextControl.ReportingCloud

Replace the content of Program.cs with the following code:

using TXTextControl.ReportingCloud;

// Read the API key from an environment variable
string apiKey = Environment.GetEnvironmentVariable("REPORTINGCLOUD_API_KEY")
    ?? throw new InvalidOperationException("Set REPORTINGCLOUD_API_KEY first.");

ReportingCloud rc = new ReportingCloud(apiKey);

AccountSettings settings = rc.GetAccountSettings();
Console.WriteLine($"Plan: {settings.SerialNumber}");
Console.WriteLine($"Documents this month: {settings.CreatedDocuments} of {settings.MaxDocuments}");

The code works as follows:

• new ReportingCloud(apiKey) creates the client with an API key. It sends every request to https://api.reporting.cloud with the header Authorization: ReportingCloud-APIKey <key>.
• GetAccountSettings calls GET /v1/account/settings and returns an AccountSettings object. SerialNumber is Trial for a trial account and the serial number of the subscription for a paid account.
• A request that fails throws an ArgumentException with the message of the Web API.

Set REPORTINGCLOUD_API_KEY to one of your API keys and start the application with dotnet run. It prints the plan and the documents created this month.

Vulnerability Warnings

The package was last published in September 2019, and its dependencies are as old. In a .NET 10 project, dotnet add package and dotnet build report NU1903 warnings ("has a known high severity vulnerability") for three of them:

A direct reference to a current version of Newtonsoft.Json replaces version 10.0.3 in your project and removes its warning:

dotnet add package Newtonsoft.Json

With Newtonsoft.Json 13.0.4 in the project, the SDK sends its requests and reads the JSON responses as before. The warnings for Microsoft.NETCore.App and Microsoft.NETCore.Jit remain, because the netcoreapp1.1 build of the package depends on them. If they are not acceptable in your project, call the Web API with HttpClient instead of the SDK.

PHP

The Composer package textcontrol/textcontrol-reportingcloud installs the PHP SDK and its dependencies, among them the HTTP client Guzzle 7. Its classes are in the namespace TextControl\ReportingCloud.

Install the Package

Run Composer in the folder of your project:

composer require textcontrol/textcontrol-reportingcloud:^4.0

On PHP 8.3 and later, Composer installs version 4.0.5. On PHP 8.1 and 8.2, it installs 4.0.2, the newest release that supports them. Then load the Composer autoloader in your scripts:

require_once __DIR__ . '/vendor/autoload.php';

Older projects may require the SDK by its earlier name, textcontrol/txtextcontrol-reportingcloud, which Packagist marks as abandoned; Requirements lists its releases. The current package, textcontrol/textcontrol-reportingcloud 4.0.0 of September 2023, also moved the classes from the namespace TxTextControl\ReportingCloud to TextControl\ReportingCloud, so code written for an earlier version needs its use statements changed.

Check the Installation

Save the following script as check.php in the folder of your project:

<?php
declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use TextControl\ReportingCloud\ReportingCloud;

$reportingCloud = new ReportingCloud([
    'api_key' => (string) getenv('REPORTINGCLOUD_API_KEY'),
]);

$settings = $reportingCloud->getAccountSettings();

printf("Plan: %s\n", $settings['serial_number']);
printf("Documents this month: %d of %d\n", $settings['created_documents'], $settings['max_documents']);

The code works as follows:

• The 'api_key' option passes the API key to the constructor. getenv returns false when the variable is not set, and the cast turns it into a string, which the setApiKey method behind the option expects.
• getAccountSettings calls GET /v1/account/settings and returns an array with keys such as serial_number, created_documents and max_documents.

Run it with php check.php after setting REPORTINGCLOUD_API_KEY to one of your API keys. The demo folder of the package, vendor/textcontrol/textcontrol-reportingcloud/demo, contains sample scripts for most tasks of the Web API, such as merge-document-basic.php and manage-api-keys.php. They read the API key from REPORTING_CLOUD_API_KEY, not from REPORTINGCLOUD_API_KEY. PHP describes the demo scripts.

Warning

The API Key Demo Deletes Keys. manage-api-keys.php deletes every API key of the account except the one it runs with.

Java

The Java SDK is not available from Maven Central. You build it from its repository with the Gradle wrapper and add the result to your project.

Build the Library

The build needs the Java JDK 8, as the README of the repository states. Clone the repository and run the build:

git clone https://github.com/TextControl/txtextcontrol-reportingcloud-java.git
cd txtextcontrol-reportingcloud-java
bash gradlew build -x test

The script gradlew is not marked as executable in the repository, so the command starts it with bash; sh fails on Linux distributions whose sh is dash, such as Debian and Ubuntu. The wrapper runs only on JDK 8: on a current JDK, Gradle 2.9 stops with Could not determine java version, and Java in Getting Started builds the SDK with javac instead. On Windows, run gradlew.bat build -x test. The wrapper downloads Gradle 2.9 on the first run. -x test leaves out the unit tests of the repository, which call the Web API with the credentials of a test account and don't find their credentials file on Linux and macOS; Java explains them.

Add the JAR file of the library to your project, together with its dependencies: Gson 1.7.2 (com.google.code.gson:gson:1.7.2) and, for the class FindAndReplaceBody, JavaFX (javafx.util.Pair), which a JDK with JavaFX or the library org.openjfx:javafx-base provides. bash gradlew javadoc creates the API documentation of the library.

Check the Installation

The Java SDK authenticates with the user name (the email address you signed up with) and password of the account; it has no constructor for an API key:

import com.textcontrol.reportingcloud.ReportingCloud;

import java.io.IOException;

public class CheckInstallation {
    public static void main(String[] args) throws IOException {
        // The user name is the email address of the account
        ReportingCloud reportingCloud = new ReportingCloud(
            System.getenv("REPORTINGCLOUD_USERNAME"),
            System.getenv("REPORTINGCLOUD_PASSWORD"));

        int count = reportingCloud.getTemplateCount();
        System.out.println("Templates in storage: " + count);
    }
}

getTemplateCount calls GET /v1/templates/count and returns the number of templates in your template storage. The check doesn't read the account settings as the other SDKs do: on a trial account, whose subscription end date validUntil is null, getAccountSettings of SDK 1.3 throws a JsonParseException. See GET /v1/account/settings.

Ruby

The gem txtextcontrol-reportingcloud installs the Ruby SDK. It has no runtime dependencies.

Install the Gem

Install it with RubyGems:

gem install txtextcontrol-reportingcloud

In an application that uses Bundler, add the gem to the Gemfile instead:

gem 'txtextcontrol-reportingcloud'

Then run bundle install. On Ruby 4.0, also add gem 'base64' and gem 'ostruct': the gem loads ostruct, Ruby code that decodes its documents loads base64, and Ruby 4.0 no longer provides either to Bundler by default.

Check the Installation

Like the Java SDK, the Ruby SDK authenticates with the user name and password of the account:

require "txtextcontrol/reportingcloud"

# The user name is the email address of the account
reporting_cloud = TXTextControl::ReportingCloud::ReportingCloud.new(
  ENV["REPORTINGCLOUD_USERNAME"], ENV["REPORTINGCLOUD_PASSWORD"])

settings = reporting_cloud.get_account_settings
puts "Plan: #{settings.serial_number}"
puts "Documents this month: #{settings.created_documents} of #{settings.max_documents}"

get_account_settings calls GET /v1/account/settings and returns an AccountSettings object. For a trial account, serial_number is the symbol :trial.

Next Steps

• .NET: the methods of the .NET SDK, with a merge example.
• PHP: the methods of the PHP SDK, with a merge example.
• Java: the methods of the Java SDK, with a merge example.
• Ruby: the methods of the Ruby SDK, with a merge example.
• ASP.NET Core: merge a template into a PDF with the .NET SDK.
• PHP: merge a template into a PDF with the PHP SDK.
• Java: build the Java SDK and merge a template into a PDF.
• Ruby: merge a template into a PDF with the Ruby SDK.
• Authentication: how each SDK sends your credentials.