PREREQUISITES

In order to connect Vivantio to JIRA, you’re going to need:

• Admin access to your Vivantio instance
• Admin access to your JIRA instance
• A user account in JIRA for Vivantio
• The IP address(es) for your JIRA servers

BASIC CONFIGURATION

Step 1:

Log into Vivantio, open the Admin Area, and select JIRA under the Integration & API heading on the left menu:

The first screen you’ll see will prompt you for your JIRA credentials. Enter them and hit ‘Save’.

Step 2:

The bottom of the screen will update to show your unique Webhook URL:

You’ll use this URL when configuring Webhooks within JIRA.

However: before you can do that, you need to configure the IP Range for Vivantio to accept requests from, using the ‘IP Range’ button in the menu bar:

Having configured those options, you can move on to the next tab, Ticket to Issue Mapping.

TICKET TO ISSUE MAPPING

You can control which types of Vivantio Ticket can be mapped to which types of JIRA Issue by setting up Ticket to Issue Mappings. This prevents the wrong type of information being transferred or the wrong type of records being created.

When creating a Ticket to Issue Mapping, you’ll be prompted for a number of different things:

• Ticket Type – the Vivantio Ticket Type
• Project – the Project in JIRA
• Issue Type – the Issue Type in JIRA
• Vivantio ID Custom Field – if you have a custom field in JIRA that you want to use to store the Vivantio Ticket ID, you can enter the (system) field name here. This will usually be in the format ‘customfield_10010’
• Link Issue to Ticket – JIRA has a concept of ‘links’ within a ticket – checking this box will add a link to the Vivantio Ticket to the Issue in JIRA
• Action / Attachment Sync – you can configure Vivantio to automatically send updates to JIRA when the Vivantio Ticket is updated (Note: this option does not force JIRA to update Vivantio though. That has to be configured within JIRA itself.)

After choosing the appropriate options, hit ‘Save’, and you’re ready to start creating JIRA Issues.

CREATING A NEW ISSUE

When viewing a Ticket in Vivantio, under the “More…” menu item, you’ll see the option to “Create New JIRA Issue”:

Clicking that button will bring up the “Create New JIRA Issue” dialog:

You can optionally enter Notes for the Vivantio Ticket History, then hit ‘Save’ to create the JIRA Issue. After a short period of time, you’ll see a JIRA tab appear on the Ticket Details:

That includes a link to view the Issue in JIRA, along with options to unlink the ticket from JIRA, or to add a direct comment to the JIRA Issue – useful if you didn’t choose to automatically sync actions.

GETTING INFORMATION BACK FROM JIRA

The next step in the process is getting information added to JIRA sent into Vivantio. This is done using Webhooks in JIRA. Full documentation on Webhooks can be found here, but we’ll briefly walk you through the steps required to configure them.

Back in the Vivantio Admin Area, you’ll find your unique Webhook URL, which will look something like:

https://url-to-your-vivantio-instance/webhooks/jira/event?accesskey=xxx-yyy-zzz

Make a note of this, head in to the “System” section of the JIRA Admin Area, and find the ‘WebHooks” menu option under “Advanced” (towards the bottom left of the screen). You’ll then have the option to “Create WebHook”, which is going to give you a screen more-or-less similar to the below:

You can enter whatever you want for the “Name”. Vivantio doesn’t use that field. Add your Unique URL in, then head down to the “Events” section, where you choose when you want the Webhook to fire, and for which Issues:

It’s up to you exactly which events you want the Webhook to fire for. For example, you might want to just have the Webhook fire when an Issue is updated or a Comment is added. More advanced users might want to configure the Webhook to only fire for specific transitions as a post function in a Workflow. (Note: see here in the Atlassian docs for more info on that.)

Having done that, you then need to set Vivantio up to listen for that specific event, and decide what actions to take. Back in the JIRA section of the Vivantio Admin Area, select the Webhooks tab, click Add, and choose the type of Ticket you want the Webhook to run for. Completing that step will show you the Add Webhook dialog:

In the name field, you’ll enter either a standard event name (such as ‘issue:updated’) or the name of a transition. For simple integrations, you can then choose to just add the JIRA Comments as Notes–then when the Webhook in JIRA fires, the comments will be added to Vivantio.

If you’re using transitions though, you might want more complicated actions to take place – for example, when an Issue is resolved in JIRA, you might want to change the status of the Vivantio ticket. You can do that using the Actions grid at the bottom of the page.

And there you have it: bi-directional integration between Vivantio and JIRA. If you’re using Vivantio and JIRA, and you don’t yet have them integrated, give it a try, and see how it can help you improve communications between your Service Desk and your development team!