Configure Work Item Workflow

Note:

This topic covers workflow configuration for Work Items. There is a separate workflow configuration for Documents.

Workflow controls a development process to ensure that no process steps are missed or skipped over. Workflows for Work Items in Polarion can be mapped to the steps in almost any process, whether it's defined by some methodology (Scrum, V-Model, etc.), completely by customer, or a hybrid of both.

Warning:

Workflow definitions and status enumeration work in tandem.

Type-specific and generic enumerations should not be mixed together.

(This also applies to Project and Global Definitions.)

A workflow consists of a set of named statuses and status transitions, transition conditions and dependencies that a Work Item passes through in its life cycle. For example, consider the following set of status definitions:

  1. Open (which might be the initial status for new items)

  2. Accepted

  3. In Progress

  4. Resolved

  5. Closed

  6. Reopened

If a user changes the Work Item's status from Open to In Progress, or Open to Resolved, this invokes an action, which triggers a status transition, which is automatically tracked in the Work Item's history. Actions may trigger underlying system functions — creating a linked Work Item, or clearing some field's value, for example. Workflow actions can be conditional. That is, some condition must be checked and fulfilled before the user can perform the action.

You can customize Work Item workflows and transitions in several scopes: globally (for all projects), project-specific for individual Projects, and/or Type-specific, which applies only to a specific type of Work Item in a project. (Type-specific can be configured both globally and in projects.) Polarion looks for the most specific workflow definition first and proceeds toward the most generic in the following search sequence:

  1. Project-specific and Work Item type-specific

  2. Global and Work Item type-specific

  3. Project-specific

  4. Global

Configuration process summary

Generally, you perform the following operations in the order listed:

  1. Configure Work Item custom fields: define any that are needed for Work Items in the scope. If your workflow will not have any functions and conditions that reference Work Item custom fields, you can skip this operation.

  2. Configure Statuses: Determine the statuses a Work Item can have at various stages of its lifecycle — Draft, In Progress, and Implemented, for example. Then create a Status definition for each one in the Statuses section of the Workflow Designer.

  3. Configure Actions: Determine what actions are needed to transition a Work Item from one status to another throughout your development process, give them brief but intuitive names, and create an Action definition for each one in the Actions section of the Workflow Designer.

    Action names appear in the drop-down list of a Document's Status field in the Document Properties sidebar. The name indicates to the user what transition takes place as a result of invoking the Action. For example, an Action named Mark as Implemented can be defined for the transition of a Work Item from the status In Progress to the status Implemented.

  4. Configure Functions and Conditions: Optional. You can specify one or more programmatic functions that the system should run when an Action is invoked by users, and specify conditions that must be satisfied before in order for the specified functions to run.

  5. Configure Transitions: Now you can specify how the Work Item transitions from one status to another in the Transitions section of the Workflow Designer page (see Using the Transition Matrix).

Workflow Designer

A graphical Workflow Designer tool is provided in the web interface. It presents a visualization of workflow configurations and related enumerations such as status definitions. The Workflow Designer is available in all of the available scopes.

Access the Workflow Designer for Work Items

To access the Workflow Designer tool, you need to go into Administration for the scope you want to customize (global or project).

Access for global configurations

If you want to configure Global workflows, select Repository in the Open Project or Project Group dialog box. Keep in mind that changes will apply not only to new projects, but to all existing projects unless a project-scope workflow configuration has been defined for them individually.

Access for project configurations

To configure workflow for a specific project, select the project in the Open Project or Project Group dialog box after entering Administration.

The Workflow topic

Once you are in the desired Administration scope, go to the Navigation pane, expand the Work Items node, and select Workflow. The Work Item Workflow page opens and displays a table of existing and available workflow configurations.

Workflow configurations table shows existing configurations, and provides access to the Workflow Designer.

The first row of the table is labeled -- All Types --. This is where you can define a default workflow for all Work Item types in the scope that do not have an overriding type-specific workflow configuration defined for them. The Type column indicates whether or not a type-specific workflow is configured for that type in the current scope. If a cell in that column is empty, it means no workflow is configured for the Work Item type shown on that row, and the All Types workflow will be used.

Using the Workflow Designer

Please refer to the following figure while reading the information in this section.

Workflow Designer for a Work Item

The Transitions section at the top of the Workflow Designer is a matrix of workflow transitions between Work Item statuses. The direction is from row to columns. For example, the value where the row Open intersects the column Resolved represents the transition from the Open status to the Resolved status. At each intersection where a transition is possible, there is a list of Actions. The Actions are defined in the Actions section of the designer. When end users want to transition a Work Item to a different status, they select the appropriate Action in the Status field of the item. For more information, see Using the Transition Matrix.

The Statuses section is an enumeration editor for defining workflow status definitions for the scope in which you are working.

Below the Statuses section is the Actions section. This is an editor for transition Action definitions. Action names that appear in the drop-down lists in the Transitions matrix are defined here. The Required roles, Required fields, and Cleared fields columns are comma-separated lists of role IDs and field IDs. Only simple field types can be specified in these columns, not collection or structure types.

The Initial column in each Action row enables you to specify one Action as the first action that must occur in order for the Work Item to enter the status defined as the initial status when a new Work Item of the applicable type(s) is created. (Defining an Initial status is required.) Specifying an initial action is mainly important if some fields must be marked as required, and/or some field(s) must have value(s) cleared, and/or some workflow function must be run before the defined initial status (Draft, for example) is applied to a new Work Item. If no initial action is specified, then no fields are changed and no workflow function runs when a new item is created, even if the Action has these defined. Field changes and workflow functions only take place when the Action is invoked manually by changing the Work Item's status.

The Conditions and Functions columns in each Action row display indicate if any workflow conditions and functions are configured for the action. (Indicator is a button labeled with the number of conditions or functions currently configured. Clicking the button opens the respective dialog box where the conditions/functions are specified.)

The Actions column in this section of the designer contains two icons. The icon invokes the Action Details dialog box, which provides tools for defining workflow functions and conditions to be run when the Action is invoked.

Required roles

In the Required Roles field you can enter a comma-separated list of roles that a user has to have in order to be able to invoke the Action. These roles may be either the project or global user roles project_admin or admin, or two special system roles:

  • workitem.assignee - only assignee of the Work Item has this role

  • workitem.author - only author of the Work Item has this role

Valid role names are all global and project roles (admin, user, for example) in the same form as in User Management - Roles. There is no need to prefix them with a project ID, because they are always resolved against a given Work Item's project. The only permitted logical role is workitem.assignee. Roles have OR logic - one match is enough for the condition to succeed.

Available conditions and functions

For a listing of the available conditions for this configuration and functions that can be specified, see Workflow Conditions and Functions.

Action Names

It can be helpful to your end users if you specify the Name property of an action as a verb or verb phrase. For example, suppose you have w statuses: Implemented and Verified, and you want to define Actions for the transition from some other status(es) to these statuses.

For transitions to the Implemented status, a good choice for the Action name would be Mark as Implemented as opposed to just Implemented. The same idea applies to the Verified status. The transition Action name might be Verify Implementation or Mark as Verified.

Using the Transitions Matrix

When defining transitions using the Workflow Designer's Transitions matrix, it's important to keep two things in mind:

  • You are defining what transitions are allowed between any 2 statuses

  • Therefore, you don't need to specify an action for every transition, just those transitions you want to allow to occur between two statuses

Consider an example of a workflow for a Requirement. Assume that, among others, the statuses Draft and Awaiting Review are defined.

Allow transition

No transition to same status.

No transition

Actions

Allow and disallow transition to take place between 2 Work Item statuses

It makes sense to allow transition from the Draft status to the Awaiting Review status, so at the intersection of these two, you specify the Send to Review action (which has already been defined in Actions).

It would not make sense for the process to allow transition directly from the Draft status to the Reviewed status (assume the team process does not allow this), so no action is specified where Draft intersects Reviewed in the matrix.

For some status, you may want to have more than one possible transition. For example, suppose you have the status definitions Implemented, Verified, and Needs Changes. For Work Items having the Implemented status, let's say there are two possibilities in the process: QA can pass the item and give it the Verified status, or QA can reject the item and send it back for changes, giving it the Needs Changes status. The workflow can be configured to support this process but allowing 2 transitions on the Implemented status.

  • Transition from Implemented status to Verified status via the Mark as Verified action.

  • Transition from Implemented status to Needs Changes status via the Reopen action.

Where it makes sense for your process, enable more than one transition for a status

Multiple transitions allowed.

Actions

Workflow for Approvals

Polarion's standard project templates are preconfigured to support a formal approval process. Even if the overall process as configured meets your needs, there may still be some things you want to adjust in the approvals workflow. For example, the default configuration includes a workflow function on some Actions that automatically adds users to the Approving Users table of the Actions field of Work Items, resulting in notifications to those users. However, the users so added by the default settings may not be users you actually want, or there might be other users you want included that are not.

Basically, for each Work Item type you should review the Actions that relate to the approval process in the Workflow Designer. For example, for a requirement, click Editfor the Send to approve action. By default, this Action invokes a workflow function AddDefaultApprovals, which automatically adds some users to the Approvals field of Work Items when the Send to approve action is invoked.

By default, this function uses the approvals.roles parameter with a single value project_approver. This means that when the Action is invoked, all users whose user profile includes the project_approver role are added to Approving Users table in the item's Approvals field. If this is not what you want, you can either change the role, or add more roles, or use the approvals.users parameter instead. (For more information, see Workflow Functions.)

Another Action to review might be Back to Draft. By default, this Action invokes the workflow function ResetApprovalStatus. Perhaps you want to invoke some other function after that — SetDate, for example.

Require Signatures for Workflow Actions

You can require end users to electronically sign when invoking a workflow action to transition to a new status.

In the Actions section of the Workflow Designer, each action has a check box option, Requires Signature. Selecting this option means that a user invoking the Action is requested to provide an electronic signature, and the workflow transition cannot take place until a signature has been logged.

To configure this functionality, you need to edit the following properties in the system properties file polarion.properties (follow link for location):

  • secure.approvals: The value is a Boolean true or false (the default value is false). If set to true, then when an end user performs an approval or disapproval Action, the password dialog box is presented as described above.

    Example: secure.approvals=true or secure.approvals=false

  • secure.dialog.title: The value of this property is a string of characters. The string appears as the title of the password dialog box presented when an end user invokes one of the configured secure workflow actions. You only need to set this property if you want to override the system default title for the dialog box (shown in the example below).

    Example: secure.dialog.title=Enter Password

  • secure.dialog.message: The value of this property is a string of characters. The string appears as a message in the password dialog box presented when an end user invokes one of the configured secure workflow actions. You only need to set this property if you want to override the system default message for the dialog box (shown in the example below).

    Example: secure.dialog.message=By entering my password I signify that I have reviewed and approved the content of this individual Work Item, or group of Work Items, just as I would have by applying my own handwritten signature.

    Tip:

    For security, it is highly recommended to use the https protocol for access to Polarion when your system is configured to use electronic signatures.

Enable Electronic Signatures Support

You can enable secure approvals that require electronic signatures to satisfy compliance or governance requirements.

Use the following system properties in polarion.properties:

  • secure.approvals=true: Enables electronic signatures for approvals.

  • secure.approvals.comment=put your custom comment text here: The custom text is used as the text of a new comment created when a user enters a password to confirm a secure approval.

    An example value would be: Item was e-signed.

  • secure.approvals.comment.onBehalfOf=put your custom comment text here: Similar to the above property, but also supports a single user who can confirm a secure approval on behalf of another user.

    Supports the following variables:

    • $user

      Inserts the name of the current user.

    • $otheruser

      Inserts the name of the user that the current user is doing the approval on behalf of.

    • $verdict

      Inserts the approval verdict.

    • $img

      Adds an approval verdict image.

    • An example value would be: Approval verdict: $img $verdict (by $user on behalf of $otheruser).

  • secure.approvals.comment.text=put your custom comment text here: Displays the state of the approval.

    Supports the following variables:

    • $img

    • $verdict

    • $user

    • An example value would be: $img $verdict by $user

Localize the Approval messages:

You can override the signature approval messages for the below properties directly in the polarion.properties file.

You don't have to dig through and change the localization messages file.

(For example, the C:\Polarion\polarion\plugins\com.polarion.psvn.translations.en_3.18.2\META-INF\messages_en.properties file for English.)

Tip:

Non-ASCII languages should be converted to Unicode.

For example 祝你有美好的一天 should be written as: 祝你有美好的一天

  1. Shutdown the Polarion server.

  2. Open the polarion.properties file in your favorite text editor.

    (Default location: C:\Polarion\polarion\configuration.)

  3. Uncomment the secure.approvals=true property.

    This enables secure approval comments using the default (English) messages.

    (If it's not present in the file, add it on a new line.)

  4. Add the following properties with your custom messages .

    (Customize the default messages after the = character.)

    • secure.approvals.comment=Your custom message

      Overrides the dialog.secure.comment=Item was e-signed value in the localization messages file.

    • secure.approvals.comment.text=Your custom message

      Overrides the dialog.secure.comment.text=Approval verdict: $img {1} value in the localization messages file.

      (Where {1} is the verdict text.)

    • secure.approvals.comment.onBehalfOf=Your custom message

      Overrides the dialog.secure.comment.onBehalfOf=Approval verdict: $img {1} (on behalf of {2}) value in the localization messages file.

      (Where {1} is verdict text and {2} is the user that the approval was done on behalf of.)

  5. Save your changes and close the polarion.properties file.

  6. Start the Polarion server.