Tutorial - Creating a custom field type
|Level of experience||BEGINNER|
|Atlassian application||JIRA 4.X+|
On this page:
This tutorial shows you how to create a new custom field type for JIRA using the plugin development platform. You'll create a custom field that can only be edited as an admin user. Your custom field will be written and installed as a JIRA plugin, and include a Java class that extends the
GenericTextCFT class. You'll use a Velocity template, a format that combines Java and HTML, to render your field and control who can edit or view the field. To tether your Java class and template together, you'll define both in a single
customfield-type plugin module in your
atlassian-plugin.xml descriptor file.
This tutorial covers the following topics:
- An overview of custom fields and the files that comprise the plugin
- Extending the custom field type class,
GenericTextCFT, for your plugin
- Using the
customfield-typeplugin module type for JIRA
To complete this tutorial you should already understand basic Java development. Familiarity with JIRA is also helpful. You should be able to complete this tutorial even if you've never created a plugin before.
We encourage you to work through the tutorial. If you'd like to skip ahead or check your work when you're done, you can find the plugin source on Atlassian Bitbucket. Bitbucket serves as a public Git repository containing the tutorial's source code. To clone the repository for this plugin, issue the following command:
Alternatively, you can download the source code for this plugin project.
Step 1. Create the plugin project and trim the skeleton
In this step you'll generate a JIRA plugin skeleton. You'll use
atlas- commands to automate the plugin creation. Some files are automatically generated by the SDK that you won't need for this tutorial, so you'll delete them in this step.
- Open a terminal window and navigate to your Eclipse (or equivalent IDE) workspace directory.
Enter the following command to create a JIRA plugin skeleton:
When prompted, enter the following information to identify your plugin:
Confirm your entries when prompted with
Your terminal notifies you of a successful build:
Change to the
jira-custom-field-exampledirectory created by the previous step.
Delete the test directories.
Set up up testing for your custom field isn't part of this tutorial. Use the following commands to delete the test directories.
Delete the unnecessary Java files.
You'll build a Java class for your plugin in future steps.
- Edit the
Remove the generated
- Save and close the file.
Here's how your
atlassian-plugin.xml descriptor file should appear up to this point:
Import your project into your IDE
Make your project available to Eclipse.
You'll see a successful build message:
You can open a new terminal window to perform this action.
- Click File > Import.
Eclipse starts the Import wizard.
- Expand the General folder tree to choose Existing Projects into Workspace.
- Click Next.
- Click Browse and enter the root directory of your workspace.
Your Atlassian plugin folder should now appear under Projects.
- Ensure your plugin checkbox is ticked and click Finish.
Eclipse imports your project, and it's now visible in your Package Explorer view.
Step 2. Create your
Your custom field extends the JIRA
GenericTextCFType is one of many custom field-specific Java classes and interfaces – other examples include DateCFType to set dates, UserCFType to pick users, and SelectCFType for picking a single option from a list. The
GenericTextCFType class stores and retrieves field values as strings. Here you'll extend the class for your plugin, and in future steps you'll apply your field logic in your Velocity template so that admins alone can modify the string value.
These instructions are written for Eclipse, but you can use the equivalent steps for your own IDE.
- Open Eclipse.
- Locate the
- Right-click the package and choose New > Class.
- Name your class
com.atlassian.jira.issue.customfields.impl.GenericTextCFTypeas the superclass.
- Tick the checkboxes to include Constructors from superclass and Inherited abstract methods.
Your class contains the following stub code to extend
- Save and close the class.
Update your project changes.
Step 3. Create a Velocity template to format your custom field
In this step you'll write the logic for rendering your custom field in a Velocity template. You'll create a condition to check if the user's group name includes
'jira-administrators'. If users fit the criteria, they'll be able to edit the field value. All other users will be able to see the value entered, but be unable to change it. You'll also create an
else condition that if no value has been set for the field, JIRA will display "N/A" as the default value.
edit-jiraadminonlytext.vmfile under your new
Copy and paste the following onto the command line.
Here you'll add the conditional check to see if the user is an admin. If no value exists, the user will see "N/A".
- Hit CTRL + D to save and exit the VM editor.
Step 4. Add a
customfield-type plugin module to your descriptor file
In this step you'll complete your plugin code with the addition of a
customfield-type plugin module. You'll add this module to the
atlassian-plugin.xml descriptor file. The descriptor file was automatically generated when you built your plugin skeleton, and describes dependencies to the Atlassian system. Inserting a
customfield-type plugin module lets you add your custom field to JIRA. This module requires a Java class for implementation and a unique key identifier. You'll also reference your Velocity template as a resource type element. There are four view types for any custom field, three of which are required:
||yes||Provides a basic read-only view of the field value.|
||no||Read-only view for displaying in the issue navigator. The issue navigator will display the
||yes||Renders the edit widget in issue creation, editing issues, and editing defaults. This is the value you'll replace with your custom Velocity template.|
||yes||Shows the value in XML format for RSS or XML exports.|
You'll use two built-in Velocity templates in JIRA for the
xml view types, and your custom template for the
- Locate the closing
Add the opening and closing tags for your
Place the block before the end of the closing
</atlassian-plugin>tag. You'll give your custom field a unique key, name, and define
JiraCustomFieldas the implementing Java class.
Add a description inside the first
This description appears in JIRA when you apply the custom field type from the admin pages.
Define which Velocity templates to use for each view type:
- Save and close your descriptor file.
Update your project changes.
From your project root, issue the following command:
Here's the completed
atlassian-plugin.xml descriptor file:
Step 5. Build, install, and run your plugin
In this step you'll install your plugin and run JIRA. You'll log into your JIRA instance as an admin and configure visibility for your custom field.
Open a terminal and navigate to your project root.
This builds your plugin code, starts a JIRA instance, and installs your plugin. This could take a few minutes.
Locate the URL for JIRA.
Your terminal outputs the location of your local JIRA instance, defaulted to http://localhost:2990/jira
- Navigate to your JIRA instance in a browser window.
We recommend using Google Chrome or Mozilla Firefox for consistency.
- Log in with admin / admin.
- Once logged in, navigate to the custom field options under > Issues > Custom Fields.
- Click Add Custom Field and choose Advanced.
- Choose your plugin, Admin Editable Text Field from the list and click Next.
- Enter details as prompted.
Choose Any issue type for Choose applicable issue types, and Global context to apply to all issues in JIRA.
- Associate the field with all screens and click Next.
Step 6. Create a test user and test your custom field type
Now that you've added your custom field, let's put it to the test. You'll create a new user without admin permissions so you can verify your field settings.
- From any page in your local JIRA instance, click > Users Management.
- Click Create User and enter details for a test user.
Keep it simple and use your own email address.
- Next, create a project.
Click Projects > Create Project.
Now you'll be able to create an issue to test your field.
- Choose Bug Tracking > Next.
- Choose a name (like "Test") and click Submit.
- Create an issue for your project.
Click Create Issue and verify you can enter text into your custom field type as an admin.
- Log out and log in with your test user credentials.
- Create an issue as your test user.
Verify that you're unable to modify the field you customized.