Package com.atlassian.jira.config

Interface IssueTypeSchemeService

All Known Implementing Classes:
DefaultIssueTypeSchemeService
@PublicApi public interface IssueTypeSchemeService
Service for managing issue type schemes and their project associations.

Note, this service does not support issue type migrations. Issue type scheme updates and project associations that require migrations will fail and return with error outcomes.

Since:
8.0

  • Method Details

    • createIssueTypeScheme

      ServiceOutcome<FieldConfigScheme> createIssueTypeScheme(ApplicationUser user, String name, String description, List<String> issueTypeIds, String defaultIssueTypeId)
      Creates a new issue type scheme with the specified name, description, issue types, and default issue type. Newly created issue type schemes do not start out associated with any projects.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the name is null or an empty string
      • no issue type ids are specified
      • the new scheme's default issue type is not listed among the issueTypeIds

      Parameters:
      user - user that performs the create operation. Must be a Jira administrator.
      name - what the new issue type scheme will be called. Must not be null or empty.
      description - optional additional information about the new scheme
      issueTypeIds - which issue types will be available to projects associated with this scheme. Must not be null or empty.
      defaultIssueTypeId - specifies which of the new scheme's issue types will be initially selected when creating a new issue (in a project associated with this scheme). Can be null (meaning no default), but otherwise must be an id found in issueTypeIds.
      Returns:
      a service outcome containing the created issue type scheme or an error if something went wrong during the operation.

    • createIssueTypeScheme

      default ServiceOutcome<FieldConfigScheme> createIssueTypeScheme(ApplicationUser user, String name, String description, List<String> issueTypeIds)
      Creates a new issue type scheme with the specified name, description, issue types, and an unspecified default issue type. Newly created issue type schemes do not start out associated with any projects.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the name is null or an empty string
      • no issue type ids are specified

      Parameters:
      user - user that performs the create operation. Must be a Jira administrator.
      name - what the new issue type scheme will be called. Must not be null or empty.
      description - optional additional information about the new scheme
      issueTypeIds - which issue types will be available to projects associated with this scheme. Must not be null or empty.
      Returns:
      a service outcome containing the created issue type scheme or an error if something went wrong during the operation.

    • getAllIssueTypeSchemes

      ServiceOutcome<List<FieldConfigScheme>> getAllIssueTypeSchemes(ApplicationUser user)
      Retrieves and returns all issue type schemes in the Jira.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator

      Parameters:
      user - user that performs the retrieval operation. Must be a Jira administrator.
      Returns:
      a service outcome containing the issue type schemes found in the Jira

    • getIssueTypeScheme

      ServiceOutcome<FieldConfigScheme> getIssueTypeScheme(ApplicationUser user, long schemeId)
      Retrieves the issue type scheme specified by the schemeId.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the schemeId does not correspond with a valid issue type scheme

      Parameters:
      user - user that performs the retrieval operation. Must be a Jira administrator.
      schemeId - unique id that references an existing issue type scheme to retrieve.
      Returns:
      a service outcome containing the specified issue type scheme, if it exists.

    • getIssueTypeScheme

      default ServiceOutcome<FieldConfigScheme> getIssueTypeScheme(ApplicationUser user, String schemeId)
      Retrieves the issue type scheme specified by the schemeId.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the schemeId does not correspond with a valid issue type scheme

      Parameters:
      user - user that performs the retrieval operation. Must be a Jira administrator.
      schemeId - unique id that references an existing issue type scheme to retrieve.
      Returns:
      a service outcome containing the specified issue type scheme, if it exists.

    • updateIssueTypeScheme

      ServiceOutcome<FieldConfigScheme> updateIssueTypeScheme(ApplicationUser user, long schemeId, String name, String description, List<String> issueTypeIds, String defaultIssueTypeId)
      Updates the issue type scheme specified by schemeId to have the given name, description, issue types, and default issue type. Project associations are not within the scope of this operation; use setProjectAssociations or addProjectAssociations instead.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the schemeId does not correspond with a valid issue type scheme
      • an attempt is made to update the system's default issue type scheme
      • the name is null or an empty string
      • no issue type ids are specified
      • the new default issue type is not listed among the issueTypeIds being assigned
      • changing the scheme's issue types requires a migration of issues by any of its associated projects

      Parameters:
      user - user that performs the update operation. Must be a Jira administrator.
      schemeId - unique id that references an existing issue type scheme to update.
      name - what the issue type scheme will be called after the update. Must not be null or empty.
      description - optional additional information about the updated scheme
      issueTypeIds - which issue types will be available to projects associated with this scheme. Must not be null or empty.
      defaultIssueTypeId - specifies which of the scheme's issue types will be initially selected when creating a new issue (in a project associated with this scheme). Can be null (meaning no default), but otherwise must be an id found in issueTypeIds being assigned.
      Returns:
      a service outcome containing the updated issue type scheme or an error if something went wrong during the operation.

    • updateIssueTypeScheme

      default ServiceOutcome<FieldConfigScheme> updateIssueTypeScheme(ApplicationUser user, String schemeId, String name, String description, List<String> issueTypeIds, String defaultIssueTypeId)
      Updates the issue type scheme specified by schemeId to have the given name, description, issue types, and default issue type. Project associations are not within the scope of this operation; use setProjectAssociations or addProjectAssociations instead.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the schemeId does not correspond with a valid issue type scheme
      • an attempt is made to update the system's default issue type scheme
      • the name is null or an empty string
      • no issue type ids are specified
      • the new default issue type is not listed among the issueTypeIds being assigned
      • changing the scheme's issue types requires a migration of issues by any of its associated projects

      Parameters:
      user - user that performs the update operation. Must be a Jira administrator.
      schemeId - unique id that references an existing issue type scheme to update.
      name - what the issue type scheme will be called after the update. Must not be null or empty.
      description - optional additional information about the updated scheme
      issueTypeIds - which issue types will be available to projects associated with this scheme. Must not be null or empty.
      defaultIssueTypeId - specifies which of the scheme's issue types will be initially selected when creating a new issue (in a project associated with this scheme). Can be null (meaning no default), but otherwise must be an id found in issueTypeIds being assigned.
      Returns:
      a service outcome containing the updated issue type scheme or an error if something went wrong during the operation.

    • updateIssueTypeScheme

      default ServiceOutcome<FieldConfigScheme> updateIssueTypeScheme(ApplicationUser user, long schemeId, String name, String description, List<String> issueTypeIds)
      Updates the issue type scheme specified by schemeId to have the given name, description, issue types, and an unspecified default issue type. Project associations are not within the scope of this operation; use setProjectAssociations or addProjectAssociations instead.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the schemeId does not correspond with a valid issue type scheme
      • an attempt is made to update the system's default issue type scheme
      • the name is null or an empty string
      • no issue type ids are specified
      • changing the scheme's issue types requires a migration of issues by any of its associated projects

      Parameters:
      user - user that performs the update operation. Must be a Jira administrator.
      schemeId - unique id that references an existing issue type scheme to update.
      name - what the issue type scheme will be called after the update. Must not be null or empty.
      description - optional additional information about the updated scheme
      issueTypeIds - which issue types will be available to projects associated with this scheme. Must not be null or empty.
      Returns:
      a service outcome containing the updated issue type scheme or an error if something went wrong during the operation.

    • updateIssueTypeScheme

      default ServiceOutcome<FieldConfigScheme> updateIssueTypeScheme(ApplicationUser user, String schemeId, String name, String description, List<String> issueTypeIds)
      Updates the issue type scheme specified by schemeId to have the given name, description, issue types, and an unspecified default issue type. Project associations are not within the scope of this operation; use setProjectAssociations or addProjectAssociations instead.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the schemeId does not correspond with a valid issue type scheme
      • an attempt is made to update the system's default issue type scheme
      • the name is null or an empty string
      • no issue type ids are specified
      • changing the scheme's issue types requires a migration of issues by any of its associated projects

      Parameters:
      user - user that performs the update operation. Must be a Jira administrator.
      schemeId - unique id that references an existing issue type scheme to update.
      name - what the issue type scheme will be called after the update. Must not be null or empty.
      description - optional additional information about the updated scheme
      issueTypeIds - which issue types will be available to projects associated with this scheme. Must not be null or empty.
      Returns:
      a service outcome containing the updated issue type scheme or an error if something went wrong during the operation.

    • deleteIssueTypeScheme

      ServiceOutcome<Void> deleteIssueTypeScheme(ApplicationUser user, long schemeId)
      Deletes the issue type scheme specified by the schemeId. Any projects associated with this scheme will revert to the global default issue type scheme.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the schemeId does not correspond with a valid issue type scheme
      • an attempt is made to delete the system's default issue type scheme

      Parameters:
      user - user that performs the delete operation. Must be a Jira administrator.
      schemeId - unique id that references an existing issue type scheme to delete.
      Returns:
      an empty service outcome indicating a successful deletion or an error if something went wrong during the operation.

    • deleteIssueTypeScheme

      default ServiceOutcome<Void> deleteIssueTypeScheme(ApplicationUser user, String schemeId)
      Deletes the issue type scheme specified by the schemeId. Any projects associated with this scheme will revert to the global default issue type scheme.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the schemeId does not correspond with a valid issue type scheme
      • an attempt is made to delete the system's default issue type scheme

      Parameters:
      user - user that performs the delete operation. Must be a Jira administrator.
      schemeId - unique id that references an existing issue type scheme to delete.
      Returns:
      an empty service outcome indicating a successful deletion or an error if something went wrong during the operation.

    • addProjectAssociations

      ServiceOutcome<Void> addProjectAssociations(ApplicationUser user, long schemeId, List<String> projectIdsOrKeys)
      Adds additional project-scheme associations between the issue type scheme specified by the schemeId and the projects given by the projectIdsOrKeys collection. This operation does not modify or remove any existing project associations that the scheme has.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the schemeId does not correspond with a valid issue type scheme
      • any of the projectIdsOrKeys does not reference a valid project
      • associating the scheme with any of the specified projects requires an issue migration

      Parameters:
      user - user that performs the association operation. Must be a Jira administrator.
      schemeId - unique id that references an existing issue type scheme to add project associations to.
      projectIdsOrKeys - lookup keys/ids for projects to be associated with the issue type scheme
      Returns:
      an empty service outcome indicating the successful addition of associated projects or an error if something went wrong during the operation.

    • addProjectAssociations

      default ServiceOutcome<Void> addProjectAssociations(ApplicationUser user, String schemeId, List<String> projectIdsOrKeys)
      Adds additional project-scheme associations between the issue type scheme specified by the schemeId and the projects given by the projectIdsOrKeys collection. This operation does not modify or remove any existing project associations that the scheme has.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the schemeId does not correspond with a valid issue type scheme
      • any of the projectIdsOrKeys does not reference a valid project
      • associating the scheme with any of the specified projects requires an issue migration

      Parameters:
      user - user that performs the association operation. Must be a Jira administrator.
      schemeId - unique id that references an existing issue type scheme to add project associations to.
      projectIdsOrKeys - lookup keys/ids for projects to be associated with the issue type scheme
      Returns:
      an empty service outcome indicating the successful addition of associated projects or an error if something went wrong during the operation.

    • getAssociatedProjects

      ServiceOutcome<List<Project>> getAssociatedProjects(ApplicationUser user, long schemeId)
      Retrieves the project-scheme associations for the issue type scheme specified by the schemeId.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the schemeId does not correspond with a valid issue type scheme

      Parameters:
      user - user that performs the association operation. Must be a Jira administrator.
      schemeId - unique id that references an existing issue type scheme
      Returns:
      the projects associated with the specified schemeId or an error if something went wrong during the operation.

    • getAssociatedProjects

      default ServiceOutcome<List<Project>> getAssociatedProjects(ApplicationUser user, String schemeId)
      Retrieves the project-scheme associations for the issue type scheme specified by the schemeId.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the schemeId does not correspond with a valid issue type scheme

      Parameters:
      user - user that performs the association operation. Must be a Jira administrator.
      schemeId - unique id that references an existing issue type scheme
      Returns:
      the projects associated with the specified schemeId or an error if something went wrong during the operation.

    • setProjectAssociations

      @Deprecated ServiceOutcome<Void> setProjectAssociations(ApplicationUser user, long schemeId, List<String> projectIdsOrKeys)
      Deprecated.
      favor addProjectAssociations(ApplicationUser, long, List) invalid input: '&' removeProjectAssociation(ApplicationUser, long, String) instead
      Replaces the project-scheme associations for the issue type scheme specified by the schemeId with the projects given by the projectIdsOrKeys collection. Again, this operation overwrites any existing project associations that the scheme has.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the schemeId does not correspond with a valid issue type scheme
      • any of the projectIdsOrKeys does not reference a valid project
      • associating the scheme with any of the specified projects requires an issue migration

      Parameters:
      user - user that performs the association operation. Must be a Jira administrator.
      schemeId - unique id that references an existing issue type scheme.
      projectIdsOrKeys - lookup keys/ids for projects to be associated with the issue type scheme
      Returns:
      an empty service outcome indicating the successful replacement of associated projects or an error if something went wrong during the operation.

    • setProjectAssociations

      default ServiceOutcome<Void> setProjectAssociations(ApplicationUser user, String schemeId, List<String> projectIdsOrKeys)
      Replaces the project-scheme associations for the issue type scheme specified by the schemeId with the projects given by the projectIdsOrKeys collection. Again, this operation overwrites any existing project associations that the scheme has.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the schemeId does not correspond with a valid issue type scheme
      • any of the projectIdsOrKeys does not reference a valid project
      • associating the scheme with any of the specified projects requires an issue migration

      Parameters:
      user - user that performs the association operation. Must be a Jira administrator.
      schemeId - unique id that references an existing issue type scheme.
      projectIdsOrKeys - lookup keys/ids for projects to be associated with the issue type scheme
      Returns:
      an empty service outcome indicating the successful replacement of associated projects or an error if something went wrong during the operation.

    • removeAllProjectAssociations

      ServiceOutcome<Void> removeAllProjectAssociations(ApplicationUser user, long schemeId)
      Removes all project associations for the issue type scheme specified by the schemeId.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the schemeId does not correspond with a valid issue type scheme
      • the schemeId corresponds with the default global issue type scheme

      Parameters:
      user - user that performs the removal operation. Must be a Jira administrator.
      schemeId - unique id that references an existing issue type scheme.
      Returns:
      an empty service outcome indicating the successful removal of the associated projects or an error if something went wrong during the operation.

    • removeAllProjectAssociations

      default ServiceOutcome<Void> removeAllProjectAssociations(ApplicationUser user, String schemeId)
      Removes all project associations for the issue type scheme specified by the schemeId.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the schemeId does not correspond with a valid issue type scheme
      • the schemeId corresponds with the default global issue type scheme

      Parameters:
      user - user that performs the removal operation. Must be a Jira administrator.
      schemeId - unique id that references an existing issue type scheme.
      Returns:
      an empty service outcome indicating the successful removal of the associated projects or an error if something went wrong during the operation.

    • removeProjectAssociation

      ServiceOutcome<Void> removeProjectAssociation(ApplicationUser user, long schemeId, String projKeyOrId)
      For the issue type scheme specified by the schemeId, removes the project association given by projKeyOrId.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the schemeId does not correspond with a valid issue type scheme
      • the schemeId corresponds with the default global issue type scheme
      • the projKeyOrId doesn't correspond with a project that the issue type scheme is associated with
      • any of the projectIdsOrKeys does not reference a valid project

      Parameters:
      user - user that performs the removal operation. Must be a Jira administrator.
      schemeId - unique id that references an existing issue type scheme.
      projKeyOrId - key/id for the project that we're un-associating with the scheme
      Returns:
      an empty service outcome indicating the successful removal of the associated project or an error if something went wrong during the operation.

    • removeProjectAssociation

      default ServiceOutcome<Void> removeProjectAssociation(ApplicationUser user, String schemeId, String projKeyOrId)
      For the issue type scheme specified by the schemeId, removes the project association given by projKeyOrId.

      This operation will fail validation and return an unsuccessful outcome if:

      • the user is not a Jira administrator
      • the schemeId does not correspond with a valid issue type scheme
      • the schemeId corresponds with the default global issue type scheme
      • the projKeyOrId doesn't correspond with a project that the issue type scheme is associated with
      • any of the projectIdsOrKeys does not reference a valid project

      Parameters:
      user - user that performs the removal operation. Must be a Jira administrator.
      schemeId - unique id that references an existing issue type scheme.
      projKeyOrId - key/id for the project that we're un-associating with the scheme
      Returns:
      an empty service outcome indicating the successful removal of the associated project or an error if something went wrong during the operation.

    • getIssuesRequiringMigration

      ServiceOutcome<List<Issue>> getIssuesRequiringMigration(ApplicationUser user, Collection<String> chosenIssueTypeIds, List<Long> projectIds)
      Figures out which issues in the specified projects would require migration if only the chosenIssueTypeIds were made available to the projects.
      Parameters:
      user - user that performs the lookup operation.
      chosenIssueTypeIds - collection of issue type ids against which we're checking the need for issue migrations.
      projectIds - collection of unique identifiers for the projects whose issues may require migration.
      Returns:
      a service outcome containing the list of issues requiring migration (if any) or an error if something went wrong during the operation.

    • getIssuesRequiringMigrationDueToSchemeAssociation

      ServiceOutcome<List<Issue>> getIssuesRequiringMigrationDueToSchemeAssociation(ApplicationUser user, FieldConfigScheme issueTypeScheme, List<Long> projectIds)
      Figures out which issues in the specified projects would require migration if the given issueTypeScheme were to be associated with them.
      Parameters:
      user - user that performs the lookup operation.
      issueTypeScheme - issue type scheme against which we're checking the need for issue migrations.
      projectIds - collection of unique identifiers for the projects whose issues may require migration.
      Returns:
      a service outcome containing the list of issues requiring migration (if any) or an error if something went wrong during the operation.

    • getNumIssuesMatchingTypesInProjects

      long getNumIssuesMatchingTypesInProjects(ApplicationUser user, Collection<Long> projectIds, Collection<String> issueTypeIds) throws SearchException
      For the projects specified by projectIds, determines how many issues are of the types given by issueTypIds. This functionality is provided as a separate hook, as it can be implemented more efficiently this way rather than via getIssuesMatchingTypesInProjects(..).size().
      Parameters:
      user - user that performs the lookup operation.
      projectIds - unique identifiers for the projects whose issues we'd like to inspect.
      issueTypeIds - unique identifiers for the issue types that we're looking for instances of in the projects.
      Returns:
      the number of issues in the given projects that are of the types specified by issueTypeIds
      Throws:
      SearchException

    • getIssuesMatchingTypesInProjects

      @Deprecated(forRemoval=true) List<Issue> getIssuesMatchingTypesInProjects(ApplicationUser user, Collection<Long> projectIds, Collection<String> issueTypeIds) throws SearchException
      Deprecated, for removal: This API element is subject to removal in a future version.
      use getIssuesMatchingTypesInProjectsUnsorted(ApplicationUser, Collection, Collection) instead.
      For the projects specified by projectIds, finds the issues that are of the types given by issueTypIds. Note: rather than calling .size() on the results of this method, use the more efficient getNumIssuesMatchingTypesInProjects(...) instead.
      Parameters:
      user - user that performs the lookup operation.
      projectIds - unique identifiers for the projects whose issues we'd like to inspect.
      issueTypeIds - unique identifiers for the issue types that we're looking for instances of in the projects.
      Returns:
      List of Issues in the given projects that are of the types specified by issueTypeIds
      Throws:
      SearchException

    • getIssuesMatchingTypesInProjectsUnsorted

      Stream<Issue> getIssuesMatchingTypesInProjectsUnsorted(ApplicationUser user, Collection<Long> projectIds, Collection<String> issueTypeIds) throws SearchException
      For the projects specified by projectIds, finds the issues that are of the types given by issueTypIds.
      Parameters:
      user - user that performs the lookup operation.
      projectIds - unique identifiers for the projects whose issues we'd like to inspect.
      issueTypeIds - unique identifiers for the issue types that we're looking for instances of in the projects.
      Returns:
      Unsorted stream of Issues in the given projects that are of the types specified by issueTypeIds. Note that it should be closed after use, e.g. using try-with-resources
      Throws:
      SearchException

    • errorCase

      <T> ServiceOutcome<T> errorCase(String msg, ErrorCollection.Reason reason)
      Creates a failed service outcome with the specified error msg and reason.
      Type Parameters:
      T - generic type that corresponds with what the successful outcome would have been.
      Parameters:
      msg - string explanation of the failure.
      reason - Motivation/reason behind the failure.
      Returns:
      a failed service outcome with the specified error.

    • getDefaultIssueType

      IssueType getDefaultIssueType(FieldConfigScheme issueTypeScheme)
      Looks up and returns the default issue type (the one that is presented as the initial/selected choice to users when creating a new Issue, for instance) for the specified issue type scheme.
      Parameters:
      issueTypeScheme - scheme whose default issue type we'd like to look up.
      Returns:
      the default issue type for the specified issue type scheme--or null if it is unspecified.