Overview
Simple data connectors allow you to connect to 3rd party applications via their 'Application Programming Interface' (API). This means you can retrieve data for use on a form either to populate an external dropdown (e.g. a list of supplier, customers etc.) or to put data into an external calculated field (e.g. retrieve a budget or forecast figure). They can also be used in the process of an app to send data to a URL and use the response in further steps of the process.
Simple data connectors are created and edited from the 'Data Connector' option at the top of the main UniFi screen.
Some familiarity with making API calls is helpful in order to build connector, but examples are available as part of the set of Foundation Apps that comes with UniFi so less technical users may find using these as a starting point for customisation helpful.
-
Connector Name - This is what the user designing the form will see when they are selecting a connector.
-
URL - The URL of the API endpoint. This should be provided by the developer of the 3rd party software you are connecting to.
-
Method - GET, POST, PUT and DELETE are available here, again the 3rd party software should have documented what methods are required for their endpoints.
Users can specify 'parameters' and 'body' when using these on a form, these will be supplied to the API in the appropriate format.
-
Accept - The data format expected to be returned via the API. Valid values are json, json/text, xml and text.
-
Query - This should be a valid JSONPath if the data being returned is JSON, or an XPath if the data is XML. https://www.freeformatter.com is one of several online tools to validate JSONPath and XPath expressions that can help with constructing these queries.
-
Security - Currently 'None' and 'UK Government' are the only available values here (this is for compatibility with MTD requirements). However, more may be added according to demand. Note that other headers can be added within the advanced properties of the form field that is using the data connector. These can be either fixed values or linked to the contents of other fields on the form.
-
Test Connector - This button allows you to send a test to the URL with the results displaying in the box below. For more advanced testing options (e.g. if you need to send specific body data as part of the request) many tools are available such as https://www.postman.com.