Crucible Workflow Conditions Plugin Module Tutorial
About the tutorial
The plugin created in this tutorial makes use of the workflow-condition modules. The plugin prevents a user from closing a review until at least one reviewer completes the review.
In this tutorial you will:
- Create a Fisheye/Crucible plugin
- Implement the
- Configure the workflow-condition module
- Implement simple Actions to engage user with interaction after failed transition
This tutorial teaches you how to:
- Implement the
- Render a warning or error message for the user performing the transition
- Check the condition on important transitions only.
For general information about the plugin development, see FishEye and Crucible Plugin Guide - Atlassian Developers
We encourage you to work through this tutorial. If you want to skip ahead or check your work when you are done, you can find the plugin source code on Atlassian Bitbucket. Bitbucket serves as a public Git repository containing the tutorial's code. To clone the repository, run:
The Workflow Conditions API was introduced to FishEye/Crucible in version 4.2 as an experimental API and had changed in 4.3 release. From version 4.3, FishEye/Crucible is considered as final and there are no planned changes towards it anymore.
Stage 1: Create plugin structure and run FishEye/Crucible
Follow the steps below to learn how to create your plugin structure and run FishEye/Crucible.
a) Create your plugin skeleton using the Atlassian Plugin SDK:
b) (optional) If atlas-create-fecru-plugin creates a plugin skeleton with a different version of Fisheye/Crucible than you want to use, update the properties in pom.xml
c) Run FishEye/Crucible with the skeleton plugin:
d) Go to http://localhost:3990/fecru/
e) Authenticate with the following credentials:
Stage 2: Implement Workflow Condition
In this tutorial you're going to implement the condition which prevents a user from closing a review when none of the reviewers have completed the review.
How to start
com.atlassian.crucible.workflow.WorkflowCondition SPI class.
The condition in the current state doesn't do anything useful yet. To check for some conditions during the review transition, you must implement the
validateTransition method. This method is called every time a review is being transitioned. It's up to you to verify that it's the transition type the condition should react to.
validateTransition method should return a
ValidationResult, which can be of one of the following states:
- OK - condition passes, review transition can be performed
- WARN - condition fails, warnings can be skipped and the review transition performed
- ERROR - conditions fails, review can't be transitioned without fixing validation errors
As soon as you defined the programmed condition to react only to closing a review you need to implement the condition check. For the purpose of this tutorial, the check verifies only if there's at least one reviewer who completed the review.
ValidationResult can be created using static factory methods and consists of:
- result severity → OK, WARN, ERROR
- result key → which will be presented when the transition is invoked through the REST API and it fails
- result message
- → Message which will be presented to an user once condition validation fails. Plugin developers are encouraged to write concise, short messages. Longer messages will be hidden under AUI Expander
- → REST key which will be used to construct the REST call response
- → REST message (optional) which will be used to construct the REST call response
- → Optional list of actions to allow end user to interact with your plugin
In previous step, you implemented
CompletedReviewerWorkflowCondition, which defines the behaviour of your condition. Now, lis the condition in atlassian-plugin.xml in
workflow-condition module to let FishEye/Crucible's plugin system know about it.
The class is the class of the workflow condition, and the key are unique identifiers required by the plugin system. A single plugin can define multiple
workflow-condition modules. Once the plugin module is configured, a review can't be closed it, until at least one reviewer completes it.
Invoking the transition using REST and JAVA APIs is also prohibited and will fail with an error.
Stage 3: Implement interaction with user
Workflow Condition actions
In previous steps, you wrote a workflow condition which presents simple error message to a user but doesn't allow for any user interaction. ResultMessage can also contain actions which allow for such interaction. The starting point for building any kind of action is the
com.atlassian.crucible.workflow.ResultAction interface. Crucible allows for two types of actions:
- URL action
The URL action represents a simple HTML link. It can be constructed with the
buildUrlAction method. For the purpose of this tutorial, let's include the link to a Users page in a failed condition message.
As a result of such ValidationResult, Crucible will include the link to a Users page as a part of the failure message.
- AMD module which exports an object with the onClick function
Given code will result in the following dialog:
Workflow Condition Context
reviewId→ returns the review id
hideDialog→ hides transition dialog
resolveMe→ resolves current condition on the front-end side, which results in removing it from the dialog. Note: This action will affect only the front-end side. If the problem which triggered the workflow condition is not fixed, the transition will fail again
showError→ shows error banner in the current dialog, accepts error message
hideError→ hides error banner
In the next step, we'll extend remind-handler to resolve the condition when AJAX call succeeds and show the error banner in case of an error. To do that, we'll use the context object as a handler.
With such handler, if the request succeeds, Crucible will remove given message from the list. In this particular case there was only one error message so the user is allowed to proceed.
workflowConditionContext.showError(); shows the following error banner: