digitalicagroup/redmine-command

Redmine-Slack integration to manage issues

Redmine Command

A simple Redmine slack integration to manage issues., _(*1)

Uses * One Slack "Slash Commands" and one "Incoming WebHooks" integration (see Install). * php-redmine-api * KLogger, _(*2)

How does it work? * It installs as a PHP application on your web server (using composer). * Through a "Slash Commands" Slack integration, it receives requests. * It communicates with your redmine installation to gather (or update) data. * Posts the results to an "Incoming WebHooks" Slack integration in the originator's channel or private group (yeah, private group!)., _(*3)

Current Features

The current stable release implements an extensible architecture that support easy implementation of future commands. Commands list: * show . Shows all the details in a redmine issue(s). * ussage (from slack): /redmine show issue_numbers * example: /redmine show 1 2 10 * help . Shows the help data from every registered command. * ussage: /redmine help, _(*4)

TODO

• Move all strings variables to a global definitions file.
• Implement more commands. The current work in progress centers around creating issues.

Requirements

• PHP >= 5.4 with cURL extension,
• "Enable REST web service" on your redmine settings (Administration > Settings > Authentication)
  • Your "API access key" from your profile page.
• Slack integrations (see install).

Install

On Slack

• Create a new "Slash Commands" integration with the following data:, _(*5)

  • Command: /redmine (or whatever you like)
  • URL: the URL pointing to the index.php of your redmine-command install
  • Method: POST
  • Token: copy this token, we'll need it later.

• Create a new "Incoming WebHooks" slack integration:, _(*6)

  • Post to Channel: Pick one, but this will be ignored by redmine-command.
  • Webhook URL: copy this URL, we'll need it later.
  • Descriptive Label, Customize Name, Customize Icon: whatever you like.

• Go to Slack API and copy the authentication token for your team., _(*7)

• Go to your profile page on Redmine and copy your "API access key"., _(*8)

On your web server

Install composer in a folder of your preference (should be accessible from your web server) then run:, _(*9)

$ php composer.phar require digitalicagroup/redmine-command:~0.1
$ cp vendor/digitalicagroup/redmine-command/index.php .

The last line copies index.php from the package with the configuration you need to modify., _(*10)

Edit index.php and add the following configuration parameters:, _(*11)

/**
 * token sent by slack (from your "Slash Commands" integration).
 */
$config->token =              "vuLKJlkjdsflkjLKJLKJlkjd";

/**
 * URL of the Incoming WebHook slack integration.
 */ 
$config->slack_webhook_url =  "https://hooks.slack.com/services/LKJDFKLJFD/DFDFSFDDSFDS/sdlfkjdlkfjLKJLKJKLJO";

/**
 * Slack API authentication token for your team.
 */
$config->slack_api_token =    "xoxp-98475983759834-38475984579843-34985793845";

/**
 * Base URL of redmine installation.
 */
$config->redmine_url =        "https://your/redmine/install";

/**
 * Redmine API key.
 */
$config->redmine_api_key =    "0d089u4sldkfjfljlksdjffj43099034j";

/**
 * Log level threshold. The default is DEBUG.
 * If you are done testing or installing in production environment,
 * uncomment this line.
 */
//$config->log_level =           LogLevel::WARNING;

/**
 * logs folder, make sure the invoker have write permission.
 */
$config->log_dir =            "/srv/api/redmine-command/logs";

Make sure you give write permissions to the log_dir folder., _(*12)

Troubleshooting

This is a list of common errors: * "I see some errors about permissions in the apache error log". * The process running redmine-command (usually the web server) needs write permissions to the folder configured in you $config->log_dir parameter. * For example, if you are running apache, that folder group must be assigned to www-data and its write permission for groups must be turned on. * "I followed the steps and nothing happens, nothing in web server error log and nothing in the app log". * If you see nothing in the logs (and have the debug level setted), may be the app is dying in the process of validating the slack token. redmine-command validates that the request matches with the configured token or the app dies at the very beginning. * "There is no error in the web server error log, I see some output in the app log (with the debug log level), but i get nothing in my channel/group". * Check in the app log for the strings "[DEBUG] Util: group found!" or "[DEBUG] Util: channel found!" . If you can't see those strings, check if your slack authentication token for your team is from an user that have access to the private group you are writing from. * I just developed a new command but I am getting a class not found error on CommandFactory. * Every time you add a new command (hence a new class), you must update the composer autoloader. just type: * php composer.phar update, _(*13)

Contribute

If you want to add aditional commands, your are welcome to contribute. All you need to do is extend the AbstractCommand class, and add a new entry to the commands_definition.json file. (You can see CmdShow.php for an example of what a command must do)., _(*14)

All commands are received through the same "Slash Command Integration", so the first word after the /redmine must be the command trigger. The next words are splited by one or more spaces and passed to the command that triggered., _(*15)

The active development is done under the unstable branch. And the last stable release candidate is in the master branch., _(*16)

About Digitalica

We are a small firm focusing on mobile apps development (iOS, Android) and we are passionate about new technologies and ways that helps us work better. * This project homepage: RedmineCommand * Digitalica homepage: digitalicagroup.com, _(*17)