Open topic with navigation

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 [-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 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 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 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 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 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 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 Server form-delete events for user forms, which informs Swarm when a user is deleted.
  • group: this type should be used with Helix 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 Server form-delete events for group forms, and informs Swarm when a group is deleted.
  • changesave: this type should be used with Helix 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 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 Server change-commit events, and informs Swarm when a changelist is committed.
  • shelvedel: this type is used with Helix 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 (this trigger must be commented out if the Workflow technology preview feature is enabled): 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 (this trigger must be commented out if the Workflow technology preview feature is enabled): 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 (only use if the Workflow technical preview feature is enabled. If the Workflow technology preview feature is disabled these triggers must be commented out. The enforce and strict triggers above must be commented out if the Workflow feature is enabled):
  • Important

    Trigger types checkenforced, checkstrict, and checkshelve were introduced in Swarm 2018.2 for the Workflow technology preview feature.

    Known limitations

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

    • -g group: 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.
    • 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 leave the Workflow technology feature disabled.

  • 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 with_review workflow rule and cannot be configured. checkenforced triggers on a Helix Server change-submit event.
    • If a commit is made to a branch that has with_review set to strict, 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 with_review workflow rule and cannot be configured. checkstrict triggers on a Helix Server change-content event.
    • This check is performed after checkenforced. If the with_review rule is set to strict, 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 end_rules workflow rule and cannot be configured. checkshelve triggers on a Helix Server shelve-submit event.
    • If a shelf is associated with a review, and it is committed to a branch that has end_rules set to no_revision, 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 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 technology preview feature is enabled:

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

• -r (optional) Do not use if the Workflow technology preview feature is enabled:

  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 technology preview feature is enabled:

  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) Do not use if the Workflow technology preview feature is enabled:

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

• ADMIN_TICKET_FILE (optional) Do not use if the Workflow technology preview feature is enabled:

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

  Important

  Ensure that the ticket belongs to a user with admin privileges in the Helix 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 technology preview feature is enabled:

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

• P4 (optional) Do not use if the Workflow technology preview feature is enabled:

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

• EXEMPT_FILE_COUNT (optional) Do not use if the Workflow technology preview feature is enabled:

  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 technology preview feature is enabled:

  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.

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