Team process preconditions for Engineering Workflow Management source control operations

Your team can specify various conditions that must be met before certain Engineering Workflow Management source control operations are allowed to complete. The Team Adviser view provides more information about these preconditions and how to meet them.

About this task

Engineering Workflow Management source control provides several preconditions that you can use when customizing processes for your team.

Where possible, use server-side approvals instead of client-side approvals. Client-side approvals are not guaranteed to run in all situations, and on all clients. The web client does not run any client-side advisors.

For information about how to set a precondition in the Eclipse client, see Modifying operation behavior (preconditions and follow-up actions) in project areas and team areas.

For information about how to set a precondition in the web client, see Setting preconditions and follow-up actions.
Table 1. Client-side preconditions
Operation Precondition name Precondition action Available in clients
Operation: Deliver (client): Runs before delivery of baselines, change sets, or on a component replacement. Affects all components in streams that are owned by the process area. The Deliver (client) precondition runs on the client before the server is contacted about the delivery. This operation is appropriate for preconditions that require client state to run, such as detecting compilation errors, or whether the most recent JUnits completed. Check language definition association Deliver operations fail if a file does not have an associated language definition. For this precondition, you can specify file extensions to be exempt from checking for associated language definitions. z/OS®, IBM i
Prevent unintended ignored changes Deliver operations fail if you set a file to be ignored after another user sets the same file to be ignored. z/OS
Prohibit non-externalized Java™ strings Deliver operations fail on Java files that have non-internationalized strings. Eclipse
Prohibit unused Java imports Deliver operations fail on Java files that have unused imports. Eclipse
Prohibit workspace errors Deliver operations fail if there are compilation errors in the files in the Eclipse workspace or open Visual Studio solution. Eclipse, Visual Studio
Require JUnit test run Requires a JUnit test to run (successfully) in the Eclipse workspace. Eclipse
Require static analysis run Require a static analysis tool to run on Visual Studio projects before a deliver operation. Visual Studio
Require unit test run Require either MSTest or NUnit tests to be run on projects before a deliver operation. Visual Studio
Require work item approval Change sets that require approvals can be delivered. Eclipse, CLI, Visual Studio
Require work items and comments Change sets that have work items and comments can be delivered.
Note: This precondition does not apply to change sets that are delivered as part of a baseline. Use the Operation: Deliver (server) version of this precondition to apply to change sets that are delivered as part of a baseline.
Eclipse, CLI, Visual Studio
Table 2. Server-side preconditions
Operation Precondition name Precondition action
Operation: Check-in (server): Runs before check-in of resources. Affects components that are owned by the process area. An extension point for check-in operations is also available so that you can write your own preconditions. The following server-side preconditions are available for source control check-in operations. You can set them in either the Eclipse client or web client. Restrict File Size This precondition prevents users from checking in files that exceed a specified size limit.
Restrict Check-in of Resources with the Same Name This precondition prevents users from checking in a resource if another resource in the same location has the same name, even when the capitalization differs. Because Windows systems ignore capitalization and Linux systems do not, this precondition can help avoid conflicts in projects where developers use both platforms.
Restrict Check-in Based on Specified MIME Types and Encodings This precondition prevents users from checking in files if the MIME type or encoding are not permitted for the process area.
Operation: Deliver (server): Runs before delivery of baselines, change sets, or on a component replacement. Affects all components in streams that are owned by the process area. The Deliver (server) operation runs on the server before change sets are added or removed from a component. The operation is run on the set of change sets that are being added to (or removed from) a component. Restrict Change Set Size This precondition ensures that the number of changes in each change set does not exceed the value specified when configuring the precondition.
Require Work item Approval

Verifies that change sets that are linked to a work item have a minimum number of approvals. The approvals are specified by role and must be complete at the time of delivery.

The precondition ensures that a minimum number of approvals are received before the associated change sets can be delivered to a stream.

Note: To prevent users from linking new change sets to work items that already have approvals, enable the Prevent Linking to Approved Work Items precondition.
Require Work Item and Comments

Verifies that change sets have work item links and/or comments. The precondition can be configured to require change sets to have a comment or a work item/change request (OSLC link).

If a work item is required, the owner and target iteration can be verified. Although it makes sense to constrain the work item owner and iteration in development streams, this requirement is not true of integration streams, since:

  • Change sets are often delivered by release engineers, so the owner identity check blocks the delivery.
  • If change sets were delivered to the development stream in previous iterations, then associated work items were likely targeted to those iterations.
Require Streams or Workspaces to be Synchronized Before Delivery

Ensures that you do not have incoming changes at the time of delivery. You can limit the scope of this precondition to specific components.

This precondition ensures to allow delivery only when the source stream or workspace is synchronized with the target stream or workspace. It also ensures that you have all the changes in a stream or workspace before you complete a delivery operation and you can test with the full stream content. This scenario works well in IDEs where source is built automatically after an accept operation.

Restrict Change Set Delivery to Components in a Stream

Limits the roles that are allowed to deliver change sets to components in a specific stream. This restriction prevents teams that do not own a component from delivering changes to it. You can specify which repository workspaces or streams can deliver changes to a component.

When multiple teams are flowing into a single integration stream, it is useful to limit delivery privileges to the team that owns each component, rather than allow any developer to deliver to any component.

Note: Unlike other preconditions, this precondition operates on all roles, so only assign it to the Everyone role.
Require Work Items to Match Query

When delivering change sets, ensures that associated work items match a query.

This precondition verifies that the work items associated with each change set are listed in a work item query result. The precondition applies to all streams that are owned by the project/team area for which that precondition is set.

The query allows complex validation of a work item's fields, including custom attributes. Options on the precondition allow the process author to set whether each change set must have at least one matching work item or whether every work item must match.

Work item queries can match only work items in their process area. The precondition allows the process author to control how work items from other process areas are handled: either allowed or denied.

Operation: Deliver Phase 2 (server): Runs before the delivery of baselines and change sets or on a component replacement. Affects all components in streams that are owned by the process area. Check Ignore Changes Permissions Changes that are marked to be ignored by a dependency build must have permission to do so.
Restrict Changes by Item Name

Prevents changes to files, folders, or symbolic links that are based on their name. The precondition can be scoped to specific components in a stream.

Items can be matched with operators (* indicating zero or more characters, or ? indicating exactly one character) or Java regular expressions. Depending on the precondition's configuration, matching items are either allowed (all items in a change set must match the pattern) or blocked (no items in a change set can match the pattern).

Regular expressions are matched in the manner of a search: the regex matches a substring of the item name. To require the entire name to match, use a caret (^) and dollar sign ($) to anchor the regex to the start and end of the string.

Note: Changes to folders and symbolic links are not considered hierarchically, so preventing a change to all items named src does not prevent delivery of a change set modifying a file in the src folder.
Restrict Changes to Items

Limit the roles that are permitted to change specific files. The precondition can either operate in a mode where the changes to the selected files are allowed or denied.

Restricting changes to files allows teams that operate under a lock-down mode to prevent changes to portions of their streams at specific times. Process authors can use this precondition to keep plug-in dependencies stable by matching MANIFEST.MF files or limiting string changes after a string freeze.

Required Content

Ensures that files contain a specific string on delivery. Only files with names that are matching a specific pattern are checked.

On teams where ownership must be asserted within source code, this precondition allows process authors to force every source file to contain a copyright string.

Operation: Save Change Set Links and Comments (server): Runs before a change set is assigned a new comment or has a work item link added/removed. Affects change sets in components that are owned by the process area. Prevent Links by Approvers

Ensures that change set authors do not approve their own work items.

This precondition prevents a change set from being linked to a work item with an approver who is also the change set author. The Require Disinterested Approvers preconditions on work item save prevents an approver from being added to a work item already linked to change sets with the same author. Use these two preconditions together.

Restrict Associating to Active Change Sets

Stops incomplete change sets from being associated with work items.

This precondition is useful in processes that require approvals because active change sets can be modified after the approval is granted.

Prevent Linking to Approved Work Items

Ensures that change sets cannot be linked to work items that already have approvals. This requirement prevents users from using an approved work item to deliver more change sets.

Teams that want to enforce strict process on work items (using Require Work Item Approval, for example) can use this precondition to ensure that all change sets are individually approved before flowing into a stream.

By default, the precondition blocks linking to any work item with approvals, regardless of the approval state. To allow change sets to be linked to work items in specific approval states, add them through the Allowed Link States configuration.

Restrict Associating to Closed Work Items

Prevents change set links from being added to or removed from closed work items.

Teams with a strict work item lifecycle can use this precondition to stop change sets from being associated or dissociated with a work item whose work is complete.

You can also use this precondition to add a comment to a work item when links are added/removed and to ensure that the project area of a stream contains the user who is delivering the changes.

Operation: Save Stream (server): Controls permissions for stream operations when changes are made to the underlying structure of a stream. Prevent Adding Component to Stream When Component and Stream Owners are Different. Prevents adding a component to a stream when component and stream owners are different.
Prevent Adding User Owned Component Prevents adding user-owned components.
Restrict Stream Visibility to be set to Public Prevents setting the stream visibility to Public.
Ensure Snapshot Names are Unique Ensure that the snapshots associated with a stream have a unique name. Snapshots cannot be created for the stream, moved to the stream or renamed on the stream if a snapshot with the same name is already associated with the stream.

When a precondition prevents you from delivering a change set, the Team Adviser view opens automatically and presents an explanation of why the failure occurred, how you can fix the problem, and whether you can override the process precondition.

For more information about customizing a team process to add, remove, or modify the behavior of these and other preconditions, see Customizing the process in projects, teams, and templates.