Configuring zAgileConnect

The configuration of the Salesforce package involves the following required steps.  The zAgileConnect JIRA add-on must be installed and communications must be enabled between Salesforce and JIRA before proceeding with these steps.

Furthermore, the configuration of the JIRA add-on needs to be done in parallel with the package configuration. Admin privileges are required in both applications for the configuration steps.

1. Select JIRA Projects, Issue Types relevant (visible) to Salesforce users, as well as their default values that would be used during Issue Creation.
2. Select Salesforce Case properties to send to JIRA for display within the Issue context (in Related Salesforce panel on Issue View screen)
3. Select Issue properties to pull from JIRA to display on the Case page, as well as in Salesforce Reports
4. Select Case Fields to copy to JIRA Issue fields (with v1.7, this feature is now also available for JIRA Cloud users)
5. Select Salesforce fields to send to JIRA Issues

Select default JIRA Project, Issue Type and Priority

In this section, you will select all JIRA projects and Issue Types that will be visible in Salesforce for Issue Creation.  This is typically a subset of all available Projects and Issue Types that may be defined in your JIRA instance, since not all of them may be relevant for the Support teams.

In addition to selecting a subset from the list, you will also need to pick default values that will be used during Issue Creation.  The defaults are primarily for convenience since it minimizes the need to make those selections for each JIRA Issue that is being created from Salesforce.

There are some additional options that are also available in this configuration section, depending upon the version of zAgileConnect you have installed.

1. Auto creation of JIRA Issue when Case is created – this option can be enabled if a JIRA Issue must automatically be created for every Case that is created in Salesforce
2. Disable All Triggers – this option will disable triggers that are used to automatically send Case updates to JIRA.  This is only to be used in some exceptional situations when the zAgileConnect triggers may interfere with other activities or components.  Disabling triggers will still allow Support teams to access existing data until the root cause is resolved.
3. Email Notifications – With v1.7, you can specify an email address to which notifications will be sent in the event of any errors related to background jobs that are used for performing JIRA updates.

Select Case properties to be sent to JIRA

In this section, you can select the Case properties that you want to send to JIRA for display within the issue context.  The metadata associated with these properties will be sent to JIRA upon saving.  Subsequently, when a JIRA Issue is created from Salesforce, values corresponding to these properties are sent to JIRA for associating (and displaying or copying) with the Issue.

You may also select properties of additional objects (including custom objects ) related to the Case for sending to JIRA.  To accomplish this, please select the objects on the first tab and save the changes. After refreshing the configuration page, the second tab (Case Properties) will show the properties of all of the objects selected.

To pass Case Owner (name) to JIRA, select User and Group from the Salesforce Objects list.  This will enable Owner Name property in the Case properties tab.

Please make sure that the Case properties to be shared with JIRA are accessible to the Integration User that is used for authenticating Salesforce to JIRA.  Permissions associated with this user will be effective when accessing Case details for JIRA users.

The following tab allows you to select specific properties of Case or related Objects to send to JIRA for providing Case context to related Issues.  The checkbox indicates whether that property will display in the ‘Salesforce Properties‘ panel on the issue screen.

Selecting Sources for Attachments to be sent to JIRA

With zAgileConnect v1.7.5, the configuration section above also allows the selection of sources (objects) for Attachments to be sent to JIRA.  Previous to this release, only Case attachments could be sent to JIRA.  However, with this enhancement, it is possible select additional objects, (Case, Account, Email, etc), custom objects, as well as Feed Items (Case Feed, Contact Feed, etc.).

Please note that all objects to be selected here must have direct relationship to Case to be accessible for attachment source.

Select JIRA Issue Properties to bring to Salesforce

You can configure JIRA Issue properties to bring (copy) into Salesforce custom object ZIssue that is bundled with the package.  These properties may also include custom fields.

Please note that if you desire to bring JIRA Issue custom fields into Salesforce, you will need to add corresponding fields to the ZIssue custom object with matching field type. Once these custom fields exist in ZIssue, they can be mapped to corresponding JIRA Issue custom fields.

Via the dropdown, you can view and select JIRA Issue fields, including custom fields.

The following screenshot provides an example of JIRA issue mapping into Salesforce.

Please note that all standard fields will be automatically mapped to the corresponding fields provided in the ZIssue custom object in Salesforce.  You may choose to remove the standard field from the list, however, you cannot modify its mapping.

Furthermore, the checkbox next to each field determines whether that field is to be displayed in the ‘Related JIRA Issues’ panel.

All fields within this list are available for Salesforce reporting.

Select Salesforce fields to send to JIRA Issues

This section refers to copying values from Salesforce Case fields into corresponding JIRA Issue fields.  This is different from sending Case fields to JIRA for display since this directly copies the values into JIRA Issue fields which may further be updated either when they are updated in Case or by the escalation teams in JIRA via Issue Edit.  Typical scenarios for this would be copying descriptive text fields, such as Environment, or passing into required fields in JIRA Issue when creating it from Case.

Please note that this option is only available for Issues created from a Case.  If an existing JIRA Issue is linked to a Case, copying Case fields to Issue fields is not supported.  

JIRA Server –  Prior to v1.7, zAgileConnect provided limited support for this feature.  Issue fields such as Summary and Description were pre-mapped from Case Subject and Description and could not be configured.  Mapping was only supported between text and boolean values.  Furthermore, the configuration for field mapping was achieved in JIRA via plugin Admin options.   This configuration option has since been moved from JIRA into the Salesforce package, beginning with v1.7

JIRA Cloud – Prior to v1.7, this configuration was not available.

Field mapping is achieved by adding Case fields from the drop down to the mapping table (as shown below) and selecting a corresponding JIRA field from the Issue Field column drop down.  For each Case field added to this table, zAgileConnect will bring a list of possible matches from JIRA based on field type.

Please be sure to map Issue Summary and Description during the initial configuration of zAgileConnect.  In prior versions, these fields were pre-mapped and copied from Case Subject and Description, respectively.  However, with v1.7, you must map them as part of this configuration.

The configuration also allows you to explicitly specify if the Case fields copied to JIRA must be updated whenever they change in Case – or only copied the first time and left for JIRA users to update them when needed.

Add Visualforce Page to Case layout for Related JIRA Issues

The final step in this setup before turning this capability to Support teams involves adding a Visualforce page (Related JIRA Issues) to the Case page layout from where users will interact with JIRA.  To achieve this, edit the layout of the Case page, create a section for the JIRA Related Issues and drag the Visualforce page ‘zAgileConnect JIRA’ into this section.

Set the property of this page for sufficient width and scrolling, as desired.