Package 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 Details

    • isEnabledForAllProjects

      boolean isEnabledForAllProjects()
      Returns:
      true if Structure is enabled for all projects
      See Also:

    • 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:

    • 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:

    • 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:

    • 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:

    • isEnabledForAnyone

      default boolean isEnabledForAnyone()
      Returns:
      true if Structure is enabled for all users (that have access to the enabled projects)
      See Also:

    • 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:

    • isCreateEnabledForAnyone

      default boolean isCreateEnabledForAnyone()
      Returns:
      true if creating new structures is enabled for all users (that have access to Structure at all)
      See Also:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • getAttributeSensitivitySettings

      @NotNull AttributeSensitivitySettings getAttributeSensitivitySettings()

    • setAttributeSensitivitySettings

      void setAttributeSensitivitySettings(@NotNull AttributeSensitivitySettings settings)