Compatibility with JIRA

Plugin Version	3.12	3.13 (All)	4.0
Behaviours-jira-0.2.7.jar

Description

The behaviours plugin allows an administrator to create one more or behaviours, which can be thought of as "Behaviour Schemes". A behaviour defines how fields behave. Some examples of behaviours are:

• Making a field mandatory depending on other data entered in to the form
• Making a field read-only dependent on user role or group
• Doing server-side validation of field data, before the form is submitted
• Setting a field value dependent on other form data

Once you've created the behaviour apply it to a test project - test it works as expected, then apply it to a real project.

Installation

Download the zip file from the link above. From within the zip file, extract the Behaviours-nnn.jar and drop it in to WEB-INF/lib or whatever is appropriate for your application server.

Download Groovy 1.5.N from here - if you are not already using groovy, 1.5.7 is recommended. Copy <GroovyDistro>/embeddable/groovy-all-n.n.n.jar to WEB-INF/lib. Groovy 1.5.7 tested mostly.

If you had a previous version, please follow Uninstalling version 0.1 of the Behaviours plugin before installing.

Restart jira.

Examples

Use client side validation according to the Field Config Scheme for a given project

Create a new Behaviour. Go the Administration sceen, and click the Behaviours link, in the Schemes section.

Click Fields:

Check the Enable link next to "Validate Jira Requiredness" box.

then the all behaviours link.

Now click on Add Mapping next to your new behaviour. Select a project, then click the button:

This is the simplest possible configuration and should be used to check everything is working.

Create a new issue in the project that you have associated with this behaviour. Assuming you haven't done anything funky to the default field config scheme, the Summary field should be highlighted:

(If it isn't, see trouble-shooting below).

If you try to submit without entering a summary you should get the following popup:

If that's all working, continue...

Making a field required for a given project for a particular transition, using the workflow validator

You can use Jira Suite Utilities to make fields required on certain transitions, the problem is they are not shown as required until you submit. Create a new behaviour or edit an existing one. Click the Enable link next to "Use Validator Plugin". Ensure this behaviour is associated with a project.

When going through a transition that requires a field, these should be shown as required before you submit. In this example I have added Fields Required validator on the Resolve action.

Adding a server-side validator

You may wish certain fields to be validated on the server. For example, a "sponsor" field might verify that the provided sponsor exists in the company's LDAP server. Examples like this are too complex to be shipped though, so we'll just use a contrived example.

The com.onresolve.jira.groovy.user.Sample is a sample class included in the jar, that contains various examples. You can write your own classes or scripts, more on that later. For now we will use the checkValidJiraUser method to check that the field contains a valid jira user. (Of course, for this you would just use a User-type field, but for the purposes of demonstation...).

Create a new field of type Text Field < 255 chars, called Sponsor. Associate with your project, and make sure it's on a screen.

Now click the Fields link by your behaviour. From the Add Field section, choose Sponsor and click Add. Now click the link "Add server validation":

Enter the values as shown:

If you have made any mistakes you should get a validation error here, for instance if you accidentally put any spaces in either field.

Now, create a new issue in the project, and enter valid and invalid values for Sponsor:

You will have to tab away from the field for the validation to fire.

Another example is requiring the summary has a minimum of ten characters - use the method checkMinLength.

See the Sample.groovy file for how this is done.

Set one field based on another field with information provided by the server

In this next contrived example, we will set a read-only field with the component lead's user name. You need a server validator on the Component field to get the component lead, and you will make another field read-only.

Create a User-type field, in this example I've called it UserFieldA (if you try this example you must call the field the same thing, unless you modify the code). The behaviour should look like this:

So the user field is read-only, the method to use is setFieldToComponentLead.

On selecting a component the field value should change:

If you unselect the component or select Unknown it should be cleared.

Instead of using a precompiled class, try the same thing with a script. Create a file on disk accessible by jira, called say: SetFieldToComponentLead.groovy. Enter the following contents:

package com.onresolve.jira.groovy.user

import com.atlassian.jira.project.ProjectManager
import com.atlassian.jira.ComponentManager

public class ScriptSample extends FieldBehaviours {
    ComponentManager componentManager = ComponentManager.getInstance()

    public void setFieldToComponentLead () {
        FormField formComponent = getFieldById(fieldChanged)
        FormField formUserField = getFieldByName("UserFieldA")
        String componentLead
        String componentId = formComponent.getFormValue()

        if (componentId) {
            ProjectManager projectManager = componentManager.getProjectManager()
            componentLead = projectManager.getComponent(Long.parseLong(componentId))?.getString("lead") ?: ""
        }
        else {
            componentLead = ""
        }
        formUserField.setFormValue(componentLead)
    }
}

Now instead of using a class name, enter the full path to this file. You should get the same result. The file will be compiled when you click Update, if there are any compilation errors they will be displayed. The class is then cached, should you change this file you will need to return to this screen and click Update again (or you could restart jira).

Make a field read-only except for a certain role

Now we'll make the "Environment" field writable only if the user is in the project administrator role (for no particular reason).

Add the Environment field to your behaviour, and set it to be read-only. Now, add a condition to this rule. Click the Add Condition link, and choose the Except radio button, then select the Administrators from the Project Role dropdown. The behaviour should now look like this:

So to translate this, the Environment field will be read-only, except when the current user is in the project administrators role for this project.

The conditions work like this. If any of the When conditions are true, the field behaviour will apply. If there are except conditions, and if any of those are true, the behaviour will not apply.

It's possible to add the same field twice to a behaviour. In fact, to continue this example, if you wanted the Environmenet to be mandatory for project admins, and read-only for everyone else, you would have to add it twice (although you might be better using a script instead).

Make a field writable only if a certain value is set in another field

We'll make the Sponsor field writable only if the component "Component 1" is set.

Note that Sponsor is set to read-only, so that when the isse loads it's originally read-only, and is then changed by the validator on the Component/s field.

Require a Comment when the state is Reopened

Conditions can also be set based on actions or states. If you want to require a comment when the state changes to say Reopened, you can put a condition based on that status, rather than specifying all actions that lead to that state.

The user will be required to enter a comment for any transition which leads to the state Reopened, which is the Reopen action from the Closed and Resolved states in the default jira workflow. Note that this does not require a comment for an edit action when the state is Reopened, but it would for a transition that does not change the state, but whose result is Reopened.

Creating conditions based on states and actions is a little complex. Before setting any conditions you should set a "guide workflow". This simply allows the plugin to show you workflow elements from this plugin to choose from. If you later change the workflow for your project, it will continue to work, although if IDs have changed these will need to be adjusted, as, internally, only references to status and action IDs are stored, not names.

Result:

Modify field descriptions

You can modify field descriptions on-the-fly, possibly to reflect changes in requiredness. Example, on changing the priority to Blocker, the Description help text changes:

To do this you put a validator on for example, "Priority", with the following code:

public void setEnvironmentWhenHighPri () {
    FormField formField = getFieldById("priority")
    FormField descField = getFieldById("description")

    if (formField.getFormValue() == "1") { // Blocker priority
        descField.setHelpText("<div class=\"warningBox\">Please explain why priority is Blocker.</div>")
    }
    else {
        descField.setHelpText("")
    }
}

Further Miscellaneous Examples

Miscellaneous Behaviours Examples.

Troubleshooting

Missing groovy jar

On startup you get error like this:

com.atlassian.plugin.PluginParseException: Error retrieving dependency of class: com.onresolve.jira.groovy.BehaviourManagerImpl. 
	Missing class: groovy/lang/GroovyObject
        at com.atlassian.plugin.descriptors.AbstractModuleDescriptor.init(AbstractModuleDescriptor.java:71)
        at com.atlassian.jira.plugin.component.ComponentModuleDescriptor.init(ComponentModuleDescriptor.java:22)

You didn't copy the groovy-1.5.x jar, see the installation instructions. Add in this jar, restart jira, then enable the Behaviour plugin - as the system will probably have disabled it.

Nothing happens at all

Enable logging (see below) and check the logs.

Limitations

Javascript-based

This relies on client-side javascript. In most environments users are free to disable javascript in their browser, so no good if security is critical. However, my use case is generally to prompt the user that they should be entering another field depending on some condition, so it's generally good enough for me - no worse off than if you didn't use this anyway..
If you've made a field read-only, you can always look at the history to see if your rules have been subverted.

However, one of the intentions of this plugin is to provide a more structured way for customisation than enter javascript in a field description, so you're no worse off than if you had used that method.

Bulk Edit

No support for bulk edits, at the moment. This could be added, however, all issues part of the bulk edit would need to have the same behaviour associated for it to be doable.

Alpha

There are bugs (please let me know), and this is short of real-world production testing.

Latency

The field behaviours are retrieved from the server after the form has loaded in the browser. In my environment this takes approximately 80 ms so is not noticeable by humans. Over the public internet this may be a lot worse, and so the delay in the styling being applied may be appreciable for the users.

Remote API

Due to limitation 1, i.e. JavaScript based, the behaviours are not enforced when using the remote API.

Getting help

If you have any problems, please include in your bug report:

1. server logs. You can switch these on by using the enable logging link from the Behaviours page. To do so permanently, include these lines in your log4j.properties file:

   log4j.category.com.onresolve.jira.groovy = DEBUG, console, filelog
   log4j.additivity.com.onresolve.jira.groovy = false
   

2. For the problematic behaviour, click Edit, and include the XML snippet you see there.
3. Description of any custom field types involved, eg their type.

Releases

Fixed in 0.2.7

• Handles manufactured URLs that specify invalid project/issue types.
• Handles hiding and showing for checkboxes and radio buttons.
• Making fields hidden is part of the UI, not just the API.

Fixed in 0.2.6

New in 0.2.5

Internationalisation. Only the strings that users might see are able to be localised at this time. To create a new translation add a locale-specific file at com.onresolve.jira.groovy.clientval.properties. There is a French one in the source package (and English). If you write one please provide to me... thanks.

Comments Please add any comments to the original page here: Behaviours Plugin.