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.

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 one of the supported authentication methods.
• 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 using one of the supported authentication methods; good credential 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.

Authentication types

The Custom Data Connector supports the following authentication types. Select the one that matches your data source requirements.

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.

   Important If the Base URL includes an identifier, please note that Templafy only supports identifiers that start with standard letters or '_' and contain only the standard letters, numbers and '_' and '-'. Example of a supported Base URL: https://mycompany.com/api/odata/v4/m9d7-ebf2 Example of an unsupported Base URL: https://mycompany.com/api/odata/v4/5k74-3jha

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

   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.