Lucene Provider

Lucene is your go-to for universal search because it requires no additional software to use. Just activate and you're done.

Elasticsearch Provider

Elasticsearch is an open-source search index used by many of the largest websites including Netflix, eBay and the New York Times. It's free to use but does require that you have the ability to install software on your server. We provide a guide to installing Elasticsearch in the appendix of this guide.

If Lucene is the recommended provider, you might ask, "Why would I ever need Elasticsearch?" Good question! Elasticsearch allows you to pass the overhead of indexing and searching to another server. It's also the recommended approach if you are running in a clustered environment. For most organizations, however, it is overkill.

Understanding How Universal Search Works

Rock is made up of numerous types of data called entities. Entities are things like Person, Group, Group Member, etc. Universal Search supports indexing the following entity types (more could be added in the future based on community response).

• Site
• Person
• Group
• Content Channel Item
• Event Item
• Document
• Business

You might ask, why not index all entities? Working with search is a delicate balance between providing the information the user wants and overloading them with random results. For instance, does anyone want to see results for Workflow Action Types in their search response?

Enable a Search Provider

First, we'll need to tell Rock which search provider we'd like to use and provide the configuration details needed to connect. We do this under Admin Tools > System Settings > Universal Search Index Components.

Next, select the provider type you'd like to enable.

If you choose Lucene as your search engine, Rock displays the following configuration window.

If you choose Elasticsearch, Rock displays the following configuration window.

Enabling Entities for Universal Search

Now that we have a provider configured, we're ready to enable entities to be indexed. To do this, navigate to Admin Tools > General Settings > Universal Search Control Panel.

At the top of this page, you'll see a few details about the provider you selected. Below you'll find a list of the entities that are able to be indexed.

To enable a new entity type, click the row of the entity and select Enable Indexing on the dialog that pops up. This entity is now enabled for Universal Search and a request has been queued to bulk index this entity.

Keeping Entities in Sync

As you'll read later, the entities should keep the index up-to-date as changes are made. A system job has also been created to re-index every night (this ensures that items added through SQL or other means are addressed). The settings of this job can be adjusted under Admin Tools > System Settings > Jobs Administration > Universal Search Re-Index.

Person

The person entity is pretty basic. Once enabled, all individuals in the database will be sent to the index. You can add specific person attributes to be indexed as well (Admin Tools > General Settings > Person Attributes). When you add/delete attributes to the index, you'll want to run a bulk load on the Person index to ensure they are available right away. Otherwise, you'll need to wait until the bulk re-index happens that night. Don't forget; bulk loading is done from Admin Tools > General Settings > Universal Search Control Panel.

Business

Businesses don't have their own entity. In Rock business actually share the Person entity (which makes sense when you consider how businesses relate to things like giving). In Universal Search we do break them out, so they look like a separate entity to allow you better filter options (sometimes you want businesses in your results; sometimes you don't) but when it comes to setting up indexing and settings, remember that they share with people.

Group

When you enable groups to be indexed, you may wonder why nothing is displayed. Before groups are displayed, you'll need to configure which group types you want added to the index. You can configure this with the Group Type Editor (Admin Tools > General Settings > Group Types). Once you enable a group type, a call will be sent to immediately start bulk updating the groups (no extra steps required on your part).

When new groups are added or an existing group is modified, it will be immediately sent to the index.

You can also determine which group attributes you would like indexed. Changing the attributes will require a manual index re-load.

Applying a custom icon to the group type is a good idea, as it will be displayed in the results.

Content Channel Items

Content Channel Items work much the same way as groups. You'll need to configure which content channels you'd like to be indexed. You can also determine which attributes to include in the index. One other property to note is the Content Channel Item Publishing Point for the channel. This setting allows you to determine how to link to the resulting item. When left blank, the internal channel item page will be used. More commonly though, you'll want to provide a template to a custom page (like a blog detail page).

Site

Sites are quite different from the other entities discussed here. When you index a site, you are really interested in searching all of the pages of the site. To do this, one must crawl the site looking for all of the content of the pages. For instance, a single Blog Item Detail page will need to be crawled several times to retrieve each of the blog posts. When you enable the Site entity, you'll need to complete the following steps:

1. Enable each site that you would like to add to the index under Admin Tools > CMS Configuration > Sites. Edit the site's Advanced Settings to allow indexing.
2. Once enabled, be sure to add the Crawling Starting Location for the site. This is the URL that the crawler will use to start the index process.
3. Set up a new Rock Job to crawl the site on a schedule that you determine is best for your needs. This can be done under Admin Tools > System Settings > Jobs Administration. The job type will be Index Rock Site.

Indexing processes, even Google’s, use hyperlinks to find and index all the pages on site. So, if a link to a particular page doesn’t exist anywhere on your site, crawlers can’t find that page. To ensure all pages on your site are found and indexed, you could create a new page for the purpose of indexing. The page would contain nothing but links, including the home page of the site. The URL for the links page would then be used as the Crawling Starting Location referenced above.

Event Item

Indexing for event items is set at the calendar level. Edit the calendar under Tools > Calendars to turn on the Indexing Enabled setting. With indexing enabled, you can search for keywords that come from the event item’s title, description or summary.

Document

Documents can also be searched for and included in your search results. Unlike some of the other entities, there isn't a specific Indexing Enabled setting you'll need to turn on for different Document Types. Just enable indexing for Documents in the Universal Search Control Panel and you're off to the races. You can search for documents by Name or Type.

Default Entity Results

Each entity has a default result template that you can change. This is a great place to modify what you'd like to be returned across multiple search interfaces. You can edit these templates on a per-entity basis under Admin Tools > Security > Entity Administration.

There are two templates available for your customization. The first, Index Results Template, is the template for the result row of the search. The other, Index Document URL Pattern, is the Lava template for determining the URL for the specific result when used in the Smart Search.

Let's consider a use case for how you might want to modify these templates. Say you have a custom group type in Rock that you would like to display differently than the normal group result. Perhaps you'd like to add a specific attribute value for the group and link to a different group detail page. This is all possible by updating these two Lava templates.

Sample Results Template

{% assign url = "~/Group/" | ResolveRockUrl %}

{% assign groupTypeId = IndexDocument.GroupTypeId %}
{% if groupTypeId == 24 %}
    {% assign url = "~/Organization/" | ResolveRockUrl %}
{% endif %}

{% if DisplayOptions.Group-Url and DisplayOptions.Group-Url != null and DisplayOptions.Group-Url != '' %}
    {% assign url = DisplayOptions.Group-Url | ResolveRockUrl %}
{% endif %}

<div class="row model-cannavigate" data-href="{{ url }}/{{ IndexDocument.Id }}">
    <div class="col-sm-1 text-center">
        <i class="{{ IndexDocument.IconCssClass }} fa-2x"></i>
    </div>
    {% if groupTypeId == 24 %}
        <div class="col-sm-4">
            <strong>{{ IndexDocument.Name }}</strong> <small>({{ IndexDocument.GroupTypeName }})</small>
            {% if IndexDocument.Description != null and IndexDocument.Description != '' %}
                <br> 
                {{ IndexDocument.Description }}
            {% endif %}
        </div>
        <div class="col-sm-7">
            {{ IndexDocument.MemberList }}
        </div>
    {% else %}
        <div class="col-sm-11">
            <strong>{{ IndexDocument.Name }}</strong> <small>({{ IndexDocument.GroupTypeName }})</small>
            {% if IndexDocument.Description != null and IndexDocument.Description != '' %}
                <br> 
                {{ IndexDocument.Description }}
            {% endif %}
        </div>
    {% endif %}
</div>

Notice the checking of the group type to customize the URL and the results.

Sample URL Template

{% assign url = "~/Group/" | ResolveRockUrl %}

{% assign groupTypeId = IndexDocument.GroupTypeId %}
{% if groupTypeId == 24 %}
    {% assign url = "~/Organization/" | ResolveRockUrl %}
{% endif %}

{% if DisplayOptions.Group-Url and DisplayOptions.Group-Url != null and DisplayOptions.Group-Url != ' %}
    {% assign url = DisplayOptions.Group-Url | ResolveRockUrl %}
{% endif %}

{{ url }}/{{ IndexDocument.Id }}

Custom Lava

When using the default search block, you can process your results through custom Lava you produce. This Lava is provided as a block setting. You'll need to both enable the usage of the custom Lava and provide a Lava template. A very basic template is provided as a starting point.

Search Lava Command

When you want 100% control, you can drop down and use the "search" Lava command. This command works very similarly to the entity commands and allows you 100% control of the formatting of your results. See the documentation for this command in the Lava docs at community.rockrms.com/lava.

Elasticvue

Once you're done setting up Elasticsearch, you may want to consider installing Elasticvue. It's a nice administrative console for Elasticsearch which gives you some visibility into what's going on under the hood. It comes as a browser extension, which is easy to set up. To do this simply:

1. Visit elasticvue.com and scroll down to the "Get elasticvue" section.
2. Click the button for the browser you want to add the extension to and install the extension.
3. Access the extension in your browser. You'll need the UserName and Password from the steps in the prior section above. The "Uri" field should be populated, but if it's not set it to http://localhost:9200.
4. Click Test Connection and if all goes well click Connect.

Multiple Environments

If you have an Elasticsearch server configured in different environments on separate VMs, you’ll need to make some changes after refreshing from one environment from the other. Generally, this applies when you’re refreshing a sandbox environment from a production environment.

The settings in Rock must be changed to point the refreshed environment to the correct Elasticsearch server.

To do this, go to Admin Tools > System Settings > Universal Search Index Components and click on Elasticsearch 8.x. Then, update the following fields according to your Elasticsearch setup:

1. Node URL
2. UserName
3. Password
4. Certificate Fingerprint ("SHA Certificate" in Elasticsearch)

Note that you may not need to update the UserName if they’re the same in both environments.

Your sandbox environment will not be able to reach your production Elasticsearch server until these updates are made. This can be confirmed by going to Admin Tools > General Settings > Universal Search Control Panel. If the node hasn’t been updated after a refresh, you’ll see a message indicating a connection to the Elasticsearch server cannot be made.