REST search result suppliers for Global Search

Search result suppliers are responsible for providing search results to the Global Search search result list through the Periscope, its back-end. Below, we describe how you can configure and use search result suppliers that integrate search results of external content through REST.

This feature is only available in the DX Core edition of Magnolia.

For information about the Magnolia supplier that searches over defined JCR workspaces or about creating a custom search result supplier, see Periscope module: Search result suppliers.

Configuration properties

The REST-based supplier functionality for the Periscope module is provided by the magnolia-rest-client-ui module as a combination of the following specific Magnolia classes:

info.magnolia.rest.ui.periscope.RestClientResultSupplierDefinition
info.magnolia.rest.ui.periscope.SearchResultExpressionDefinition

A REST-based search result supplier can be created as a YAML file and configured using the following properties:

Property Description

Property	Description
`class`	required `info.magnolia.rest.ui.periscope.RestClientResultSupplierDefinition`
`restClient`	required Name of a configured REST client to fetch search data with.
`restCall`	required Name of a configured REST call definition in the client.
`searchResultExpression`	required List of JSON path expressions to get data for each item to be shown in the Global Search results list. Provided by the `info.magnolia.rest.ui.periscope.SearchResultExpressionDefinition` class.
`title`	required Expression to get the title of the item, for example: `$.values[*].title`
`url`	required Expression to get the URL address of the item, for example: `$.values[*].links.html.href`
`content`	optional Expression to show the detail of the item.
`editor`	optional Expression to get the editor name of the item.
`date`	optional Expression to get the last-modified date of the item. YAML files with configuration of search result suppliers should be stored in the `searchResultSuppliers` folder of your module: `<module-name> ├── apps ├── contentTypes ├── decorations ├── i18n ├── module.yaml ├── restClients │ └── <rest-client-name>.yaml ├── restEndpoints ├── searchResultSuppliers │ └── <search-result-supplier-name>.yaml └── templates`

class

required

info.magnolia.rest.ui.periscope.RestClientResultSupplierDefinition

restClient

required

Name of a configured REST client to fetch search data with.

restCall

required

Name of a configured REST call definition in the client.

searchResultExpression

required

List of JSON path expressions to get data for each item to be shown in the Global Search results list.

Provided by the info.magnolia.rest.ui.periscope.SearchResultExpressionDefinition class.

title

required

Expression to get the title of the item, for example:

$.values[*].title

url

required

Expression to get the URL address of the item, for example:

$.values[*].links.html.href

content

optional

Expression to show the detail of the item.

editor

optional

Expression to get the editor name of the item.

date

optional

Expression to get the last-modified date of the item.

YAML files with configuration of search result suppliers should be stored in the searchResultSuppliers folder of your module:

<module-name>
├── apps
├── contentTypes
├── decorations
├── i18n
├── module.yaml
├── restClients
│ └── <rest-client-name>.yaml
├── restEndpoints
├── searchResultSuppliers
│ └── <search-result-supplier-name>.yaml
└── templates

Sample REST integration

The following configuration files illustrate how you can deliver search results from outside of Magnolia. When enabled, the supplier definition integrates the GitHub API: Search issues and pull requests.

Supplier definition

class: info.magnolia.rest.ui.periscope.RestClientResultSupplierDefinition
restClient: github
restCall: searchGithubIssues
searchResultExpression:
  title: $.items[*].title
  url: $.items[*].html_url
  content: $.items[*].body
  date: $.items[*].updated_at
enabled: true

Client definition

baseUrl: https://api.github.com
restCalls:
  searchGithubIssues:
    method: get
    entityClass: com.fasterxml.jackson.databind.JsonNode
    path: /search/issues
    queryParameters:
      q: "{query}"

If you then query GitHub’s issues, the search result area of the Global Search displays the results.

REST search result suppliers for Global Search

Configuration properties

Sample REST integration

Location

Main doc sections