A WordPress plugin that integrates Mattermost slash commands with Jira for creating issues directly from chat channels.
- Slash Command Integration: Handle
/jira
commands from Mattermost - Channel-Project Mapping: Automatically map Mattermost channels to Jira projects
- Flexible Project Keys: Support both automatic mapping and manual project key specification
- Admin Interface: Easy management of settings and channel mappings
- Webhook Security: Token-based verification for secure webhook handling
- Invocation Logging: Comprehensive logging of all webhook requests and responses for debugging
- Upload the plugin files to
/wp-content/plugins/wp-mm-slash-jira/
- Activate the plugin through the 'Plugins' menu in WordPress
- Go to Settings > MM Jira Integration to configure the plugin
- Jira Domain: Your Jira domain (e.g.,
your-domain.atlassian.net
) - Jira API Key: Your Jira API key in format
email:api_token
- Webhook Token: A secure token to verify webhook requests from Mattermost
- Email Domain: Your company's email domain for automatic reporter assignment (e.g.,
company.com
) - Enable Logging: Check this option to store detailed invocation logs for debugging and monitoring
Email Domain Feature: When configured, the plugin will automatically search for Jira users using the pattern username@emaildomain
and set them as the reporter when creating issues. For example, if the email domain is set to "company.com" and user "john" creates an issue, the plugin will search for "john@company.com" in Jira and set that user as the reporter.
Map Mattermost channels to Jira projects:
- Go to the "Channel Mappings" tab
- Add new mappings with:
- Channel ID: The Mattermost channel ID
- Channel Name: Display name for the channel
- Jira Project Key: The Jira project key (e.g., PROJ, DEV, BUG)
Monitor and debug webhook invocations:
- Go to the "Invocation Logs" tab
- View all webhook requests and responses
- Filter logs by channel, user, or status
- Click "View Details" to see full request/response payloads
- Logs include execution time, status, and error messages
Configure the slash command in Mattermost:
- Go to System Console > Integrations > Slash Commands
- Create a new slash command with:
- Command:
/jira
- Request URL:
https://your-wordpress-site.com/wp-json/jira/mattermost/slash/jira
- Request Method: POST
- Response Username: Jira Bot
- Response Icon: (Optional) Jira icon URL
- Autocomplete: Enabled
- Autocomplete Description: Create Jira issues from chat
- Autocomplete Hint:
create [PROJECT-KEY-ISSUE-NUMBER] Title
- Command:
There are two ways to associate Mattermost channels with Jira projects:
- Go to Settings > MM Jira Integration in WordPress admin
- Navigate to the "Channel Mappings" tab
- Add new mappings with:
- Channel ID: The Mattermost channel ID (e.g.,
fukxanjgjbnp7ng383at53k1sy
) - Channel Name: Display name for the channel (e.g.,
general
) - Jira Project Key: The Jira project key (e.g.,
PROJ
,DEV
,BUG
)
- Channel ID: The Mattermost channel ID (e.g.,
Use the /jira bind
command directly in any Mattermost channel:
/jira bind PROJECT-KEY
Examples:
/jira bind PROJ
- Binds current channel to PROJ project/jira bind DEV
- Binds current channel to DEV project/jira bind BUG
- Binds current channel to BUG project
Benefits of Channel Binding:
- Create issues without specifying project key:
/jira create Fix login bug
- Use quick shortcuts:
/jira bug Fix login issue
,/jira task Update docs
- Get project-specific links:
/jira link
,/jira board
- View channel statistics:
/jira status
To remove a channel's project binding:
/jira unbind
What happens when you unbind:
- The channel is no longer mapped to any Jira project
- You must specify project keys in all commands:
/jira create PROJ Title
- Quick shortcuts will no longer work without project keys
- Use
/jira bind PROJECT-KEY
to bind to a different project
Example:
/jira unbind
- Removes current channel's project binding- After unbinding, use
/jira create PROJ Fix bug
instead of/jira create Fix bug
To see all available Jira projects and their keys:
/jira projects
This command will:
- List all projects in your Jira instance
- Group projects alphabetically for easy browsing
- Show project keys, names, and direct links to Jira
- Provide instructions for binding and creating issues
Example Output:
π **Available Jira Projects**
**Total Projects:** 15
**A**
β’ **API** - [API Development](https://your-domain.atlassian.net/browse/API)
β’ **APP** - [Application Development](https://your-domain.atlassian.net/browse/APP)
**B**
β’ **BUG** - [Bug Tracking](https://your-domain.atlassian.net/browse/BUG)
**D**
β’ **DEV** - [Development](https://your-domain.atlassian.net/browse/DEV)
**T**
β’ **TEST** - [Testing](https://your-domain.atlassian.net/browse/TEST)
**To bind this channel to a project:**
β’ `/jira bind PROJECT-KEY` - Replace PROJECT-KEY with one of the keys above
**To create issues in a specific project:**
β’ `/jira create PROJECT-KEY Title` - Create issue in specific project
β’ `/jira bug PROJECT-KEY Title` - Create bug in specific project
β’ `/jira task PROJECT-KEY Title` - Create task in specific project
β’ `/jira story PROJECT-KEY Title` - Create story in specific project
To see the current project binding and channel statistics:
/jira status
This will show:
- Current project binding (if any)
- When the binding was created
- Total issues created in this channel
- Recent activity statistics
- Available commands for the current setup
You can create issues in specific projects without binding the channel:
/jira create PROJECT-KEY Title
/jira create PROJ-123 Title
Examples:
/jira create PROJ Fix login bug
- Creates issue in PROJ project/jira create DEV-456 Add new feature
- Creates issue in DEV project/jira bug BUG Fix critical issue
- Creates bug in BUG project/jira task TEST Update test cases
- Creates task in TEST project
Jira project keys must:
- Contain only uppercase letters and numbers (A-Z, 0-9)
- Be 10 characters or less
- Exist in your Jira instance
Valid examples: PROJ
, DEV
, BUG
, TEST
, API123
Invalid examples: project
(lowercase), PROJECT-KEY
(hyphens), VERYLONGPROJECTKEY
(too long)
Command | Description | Example |
---|---|---|
/jira projects |
List all available Jira projects | /jira projects |
/jira bind PROJECT-KEY |
Bind current channel to a project | /jira bind PROJ |
/jira unbind |
Remove current channel's project binding | /jira unbind |
/jira status |
Check current project binding and stats | /jira status |
/jira create PROJECT-KEY Title |
Create issue in specific project | /jira create PROJ Fix bug |
/jira create Title |
Create issue in bound project | /jira create Fix bug |
/jira bug PROJECT-KEY Title |
Create bug in specific project | /jira bug PROJ Fix bug |
/jira task PROJECT-KEY Title |
Create task in specific project | /jira task PROJ Update docs |
/jira story PROJECT-KEY Title |
Create story in specific project | /jira story PROJ Add feature |
Workflow Examples:
- First time setup:
/jira projects
β/jira bind PROJ
β/jira create Fix bug
- Quick issue creation:
/jira bug Fix login issue
(if channel is bound) - One-off issue:
/jira create DEV-123 Add feature
(no binding needed) - Change project binding:
/jira unbind
β/jira bind DEV
β/jira create Fix bug
/jira create Fix login bug
- Creates issue in mapped project/jira bug Fix login issue
- Creates bug issue (shortcut)/jira task Update documentation
- Creates task issue (shortcut)/jira story Add new feature
- Creates story issue (shortcut)/jira view PROJ-123
- View detailed issue information/jira create Bug:Fix login bug
- Creates bug issue with specific type/jira create PROJ Story:Add new feature
- Creates story issue with specific project/jira create Task:Update documentation
- Creates task issue with specific type/jira create PROJ-123 Add new feature
- Creates issue with specific project/jira assign PROJ-123 developer@company.com
- Assigns issue to user by email/jira find developer@company.com
- Search for a user by email address/jira bind PROJ
- Binds current channel to Jira project/jira unbind
- Removes current channel's project binding/jira status
- Shows current project binding and statistics/jira link
- Get links for creating new tasks/jira board
- Get links to Jira boards and backlogs/jira projects
- List all available Jira projects/jira help
- Shows help message
Use these shortcuts for faster issue creation:
/jira bug Title
- Creates a bug issue in mapped project/jira bug PROJECT-KEY Title
- Creates a bug issue in specific project/jira task Title
- Creates a task issue in mapped project/jira task PROJECT-KEY Title
- Creates a task issue in specific project/jira story Title
- Creates a story issue in mapped project/jira story PROJECT-KEY Title
- Creates a story issue in specific project
View comprehensive information about any Jira issue:
/jira view PROJ-123
- View issue details including status, description, comments, and more
Information displayed:
- Summary, Type, Status, Priority
- Assignee and Reporter
- Story Points (if available)
- Labels and Components
- Description
- Recent Comments (last 5)
- Direct link to Jira
/jira create Fix login bug
/jira bug Fix login issue
/jira task Update documentation
/jira story Add new feature
/jira view PROJ-123
/jira create Bug:Fix login bug
/jira create PROJ Story:Add new feature
/jira create Task:Update documentation
/jira create PROJ-456 Add user authentication
/jira create BUG-789 Database connection timeout
/jira assign PROJ-123 developer@company.com
/jira find developer@company.com
/jira bind PROJ
/jira unbind
/jira status
/jira link
/jira board
/jira projects
/jira help
You can specify the issue type using the format TYPE:Title
:
- Task - General tasks and work items
- Bug - Software defects and issues
- Story - User stories and features
- Epic - Large initiatives and projects
- Subtask - Smaller tasks within larger issues
- Improvement - Enhancements and improvements
- New Feature - New functionality and features
If no issue type is specified, it will be determined automatically based on the channel name or default to 'Task'.
Successful issue creation returns:
β
Issue created successfully!
**Issue:** PROJ-123
**Title:** Fix login bug
**Created by:** @alan
**Project:** PROJ
**Type:** Bug
**Reporter:** John Developer (john@company.com)
[View in Jira](https://your-domain.atlassian.net/browse/PROJ-123)
Note: The Reporter field will only appear when the Email Domain setting is configured and a matching Jira user is found.
The plugin provides the following REST API endpoints:
POST /wp-json/jira/mattermost/slash/jira
- Handle slash commandsGET /wp-json/jira/mattermost/slash/mappings
- Get channel mappingsPOST /wp-json/jira/mattermost/slash/mappings
- Add new mappingDELETE /wp-json/jira/mattermost/slash/mappings/{id}
- Delete mapping
The webhook expects these parameters from Mattermost:
token
- Webhook verification tokenchannel_id
- Mattermost channel IDchannel_name
- Mattermost channel nametext
- Command text (e.g., "create Fix login bug")user_name
- Username who executed the command
- All webhook requests are verified using the configured token
- Admin endpoints require WordPress admin capabilities
- Jira API credentials are stored securely in WordPress options
-
"No Jira project mapped to this channel"
This error occurs when you try to create an issue without specifying a project key and the current channel is not bound to any Jira project.
Solutions:
Option A: Bind the channel to a project (Recommended)
- Use
/jira bind PROJECT-KEY
to bind the current channel to a Jira project - Example:
/jira bind PROJ
or/jira bind DEV
- After binding, you can use simple commands like
/jira create Fix login bug
Option B: Specify project key in command
- Use
/jira create PROJECT-KEY Title
to create issues in specific projects - Example:
/jira create PROJ Fix login bug
or/jira create DEV-123 Add feature
Option C: Use admin interface
- Go to Settings > MM Jira Integration > Channel Mappings
- Add a mapping for the channel ID to a Jira project key
To find available project keys:
- Use
/jira projects
to see all available Jira projects and their keys - This will show you the exact project keys you can use
- Use
-
"Jira configuration not set up"
- Configure Jira domain and API key in settings
- Go to Settings > MM Jira Integration and fill in:
- Jira Domain (e.g.,
your-domain.atlassian.net
) - API Key (format:
email:api_token
) - Webhook Token
- Jira Domain (e.g.,
-
"Failed to create issue"
- Check Jira API credentials are correct
- Verify the project key exists in your Jira instance
- Check Jira API permissions for the user
- Use
/jira projects
to verify available project keys - Check WordPress error logs for detailed error messages
-
"Invalid project key format"
- Project keys must contain only uppercase letters and numbers (A-Z, 0-9)
- Project keys must be 10 characters or less
- Use
/jira projects
to see valid project keys - Examples:
PROJ
,DEV
,BUG
,TEST
(valid) vsproject
,PROJECT-KEY
(invalid)
-
"Jira domain not configured"
- Go to Settings > MM Jira Integration
- Set the Jira Domain field (e.g.,
your-domain.atlassian.net
) - Make sure to use the correct domain format without
https://
Enable WordPress debug mode to see detailed error messages:
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
If you're still having issues:
- Check the logs: Go to Settings > MM Jira Integration > Invocation Logs to see detailed request/response logs
- Test connectivity: Use
/jira projects
to test if Jira API is working - Verify credentials: Double-check your Jira domain and API key
- Check permissions: Ensure your Jira user has permission to create issues in the target project
wp-mm-slash-jira/
βββ wp-mm-slash-jira.php # Main plugin file
βββ includes/
β βββ class-wp-mm-slash-jira.php # Main plugin class
β βββ class-wp-mm-slash-jira-admin.php # Admin interface
β βββ class-wp-mm-slash-jira-api.php # API handler
β βββ class-wp-mm-slash-jira-logger.php # Logging functionality
βββ assets/
β βββ admin.js # Admin JavaScript
β βββ admin.css # Admin styles
βββ README.md # This file
The plugin creates a table wp_mm_jira_mappings
with:
id
- Primary keychannel_id
- Mattermost channel IDchannel_name
- Channel display namejira_project_key
- Jira project keycreated_at
- Timestamp
The plugin also creates a table wp_mm_jira_logs
with:
id
- Primary keytimestamp
- When the request was madechannel_id
- Mattermost channel IDchannel_name
- Channel display nameuser_name
- Username who executed the commandcommand
- The slash command textrequest_payload
- Full request payload (JSON)response_payload
- Full response payload (JSON)response_code
- HTTP response codeexecution_time
- Request execution time in secondsstatus
- Success or error statuserror_message
- Error message if applicable
GPL v2 or later
For issues and feature requests, please create an issue in the plugin repository.
Use these curl commands to test the webhook functionality. Replace the placeholders with your actual values:
curl -X POST "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/jira" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=your_webhook_token" \
-d "channel_id=fukxanjgjbnp7ng383at53k1sy" \
-d "channel_name=general" \
-d "text=create Fix login bug" \
-d "user_name=alan"
curl -X POST "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/jira" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=your_webhook_token" \
-d "channel_id=fukxanjgjbnp7ng383at53k1sy" \
-d "channel_name=general" \
-d "text=create PROJ-123 Add new feature" \
-d "user_name=alan"
curl -X POST "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/jira" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=your_webhook_token" \
-d "channel_id=fukxanjgjbnp7ng383at53k1sy" \
-d "channel_name=general" \
-d "text=create Bug:Fix login issue" \
-d "user_name=alan"
curl -X POST "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/jira" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=your_webhook_token" \
-d "channel_id=fukxanjgjbnp7ng383at53k1sy" \
-d "channel_name=general" \
-d "text=create PROJ Story:Add new feature" \
-d "user_name=alan"
# Test bug shortcut
curl -X POST "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/jira" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=your_webhook_token" \
-d "channel_id=fukxanjgjbnp7ng383at53k1sy" \
-d "channel_name=general" \
-d "text=bug Fix login issue" \
-d "user_name=alan"
# Test task shortcut
curl -X POST "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/jira" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=your_webhook_token" \
-d "channel_id=fukxanjgjbnp7ng383at53k1sy" \
-d "channel_name=general" \
-d "text=task Update documentation" \
-d "user_name=alan"
# Test story shortcut
curl -X POST "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/jira" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=your_webhook_token" \
-d "channel_id=fukxanjgjbnp7ng383at53k1sy" \
-d "channel_name=general" \
-d "text=story Add new feature" \
-d "user_name=alan"
# Test shortcut with project key
curl -X POST "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/jira" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=your_webhook_token" \
-d "channel_id=fukxanjgjbnp7ng383at53k1sy" \
-d "channel_name=general" \
-d "text=bug PROJ Fix login issue" \
-d "user_name=alan"
# Test viewing issue details
curl -X POST "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/jira" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=your_webhook_token" \
-d "channel_id=fukxanjgjbnp7ng383at53k1sy" \
-d "channel_name=general" \
-d "text=view PROJ-123" \
-d "user_name=alan"
# Test viewing bug issue
curl -X POST "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/jira" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=your_webhook_token" \
-d "channel_id=fukxanjgjbnp7ng383at53k1sy" \
-d "channel_name=general" \
-d "text=view BUG-456" \
-d "user_name=alan"
# Test viewing story issue
curl -X POST "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/jira" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=your_webhook_token" \
-d "channel_id=fukxanjgjbnp7ng383at53k1sy" \
-d "channel_name=general" \
-d "text=view STORY-789" \
-d "user_name=alan"
curl -X POST "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/jira" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=your_webhook_token" \
-d "channel_id=fukxanjgjbnp7ng383at53k1sy" \
-d "channel_name=general" \
-d "text=assign PROJ-123 developer@company.com" \
-d "user_name=alan"
curl -X POST "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/jira" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=your_webhook_token" \
-d "channel_id=fukxanjgjbnp7ng383at53k1sy" \
-d "channel_name=general" \
-d "text=bind PROJ" \
-d "user_name=alan"
curl -X POST "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/jira" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=your_webhook_token" \
-d "channel_id=fukxanjgjbnp7ng383at53k1sy" \
-d "channel_name=general" \
-d "text=status" \
-d "user_name=alan"
curl -X POST "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/jira" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=your_webhook_token" \
-d "channel_id=fukxanjgjbnp7ng383at53k1sy" \
-d "channel_name=general" \
-d "text=link" \
-d "user_name=alan"
curl -X POST "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/jira" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=your_webhook_token" \
-d "channel_id=fukxanjgjbnp7ng383at53k1sy" \
-d "channel_name=general" \
-d "text=board" \
-d "user_name=alan"
curl -X POST "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/jira" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=your_webhook_token" \
-d "channel_id=fukxanjgjbnp7ng383at53k1sy" \
-d "channel_name=general" \
-d "text=help" \
-d "user_name=alan"
curl -X GET "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/mappings" \
-H "X-WP-Nonce: your_nonce_here" \
-H "Authorization: Bearer your_auth_token"
curl -X POST "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/mappings" \
-H "Content-Type: application/json" \
-H "X-WP-Nonce: your_nonce_here" \
-d '{
"channel_id": "fukxanjgjbnp7ng383at53k1sy",
"channel_name": "general",
"jira_project_key": "PROJ"
}'
curl -X DELETE "https://your-wordpress-site.com/wp-json/jira/mattermost/slash/mappings/1" \
-H "X-WP-Nonce: your_nonce_here"
You can also use the included test-webhook.php
script for quick testing:
php test-webhook.php
For a more interactive testing experience, use the web-based test interface:
- Access the interface: Navigate to
wp-content/plugins/wp-mm-slash-jira/test-interface.php
in your browser - Login: You must be logged in as a WordPress administrator
- Configure settings: Set your channel ID, channel name, and username
- Test commands: Use the quick command buttons or type commands manually
- View responses: See real-time responses in a chat-like interface
Features:
- π― Chat-like interface - Simulates Mattermost experience
- β‘ Quick commands - One-click testing of common commands
- π§ Configurable settings - Test different channels and users
- π Status indicators - Shows plugin configuration status
- π Response details - View full API responses
- π± Responsive design - Works on desktop and mobile
Usage:
- Open the test interface in your browser
- Configure channel settings on the left sidebar
- Click quick commands or type custom commands
- View responses in the chat area
- Click "Show Response Details" to see full API data
Example workflow:
- Set channel name to "general"
- Click "bind PROJ" to bind the channel
- Click "create Fix login bug" to create an issue
- Click "status" to check the binding
- View all responses in the chat interface
{
"response_type": "in_channel",
"text": "β
Issue created successfully!\n\n**Issue:** PROJ-123\n**Title:** Fix login bug\n**Created by:** @alan\n**Project:** PROJ\n\n[View in Jira](https://your-domain.atlassian.net/browse/PROJ-123)"
}
{
"response_type": "ephemeral",
"text": "β No Jira project mapped to this channel. Please add a mapping or specify a project key."
}
Before testing, ensure:
- β Plugin is activated
- β Jira domain and API key are configured
- β Webhook token is set
- β Channel mappings are added (or use specific project keys)
- β WordPress debug mode is enabled for detailed error messages
- β Logging is enabled to capture test requests
- 403 Forbidden: Check webhook token and WordPress permissions
- 404 Not Found: Verify the REST API endpoint URL
- 500 Internal Server Error: Check WordPress error logs
- Jira API Errors: Verify Jira credentials and project keys