Hubot Jira Bot

Lets you search for JIRA tickets, open them, transition them thru different states, comment on them, rank them up or down, start or stop watching them or change who is assigned to a ticket. Also, notifications for assignments, mentions and watched tickets.

###Dependencies:

moment
octokat
node-fetch
underscore
fuse.js

###Configuration:

HUBOT_GITHUB_ORG - Github Organization or Github User
HUBOT_GITHUB_TOKEN - Github Application Token
HUBOT_JIRA_GITHUB_DISABLED - Set to true if you wish to disable github integration
HUBOT_JIRA_PASSWORD
HUBOT_JIRA_PRIORITIES_MAP [{"name":"Blocker","id":"1"},{"name":"Critical","id":"2"},{"name":"Major","id":"3"},{"name":"Minor","id":"4"},{"name":"Trivial","id":"5"}]
HUBOT_JIRA_PROJECTS_MAP {"web":"WEB","android":"AN","ios":"IOS","platform":"PLAT"}
HUBOT_JIRA_TRANSITIONS_MAP [{"name":"triage","jira":"Triage"},{"name":"icebox","jira":"Icebox"},{"name":"backlog","jira":"Backlog"},{"name":"devready","jira":"Selected for Development"},{"name":"inprogress","jira":"In Progress"},{"name":"design","jira":"Design Triage"}]
HUBOT_JIRA_TYPES_MAP {"story":"Story / Feature","bug":"Bug","task":"Task"}
HUBOT_JIRA_URL https://jira-domain.com:9090
HUBOT_JIRA_USERNAME
HUBOT_JIRA_FIELDS customize the jira fields returned by api, defaults to: ["issuetype", "status", "assignee", "reporter", "summary", "description", "labels", "project"]
HUBOT_SLACK_BUTTONS {"watch":{"name":"watch","text":"Watch","type":"button","value":"watch","style":"primary"},"assign":{"name":"assign","text":"Assign to me","type":"button","value":"assign"},"devready":{"name":"devready","text":"Dev Ready","type":"button","value":"selected"},"inprogress":{"name":"inprogress","text":"In Progress","type":"button","value":"progress"},"rank":{"name":"rank","text":"Rank Top","type":"button","value":"top"},"running":{"name":"running","text":"Running","type":"button","value":"running"},"review":{"name":"review","text":"Review","type":"button","value":"review"},"resolved":{"name":"resolved","text":"Resolved","type":"button","style":"primary","value":"resolved"},"done":{"name":"done","text":"Done","type":"button","style":"primary","value":"done"}}
HUBOT_SLACK_PROJECT_BUTTON_STATE_MAP {"PLAT":{"inprogress":["review","running","resolved"],"review":["running","resolved"],"running":["resolved"],"resolved":["devready","inprogress"],"mention":["watch","assign","devready","inprogress","rank"]},"HAL":{"inprogress":["review","running","resolved"],"review":["running","resolved"],"running":["resolved"],"resolved":["devready","inprogress"],"mention":["watch","assign","devready","inprogress","rank"]},"default":{"inprogress":["review","done"],"review":["done"],"done":["devready, inprogress"],"mention":["watch","assign","devready","inprogress","rank"]}}
HUBOT_SLACK_VERIFICATION_TOKEN - The slack verification token for your application

Note that HUBOT_JIRA_USERNAME should be the JIRA username, this is not necessarily the username used if you log in via the web. To determine a user's username, log in as that user via the web, and check the user profile. Frequently, users may log in using an email address such as 'bob@somewhere.com' or a stem, such as 'bob'; these may or may not match the username in JIRA.

####A note about chat:jira user lookup In order for direct messages (notifications) and a few other username based commands to work JiraBot attempts to match JIRA users with chat users by email address. This has been tested primarily on the Hubot Slack adapter and may not work without modification on others. The take away is that you must have the same e-mail address on both services for this to work as expected.

####Notifications via Webhooks In order to receive JIRA notifications you will need to setup a webhook. You can find instructions to do so on Atlassian's website. You will need your hubot to be reachable from the outside world for this to work. JiraBot is listening on /hubot/jira-events. Currently the following notifications are available:

You are mentioned in a ticket in either the description or in a comment
You are assigned to a ticket
The following notifications apply if you are assigned to the ticket:
- A new comment is left on the ticket
The following notifications apply if you are watching the ticket in question:
- Work begins on the ticket (enters the In Progress state or similar)
- The ticket is closed
- A new comment is left on the ticket

###The Definitive hubot JIRA Manual @hubot can help you search for JIRA tickets, open them, transition them thru different states, comment on them, rank them up or down, start or stop watching them or change who is assigned to a ticket

####Opening Tickets

hubot [<project>] <type> <title> [<description>]

You can omit <project> when using the command in the desired projects channel Otherwise you can specify one of the following for <project>: #web, #android, #ios, #platform <type> is one of the following: story, bug, task <description> is optional and is surrounded with single or triple backticks and can be used to provide a more detailed description for the ticket. <title> is a short summary of the ticket

#####Optional <title> Attributes

Labels: include one or many hashtags that will become labels on the jira ticket #quick #techdebt

Assignment: include a handle that will be used to assign the ticket after creation @username

Transitions: include a transition to make after the ticket is created >triage, >icebox, >backlog, >devready, >inprogress, >design

Priority: include the ticket priority to be assigned upon ticket creation !blocker, !critical, !major, !minor, !trivial

####Creating Sub-tasks

hubot subtask <ticket> <summary>

Where <ticket> is the parent JIRA ticket number and <summary> is a short summary of the task

####Cloning Tickets

<ticket> clone to <channel> <ticket> > <channel>

Where <ticket> is the JIRA ticket number and <channel> is one of the following: #web, #android, #ios, #platform

####Ranking Tickets

<ticket> rank top <ticket> rank bottom

Where <ticket> is the JIRA ticket number. Note this will rank it the top of column for the current state

####Commenting on a Ticket

<ticket> < <comment>

Where <ticket> is the JIRA ticket number and <comment> is the comment you wish to leave on the ticket

####Adding labels to a Ticket

<ticket> < #label1 #label2 #label3

Where <ticket> is the JIRA ticket number

####Assigning Tickets

<ticket> assign @username

Where <ticket> is the JIRA ticket number and @username is a user handle

####Transitioning Tickets

<ticket> to <state> <ticket> ><state>

Where <ticket> is the JIRA ticket number and <state> is one of the following: triage, icebox, backlog, devready, inprogress, design

####Watching Tickets

<ticket> watch [@username]]

Where <ticket> is the JIRA ticket number @username is optional, if specified the corresponding JIRA user will become the watcher on the ticket, if omitted the message author will become the watcher

####Ticket Notifications

Whenever you begin watching a JIRA ticket you will be notified (via a direct message from @hubot) whenever any of the following events occur: - a comment is left on the ticket - the ticket is in progress - the ticket is resolved

You will also be notified if: - you are mentioned on the ticket - you are assigned to the ticket

If you are assigned to a ticket, you will be notified when: - a comment is left on the ticket

To enable or disable this feature you can send the following directly to hubot:

jira disable notifications

or if you wish to re-enable

jira enable notifications

####Searching Tickets

hubot jira search <term>

#####Optional <term> Attributes Labels: include one or many hashtags that will become labels included in the search #quick #techdebt

Where <term> is some text contained in the ticket you are looking for##Documentation with Configuration examples from above

marchfederico/hubot-jira-bot

Hubot Jira Bot