The goal of this section is to lay out for developers the expected response structure of RPC called from the Docxpresso interface.
Although the use of external services is usually the preferred way to exchange data on real time directly from the browser the RPCs can be particularly useful to load some data on page loading that requires some general input from the end user or just to populate a dynamical dropdown (see also the section on data configuration on real time).
A Docxpresso RPC requires that there is a “micro REST Service” that returns a JSON with Docxpresso format (more on this below) which contents may or not depend on the parameters that are passed in the URL by GET.
Besides the parameters that are defined in the Docxpresso backoffice interface and that should be provided by the end user or predefined in the RPC Docxpresso also sends the additional following query parameters if a “secret” is provided for secure RPCs (otherwise the secret is taken to be the Docxpresso APIKEY):
- callback
- timestamp
- uniqid
- APIKEY
This last APIKEY parameter is generated as follows:
- Concatenate “timestamp-uniqid-method” where method stands for the RPC name as defined in the backoffice
- Compute the sha1-hmac of the secret and the previously concatenated string following, for example, the function defined in: https://en.wikipedia.org/wiki/Hash-based_message_authentication_code
The URL associated with the RPC may or not authenticate the validity of the APIKEY and depending on the type of the RPC and the parameters sent by GET prepare a response that should have the following format:
The callback parameter is required to generate a response in JSONP format in order to avoid CORS issues (due to the fact that the domain of the service will, in general, differ from the one of the Docxpresso app).
OnLoad RPCs
The goal of this type of RPC is load some variables on the Docxpresso interface that could not be done at the server level because it needs some end user input.
Like any other Docxpresso RPC it should return a JSONP so it is recommended to send an application/javascript header.
In order to build the response first one should get the value of the callback GET parameter and wrap the JSON within the corresponding callback function.
In order to illustrate the process let us imagine that we want to load from a RPC the name of an user that is represented within the Docxpresso template like {{name}} the corresponding PHP script will read like (obviously the RPC can be generated in any other language like Java, .NET, Python, …):
<?php
header('Content-type: application/javascript');
//here will come all the logic of the RPC that may include searches in databases, etcetera in order to //generate a variable $name
$callback = $_GET['callback'];
$json='{"varValues":{"name": ["' . $name .'"]}}';
echo $callback . '(' . $json . ')';The generalization to more than one variable just requires to add the additional variable names to the varValues JSON property.
Dropdown RPCs
The goal of a dropdown RPC is to populate a dropdown associated with a given Docxpresso variable.
In this case the structure of the response JSONP must be as follows:
<?php
header('Content-type: application /javascript');
//here will come all the logic of the RPC that may include searches in databases, etcetera in order to //generate a variable the options of the associated dropdown
$id = $_GET['id'];
$callback = $_GET['callback'];
echo $callback . '([["key1","value1"],["key2","value2"],["key3","value3"]])';Triggered RPCs
This case is almost identical to the onLoad case with one important difference: if the JSON includes the property “replaceMode”: “row” the variable replacement will be limited to the variables that share the same cloneable row group.
This is done so in, for example, an invoice one may clone items and each of them may contain a “catalog entry” and the corresponding price that is assigned to each item.
