Custom Data Providers

Overview

Through optional modules EasyCatalog provides a number of data providers (ODBC, XML, Excel, CSV, Sqlite).  The Enterprise Data Provider also provides additional connections to a number of third party systems.  For connections to other systems, such as JSON or REST APIs, the Enterprise Data Provider enables the ability to create custom data providers.

Creating a Custom Data Provider

Custom data providers are implement via a single Lua script. The script is parsed each time the File->New->EasyCatalog Panel menu is accessed. The script should be called <name>.lua where <name> is the menu name shown on the File menu. Templates should be saved into the ‘EasyCatalog Data Source Templates’ folder in the EasyCatalog workspace folder.

Implementing the Script

The script should provide a number of specific functions, which are called during data retrieval and update. The script is stateless, so cannot persist global variables. To persist data a single Lua table is used to stores data source settings in the data.xml configuration file.

Script Functions

The examples below show connection to the REST API of an Airtable data source.  The entire script can be downloaded here.

Initial Data Retrieval

  • Initialize()

This method is called immediately after selecting File->New->EasyCatalog Panel->New <name> Data Source.  The purpose is to return a table of default settings for the data source.

  • ConfigureUI(config)

In the Desktop version of InDesign, this is called after Initialize or when the data source is edited. It’s not used on InDesign Server.  Its purpose is to present UI in order to specify credentials and criteria for data selection and return an updated configuration table. If a table is returned, this must contain a name entry, which will be the name of the new data source.  If it returns nothing, then the user cancelled the operation.  In the case of editting the data source, the name cannot change.

  • Synchronize(config, DATASOURCE)

Once the configuration table has been created, Synchronize is called to create a new RECORDSET, which should be returned.  Parameters are the data sources configuration setting and the DATASOURCE object.  This should return the result of a RECORDSET.new command to create a complete record set of field definitions and record data, or nil for failure.

  • SaveRecords(config, datasource, records)

This is an optional function.  When available it is called to  write back local changes to the original data source.  For selective updates, on a field by field basis the updatestate of the field can be used to check if it needs updated. On successful update, this should be cleared.

Handling Images

When an image field is set to URL source, the option to allow the script to download the image is available.

  • CanResolveAssetURI(field name, uri)

The field name and the location as determined the fields location setting are passed. The function should return true or false to indicate the image should be downloaded by the script;

  • ResolveAssetURI(configuration, uri)

Should turn the uri as specified by the image into a fully qualified URL

  • GetAsset(config, location, filepath)

Preforms the download of the image. location is the result of ResolveAssetURI and file path is a full path to where the image should be stored. returns true of false to indicate success.