Custom Workflows plug-in 2.0.9
This plug-in provides a great functionality for those who is familiar with the Ruby language. It allows to customize workflow by defining own rules for issues processing. It's possible:
- To change issue properties if some conditions are met.
- To create new issues programmatically, if the conditions are met (for example you can create an issue in another project if the status of source issue is changed to specific value).
- To raise custom errors which will be displayed to the user, if he does something wrong.
- To do anything that conforms to your needs.
Supported observable objects:
- Attachment
- Group
- Issue
- Issue relations
- Time entry
- User
- Version
- Wiki
- <Shared code>
<Shared code>
- a special type for workflows that are running before all other workflows and can provide libraries of
additional functions or classes.
Thanks to
The initial development was supported by DOM Digital Online Media GmbH. The present development is supported by Kontron
Getting help
Create an issue if you want to propose a feature or report a bug:
https://github.com/anteo/redmine_custom_workflows/issues
Check Wiki for examples and programming hints:
https://github.com/anteo/redmine_custom_workflows/wiki
Check this repo with some tested in work custom workflows:
https://github.com/VoronyukM/custom-workwlows
Installation
From a ZIP file:
- Download the latest version of the plugin.
- Unzip it to /plugins.
From the Git repository:
- Clone the repository:
cd redmine/plugins
git clone https://github.com/anteo/redmine_custom_workflows.git
After download:
- Run migrations and restart the application:
cd redmine
bundle install
RAILS_ENV=production bundle exec rake redmine:plugins:migrate NAME=redmine_custom_workflows
systemctl restart apache2
Configuration
First, you need to define your own custom workflow(s). We already included one, called "Duration/Done Ratio/Status correlation". You'll find it after installing the plug-in. It demonstrates some possibilities of the plug-in.
Go to the Administration section, then select Custom workflows. A list of defined workflows will appear. Here you can create a new workflow, update, reorder or delete the existing workflows. The order of workflows specifies the order in which the workflow scripts will be executed.
Then click the Create a custom workflow button. Enter a short name and full description. Below you will see two text areas. Fill one or both text areas with Ruby-language scripts that will be executed before and after saving the issue (on before_save and after_save callbacks respectively).
Both scripts are executed in the context of the issue. So, access properties and methods of the issue directly (or
through keyword self
). You can also raise exceptions by raising RedmineCustomWorkflows::Errors::WorkflowError
exception.
If you change some properties of the issue before saving it, it will be revalidated then and additional validation errors
can appear.
E.g.:
raise RedmineCustomWorkflows::Errors::WorkflowError, 'Your message'
You can also display an info/warning/error message to the user using an observed object property custom_workflow_messages
.
E.g.:
self.custom_workflow_messages[:notice] = 'Custom workflow info'
self.custom_workflow_messages[:warning] = 'Custom workflow warning'
self.custom_workflow_messages[:error] = 'Custom workflow error'
Some environmental variables are available in observable objects.
E.g.:
self.custom_workflow_env[:remote_ip]
Enabling custom workflows for projects
After you defined your custom workflow(s), you need to enable it for particular project(s). (This is valid for project related observable objects.) There are two ways of doing this.
- While editing existing or creating a new custom workflow;
- In the project's settings (if the user has appropriate permission). Open Project settings. Go to Custom workflows tab of the project's settings and enable those workflows you need for this project.
Now go to the Issues and test it.
Examples
Duration/Done Ratio/Status correlation example
Fill the "before save" script with:
if done_ratio_changed?
if (done_ratio == 100) && (status_id == 2)
self.status_id = 3
elsif [1,3,4].include?(status_id) && (done_ratio < 100)
self.status_id = 2
end
end
if status_id_changed?
if (status_id == 2)
self.start_date ||= Time.now
end
if (status_id == 3)
self.done_ratio = 100
self.start_date ||= created_on
self.due_date ||= Time.now
end
end
Example of creating subtask if the issue's status has changed
Fill the "before save" script with:
@need_create = status_id_changed? && !new_record?
Fill the "after save" script with:
if @need_create
issue = Issue.new(
author: User.current,
project: project,
tracker: tracker,
assigned_to: author,
parent_issue_id: id,
subject: 'Subtask',
description: 'Description')
issue.save!
end
Do not forget to check whether the issue is just created. Here, we create a new issue and newly created issue will also be passed to this script on save event. So, without a check, it will create another sub-issue. And so on. Thus, it will fall into infinite loop.
Compatibility
This plug-in is compatible with Redmine 4.1.x., 4.2.x. and 5.0.x.