Forums/Documentation/Setting up integrations

JIRA Integration: Creating a Custom Widget

Steven Yan
posted this on June 25, 2010 00:22

As JIRA is a highly flexible issue tracking tool, the Zendesk JIRA integration does not always completely serve the needs of our customers.  We've received a number of requests to enable customers to create their own custom JIRA widgets to suit their workflow needs, such as adding the ability to pass values for required issue fields.  The Zendesk custom widget framework is a great way for customers to tailor JIRA integration to their specific requirements.

To help you get started in creating your own custom JIRA widget, here is some template code and instructions on setting up your custom widget.  Disclaimer:  Zendesk Support cannot provide support for the development and maintenance of custom widgets.

Configuring JIRA

This article assumes that you've confirmed your JIRA install according to the instructions in the JIRA Integration guide.


JIRA custom widget template code

Custom widget code based off of our native JIRA widget is attached to this article.  The file should be downloaded and hosted on an HTTP server of your choosing.

 

Creating a custom widget

After you've hosted your widget code, go to Account > Widgets > Add Widget > Custom Widget and paste the following code into your custom widget configuration.  You'll need to replace the url, username, password and hosted widget code with the appropriate values for your environment.

 

<div id="jira_custom_widget" ticket_id="{{ticket.id}}" url="<jira_url>" username="<jira_username>" password="<jira_password>" custom_field_id="10000" subject="{{ticket.title}}" description="{{ticket.description}}" external_id="{{ticket.external_id}}">
<div id="content"></div>
</div>

<script type="text/javascript">
  Widget.require('<full_path_to_hosted_jira_widget_code>', {type: 'text/javascript'});
</script>

 

Here's an example configuration:
Screen_shot_2010-06-25_at_12.15.12_AM.png 


Customizing your widget code

Verify that the template code works before you continue to customize your JIRA widget.  The widget code relies on standard JIRA APIs with one exception.  The Zendesk JIRA plugin contains an API extension for retrieving assignable users for a project that is not supported in the standard JIRA API.  If you wish to extend the JIRA APIs available to your custom widget even further, you can customize the open source plugin code.

<div id="jira_custom_widget" ticket_id="{{ticket.id}}" url="http://72.167.96.167:8080" username="steven" password="mypassword" custom_field_id="10000" subject="{{ticket.title}}" description="{{ticket.description}}" external_id="{{ticket.external_id}}">
  <div id="content"></div>
</div>
<script type="text/javascript">
  Widget.require('http://sutra.heroku.com/javascripts/jira_custom_widget_template.js', {type: 'text/javascript'});
</script>
 

Comments

User photo
Alan Farkas

I created the custom Jira widget using the instructions on this page, but it's not working properly. I added the custom widget to my ticket page and the only thing that is displayed is the Widget title - nothing else - no combo boxes for Project, Type, and Assignee

July 27, 2010 22:20
User photo
Steven Yan
Product Manager

Alan, I will take a look at your configuration and let you know if something is amiss.

July 27, 2010 22:28
User photo
Alan Farkas

Thanks!

July 27, 2010 22:30
User photo
Steven Yan
Product Manager

Alan -- the <div> tag in your custom widget needed to have an id of "jira_custom_widget" -- your configuration had named it "jira_custom_template".  The code that we are providing relies on the ID of this <div> to function properly.  You should be all set now.

July 27, 2010 22:46
User photo
Alan Farkas

oh ok. Thank you very much for looking at this so quickly.

July 27, 2010 22:48
User photo
Alan Farkas

Unfortunately, "components" is a required field for us when adding Jira issues. I've been struggling with modifying the custom template to send back a value for Components, which must be some sort of array or complex field type in Jira.

 

Specifically, I need help with the Submit SOAP call. Right now, it's sending back "nil" for the value. I've trying modifiying right now to send back a hard-coded string value or a string array, but all my attempts fail with an invalid data type message.

July 28, 2010 09:13
User photo
Steven Yan
Product Manager

Alan -- unfortunately we can't provide support for custom widget development.  I'd suggest contacting Atlassian Support or joining an Atlassian development forum for help with your specific SOAP call.

July 30, 2010 11:54
User photo
Xavier Lembo

Hi Steven,

I've just hacked a custom jira widget , everything is ok when using it to submit a new Issue to Jira,  the issue is well created, and jira return his issue key well and it's writed back to the widget. But when we come back to the ticket , the notice writing the issue key doesn't appear anymore.

The issue key is present, because if i put 2 widgets on the page ( the zendesk default one and mine ) , the jira widget is ok and writes the issue key but mine don't.

 

In fact, if i track back my widget with firebug, i can see that the external_id field used to initialize the widget is not passed, so the following code always leave the external_id blank .

Any idea about the problem ? for me it sounds like : external_id attribut is not present in the view and therefor is not passed to my widget.

Thanks in advance

Xavier

<div id="jira_custom_widget" ticket_id="{{ticket.id}}" url="http://my.jira.url" username="zendesk" password="mypassword" custom_field_id="10000" external_id="{{ticket.external_id}}" subject="{{ticket.title}}" description="{{ticket.description}}"  requester_name="{{ticket.requester.name}}" organization="{{ticket.organization.name}}" >
<div id="content"></div>
</div>

August 17, 2010 08:02
User photo
Steven Yan
Product Manager

That is strange, that should work properly in the case you describe.  The {{ticket.external_id}} token should be replaced with the proper value.  It sounds like it may be some sort of caching issue.  Let me do some more investigation and I'll get back to you.

August 20, 2010 09:36
User photo
Miles Wilson
stringtogether

I think I have a similar problem -

I want to access the JIRA Issue number from the REST API, but both these problems I suspect (dont know for sure) are caused by the new way that the JIRA integration stores the link, in an 'external_links' array, rather than in the external-id variable.

This way of doing the integration doesn't appear to be written up anywhere, can you point us in the direction of some documentation?

 

The external-id field Xavier is trying to get to, is no longer populated by the new jira integration.

 

Thanks

 

Miles

September 14, 2010 03:58
User photo
VP
reuters

Hi,

After going through the js code and a lot of trial and error, I have finally figured out the way to pass custom field and not its value yet. Zendesk passes the value of the custom field as the zendesk ticket id. I don't understand what is the purpose of this and how I can override to send the values I want to. Please see my code below.

custom_field_id="10081"

 

where 10081 is the id of the custom field that is required in a JIRA project.

There has to be some way to do this, pass a key value pair or something. How do I pass multiple custom fields and their values?

Is this an assumption on Zendesk's side that only one custom field would be a required field on a JIRA project and the value has to be the Zendesk ticket id.

 

Please let me know.

November 12, 2010 10:34
User photo
VP
reuters

Thanks in advance!.. any help will be greatly appreciated.

November 12, 2010 12:34
User photo
Juha Palomäki
tofuture

We have priority as a mandatory field for certain projects and issue types. I modified the template and included the priority selection as well. 

My modified version is available on Github, in case somebody is interested: https://github.com/juhap/zendesk-jira

March 03, 2011 13:48
User photo
Jason Delmore
riskexchange

The native JIRA widget adds Zendesk attachments as links into the Description field.  The Custom Widget does not have this functionality.  Would it be possible to publish the updated widget code that does this?

April 21, 2011 12:33
User photo
Jason Delmore
riskexchange

Never mind, I added this myself.  For anyone else interested...

var description = XmlCustomHelper.getTextContentByKey(transport.responseXML, "description");
var newline = String.fromCharCode(13) + String.fromCharCode(10);
var attachmentList = transport.responseXML.getElementsByTagName('attachment');
if (attachmentList.length > 0) {
    description = description + newline + newline + "Attachments:";
}
// loop over each attachment
for (var i = 0; i < attachmentList.length; i++) {
    description = description + newline + XmlCustomHelper.getTextContentByKey(attachmentList[i], "filename") + " - " + XmlCustomHelper.getTextContentByKey(attachmentList[i], "url");
}

Then just pass description rather than this.description to submitIssue2().

April 28, 2011 07:50
User photo
Aditya

I installed the plugin into JIRA and configured the Zendesk widget. I can see the projects and fields in Zendesk as well as the assignee ID. But when I go and submit a ticket in the Jira widget I get the following: 

 

Failed to retrieve JIRA issue key.

(com.atlassian.jira.rpc.exception.RemoteValidationException: {versions=Affects Version/s is required., fixVersions=Fix Version/s is required.} : [])

I am running JIRA 4.1.2 fyi. Juha pointed out in the other page (Zendesk + jira intigretion) that "Fix version is specified as mandatory field in your Jira configuration. The widget does not supply this information." What would be the correct call to place in the widget to pass on the version and has anyone already modified the widget to do this? 

April 28, 2011 23:30
User photo
Juha Palomäki
tofuture

The optional/mandatory fields are configured via "Field configuration schemes" in JIRA Administration. 

JIRA Administration => Field Configurations => (select the field configuration scheme) => (select field configuration) . Eventually you should be able to find a screen where you have list of different fields. There you should be able to make the required fields optional.

It is also possible to create a custom version of the Widget that supplies more information, but this requires knowledge of Javascript and the JIRA web api. Somewhere on Zendesk web pages there is information about creating modified version of the widget.

In our case the Zendesk - JIRA workflow goes like this:

  1. Customer reports an issue via email to Zendesk
  2. Agent reviews that case. If the issue is a software bug, we use the integration to create the issue on JIRA
  3. Software engineers work with JIRA, set things like affected versions, fix versions there and eventually resolve the case on JIRA
  4. Agent updates customer via Zendesk and eventually closes the case on Zendesk
April 29, 2011 00:28
User photo
Aditya

@juha thanks for you jira_widget.js for the priority calls. We are trying to implement the versions and fix versions calls. Do we need to develop a SOAP call for those as well. And any place where you found what the calls are for each field? 

May 09, 2011 14:14
User photo
Karl Picard
HTC

Is there a way to imbed the custom code directly in the widget as apposed to putting in the section:

<script type="text/javascript">
  Widget.require('<full_path_to_hosted_jira_widget_code>', {type: 'text/javascript'});
</script>

I have no where to host my custom javascript currently.  I am looking to run what Juha did with the priority as a required field.

May 23, 2011 15:04
User photo
Aditya

We have gotten the custom widget to work but when the ticket is updated in Zendesk and pushed to Jira. But can not get Jira to push back to zendesk. 

Also currently cant not pass fields affectsversions from zendesk to jira. Anyone have this issue and resolve it? 

June 01, 2011 10:54
User photo
Jamie Bousfield

To get the components and affected versions into the custom widget submit issue please look at the attached JavaScript file.

I'm still trying to get a custom fields that is a select list but have not been successful yet. If you can suggest any improvements or know how to load in a custom Select fields from JIRA please let me know. When I get some time I might come back to it.

August 30, 2011 20:36
User photo
Yury Dorofeev

Hi Stiven! I am currently working with Jira-Zendesk integration and found your useful post. The only question I have how can I uppload jira_custom_widget_Component and Version.js to Jira server if I use "OnDemand" version and not going to install it manually. If I can not do that what shall I write here:

<script type="text/javascript">
  Widget.require('<full_path_to_hosted_jira_widget_code>', {type: 'text/javascript'});
</script> 

Thank you in advance! 

Regards Yury


August 28, 2012 07:54