Add a workflow

Note
  • Swarm workflows can be created by any Swarm user.
  • Shared Swarm workflows can be viewed by any Swarm user.
  • Shared Swarm workflows can be applied to a project or project branch by any Swarm user that is authorized to edit the project.
  • The global workflow can be viewed by any Swarm user but can only be edited by a Swarm user with super or admin privileges, or users that have been made an owner.

To add a workflow:

  1. On the Swarm Workflows page, click the + Add Workflow button.

    The Add Workflow page is displayed:

     

    Add Workflow Page image
  2. Enter a name for the workflow.
  3. Optional: provide a description for the workflow.

  4. You are automatically added as the owner of the workflow.

    Optional: add more owners if required. This field auto-suggests groups, and users within Helix Core Server as you type (up to a combined limit of 20 entries).

    Important
    • A workflow must have at least one owner.
    • If you remove yourself as an owner, you cannot edit this workflow configuration later unless you have super user rights.

  5. Optional: if you want other Swarm users to be able to use this workflow, select the Shared with others checkbox.

    Tip

    Leave the checkbox unselected until you have proved that the workflow rules work as expected. This keeps the workflow private and stops other Swarm users using the workflow until you are happy with it. Once you are happy with the workflow, select the checkbox to share the workflow with other users.

  6. Rules:

    On commit without a review:

    This rule is applied when a changelist without an associated review is submitted from outside of Swarm.

    Select one of the following options:

    • Allow: the changelist is not checked, the changelist is submitted without a review.
    • Create a review: the changelist is submitted and a review is created automatically for the changelist.
    • Reject: the changelist submit is rejected.

      • Tip

      The selected rule is also applied when a changelist is submitted with #review in the description. For more information about creating a review by including a keyword in the changelist description, see Create a review.

    On commit with a review: This rule is applied when:

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

    Select one of the following options:

    • Allow: the changelist review state is not checked. The changelist is committed even if its associated review is not approved.
    • Reject unless approved: the changelist is only submitted if its associated review is approved and the content of the changelist is identical to the content of the approved review.

      • Tip

      The selected rule is also applied when a changelist is submitted with #review-nnnnn, #replace-nnnnn, or #append-nnnnn in the description (nnnnn = review ID). For more information about adding a changelist to a review by including a keyword in the changelist description, see Add a changelist to a review.

    On update of a review in an end state:

    Used to stop review content being automatically changed for reviews that are in specific states. By default, the protected end states are Archived, Rejected, and Approve:Commit. The end states are set by the Swarm administrator, see end_states.

    Tip

    When a review is in a protected end state, it can still be updated manually by a user from the Swarm UI.

    This rule is applied when a changelist is added to a review.

    Select one of the following options

    • Allow: the review is not checked. The changelist is added to the review no matter what the review state is. This is the default setting.
    • Reject: if the review is in one of the states specified in the end_state configurable:
      • The Add Change button is disabled for the review.
      • The changelist is rejected if it is added outside of Swarm using #review-nnnnn, #replace-nnnnn, or #append-nnnnn in the description (nnnnn = review ID).

    Count votes up from:

    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.

    This rule is applied when a user votes on a review.

    Select 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.
    Tip

    For instructions on how to set Minimum up votes for projects and branches, see Project minimum up votes and Branch minimum up votes.

    Automatically approve reviews:

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

    This rule is applied when a user votes on a review.

    Select one of the following options:

    • Never: reviews are not automatically approved. This is the default setting.
    • Based on vote count: 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.
      • All of the tests configured to block approval have passed.
      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.

  7. Tests

    8. Optional: add tests to the workflow, the tests are run when a review associated with the workflow is either created/updated or submitted. Selected from the When dropdown for the test.

    Tip
    • Tests are only saved on the workflow when you click the Save button.
    • If a review is associated with multiple workflows, all of the tests on all of those workflows are run for the review. If the same test is on more than one of the associated workflows, it is only run once.

    Add a test:  

    1. Click Image of the + Add Test link in the Tests area.
    2. Select the test to run from the Tests dropdown list.
    3. Select when you want the test to run from the When dropdown list.

      Tip

      • Review content change is when the files or content of files in a review change. A change to the review description does not trigger a test.

      • On Demand tests are unaffected by the review content change check.

      • On Update the test will run when:
        • a review is created.

        • a review is submitted and the review content has changed compared to the previous review version.

        • a review is updated and the review content has changed since the previous review version.

        • Tip

        If the review content has not changed since a test last successfully reported a pass, it will not be re-run when a review is versioned or submitted. If a test is still running or has not updated Swarm with a pass state, it will be re-run, even on a submit.

      • On Submit the test will run when a pre-commit review is submitted or a post-commit review is created.
      • On Demand the test will not run automatically, but you can run it manually from the Tests dialog on the review page.
    4. Select whether Swarm blocks approval if the test fails from the Blocks dropdown list:
      • Nothing if the test fails it will not block approval.
      • Approve if the test fails it will prevent the review from being approved.
    5. Click the Accept Image of the Accept button button to add the test to the workflow.

    Edit a test on the workflow:

    1. Click the Edit Edit button image button next to the test you want to edit.
    2. The Test, When, and Blocks dropdown lists are displayed for the test.
    3. Make changes as required.
    4. Click the Accept Image of the Accept button button to confirm your changes.

    Remove a test from the workflow:

      Click the Delete Image of the Remove button button next to the test to remove it from the workflow.

      The test is removed immediately, no confirmation is requested. You must save the workflow to complete the test removal.

  8. Click Save.

    Note

    The Save button is disabled if any required fields are empty.