Trigger options

Warning

If you are using Swarm Helix Core Server Triggers, the Swarm Helix Core Server extension must not be installed.

Tip

We recommend you use Helix Core Server Extensions, Helix Core Server Extensions are easier to install and maintain than triggers. See Helix Core Server Extensions dependencies.

The Swarm trigger script, swarm-trigger.pl, provides the following command line options and configuration items.

Command-line options

Synopsis

swarm-trigger.pl -t type -v ID [-c config_file]
swarm-trigger.pl -o
swarm-trigger.pl -h

Informational options

The following options perform no processing, and simply provide information useful to a Swarm administrator. These are not intended to be used within trigger entries in the Helix Core Server.

  • -h

    Displays a list of the available options, some guidance on its usage, and a copy of the trigger table entries that should be configured in the Helix Core Server to execute the script in its current path.

  • -o

    Displays a copy of the trigger table entries that should be configured in the Helix Core Server to execute the script in its current path.

Operational options

The following command-line options are used in the trigger table entries in the Helix Core Server to specify how the Swarm trigger script should be executed.

  • -t type

    Specifies the type of processing that the trigger script undertakes. type can be one of:

    • job: this type should be used with Helix Core Server form-commit events for job forms, and informs Swarm when a job is created or modified.
    • user: this type should be used with Helix Core Server form-commit events for user forms, which informs Swarm when a user is added or modified.
    • userdel: this type should be used with Helix Core Server form-delete events for user forms, which informs Swarm when a user is deleted.
    • group: this type should be used with Helix Core Server form-commit events for group forms, and informs Swarm when a group is created or modified.
    • groupdel: this type should be used with Helix Core Server form-delete events for group forms, and informs Swarm when a group is deleted.
    • changesave: this type should be used with Helix Core Server form-save events for change forms, and informs Swarm when a changelist is created or modified.
    • shelve: this type should be used with Helix Core Server shelve-commit events, and informs Swarm when a changelist is shelved, which can create or update a review.
    • commit: this type should be used with Helix Core Server change-commit events, and informs Swarm when a changelist is committed.
    • shelvedel: this type is used with Helix Core Server shelve-delete events, and informs Swarm when a file is deleted from a shelf.

      • Important

      Do not use the Swarm user that is configured in the Swarm configuration file when deleting shelves, or deleting files from shelves. The Swarm logic processes the shelve-delete trigger event, if the event is invoked by the Swarm user it is rejected. The delete operations will fail.

    • enforce comment out if the Workflow feature is enabled (enabled by default): this type is used to verify that commits to specific depot paths are associated with approved reviews. If a commit includes a file within the specified depot path, and it is not associated with a review (or a review that is not approved), the commit is rejected.

      • Using the enforce type prevents users from committing changes to specific depot paths without those changes being reviewed and approved.

    • strict comment out if the Workflow feature is enabled (enabled by default): this type is used to verify that the file content in a commit matches the file content of its associated approved review. If one or more files in a commit do not match the content of the file in its associated review, the commit is rejected.

      • Using the strict type prevents users from making changes to the file content after a review has been approved and then submitting the unapproved changes.

      Note

      strict implies enforce.

    • Workflow trigger types comment out if the Workflow feature is disabled (enabled by default). The enforce and strict triggers above must be commented out if the Workflow feature is enabled:

      • Important

      Known limitations

      The workflow triggers do not support the following trigger functionality available in Swarm 2018.1 and earlier:

      • EXEMPT_FILE_COUNT: When set to a positive integer, commits with a file count greater or equal to this value are exempt from enforce or strict verifications.
      • EXEMPT_EXTENSIONS: A comma separated list of file extension. Commits with files having only these extensions are exempt from enforce or strict verifications.

      To continue to use this functionality, you must keep your existing enforce and strict triggers and disable the Workflow feature.

      Tip

      By default, all group members and users must follow any workflow rules that apply to changelists and reviews. However, your Swarm administrator can configure specific groups and users so that they are excluded from following the workflow rules. This applies to actions taken in the Swarm UI, the Helix Core command-line (P4), a P4D client, and the Swarm API.

      The following trigger types are used by Swarm for workflow rules. They are not intended for use in custom trigger scripts.

      • checkenforced: this type is used by the Swarm On commit with a review workflow rule and cannot be configured. checkenforced triggers on a Helix Core Server change-submit event.

        • If a commit is made to a branch that has On commit with a review set to Reject unless approved, and it is not associated with a review (or the review is not approved), the commit is rejected. If the commit is associated with an approved review, a content check is carried out by checkstrict.

      • checkstrict: this type is used by the Swarm On commit without a review workflow rule and cannot be configured. checkstrict triggers on a Helix Core Server change-content event.

        • This check is performed after checkenforced. If the On commit without a review rule is set to Reject, and one or more files in a commit do not match the content of the file in its associated review, the commit is rejected.

      • checkshelve: this type is used by the Swarm On update of a review in an end state workflow rule and cannot be configured. checkshelve triggers on a Helix Core Server shelve-submit event.

        • If a shelf is associated with a review, and it is committed to a branch that has On update of a review in an end state set to Reject, Swarm checks what state the review is in to make sure it is not in a protected state. If the review is in a protected state, the commit is rejected.

    Important

    You cannot mix Swarm trigger types with unrelated Helix Core Server events; the behavior is undetermined, and the information required for each type of processing may not be available to the trigger.

  • -v ID

    Specifies ID, which is the identifier for the current trigger type.

    When the type is job, user, userdel, group, groupdel, or changesave, ID should be %formname% to specify the specific form identifier Swarm should process.

    When the type is shelve, commit, shelvedel, checkenforced, checkstrict, or checkshelve ID should be %change% to specify the specific changelist Swarm should process.

  • -p port (optional) Do not use if the Workflow feature is enabled (default)

    Specifies the Helix Core Server port (P4PORT). This value is optional, and is only used for types enforce or strict as the trigger has to run its own commands against the Helix Core Server during its processing.

  • -r (optional) Do not use if the Workflow feature is enabled (default)

    Specifies that, when types enforce or strict are being processed, the verifications should only be performed on commits that are currently in review.

  • -g (optional) Do not use if the Workflow feature is enabled (default)

    Specifies a group to exclude from enforce or strict verifications. Members of the group (including sub-groups) are not subject to enforce or strict verifications.

  • -c config_file (optional)

    Specifies an optional config_file which is used to specify configuration items.

Configuration items

The following configuration items are used in the swarm-trigger.conf (or another file, if the -c option is used in the trigger entries).

  • SWARM_HOST (required)

    Specifies the host URL of your Swarm instance, with the leading http:// or https://. For example: https://myswarm.url.

  • SWARM_TOKEN (required)

    A token used when talking to Swarm. To obtain the token, log into Swarm as a user with super privileges and select the About Swarm from the user menu in the main navigation bar.

    You can also manually create additional tokens. Tokens are empty files stored within SWARM_ROOT/data/queue/tokens (the filename is the token and is reported on the About Swarm dialog), that should be readable by the web server.

    You might manually create additional tokens to allow other processes to talk to Swarm, such as JIRA build tasks, and to selectively invalidate access to Swarm without interfering with regular Swarm operations.

  • ADMIN_USER (optional) Do not use if the Workflow feature is enabled (default)

    When enforce or strict verifications are to be performed, you may need specify a username of a user in the Helix Core Server that has admin privileges. If you do not specify a username, the trigger script uses the Helix Core Server user set in the environment.

  • ADMIN_TICKET_FILE (optional) Do not use if the Workflow feature is enabled (default)

    When enforce or strict verifications are to be performed, you may need specify the path to the .p4tickets file, if your Helix Core Server tickets file is not the default $HOME/.p4tickets.

    Important

    Ensure that the ticket belongs to a user with admin privileges in the Helix Core Server, and is a member of a group with an unlimited or very long ticket timeout. If this user's authentication times out, enforce and strict verifications stop working.

  • P4_PORT (optional) Do not use if the Workflow feature is enabled (default)

    When enforce or strict verifications are to be performed, you may need to set the port value (P4PORT) of the Helix Core Server, particularly if the Helix Core Server is on a non-standard port, or if the Helix Core Server is not using the default hostname.

  • P4 (optional) Do not use if the Workflow feature is enabled (default)

    Specifies the full path to p4, the Helix Core Server command-line client. This is only required when p4 is not found in the PATH of the Helix Core Server environment, and when enforce or strict verifications are to be performed.

  • EXEMPT_FILE_COUNT (optional) Do not use if the Workflow feature is enabled (default)

    When set to a positive integer, commits with a file count greater or equal to this value are exempt from enforce or strict verifications.

  • EXEMPT_EXTENSIONS (optional) Do not use if the Workflow feature is enabled (default)

    A comma-separated list of file extensions. Commits with files having only these extensions are exempt from enforce or strict verifications.

  • VERIFY_SSL (optional)

    If HTTPS is used on the Swarm web server, this controls whether the SSL certificate is validated or not.

    By default VERIFY_SSL is set to 1, this means any SSL certificates must be valid. If the Swarm web server is using a self signed certificate, VERIFY_SSL must be set to 0.

    For more information about the risks of using a self-signed SSL certificate, see Security risks of using a self-signed certificate.

  • TIMEOUT (optional)

    Sets the number of seconds to wait before returning an error when communicating with the Swarm server.

    The default setting is 30 seconds.

  • IGNORE_TIMEOUT (optional)

    Configure the action to take if communication with the Swarm server times out. For example, if you are submitting a large number of files to the Helix Core Server.

    Options are:

    • 0 if communication with the Swarm server times out, the submit will fail. This is the default setting.
    • 1 if communication with the Swarm server times out, the submit will continue. This increases the reliability of submits.

  • IGNORE_NOSERVER (optional)

    Configure the action to take if communication with the Swarm server fails. For example, the Swarm server is down.

    Options are:

    • 0 if communication with the Swarm server fails, the submit will fail. This is the default setting.
    • 1 if communication with the Swarm server fails, the submit will continue. This increases the reliability of submits.