{"id":13764637,"url":"https://github.com/ModusCreateOrg/ciscospark-jira","last_synced_at":"2025-05-10T19:31:39.435Z","repository":{"id":70965751,"uuid":"87552726","full_name":"ModusCreateOrg/ciscospark-jira","owner":"ModusCreateOrg","description":"JIRA bot for Cisco Spark","archived":true,"fork":false,"pushed_at":"2017-11-22T20:34:32.000Z","size":147,"stargazers_count":8,"open_issues_count":1,"forks_count":6,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-02-02T11:01:55.658Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ModusCreateOrg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2017-04-07T14:05:20.000Z","updated_at":"2024-02-22T17:28:53.000Z","dependencies_parsed_at":"2023-03-11T09:34:06.191Z","dependency_job_id":null,"html_url":"https://github.com/ModusCreateOrg/ciscospark-jira","commit_stats":null,"previous_names":["moduscreateorg/ciscospark-jira","promptworks/ciscospark-jira"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ModusCreateOrg%2Fciscospark-jira","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ModusCreateOrg%2Fciscospark-jira/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ModusCreateOrg%2Fciscospark-jira/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ModusCreateOrg%2Fciscospark-jira/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ModusCreateOrg","download_url":"https://codeload.github.com/ModusCreateOrg/ciscospark-jira/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253470982,"owners_count":21913771,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T16:00:24.474Z","updated_at":"2025-05-10T19:31:39.135Z","avatar_url":"https://github.com/ModusCreateOrg.png","language":"JavaScript","funding_links":[],"categories":["Code samples"],"sub_categories":["Bot samples"],"readme":"# Jira bot for Cisco Spark\n\n[![CircleCI](https://circleci.com/gh/promptworks/ciscospark-jira.svg?style=svg)](https://circleci.com/gh/promptworks/ciscospark-jira)\n\nThis is a self-hosted bot for Cisco Spark that integrates with Jira.\n\n[![Deploy](https://www.herokucdn.com/deploy/button.png)](https://heroku.com/deploy)\n\n# Features\n\nThis bot allows developers and project managers to work seamlessly with Jira directly from\nCisco Spark.\n\nWith this bot, you can:\n\n* create new tickets\n* list assigned tickets\n* get requested details about a ticket\n* assign, comment on, or update the status of a ticket\n* receive updates on Jira tickets as they happen\n\nwithout having to leave your Spark channel.\n\n![example use](https://user-images.githubusercontent.com/1062277/27293924-d3e1b5b2-54e5-11e7-8243-5fc8fa1cdd3a.png)\n\nThe bot is designed so that you can deploy the bot yourself so you can maintain\nfull control over the bot and its access to your data.\n\n## Spark Configuration\n\nIn order for the bot to communicate with Cisco Spark, a couple configuration values\nare expected to exist in the environment (or `.env` or `.env.local` files):\n\n* `PUBLIC_ADDRESS` - the address at which your bot can be reached.\n* `ACCESS_TOKEN` - the bot's access token from Cisco Spark\n* `SPARK_SECRET` - [secret for validating the origin of\n  webhooks](https://developer.ciscospark.com/webhooks-explained.html#auth)\n* `LIMIT_TO_ORG` - (optional) ID of the organization that the bot should reply\n  to. Users not in this org sending messages to the bot will receive no reply.\n* `LIMIT_TO_DOMAIN` - (optional) Email domain(s) of users that can message the\n  bot. Users whose email is not in one of these domains are ignored by the bot.\n  If multiple domains are supported, they should be specified as a space-separated\n  list of domains (`\"example.com example2.com\"`).\n\n## Jira Configuration\n\nIn order for the bot to talk with Jira a couple configuration values are required:\n\n* `JIRA_HOST` - the URL to the Jira instance\n  (`https://YOUR_SUBDOMAIN.atlassian.net` for example)\n* `JIRA_USERNAME` and `JIRA_PASSWORD` - the username and password used to\n  authenticate with the Jira API. Changes made to Jira will be performed by\n  this user, so you may want to create a special bot account.\n\n### Jira Webhooks\n\nTo be notified of events via webhooks, you must\n[register\nthe webhook via the Jira administration console](https://developer.atlassian.com/jiradev/jira-apis/webhooks#Webhooks-jiraadmin).\n\nIf the bot's Jira account is an administrator, the bot can do this itself when\nyou tell it to `setup webhooks`.\n\nIf the bot is not an administrator, you must setup up webhooks manually.\nThe URL should be `\u003cPUBLIC_ADDRESS\u003e/jira/receive`, where `\u003cPUBLIC_ADDRESS\u003e` is\nthe same URL as specified above. Be sure to select the notifications that you\nwant to receive in the administration console.\n\nOnce the webhooks are setup in Jira, you can use the `watch` command with the bot\nto receive notifications of updates to the watched issues. The updates will be\nposted to whichever room the command was given in.\n\nAdditionally, you can specify a room to receive all webhook notifications.\nThis is done using the `JIRA_WEBHOOK_ROOM` environment variable and should\nbe the ID of the room you want notifications posted to. A script to list rooms\nand their IDs (`yarn list-rooms`) has been included to make finding the desired\nroom ID easier.\n\n## Deploying your own bot\n\nHere are instructions for deploying on Heroku, but this can be adapted to any host.\n\n1. [Create a new bot account](https://developer.ciscospark.com/add-bot.html) on Cisco Spark\n1. Clone this repo\n1. Create a new app on heroku\n\n        heroku apps:create my-spark-bot\n\n1. Add a Redis addon\n\n        heroku addons:create heroku-redis:hobby-dev\n\n1. Add environment variables to the heroku app to match those in `.env`.\n   e.g.\n\n        heroku config:add PUBLIC_ADDRESS=https://my-spark-bot.herokuapp.com\n        heroku config:add JIRA_HOST=https://test.atlassian.net\n\n1. Push to heroku\n\n        git push heroku\n\n1. Add your bot to your space.\n\n## Running the bot via Docker\n\nA Dockerfile has been included to run the bot via Docker. Here are some basic\ninstructions on running the bot via Docker locally.\n\n1. [Create a new bot account](https://developer.ciscospark.com/add-bot.html) on Cisco Spark\n1. Clone this repo\n1. Build the Docker image:\n\n        docker build -t myjirabot .\n\n1. Copy `.env` to `.env.local` and customize\n\n        cp .env .env.local\n\n1. Run the Docker image, specifying the newly created env file:\n\n        docker run -it --env-file .env.local myjirabot\n\n## Development\n\n### Work on the bot\n\n\n1. [Create a new bot account](https://developer.ciscospark.com/add-bot.html) on Cisco Spark\n\n1. Clone this repo\n\n1. Install dependencies\n\n        yarn install\n\n1. Copy `.env` to `.env.local` and customize\n\n        cp .env .env.local\n\n1. Start the local development server\n\n        yarn server-dev\n\n1. If using Docker, you can run the image specifying the environment file and\n   exposing port 3000:\n\n        docker run -it --env-file .env.local --publish 3000:3000 myjirabot\n\n1. Run ngrok (or something like it).\n\n    Because Spark uses webhooks to talk to bots, you must run something like\n    ngrok locally to expose your server to the web.  We've included a script to\n    do this for you (requires ngrok)\n\n        yarn ngrok\n\n\n### Tests\n\nRun the tests:\n\n    yarn test\n\nRun the test watcher, which will re-run tests after every file change:\n\n    yarn test-watch\n\n\n### Code Structure\n\nThe code is laid out with the following structure:\n\n```\nsrc\n├── attachHandlers.js  # Where all the phrases that will invoke handlers are specified\n├── controller.js      # Creates the botkit `sparkbot` controller, configured via the env\n├── handlers           # Directory containing all the functions that handle messages/webhooks received\n│   ├── index.js       # Contains generic message handlers (\"help\", for example)\n│   ├── issues.js      # All message handlers related to issue management\n│   └── webhooks.js    # All webhook handlers\n├── index.js           # The entry point of the bot\n├── jira.js            # Wrapper around Jira API\n└── server.js          # Webserver that handles incoming Spark messages and Jira webhooks\n```\n\nSeparating the handlers from the controller (in this case, specifying expected phrases\nin `attachHandlers.js`) allows us to test the pattern matching (in `tests/attachHandlersTest.js`)\nseparate from the functionality of the handler (in `tests/handlers/*.js`).\n\n\n### Adding more commands\n\nAdding a new command requires two steps: writing a new handler and attaching that handler to the bot.\n\n#### 1. Write a new handler\n\nAdd a function in `src/handlers/` that will handle the message from Spark. The\nfunction should take two arguments, the `bot` (the botkit instance) and the\n`message` (that invoked this handler).\n\nThe handler will be passed as the `callback` argument to [the botkit\n`hears`](https://github.com/howdyai/botkit/blob/fca645275c8d3ed462110062dcda8e804da77bb0/docs/readme.md#matching-patterns-and-keywords-with-hears)\nfunction, so the `message` argument will contain any available \"match\" information.\n\nTo send a reply to the message, you can use the `bot.reply` method, passing in the\noriginal message (so the bot knows where to send the reply to) and the intended\nreply: `bot.reply(message, \"Hello World\")`.\n\n#### 2. Attach the new handler\n\nNow that we have a function to reply to a message, we need to tell the botkit\ncontroller when to invoke the function. This is accomplished by adding to\n`src/attachHandlers.js`.\n\nFor example, if we added a `helloWorldHandler` in `src/handlers/index.js`, we could\nadd the following line to invoke our new command when a user says \"hello\" to our bot:\n\n```javascript\ncontroller.hears(['hello'], 'direct_mention,direct_message', handlers.helloWorldHandler)\n```\n\n\n### Adding more webhooks\n\nSimilar to adding a new command, adding a new webhook is a two-step process. First,\nwe need to add a handler for the incoming webhook notification and then tell\nbotkit when to invoke our handler.\n\n#### 1. Write a new handler\n\nYou can add a new function in `src/handlers/webhooks.js` that accepts two parameters:\n`bot`, the botkit instance and `event` the JSON body of the webhook notification\nfrom Jira.\n\nIn order to send a message, we need to know which room to post the webhook notifications\nto, specified by the `JIRA_WEBHOOK_ROOM` environment variable. For your convenience,\na `replyToWebhook` function exists that accepts the `bot` and the intended reply\nand looks up the correct room to post to for you.\n\n#### 2. Attach the webhook handler\n\nNow that we have the webhook handler, we need to tell botkit when to invoke our\nhandler. This is again done in `src/attachHandlers.js`.\n\nRather than using `hears`, we can use the `on` function to invoke our handler\nwhen the webhook event comes in. When a webhook is received, an event is triggered\nwith the name of the webhook event.\n\nFor example, to respond to a `issue_created` event, we can add the following line:\n\n```javascript\ncontroller.on('jira:issue_created', handlers.webhooks.issueCreatedHandler)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FModusCreateOrg%2Fciscospark-jira","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FModusCreateOrg%2Fciscospark-jira","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FModusCreateOrg%2Fciscospark-jira/lists"}