Mindbreeze InSpire SDK Plugins
Mindbreeze Item Transformation and Post Filter Plugins

Preparation

For building and deploying the examples from this document, the following third-party Software is needed:

• Java SE Development Kit: Version 1.8 or newer
• Eclipse IDE for Java Developers

Installation of the Mindbreeze Software Development Toolkit

If you are using Microsoft Windows: install the Mindbreeze SDK by executing MesSDKSetup.exe .

If you are using Linux or OSX: extract the mes-devel-<version>.zip to a folder of your choice and add the SDK/bin folder from the archive to your Path variable.

Generating a Mindbreeze Plugin Project

The Mindbreeze Software Development Toolkit contains a tool for generating Mindbreeze Plugin Projects: mesjavaplugin.bat for Microsoft Windows installations and mesjavaplugin.sh for Unix-based systems. The tool can be used for generating the following Mindbreeze extension types:

datasource: Crawler, context and authorization plugin for a given data source.

filter: Filter plugin for a given data type.

postfilter: Post filter transformation plugin.

itemtransformer: Item transformation plugin.

Called without parameter the mesjavaplugin tool displays its usage with examples:

The parameter <name> is the name of the plugin. The project will be generated in a folder with the name of this parameter lowercased in the current path.

The parameter <base package> is the java package where the source files will be generated.

Example 1: A Post Filter Transformation Plugin

Please follow these steps to generate and deploy a post filter transformation plugin for editing or adding custom metadata:

1. Create the plugin project: mesjavaplugin.sh postfilter MetadataProcessor com.mycompany

1. Navigate to the metadataprocessor folder in your current path.

1. Import the newly created project into your Eclipse IDE:

1. After successfully importing the project, you will find a stub implementation of the plugin in the file MetadataProcessorPostFilter.java:

Note: The name of the Java file is <name>PostFilter.java whereas <name> is the plugin name parameter from the previous step.

1. Extend the source code according to your needs. For example, the following implementation would add the metadata “meta” with a string value of “value”:

private void processRequest(FilterAndIndexRequest.Builder request) {

    // Clone the request

    Metadata.Builder metadataBuilder = request.getContentBuilder().getMetadataBuilder();

    NamedValue.Builder namedValueBuilder = NamedValue.newBuilder();

    namedValueBuilder.setName("meta");

    namedValueBuilder.addValue(ValueHelper.newBuilder("value"));

    metadataBuilder.addMetadatum(namedValueBuilder)

}

1. Build the plugin archive by executing the script build.bat on Windows Systems or build.sh on Unix in the project directory. If the process was successful, an archive with the name <name>-postfilter.zip should be produced. Again, <name> is the plugin name parameter that was specified previously.

1. The plugin is ready to be installed in the tab “Plugins” in the Management Center:

1. After the successful installation, the plugin can be activated for any filter service:

Example 2: An Item Transformation Plugin

Please follow these steps to generate an item transformer plugin for editing or adding custom metadata:

1. Create the plugin project: mesjavaplugin.sh itemtransformer MetadataProcessor com.mycompany

1. Navigate to the folder metadataprocessor in your current path.

1. Import the newly created project into your Eclipse IDE (As in the previous example).

1. After successfully importing the project, you will find a stub implementation of the plugin in the file MetadataProcessorItemTransformerService.java:

1. Extend the code according to your needs. This example again adds a metadata named “meta” with the value “value”:

    private void processItem(Item.Builder itemBuilder) {

    itemBuilder.addProperty(

    NamedValue.newBuilder()

    .setName("meta")

    .addValue(ValueHelper.newBuilder("value"))

    );

}

1. Build the plugin archive by executing the script build.bat on Windows Systems or build.sh on Unix in the project directory. If the process was successful, an archive with the name <name>-postfilter.zip should have been produced. Again, <name> is the plugin name parameter that was previously specified.

1. The plugin is ready to be installed in the tab “Plugins” in the Management Center:

1. After the successful installation, the plugin is available for all Index Services.

Plugin Configuration

As you could see in both examples, it is possible to define properties for the installed plugins from the configuration interface by adding custom plugin properties.

These configuration properties are accessible in the plugin source code from the properties map:

Map<String, List<String>> properties = null;

The init method that is retrieving the configuration properties is called automatically if the plugin implements the com.mindbreeze.enterprisesearch.mesapi.Initializable interface.

The previous example of an Item Transformer plugin now setting a metadata value to a configuration parameter named “meta” looks like:

    private void processItem(Item.Builder itemBuilder) {

    if (properties != null && properties.containsKey("meta")) {

    List<String> values = properties.get("meta");

    if (values != null && !values.isEmpty()) {

    String value = values.get(0);

    if (value != null) {

    itemBuilder.addProperty(

            NamedValue.newBuilder()

            .setName("meta")

            .addValue(ValueHelper.newBuilder(value))

            );

    }

    }

    }

    }

Plugin Descriptor Configuration Section

The Plugin Descriptor plugins.xml describes the plugins available in the archive. The main outline is as follows:

version

plugins

Plugin

id

kind

extension

code

if kind is CODE

properties  

for predefined properties that are passed to the Plugin

config_options

• The element config_options itself is a language for describing configuration user interface elements and therefore allows the plugin developer to extend the Mindbreeze InSpire configuration interface. As an example, the following configuration extends the configuration user interface with the “meta” property.  As of this writing the configuration interface supports English translations only. Supported input types are TEXT, NUMBER, BOOLEAN, TEXTAREA, SELECT, PASSWORD, CREDENTIAL. Default values can be added via default_string or default_numeric. Select options can be defined using the select_option element.

      <config_option>

        <Group>

          <label>

            <LangString>

              <lang>en</lang>

              <value>Base Configuration</value>

            </LangString>

          </label>

          <level>DEFAULT_LEVEL</level>

          <option>

            <Option>

              <name>meta</name>

              <input>TEXT</input>

              <hint>The value that is added as the meta property.</hint>

              <label>

                <LangString>

                  <lang>en</lang>

                  <value>meta property value</value>

                </LangString>

              </label>

              <option />

            </Option>            

          </option>

        </Group>

      </config_option>