com.almworks.jira.structure.api.settings

Interface StructureConfiguration

public interface StructureConfiguration

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

Typically, only Jira administrators have write access to the app 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
JqlClauseBuilder	addConfigurationScopeClause(JqlClauseBuilder builder) Adds to the JQL builder a condition that limits the result set to the projects enabled for Structure.
void	clearUISettings(ApplicationUser user, Project project) Completely removes per-user or per-project settings.
AttributeSensitivitySettings	getAttributeSensitivitySettings()
default 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.
Query	getConfigurationScopeQuery() Utility method that returns a JQL query that selects all issues in the projects that are available for Structure.
default List<PermissionSubject>	getCreatorPermissionSubjects() Used to get the list of groups (possibly other permission subjects) that are allowed to create new structures.
List<Project>	getCurrentlyEnabledProjects()
long	getDefaultStructureId(Project project) Returns the ID of the default structure for a given project.
default List<PermissionSubject>	getEnabledPermissionSubjects() Used to get the list of groups (possibly other permission subjects) that the app is enabled for.
List<PermissionSubject>	getPermissionSubjects(StructureAppPermission permission) Returns the list of groups (possibly other permission subjects) that are granted the given Structure app permission.
LongList	getPickedProjectIds() This method returns a list of IDs of projects picked by the administrator for the Structure app.
List<Project>	getPickedProjects() This method returns a list of projects picked by the administrator for the Structure app.
default 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(ApplicationUser user, Project project) Retrieves user interface settings for the specified user and project.
boolean	isAllowed(StructureAppPermission permission, ApplicationUser user) Checks if the user is granted the given Structure app permission.
boolean	isAllowedForAnyone(StructureAppPermission permission) Checks if the given Structure app permission is granted to all users.
default boolean	isAutomationAccessAllowed(ApplicationUser user) Checks if the user is allowed to configure and use automation.
default boolean	isAutomationEnabledForAnyone()
default boolean	isCreateEnabledForAnyone()
boolean	isDefaultStructureSetForProject(Project project) Used to check whether a specific project has system-level default structure overridden with project-level default structure.
boolean	isEnabledForAllProjects()
default boolean	isEnabledForAnyone()
boolean	isProjectEnabled(Project project) Checks if a given project is enabled for Structure
boolean	isStructureAvailable(ApplicationUser user) Checks if Structure is available for the specified user.
default boolean	isStructureCreationAllowed(ApplicationUser user) Checks if the user is allowed to create new structures.
default boolean	isSynchronizationAllowed(ApplicationUser user) Checks if the user is allowed to configure and control synchronizers.
default boolean	isSynchronizationEnabledForAnyone()
void	setAllowedForAnyone(StructureAppPermission permission, boolean allowed) Grant the given Structure app permission to anyone.
void	setAttributeSensitivitySettings(AttributeSensitivitySettings settings)
default void	setAutomationEnabledForAnyone(boolean enabled) Changes whether the automation is available for all users.
default void	setAutomationPermissionSubjectsEncoded(String subjects) Changes the list of the users / groups that are allowed to configure and control automation in controlled structures.
default void	setCreateEnabledForAnyone(boolean enabled) Changes whether the creation of new structures is available for all users.
default void	setCreatorPermissionSubjectsEncoded(String subjects) Changes the list of the users / groups that are allowed to create new structures.
void	setDefaultStructureId(Project project, Long structureId) Changes the ID of the default structure for the specified project.
void	setEnabledForAllProjects(boolean enabled) Changes whether the app is enabled for all projects.
default void	setEnabledForAnyone(boolean enabled) Changes whether the app is available for all users.
default void	setEnabledPermissionSubjectsEncoded(String subjects) Changes the list of the users / groups that the Structure app is enabled for.
default void	setPermissionSubjects(StructureAppPermission permission, Collection<? extends PermissionSubject> subjects) Changes the list of the users / groups that are granted the given Structure app permission.
void	setPermissionSubjectsEncoded(StructureAppPermission permission, String subjects) Changes the list of the users / groups that are granted the given Structure app permission.
default void	setPickedProjectIds(Collection<Long> projectIds) Changes projects that Structure is enabled for.
default void	setPickedProjectIds(LongIterable projectIds) Changes projects that Structure is enabled for.
void	setPickedProjectIds(String idList) Changes projects that Structure is enabled for.
default void	setSynchronizationEnabledForAnyone(boolean enabled) Changes whether the synchronization is available for all users.
default void	setSynchronizationPermissionSubjectsEncoded(String subjects) Changes the list of the users / groups that are allowed to configure and control synchronizers in controlled structures.
void	setUISettings(ApplicationUser user, 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 is enabled for all projects

See Also:

Selecting Structure-Enabled Projects

getPickedProjectIds

@NotNull
LongList getPickedProjectIds()

This method returns a list of IDs of projects picked by the administrator for the Structure app. 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<Project> getPickedProjects()

This method returns a list of projects picked by the administrator for the Structure app. 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<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
                         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

default boolean isEnabledForAnyone()

Returns:

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

See Also:

Restricting User Access to Structure

getEnabledPermissionSubjects

@NotNull
default List<PermissionSubject> getEnabledPermissionSubjects()

Used to get the list of groups (possibly other permission subjects) that the app is enabled for. Note that if the app 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 app is enabled for (when not enabled for anyone)

See Also:

PermissionSubject.JiraGroup, Restricting User Access to Structure

isCreateEnabledForAnyone

default boolean isCreateEnabledForAnyone()

Returns:

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

See Also:

Changing Permission to Create New Structures

getCreatorPermissionSubjects

@NotNull
default 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

default 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
default 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

default 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
default 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 app is enabled for all projects.

Parameters:

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

See Also:

Selecting Structure-Enabled Projects

setPickedProjectIds

void setPickedProjectIds(@Nullable
                         String idList)

Changes projects that Structure 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

setPickedProjectIds

default void setPickedProjectIds(@Nullable
                                 LongIterable projectIds)

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

Parameters:

projectIds - collection of project IDs

See Also:

Selecting Structure-Enabled Projects

setPickedProjectIds

default void setPickedProjectIds(@Nullable
                                 Collection<Long> projectIds)

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

Parameters:

projectIds - collection of project IDs

See Also:

Selecting Structure-Enabled Projects

setEnabledForAnyone

default void setEnabledForAnyone(boolean enabled)

Changes whether the app is available for all users.

Parameters:

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

See Also:

Restricting User Access to Structure

setEnabledPermissionSubjectsEncoded

default void setEnabledPermissionSubjectsEncoded(@Nullable
                                                 String subjects)

Changes the list of the users / groups that the Structure app 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

default 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

default 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

default 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

default 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

default 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

default 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
JqlClauseBuilder addConfigurationScopeClause(@Nullable
                                                      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
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
                             ApplicationUser user)

Checks if Structure is available for the specified user.

This is not the same as isAllowed(CoreAppPermissions.USE, user), because it also checks user's access to enabled projects.

Parameters:

user - the user, null means anonymous

Returns:

true if the user can use Structure

See Also:

Who Has Access to the Structure

isStructureCreationAllowed

default boolean isStructureCreationAllowed(@Nullable
                                           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

default boolean isSynchronizationAllowed(@Nullable
                                         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

default boolean isAutomationAccessAllowed(@Nullable
                                          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)

isAllowedForAnyone

boolean isAllowedForAnyone(@NotNull
                           StructureAppPermission permission)

Checks if the given Structure app permission is granted to all users.

Parameters:

permission - the permission

Returns:

true if the permission is granted to all users

See Also:

CoreAppPermissions

getPermissionSubjects

@NotNull
List<PermissionSubject> getPermissionSubjects(@NotNull
                                                       StructureAppPermission permission)

Returns the list of groups (possibly other permission subjects) that are granted the given Structure app permission.

Parameters:

permission - the permission

Returns:

the list of subjects that are granted the permission

See Also:

CoreAppPermissions

setAllowedForAnyone

void setAllowedForAnyone(@NotNull
                         StructureAppPermission permission,
                         boolean allowed)

Grant the given Structure app permission to anyone.

Parameters:

permission - the permission

allowed - true to grant the permission to anyone

See Also:

CoreAppPermissions

setPermissionSubjectsEncoded

void setPermissionSubjectsEncoded(@NotNull
                                  StructureAppPermission permission,
                                  @Nullable
                                  String subjects)

Changes the list of the users / groups that are granted the given Structure app permission.

Parameters:

permission - the permission

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

See Also:

CoreAppPermissions

setPermissionSubjects

default void setPermissionSubjects(@NotNull
                                   StructureAppPermission permission,
                                   @Nullable
                                   Collection<? extends PermissionSubject> subjects)

Changes the list of the users / groups that are granted the given Structure app permission.

Parameters:

permission - the permission

subjects - the collection of permission subjects

See Also:

CoreAppPermissions

isAllowed

boolean isAllowed(@NotNull
                  StructureAppPermission permission,
                  @Nullable
                  ApplicationUser user)

Checks if the user is granted the given Structure app permission.

Parameters:

permission - the permission

user - the user, null means anonymous

Returns:

true if the user is granted the permission

See Also:

CoreAppPermissions

getDefaultStructureId

long getDefaultStructureId(@Nullable
                           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.

The Structure app 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
                           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
                                        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
                                  ApplicationUser user,
                                  @Nullable
                                  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
                   ApplicationUser user,
                   @Nullable
                   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
                     ApplicationUser user,
                     @Nullable
                     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

getAttributeSensitivitySettings

@NotNull
AttributeSensitivitySettings getAttributeSensitivitySettings()

setAttributeSensitivitySettings

void setAttributeSensitivitySettings(@NotNull
                                     AttributeSensitivitySettings settings)