External Data Sources

This article explains what External Data Sources are and how these can be made available in Templafy.

External Data Sources can either be referenced as they are, or they can be transformed before use. Connecting to External Data Sources works for any of the Data Connectors and any Open Data Protocol API (OData) to fetch publicly available data sources. A Data Connector must be enabled and configured before External Data Sources can be set up and used in template configuration.

What is an External Data Source?

An External Data Source is a list of data hosted in an external system, e.g. Salesforce, Microsoft Dynamics 365 or any publicly available data source. This means that you can reference data that is hosted in external systems and use it when configuring templates and ultimately upon creating a dynamic document, which can then be populated with content coming from External Data Sources. 

Use case example

The document you generate requires live currency prices. Upon generation, Templafy queries the external system and inserts up-to-date data into the document.

How to create an External Data Source in the Admin Center

1. Navigate to Resources section. 
2. Go to the tab External Data Sources.
   
3. Fill in the required fields: 
   • Connector: choose the Connector type from the dropdown. The Data Connector would need to be set up in advance. 
   • EntityDataSet: choose which dataset you wish to add from the external system you're connected to. The datasets displayed here are pulled in from the external system.
   • Name: set the display and reference name of your data source. This cannot be changed later.  
   • Description: add a description (optional):
     
     

Schemas and Items Inside External Data Sources

External Data Sources without Data Transformation

Where External Data Sources are being used without transformation, you can view schemas and items added to the External Data Source. However, you don't have edit access, since this data is hosted in the external system it's retrieved from. 

• View items: opens a sample of the items inside the data source (view access only).
• Refresh schema: if modifications are made to the schema in the external system, lets you refresh the schema and propagate the changes to Templafy.
• Edit: lets you edit the description of your data source.
• Delete: lets you delete the data source, unless it's being used in a template configuration.

External Data Sources with Data Transformation

Where External Data Sources are being used with transformation, schemas and items of the External Data source can be viewed. If the Data Transformation module is enabled, additional options on the External Data Source will be visible. Some options will change depending on whether a transformation is applied or not.

• View items: before any transformation is applied, this opens a view only sample of items from the data source.
• View items before transformation: after a transformation is applied, the View items button changes to View items before transformation. This shows a view only sample of the original data before transformation.
• Choose entities for transformation: Select the related entities or objects on the external data source to include in transformation inputs.
• Transform data: Use JMESPath transformations to manipulate input data to a desired output.
• Refresh schema: if modifications are made to the schema in the external system, lets you refresh the schema and propagate the changes to Templafy.
• Edit: lets you edit the description of your data source.
• Delete: lets you delete the data source, unless it's being used in a template configuration.
  

External Data Source Details and Schema tabs

When selecting a row of an added External Data source, two tabs appear on the right side of the screen: Details and Schema.

Details

The Details tab opens by default. In this tab, you can see basic information about the External Data Source. The information in the Details tab is the same for each External Data Source, regardless of whether or not a transformation is applied.

Connector: This is the display name of the source system Data Connector.

EntityDataSet: This is the name of the data Entity from the source system.

Name: The display name of the External Data Source that was set when creating the record in Templafy.

Description: Description added to the External Source at the time of creation or after editing.

Schema

The Schema tab shows a view of the External Data Sources schema, or field names and structure.

For External Data Sources without a transformation applied, this tab will show the schema as it is defined in the source system. 

For External Data Sources with a transformation applied, the Schema tab will show the new output schema defined by the transformation. 

Configuring templates with External Data Source references

1. Open Template Designer.
2. Go to the Forms tab.
3. Add a Form field.
4. Choose Data Connector (only enabled and configured Data Connectors are shown).
5. Choose from the list of available External Data Sources.
6. Click Save.
7. On the Element tab create the Form binding referencing this form field. 
8. Create a Form binding, e.g. {{Form.DataSource.Column}}.

More information about how to use External Data Sources in Dynamics can be found here.