Deskzilla application allows users to customize the bugs workflow by defining a set of actions which can be applied to a bug or a number of bugs. The actions (for example, Resolve As, Reassign, Close) are defined in the XML file and can be accessed through the Workflow drop-down menu on the Bugs Toolbar.



Below is the explanation of the XML file structure and tags used to define new workflow actions, which will allow you to create new actions and modify the existing ones.

Default Workflow

By default, workflow actions are pre-configured for the standard Bugzilla workflow. Starting with Bugzilla version 3.2, Bugzilla administrator can customize statuses and workflow in Bugzilla, and so you might need to change the definition of the workflow in workflow.xml accordingly.

Even if you don't change workflow.xml, you still will be able to change status for a bug using Edit Bug dialog. However, workflow actions are useful to make bulk changes and to change several fields at once.

Actions

The action tag is used to define the action and its preconditions.

"Sample action"


<action>
  <name>Resolve As</name>
  <condition>Open</condition>
  <!-- Or, instead of condition tag: <filter>status in (UNCONFIRMED NEW ASSIGNED REOPENED)</filter> -->
  <set>
    <!-- action script -->
  </set>
</action>
CODE

It consists of three mandatory sub-elements:

  • The name tag, which defines the name of the action shown in the UI components (for example, Workflow combo box).
  • Action applicability condition, which defines which conditions a bug must meet to be eligible for the action. Action applicability can be defined either by referring to the condition defined earlier or by specifying a filter statement using the filter tag and the same syntax as is used for the condition definition.
  • The set tag, which defines the action script which runs when the action is applied. The script may contain both defined actions (for example, change the status value to Closed for the Close action) and actions, which require user input (for example, get the user comment when the bug status is changed).

Optionally an action may contain the windowId child tag, which defines the window identifier used to refer to the visual properties of the action window (for example, size, position, etc). This identifier can be used to apply one window configuration for several actions. If not specified the action name is used to generate the identifier.

Below is the explanation of the action script syntax and tags.

Conditions


Bugs must meet specific conditions to be eligible for the action. These conditions are defined outside or inside the action tags using the condition tag and then used in the action element.

"Sample condition"


<condition>
  <name>Open</name>
  <filter>status in (UNCONFIRMED NEW ASSIGNED REOPENED)</filter>
</condition>
CODE

The Condition element has two child tags, both of which are mandatory:

  • The name tag defines the name of the condition by which it can be referred to later.
  • The filter tag defines the condition itself. The syntax is same as in the Query Builder.

The Workflow.xml file uses the same syntax as the Query Builder for conditions definition, so the statements can be first created in the Query Builder and then copied to the XML file. To do that, open Query Builder, create the required filter, then right-click on the condition in Filter: section in the Query Builder and select Copy. Then paste the text from the clipboard into the <filter> tag.

Action Script

Action script is provided in the set tags and defines a number of changes that are made to the bug as a result of the action (the action that defines no changes does not make sense, but is valid). Each script element defines which field of the bug is altered and how.

Below is the description of tags used to define the fields changes.

value

The value tag assigns the specified value to the field defined in the name tag.

"Sample modification"


<attribute>
  <name>status</name>
  <value>RESOLVED</value>
</attribute>
CODE

This tag is applicable for enumeration fields only (for example, status or assignee). The tag content is the textual representation of the desired value.

When the action is selected from the Workflow combo box the modified field is shown to user in the Action window with its new value and in the read-only mode.

askAddTextElement


The tag adds a text value and is shown as the text box in the Action window.

"Add comment"


<attribute>
  <name>comments</name>
  <askAddTextElement>$(bz.form.label.comment!mnemonic=o):</askAddTextElement>
  <checkbox>$(bz.form.label.privateComment!mnemonic=p)</checkbox>
</attribute>
CODE

This tag can only be used to add comments to a bug and should be used as shown in the example.
Content of askAddTextElement defines the text box label. Content of checkbox defines the label shown next to the "private comment" checkbox, which defines if the comment is visible to other users. Content of both tags can be filled with any text.

askAddNotEmptyTextElement

This tag is the same as askAddTextElement, but makes the comment mandatory. The action cannot be completed unless the comment is specified.

askReference


This tag prompts a user to select a single enumeration value. It is shown in the Action window as a combo box populated with the possible field values with the editing option disabled.

"Sample combobox"


<attribute>
  <name>resolution</name>
  <askReference>$(bz.field.Resolution!mnemonic=r):</askReference>
  <exclude>N/A</exclude>
  <exclude>DUPLICATE</exclude>
</attribute>
CODE

The content of askReference specifies the label text.

This element supports additional exclude tags which remove the specified values from the values list.

askEditableReference

This tag works as the askReference tag, but allows user to type in new values and is shown as a standard combo box in the Action window where a user can either select an existing value or type in a new value. The exclude tags are not supported for this element.

askString

This tag prompts a user to change the value of the text field when the action is performed by specifying the new value in the text box.

"Sample change text field"


<attribute>
  <name>duplicate_of</name>
  <askString>$(bz.field.DuplicateOf!mnemonic=d):</askString>
</attribute>
CODE

Available Attributes

Here's the list of attributes that can be used in workflow.xml:

Attribute ID (use in <name>)

Available actions

product

value,askReference

component

value,askReference

version

value,askReference

milestone

value,askReference

platform

value,askReference

operating_system

value,askReference

priority

value,askReference

severity

value,askReference

resolution

value,askReference

status

value,askReference

assigned_to

value,askReference,askEditableReference

qa_contact

value,askReference,askEditableReference

reporter

value,askReference,askEditableReference

id

cc

comments

askAddTextElement, askAddNotEmptyTextElement

attachments

summary

askString

status_whiteboard

alias

askString

url

askString

keywords

modification_timestamp

creation_timestamp

blocks

blocked_by

duplicate_of

askString

Deadline

estimated_time

actual_time

remaining_time

groups

seeAlso