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 that 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.

HubSpot Video

The Datylon Server consists 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 web app
    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 them. 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 characterized 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 an 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.

JSON: 

If the ‘default workbook' is used when creating the template, it should be referred to as ‘main template datasheet container’ in the JSON payload. 


Find below the JSON structure for use with the 'default workbook' :

{

  "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": [

      ...

    ],

    ....

  }

}
Row x, col y refers to the values in row x, column y of the corresponding sheet.


Below an example in case one or multiple other workbooks are used:

{
 "Name of first workbook":{
    "Sheet 1":[["Category","v1","v2"],["category1","12","14"],["category2","3","13"],["category3","43","12"],["category4","2","11"]]
   }
,"name of 2nd workbook":{
  "Sheet 1":[["Category","Value"],["A1","1"],["A2","50"],["A3","2"],["A4","50"],["A5","5"],["A6","32"],["A7","4"],["A8","6"],["A9","7"],["A10","8"],["A11","44"]],
  "Sheet 2":[["Cat 4","Val 4"],["aaa","44"],["bbb","44"],["ccc","44"]]
   }
,"Name of 3rd workbook":{
  "Sheet 1":[["v1","Value"],["c1","122.1"],["c2","443.9"],["c3","322.322"]]
    }
}

 

 

The number of sheets and the sheet names in the JSON should match exactly the number of sheets and names in the Datylon design/template. The sheet names are case sensitive. 



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

  • The number of sheets in the workbook should match the number of sheets in the default data source.
  • The name(s) of the sheet(s) should match exactly. The sheet names are case sensitive. 
  • The structure of each of the sheets should match the structure of the corresponding sheet in the default data source of the Datylon template.

 

Example

On our inspiration page, you can open any design and download a JSON file as a sample. 

Below you'll find a simple example: 

 

The template above with dummy data is rendered using the 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 rendering workflow keeping privacy-sensitive data on-site while the templates are stored in the Datylon web app.

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 web app 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

Use this link if you'd like to book a demo with our solution architect and learn more about Datylon Server. Check this page for more information about Datylon Server and possible use cases.