ReportingCloud

Sharing Documents

Topic

An invoice that a customer should see right after a purchase doesn't have to travel as an email attachment or a download: your website can show it in a document viewer. GET /v1/document/share returns an encrypted name for a document in your template storage, and the viewer widget of ReportingCloud displays the document under that name in any web page. Text Control introduced the endpoint and the widget in October 2017 as a beta feature, in the blog article Sharing Documents with ReportingCloud, and the feature left its beta in January 2018.

How Sharing Works

Sharing takes three steps:

  1. The document is stored in the template storage of your account, like a template.
  2. GET /v1/document/share returns the encrypted document name of the stored document. The name encodes where the document is stored.
  3. A web page loads the viewer script from the portal and passes it the encrypted name. The viewer shows the document in a frame served by portal.reporting.cloud.

The request takes one parameter:

Part of the requestContent
templateNameThe name of the document in the template storage
Response200, the encrypted document name as a string
Errors400 when the storage has no document of this name, 403 when the request is not authorized

The document is delivered by ReportingCloud from your storage; your web server only passes on the name. Every request carries an Authorization header, as Authentication describes. The reference marks document/share with no quota of its own, but the documents you keep in the storage for sharing count against the template storage quota of your plan together with your templates. Plans and Licensing lists the number each plan stores.

Store a Created Document for Sharing

GET /v1/document/share works with the names of the template storage only, so a document that a merge creates has to be stored before it can be shared. Merge with a return format that POST /v1/templates/upload accepts, DOC, DOCX, RTF or TX, and upload the result under a name of its own.

The following commands assume that merged.json holds the response of a POST /v1/document/merge request with returnFormat=DOCX, as the Overview of the Mail Merge section creates it:

API=https://api.reporting.cloud/v1
AUTH="Authorization: ReportingCloud-APIKey $REPORTINGCLOUD_API_KEY"

# The first document of the merge response, still a Base64 string in a JSON string
jq '.[0]' merged.json > document.json

curl -X POST "$API/templates/upload?templateName=invoice-10001.docx" \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  --data-binary @document.json

The commands work as follows:

  • The merge response is an array of Base64 strings, one per created document. jq '.[0]' takes the first one and keeps its quotes, which is the body that templates/upload expects.
  • The upload stores the document as invoice-10001.docx. Give every shared document a name of its own, because an upload replaces a stored file of the same name.

A shared document stays in the storage until you delete it with DELETE /v1/templates/delete, as Managing Templates shows. Delete the documents that no longer have to be shown, so that they don't fill the storage of your plan.

Request the Encrypted Name

The following command requests the encrypted name of the stored document:

curl -H "$AUTH" "$API/document/share?templateName=invoice-10001.docx"

The response is the encrypted name in a JSON string, such as:

"jHjsdfhsdfjhaJhJHSF-HFhjusefhJH787fha-ahjasdhuzhKLJHLLKUjhdfadf8988"

jq -r . removes the quotes when a script processes the name further. The trial demo template works the same way: templateName=sample_invoice.tx shares sample_invoice.tx.

Show the Document in a Web Page

The viewer is embedded with an element that holds the encrypted name in its data-document attribute and the script reportingcloud.js from the portal:

<div id="reportingcloud-documentviewer" style="height: 800px;"
     data-document="jHjsdfhsdfjhaJhJHSF-HFhjusefhJH787fha-ahjasdhuzhKLJHLLKUjhdfadf8988"></div>

<script async src="https://portal.reporting.cloud/scripts/reportingcloud.js" charset="utf-8"></script>

The script, ReportingCloud Viewer 1.0, works as follows:

  • It looks for the element with the id reportingcloud-documentviewer and reads its data-document attribute. The id is fixed, so a page shows one shared document.
  • It adds a frame to the element that loads the viewer from https://portal.reporting.cloud/viewer with the encrypted name and allows full-screen mode.
  • The frame takes the full width and height of the element. Give the element a height, as the style attribute above does.
  • It runs once, when it has loaded. Place the script element after the viewer element, so that the element exists when the script looks for it.

When the name is missing or not valid, the frame shows the message "Oops. We can't find what you're looking for." instead of the document.

Share a Document With .NET

The method ShareDocument of the NuGet package TXTextControl.ReportingCloud requests the encrypted name. Call it on your server, so that the API key never reaches the browser: the page only receives the name. The following ASP.NET Core MVC controller requests the name of sample_invoice.tx and passes it to its view:

using Microsoft.AspNetCore.Mvc;
using TXTextControl.ReportingCloud;

public class InvoiceController : Controller
{
    public IActionResult Show()
    {
        var rc = new ReportingCloud(Environment.GetEnvironmentVariable("REPORTINGCLOUD_API_KEY"));

        // The encrypted name of the stored document
        ViewData["DocumentName"] = rc.ShareDocument("sample_invoice.tx");

        return View();
    }
}

The view Views/Invoice/Show.cshtml writes the name into the viewer element:

<div id="reportingcloud-documentviewer" style="height: 800px;"
     data-document="@ViewData["DocumentName"]"></div>

<script async src="https://portal.reporting.cloud/scripts/reportingcloud.js" charset="utf-8"></script>

The code works as follows:

  • The ReportingCloud constructor takes the API key from the environment variable REPORTINGCLOUD_API_KEY.
  • ShareDocument calls GET /v1/document/share with the name of the stored document and returns the encrypted name as a string. A refused request throws an ArgumentException with the answer of the Web API as its message.

The PHP SDK 4.0, the Java SDK and the Ruby SDK have no method for document/share. From these languages, send the GET request of the curl sample with the HTTP client of your application.

Next Steps