SDK

The Docxpresso SDK is a tool for developers that is designed to simplify the following general tasks:

• Remote management of Docxpresso instances.
• Integration of Docxpresso with third party tools: web sites, intranets, CRMs, ERPs,…
• Data exchange among services.

Explicitly, and among many other things, with the help of the SDK one may remotely:

• Generate links to interactive documents and web forms for the use of external users.
• Download complete lists of templates by category.
• Download user data and generated documents.
• Request the automatic generation of documents from externally provided data.

Although the SDK contains profuse documentation inline in the following we will describe in general terms the purpose and usage of the main (though not all) available SDK methods.

General usage of the SDK

In order to have access to the SDK methods one should first provide:

• The apikey of the corresponding Docxpresso instance that may be found, for example, in the Config > Account menu entry of your Docxpresso instance web interface.
• The URL of your Docxpresso installation.

The general structure of your PHP script should read something like:

<?php
	//include the SDK
	include('[path]/SDK.php');
	//setup the namespace
	use SDK_Docxpresso as SDK;

	//define the compulsory identification options
	$options['pKey'] = "your apikey goes here";
	$options['docxpressoInstallation'] = 'https://thepathtoyourDocxpressoInstallation';

	//create an instance of the SDK
	$APICall = new SDK\Utils($options);

	//generate a link to interact with Docxpresso
	//in this example for requesting a list of template categories
	$url_categories = $APICall->listCategories();

NOTE: if needed you may change in the SDK the namespace and class name for integration with frameworks that may require to do so in order to function properly with autoloaders.

Creating edition links

The previewDocument is arguably the most important method of the whole SDK. It allows for the generation of secure links to the end user Docxpresso web interface, i.e. generate secure links (via HMAC) that may be embedded in other websites or emails when clicked allow end users to access in a secure manner the standard Docxpresso document web interface.

The previewDocument method has a plethora of options but the most important ones include:

• The template id.
• The token that identifies a previous use in case we want to continue a previous edition of the document.
• The form option that if set to true will open a web form rather than an interactive document.
• The format of the generated document: odt, doc, docx, pdf or rtf.
• The responseURL, i.e. the web page where the user should be redirected after completing the process.
• The prefix if given will allow only the edition of variables that start with that prefix.
• The option editableVars allow for restricting the enduser edition to a list of variables separated by comma.
• The GDPR option when set to true the end user will be obliged to accept the privacy policy (note that it is only active if the GDPR option has been globally activated for the corresponding Docxpresso instance).

A typical call would look like:

$APICall->previewDocument(array('template' => 28, 'responseURL' => 'http://domain.com/thanks'));

The more advanced methods include options to exchange in/out data with other services, modify template config on real time, but they will not be discussed here.

Obtaining information about the available templates

The SDK offers a wide variety of methods designed to get information about the templates available in your Docxpresso installation that we will be briefly described here.

List of templates and categories

You may get a complete list of documents and categories in JSON format with the help of the documentTree method.

This method like all other methods that respond JSON accept a parameter named callback that if given will return JSONP response (padded JSON) so it can be used directly in JavaScript.

IMPORTANT: be careful to never expose to unauthorized parties authentication info like the apikey, so only the final URLs generated by the SDK should be included in a web page or .js file.

You may further filter by:

• Category id (only the corresponding subtree will be sent).
• Published (only "published" templates will be sent).
• Access rules (one may restrict the list only to "public" templates or the ones accessible by a given user.)

If you do not need all the info you may also simply obtain:

• A category list via the listCategory method.
• A list of documents by category with the help of the documentsByCategory method with the same filters as the documentTree method.
• templatesByName allows also to filter in addition by the template name (a LIKE %…% SQL type search).

Detailed template data

One may get detailed info about the structure and all other info associated with a given template via the following methods:

• getTemplateData: given the id of a particular document one may retrieve in JSON format the associated template base64 encoded, the data structure of the template, its associated HTML code, the thumbnail,…
• getTemplateThumbnail: given the id one may recover just the corresponding thumbnail base64 encoded.

Downloading/generating final documents remotely

One may download a previously generated document or request a new one with the following available methods:

• downloadDocument: by providing the template id and the token associated to a particular usage one may download the associated document and/or a zip file with its attachments if any.
• requestDocument: by providing a template id and sending the relevant data in JSON format well directly in the request or via a requestDataURI parameter one may generate a complete new document. This document is sent directly as a download (default) or like a base64 encoded string in a JSON by setting the response parameter to "json".
• regenerateDocument: one may regenerate a previous document in a different format by providing a template id, a usage token and a document name with the required format (pdf, odt, docx, doc or rtf).

Retrieving user data from Docxpresso

In order to fully integrate Docxpresso with third party tools you will certainly need to access remotely the data stored in the Docxpresso databases.

Our SDK provides quite a few methods to do so:

• dataByUsage: allows to get all raw data from a Docxpresso usage by simply providing the relevant usageId that may be obtained from the responseURL (as a query parameter) or directly with some of the other available methods that we describe in the following.
• dataByTemplate: allows to download the data for all usages of a given template (selected by id) filtered by: dates, identifier and reference among other possibilites and sorted by any of these fields. You may also paginate the results using the firstResult and maxResults parameters.
• dataDigestByUsage: the same as before but returned in HTML (default) or CSV format.
• dataStatistics: allows for the download all basic statistic data regarding template usage in JSON format (or JSONP for direct embedding in a web page).

Remote instance access and authentication methods

You may allow direct access to Docxpresso for registered users from external websites with the help of the AccessByTokenAction method that only require:

• email: the user email registered in Docxpresso.
• url: the target web page to visit. If not given will be the standard Docxpresso homepage.

You may also check the legitimacy of requests coming from Docxpresso by checking the "internal coherence" of the provided additional parameters: data, timestamp, uniqid and APIKEY by means of the checkAPIKEY method that will return true or false for legitimate or tampered requests respectively.