Yesterday IBM released the prototype version of the DQL Explorer that was demoed some weeks ago at IBM Think by Luis Guirigay on OpenNTF and Github. Of course the interest was tremendous and so I was enthusiastic to test it out.
However, there are currently some caveats to deal with and this post explains what I found so far.
There are three different ways to get into the deploying process of the final application:
- download the pre-built NSF file from OpenNTF
- clone the repo from Github and also use the NSF file which is shipped here, too
- clone the repo from Github, built the web component and assemble everything in the NSF
The third option also offers the possibility to run the web component in development mode which means that it runs independent form the NSF on your local machine and you can have a look into the source code, which is quite interesting. The problem is that I could not get it to work, I get errors when I try to access it on my local machine though I followed the instructions.
Regarding the web component’s source code: it’s written in Node.js and is using React as the UI renderer. I am not familiar with that stuff so there is something to learn.
On the other hand the NSF part is quite straight forward. It’s using Lotusscript agents for the REST calls and they execute the DQL queries. It has nothing to do with the Proton task and so you are able to run the NSF also on Windows machines.
Preperations
After you put the NSF on your server you have to edit the two documents that come with it (in the view „Lookups“):
- directories to search: you may want to remove the default value there but don’t leave it blank. Just put a / in the field
- file names to include: here you can specify certain databases to work with if you don’t want to use a whole directory
But there are some issues I already documented:
- using complex databases as a source may result in hangs of the „getdatabases“ agent or even a server crash
- I had a database from which the agent returned fieldnames that were empty and this will end up in errors in the UI
- it seems that special characters like / (a slash) in a field value also produce invalid JSON
The first issue occured with the fakenames NSF (or basically any other database which is based on the Domino Directory template). It seems to bee too complex to be scanned by the agent so the JSON will be too big to handle - I don’t know the actual reason for the error you get (the agent won’t be executed in a reasonable amount of time, though this will happen only after only a few seconds) or the server crash. I guess it’s a memory limitation for web agents written in Lotusscript. If you can please choose a much simpler database for the start. I used Theo’s Wine Tasting app again. It’s not the most interesting data structure there but it works.
For the second problem I used a database I created long ago that only contains a small subset of documents from the fakenames NSF and which is basically only to demo the Datatables JQuery plugin, so data structure is also not very interesting. However, there seems to be a problem reading field names from the forms. I recommend you to have a look into the agent’s code to see what’s going on there. I already added error handlers in all 3 agents.
The third was something I’ve seen today from Ulrich’s example and I can’t confirm on that, yet.
Anyway, make sure you set the ACL correctly (Anonymous shoudn’t be able to access the database) and sign it with an approriate ID.
For every app you want to search in you have to activate the design catalog by issueing the updall command:
load updall <database.nsf> -e
load updall <database.nsf> -d
If it’s all done, you should be able to access the app under
http://<yourserver>/dqlexplorer.nsf/index.html
and it should look something like that:
Thanks to all who made this cool example possible! 