How to connect Tockify with Ninox
This "how-to-connect" documentation will explain the initial configuration of an example connection from Tockify to a Ninox database. We will be synchronizing data stored in Tockify.
This guide presupposes that you have installed the Layer2 Cloud Connector and that you are familiar with its basic functionality. The Layer2 Cloud Connector User Documentation will provide you with all necessary information.
1. Configuring Tockify
2. Configuring the Layer2 Cloud Connector
2.1 Creating a new connection
2.2 Configuring the Data Entity 1
2.3 Configuring the Data Entity 2
2.4 Running your connection
3. Hints and known issues
3.1 Connection direction
1. Configuring Tockify
To send data from your Tockify calendar to another system, you must generate an .ics-file from your calendar. Go to a browser and paste this URL https://tockify.com/api/feeds/ics/nameofyourcalendar setting the name from the calendar you want to get the .ics-file from at the end. Pressing enter should generate a file like in the picture.
You must now import the generated .ics-file into your Outlook. Right click on the .ics-file / Open With / Outlook should give you this picture:
2. Configuring the Layer2 Cloud Connector
2.1. Creating a new connection
Create a new connection by using the Create New Connection option in the Actions pane (right-hand side). The new connection will appear at the bottom of the Connection Manager List (left-hand side). Click on your newly created connection to open the connection configuration settings.
Choose a meaningful name for your connection and replace the current "New Connection" Connection Title with it.
Connections from Tockify can be uni-directional only. An initial connection should always be uni-directional to assure that both data entities are identical before switching to bi-directional. Therefore, choose Left to Right as Direction.
2.2. Configuring the Data Entity 1
We will now set up our Data Entities. Go to the data entity “Data Entity 1” to open the configuration settings.
Choose a Data Entity Title. It is recommended to give your entities meaningful names to maintain an overview when you decide to set up multiple connections.
Select the Data Provider for Exchange from the data provider list. You can search for Exchange by typing into the selection box.
For the Connection String, we need the URL parameter, the user e-mail address where the calendar were imported to and the password for this user. You can copy the below connection string and adjust it to match your gathered information. Use the Verify Connection String option to evaluate if the provided connection string is valid.
- "URL=outlook.office365.com;" this property points to the Outlook system
- "[email protected];" this property points to the user e-mail address
Set your password in the designed field.
The Select Statement text box is used to define specific data queries. We will be gathering the information from the Calendar layer2tockify. Check the name of your calendar in Outlook first and set the name at Calendar/calendarname. You can copy the below select statement and adjust it to match your needs. Save your changes by using the right-hand pane option Save Changes.
SELECT * FROM "Calendar/layer2tockify"
To check if all necessary columns are received, you can use the Preview Data option on the right-hand pane which will provide you with a pop-up window showing your sample data from your Tockify entity.
2.3. Configuring the Data Entity 2
To connect to Ninox we must generate an API key first. Go to https://user.ninoxdb.de/account/api, log in with your Ninox account and in the tab account/API generate a new API key and copy the generated value.
If you do not have one, create a database in your Ninox and a table with the wanted fields to match your Tockify columns data inside the created database. We are going to send our Tockify data to a table called CustomTockifyCalendar inside a database named Tockify we created.
In the Layer2 Cloud Connector, use the left-hand pane to switch to the data entity "Data Entity 2". We will be using the JSON Provider for this setup.
Additionally to the API Key we have created, our final connection string contains three ID values which we need to gather in a step-by-step setup. This step-by-step setup will adjust the connection string and adds a new ID value with each iteration. The first connection string looks like this:
Replace the placeholder "yourapikey" with your generated Ninox API key. Also add the following select statement to the Select Statement frame:
SELECT * FROM json
Now click on "Preview Data" in the right-hand pane. This will give you a table visualization from this API endpoint. Gather the team ID as we will need it for the next step. Paste the placeholder "teamid" in the URI of the below URI and add the endpoint databases. You can copy the below connection string, but if you do keep in mind to also add the API key again.
Clicking on preview again will give you the databases and the ids. Copy the id from the database you want to connect to, add the value to the URI and the endpoint tables.
Clicking on preview again will give you the tables and the ids. Copy the id from the table you want to connect to, add the value to the URI and the endpoint records.
Clicking on preview should show all the records for the selected table, if the table has records or shows an empty preview if the table has no records.
Now you can use this complete connection string for the connection to the records of a table inside a database in Ninox:
- "URI=https://api.ninoxdb.de/v1/teams/.../endpoint;" this property defines the endpoint you want to write/read data to/from.
- "CustomHeaders="Authorization Bearer yourapikey";" this property must point to the generated API key.
- "DataModel="FlattenedDocuments;" this property says we are going to flatten the JSON results.
- "GenerateSchemaFiles=OnUse;" this property is set to OnUse in order to generate the needed schema file.
- "Location=yourpath;" this property must be set to the folder we want to save our generated schema file. NOTE: we must edit this file to write into Ninox.
- "Other=BatchSize=1;" this property should be set to avoid errors with bulk updates, inserts or deletes.
Clicking on preview data now generates a file in the Location path from your connection string named json.rsd. Open this file and delete the parameter key="true" from the attribute name="json:_id". Set the key="true" parameter to the attribute name="id". It should look like this:
<attr xs:type="integer" readonly="readonly" name="id" other:xpath="/json/id" key="true">
<attr xs:type="string" readonly="readonly" name="json:_id" other:xpath="/json/_id">
Add this line after the line where the attr="URI" is defined after the api:info block.
<api:set attr="ContentType" value="application/json" />
At this point you can read from the Ninox endpoint. You also must add the INSERT, UPDATE and DELETE blocks in order to write records into the table. The field names should match the names from your table columns in Ninox. An example for this file can be found in the section 3.2
Also set a primary key for this entity. In the next step, we will configure our mapping settings. Click on the Mappings option on the left-hand pane. If your fields from SharePoint are named identical to the fields from your source system, the Enable Auto Mapping option will match those columns. Disabling this option allows you to match your columns as needed. Save your changes by using the right-hand pane option Save Changes.
2.4. Running your connection
To run your connection switch back to the main connection configuration node and use the Run Now Button located on the bottom of the setup page. NOTE: This will only work after you make the changes showed in the section 3.2. The Run Synchronization Toolbox will also display the synchronization process.
Below is a data preview of the information we have accessed in our source entity:
This will be the result in our Ninox table after our initial successful synchronization:
See section 3.1 for further information.
3. Hints and known issues
3.1. Connection direction
As far as tested, this connection supports uni-directional only
In order to write into your Ninox table, the .rsd-file you generated must implement the INSERT, UPDATE and DELETE operations. The blocks must contain the URI attribute pointing to the Ninox API endpoint from your table records. The UPDATE block becomes the id from the record to be updated in the body. The DELETE block gets also the id from the record we want to delete at the end from the endpoint URL.
The INSERT block needed the attribute URI pointing to the records endpoint from the table where you want to make inserts to. The attribute data must be built accordantly to the Ninox API. You can use this as an example but the field names must match your attribute names from the .rsd-file:
The UPDATE block looks like the INSERT block but the Ninox API requires the record id for the update:
The DELETE block is easier. The record id for the operation comes at the end from the URI endpoint:
The complete file with the comments can be found here.