Jira Sidebarchat Integration


Main features:

  • Works with Grape Cloud/On-Premise and Jira On-Premise

  • Chats can be created with the click of a button in Jira

  • The chat is embedded as a sidebar in Jira

  • Users from Jira fields that contain users or groups can be automatically added

  • Watchers are added to the chat and un-watching removes a user from the chat


  • Jira Fields with users or groups that are automatically synced to chat groups can be selected per project, including custom fields.

  • Individual users can be added manually to a specific chat by pression the cogwheel next to the Grape button in Jira

  • The add-on can be enabled for certain groups only, so you can test it with a subset of your Jira users.


  • Sidebar chat

    Jira sidebar Chat

  • Same chat in Grape

    Same chat in Grape

  • Button to create chat

    Grape Create Button

  • Adding/removing individual users

    Grape Add Individual Users


  • Jira On-Premise Server

  • Jira admin account

  • Grape admin account

  • Network: Jira Server can talk to Grape Server over HTTPS

  • Jira users exist in Grape (ideal: central user management), see “How are Jira users matched to Grape users?” below


  • Doesn’t work with Jira Cloud

  • The Organization id can be set at the add-on level, not at project level.

  • The Auth Token is not refreshed automatically. It can be manually changed in Grape and in Jira.

Administrator Setup (Sidebar Chat)

  1. create a separate Bot user in Grape who will be used to create the Jira groups:

    1. Click the cogwheel in the Chat

    2. Click Integrations

    3. Scroll down to “Bot API” and click on “Bot API”

    4. Click “Create new Bot” (“Neuen Bot erstellen”)

      • Enter a name, e.g. “Jira Integration Service User”

      • upload an avatar image (this will displayed in the members list in each group that the bot creates)

      • Save

    5. Scroll down to your bot, click the eye button to see the token.

    6. Copy the token

  2. Set up an Application link

    Note: you can reuse the application link for the Jira Integration with Grape Search and Actvities if you have already created this. Make sure the application link’s name is “Grape” and it is set to primary.

    To create a fresh application link do the following:

    1. In Jira’s admin interface, go to “Applications” –> “Application links”

    2. Enter your Grape Server’s URL, e.g. https//grape.example.com and click “Create new link”

    3. If Jira warns you about redirects, check “Use this URL” and click “Continue”

    4. Enter “Grape” as name (don’t change the name!) and click “continue”

    5. Make it a primary link: In the application link table, click the three-dots menu button in the row of the newly created link and click “Make primary”

    6. Disable and enable the addon each time you change a setting Grape App Link

  3. Install add-on jar file

    1. In Jira’s admin interface, go to “Add-ons” –> “Manage apps”

    2. Click “Upload app”

    3. Paste into the “From this URL” input: https://www.chatgrape.com/download/grape-jira.jar and press “Upload” (or download grape-jira.jar and upload it to Jira)

  4. Click “Grape Settings” in the sidebar

    addon settings

    • URL: Use the Grape URL inlcuding organization subdomain: e.g. https://company.chatgrape.com

      • if you run in single organization mode you don’t have a organization subdomain)

      • no trailing /

    • organization id:

      • 1 if you are running Grape Server.

      • for cloud users:

        1. Open the chat in the browser, view the source code (Chrome/Firefx on Windows: CTRL + U. On macOS Command + Option + U)

        2. search for "organization" (with quotation marks)

        3. find your id:


    • auth token: the token from your Bot user

  5. Allow the Grapechat to be embedded in Jira:

    1. Enter grape configure --reconfigure in your shell on your Grape server.

    2. Press enter until you reach the question Hosts to add to the CORS whitelist:

    3. Enter the Server name, e.g. jira.YOURCOMPANY.com. IMPORTANT: If you had some previous Hosts entered, the setup will display them to you. In this case you have to copy them in your input field, e.g. jira.YOURCOMPANY.com, confluence.YOUR-COMPANY.com, sharepoint.YourCompany.com.

    4. After navigating through the setup, enter grape install and you are done!

  6. Optional: configure project specific settings:

    1. Open “Project Settings” for your Jira project

    2. click “Grape settings” in the menu

  7. Test the integration:

    1. Open/create an issue in Jira

    2. Click the “Create Grape Chat” button on right side.

User Setup

No users setup needed.


How are Jira users matched to Grape users?

Users are matched by email only, so it’s recommended to use a central source of users for both Jira and Grape, like Crowd or Active Directory to make sure that users exist in both Jira and Grape, with the same email address.

Migrating from one service user to another one

If you have already created rooms with the Jira integration but want to change the service user that is used to create the rooms, you need to assign all existing rooms to the new user.

  1. Copy the following code to a text editor and adjust the first three variables. You can find the user ids in the Django Admin (grape.example.com/admin).

    organization_id = 1
    old_user_id = 123
    new_user_id = 456
    rooms = Room.objects.filter(is_managed=True, organization_id=organization_id, creator_id=old_user_id)
    for room in rooms:
    input('\nThose %s rooms will be changed. Press any key to continue or ctrl+c to cancel' % rooms.count())
    for room in rooms:
        room.creator_id = new_user_id
  2. SSH into your server and open a Django shell on your server.

  3. Copy & paste the code and press Enter twice to run the code and Enter again to confirm the changes.