Zendesk to Neo4j Integration — Building the UI
This document will explain how the Zendesk dashboard was developed using the graph-based application development framework Structr from our partner of the same name.
This is a continuation of Zendesk to Neo4j Integration : Better control over your reporting needs
Now that we have demonstrated how to utilize the Zendesk REST API along with Neo4j APOC to read data from Zendesk and build the associated nodes/labels and relationships in Neo4j, reporting becomes a very simple task given the Cypher language.
But like so many Neo4j experiences the next step becomes displaying the data in a UI other than the default Neo4j browser. More than likely you are going to have users that are not familiar with Cypher or want a user interface more than what the Neo4j browser offers.
It should be noted that everything presented was built by me. Whereby my development skill set is best summed up as having a good grasp of Linux and Cypher, and effectively HTML 101 skills (i.e. I know the difference between a <a href> vs a <table> tag) and an ability to minimally read Javascript. And with such skill set, I was able to create professionally looking HTML pages in a fairly short amount of time.
The example was built using Neo4j 3.4.x, the APOC library and Structr 3.0. The entire Structr experience is hosted with a Jetty webserver that is included with Structr.
A simple page which allows the user to get a one-click experience to view details on a specific organization will look similar to
To which upon initially arriving on this page the user will select the Organization defined in Zendesk from the drop down in the top left corner.
Once selected the data in the right frame is then populated.
As to the construction of the UI, Structr provides an IDE which allows you to start by
- import webpage templates,
- add your HTML elements
- bind the HTML elements to a Cypher statement result
The Structr tutorials suggest a good starting point for importing a Web page template is to use those which are provided at GetBootstrap.com. I thus imported their Dashboard as a starting template. To perform the Import, within the Structr UI click on the Import icon as depicted
The following dialogue will then prompt for the URL of the page to Import.
Once imported, your page is now in Structr and you can make edits as required. My goal in importing the GetBootstrap.com Dashboard page was to define the look of the page since I’m not an expert on CSS etc.
After importing the Structr IDE should then appear similar to
And upon clicking on an object in the right frame (i.e. the web page) should cause the tree-view structure on the left frame to advance to the corresponding element.
For each HTML element in the left frame/tree-view, and to the right of the object name were 4 options (‘Clone’, ‘Edit Properties’, ‘Remove’, ‘Access Control’). Initially, I used ‘Remove’ to clean up the web page and remove elements that I was not going to use.
Eventually, my page became a series of HTML tables. To bind a table row to a Cypher statement, click the ‘Edit Properties’ option next to the <tr> HTML object which should then produce the following dialogue.
By choosing the ‘Cypher Query’ tab I could then enter the Cypher statement to be bound to the table row.
And finally, the results of this query are then bound to the ‘Data Key’ which I have named ‘ZendeskUser’.
It should be noted that the Cypher Query approach needs results returned in a Cypher map, and thus the
return {oName: o.name, uName: u.name, ...}unlike what one might normally return for example,return o.name as oName, u.name as Uname,....
After clicking the ‘Save‘ buttons above I can then express elements of the <tr><td> using this ‘Data Key’.
From the display below the <tr> object has an icon of
indicating the HTML item is bound to a Cypher statement.
Further using the DataKey I can then define each <td> element under the <tr> row. For each <td> I have added a Content Element and added the placeholder of${ZendeskUser.uName}. I could refer to each element of my Cypher map with the ZendeskUser key prefix.
It’s as easy as that.
As for my final dashboard — It was simply a repetition of the above in terms of creating new tables, and defining the corresponding Cypher to populate the table data within each table row.
And Structr made this real easy through the use of the ‘Clone’ functionality which appeared next to every HTML element. So if I cloned the <table> element, it took the current <table> and made an exact clone and placed it immediately underneath the existing <table>. And then I only had to adapt the columns that needed to change.
Other Noteable Features of Structr
User Access
Structr has an ability to define its own list of users who can access the UI and which HTML elements the user can see. I did not entirely utilize this functionality but rather simply fronted all my pages with a Google OAuth plugin.
Content Storage
Most all of the Structr content (i.e. the HTML that makes up the page you have designed) is actually recorded in the Neo4j graph. This has the benefit that a Neo4j backup will save all your work performed within Structr.
Additional HTML
Structr allows you to define HTML items as required within the UI. So if you want to add some Javascript into your page, simply right mouse within the tree view and add a new <script> tag and then define its content.
In my dashboard example I utilized this functionality so as to support dynamic table sorting. Clicking on a column header will locally sort the table by that column header. To do this I added 2 <script> objects which utilized the example from http://luiliom.free.fr/
The Structr team was very helpful with my questions and I had quite some fun building this application. I can recommend you try it yourselves, starting with a similar example as mine.
