Trigger options

If you are using P4 Code Review P4 Server Triggers, the P4 Code Review P4 Server extension must not be installed.

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

The P4 Code Review 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 P4 Code Review administrator. These are not intended to be used within trigger entries in the P4 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 P4 Server to execute the script in its current path.

  • -o

    Displays a copy of the trigger table entries that should be configured in the P4 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 P4 Server to specify how the P4 Code Review 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 P4 Server form-commit events for job forms, and informs P4 Code Review when a job is created or modified.
    • user: this type should be used with P4 Server form-commit events for user forms, which informs P4 Code Review when a user is added or modified.
    • userdel: this type should be used with P4 Server form-delete events for user forms, which informs P4 Code Review when a user is deleted.
    • group: this type should be used with P4 Server form-commit events for group forms, and informs P4 Code Review when a group is created or modified.
    • groupdel: this type should be used with P4 Server form-delete events for group forms, and informs P4 Code Review when a group is deleted.
    • changesave: this type should be used with P4 Server form-save events for change forms, and informs P4 Code Review when a changelist is created or modified.
    • shelve: this type should be used with P4 Server shelve-commit events, and informs P4 Code Review when a changelist is shelved, which can create or update a review.
    • commit: this type should be used with P4 Server change-commit events, and informs P4 Code Review when a changelist is committed.
    • shelvedel: this type is used with P4 Server shelve-delete events, and informs P4 Code Review when a file is deleted from a shelf.

      • Do not use the P4 Code Review user that is configured in the P4 Code Review configuration file when deleting shelves, or deleting files from shelves. The P4 Code Review logic processes the shelve-delete trigger event, if the event is invoked by the P4 Code Review 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.

      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:

      • Known limitations

      The workflow triggers do not support the following trigger functionality available in P4 Code Review 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.

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

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

      • checkenforced: this type is used by the P4 Code Review On commit with a review workflow rule and cannot be configured. checkenforced triggers on a P4 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 P4 Code Review On commit without a review workflow rule and cannot be configured. checkstrict triggers on a P4 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 P4 Code Review On update of a review in an end state workflow rule and cannot be configured. checkshelve triggers on a P4 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, P4 Code Review 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.

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

    On Windows Perforce servers using Strawberry Perl, multithreading issues and the spawning of numerous perl.exe child processes can occur if the swarm-trigger.pl script is referenced from a depot path.

    To mitigate these issues for non-workflow triggers, add the -z flag to the end of your trigger definitions. This forces Perl processes to run synchronously, bypassing potential problems with Win32 process forking. For example:

    swarm.shelvesub shelve-submit //... "perl %//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t checkshelve -v %change% -u %user% -z"

    Do not use the -z flag with workflow triggers. Using this flag with workflow triggers will prevent the enforce and strict code sections within the trigger script from executing correctly. Workflow triggers should be configured without the -z flag.

  • -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 P4 Code Review should process.

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

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

    Specifies the P4 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 P4 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 P4 Code Review instance, with the leading http:// or https://. For example: https://myswarm.url.

  • SWARM_TOKEN (required)

    A token used when talking to P4 Code Review. To obtain the token, log into P4 Code Review as a user with super privileges and select the About P4 Code Review 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 P4 Code Review dialog), that should be readable by the web server.

    You might manually create additional tokens to allow other processes to talk to P4 Code Review, such as JIRA build tasks, and to selectively invalidate access to P4 Code Review without interfering with regular P4 Code Review 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 P4 Server that has admin privileges. If you do not specify a username, the trigger script uses the P4 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 P4 Server tickets file is not the default $HOME/.p4tickets.

    Ensure that the ticket belongs to a user with admin privileges in the P4 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 P4 Server, particularly if the P4 Server is on a non-standard port, or if the P4 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 P4 Server command-line client. This is only required when p4 is not found in the PATH of the P4 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 P4 Code Review 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 P4 Code Review 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 P4 Code Review server.

    The default setting is 30 seconds.

  • IGNORE_TIMEOUT (optional)

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

    Options are:

    • 0 if communication with the P4 Code Review server times out, the submit will fail. This is the default setting.
    • 1 if communication with the P4 Code Review 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 P4 Code Review server fails. For example, the P4 Code Review server is down.

    Options are:

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