Jira Sidebarchat Integration¶
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.
Same chat in Grape
Button to create chat
Adding/removing 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)¶
create a separate Bot user in Grape who will be used to create the Jira groups:
Click the cogwheel in the Chat
Scroll down to “Bot API” and click on “Bot API”
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)
Scroll down to your bot, click the eye button to see the token.
Copy the token
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:
In Jira’s admin interface, go to “Applications” –> “Application links”
Enter your Grape Server’s URL, e.g. https//grape.example.com and click “Create new link”
If Jira warns you about redirects, check “Use this URL” and click “Continue”
Enter “Grape” as name (don’t change the name!) and click “continue”
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”
Disable and enable the addon each time you change a setting
Install add-on jar file
In Jira’s admin interface, go to “Add-ons” –> “Manage apps”
Click “Upload app”
Paste into the “From this URL” input:
https://www.chatgrape.com/download/grape-jira.jarand press “Upload” (or download grape-jira.jar and upload it to Jira)
Click “Grape Settings” in the sidebar
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)
1if you are running Grape Server.
for cloud users:
Open the chat in the browser, view the source code (Chrome/Firefx on Windows: CTRL + U. On macOS Command + Option + U)
"organization"(with quotation marks)
find your id:
auth token: the token from your Bot user
Allow the Grapechat to be embedded in Jira:
grape configure --reconfigurein your shell on your Grape server.
Press enter until you reach the question
Hosts to add to the CORS whitelist:
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.
After navigating through the setup, enter
grape installand you are done!
Optional: configure project specific settings:
Open “Project Settings” for your Jira project
click “Grape settings” in the menu
Test the integration:
Open/create an issue in Jira
Click the “Create Grape Chat” button on right side.
Administrator Setup (Grape Search)¶
Open Django Admin (https://yourGrapeServer/admin)
Find “External search configs” and click “add”
Fill out the form:
Organization: click the Search icon and click on your organization in the pop up. It’s probably “1”.
Verbose Name: “Jira” or “Jira Instance X” or something like that. This text will be shown in the grape search list of connected services and can be changed any time.
Key: “jira” or similar. This must be unique and will not be visible to the user.
URL: Paste the URL that is displayed in the Jira plugin settings:
Access token: Paste the Bot token here that you also pasted into the plugin.
Impersonation: select “email”
Explicit: Check this if you want your users to explicitly filter for this integration in the Grape search. If this is not checked, Jira search results will appear in every (unfiltered) Grape search query. This can theoretically increase load on your Jira Server but usually doesn’t cause any problems unless people use the Grape Search every second. The Grape clients do a Grape Search query after the users stops typing in Grape Search for 200ms. For every Grape Search query a request will be sent to the Jira server and a search will be executed.
timeout: 0,5 seconds is a reasonable default.
Set the permissions (“object permissions”): This allows you to limit the external search to a certain subset of your users. You could limit it to certain AD groups or users which are in specific chat group. Since the search is impersonated we will allow all users of the organisation:
Click “Add Object permission” —> a new inline input form appears
Click the search button next to the “Access group” input field
Click “Organisation” in the filter on the right
Find your organisation in the list and click on “all”
Test the integration:
Make sure your Grape account has the same email adress as your Jira account.
Open the chat and press ‘#’ to open the Grape search
press ‘+’ to see the list of integrations. you should Jira with the name you entered as “Verbose Name”. if you clicked “Explicit” in the setup you have to selevt this integration and press enter.
Type a word that is part of an issue title in Jira
You should see one or multiple matching issues in the results:
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.
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: print(room.slug) 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 room.save()
SSH into your server and open a Django shell on your server.
Copy & paste the code and press Enter twice to run the code and Enter again to confirm the changes.