Configuring Dataplane

This section describes the options available to under Dataplane Reports » Administration » Configuration.

Dataplane Indexing

Building the History Index

Before you can run any Arsenale Dataplane reports, you must build Dataplane's history index.

This is typically a one-time operation. Once the history index is built, Arsenale Dataplane updates the index in real-time to ensure that reports are always using the most up-to-date data.

Rebuilding the index can take a long time—up to a few hours on large systems, and sometimes even longer on enterprise-scale systems (particularly when using Microsoft SQL Server). While all indexing is done in the background and should not affect regular Jira use, users will be unable to run Dataplane reports while the index is being built.

To build the history index, from the Dataplane Administration page select the Configuration tab and click the Build Index button.

While the Arsenale Dataplane index is being built, you can view the progress on this same Configuration page.

The index build is done as a background process. While the index is being built, you do not need to remain on the Dataplane Administration page, or on the Configuration tab within that page. You are free to browse anywhere else in Jira, and may return to the Dataplane Administration page at any point to see the latest index build progress.

Once the Dataplane index build is complete, you will see the updated indexer status on this page:

Indexing on Jira Data Center

When building the Dataplane index for the first time, or when incorporating incremental changes to the index, Dataplane runs a background task to perform the indexing operations. In a Jira Data Center installation, these indexing tasks are performed on only one cluster node at a time.

The node on which you click the "Build Index" button in the UI may not necessarily be the node that performs the underlying indexing work.

If you have any questions about how to determine which node is performing the indexing, please contact Arsenale Support.

On startup in a Jira Data Center instance, Dataplane will automatically select one "master" Jira node to perform the indexing tasks. As cluster nodes are brought up and down, so long as Dataplane is not in the middle of an indexing operation, these indexing tasks are automatically handed off to another live node in the cluster as needed.

For performance reasons, the initial Dataplane index build process cannot be handed off to another node.

If you are building the Dataplane index for the very first time, or you are performing an upgrade that necessitates a Dataplane reindex, you must ensure that the node performing the indexing operation remains up for the duration of the indexing process.

If the node goes down in the middle of indexing, you must manually restart the indexing process.

Synchronizing the History Index

Once the history index has been built, the Sync Index button allows you to request a manual synchronization of the Dataplane index.

Performing a manual synchronization of the Dataplane index is not required under normal operation, since Dataplane tracks all issue changes automatically.

When you click the Sync Index button, Dataplane will perform the following actions:

Refresh the list of Jira custom fields to determine if any newly-added fields should be made available for use in the Dataplane UI, and
Find any previously-existing issues in Jira that do not already exist in the Dataplane index.

If you have added a new custom field to Jira (or renamed an existing one) since Dataplane was installed or enabled, clicking Sync Index will ensure that the custom field is made available to users.

Under normal circumstances, all issues that are created and updated in Jira are automatically included in the Dataplane index in real time. However, if an issue is created without generating an issue event (such as by some versions of the Jira Issue Importer, or by a Groovy-based script that does not generate events), the issue may not be added to the index, and performing a manual Sync Index after the issue import may be required in order to see the issue in reports.

Similarly, if you disable or uninstall Dataplane, create some issues, and then re-enable Dataplane, those issues may not be visible in some historical reports until you click Sync Index.

When creating a new ScriptRunner-based custom field, you will need to click the Sync Index in Dataplane the very first after creating the custom field in Jira, which will allow the field to be displayed in the Dataplane UI. Dataplane does not require any further Sync Index operations for ScriptRunner fields (not even if you change the underlying script). However, since ScriptRunner fields are cached in Jira's Lucene index, you will need to reindex Jira itself if you make a change to the field's script that modifies the value it calculates for an issue.

Automatically Rebuilding the History Index

Each night at midnight (00:00) server time, Dataplane runs a history index maintenance task. Among other functions, this task performs validity checks on the index data and optimizes index data storage.

If the nightly index maintenance task detects a critical, unrecoverable data error in the history index, Dataplane's history index is marked invalid and a full rebuild of the index is required. Until a Dataplane administrator initiates a rebuild of the history index, Dataplane will display an error message to all Dataplane users and administrators indicating that report results may be invalid until the history index is rebuilt.

The early morning timing of this index invalidation can mean many hours go by before the issue is discovered and a Dataplane administrator is able to kick off a full rebuild of the Dataplane history index.

To limit downtime in this situation, set the following JVM property in your Jira bin/setenv.sh file to have Dataplane automatically begin rebuilding its history index should it encounter any critical, unrecoverable index data errors:

-Dcom.arsenalesystems.dataplane.indexer.autoRebuild=true

This JVM property setting is rarely needed, as unrecoverable Dataplane index data errors are not common. We recommend enabling this property only if you are regularly experiencing Dataplane index invalidation, and only as a temporary workaround while you engage Arsenale Support to determine the root cause of the problem.

Removing the History Index

If you need to uninstall Arsenale Dataplane permanently, you can use the Remove Index button on the same Configuration tab to remove all existing Dataplane index data from your Jira database. This will drop all of the tables that Dataplane created to build an index.

Depending on your database, dropping the tables may or may not release the recovered space back to the filesystem.

Configuring Permissions

Configuring Dataplane Access Permission

Permission to use Arsenale Dataplane is granted under Dataplane Access Permission on the Configuration tab of the Arsenale Dataplane » Administration page.

By default, all users in the jira-administrators and jira-users groups are given access to Dataplane. The Dataplane Reports Jira menu item will be visible to groups in this permissions list.

In general, users who are not in any group in the permissions list will not see any Dataplane menus or be able to run reports directly through Dataplane. However, if an existing Dataplane user creates a report, shares it, and adds the resulting shared report to a Jira dashboard that is visible to other users, everyone who is able to see the dashboard will also be able to view the Dataplane report, even if those individuals do not otherwise have Dataplane privileges. This allows administrators to restrict report creation to a select group of users, but still to display read-only Dataplane reports to other users on dashboards and information radiators.

To give groups permission to use Dataplane, type in the group names and click Add Groups.

To remove groups of users from the permissions list, select those groups and click on Remove Selected Groups.

The permissions list does not grant add-on administration privileges.

The Dataplane administration page is only accessible to users with Jira Administration privileges.

Configuring Customizer Script Permission

Dataplane users can modify or extend the functionality of reports with sandboxed, Groovy-based Customizer Scripts.

By default, all users in the jira-users and jira-administrators groups are granted permission to use Customizer Scripts. If you wish to prevent some or all of these users from using Customizer Scripts, you may customize the list of groups under the Customizer Script Permission section on the Configuration tab of Dataplane Reports » Administration.

Dataplane also handles saved reports that use Customizer Script: in order to run the report, either the user who created the report or the user who is currently accessing the report must have Customizer Script permission. This means that a small set of users may be given Customizer Script permission, who can then create a set of reports that can be shared with a larger set of users who do not have Customizer Script permission.

Note that Customizer Script permission is checked in real time. For example, if a trusted user is given Customizer Script permission and then saves a report with a script, any other user in the system (even those without Customizer Script permission) will be able to run the report. However, if Customizer Script permission is later withdrawn from the user who saved the report, only those other users who have Customizer Script permission will be able to run the report (even if the saved report itself has not been changed).

Configuring Default Report Sharing

When saving a report, Dataplane allows users to make the resulting report available to other users, other groups, or everyone (including anonymous users, if your Jira permits anonymous access).

This section allows the administrator to define the default sharing options for newly-saved reports. When users create new reports from a report template, the report will inherit the default sharing options specified in this section. Unless the administrator has made a selection in this section, the default for newly-created reports is "Not shared".

The selections made here apply only to newly-created reports that are being saved for the first time with Save As. The sharing selections of any existing saved reports will not be modified. In addition, existing reports that are copied using the Save As feature will still inherit the sharing options of the original report, rather than the default options specified here.

For a description of the Not shared option, the Everyone option and the projects/groups control, please see the documentation for Saving Reports.

Page Contents