Documentation | 2025.1

# Installing the Swarm Helix Core Server extension (recommended)

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

- You must be a user with super user permissions to install and configure Helix Core Server Extensions.

Swarm needs to know about a number of Helix Core Server events to operate correctly, this is done by using Helix Core Server Extensions. Helix Core Server Extensions must be installed and configured on your Helix Core Server to complete your Swarm installation. The Swarm Helix Core Server extension is included with the Swarm product download.

## Prerequisites

To install the Swarm Helix Core Server extension you need:

A compatible version of Helix Core Server for Helix Core Server Extensions:

- Linux: Helix Core Server 2021.2 and later. If you are using an earlier version of Helix Core Server, you must use triggers.

- Windows: Helix Core Server 2021.2 and later. If you are using an earlier version of Helix Core Server, you must use triggers.

You will also need:

- Helix Core Server Extensions installed and configured on your Helix Core Server.

- A user with super permissions to install and configure the Swarm Helix Core Server extension.

## Swarm Helix Core Server extension installation

The following commands can be run on the Swarm server or the Helix Core Server. You must be a Helix Core Server super user to install and configure Helix Core Server Extensions.

The Swarm Helix Core Server extension file is included for all of the Swarm installation types. The helix-swarm.p4-extension file is located in swarm_root/p4-bin/extensions

Run the following commands as a Helix Core Server user with super permissions:

1. Install the Swarm Helix Core Server extension on the Helix Core Server with:

p4 extension --yes --install helix-swarm.p4-extension

Example response:

    Extension 'Perforce::helix-swarm' version '2022.1.20221215' installed successfully.
    Perform the following steps to turn on the Extension:

    # Create a global configuration if one doesn't already exist.
    p4 extension --configure Perforce::helix-swarm

    # Create an instance configuration to enable the Extension.
    p4 extension --configure Perforce::helix-swarm --name Perforce::helix-swarm-instanceName

    For more information, visit: https://www.perforce.com/manuals/extensions/Content/Extensions/Home-extensions.html

2. Create a global configuration if one doesn't already exist:

   p4 extension --configure Perforce::helix-swarm

   The spec file opens in your text editor, for example:

       ExtName:        helix-swarm
       ExtDescription:
               Helix Swarm Extension

       ExtVersion:     2022.1.DEV.20220120

       ExtUUID:        4532BC59-7BC8-478F-ADF6-0A563C42563D

       ExtRev: 1

       ExtMaxScriptTime:       unset

       ExtMaxScriptMem:        unset

       ExtAllowedGroups:

       ExtEnabled:     true

       ExtP4USER:      sampleExtensionsUser

       Name:   helix-swarm

       Owner:  super

       Update: 2022/01/21 10:43:46

       Description:
               The description of your config.

       ExtConfig:
               Debug:
                       2
               Swarm-Secure:
                       true
               Swarm-Token:
                       ... SWARM-TOKEN
               Swarm-URL:
                       http://localhost/

3. Edit the spec file to match your system:

   - ExtP4USER: Set to an existing user with super permissions.

   - ExtConfig: Check and edit the values in this block:

     - Debug:

       Debug levels 0 to 3 control the amount of debug information sent to the Helix Core Server Extensions log.

       A debug level of 10 and higher sends all debug information to the client. This is useful for debugging, but should not be run in a production environment.

     - SSL-CA-File: (optional) Set the absolute path of the Certificate Authority (CA) Privacy-Enhanced Mail (PEM) file to validate the Swarm Helix Core Server's certificate. Ensure that this file is accessible to the Helix Core Server process owner.

       If a suitable certificate is not found in the local SSL certificate store maintained by the operating system or if there are verification issues from using a self-signed certificate then the default CA file is used.

       By default, the local certificate stored in the default CA file is used if the absolute path for the Certificate Authority (CA) is not specified.

     - Swarm-Secure:

       - true will only accept secure SSL certificates.

       - false will accept insecure SSL certificates.

     - Swarm-Token: Set to the Swarm trigger token value.

       To set multiple Helix Core Server token settings for Extensions, repeat the following steps for each Helix Core Server. The process to obtain an extension token of your Swarm instance is similar to obtaining a trigger token of your Swarm instance.

       To obtain the trigger token of your Swarm instance:

       1. Log in to Swarm as a super user.

       2. Click your userid, found at the right of the main toolbar.

       3. Select About Swarm.

       4. The About Swarm dialog is displayed and Swarm generates an API token if it doesn't already exist.

       5. Copy the trigger token value displayed at the bottom of the dialog and paste the token into the spec file.

     - Swarm-URL: Set to the URL of your Swarm instance.

4. When you have finished editing the spec file, save it in your text editor.

5. Create an instance configuration to enable the extension:

   p4 extension --configure Perforce::helix-swarm --name swarm

   The spec file opens in your text editor, for example:

       ExtName:        helix-swarm

       ExtDescription:
               Helix Swarm Extension

       ExtVersion:     2022.1.DEV.20220120

       ExtUUID:        4532BC59-7BC8-478F-ADF6-0A563C42563D

       ExtRev: 1

       ExtMaxScriptTime:       unset

       ExtMaxScriptMem:        unset

       ExtEnabled:     true

       ExtDebug:       none

       Name:   swarm

       Owner:  super

       Update: 2022/01/21 10:58:41

       Description:
               The description of your config.

       ExtConfig:
               depot-path:
                       //...
               enableStrict:
                       true
               enableWorkflow:
                       true
               httpTimeout:
                       30
               ignoreErrors:
                       false

   We recommend that these settings are left at their default values, but the configuration needs to be run to set the default values.

   - enableStrict: Enable strict checking of reviews for workflow. Verifies 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.

   - enableWorkflow: Enable workflow.

   - httpTimeout: Timeout (in seconds) when communicating with the Swarm server.

   - ignoreErrors: If the server returns an error (timeout, not there), then default to allowing a request. It means workflow rules can be skipped, but if the Swarm server is down it will not block submits.

6. Save the spec file in your text editor.

7. Confirm your Swarm Helix Core Server extension is installed and configured by running the following command on the Helix Core Server:

p4 extension --run swarm ping

- If the Swarm Helix Core Server extension is working, the Helix Core Server responds with OK

- If the Swarm Helix Core Server extension is not working, the Helix Core Server responds with an error message. For example, BAD (Cannot reach https://swarm-example.com/)

For more information about Helix Core Server Extensions, see:

- Extension overview in the Helix Core Extensions Documentation.

- p4 extension in the Helix Core Command-Line (P4) Reference.

8. Depending on your installation type, do one of the following:
   - Swarm package installation: Review the post-install configuration options to customize your Swarm installation, see Post-install configuration options.
   - Swarm tarball installation: Set up a recurring task to spawn workers, see Set up a recurring task to spawn workers.

## Add Swarm as an HTML tab in the Helix Core Visual Client (P4V)

To add Swarm as an HTML tab in the Helix Core Visual Client (P4V), see HTML Tabs section in the P4VJS Developer Guide.

Your search for returned results