Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Setup

To install the OvElasticLink plugin, go to JIRA administration, then go to the Manage Add-ons section. On the add-ons administration page, click the Upload add-on button, as shown in the screenshot below.

 

 

 

 

 

 

 

 

 

Once the plugin is installed, a new menu appears on the administration left-hand menu (you may have to reload the page to see the menu appear).

Administration

The OvElasticLink administration is separated in three sections :

  • ElasticSearch cluster
    • In this administration section, you must give the plugin information about your running ElasticSearch cluster. This will allow the plugin to connect to the cluster and execute administrative and indexing tasks.
  • Contexts
    • This section allows you to define some indexing contexts, to select which issues from which projects will be indexed in the ElasticSearch cluster.
  • Mappings
    • This section allows you to define which issue fields must be indexed in the ElasticSearch index.

ElasticSearch cluster administration

There are very few settings to configure in this section, as the plugin is smart enough to discover most of the useful settings it needs to know, once you provided minimal information. Basically, the only information you need to provide are :

  • the ElasticSearch cluster name
  • the IP and port of one of the cluster nodes.

The screenshot below shows the default cluster administration page.

A few things to notice here :

  • the cluster status cannot be retrieved, because the ElasticSearch cluster has not been configured yet;
  • the cluster name is set to its default value, elasticsearch (more on this below);
  • no nodes are shown.

Cluster name

The cluster name is mandatory. By default, the plugin will suppose the cluster is named elasticsearch, as it is the default cluster name of an ElasticSearch node. If your cluster name is different, enter its name in the Cluster name field, as shown below, and click the Update button.

This step is the first one to accomplish before adding node, because nodes configured while the cluster name is wrong will be shown as down, because they are not part of the configured cluster.

Cluster nodes

The next step is to give the plugin the IP and port of one of the nodes of the ElasticSearch cluster. To do this, click the Add Node button under the cluster nodes table. This will bring up a pop-up window where you are asked to enter an IP address and a port. Both are mandatory. When you entered these information, please click the Save button.

Cluster and nodes discovery

In the example screenshot above, a single node IP/port is entered. But in the screenshot below, you can see that two nodes are listed in the cluster nodes table. This is because OvElasticLink makes use of an ElasticSearch client feature called network sniffing, which allows a client to discover all nodes in a cluster with only the address of one of the nodes. So even if your cluster is made of a lot of nodes, you will a-only have to enter the IP and port of only of them in the plugin administration (provided this node is up !).

This screen has completely changed by entering only two information : 

  • the cluster name
  • the IP and port of one node.

OvElasticLink has discovered the rest, as you can see in the screenshot above. The discovered information are :

  • In the cluster status
    • the number of nodes in the cluster (here 2)
    • the cluster status (here GREEN)
    • that the OvElasticLink index does not exist (there is a Create link under the ElasticLink Index column). See paragraph ElasticLink Index below for more information on this.
  • In the nodes table :
    • the second node, appearing in the nodes table, with the IP 192.168.1.13 and port 9301
    • the nodes names (here Node 1 and Node 2)
    • the nodes statuses (here both are UP)

ElasticLink Index

To index JIRA issues in ElasticSearch, OvElasticLink needs to have a dedicated index in the ElasticSearch cluster (as many indices can co-exist in a cluster, used by many different applications). If this dedicated index does not exist in the configured cluster, a Create link will appear in the Cluster status section of the ElasticSearch cluster administration page.

To create this index, just click this link, and OvElasticLink will create the index immediately.

ElasticLink Index name

The name of the index created by OvElasticLink is based on the home url of the JIRA instance the plugin is deployed into. Basically, the plugin takes the home url, and removes all / characters and http(s) prefix. For example, for a JIRA instance with a home url set to : http://localhost:2990/jira/, the index name will be localhost:2990jira. See the result of the created index on the screenshot below :

If you are using some ElasticSearch monitoring applications or plugin, you can check the index in your cluster, as shown below :

Now that the index is created, you are done with the ElasticSearch cluster administration.

 

Contexts administration

OvElasticLink plugin uses the notion of contexts to decide wether an issue must be indexed or not. A context, apart from its name, is defined by two elements :

  • a list of projects;
  • a list of issue types.

The combination of these two elements will allow the plugin to know, when an issue is created or updated, if it must be indexed in ElasticSearch or not.

To configure one or more contexts, go to the Contexts administration page. When no context is defined, this page will look like this :

To add a context, click the Add context button under the configured contexts table. This will bring up a pop-up window where you'll be able to configure the context.

In this window, only the title is mandatory. If you don't enter any project or issue type, then this context will apply to all projects and all issue types. It is important to know a few things about a context configuration :

  • a context title must be unique. If you enter a context title that already exists, an error will be shown and the context will not be saved;
  • A context perimeter must be unique. This means that an issue cannot be associated with two contexts. For example, if you configure a context Context1 for All projects and the Bug issue type, you cannot configure another context Context2 for project DEMO and the Bug and Task issue types. Because if you do so, an issue in the DEMO project of type Bug will match Context2 context, of course, but it would also match Context1 (All projects and issue type Bug). When you know more about mappings (explained later in this document), you will understand why this is not possible. Anyway, if you configure a context that would conflict with an existing one, an error will be shown and your context will not be saved.

Below is an example context configuration :

Issue types and projects inputs help you in your selection. Start typing, and a drop down menu containing projects or issue types matching the entered text will appear, as shown below. Just select one of them, or continue typing to refine the proposed choices.

When your context is created, it appears in the list of configured contexts, as shown in the screenshot below :

Of course you can still modify a context, or delete it, by using the Edit or Delete links in front of the context you want to modify or delete. Please note that in some cases, you won't be able to delete a context. This will happen if the context you want to delete is associated with a mapping. More on this below.

Mappings administration

The last administration section to configure is the Mapping section. A mapping defines how issues will be indexed in ElasticSearch. To be more specific, it allows you to choose which fields from issues matching a context (this will be explained later) will be used for ElasticSearch indexation. If a field is indexed, it is searchable in ElasticSearch. If it is not, you won't be able to search issues based on values from this field.

The default mapping administration screen looks like this :

 

An information note is visible here to inform you that as long as no mapping is provided for the context(s) you defined, no indexation in ElasticSearch will be performed.

To add a new mapping, click the Add mapping button under the configured mappings. This will bring up a pop-up window where you can configure your mapping, as shown below :

 

As for contexts, the mapping title is mandatory, and must be unique. And as for contexts, mapping perimeter must be unique. This means you cannot configure two mapping associated with a common context.

Like in the context configuration window, the contexts selection here offers assistance. Start typing, and existing contexts will appear. Select one of them or continue typing to refine the proposed matching contexts. See it below in action :

 

As an example, here is a mapping definition, matching the context example created earlier in this document :

Once you hit the Save button, and provided no conflict is detected, your mapping will appear in the table of configured contexts, as shown in the screenshot below :

 

As you can see in the screenshot above, the created mapping is displayed, and a NO status label is shown to inform you that your mapping is neither configured or synchronized. Let's explain what are Configuration and Synchronization.

Mapping configuration

We quickly mentioned earlier in this document that a mapping allows you to choose which fields of an issue will be indexed in ElasticSearch. The mapping configuration is the place where you configure this.

To begin configuring your mapping (or to change its configuration), click the Configure link in front of the mapping you want to configure. This opens a configuration panel under the mappings table, as shown below :

 

You may be wondering where this fields come from, and why they appear here, and others do not. OvElasticLink uses the context(s) you associated with your mapping to discover the maximum common field between all projects and issue types configured in associated contexts. If a field is available in an issue type of a project configured in the context associated with your mapping, it will be listed here. If a field is available in the Task issue type of the project configured in your context but you only configured your context to index Bug issue types, then this field will not appear here. If you configured more than one context, and a field is available in one of your contexts but not in another one, it will not appear here. As stated before, the fields listed in the mapping configuration panel are all the common available fields of all the associated contexts. The reason for that is to make sure all indexed issues have value for all indexed fields (provided you gave a value to this field in the JIRA issue).

Another important point to note. The Key field does not appear in the list, because (as explained in the configuration panel) the issue key is always indexed. And by the way, the ElasticSearch document id for the indexed issue is the issue key. This allows you to search by issue key or to get an issue by its key (document id in ElasticSearch).

Here is an example mapping configuration :

Once you configured and saved your configuration, the mapping appears as configured in the mappings table, as shown below :

 

Mapping synchronization

Once a mapping is configured, you have to give this configuration to ElasticSearch, so it knows how to index the issue the plugin will send for indexation. This process is called synchronization. When you hit the Synchronize link of a mapping, OvElasticLink will convert your configuration to an ElasticSearch mapping and create (or update) a type in the ElasticSearch index. The name of the ElasticSearch type corresponding to your mapping is based on the mapping name : OvElasticLink will convert the mapping title to lower case, and replace all spaces with underscores. As an example, for the mapping created in the screenshot above (Demo Issues), the ElasticSearch type will be named demo_issues.

If the synchronization is successful, an information message will be shown, as shown below :

 

And the mapping in the mappings table will be displayed as synchronized, as you can see in the screenshot below :

 

Please note that as soon as you change the mapping configuration, the mapping will change to not synchronized. As long as you don't synchronize the modified configuration with ElasticSearch, issues indexation will not change (for example, if you added a field, it will not appear in ElasticSearch until you synchronize your configuration and reindex the issue).

 

Issue indexation

Issue indexation is triggered :

  • when editing or creating an issue, adding or editing a comment provided the issue matches one of the configured contexts;
  • when manually launching the bulk indexation process, which will index (or reindex) all existing issues.
  • No labels