User Access: GUIDEcx/Jira Admins can establish a connection with Jira Cloud.
How to set up the Jira Integration
There are three steps you need to follow: Authentication, Status Mapping, and Project Connection. See how to do that below:
1. Authenticate Jira within GUIDEcx
All Authentications MUST be done by a Jira Admin.
Go to the lower left-hand corner in GUIDEcx and click on “Company Details”, click the “Marketplace” tab, and select the Jira App from the Integrations Marketplace. Select "Connect".
You will see several different authentication types. We HIGHLY recommend using the API Token Authentication.
Authentication Types
API Token - RECOMMENDED
Host Name - Refers to the URL of your Jira account (e.g.https://orgname.atlassian.net)
Email - This MUST be the email address of a Jira Admin
API Token - Get/create API tokens by going to id.atlassian.com > Settings > API Keys > Create API Key
O Auth 2.0 -
Host Name - Refers to the URL of your Jira account (e.g.https://orgname.atlassian.net)
Connect - After selecting the Connect button a new Authorization window will pop-up. This is Workato requesting access to your Atlassian account. Please accept.
Advanced Settings - For the integration to work properly it is recommended to "Select All" Scopes. However, Specify only the scopes that the client is authorized to use. We are only requesting access for what is essential to the integration.
Personal Access Token -
Host Name - Refers to the URL of your Jira account (e.g.https://orgname.atlassian.net)
Personal Access Token - In Jira, select your profile picture at the top right of the screen, then choose Profile > Personal Access Token -> Create token
Basic - This authorization type is no longer accepted by Atlassian.
Host Name - Refers to the URL of your Jira account (e.g.https://orgname.atlassian.net)
Username - MUST be the Username of a Jira Admin
Password - Jira Admin Password
2. Status Mapping:
In the “Marketplace” tab of “Company Details”, click “Settings” under the Jira Software logo.
Edit the General Settings found below:
General Settings
Push GUIDEcx Project as: Choose if you would like to Push Projects from GUIDEcx into Jira as Jira Epics or Jira Projects.
Default Issue Type: Choose what type of Jira issue you create when you create a GUIDEcx Task.
Task Status Mapping: Map your GUIDEcx Task statuses to your Jira Issue statuses.
Priority Mapping: Map your GUIDEcx priorities to your Jira epic priorities. GUIDEcx only has three statuses, so please select the most appropriate corresponding statuses in Jira.
3. Project Connection
The final step is configured in Project Settings. When the previous authentication and mapping steps are complete, this is how the project edit pane will look:
To push changes from GUIDEcx to Jira, choose whether to create a new epic or project in Jira or push to an existing epic:
If "create new" is chosen, the Jira project or epic title will follow the naming pattern set during the initial integration setup.
If "push to existing" is chosen, select the existing object from the list.
To pull changes from Jira into GUIDEcx, map the default project milestone:
Chose the GUIDEcx milestone (that must be created before this step) from the "Default Project Milestone" menu at the bottom.
Tasks defined in Jira will be pulled into that milestone as new GUIDEcx tasks.
What GUIDEcx Features will Push to Jira?
What Jira actions will push back to GUIDEcx?
GUIDEcx Feature | Does this push to Jira? | If initiated in Jira, does it push to GUIDEcx? |
Task Name | Yes | Yes* |
Task Status | Yes | Yes |
Task Instructions | Yes, upon initial creation | No |
Task tags | Yes | No |
Task attachments | No | No |
Notes | Yes | No |
Deleted Task | Tasks deleted in GUIDEcx will delete the associated record in Jira (IF enabled in Jira) | Issues deleted in Jira will NOT delete in associated GUIDEcx project |
Start Date | Yes | Yes* |
Due Date | Yes | Yes* |
Assignee | Yes | No |
*IMPORTANT TO KNOW: These fields will push to GUIDEcx if they are new issues that are created after the V2 connection is made and only if the Milestone mapping has been setup. These fields will not push issues that existed before the V2 connection is made.
How to push an issue from Jira to GUIDEcx
During the Project Connection step you will be asked to select a Default Project Milestone. New Tasks from Jira will be assigned to this Milestone. This field is required for Jira Updates to Sync back to GUIDEcx.
Once the Project has been connected, add an issue to the Jira Project or Epic. The issue will only sync to the GUIDEcx Milestone if it has the GUIDEcx label.
How to Uninstall the Jira Integration
Remove the Package from GUIDEcx
Click on “Company Details”.
Click on the “Integrations” tab.
Select the Jira App
Click on "Disconnect" to disconnect and remove your Jira integration from GUIDEcx.
FAQs:
What is Required For This Integration?
One-time mapping between GUIDEcx and Jira by your Jira admin.
GUIDEcx and Jira admin rights*
*If you do not have Jira admin access, you can either add your Jira admin to GUIDEcx temporarily or have them authenticate this integration with you. If you add them to GUIDEcx, you may remove them later without disconnecting the integration. As long as the credentials you use to authenticate the Jira integration are valid, the integration will continue to work!
If I already have the Jira V1 integration will I need to Authenticate my connection again?
Yes, you will need to authenticate the connection again and confirm that the global settings are accurate. See How to connect to GUIDEcxWhat happened to the naming customization that was in v1?
We removed that step in efforts to simplify the setup process.
What will happen to my projects that have already been linked in the Jira V1 connection?
There will be a one-time non-reversible migration of data from V1 to V2.
Will my converted projects have all the Jira V2 functionality?
Yes, existing projects will show the converted settings in the new Project Settings drawer
What is new with Jira V2?
Users can now push GUIDEcx Projects into Jira as Jira Projects. Users will still have the option to push into Jira as Jira Epics.
Users can now push Jira Issues into GUIDEcx Projects. This can be done by selecting a Milestone in your Project Settings for the Jira Issues to push into.
What has changed with Jira V2?
GUIDEcx does not automatically create new Jira resources for every new project created in GuideCX. This is now an option that Admins and Guides will have in the new Project Settings drawer for existing / new projects.
Task-level overrides are no longer available. Tasks will be created on the project configured in global settings (only applicable to Project > Epic workflow)
Can I use the "Basic" Authorization Type?
Atlassian is removing support for basic auth with password for Jira (cloud only). Please update connection to use API tokens instead.