Contact tracing guide for the Neo4j Browser

Based on the past two blogposts on (Covid-19) contact tracing (see here for the posts, here for the movies), I thought it would be a good idea to pick up an old skill - to create a Browser Guide for Neo4j for people to look at this dataset example more easily. I did this a long time ago for my beergraph as well, so why not do it for the contacttracinggraph :) ...

About the Neo4j Browser and Browser guides

Here's what this is: with Neo4j, the native graph database, we always ship a default user interface called the "Neo4j Browser". It's a interactive application that communicates with the database, and that essentially allows you to fire of Cypher queries and look at / manipulate the contents of your database. Read up about it over here. Once you have done that you will realise that the Browser is actually more than that: it's also a great way for people to learn more about Neo4j, and has a built in mechanism to share "guides" to various topics. If you experiment a bit with the following commands:

Title	Description	Command
Intro	A guided tour of Neo4j Browser	:play intro
Concepts	Graph database basics	:play concepts
Cypher	Neo4j’s graph query language introduction	:play cypher
The Movie Graph	A mini graph model of connections between actors and movies	:play movie graph
The Northwind Database	A classic use case of RDBMS to graph with import instructions and queries	:play northwind graph

you will get to see a number of topics that allow you to familiarise yourself with it really easily. Most of these guides are either built in or available for serving from a webserver. But: you can also develop these guides yourself. There's a really nice worked example over here, but the process really is dead simple:

• you create an asciidoc document. 
• you run it through a tool (see below) to create the correct HTML page from that document
• you rename that html page (if necessary) to <filename>.neo4j-browser-guide - the file extension is important
• you drop that file onto your Neo4j Desktop application
• you click that file, and the Neo4j Browser will open, and the guide will appear.

Simple as that. Let me show you.

Creating the ContactTracingGuide for the Neo4j Browser

Here's the asciidoc file that I created from all the queries that I had posted in my previous blogposts:

There's really nothing special about this. The only thing that you have to keep in mind is that the

• == headings in the asciidoc will create new "slides" in the Neo4j Browser guide
• [source,cypher] elements will become clickable elements in the Neo4j Browser guide that will actually allow you to click a query and copy it to the execution pane at the top of the Browser.

It's really quite easy. Then I had to download the utility from the Neo4j github pages. Unzipping it into a directory, and preparing for ruby to be installed properly on your machine are necessary steps first, and then you can just run

./run.sh adoc/contacttracingguide.adoc html/contacttracingguide.html

and you will see that the utility starts doing its thing:

As I mentioned before, the result of the utility is basically a simple HTML file: look over here for the result.

Now we can use that html file as a Browser guide.

Using the generated Neo4j Browser Guide from Neo4j Desktop

The only step that you need to take now, is to rename the contacttracingguide.html file that we generated to contacttracingguide.neo4j-browser-guide. Kind of a silly change, but we need to do that in order for the Neo4j Desktop to recognise this file as a browser guide. Once we have done that, you can just fire up the Neo4j Desktop, start an empty database, and add the contacttracingguide.neo4j-browser-guide file to the Desktop's file section:

 That's really it. Once you have done that and your Neo4j database is running, you can just click the contacttracingguide.neo4j-browser-guide file, and the Neo4j Browser will start with the guide as the opening screen:

That's it. Now you can just walk through the steps at your own pace, and take the demo dataset for a spin.

Hope this is useful. As always, comments welcome!

All the best!

Rik