Please note that HP IDOL OnDemand is now HPE Haven OnDemand. The API endpoints have changed to Haven OnDemand. Please see the API documentation for more details.
Have you had a play with Find yet? It's a basic HP IDOL OnDemand search interface. What you might not know is that Find was designed to be a customisable, extensible interface - a platform to give developers a head start for building IDOL OnDemand UIs. We've released Find on GitHub under the MIT license so that anyone can take the source code and use it to develop their own interfaces.
What am I reading?
This is the first blog post in the Complete Find Guide series. We'll be taking you through how to get started with developing interfaces based on Find, adding features, calling new APIs and even submitting patches back to HP Autonomy for inclusion in the master repo.
Part 1: Getting Started with Find
Find comes in two parts - the frontend and the backend. Both parts have a somewhat different technology stack:
- Backbone.js - an MVC-ish framework to add some structure to the code
- Underscore.js - nice helper functions like map, reduce, and each. Build to help you work with Backbone.js
- jsWhatever - a collection of our formerly-internal, now-open-source utility functions for our stack
- Bower - dependency management for the web - means we don't have to package all the libraries listed above along with the project. Instead we can just get them at build-time.
There are some other libraries used in the frontend, of course, but those are the core ones. Have a look at bower.json to see what dependencies we've specified. You can find the frontend code in src/main/webapp/static
- Spring MVC - server-side MVC framework for clean code separation.
- Lombok - generates getters and setters for Java, thank goodness!
As you've probably guessed from reading that, the backend is written in Java. This might not be the cool choice in 2015 (I'm a Node.js fan, personally), but it's a solid, dependable, mature language that a lot of developers are already familiar with. You can find the backend code in src/main/java
Before we can start hacking about with Find we need to get our development environment set up. We're going to need to install a few tools:
We need to download the source code from GitHub, so we're going to need a Git installation.
In addition to just the basic git program, you may wish to consider installing:
- Git for Windows - Formerly known as msysGit, this gives you a nice set of Unix command line tools and a Bash shell for Windows.
- Atlassian SourceTree - A very nice Git UI, available for Windows and OSX.
We need to install the latest Java JDK from Oracle. If you're on Linux then you can probably obtain this from a package manager - OpenJDK is fine.
Next up, we need an installation of Apache Maven - scroll down the page for the tedious installation instructions. Make sure you add the mvn binary to your system path. We'll need to run Maven from the command line later.
Finally, a much simpler one: Node.js. Download the installer and install it.
Getting the source code
Now that we've got our dev tools installed, we can grab the source code.
If we just want to use Find as-is, we can just clone the main repository:
- From a terminal/console window, cd to the directory you want to clone Find to.
- git clone https://github.com/hpautonomy/find.git
If you want to modify your own copy of Find, click the "Fork" button on GitHub, then copy the HTTPS clone URL from your new repo and git clone it.
Building and running Find
cd into the find directory that you just cloned from Git. We have a couple of prereqs to attend to before we can start the application.
- cp ./src/main/filters/filter-dev.properties.example ./src/main/filters/filter-dev.properties
This sets up your development config filters file, which is used by Maven. Don't worry about it for now.
- Create a "home directory" for Find somewhere on your file system, e.g. "C:\dev\home\find" or "/opt/hp/find". This is used for storing the webapp configuration and log files.
mvn jetty:run -Dhp.find.home=YOUR_FIND_HOME_DIRECTORY
(e.g. `mvn jetty:run -Dhp.find.home=/opt/hp/find`)
(Note: if you're behind an HTTP/HTTPS proxy, you will need to set two additional Java System Properties (the -D arguments): find.https.proxyHost and find.https.proxyPort. Otherwise, Find won't be able to communicate with IDOL OnDemand. Yes, this bit me while writing this blog post (╯°□°）╯︵ ┻━┻))
The console output should end with "Starting scanner at interval of 3 seconds" or similar. This means that the server has started successfully! Navigate to "http://localhost:8080/find" in your browser and you'll see the login screen. As we're in initial setup mode, Find will have created a config file in the home directory you gave it on the command line - open the generated config.json file in an editor of your choice and copy the randomly generated password into the login screen.
On the Settings page we need to configure two things - our IDOL OnDemand API key and our admin username and password.
Enter your API key, then click "Test Key". If it's successful, you'll get an "API Key OK" message and a list of indexes to search on. Select all the indexes that you want to use.
Once you've entered a password for your admin user, click the big "Save Changes" button at the top of the screen. The config.json file will be updated with your settings. If we ever need to reset Find to a clean slate, deleting the config.json and restarting the server will put us back into initial setup mode.
Click the "Logout from settings" button at the top of the screen. You'll see the main Find search screen.
That's all for today!
Thanks for reading! We now have the Find source code on disk and a local copy running. Next time we'll be looking at how to add a new page.
You must be a registered user to add a comment here. If you've already registered, please log in. If you haven't registered yet, please click login and create a new account.