Trigger options

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 [-p port] [-r] [-g group] [-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 Versioning Engine.

-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 Versioning Engine to execute the script in its current path.

-o

Displays a copy of the trigger table entries that should be configured in the Helix Versioning Engine 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 Versioning Engine 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:

  • changesave: this type should be used with Perforce form-save events for change forms, and informs Swarm when a changelist is created or modified.

  • commit: this type should be used with Perforce change-commit events, and informs Swarm when a changelist is committed.

  • enforce: 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,

  • group: this type should be used with Perforce form-commit events for group forms, and informs Swarm when a group is created or modified.

  • groupdel: this type should be used with Perforce form-delete events for group forms, and informs Swarm when a group is deleted.

  • job: this type should be used with Perforce form-commit events for job forms, and informs Swarm when a job is created or modified.

  • shelve: this type should be used with Perforce shelve-commit events, and informs Swarm when a changelist is shelved, which can create or update a review.

  • strict: 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.

  • user: this type should be used with Perforce form-commit events for user forms, which informs Swarm when a user is added or modified.

  • userdel: this type should be used with Perforce form-delete events for user forms, which informs Swarm when a user is deleted.

Important

You cannot mix Swarm trigger types with unrelated Perforce 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, enforce, or strict, ID should be %change% to specify the specific changelist Swarm should process.

-p port (optional)

Specifies the Helix Versioning Engine 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 Versioning Engine during its processing.

-r (optional)

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

-g group (optional)

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 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)

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

ADMIN_TICKET_FILE (optional)

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

Important

Ensure that the ticket belongs to a user with admin privileges in the Helix Versioning Engine, 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)

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

P4 (optional)

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

EXEMPT_FILE_COUNT (optional)

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)

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