Articles in this section

How to build a Custom Data Connector?

Avatar
Sam Polgar
Updated
Follow

What is the Custom Data Connector?

The Custom Data Connector is an OData V4 connection from Templafy to a client system. The Custom Data Connector requests live information to be inserted into a document upon creation.

For example, a manager running a weekly sales report can generate a document with Templafy inserting current sales data from an external system.

Content

Overview

What is OData?

OData is a protocol with defined methods for building and consuming RESTful APIs. The OData protocol manages request and response headers, status codes, HTTP methods, URL conventions, media types, payload formats, and query options.

Templafy first queries the OData endpoint for $metadata. The OData servers response describes each entity, its properties, data types, and which operations can be used. Templafy's OData client can then adapt to the metadata specification sent back.

 

How does Templafy connect to a client system?

Two architectures we have seen are:

  • Architecture 1. OData request from Templafy to client SaaS supporting OData V4
  • Architecture 2. OData request from Templafy to an OData V4 web service acting as an intermediary. This web service can transform the query and request to another system in any protocol/language

Architecture 1 - Client System Compatible with OData V4

This is available to organizations with an OData V4 compatible solution. Requirements include:

  • HTTPS endpoint available publicly
  • Authentication via Bearer Token. Currently, Templafy doesn't support an alternate method
  • OData V4 response supports Templafys datatype requirements

mceclip2.png

 

Architecture 2 - Client System Incompatible with OData V4

This is available to all organizations. Many clients prefer this architecture as they can query their systems, massage and reformat data before returning to Templafy. Requirements include:

  • HTTPS endpoint available publicly, Templafy doesn't support self-signed certificates
  • Authentication via Bearer Token. Currently, Templafy doesn't support an alternate authentication method
  • OData V4 server hosted by the client/partner
  • OData V4 response supports Templafys datatype requirements

mceclip3.png

 

Security for Architecture 2

Templafys data connector infrastructure is built using Azure Kubernetes and CICD deployment. As such, Templafy does not provide a static IP nor IP address range for a client firewall to configure in an Allowlist.

The security of your OData server is out of Templafys control or responsibility. The following security measures can assist in securing your server

  1. Templafys requests are authenticated with a Bearer token, good token hygiene is recommended
  2. Application gateway filtering requests between Templafy and the server
  3. Server Name Indication - Templafy supports SNI
  4. TLS 1.2 minimum (soon to support TLS1.3)
  5. Non-standard ports for example https://customerdataconnector.com:65443
  6. Network route filtering

Useful resources for OData

How does it all tie in together?

Assuming you now have an OData V4 connection, take the following steps to configure your Data Connector and insert data into a document


1. Enable the integration in the Templafy admin panel. Add the OData V4 endpoint

If you're testing, you can uncheck the "Activate for users" button, this will prevent it from being used by system users

mceclip5.png

 

 

2. Add an External Data Source in your Templafy Admin Section

The EntityDataSets available in the below dropdown are the result of the $metadata response from your OData V4 endpoint as described in the "What is OData" section

 

mceclip4.png

 

 

3. View the top 10 results in your External Data Sources

mceclip6.png

4. Reference the External Data Sources within your documents by following the below 2 links

 

 

Related articles

Comments

0 comments

Please sign in to leave a comment.