Advanced Configuration and Dark Features

Certain advanced aspects of Structure's behavior might not have dedicated configuration pages, being controlled by application properties or system properties instead. Additionally, some features and behaviors are usually hidden from users by default. These dark features can be turned on for an instance by the Jira administrator.

Setting Application Properties

The easiest way to add and manage custom Structure properties and dark features is to use the Structure Dark Features and Fine Tuning interface.

To add a new custom property or dark feature, enter the appropriate Property Key (see below for a list of available keys) and click Add Property.
Once the key is added to your properties list, you can adjust its value by clicking the edit icon (pencil).
To remove a custom property, click the trash icon.
Once you have made all necessary updates, Structure must be restarted to apply the changes.

To access the interface, you must have Jira Administration permissions and enter the interface location directly into your browser: https://YOUR_JIRA_ADDRESS/secure/admin/StructureDarkFeatures.jspa

Guidelines for Editing Properties

When an invalid property value is entered in the table, the default value is applied.
Spaces are not trimmed, and may result in an invalid value.
When you delete a property from the admin table, it's property value is set to the default value:
- If the property was added with our admin interface, the value is set to empty value and the property is removed from the table after a page refresh.
- If you set the value to empty (without deleting the property), the property will not be removed.
Structure must be restarted to apply changes.

Setting System Properties

You can set System properties during Startup or using Script Runner.

Both of the following methods can also be used to set Structure properties; but we recommend using the Structure Dark Features and Fine Tuning interface as described above.

On Startup

You can set System properties using the -D Jira startup option, for example:

-Dstructure.sync.guard.email.admin.cycles=5

Configuring Jira startup options is described in this article. You will need to restart Jira for the properties to take effect.

With Script Runner

You can also set system properties using the Script Runner add-on.

Install Script Runner.
Go to Administration | Add-Ons | Script Runner | Script Console.
Select Groovy as the Script Engine.
Enter the following code into the Script text box, adjust property name and value as needed, and click Run Now.

System.setProperty("structure.sync.guard.email.admin.cycles", "5")

The changes take effect after you restart Structure, but the properties will be reset to their default values when you restart Jira. In some cases, for settings to take effect you have to reinstall Structure.

Available Dark Features

Structure size limit

Property	Default	Explanation
^{com.almworks.jira.structure.AOBasedStructureManager.forestSizeLimit}	¹⁰⁰⁰⁰⁰	The maximum number of rows that one structure can contain.

Structure Automation limits

Property	Default	Explanation
^{structure.gfs.generationTimeHardLimit}	⁶⁰⁰	The maximum amount of time that can be spent for Structure generation (in seconds).

Automation Defaults

Property

Default

Explanation

^{structure.generator.defaults.disableUpdates}

^false

When adding generators:

If set to "false" (default) - the "allow changes" box is initially checked.
If set to "true" - the "allow changes" box is initially unchecked.

Activity Stream update limits

Property	Default	Explanation
^{structure.activitystream.changesLimit}	¹⁰	This parameter limits the number of history "changes" displayed per history "entry."

Hide Structure on the Issue page

Property	Default	Explanation
^{structure.feature.showOnIssuePage}	^true	Show Structure on the issue page. In some cases, switching this off may improve Issue page performance.

Manual adjustments

Property	Default	Explanation
^{structure.gfs.manualAdjustments.enable}	^true	Setting this property to false will disable manual adjustments for the entire Jira Instance. All adjustment-related UI elements and controls will disappear. Existing manual adjustments will be kept in the database, but will not be applied.
`structure.gfs.manualAdjustments.maxAdjustmentsPerStructure`	`2000`	The maximum number of manual adjustments per one structure. When this limit is reached, adding new manual adjustments will be impossible. If you reduce this limit, you may have to remove all manual adjustments for the structures that exceed it.
`structure.gfs.manualAdjustments.maxAdjustmentsPerAction`	`200`	The maximum number of manual adjustments per one user action. If this limit is exceeded, the action will be aborted without making any changes.

Hidden Issue Links

Property	Default	Explanation
^{structure.feature.hiddenLinks.enabled}	^false	Set to true to enable support for hidden issue links.

Index Consistency Checks

Property	Default	Explanation
^{structure.indexConsistencyChecker.disabled}	^false	Set to true to disable periodical checks of Lucene index consistency.

Alternative initial values for project/type when creating an issue in dialog

Normally, when the user creates new issues through dialog, Structure remembers the selected project and issue type and offers those the next time by default. This dark feature enables a different algorithm, which used to work in a previous version of Structure: the initial project and issue type are taken from the issue that was focused when "+Create" was pressed.

System property	`structure.feature.altInitialValuesInDialog`
Options to add in setenv.sh / setenv.bat	`-Dstructure.feature.altInitialValuesInDialog=true`
Internal feature name	`altInitialValuesInDialog`
Introduced in version	2.11.0

Managing Permissions

Property	Default	Explanation
^{structure.permissions.allowAllUserGroups}	^false	By default, users can only manage permissions for groups they are a part of. Setting this property to "true" allows users to manage any group, whether they belong to that group or not.
^{structure.permissions.jiraAdminHasAllPermissions}	^true	By default, Jira admins are granted all Structure global permissions, Control access to all structures, and Manage access to all views. If this property is set to "false," all global permissions and access restrictions apply to Jira admins, just like for regular users.

Resolved icon (green tick)

Property

Default

Explanation

^{structure.doneAttribute.byResolution}

^false

false - the "Resolved icon" shown when the Resolution field of an issue is non-empty

true - the "Resolved icon" is shown when the issue is in a Done status category (StatusCategory.COMPLETE)

Show Archived Timesheets by Tempo Accounts in the Tempo Worklogged column

Property

Default

Explanation

^{structure.tempo.showArchivedAccounts}

^false

false - archived accounts are not shown

true - archived accounts are available in the Tempo Worklogged drop down

Structure Export Timeout

For large, complex structures, it may take a long time to capture all the details of a structure required for exporting. In order to reduce the amount of time and resources required for export, after a set time Structure will attempt to use a cached version of the structure for the export. If this is not possible, it will continue trying to compile live data for a set time before the export fails.

Property	Default	Explanation
^{structure.export.trySnapshotTimeout}	¹²⁰	In seconds, the amount of time Structure will wait before attempting to export a cached version of the structure. Note: when a cached version is exported, a warning is added to the export.
structure.export.forestLockTimeout	⁶⁰⁰	In seconds, the total time allotted before the export fails.

Minimum time is 60 or 90 seconds, and it can take up to 60 seconds longer than the configured timeout, because lock time is measured in 30s increments (by default), and there are 2 or 3 loops where the exporter waits, depending on the attributes and forest spec.

Time in Status - Refresh Period

Property

Default

Explanation

^{structure.timeinstatus.refreshPeriod}

^3600000

Sets update period for Time in Status columns. Value is in milliseconds.

Time is Status is updated any time a status change occurs in Jira or once per hour if status remains unchanged. This option allows you to update the Time in Status more or less often, when issues remain in the same status.

Time Tracking on the Issue Page and Issue Details Page

When viewing an Issue page in Jira or the Issue Details page in Structure, the Time Tracking section provides up-to-date time tracking details, and allows you to include time tracking details for sub-issues within the calculations. If these pages are taking too long to load, disabling this feature may help.

Property	Default	Explanation
^{structure.issuePage.showTimeTracking}	^true	false - disables the Structure Time Tracking section on the Issue page and Issue Details page.

Link-related changes made by Generators or Synchronizers

By default, when a generator (see Generators) or Synchronizer creates, deletes or changes a link, the change appears immediately on an Issue Page, but it is not immediately indexed in Jira. Additionally, the change is not written to history, so it is not possible to review the changes on an issue's History tab.

This setup prevents link changes from negatively impacting system performance (a particular risk when bulk changes are made to issue links); however, there may be times when these types of changes need to be indexed immediately and/or appear in an issue's history. To enable this, simply update the following properties.

Property	Default	Explanation
^{structure.bulkLinkProcessor.useLinkManager}	^false	true - enables the immediate re-indexing after every change, writes changes in the history and creates a Structure-side event for each link update (enabling other apps to see that Structure made the change).
structure.sync.links.force.reindex	^false	true - enables immediate indexing.

Synchronizers

Synchronization lets you keep Structure issue hierarchy in sync with some other issue properties. This dark feature is disabled by default.

Property	Default	Explanation
^{structure.feature.synchronizers.enabled}	^false	Set to true to enable Synchronizers within Structure.

Synchronizer Cycle Guard

The cycle guard is a component that detects conflicting synchronizers and prevents them from cycling forever, overriding each other's changes. The table below describes the system properties that control the cycle guard.

Property	Default	Explanation
^{structure.sync.guard.disable}	^false	Set to `true` to disable the cycle guard. Conflicting synchronizers will not be prevented from running forever. Not recommended.
^{structure.sync.guard.maxAutosyncsWithoutUserChanges}	¹⁰	The maximum number of times that a synchronizer is allowed to run, processing the changes generated by another synchronizer. If this limit is exceeded, the two synchronizers are considered to be in conflict.
^{structure.sync.guard.stop.disable}	^false	If `true`, conflicting synchronizers will not be disabled automatically. The cycling may repeat after a user-generated change.
^{structure.sync.guard.email.owner.disable}	^false	If `true`, the cycle guard will never send e-mail notifications to synchronizer owners.
^{structure.sync.guard.email.admin.disable}	^false	If `true`, the cycle guard will never send e-mail notifications to Jira administrators.
^{structure.sync.guard.email.admin.cycles}	¹⁰	The minimum number of times a cycle must be detected for a synchronizer before an e-mail notification about that synchronizer is sent to Jira administrators. The counter is reset when a synchronizer is automatically disabled, so if this number is greater than 1 and automatic disabling is on, the administrators will not be notified.

Restart Structure

After applying a dark feature, it may be necessary to restart Structure for the change to take effect. To restart Structure:

Go to Administration | Manage apps
On the sidebar, click Manage apps
Locate Structure
Click Disable (when prompted, skip sending feedback)
Click Enable