Disclaimer

This repository is community supported and not maintained by Mattermost. Mattermost disclaims liability for integrations, including Third Party Integrations and Mattermost Integrations. Integrations may be modified or discontinued at any time.

Autolink Plugin

Maintainer: @levb Co-Maintainer: @iomodo

This plugin creates regular expression (regexp) patterns that are reformatted into a Markdown link before the message is saved into the database.

Use it to add custom auto-linking on your Mattermost system, such as adding links to your issue tracker based on the regexp patterns.

Posting a message containing a Jira issue key..

..automatically links to the corresponding issue in the Jira project

Configuration

1. Go to System Console > Plugins > Plugin Management and click Enable to enable the Autolink plugin.

   • If you are running Mattermost v5.11 or earlier, you must first go to the releases page of this GitHub repository, download the latest release, and upload it to your Mattermost instance following this documentation.

2. Modify your config.json file to include the types of regexp patterns you wish to match, under the PluginSettings. See below for an example of what this should look like.

Tip: There are useful Regular Expression tools online to help test and validate that your formulas are working as expected. One such tool is Regex101 . Here is an example Regular Expression to capture a post that includes a VISA card number - which you could then obfuscate with the Pattern so people don't accidentally share sensitive info in your channels.

3. Go to System Console > Plugins > Autolink to configure the following additional plugin options:
   • Enable administration with /autolink command: Select true to enables administration of the plugin using the /autolink slash command. Select false to disable this functionality.
   • Apply plugin to updated posts as well as new posts: Select true to apply the plugin to updated posts as well as new posts. Select false to apply the plugin to new posts only
   • Admin user IDs: Authorize non-System Admin users to administer the plugin when enabled. Find user IDs by going to System Console > User Management > Users. Separate multiple user IDs with commas.

Usage

Autolinks have 3 parts: a Pattern which is a regular expression search pattern utilizing the Golang regexp library, a Template that gets expanded and an optional Scope parameter to define which team/channel the autolink applies to. You can create variables in the pattern with the syntax (?P<name>...) which will then be expanded by the corresponding template.

In the template, a variable is denoted by a substring of the form $name or ${name}, where name is a non-empty sequence of letters, digits, and underscores. A purely numeric name like $1 refers to the submatch with the corresponding index. In the $name form, name is taken to be as long as possible: $1x is equivalent to ${1x}, not ${1}x, and, $10 is equivalent to ${10}, not ${1}0. To insert a literal $ in the output, use $$ in the template.

The scope must be either a team (teamname) or a team and a channel (teamname/channelname). Remember that you must provide the entity name, not the entity display name. Since Direct Messages do not belong to any team, scoped matches will not be autolinked on Direct Messages. If more than one scope is provided, matches in at least one of the scopes will be autolinked.

Below is an example of regexp patterns used for autolinking at https://community.mattermost.com, modified in the config.json file:

"PluginSettings": {
    ...
    "Plugins": {
        "mattermost-autolink": {
            "links": [
                {
                    "Pattern": "(LHS)",
                    "Template": "[LHS](https://docs.mattermost.com/process/training.html#lhs)",
                    "Scope": ["team/off-topic"]
                },
                {
                    "Pattern": "(RHS)",
                    "Template": "[RHS](https://docs.mattermost.com/process/training.html#rhs)",
                    "Scope": ["team/town-square"]
                },
                {
                    "Pattern": "(?i)(Mana)",
                    "Template": "[Mana](https://docs.mattermost.com/process/training.html#mana)"
                },
                {
                    "Pattern": "(?i)(ESR)",
                    "Template": "[ESR](https://docs.mattermost.com/process/training.html#esr)"
                },
                {
                    "Pattern": "((?P<level>0|1|2|3|4|5)/5)",
                    "Template": "[${level}/5](https://docs.mattermost.com/process/training.html#id8)"
                },
                {
                    "Pattern": "(MM)(-)(?P<jira_id>\\d+)",
                    "Template": "[MM-${jira_id}](https://mattermost.atlassian.net/browse/MM-${jira_id})"
                },
                {
                    "Pattern": "https://pre-release\\.mattermost\\.com/core/pl/(?P<id>[a-zA-Z0-9]+)",
                    "Template": "[<jump to convo>](https://pre-release.mattermost.com/core/pl/${id})"
                },
                {
                    "Pattern": "(https://mattermost\\.atlassian\\.net/browse/)(MM)(-)(?P<jira_id>\\d+)",
                    "Template": "[MM-${jira_id}](https://mattermost.atlassian.net/browse/MM-${jira_id})"
                },
                {
                    "Pattern": "https://github\\.com/mattermost/(?P<repo>.+)/pull/(?P<id>\\d+)",
                    "Template": "[pr-${repo}-${id}](https://github.com/mattermost/${repo}/pull/${id})"
                },
                {
                    "Pattern": "https://github\\.com/mattermost/(?P<repo>.+)/issues/(?P<id>\\d+)",
                    "Template": "[issue-${repo}-${id}](https://github.com/mattermost/${repo}/issues/${id})"
                },
                {
                    "Pattern": "(PLT)(-)(?P<jira_id>\\d+)",
                    "Template": "[PLT-${jira_id}](https://mattermost.atlassian.net/browse/PLT-${jira_id})"
                },
                {
                    "Pattern": "(https://mattermost\\.atlassian\\.net/browse/)(PLT)(-)(?P<jira_id>\\d+)",
                    "Template": "[PLT-${jira_id}](https://mattermost.atlassian.net/browse/PLT-${jira_id})"
                }
            ]
        },
    },
    ...
    "PluginStates": {
        ...
        "mattermost-autolink": {
            "Enable": true
        },
        ...
    }
},

Examples

1. Autolinking Ticket ####:text with alphanumberic characters and spaces to a ticket link. Use:

   • Pattern: (?i)(ticket )(?P<ticket_id>.+)(:)(?P<ticket_info>.*), or if the ticket_id is a number, then (?i)(ticket )(?P<ticket_id>\d+)(:)(?P<ticket_info>.*)
   • Template: [Ticket ${ticket_id}: ${ticket_info}](https://github.com/mattermost/mattermost-server/issues/${ticket_id})
   • Scope: ["teams/committers"] (optional)

2. Autolinking a link to a GitHub PR to a format "pr-repo-id". Use:

   • Pattern: https://github\\.com/mattermost/(?P<repo>.+)/pull/(?P<id>\\d+)
   • Template: [pr-${repo}-${id}](https://github.com/mattermost/${repo}/pull/${id})

3. Using autolinking to create group mentions. Use (note that clicking the resulting at-mention redirects to a broken page):

   • Pattern: @customgroup*
   • Template: [@customgroup]( \\* @user1 @user2 @user3 \\* )

4. For servers with multiple domains (like community and community-daily on the public Mattermost Server), a substitution of absolute conversation links to relative links is recommended to prevent issues in the mobile app. Add one pattern for each domain used:

   • Pattern: https://community\\.mattermost\\.com/(?P\u003cteamname\u003e(?a-zA-Z0-9]+)/(?P\u003cid\u003e[a-zA-Z0-9]+)
   • Template: [<jump to convo>](/${teamname}/pl/${id})/${id})

Autolink the word Handbook to a internal URL on the private team (called office), and a private channel (staff) in the public team (called everyone). - Pattern: (Handbook) - Template: [Handbook](http://www.mywebsite.com/private/handbook) - Scope: ["office", "everyone/staff"]

You can check your pattern with those Regex Testers:

• https://regex-golang.appspot.com/,
• https://regex101.com/,
• https://www.regextester.com/.

Configuration Management

The /autolink commands allow the users to easily edit the configurations.

Commands	Description	Usage
list	Lists all configured links	/autolink list
list <linkref>	List a specific link which matched the link reference	/autolink list test
test <linkref> test-text	Test a link on the text provided	/autolink test Visa 4356-7891-2345-1111 -- (4111222233334444)
enable <linkref>	Enables the link	/autolink enable Visa
disable <linkref>	Disable the link	/autolink disable Visa
add <linkref>	Creates a new link with the name specified in the command	/autolink add Visa
delete <linkref>	Delete the link	/autolink delete Visa
set <linkref> <field> value	Sets a link's field to a value Fields - Template - Sets the Template field Pattern - Sets the Pattern field WordMatch - If true uses the \b word boundaries ProcessBotPosts - If true applies changes to posts made by bot accounts. Scope - Sets the Scope field (team or team/channel or a whitespace-separated list thereof)	/autolink set Visa Pattern (?P<VISA>(?P<part1>4\d{3})[ -]?(?P<part2>\d{4})[ -]?(?P<part3>\d{4})[ -]?(?P<LastFour>[0-9]{4})) /autolink set Visa Template VISA XXXX-XXXX-XXXX-$LastFour /autolink set Visa WordMatch true /autolink set Visa ProcessBotPosts true /autolink set Visa Scope team/townsquare

Development

This plugin contains a server portion. Read our documentation about the Developer Workflow and Developer Setup for more information about developing and extending plugins.

Releasing new versions

The version of a plugin is determined at compile time, automatically populating a version field in the plugin manifest:

• If the current commit matches a tag, the version will match after stripping any leading v, e.g. 1.3.1.
• Otherwise, the version will combine the nearest tag with git rev-parse --short HEAD, e.g. 1.3.1+d06e53e1.
• If there is no version tag, an empty version will be combined with the short hash, e.g. 0.0.0+76081421.

To disable this behaviour, manually populate and maintain the version field.