Using custom buttons in SugarCRM to interface with JIRA

There are three custom buttons you can add in SugarCRM to make using the CRM plugin more convenient. These buttons give you the following functionality from your SugarCRM screen.

Create (or update) a JIRA issue from a CRM record. This button is used along with or in place of the plugin's cron service to sync data from SugarCRM to JIRA.
Link a CRM record to an existing JIRA issue allowing multiple CRM records to be linked to a single JIRA issue
Display a table showing issue data from JIRA for issues currently linked to a CRM record (for example: Account, Contact or Case)

Creating or updating a JIRA Issue from a SugarCRM Bug

You can place a button on your SugarCRM Bug view screen to manually sync the current Bug to JIRA. The first time you use this button a new Issue will be created in JIRA and linked to your Bug. After the Bug has been linked to JIRA, clicking the button will update the Issue with any new data from the Bug.

The URLs shown below use the https protocol, if you need to use http then you have to turn off the CRM plugin setting "Require secure connections (HTTPS)". You can find this setting in JIRA on the "CRM Setup" -> "Advanced Settings" screen.

On your SugarCRM server do the following:

1) Locate the SugarCRM install directory
2) Look in the sub-directory "apps\sugarcrm\htdocs\custom\modules\Bugs\metadata" for a file named "detailviewdefs.php". Note that you may need to create the sub-directories "\Bugs\metadata".
3) If the "detailviewdefs.php" file does not exist, create it using a copy of the file "apps\sugarcrm\htdocs\modules\Bugs\metadata\detailviewdefs.php"
4) Edit the "apps\sugarcrm\htdocs\custom\modules\Bugs\metadata\detailviewdefs.php" file and look for some lines of code right at the top that look like the following

$viewdefs['Bugs']['DetailView'] = array(
'templateMeta' => array('form' => array('buttons'=>array('EDIT', 'DUPLICATE', 'DELETE', 'FIND_DUPLICATES',)),
                        'maxColumns' => '2',
                        'widths' => array(
                                        array('label' => '10', 'field' => '30'),
                                        array('label' => '10', 'field' => '30')
                                        ),
                        ),

This is the PHP code that controls the line of buttons that appear at the top of the Bug view screen. We are going to add a new custom button definition to this array right after the 'FIND_DUPLICATES' button. The block of code should now look like the following. The lines in blue are added lines.

$viewdefs['Bugs']['DetailView'] = array(
'templateMeta' => array('form' => array('buttons'=>array('EDIT', 'DUPLICATE', 'DELETE', 'FIND_DUPLICATES',
array('customCode'=>'<input class="button" ' .
' onclick="window.open(\'https://JIRA-HOST/plugins/servlet/create-issue?crmtoken=TOKEN&id={$fields.id.value}\',\'jira\',\'width=592,height=215,scrollbars=1\'); this.form.module.value=\'Bugs\'; this.form.action.value=\'DetailView\';" ' .
' name="button" ' .
' value="Create/Update JIRA" ' .
' type="submit">'),
)),
                        'maxColumns' => '2',
                        'widths' => array(
                                        array('label' => '10', 'field' => '30'),
                                        array('label' => '10', 'field' => '30')
                                        ),
                        ),

Replace https://JIRA-HOST with the value appropriate for your JIRA server. The value for TOKEN can be found in JIRA on your "CRM Setup" screen.

5) We now need to flush SugarCRM's template cache so it will pick up our changes. Log into SugarCRM as admin and navigate to "Admin" -> "Repair" -> "Quick Repair and Rebuild".

For older versions of SugarCRM use "Admin" -> "Repair" -> "Clear Template Data Cache". Select the module "Bugs" and click the "Repair" button.

You should now see a new button labeled "Create/Update JIRA" on your screen when viewing a Bug in SugarCRM. Clicking this button will send the data for the Bug record being viewed to JIRA. Either a new JIRA issue will be created and linked to this Bug record or if there is already a JIRA issue linked to this Bug, that Issue will be updated. The exact Bug fields copied to JIRA are controlled by the settings on the "CRM Setup" -> "JIRA/CRM Field Mappings" screen in JIRA.

Linking a SugarCRM Bug to an existing JIRA Issue

You can also create another custom button for your Bug screen which will link a Bug to an existing JIRA issue (allowing multiple Bugs to be linked to one JIRA issue). The URL for this button definition should look like this:

https://JIRA-HOST/plugins/servlet/link-issue?jira_user=JIRA-USERNAME&pwd=JIRA-PASSWORD&id={$fields.id.value}

OR

https://JIRA-HOST/plugins/servlet/link-issue?crmtoken=TOKEN&id={$fields.id.value}

Additional Arguments

Normally the JIRA fields updated from CRM are controlled by the plugin's "JIRA/CRM Field Mappings" setup screen. But you can override one or more field mappings by adding additional arguments to the URL query string. For example, adding "&My+Field=sneeches" will set the JIRA field named "My Field" to the value "sneeches" in addition to the other JIRA fields mapped on the "JIRA/CRM Field Mappings" setup screen.

There are also other special arguments that let you adjust the behavior of the create-issue function.

URL Argument	Behavior
_always_create	Adding this argument to the URL will cause the plugin to create a new JIRA issue even if there is already a JIRA issue linked to the CRM record. This will only work if the plugin is configured to allow linking multiple JIRA issues to the same CRM record.
_always_prompt	When creating new issues, show the prompt screen to the CRM user even when the JIRA project is specified.
_mode=update	The plugin will not create new JIRA issues. Only updates to JIRA issues already linked to CRM are allowed.
_mode=create	The plugin will only create new JIRA issues. CRM records already linked to JIRA will not be sync'ed to JIRA.
_redirect-to-jira	When this argument is added to the URL the plugin will redirect the user's browser directly to the JIRA screen of the issue just created or updated. Note this normally requires the CRM user to have an account in JIRA.
_ignore	Some CRM systems add extra arguments to URLs that the CRM plugin doesn't recognize. Use this option to tell the plugin to ignore these URL arguments.
_close-window-on-success	Any external window used to display the results of the sync from CRM to JIRA will automatically be closed unless there is an error message to display.
_suppress-return-to-link	Never show the "Return to Case" link at the bottom of the results window.