Periscope module

Operations Bundled: Framework

Edition CE

License

MLA, GPL

Issues

MGNLPER

Maven site

Periscope

Latest

2.0.1

The Periscope module provides back-end functionality used by the Global Search. It can be used out-of-the-box to search all content apps or extended by activating search in external data sources and by implementing operations commonly used by your users.

The Global Search brings the back-end search functionality of the Periscope module into the Magnolia UI. It provides the UI display of the Global Search box, search results list, and filter buttons to refine results.

Module structure

artifactID Description

magnolia-periscope-core

Provides the default search result supplier and periscope operation configuration files.

magnolia-periscope-api

Provides an API to plug in search result suppliers to the search result set, as well as to create your own query sniffers (for example, for vocal commands).

magnolia-speech-recognition

Provides speech-to-text recognition capabilities.

Installing with Maven

Maven is the easiest way to install the module. Add the following to your bundle:

<dependency>
  <groupId>info.magnolia.periscope</groupId>
  <artifactId>magnolia-periscope-core</artifactId>
  <version>2.0.1</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>. 
<dependency>
  <groupId>info.magnolia.periscope</groupId>
  <artifactId>magnolia-periscope-api</artifactId>
  <version>2.0.1</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>. 
<dependency>
  <groupId>info.magnolia.periscope</groupId>
  <artifactId>magnolia-speech-recognition</artifactId>
  <version>2.0.1</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>.
The functionality of the QuerySniffer and OperationRequest components is now handled by the Global Search system. The magnolia-speech-recognition code is no longer linked to the new Global Search functionality. This obsolete code is non-functional and will be removed to streamline the codebase.

Configuration

There’s no additional configuration required for standard use because the default configuration provides a number of search result suppliers.

You may configure additional search result suppliers and periscope operations to suit your specific needs.

Search result suppliers

Search result suppliers are responsible for providing results to the Global Search.

Example supplier definition (for the Pages app content):

/pages/searchResultSuppliers/pages-app.yaml
class: info.magnolia.periscope.search.jcr.JcrSearchResultSupplierDefinition
appName: pages
workspace: website
nodeTypes:
  - mgnl:page
fullTextSearch: true
titleProperty: title
icon: icon-webpages-app
For REST integrations

You can define a search result supplier using YAML for integration of external data set through REST. For more details, see the page REST search result suppliers for Periscope.

For JCR workspaces

Content apps are detected when you start Magnolia and the system generates corresponding SearchResultSuppliers for their JCR workspaces automatically.

You only need to define a search result supplier using YAML to search JCR workspaces if you want to customize the supplier.

Magnolia provides a registry with a specific info.magnolia.periscope.search.jcr.JcrSearchResultSupplierDefinition class that searches over defined JCR workspaces using specific node types and with the option of performing full-text search.

In the example below, the JcrSearchResultSupplierDefinition class, <my-custom-workspace> workspace and <my-node-type> node type are specified. Full-text search is activated within the workspace defined.

/my-module/searchResultSuppliers/appName.yaml
class: info.magnolia.periscope.search.jcr.JcrSearchResultSupplierDefinition
workspace: <my-custom-workspace>
appName: <app-to-open>
nodeTypes:
  - <my-node-type>
fullTextSearch: true
titleProperty: caption

JcrSearchResultSupplierDefinition properties

Property Description

class

required, default is info.magnolia.periscope.search.jcr.JcrSearchResultSupplierDefinition

Fully qualified class name of the supplier definition. Must implement the info.magnolia.periscope.search.SearchResultSupplierDefinition interface.

workspace

required

Name of the workspace in the magnolia repository you want to search.

appName

optional

Name of the app that opens when a search result is clicked.

nodeTypes

required

List of node types you want to search. If no value is specified, the supplier will search all node types.

titleProperty

required

Title of the searched node. Always searched by default and used as a title for the result.

nodeNameProperty

required default is jcrName

Restricts the search only to match a specific node name.

rootPath

optional, default is /

Path configured as the root of the workspace. Only content below the path is operated on.

enabled

optional, default is true

When false, the supplier is disabled.

fullTextSearch

optional, default is true

When false, only node names are searched. See also the propertySearch property.

propertySearch

optional, default is false

When true, only property names are searched. See also the fullTextSearch property.

resultLimit

optional, default is 100

Limit on the total number of search results that can be retrieved.

timeoutSeconds

optional, default is 15

Specifies the timeout duration in seconds for individual search supplier operations.

Behavior

  • Each supplier operates independently with its own timeout.

  • If a supplier exceeds its timeout, it returns empty results, but other suppliers continue processing and return results as normal.

  • The overall search operation completes, aggregating results from all finished suppliers.

  • Timeouts are handled gracefully, with no exceptions thrown to the client.

  • Lower values (5–10 seconds): For faster responses, but complex searches may be truncated.

  • Higher values (30–60 seconds): For more comprehensive searches, but expect potential delays.

  • Balance search thoroughness with user experience.

  • Monitor supplier performance to fine-tune timeout values for specific use cases.

strategy

optional, default is info.magnolia.periscope.search.jcr.JcrSearchResultSupplierStrategy

Strategy used to construct a search result supplier from JcrSearchResultSupplierDefinition. Must implement the info.magnolia.periscope.search.SearchResultSupplierStrategy interface.

order

optional

Node containing the order configuration of search results. See the info.magnolia.periscope.search.jcr.JcrSearchResultSupplierOrder class.

     property

required

Node type property to sort search results by. Use a Magnolia node type or define your own property.

     sortBy

required

A map where:

  • The key (String) is an attribute to sort by.

  • The value is a sort direction (ASC or DESC) for the given key.

subAppName

optional, default is browser

Name of the subapp that opens when a search result is clicked.

detailSubAppName

optional, default is detail

Name of the detail subapp that opens when a search result is clicked.

icon

optional

CSS class that identifies an icon used for the supplier.

label

optional

Text displayed on the supplier icon. The value is i18n-able.

Creating a custom search result supplier

If you want to search non-JCR databases or external datasets, you must create your own corresponding SearchResultSupplier.

Use the info.magnolia.periscope.search.SearchResultSupplierDefinition interface provided by the magnolia-periscope-api submodule to implement a search result supplier.

public interface SearchResultSupplier {
    String getName();
    Stream<SearchResult> search(SearchQuery query) throws SearchException;
}

Each SearchResultSupplier is responsible for supplying results. The results of suppliers are represented by SearchResult objects which contain text, metadata and a periscope operation request, which specifies what should be done when a user selects that result.

public class SearchResult {

    private final String title;
    private final String content;
    private final String path;
    private final OperationRequest operationRequest;

    private final String type;
    private final String lastModifiedBy;
    private final ZonedDateTime lastModified;
    private final Status status;
    private final SearchResultItem resultItem;

}

Search results

You can modify the existing search results configuration by the definition decoration mechanism.

For example, the following light module configuration updates the defaultCountPerSupplier to 3, allowing you to see only up to three search results.

<my-module>/decorations/periscope-core/config.yaml
globalSearchConfiguration:
  defaultCountPerSupplier: 3

Configurable properties

The table below lists properties that affect how search results appear.

Property Description

suppliers

optional

List of search result suppliers.

See also Search result suppliers.

supplierOrder

optional

List defining the ordering of search result groups.

editorRoles

optional

List of user roles available in the Author search filter.

All users are available unless specified otherwise.

defaultCountPerSupplier

optional, default is 50

Integer defining the maximum number of search results shown from any single search supplier.

Disabling result ranker

The boolean disabled property of the info.magnolia.periscope.ResultRankerConfiguration allows you to entirely disable the ranking of Global Search results.

Asynchronicity of search queries

To improve search performance for multiple threads trying to get the same session on the same workspace, you may need to change the limit of the total number of concurrent queries.

Go to the magnolia.properties file and adjust the magnolia.periscope.result.supplier.thread system property value.

Example configuration

/periscope-core/config.yaml
resultRankerConfiguration:
  disabled: true (1)
globalSearchConfiguration:
  defaultCountPerSupplier: 50
  supplierOrder:
    - pages-app
    - stories
    - dam
    - tours
1 Disables the ranking of Global Search results.
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules