@PublicApi public interface

ManagedConfigurationItemService

com.atlassian.jira.config.managedconfiguration.ManagedConfigurationItemService
Known Indirect Subclasses

@PublicApi

This interface is designed for plugins to consume (call its methods).

Clients of @PublicApi can expect that programs compiled against a given version will remain binary compatible with later versions of the @PublicApi as per each product's API policy as long as the client does not implement/extend @PublicApi interfaces or classes (refer to each product's API policy for the exact guarantee---usually binary compatibility is guaranteed at least across minor versions).

Note: since @PublicApi interfaces and classes are not designed to be implemented or extended by clients, we may perform certain types of binary-incompatible changes to these classes and interfaces, but these will not affect well-behaved clients that do not extend/implement these types (in general, only classes and interfaces annotated with @PublicSpi are safe to extend/implement).

Class Overview

This provides an API for plugin developers and for JIRA internally to restrict the administration of certain configuration items. Often, a plugin developer will want to configure JIRA programmatically and rely on that configuration being unchanged. Using this API, the developer can register their desired items as "managed" or "locked" configuration items. This will prevent administrators from changing the configuration and invalidating the plugin's needs.

There are a few different states a ManagedConfigurationItem can be in. These are determined by the properties isManaged() and getConfigurationItemAccessLevel():

  • isManaged() == true - this item is being managed by JIRA or a plugin
  • getConfigurationItemAccessLevel() - if an item is managed, this property determines who can edit the item. See ConfigurationItemAccessLevel for more information.

For a list of which JIRA configuration items can be managed, see ManagedConfigurationItemType.

Each configuration item can only have one ManagedConfigurationItem describing it.

See Also

Summary

Constants
String SOURCE_PREFIX_PLUGIN Denotes the prefix used in the getSourceId() field when items are managed by a plugin.
Public Methods
boolean doesUserHavePermission(User user, ConfigurationItemAccessLevel configurationItemAccessLevel)
Determine if the specified User would have permission to edit an ManagedConfigurationItem with the specified level.
boolean doesUserHavePermission(User user, ManagedConfigurationItem item)
Determine if the specified User would have permission to edit the ManagedConfigurationItem.
@Nonnull Collection<ManagedConfigurationItem> getManagedConfigurationItems(ManagedConfigurationItemType type)
Retrieves all of the ManagedConfigurationItems of the specified type which are currently "available" (meaning their owner is currently available).
@Nonnull ManagedConfigurationItem getManagedCustomField(CustomField customField)
Given the CustomField, attempt to retrieve the ManagedConfigurationItem that describes it.
@Nonnull ManagedConfigurationItem getManagedWorkflow(JiraWorkflow workflow)
Given the JiraWorkflow, attempt to retrieve the ManagedConfigurationItem that describes it.
@Nonnull ManagedConfigurationItem getManagedWorkflowScheme(Long schemeId)
Given the workflow scheme ID, attempt to retrieve the ManagedConfigurationItem that describes it.
@Nonnull ManagedConfigurationItem getManagedWorkflowScheme(WorkflowScheme workflowScheme)
Given the WorkflowScheme, attempt to retrieve the ManagedConfigurationItem that describes it.
@Nonnull ServiceOutcome<Void> removeManagedConfigurationItem(ManagedConfigurationItem item)
Remove the registration of this ManagedConfigurationItem.
@Nonnull ServiceOutcome<ManagedConfigurationItem> updateManagedConfigurationItem(ManagedConfigurationItem item)
Update the registration of this ManagedConfigurationItem.

Constants

public static final String SOURCE_PREFIX_PLUGIN

Denotes the prefix used in the getSourceId() field when items are managed by a plugin.

Constant Value: "plugin:"

Public Methods

public boolean doesUserHavePermission (User user, ConfigurationItemAccessLevel configurationItemAccessLevel)

Determine if the specified User would have permission to edit an ManagedConfigurationItem with the specified level.

Parameters
user the user
configurationItemAccessLevel the level
Returns
  • the result

public boolean doesUserHavePermission (User user, ManagedConfigurationItem item)

Determine if the specified User would have permission to edit the ManagedConfigurationItem.

Parameters
user the user
item the item
Returns
  • the result

@Nonnull public Collection<ManagedConfigurationItem> getManagedConfigurationItems (ManagedConfigurationItemType type)

Retrieves all of the ManagedConfigurationItems of the specified type which are currently "available" (meaning their owner is currently available).

Parameters
type the type to retrieve
Returns
  • the items

@Nonnull public ManagedConfigurationItem getManagedCustomField (CustomField customField)

Given the CustomField, attempt to retrieve the ManagedConfigurationItem that describes it. If it does not exist, a default implementation will be returned.

If the manager of this item is no longer available (e.g. if a plugin manages a JIRA custom field and the plugin is disabled) then the item can not be considered managed.

Parameters
customField the custom field
Returns
  • the item's representation

@Nonnull public ManagedConfigurationItem getManagedWorkflow (JiraWorkflow workflow)

Given the JiraWorkflow, attempt to retrieve the ManagedConfigurationItem that describes it. If it does not exist, a default implementation will be returned.

If the manager of this item is no longer available (e.g. if a plugin manages a workflow and the plugin is disabled) then the item can not be considered managed.

Parameters
workflow the workflow
Returns
  • the item's representation

@Nonnull public ManagedConfigurationItem getManagedWorkflowScheme (Long schemeId)

Given the workflow scheme ID, attempt to retrieve the ManagedConfigurationItem that describes it. If it does not exist, a default implementation will be returned.

If the manager of this item is no longer available (e.g. if a plugin manages a workflow scheme and the plugin is disabled) then the item can not be considered managed.

Parameters
schemeId the workflow scheme ID
Returns
  • the item's representation
See Also

@Nonnull public ManagedConfigurationItem getManagedWorkflowScheme (WorkflowScheme workflowScheme)

Given the WorkflowScheme, attempt to retrieve the ManagedConfigurationItem that describes it. If it does not exist, a default implementation will be returned.

If the manager of this item is no longer available (e.g. if a plugin manages a workflow scheme and the plugin is disabled) then the item can not be considered managed.

Parameters
workflowScheme the workflow scheme
Returns
  • the item's representation
See Also

@Nonnull public ServiceOutcome<Void> removeManagedConfigurationItem (ManagedConfigurationItem item)

Remove the registration of this ManagedConfigurationItem. If the item was not previously managed, an error will be returned.

Parameters
item the item to stop managing
Returns
  • the result; errors if saving the item failed

@Nonnull public ServiceOutcome<ManagedConfigurationItem> updateManagedConfigurationItem (ManagedConfigurationItem item)

Update the registration of this ManagedConfigurationItem. If the item was not previously managed, it will now be managed.

Parameters
item the item to manage
Returns
  • the result; errors if saving the item failed