= Custom Workflows plug-in

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 display to user, if he does something wrong;
* To do anything that conforms to your needs;

== Installation

From a ZIP file:

* Download the latest version of the plugin
* Unzip to */plugins* (Redmine 2.x) or */vendor/plugins* (Redmine 1.x) folder of Redmine

From a GIT repository:

* Clone repository with <b>git clone git://git.academ.org/redmine_custom_workflows.git plugins/redmine_custom_workflows</b> command

After download:

* Run <b>rake redmine:plugins:migrate</b> (Redmine 2.x) or <b>rake db:migrate:plugins</b> (Redmine 1.x).
* Restart Redmine.

== 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 plug-in.

Go to the *Administration* section, then select <b>Custom workflows</b>. A list of defined workflows will appear. Here you can create new workflow, update, reorder and delete existing workflows. The order of workflows specifies the order in which workflow scripts will be executed.

Then click the <b>Create a custom workflow</b> button. Enter a short name, full description and script itself. Below you will see two textareas. Fill one or both textareas by 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 <b>raise WorkflowError, "Your message"</b>. If you change some properties of the issue before saving it, it will be revalidated then and additional validation errors can appear.

== Enabling workflows for projects

After you defined your custom workflow(s), you need to enable it. Open <b>Project settings</b>. Go to the <b>Enabled modules</b>. Enable the <b>Custom workflows</b> module there and click *Save*. Then go to the <b>Custom workflows</b> tab of the project settings and enable workflow(s) you need for this project.

Now go to the *Issues* and test it.

== 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 issue is just created. Here we create the new issue and newly created issue will also be passed to this script on save. So without check, it will create another sub-issue. And etc. Thus it will fall into infinite recursion.

== Compatibility

This plug-in is compatible with Redmine 1.4.x, 2.0.x, 2.1.x

== Changelog

[0.0.2] Added ability to define after_save script along with before_save, improved logging, changed context of executing script to the issue.
[0.0.1] Initial commit