A bot (web-service) which:
src/locales
).Riot
as synonym)package.json
and run npm install
.config.js
using this example.npm run start
.well connected
in logs you can create some example issue in Jira. If all is OK you have to be invited in room with such name in your Matrix client!You can use one or several. If you use several bots - distribute rooms between them. Add bots to config:
...
// Matrix params
messenger: {
// users with admin status
admins: ['admin'],
// messenger name
name: 'matrix',
// messenger domain
domain: 'matrix.example.org',
// short name, before colomn, without @
user: 'jira_bot',
// password
password: 'key',
bots: [
{
user: 'jira_bot2',
password: 'key',
},
{
user: 'jira_bot3',
password: 'key',
},
],
infoRoom: {
users: ['tt_test1', 'tt_test2'],
name: 'INFO',
},
},
Bots start asynchronously together, but queue processing starts after all bots start. Time of starting depence of count room.
Logs after starting all bots:
well connected
2019-11-20 09:49:58.520 matrix-bots fluentd messenger-api
Matrix bot jira_bot was connected on 1 min 12 sec
2019-11-20 09:49:58.522 matrix-bots fluentd /fsm/index.js
well connected
2019-11-20 10:05:48.267 matrix-bots fluentd messenger-api
Matrix bot jira_bot_2 was connected on 17 min 2 sec
2019-11-20 10:05:48.272 matrix-bots fluentd /fsm/index.js
well connected
2019-11-20 10:11:09.108 matrix-bots fluentd messenger-api
Matrix bot jira_bot_3 was connected on 22 min 23 sec
2019-11-20 10:11:09.109 matrix-bots fluentd /fsm/index.js
All matrix bots were connected on 22 min 23 sec
2019-11-20 10:11:09.111 matrix-bots fluentd /fsm/index.js
All chat bot are connected!!!
After starting bot listen to all Jira webhooks.
It means that all actions in your Jira server will be followed with webhooks. Its body we parse and save to Redis and if user is not ignored or issue is not private (it's very important for next gen Jira in cloud).
If user is ignored or issue is private we can log:
username: <name>, creator: <creator>, ignoreStatus: true
timestamp: <timestamp>, webhookEvent: <webhook_event>, issueName: <issue_name>, ignoreStatus: true
ignoreStatus: true
is set depending on:
usersToIgnore
and testMode.users
). Use for dev mode.Redis data is handled:
After succedded handling Redis records you can see logs with every key and result of handling:
Result of handling redis key <redisKey> --- <true/false>
If handling is succedded data will be removed, if staus is false
it will be in Redis and next time will be handled again. It lets us to prevent some problems with connections to matrix for example.
Work with Riot
is based on input command in room with Bot.
All commands are available only in rooms with Bot and that compares with Jira.
Get all commands and their rules to use in Riot
you can get with first command - !help
.
If you use command not correct you will get message:
Command <command name> not found
If your command is correct you will see message with info about it.
More info about all commands you can get here
To work with Riot
we use SDK Matrix. Starting bot connect to matrix domain from config as user like @${config.matrix.user}:${config.matrix.domain}
. After succedded connection you will see in logs:
createClient OK BaseUrl: https://<domain>, userId: @<user_name>:<domain>
Started connect to chatApi
Got push rules
well connected
If something is wrong in connection you will get error:
createClient error. BaseUrl: ${baseUrl}, userId: ${userId}
When Bot is stopped:
Disconnected from Matrix
To be sure that no data is lost we use Redis to save parsed webhooks. Prefix in Redis which all data is saved is in config as redis.prefix
.
Structure of records:
<function_handler>_<jira_body_timestamp>
{
funcName: <function_handler>,
data: <parsed webhook data>,
}
jira-to-matrix.service
with your configurationjira-to-matrix.service
to /etc/systemd/system/
and enable it# Add user jira-matrix-bot without homedirectory and deny system login
$ sudo useradd -M useradd -M jira-matrix-bot
$ sudo usermod -L jira-matrix-bot
# Change directory owner to new created user
$ sudo chown -R jira-matrix-bot: /path/to/jira-to-matrix
# Modify service config
$ vi /path/to/jira-to-matrix/jira-to-matrix.service
# change User, WorkingDirectory, ExecStart
# Copy service definition to systemd directory
$ sudo cp /path/to/jira-to-matrix/jira-to-matrix.servce /etc/systemd/system
# Enable connections to bot with Jira webhook (tcp port 4100, see your config.js)
$ sudo firewall-cmd --zone=public --add-port=4100/tcp --permanent
# Add permissions for SELinux (tcp port 4100, see your config.js)
$ sudo semanage port -a -t http_port_t -p tcp 4100
# Enable service to run at startup
$ sudo systemctl enable jira-to-matrix
# Start service
$ sudo systemctl start jira-to-matrix
More information is here
The project is in a rough shape and under active development. Fixed
It is successfully deployed in a medium-size company.
Developed with Node 8.1. Probably will work on any version having async/await.