com.almworks.jira.structure.api.settings

Interface StructureConfiguration

public interface StructureConfiguration

StructureConfiguration provides access to the configuration parameters of the Structure plugin.

Typically, only JIRA administrators have write access to the plugin configuration, so before changing anything you should check if the user has enough privileges - no checking is done by this component.

This service also provides some utility methods that are based on the Structure configuration.

All methods in this component are thread-safe.

Method Summary

Modifier and Type	Method and Description
com.atlassian.jira.jql.builder.JqlClauseBuilder	addConfigurationScopeClause(com.atlassian.jira.jql.builder.JqlClauseBuilder builder) Adds to the JQL builder a condition that limits the result set to the projects enabled for Structure.
void	clearUISettings(com.atlassian.jira.user.ApplicationUser user, com.atlassian.jira.project.Project project) Completely removes per-user or per-project settings.
List<PermissionSubject>	getAutomationPermissionSubjects() Used to get the list of groups (possibly other permission subjects) that are allowed to configure and control automation of controlled structures.
com.atlassian.query.Query	getConfigurationScopeQuery() Utility method that returns a JQL query that selects all issues in the projects that are available for Structure.
List<PermissionSubject>	getCreatorPermissionSubjects() Used to get the list of groups (possibly other permission subjects) that are allowed to create new structures.
List<com.atlassian.jira.project.Project>	getCurrentlyEnabledProjects()
long	getDefaultStructureId(com.atlassian.jira.project.Project project) Returns the ID of the default structure for a given project.
List<PermissionSubject>	getEnabledPermissionSubjects() Used to get the list of groups (possibly other permission subjects) that the plugin is enabled for.
com.almworks.integers.LongList	getPickedProjectIds() This method returns a list of IDs of projects picked by the administrator for the Structure plugin.
List<com.atlassian.jira.project.Project>	getPickedProjects() This method returns a list of projects picked by the administrator for the Structure plugin.
List<PermissionSubject>	getSynchronizationPermissionSubjects() Used to get the list of groups (possibly other permission subjects) that are allowed to configure and control synchronizers of controlled structures.
UISettings	getUISettings(com.atlassian.jira.user.ApplicationUser user, com.atlassian.jira.project.Project project) Retrieves user interface settings for the specified user and project.
boolean	isAutomationAccessAllowed(com.atlassian.jira.user.ApplicationUser user) Checks if the user is allowed to configure and use automation.
boolean	isAutomationEnabledForAnyone()
boolean	isCreateEnabledForAnyone()
boolean	isDefaultStructureSetForProject(com.atlassian.jira.project.Project project) Used to check whether a specific project has system-level default structure overridden with project-level default structure.
boolean	isEnabledForAllProjects()
boolean	isEnabledForAnyone()
boolean	isProjectEnabled(com.atlassian.jira.project.Project project) Checks if a given project is enabled for Structure
boolean	isStructureAvailable(com.atlassian.jira.user.ApplicationUser user) Checks if Structure plugin is available for the specified user.
boolean	isStructureCreationAllowed(com.atlassian.jira.user.ApplicationUser user) Checks if the user is allowed to create new structures.
boolean	isSynchronizationAllowed(com.atlassian.jira.user.ApplicationUser user) Checks if the user is allowed to configure and control synchronizers.
boolean	isSynchronizationEnabledForAnyone()
void	setAutomationEnabledForAnyone(boolean enabled) Changes whether the automation is available for all users.
void	setAutomationPermissionSubjectsEncoded(String subjects) Changes the list of the users / groups that are allowed to configure and control automation in controlled structures.
void	setCreateEnabledForAnyone(boolean enabled) Changes whether the creation of new structures is available for all users.
void	setCreatorPermissionSubjectsEncoded(String subjects) Changes the list of the users / groups that are allowed to create new structures.
void	setDefaultStructureId(com.atlassian.jira.project.Project project, Long structureId) Changes the ID of the default structure for the specified project.
void	setEnabledForAllProjects(boolean enabled) Changes whether the plugin is enabled for all projects.
void	setEnabledForAnyone(boolean enabled) Changes whether the plugin is available for all users.
void	setEnabledPermissionSubjectsEncoded(String subjects) Changes the list of the users / groups that the Structure plugin is enabled for.
void	setPickedProjectIds(String idList) Changes projects that Structure plugin is enabled for.
void	setSynchronizationEnabledForAnyone(boolean enabled) Changes whether the synchronization is available for all users.
void	setSynchronizationPermissionSubjectsEncoded(String subjects) Changes the list of the users / groups that are allowed to configure and control synchronizers in controlled structures.
void	setUISettings(com.atlassian.jira.user.ApplicationUser user, com.atlassian.jira.project.Project project, UISettings settings) This method is used to update the user interface settings - either system-wide default settings or per-user settings or per-project settings.

Method Detail

isEnabledForAllProjects

boolean isEnabledForAllProjects()

Returns:

true if Structure plugin is enabled for all projects

See Also:

Selecting Structure-Enabled Projects

getPickedProjectIds

@NotNull
com.almworks.integers.LongList getPickedProjectIds()

This method returns a list of IDs of projects picked by the administrator for the Structure plugin. It returns a list of IDs of picked projects even if "enable for all projects" is turned on - so for the purposes of checking whether Structure is available for a project, you need to use getCurrentlyEnabledProjects().

Returns:

a list of IDs of projects picked by JIRA administrator on the configuration page

Since:

8.2.0 (Structure 2.5)

See Also:

Selecting Structure-Enabled Projects

getPickedProjects

@NotNull
List<com.atlassian.jira.project.Project> getPickedProjects()

This method returns a list of projects picked by the administrator for the Structure plugin. It returns a list of picked projects even if "enable for all projects" is turned on - so for the purposes of checking whether Structure is available for a project, you need to use getCurrentlyEnabledProjects().

Returns:

a list of projects picked by JIRA administrator on the configuration page

See Also:

Selecting Structure-Enabled Projects

getCurrentlyEnabledProjects

@NotNull
List<com.atlassian.jira.project.Project> getCurrentlyEnabledProjects()

Returns:

a list of projects that are allowed to use Structure (if Structure is enabled for all projects, returns all projects)

See Also:

Selecting Structure-Enabled Projects

isProjectEnabled

boolean isProjectEnabled(@Nullable
                         com.atlassian.jira.project.Project project)

Checks if a given project is enabled for Structure

Parameters:

project - project to check

Returns:

true if the project is not null and available for Structure

See Also:

getCurrentlyEnabledProjects()

isEnabledForAnyone

boolean isEnabledForAnyone()

Returns:

true if Structure plugin is enabled for all users (that have access to the enabled projects)

See Also:

Restricting User Access to Structure

getEnabledPermissionSubjects

@NotNull
List<PermissionSubject> getEnabledPermissionSubjects()

Used to get the list of groups (possibly other permission subjects) that the plugin is enabled for. Note that if the plugin is enabled for all users, this method would still return the groups that an administrator has previously picked, but those groups are not used to check the permissions.

Returns:

a list of subjects that the Structure plugin is enabled for (when not enabled for anyone)

See Also:

PermissionSubject.JiraGroup, Restricting User Access to Structure

isCreateEnabledForAnyone

boolean isCreateEnabledForAnyone()

Returns:

true if creating new structures is enabled for all users (that have access to Structure plugin at all)

See Also:

Changing Permission to Create New Structures

getCreatorPermissionSubjects

@NotNull
List<PermissionSubject> getCreatorPermissionSubjects()

Used to get the list of groups (possibly other permission subjects) that are allowed to create new structures. Note that if structure creation is enabled for all users, this method would still return the groups that an administrator has previously picked, but those groups are not used to check the permissions.

Returns:

a list of subjects that are allowed to create new structures (when not enabled for anyone)

See Also:

PermissionSubject.JiraGroup, Changing Permission to Create New Structures

isSynchronizationEnabledForAnyone

boolean isSynchronizationEnabledForAnyone()

Returns:

true if synchronization is available for all users who have control access to the structure

Since:

8.5.0 (Structure 2.8)

getSynchronizationPermissionSubjects

@NotNull
List<PermissionSubject> getSynchronizationPermissionSubjects()

Used to get the list of groups (possibly other permission subjects) that are allowed to configure and control synchronizers of controlled structures.

Returns:

a list of subjects that are allowed to configure and control synchronizers (when not enabled for anyone)

Since:

8.5.0 (Structure 2.8)

isAutomationEnabledForAnyone

boolean isAutomationEnabledForAnyone()

Returns:

true if automation is available for all users who have control access to the structure

Since:

10.0.0 (Structure 3.0)

getAutomationPermissionSubjects

@NotNull
List<PermissionSubject> getAutomationPermissionSubjects()

Used to get the list of groups (possibly other permission subjects) that are allowed to configure and control automation of controlled structures.

Returns:

a list of subjects that are allowed to configure and control automation (when not enabled for anyone)

Since:

10.0.0 (Structure 3.0)

setEnabledForAllProjects

void setEnabledForAllProjects(boolean enabled)

Changes whether the plugin is enabled for all projects.

Parameters:

enabled - if true, Structure plugin will be enabled for all projects

See Also:

Selecting Structure-Enabled Projects

setPickedProjectIds

void setPickedProjectIds(@Nullable
                         String idList)

Changes projects that Structure plugin is enabled for. The setting is effective only if isEnabledForAllProjects() returns false.

Parameters:

idList - a comma-delimited list of project IDs

See Also:

Selecting Structure-Enabled Projects

setEnabledForAnyone

void setEnabledForAnyone(boolean enabled)

Changes whether the plugin is available for all users.

Parameters:

enabled - if true, Structure plugin will be available to all users that have access to at least one structure-enabled project.

See Also:

Restricting User Access to Structure

setEnabledPermissionSubjectsEncoded

void setEnabledPermissionSubjectsEncoded(@Nullable
                                         String subjects)

Changes the list of the users / groups that the Structure plugin is enabled for. When Structure is configured to be enabled for anyone, this method has no effect.

Parameters:

subjects - comma-delimited list of string-encoded permission subjects

See Also:

PermissionSubject.toEncodedString(), Restricting User Access to Structure

setCreateEnabledForAnyone

void setCreateEnabledForAnyone(boolean enabled)

Changes whether the creation of new structures is available for all users.

Parameters:

enabled - if true, anyone who has access to Structure can create new structures.

See Also:

Changing Permission to Create New Structures

setCreatorPermissionSubjectsEncoded

void setCreatorPermissionSubjectsEncoded(@Nullable
                                         String subjects)

Changes the list of the users / groups that are allowed to create new structures. When Structure is configured to allow anyone to create new structures, this setting has no effect.

Parameters:

subjects - comma-delimited list of string-encoded permission subjects

See Also:

PermissionSubject.toEncodedString(), Changing Permission to Create New Structures

setSynchronizationEnabledForAnyone

void setSynchronizationEnabledForAnyone(boolean enabled)

Changes whether the synchronization is available for all users.

Parameters:

enabled - if true, anyone who has control access to the structure can configure and control synchronizers.

Since:

8.5.0 (Structure 2.8)

setSynchronizationPermissionSubjectsEncoded

void setSynchronizationPermissionSubjectsEncoded(@Nullable
                                                 String subjects)

Changes the list of the users / groups that are allowed to configure and control synchronizers in controlled structures.

Parameters:

subjects - comma-delimited list of string-encoded permission subjects

Since:

8.5.0 (Structure 2.8)

setAutomationEnabledForAnyone

void setAutomationEnabledForAnyone(boolean enabled)

Changes whether the automation is available for all users.

Parameters:

enabled - if true, anyone who has control access to the structure can configure and control automation.

Since:

10.0.0 (Structure 3.0)

setAutomationPermissionSubjectsEncoded

void setAutomationPermissionSubjectsEncoded(@Nullable
                                            String subjects)

Changes the list of the users / groups that are allowed to configure and control automation in controlled structures.

Parameters:

subjects - comma-delimited list of string-encoded permission subjects

Since:

10.0.0 (Structure 3.0)

addConfigurationScopeClause

@NotNull
com.atlassian.jira.jql.builder.JqlClauseBuilder addConfigurationScopeClause(@Nullable
                                                                                     com.atlassian.jira.jql.builder.JqlClauseBuilder builder)

Adds to the JQL builder a condition that limits the result set to the projects enabled for Structure.

This method adds JQL constraint project IN (....) in case Structure is allowed only for specific projects and does nothing if Structure is allowed for all projects. The condition is added at the current level in the clause builder.

Parameters:

builder - a clause builder to be modified; if null, a new clause builder is created

Returns:

the builder that was passed as the parameter or the newly created builder

getConfigurationScopeQuery

@Nullable
com.atlassian.query.Query getConfigurationScopeQuery()

Utility method that returns a JQL query that selects all issues in the projects that are available for Structure. This is a convenience method that uses addConfigurationScopeClause(com.atlassian.jira.jql.builder.JqlClauseBuilder).

Returns:

a query that selects issues enabled for Structure, or null if all issues are enabled

isStructureAvailable

boolean isStructureAvailable(@Nullable
                             com.atlassian.jira.user.ApplicationUser user)

Checks if Structure plugin is available for the specified user.

Parameters:

user - the user, null means anonymous

Returns:

true if the user can use Structure

See Also:

Who Has Access to the Structure

isStructureCreationAllowed

boolean isStructureCreationAllowed(@Nullable
                                   com.atlassian.jira.user.ApplicationUser user)

Checks if the user is allowed to create new structures.

Parameters:

user - the user, null means anonymous

Returns:

true if the user can create new structures

See Also:

Who Has Access to the Structure

isSynchronizationAllowed

boolean isSynchronizationAllowed(@Nullable
                                 com.atlassian.jira.user.ApplicationUser user)

Checks if the user is allowed to configure and control synchronizers.

Parameters:

user - the user, null means anonymous

Returns:

true if the user can configure and control synchronizers

Since:

8.5.0 (Structure 2.8)

isAutomationAccessAllowed

boolean isAutomationAccessAllowed(@Nullable
                                  com.atlassian.jira.user.ApplicationUser user)

Checks if the user is allowed to configure and use automation.

Parameters:

user - the user, null means anonymous

Returns:

true if the user can configure and control automation

Since:

10.0.0 (Structure 3.0)

getDefaultStructureId

long getDefaultStructureId(@Nullable
                           com.atlassian.jira.project.Project project)

Returns the ID of the default structure for a given project. If project is null, return system-wide default structure.

Returns 0 if there's no default structure available.

Structure plugin stores a system default structure. It also allows project administrator to change default structure for a project.

Structure user interface can be configured to switch to the project default structure when that project or issue from that project is opened.

Important: It is not guaranteed that the structure with this given ID exists! The preference is stored independently from the structures.

Parameters:

project - the project for which default structure is requested; null to get a system-wide default structure

Returns:

the ID of the default structure for the specified project, or 0

See Also:

StructureManager.getStructure(Long, PermissionLevel), setDefaultStructureId(com.atlassian.jira.project.Project, Long)

setDefaultStructureId

void setDefaultStructureId(@Nullable
                           com.atlassian.jira.project.Project project,
                           @Nullable
                           Long structureId)

Changes the ID of the default structure for the specified project. If project is null, updates system-wide default structure.

See getDefaultStructureId(com.atlassian.jira.project.Project) for more details about default structures.

Parameters:

project - the project for which to set the default structure, null to set system-wide default

structureId - the ID of the default structure, null to clear the value (project-level default structure will use system-level default structure, and system-level default structure ID will be reset to 0 - no structure)

See Also:

getDefaultStructureId(com.atlassian.jira.project.Project)

isDefaultStructureSetForProject

boolean isDefaultStructureSetForProject(@NotNull
                                        com.atlassian.jira.project.Project project)

Used to check whether a specific project has system-level default structure overridden with project-level default structure.

Parameters:

project - project to check

Returns:

true if a project-level default structure has been specified

See Also:

setDefaultStructureId(com.atlassian.jira.project.Project, Long)

getUISettings

@NotNull
UISettings getUISettings(@Nullable
                                  com.atlassian.jira.user.ApplicationUser user,
                                  @Nullable
                                  com.atlassian.jira.project.Project project)

Retrieves user interface settings for the specified user and project.

UI settings are typically defined at a system level by JIRA administrator and can be overridden by each user and for each project. This method calculates the final UI settings given which user is viewing Structure widget and the project context (such as viewing an issue or a project tab).

The following is the order in which settings are applied:

1. Per-user per-project value, if set
2. Per-user value, if set
3. Per-project value, if set
4. System default value

Parameters:

user - the user to retrieve UI settings for, or null for anonymous user

project - the project to retrieve UI settings for, or null for non-project-specific settings

Returns:

an instance of UISettings that details how Structure Widget should work

setUISettings

void setUISettings(@Nullable
                   com.atlassian.jira.user.ApplicationUser user,
                   @Nullable
                   com.atlassian.jira.project.Project project,
                   @NotNull
                   UISettings settings)

This method is used to update the user interface settings - either system-wide default settings or per-user settings or per-project settings. See getUISettings(ApplicationUser, Project) for details.

Per-project UI settings are not yet supported. Using project argument currently has no effect - it would work as if project was null. The argument is added for the sake of forward compatibility as we expect to support it soon.

Use UISettingsBean to specify the settings you want to change. If a certain setting has null value, it is treated as "not set" and the value is inherited from generic settings.

To unset a specific setting and make it inherit a default value, use clearUISettings(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.project.Project) to clear all settings and then this method to restore all overridden settings you'd like to keep.

Parameters:

user - the user to apply the settings for, or null to apply globally

project - (currently not used) the project to apply settings for, or null to apply across all projects

settings - an instance of settings

clearUISettings

void clearUISettings(@Nullable
                     com.atlassian.jira.user.ApplicationUser user,
                     @Nullable
                     com.atlassian.jira.project.Project project)

Completely removes per-user or per-project settings. Next time settings are retrieved, default/inherited settings will take effect.

Either user or project settings must be specified. This method has no effect on the system defaults.

Parameters:

user - the user to clear settings for

project - the project to clear settings for

See Also:

setUISettings(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.project.Project, com.almworks.jira.structure.api.settings.UISettings), UISettings