Workflow global rules

This section provides information on how to enable workflow and configure the global workflow rules for Swarm.

Each global workflow rule has a mode setting, this determines how that rule is used by Swarm:

• Default mode: applies the workflow rule setting to projects and project branches that don't have an associated workflow. If a project or project branch has an associated Swarm workflow, the global rule is ignored.
• Policy mode: applies a minimum workflow rule setting to all projects and project branches. If a project or project branch has an associated workflow, the global rule is merged with the workflow rule and the most restrictive setting is used.

Configure the global workflow rules with the following configuration block in the SWARM_ROOT/data/config.php file:

<?php
    // this block should be a peer of 'p4'
    'workflow' => array(    
        'enabled' => true, // Switches the workflow feature on. Default is true
    ),
    'workflow_rules' => array(
        'on_submit'  => array(
            'with_review'    => array(
                'rule' => 'no_checking', // 'no_checking|strict'
                'mode' => 'default' // 'policy|default'
            ),
            'without_review' => array(
                'rule' => 'no_checking', // 'no_checking|auto_create|reject'
                'mode' => 'default' // 'policy|default' 
            ),
        ), 
        'end_rules' => array(
            'update' => array(
                'rule' => 'no_checking', // 'no_checking|no_revision'
                'mode' => 'default' // 'policy|default'
            ),
        ),
        'counted_votes' => array(
            'rule' => 'anyone', // 'anyone|members'
            'mode' => 'default' // 'policy|default'
        ),
        'auto_approve' => array(
            'rule' => 'never', // 'never|votes'
            'mode' => 'default' // 'policy|default'
        ),
        'group_exclusions' => array(
            'rule' => [], // group names to exclude from the workflow rules, defaults to empty
            'mode' => 'policy' // can only be set to 'policy'			
        ),
        'user_exclusions' => array(
            'rule' => [], // user names to exclude from the workflow rules, defaults to empty
            'mode' => 'policy' // can only be set to 'policy'			
        ),			
    ),

workflow

To disable the workflow feature, edit the SWARM_ROOT/data/config.php file and set the enabled configurable to false in the workflow section of the codeblock:

    'workflow' => array(
        'enabled' => false, // Switches the workflow feature on. Default is true
    ),			

The default value is true.

with_review

with_review: applied when:

• A Swarm review is committed.
• A changelist with an associated review is submitted from outside of Swarm.

• rule: choose one of the following options:
  • no_checking: the changelist review state is not checked. The changelist is committed even if its associated review is not approved. This is the default rule.
  • strict: the changelist review state is checked to see if the review is in an approved state (check performed during the change-submit trigger event). A further check is made to see if the content of the changelist is identical to the content of the approved review (check performed during the change-content trigger event).
    • Review is approved and changelist content is identical to the approved review: the changelist is submitted.
    • Review is approved and the changelist content is not identical to the approved review: the changelist submit is rejected.
    • Review is not approved: the changelist submit is rejected.
• mode: choose one of the following options:
  • default: the rule is only applied to a project or project branch that does not have an associated workflow. This is the default mode.
  • policy: the rule is applied to all projects and project branches even if there is an associated workflow.

without_review

without_review: applied when a changelist without an associated review is submitted from outside of Swarm.

• rule: choose one of the following options:
  • no_checking: the changelist is not checked, the changelist is submitted without a review. This is the default rule.
  • auto_create: the changelist is submitted and a review is created automatically for the changelist.
  • reject: the changelist submit is rejected.
• mode: choose one of the following options:
  • default: the rule is only applied to a project or project branch that does not have an associated workflow. This is the default mode.
  • policy: the rule is applied to all projects and project branches even if there is an associated workflow.

end_rules

By default, you can update the content of a review no matter what state the review is in. Reviews can be protected from content change if they are in a specified state by using the end_states configurable.

The end_states configurable sets the protected review states.

update: applied when a changelist is added to a review.

• rule: choose one of the following options:
  • no_checking: the review is not checked, the changelist is added to the review no matter what the review state is. This is the default setting.
  • no_revision: if the review is in one of the states specified in the end_state configurable (check performed during the shelve-submit, and change-submit trigger events):
    • The Add Change button is disabled for the review.
    • The changelist is rejected if it is added outside of Swarm by adding #review-nnnnn, #replace-nnnnn, or #append-nnnnn in the changelist description (nnnnn = review ID).
• mode: choose one of the following options:
  • default: the rule is only applied to a project or project branch that does not have an associated workflow. This is the default mode.
  • policy: the rule is applied to all projects and project branches even if there is an associated workflow.

counted_votes

By default, all of the up votes on a review are counted for the Minimum up votes value set on the project/branch the review is associated with. Limit the up votes that are counted to just the members of the project the review is associated with by using this rule.

counted_votes: applied when a user votes on a review.

• rule: choose one of the following options:
  • anyone: votes are counted for all reviewers on a review. This is the default setting.
  • members: only the up votes of members of the project the review is associated with are counted for the Minimum up votes set on projects/branches.
• mode: choose one of the following options:
  • default: the rule is only applied to a project or project branch that does not have an associated workflow. This is the default mode.
  • policy: the rule is applied to all projects and project branches even if there is an associated workflow.

auto_approve

By default, reviews must be manually approved. Enable automatic approval of reviews with this rule.

auto_approve: applied when a user votes on a review, a required reviewer is added to a review, or a required reviewer is made an optional reviewer on a review.

• rule: choose one of the following options:
  • never: reviews are not automatically approved. This is the default setting.
  • votes: reviews are automatically approved if:
  • There are no down votes on the review.
  • There are no moderators on the review. If a review has moderators it cannot be automatically approved.
  • All of the Required reviewers on the review have voted up.
  • The Minimum up votes on the review has been satisfied for each of the projects and branches the review spans.
  Important

  Moderators prevent the automatic approval of reviews. For more information about moderators, see Moderators.

  Tip

  After a review has been automatically approved it needs to be manually committed.

• mode: choose one of the following options:
  • default: the rule is only applied to a project or project branch that does not have an associated workflow. This is the default mode.
  • policy: the rule is applied to all projects and project branches even if there is an associated workflow.

group_exclusions

By default, all group members must follow any workflow rules that apply to changelists and reviews. Add groups to the group_exclusions configurable to enable specific groups (including any sub-groups) to ignore workflow rules across the entire depot. This applies to actions taken in the Swarm UI, the P4D command line, a P4D client, and the Swarm API.

group_exclusions:

• rule: add the name of the group that you want to exclude from the workflow rules. Multiple groups can be excluded but they must be separated by commas. Only exact matches are excluded.
• mode: the only valid selection is policy, the group can ignore all of the workflow rules across the entire depot.

user_exclusions

By default, all users must follow any workflow rules that apply to changelists and reviews. Add users to the user_exclusions configurable to enable specific users to ignore workflow rules across the entire depot. This applies to actions taken in the Swarm UI, the P4D command line, a P4D client, and the Swarm API.

user_exclusions:

• rule: add the name of the user that you want to exclude from the workflow rules. Multiple users can be excluded but they must be separated by commas. Only exact matches are excluded.
• mode: the only valid selection is policy, the user can ignore all of the workflow rules across the entire depot.