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
- Architecture 1 - Client System Compatible with OData V4
- Architecture 2 - Client System Incompatible with OData V4
- Useful OData V4 resources
- How does it all tie in together?
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
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
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
- Templafys requests are authenticated with a Bearer token, good token hygiene is recommended
- Application gateway filtering requests between Templafy and the server
- Server Name Indication - Templafy supports SNI
- TLS 1.2 minimum (soon to support TLS1.3)
- Non-standard ports for example https://customerdataconnector.com:65443
- Network route filtering
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
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
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
3. View the top 10 results in your External Data Sources
4. Reference the External Data Sources within your documents by following the below 2 links
- https://support.templafy.com/hc/en-us/articles/360016983058-External-Data-Sources
- https://support.templafy.com/hc/en-us/articles/360017884978-Data-Connector-Form-field-External-Data-Source-
Comments
0 comments
Please sign in to leave a comment.