Elasticsearch is a powerful search engine that provides numerous unique, configurable options, including "fuzzy matching” (i.e., matching similar words), predictive search, and auto-completion.
Elasticsearch is enabled by two web services, one used by Flare and the other used by Elasticsearch. The Elasticsearch web service runs a portal that allows you to manage the targets, topics, and indexes employed by the Elasticsearch engine in your server-based HTML5 target.
General Steps for Using Elasticsearch
These are the steps needed to set up Elasticsearch.
- Set Up Server Configure a remote server to store your search indexing data. This is usually done by a network administrator.
- Set Search Engine Select Elasticsearch as the search engine in the Target Editor.
- Create Destination Files Add and configure primary and Elasticsearch destination files so you can publish your output and search results.
- Connect Destinations with Target Associate your publishing destinations with the HTML5 target.
-
Generate and Test Output Build the HTML5 target. When the build is near completion, you will notice a new icon display in the system tray. This is for the MadCap Process Manager, which will handle the web services required for Elasticsearch if you are running locally on your machine.
Once the build is complete, start testing your output with a few searches to ensure Elasticsearch is working in accordance with your configuration.
- Manage Search Indexes As your Elasticsearch output is searched, you may want to control the size of the indexes for your target.
Note: You can also modify the appearance of your auto-complete suggestions in the search results.
Setup Example
Example
Bob wants to use Elasticsearch with his HTML5 output.
First, he sends his network administrator the steps for setting up a Elasticsearch remote server
After the network administrator finishes setting up ther server, she sends Bob the URL for it. In this case, let’s say the URL is https://ourelasticsearchservices.fictionsoft.com.
Bob opens his HTML5 target, selects the Search tab, and chooses Elasticsearch as the search engine type.
He also decides which Elasticsearch options on that tab he wants to use and sets them accordingly.
Next, Bob creates a primary publishing destination. This is the destination where he will send his output.
Let’s say Bob needs to upload his output to this location:
help.fictionsoft.com/myoutput/
One option is that Bob could use file transfer protocol (FTP) to copy his output directly up to the server where his output will be hosted. But suppose Bob prefers to use a third-party tool (say, FileZilla) to transfer his output files to the server. In that case, Bob chooses File System as the type, and for the directory he selects a folder that he created in his My Documents folder.
Now Bob creates an Elasticsearch destination file. In this file, he chooses Elasticsearch as the type, and he enters the URL that his network administrator gave him (https://ourelasticsearchservices.fictionsoft.com).
Next, Bob returns to his target and opens the Publishing tab. In this tab, he places a check mark next to his primary destination. Then in the Elasticsearch Destination cell, he chooses the other destination file.
After saving all his changes, Bob builds the target. When that is done, he clicks the Publish button in the Target Editor, which copies the output files to the local folder he set up in his My Documents directory.
Finally, Bob uses his third-party tool to transfer the output files from that My Documents folder up to their final destination (help.fictionsoft.com/myoutput/). When users access that output, the search function will be using Elasticsearch features.
Notes
Note: You must use Elasticsearch version 5.6, as that is the version supported by MadCap Flare.
Note: If you enable the Mark of the Web setting in your Elasticsearch target and viewing the output locally in Internet Explorer, you will continuously receive the following warning message:
This message will display every time you enter search criteria. In order to avoid receiving this message, it is recommended that you disable the Mark of the Web setting.
Note: Synonyms are not supported in Elasticsearch.
Note: If you are viewing your generated Elasticsearch output on Microsoft Edge, you will not be able to search. In order to use Edge for your Elasticsearch output, you will need to run the following command prompt one time as an administrator:
-
CheckNetIsolation LoopbackExempt -d -n=Microsoft.MicrosoftEdge_8wekyb3d8bbwe
This will disable loopback in your Edge browser and allow you to use your Elasticsearch target in Edge. For more information on this, visit Enabling Elasticsearch Targets In Microsoft Edge.
Note: Elasticsearch is not supported for outputs hosted through MadCap Central.