Job keywords

By default, if you add jobnnnnn or @jobnnnnn to a job description, changelist description, review description, or comment, Swarm automatically creates a link to the Swarm job page if a match is found. The jobnnnnn or @jobnnnnn keywords are hardcoded in Swarm and always present.

If your job numbers are not formatted as jobnnnnn, you can configure Swarm to recognize other keywords in addition to job and @job. For example, if your job numbers are formatted as defectnnnnnn, Swarm can be configured to recognize them and link to the correct job page.

When you create a new job keyword, this is in addition to the default job keywords. Multiple job keywords can be specified. The first successful match is used, starting with the default job keywords. Once Swarm finds a match, none of the other keywords are evaluated.

The job keyword is configured with a regular expression so that almost any keyword can be used. When you add a new job keyword to Swarm, take care to choose syntax and terminology that is unlikely to occur naturally in a description to avoid unexpected links being created.

Tip

If you make a configuration change, Swarm will not use it until the configuration cache has been reloaded, this forces Swarm to use the new configuration. You must be an admin or super user to reload the Swarm config cache. Navigate to the User id dropdown menu, select System Information, click the Cache Info tab, and click the Reload Configuration button.

Adding a new job keyword

Tip

You can test the results of your regular expression before using it, see https://regex101.com/
Regular expressions are case insensitive.

Job parameters:

'word_length_limit': The limit on the number of characters which a text to be linkified can have.
'target': Opens the URL in the same tab or a new tab, defaults to '_self'. To open the URL in a new tab, set to '_blank'.
'regex': The regular expression used to match the job keyword.
'url': The URL to append the regex match to. This URL plus the job number matched by the regex is used to display the job page. This URL can reference a Swarm page or an external defect tracking system.

Optional: Specify the regex capture group to append to the URL. For example, adding /{2} after the url parameter tells Swarm to append the second regex capture group result to the url. For more information on capture groups, see https://www.regular-expressions.info/brackets.html.

Swarm page link example

Tip

In this example, only the second regex capture group is appended to the url parameter. This means that the @ character is only used to help identify the job and is not appended to the URL.

For example, to add "defect" as a jobs keyword so that both @defectnnnnn and defectnnnnn mentions are linked to a job page in Swarm, add the following block to the SWARM_ROOT/data/config.php file:

<?php
    // this block should be a peer of 'p4'
    'linkify' => array(
        'word_length_limit' => 2048,
        'target' => '_blank',
        'markdown' => array(
            array(
                'id'    =>  'jobs',
                'regex' => '(@?)(defect[0-9]+)', // the regular expression used to match the job keyword, default is empty
                'url'   => '{baseurl}/{2}',      // url that matching job numbers are appended to, default is empty
            ),
        ),
    ),

External page link example

Tip

In this example, the /{0} character string at the end of the url is important because it helps the external link to get built dynamically.

For example, to add "issue" as a jobs keyword so that mentions of issuennnnn are linked to jobs in your defect tracking system, add the following block to the SWARM_ROOT/data/config.php file:

<?php
    // this block should be a peer of 'p4'
    'linkify' => array(
        'word_length_limit' => 2048,
        'target' => '_blank',
        'markdown' => array(
            array(
                'id'    =>  'jobs',
                'regex' => '(issue[0-9]+)',               // the regular expression used to match the job keyword, default is empty
                'url'   => 'example.defect-tracker-url/{0}', // url that matching job numbers are appended to, default is empty
            ),
        ),
    ),

Jira issue link example

Tip

In this example, the /{0} character string at the end of the url is important because it helps the external link to get built dynamically.

For example, to add your Jira issue format so that mentions of xxx-nnnnn are linked to Jira issues in your Jira system, add the following block to the SWARM_ROOT/data/config.php file:

<?php
    // this block should be a peer of 'p4'
    'linkify' => array(
        'word_length_limit' => 2048,
        'target' => '_blank',
        'markdown' => array(
            array(
                'id'    =>  'jira',
                'regex' => '[A-Z1-9]{2,}-\d+',               // the regular expression used to match the job keyword, default is empty
                'url'   => 'example.jira-system-url/browse/{0}', // url that matching numbers are appended to, default is empty
            ),
        ),
    ),