⚠️ This legacy integration is deprecated and we do not support this integration anymore. Please check out the new and improved Jira Integration V2

Before Setting Up

What is Required For This Integration?

One-time mapping between GUIDEcx and Jira by your Jira admin.
GUIDEcx and Jira admin rights*
A COMPANY MANAGED Project in Jira to connect to**

*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!

**In Jira you can create a Company or Team Managed Project. You must use a Company Managed Project because these types of projects allow you to LINK issues to GUIDEcx whereas Team Managed Projects DO NOT. If you connect to a team managed project, then the integration will not work.

What Does the Jira Integration Do?

Our Jira integration is a great way to create Jira issues from GUIDEcx tasks. The GUIDEcx task status can also be updated based on its progress within Jira.

For example, if there are a handful of Jira issues that need to be created every time you onboard a new client, this can be a great way to streamline that process and provide visibility within Jira.

Integration Translation 1

Jira	GUIDEcx
Project	(Not Applicable)
Epic	Project
Issue	Task

The diagram above helps us understand how these two systems speak to each other.

Within Jira, a "project" is like a folder where “epics” can be created. Jira "epics" are equivalent to GUIDEcx “projects”.
The Jira "Issues" that appear within that “epic” are equivalent to GUIDEcx “tasks”. A common Jira project to create is "GUIDEcx Onboarding".

For example, once you create a project within GUIDEcx using a template that includes Jira tasks, a subsequent “epic” will be created within Jira. Let's say this GUIDEcx project is called "Target Onboarding". The diagram would look like this:

Integration Translation 2

Jira	GUIDEcx
Project (GUIDEcx Onboarding)	(Not Applicable)
Epic (Target Onboarding)	Project (Target Onboarding)
Issue (Create client portal)	Task (Create client portal)

Which fields are synced?

These are the fields that are synced if added to issue screens in Jira.

We've outlined the fields below from Jira and tell you where the info is being pulled from in GUIDEcx. i.e. Jira Issue Labels = GUIDEcx Task Tags

Where in my GUIDEcx Project do the fields in my Jira Epic come from?

Jira Epic	GUIDEcx
Epic Name	Naming Format for Jira Epics Jira integration settings
Issue Type	Default Issue Type Jira integration Settings
Project	Default Jira Project Jira integration settings
Reporter	Project Manager email If there is no matching email in Jira, it will use the email of whoever set up the Jira integration.
Summary	Naming Format for Jira Epics Jira integration settings

Where in my GUIDEcx Task do the fields in my Jira Issue come from?

Jira Issue	GUIDEcx Task
Assignee	Task assignee email If there is no matching email in Jira, no action will be made. If the task is unassigned it will update the task in Jira to unassigned.
Description	Task Instructions
Epic Link	Link to the Epic created by the corresponding GUIDEcx Project.
Issue type	Default Issue Type Jira integration settings
Labels	Task Tags
Priority	Priority
Reporter	Project Manager email If there is no matching email in Jira, it will use the email of whoever set up the Jira integration.
Summary	Task Name
Start Date	Task Start Date
Due Date	Task Due Date

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 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	No
Due Date	Yes	No
Assignee	Yes	No

How to Connect to GUIDEcx

1. Authenticating Jira within GUIDEcx

Go to the lower left-hand corner in GUIDEcx and click on “Company Details”, click the “Integrations” tab, and click “Connect Jira” under the Jira Software logo.

2. Create or select a project within Jira Software

If you already have a Jira project created for GUIDEcx projects, you can skip this step. If not, create a project in Jira (this is where the tasks you create within GUIDEcx will be sent). You can create more than one Jira project to collect GUIDEcx tasks. Each project you want to receive tasks from in GUIDEcx will need its own field mapping (we’ll cover that in a bit).

It's best practice to have a single project setup within your Jira instance to receive all onboarding-related tasks.

(Finished project)

3. Field Mapping between GUIDEcx and Jira

In GUIDEcx, you can create a mapping between the two systems.

In the “Integrations” tab of “Company Details”, click “Settings” under the Jira Software logo.
You will see the screen below. In the screenshot, you'll see an example of each setting already configured.

A: Default Jira Project. This selects the default project in Jira where you want GUIDEcx tasks to go. (This Jira project was created above in step 2.)
B: Default Issue Type. When sending a GUIDEcx task into Jira, you can decide if it will become an “Epic”, “Task”, or “Subtask”. We recommend setting this to "Task".
C: Epic Naming Format. This will be the naming convention for Epics created in Jira (each project in GUIDEcx is associated with a single epic in Jira).
D: Issue Naming Format. This will be the naming convention for issues created in Jira (each task in GUIDEcx is associated with a single issue in Jira).

E: Project Status. Select the Jira project name, complete the field mappings in boxes G and F, and click "Save." Then, if you have multiple Jira projects, select the next Jira project name and repeat the mapping steps for each.
F: Task Status. This is for correlating the task status from GUIDEcx to issue status in Jira.
G: Priority. This is for mapping priority statuses from GUIDEcx to Jira. GUIDEcx only has three statuses, so please select the most appropriate corresponding statuses in Jira.

Once you’ve mapped everything, click “Save”.

4. Testing your Jira integration

To test your Jira Integration, create a template in GUIDEcx with at least one milestone and one task.

Within the task details, turn on the "Sync with Jira" toggle for each task you want to sync with Jira.
Then, set which Jira project you want these tasks to go to and what issue type the task will transfer as.
Create a project in GUIDEcx using this template. Once it has been created, there will be a "Jira Epic" link in GUIDEcx. This can be found in the edit menu of the GUIDEcx project (screenshot below). This link confirms that your GUIDEcx project and Jira epic are connected correctly.

Important Steps for Troubleshooting

Make sure your GUIDEcx task statuses and priorities match what is in Jira.

This step is super important. If your Jira is configured in such a way that an “issue” needs to have additional fields in order to be created, then your GUIDEcx “task” will not appear within your Jira. In order to fix this, you will have to update the required fields in Jira to match what is available within GUIDEcx (Status and Priority).
Check to make sure each task you want to appear within Jira has an Issue link.

Within a GUIDEcx task, you can click the "Jira Issue" link to open a browser window directly to the corresponding issue within Jira. If you don't see this link, there is a configuration issue that has prevented the task from being sent to your Jira instance.
What if the Jira "issue" status isn’t updating when you update the "task" status within GUIDEcx?

Make sure your task and issue statuses are mapped correctly. Once that has been confirmed, you'll want to give any change you make 10 minutes to take effect in either system when making a status update. (Please see setup step 3.)
To move a connected task to a different Jira project, you can delete the task by disabling the sync, and re-enabling the sync with a different project selected on the task-level overrides.
If GUIDEcx projects still aren’t sending tasks to Jira,
1. Verify the settings in GUIDEcx and Jira and that the correct Jira project has been selected for the GUIDEcx task.
2. Check the priority and status mappings for tasks.
3. Test on a new project. (There isn't any retroactive syncing.)
4. The issue can't be created in Jira until there is an epic in Jira, so make sure there is one by going to the GUIDEcx project settings and locating the Jira link.
5. Check one of the GUIDEcx tasks that you are syncing with Jira. If the Jira link is populated, it was set up properly. If there's a link to Jira but you cannot locate the task in Jira, let us know!

Remember, within each Jira issue, you'll see that task name, instructions, and tags will port over from GUIDEcx. Issue comments and statuses will have a bidirectional sync with GUIDEcx notes and statuses respectively.

ERROR ALERTS:

ERROR	WHAT THIS MEANS	SOLUTION
Create/Delete a Jira Epic	GUIDEcx cannot create or delete a Jira Epic.	Please check your Jira Configuration settings and ensure the credentials that were used to set up the connection have sufficient permissions/access.
Create, Update, Delete Issues	GUIDEcx cannot create, update, or delete issues.	Please check your Jira Configuration settings and ensure the credentials that were used to set up the connection have sufficient permissions/access. You can also check the project's workflow settings.
Create, Update, Delete Jira Issue Comment	GUIDEcx cannot create, update, or delete comments.	Please check your Jira Configuration settings and ensure the credentials that were used to set up the connection have sufficient permissions/access.
GUIDEcx Project missing Jira Epic	GUIDEcx cannot find the Jira Epic because: There is a configuration/setup issue or The Epic was deleted from Jira	Please check your Jira Configuration settings and ensure the credentials that were used to set up the connection have sufficient permissions/access.