How to build a Custom Data Connector

About this article

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.

Sections in this article

• What is OData?
• How Does Templafy Connect to a Client System
• Security for OData V4 Server
• Supported Data Types in Templafy
• Useful Resources for OData
• Completing the Setup in Templafy

Prerequisites

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

Templafy can either connect to a client system that natively supports OData V4 or a separate OData V4 web service that acts as an intermediary between Templafy and the client system. 

Requirements for connecting include:

• HTTPS endpoint available publicly; Templafy does not support self-signed certificates for HTTPS connections
• Authentication via static Bearer Token. Currently, Templafy doesn't support an alternate authentication method
• OData V4 response supports Templafy's data type requirements
• OData V4 server hosted by the client/partner if the intermediary web service is required.

Security for OData V4 Server

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

1. Templafy's requests are authenticated with a Bearer token; good token hygiene is recommended
2. TLS 1.2 minimum required
3. Network route filtering on Templafy's static IP addresses can be implemented

Supported Data Types in Templafy

Templafy supports the following data types from an OData response:

• Edm.Boolean

• Edm.Byte

• Edm.Date

• Edm.DateTimeOffset

• Edm.Decimal

• Edm.Double

• Edm.Duration

• Edm.Guid

• Edm.Int16

• Edm.Int32

• Edm.Int64

• Edm.SByte

• Edm.Single

• Edm.String

Useful Resources for OData

• OData V4 specifications https://www.odata.org/documentation/
• Node JS server: https://www.npmjs.com/package/simple-odata-server
• .NET getting started project: https://docs.microsoft.com/en-us/odata/webapi/getting-started

Completing the Setup in Templafy

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

1. Enable the Custom Data Connector
   
   
   
   

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
   
   
   
   

Related articles