Project Specific Select Field

This plugin provides new custom field types based on single and multi select field, where the project admin is able to define the values for the select field specifically for his project resp. the corresponding custom field context. (In standard Jira the option values of a select field can only be managed by a Jira admin.)

Auto-complete and filter criteria selection in JIRA search as well as use of the custom field in Pie Chart, Issue Statistics and Two-Dimentional Filter Statistics gadgets is supported.

Configuration

Adding a Project Specific Custom Field

After installation of the add-on go to Jira administration and add a custom field of type

• Project Specific Select Field
• Project Specific Multi Select Field
• Project Specific Select Field (simple) -- This custom field type is deprecated (see details below)

Please choose the required custom field type Project Specific Select Field or Project Specific Multi Select Field. If you want to use Project Specific Select Field (simple), please notice that this custom field type is deprecated (see details below)

In the next step you have to provide a name (mandatory) of the custom field and a description (optional).

In case of Project Specific Select Field and Project Specific Multi Select Field you also have to add one first option value (mandatory) for the global custom field context created by default. This is not required for Project Specific Select Field (simple).

Adding a context to a Project Specific Custom Field

When you now go to configuration of the custom field, you see that there is a default configuration scheme has been created. This configured by default for all issue types and all projects. Please delete this, because it is typically not needed. If you don't delete it, this means that this is the default context and shared between all projects "Global (all projects)" for which no specific context has been created (see below).

Then click to add new context and select one project from the provided list of possible projects. Create a second, third etc. new context each time selecting another project.

Starting with version 3.0 of Project Specific Select Field plugin there is an alternative way to create contexts in addition to Jira standard feature. This should be easier to use and allow better overview if you have of projects and therefore hundreds of contexts. Please choose Project Specific on the left navigation in the Issues system administration page. See screeshot below.

If you select more then one project when adding a new context, then this means, that these selected projects will share the list of option values and every project administrator can edit this shared list of option values.

If you leave issue type blank, then this means that this context is used for all issue types "Global (all issues)".

If you leave the name blank when creating a new context, then a name is created automatically using the id of the context.

You can have as much custom fields of this type as needed incl. full support for default values, setting fields to required in field configurations etc. To set the option values leave administration and open the corresponding project.

Adding Option Values to a Project Specific Select Field

There is a new project administrator tab called Project Specific showing custom fields of type Project Specific Select Field, Project Specific Multi Select Field and Project Specific Select Field (simple) relevant for this project.

The project admin can add option values for the custom fields, which then are used in create, view and edit issue dialogs and for searching. He can also order and edit them. Option values can also be disabled (these values are shown in grey color), so that they are no longer available in create or edit dialog, but old issues still can have this option value assigned. If you want to reactivate a disabled field value, simply re-enable it gain. -- Please notice that edit and order are not possible for custom fields of type Project Specific Select Field (simple).

On an additional project tab you also find statistical information incl. option value, number of issues with this field value, percentage, bar chart and link to search. You also find a button in the upper right corner, which directs you to the project administration tab mentioned above.

Audit Logging

When users are adding, editing or deleting option values for a Project Specific Select Field for a project, then a corresponding entry in Jira Audit Log is created.

Delete Option are logged in Coverage area “Apps” under Coverage level “Base”, Add Option and Edit Option under “Advanced”.

See here for details on how to use and activate Jira Audit Log for Project Specific Select Fields.

Deprecated Custom Field Type

Project Specific Select Fields (simple) is deprecated, because it has some limitations. On one hand there is no need to define a custom field context for each project, but because it is internally based on a text field, it cannot be used in Pie Chart, Issue Statistics and Two-Dimentional Filter Statistics gadgets and does not support auto-complete and filter criteria selection in JIRA search.

Converting Standard Single and Multi Select Field to Project Specific Select Field

It is easy to convert and existing JIRA standard single or multi select custom field to Project Specific Select Field, because the plugin internally uses JIRAs standard methods like option manager and custom field context and just exposes the admin UI for adding and disabling option values to project admins.

As described in the Jira documentation, you can change custom field types using SQL on database level. (Please notice that this approach is not officially supported by Atlassian even if it is part of the JIRA documentation.)

• Always back up your data before performing any modifications to the database. If possible, try your modifications on a test server.
• Stop JIRA
• Connect to the database and execute the following statement for converting a multi select custom field

-- Attention: Please contact me to verify this statement with you 
UPDATE customfield
    SET CUSTOMFIELDTYPEKEY = 'jira.plugin.projectspecificselectfield.jpssf:multicftype',
        CUSTOMFIELDSEARCHERKEY = 'jira.plugin.projectspecificselectfield.jpssf:multiselectsearcher'
  WHERE CFNAME = 'MyMultiSelect' and 
        CUSTOMFIELDTYPEKEY = 'com.atlassian.jira.plugin.system.customfieldtypes:multiselect';

• Connect to the database and execute the following statement for converting a single select custom field

-- Attention: please contact me to verify this statement with you 
UPDATE customfield
    SET CUSTOMFIELDTYPEKEY = 'jira.plugin.projectspecificselectfield.jpssf:singlecftype',
        CUSTOMFIELDSEARCHERKEY = 'jira.plugin.projectspecificselectfield.jpssf:multiselectsearcher'
  WHERE CFNAME = 'MySingleSelect' and 
        CUSTOMFIELDTYPEKEY = 'com.atlassian.jira.plugin.system.customfieldtypes:select';

• Connect to database and execute the following statement if you want to revert back from Project Specific Select Field to Jira standard select

-- Attention: please contact me to verify this statement with you 
UPDATE customfield
    SET CUSTOMFIELDTYPEKEY = 'com.atlassian.jira.plugin.system.customfieldtypes:select',
        CUSTOMFIELDSEARCHERKEY = 'com.atlassian.jira.plugin.system.customfieldtypes:multiselectsearcher'
  WHERE CFNAME = 'MySingleSelect' and
        CUSTOMFIELDTYPEKEY = 'jira.plugin.projectspecificselectfield.jpssf:singlecftype';

-- Attention: please contact me to verify this statement with you 
UPDATE customfield
    SET CUSTOMFIELDTYPEKEY = 'com.atlassian.jira.plugin.system.customfieldtypes:multiselect',
        CUSTOMFIELDSEARCHERKEY = 'com.atlassian.jira.plugin.system.customfieldtypes:multiselectsearcher'
  WHERE CFNAME = 'MyMultiSelect' and
        CUSTOMFIELDTYPEKEY = 'jira.plugin.projectspecificselectfield.jpssf:multicftype';

• Restart JIRA
• Reindex JIRA

REST API and SQL API

Project Specific Select Field custom fields and option values can be managed also via REST API and SQL API. For more details see here

• REST API
• SQL API

Support

In case of problems or enhancement requests concerning the plugin, please raise an issue in the Issue Tracker or get in contact via email.

In case of questions on usage or configuration, please raise a question in Atlassian Answers and tag your question with "addon-jira.plugin.projectspecificselectfield.j".

Detailed Logging

In some cases detailed logging information might be useful. To enabled this for the plugin please go to Administration > System > Logging and Profiling and set jira.plugin.projectspecificselectfield.ProjectSpecificSelectTab, jira.plugin.projectspecificselectfield.util.OptionValuesManagerUtil resp. jira.plugin.projectspecificselectfield.rest.OptionValuesManagerRest to DEGUB.

Problems with ordering of option value

For custom fields of type Project Specific Select Field and Project Specific Multi Select Field options can be manually ordered by project admins via Project Specific tab in project administration or by JIRA admins in custom fields configuration.

Because of a bug in an older versions of the Project Specific Select Field plugin, you might experience problems in ordering of the option values. When moving options top, bottom, up or down, it feels like there are two groups of options in the list (the newly added options in the upper part and option values added longer time ago at the bottom) and you cannot move an option from the lower part to the upper part, but just inside a group of options at the top or inside the group at the bottom. This is because in early version of the plugin a partentOptionId was set, which should have been null.

To check, if this problem is relevant for your please use the following SQL. Is option values are returned, then these needs to be fixed in the next step.

-- Attention: Please contact me to verify this statement with you 
SELECT CUSTOMFIELD.ID, CUSTOMFIELDTYPEKEY, CFNAME, CUSTOMFIELDOPTION.ID, CUSTOMVALUE 
FROM CUSTOMFIELD, CUSTOMFIELDOPTION
WHERE CUSTOMFIELD.ID = CUSTOMFIELDOPTION.CUSTOMFIELD
AND (CUSTOMFIELDTYPEKEY = 'jira.plugin.projectspecificselectfield.jpssf:multicftype'
OR CUSTOMFIELDTYPEKEY = 'jira.plugin.projectspecificselectfield.jpssf:singlecftype')
AND PARENTOPTIONID is not NULL

To find out relevant custom field id please use the following SQL.

SELECT ID, CFNAME, CUSTOMFIELDTYPEKEY from CUSTOMFIELD
WHERE CUSTOMFIELDTYPEKEY = 'jira.plugin.projectspecificselectfield.jpssf:multicftype'
OR CUSTOMFIELDTYPEKEY = 'jira.plugin.projectspecificselectfield.jpssf:singlecftype' ;

To fix this problem you need to update the corresponding rows in table CUSTOMFIELDOPTION. There are option values in this table for the corresponding custom field, where PARENTOPTIONID is not null. Please update these rows using SQL.

-- Attention: Please contact me to verify this statement with you 
UPDATE CUSTOMFIELDOPTION
SET PARENTOPTIONID = NULL
WHERE CUSTOMFIELD = <your_custom_field_id> ;

Updating from Version 0.9

In general the update process is very easy. Just update using Plugin resp. Add-on Manager in JIRA and you are done. Only when updating from version 0.9 to 1.x there is some manual work to do. In table AO_9661E7_SELECT_OPTION the column CUSTOM_FIELD_ID will be changed from String to Integer during update, but you as a database administrator have to prepare the data a little bit. In CUSTOM_FIELD_ID in version 0.9 values like "customfield_10001" where stored, with version 1.x it is just the integer "10001".

• Stop JIRA
• Make backup of database in case something goes wrong
• Open your database tool and execute the following statement (this one is specific for MySQL and might differe for other databases; please contact support in case you are not sure):

-- Attention: Please contact me to verify this statement with you
-- This statement works for PostgreSQL and Oracle databases; for other databases the SQL statements need little changes

UPDATE AO_9661E7_SELECT_OPTION SET CUSTOM_FIELD_ID = SUBSTR(CUSTOM_FIELD_ID, 13) 
WHERE CUSTOM_FIELD_ID LIKE 'customfield_%';

• Restart JIRA and verify update by opening a project, swith to "Project Specific" tab and review field values and issue statistics shown there

If this fails, then automatic change of column CUSTOM_FIELD_ID from String to Integer of table AO_9661E7_SELECT_OPTION during update cannot be done automatically by JIRA. Then please follow the instructions below.

• After shutdown and backup of your database execute the following statement to rename and create a new column with type Integer.

-- Attention: Please contact me to verify this statement with you
-- This statement works for Oracle database; for other databases the SQL statements need little changes

ALTER TABLE AO_9661E7_SELECT_OPTION
RENAME COLUMN CUSTOM_FIELD_ID TO CUSTOM_FIELD_ID_VARCHAR2;

ALTER TABLE AO_9661E7_SELECT_OPTION
ADD (CUSTOM_FIELD_ID NUMBER(20));

UPDATE AO_9661E7_SELECT_OPTION
SET CUSTOM_FIELD_ID = TO_NUMBER(REPLACE(CUSTOM_FIELD_ID_VARCHAR2 ,'customfield_'));

• Restart JIRA and verify update by opening a project, swith to "Project Specific" tab and review field values and issue statistics shown there