Installing the Swarm Helix Core Server extension (recommended)

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

Tip

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:

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

  3. 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/
  4. 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.

        Important

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

        Important

        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.

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

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

  7. Save the spec file in your text editor.

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

  9. p4 extension --run swarm ping

  10. Depending on your installation type, do one of the following:

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.