As you probably know we have a lot of built-in integrations like Jira, Trello, Github, etc. but sometimes there the need arises to integrate custom data into Fibery. In this article we will show how to create simple integration app which does not require any authentication. We intend to create a public holidays app which will sync data about holidays for selected countries. The holidays service https://date.nager.at will be used to retrieve holidays.

Getting Started

All communication between an integration application and Fibery services is done via standard hypertext protocols, whether that be HTTP or HTTPS. Please check out the full documentation here. The choice of underlying technologies used to develop integration applications is up to the individual developer. We are going to implement all required endpoints in web app step by step. I will use Node.js for implementing this integration app. The source code can be found here.

App configuration endpoint

Every integration should have the configuration which describes what the app is doing and the authentication methods.

The app configuration should be accessible at GET "/" endpoint and should be publicly available. I used Heroku to host my app which can be found here.

This is the endpoint implementation.

const appConfig = require(`./config.app.json`);
app.get(`/`, (req, res) => res.json(appConfig));

This is how config.app.json looks like.

NOTE: All properties are required. Find the information about all properties here.

Since I don't want my app be authenticated I didn't provide any fields for "Public Access" node in authentication. It means that any user will be able to connect their account to the public holidays app. Find an example with token authentication here.

Validate

This endpoint is responsible for app account validation. It is required to be implemented. Let's just send back the name of account without any authentication since we are creating an app with public access.

POST /validate

app.post(`/validate`, (req, res) => res.json({name: `Public`}));

Sync configuration endpoint

The way data is synchronised should be described.

The endpoint is POST /api/v1/synchronizer/config

const syncConfig = require(`./config.sync.json`);
app.post(`/api/v1/synchronizer/config`, (req, res) => res.json(syncConfig));

config.sync.json

types - responsible for describing types which will be synced. For the holidays app it is just one type with id "holidays" and name "Public Holidays". It means that only one integration Fibery database will be created in the space, with the name "Public Holidays".

filters - contains information on how the type can be filtered. In our case there is a multi drop down ('countries') which is required and marked as datalist. It means that options for this drop down should be retrieved from app and special end-point should be implemented for that. Also we have two numeric filters from and to which are optional and can be used to filter holidays by years .

Find information about filters here.

Datalist

Endpoint POST /api/v1/synchronizer/datalist should be implemented if synchronizer filters has dropdown marked as "datalist": true.

Since we have countries multi drop down which should contain countries it is required to implement the mentioned endpoint as well.

NOTE: For this app, only the list of countries is returned since our config has only one data list. In the case where there are several data lists then we will need to retrieve "field" from request body which will contain an id of the requested list. The response should be formed as an array of items where every element contains title and value properties.

For example part of countries response will look like this:

{ "items": [
{ "title": "Poland", "value": "PL"},
{ "title": "Belarus", "value": "BY"},
{ "title": "Cyprus", "value": "CY"},
{ "title": "Denmark", "value": "DK"},
{ "title": "Russia", "value": "RU"}
]}

Schema

POST /api/v1/synchronizer/schema endpoint should return the data schema of the app. In our case it should contain only one root element "holiday" named after the id of holiday type in sync configuration above. Find the documentation about schemas here.

const schema = require(`./schema.json`);
app.post(`/api/v1/synchronizer/schema`, (req, res) => res.json(schema));

schema.json content can be found below

NOTE: Every schema type should have "id" and "name" defined.

Data

The data endpoint is responsible for retrieving data. Check the documentation on how request body looks. There is no paging needed in case of our app, so the data is returned according to selected countries and years interval. The source code can be found here.

POST /api/v1/synchronizer/data

The requestedType and filter can be retrieved from the request body.

The response should be returned as array in "items" element.

{ "items": [] }

Testing custom integration app

  1. It is recommended to create integration tests before adding your custom app to Fibery apps gallery. Check some tests I created for holidays app here.

  2. It is possible to run your app on local machine and make the app's url publicly available by using tools like ngrok.

    brew install ngrok
    ngrok http 8080

    Then you will have an ability to debug the app locally after adding it Fibery apps gallery. Don't forget to remove the app from Fibery integration apps catalog after testing.

Add, edit or remove custom integration app

Let's assume you created an app, made it's url available and are ready to try it in Fibery. Our holidays app is deployed to Heroku and accessible at https://holidays-fibery.herokuapp.com

How to add custom app

Navigate to space you would like to integrate and click integrate button, find add custom app option and click. Follow the flow.

How to edit custom app

You can change the link to a custom app or force an update to the configuration of the app after deploying it to production by finding your app in catalog and clicking on settings icon in right upper corner.

How to delete custom app

You can delete a custom app by finding your app in the catalog and clicking on settings icon in right upper corner. In case of app deletion, the databases will not be removed and relations to the databases will not be affected.

Find the source code of this app and other examples in our public gitlab repository.

Find the documentation about creating integrations apps here.

The public holidays app can be found at https://holidays-fibery.herokuapp.com

Please let us know about any questions or comments.

Did this answer your question?