Inbound and outbound data exchange

One of the key features of Docxpresso interactive documents and forms is their built-in capacity to exchange data with third parties and inner components.

This data exchange is fully bidirectional:

  • Documents may receive information from multiple sources:
    • Integrating user input (core functionality).
    • Performing real time requests to external data sources (Remote Procedure Calls).
    • Incorporating local auxiliary resources like, for example, lists of countries to populate dropdowns.
    • Preloading data from external sources via CURL.
  • Data and documents may be forwarded to authorized third party sources:
    • The generated document (core functionality).
    • All the gathered data.
  • Direct access to Docxpresso databases via fully configurable REST Services.

Basic concepts

Docxpresso is architectured as a service so it is designed to exchange information with third party websites and databases.

All outbound and inbound connections are managed by standard HTTP requests, i.e. plain URLs with additional request parameters.

In order to provide a service to a third party Docxpresso generically requires that three parameters are sent together with the URL. These parameters, that may be sent using the GET or POST method, are:

  • timestamp: this must be the standard UNIX time, i.e. the number of seconds that have elapsed since 00:00:00 (UTC), Thursday, 1 January 1970. This parameter is not required if the default security level is set to zero.
  • uniqid: this unique id used to distinguish any two requests. Notice that the timestamp and other options may coincide for different requests potentially generating a duplicated APIKEY. This parameter is not required if the default security level is set to zero.
  • APIKEY: that will allow Docxpresso to check if the current request is a legal request. It is generated with the values of the other request parameters and a private key. This parameter is not required if the default security level is set to zero.
  • options: this parameter, that must be serialized as a JSON object, must contain all the specific options regarding that particular request. These options are logically grouped as follows:
    • Data options that will be used for direct data exchange:
      • data: raw data in Docxpresso format to be included in the displayed document or form (default value: NULL).
      • requestDataURI: JSON encoded object that if not NULL (default value) should have two properties:
        • URL: the URL where we should fetch raw data in Docxpresso format to be displayed into a document or form.
        • requestData: any additional information that the target URL may need to process the request.
      • responseDataURI: URL where we should send the gathered data in Docxpresso format for its storage or further processing (default value: NULL).
      • custom: a serialized JSON object that may include custom data used to process a specific request by a thrid party client or custom code associated with a particular document (default value: NULL).
      • prefix: if not empty a string that indicates that variables starting with “prefix_” (where here prefix stands for the chosen value) should be the only editable ones, i.e. the edition of all other variables should be blocked (defalut value empty).
      • docFormat: the requested format of the generated document, if any (default value: odt).
      • token: unique identifier for an enduser transaction (default value: NULL).
      • enforceValidation: if true will not let to save the document until all validations are fulfilled. Not recommended unless you want the final user to complete the document in just one shot (default value: false).
    • Source options, used to identify a request:
      • host: the source that requested the data (if empty the host will be used) (default value: request host).
      • enduserid: the end user id. If not given the user will be registered as anonymous (default value: anonymous).
      • identifier: a variable used by the current document that may help to uniquely identify a user request (default value: NULL).
      • reference: an additional parameter used to further identify a particular request.
    • Navigation options:
      • responseURL: the URL where the end user should be redirected upon succesful completion of the request (default value: default_redirect_path as defined in app/config.yml).
      • name: the name of a generated document that is requested for download (default value: NULL).
      • documentName: the public name of the downloadable document (default value: the requested template name).
      • mimeType: the MIME type of a fetched attachment associated with a document (default value: NULL).
      • referer: the URL where the user must be redirected in case of error (default value: request referer).
      • forward: JSON encoded object that if not NULL (default value) should have two properties:
        • email: the email where the resulting document link should be sent so the data may be further edited by other enduser (default value: NULL).
        • options: all other request options that may be used to build a new petition request recursively (default value: NULL).
    • Notification options:
      • notify: email address to notify upon completion.
    • Security options:
      • access: it may be unknown, anonymous, authenticated or fullyAuthenticated (default value: "unknown").
      • securityLevel: some requests may allow personalized higher security levels. If its value is given but it is lower than the default security level it will be ignored by Docxpresso. Also notice that this value will have no effect whatsoever if the default security level is set to zero (default value: NULL).

Of course, all these options do not always apply to every single request. Moreover, if they are not provided they will assume sensible default values.

Let us go into the details that apply to each possible scenario.

Receiveing Data from outside sources

Whenever an end user requests an interactive document or its associated web form it may well happen that Docxpresso needs to provide some additional data like:

  • Information provided by the user in a previous session.
  • Useful external information fetched from outside sources like product ranges and prices, up to date legal info, etcetera.

All of this may be achieved in two different ways:

Importing data from third party websites

You may bring data from any external source by means of the requestDataURI optional parameter explained above. This data in JSON format is requested via cURL and diretly loaded in the user interface from the server.

The external server response should comply to the following:

  • The response should have a 200 HTTP Status Code header.
  • The response must carry a valid APIKEY for the corresponding security level in Docxpresso.
  • The response must be of the type application/json.
  • The forwarded JSON should follow Docxpresso JSON format.
Using RPCs

You may call external services which data will be loaded directly from the end user interface via AJAX.

In order to do so the RPC answer should obey the follwing general rules:

  • The response should be of the JSONP (padded JSON) type: application/javascript.
  • It should be "padded" within a function named equal to the request callback parameter.
  • The forwarded JSON object should have the following properties:
    • Comply with Docxpresso JSON format or
    • include a replaceMode property with value row in order to feed the variables within a single table row with the additional provided variables.