Integrate Datylon Server with our API to automate reports and charts

Learn how to integrate the Datylon Server using the API

Introduction

The Datylon Server is a platform which allows organizations to automate the production of charts, pages or complete reports based on graphically rich and on-brand templates created with Datylon for Illustrator. 

The Datylon Server consists out of the following components: 

  • Datylon for Illustrator
    An Adobe Illustrator plugin to create advanced graphs and data visualizations. The resulting designs can either be output as one-off documents, but also exported as templates to the Datylon Server for automated data updates. Read more on Datylon for Illustrator https://www.datylon.com/product/datylon-for-illustrator
  • Datylon webapp
    State of the art web application allowing the user to view, style, manage and use templates exported from Datylon for Illustrator. New charts, pages or reports are created based on these templates by binding new data sources to it. This binding process can be done manually or automatically using the Datylon Render Server API.
  • Datylon Render Server
    A REST API addressable service that allows the caller to render Datylon templates with new data and retrieve the result as svg, png or pdf 

Below you’ll find details on how to connect external applications by sending requests to the Datylon Render Server. For more information on creating templates with Datylon for Illustrator, click here

Datylon Render Server

The Datylon Render Server includes the following features: 

  • Authentication of a request.
  • Conversion of the request payload to a data structure that is used to render the template.
  • Fetching the template from https://insights.datylon.com based on a template uuid.
  • Invoking the Datylon Render Server by POSTing the template SVG and (converted) request data.
  • Returning the render result as the request response.

At first, start small. Use a template with a single bar or line chart and a small data set to get started with the integration service.

 

Render endpoint

To render a template with data, an HTTP POST request characterised by the following properties should be sent:


HTTP request and url

Please contact Datylon via the contact form or getsupport@datylon.com to provide the url and activate the license.


HTTP headers

HTTP header keys and values (except authorization) shall be in lower case. 

  • authorization
    • Basic http authorization header. E.g. assuming a Datylon account with email me@acme.com and password secret, the header becomes
      Basic bWVAYWNtZS5jb206c2VjcmV0
  • content-type
    • application/json → data should be provided as json (see further)
    • application/x-binary → data should be provided as one single xlsx workbook
  • accept
    • image/svg+xml → return render result as svg
    • image/png → return render result as png
    • application/pdf → return render result as pdf
  • x-graph-template-id
    • UUID of the Datylon template to be rendered, located on the Datylon Server. 
    • To retrieve this UUID, open the template or design in https://insights.datylon.com/create/stories and copy the alphanumeric string at the end of the url. 
  • x-graph-datasource-name
    • Name of the workbook (data source) in the Datylon template for which new data is provided.
      Caution: Default workbooks in the templates should be referred to as “main template datasheet container" in the request.
    • Only needed when providing data as a xlsx workbook

HTTP payload

Either

  • JSON data if content-type is application/json
  • XLSX file (binary) if content-type - application/x-binary

It is essential the structure of the provided data exactly matches the structure of the data used in the Datylon template.

For now, only data in the default workbook (referred to as "main template datasheet container" in the request) can be updated through the integration endpoint. 

Find below the JSON structure:

{

  "main template datasheet container": {

    "name of first sheet": [

        ["row 1,col 1","row 1,col 2",...,"row 1,col n"],

        ["row 2,col 1","row 2,col 2",...,"row 2,col n"],

        ....

    ],

    "name of second sheet": [

        ["row 1,col 1","row 1,col 2",...,"row 1,col n"],

        ["row 2,col 1","row 2,col 2",...,"row 2,col n"],

        ....

    ],

    "name of third sheet": [

      ...

    ],

    ....

  }

}
  • The amount of sheets and the names should match the amount of sheets and names in the Datylon design/template. So name of xyz sheet should be replaced with the name of the sheet at the corresponding position in the default datasource
  • row x, col y should be replaced with the new value in row x, column y of the corresponding sheet in the default datasource


In case an XLSX workbook is provided as payload for the request: 

  • The amount of sheets in the workbook should match the amount of sheets in the default datasource.
  • The name(s) of the sheet(s) should match exactly.
  • The structure of each of the sheets should match the structure of the corresponding sheet in the default datasource of the Datylon template

 

Example

The template above with dummy data is rendered using following URL, headers and data sets: 

  • URL: To be provided. Please contact Datylon.
  • authorization: Your Datylon account and password 
  • content-type: application/json or application/x-binary. See data sets below
  • accept: image/png
  • x-graph-template-id: 155d6153-4b8d-49d9-a8ba-d94417aa5111
  • x-graph-datasource-name: main template datasheet container


JSON example

{

"main template datasheet container": {

"line": [

["X","Y1","Y2","Y3"],

["jan","60","47","5"],

["feb","50","37","20"],

["mar","56","32","25"]

],

"bar-and-pie": [

["Category","Value"],

["Cat","60"],

["Dog","15"],

["Bird","9"],

["Mouse","5"],

["Horse","11"]

]

}

}

 

XLXS workbook example with 2 sheets named "line" and "bar-and-pie":

line

X Y1 Y2 Y3
jan 60 47 5
feb 50 37 20
mar 56 32 25

 

bar-and-pie

Category Value    
Cat 60    
Dog 15    
Bird 9    
Mouse 5    
Horse 11    

 

The response is the png below:

Data security & on premise deployment

Besides the cloud deployed Datylon render service, accessible from ‘anywhere’, the render service can also be deployed on premise as a Docker instance. This allows to set up a render workflow keeping privacy sensitive data on site while the templates are stored in the Datylon webapp.


Such an architecture combines the advantages of secure cloud technologies with the requirement to keep sensitive data behind a corporate firewall at all times - the on site deployed Datylon render service will retrieve the Datylon template from the webapp through a secured channel and combine it with the provided data, rendering the result as one of the supported output formats.

Support

For support please use the contact form or chat in the Help Center, or email us at getsupport@datylon.com