Contour 2.9.7 JIRA Connector 2.0

© 2010 Jama Software, Inc. Contour 2.9.7 JIRA Connector 2.0 Build great products. Contour 2.9.7 JIRA Connector 2.02 © 2010 Jama Software, Inc. Table of Contents Part I Welcome to Contour 3 Part II JIRA Connector 4 ................................................................................................................................... 41 Getting Started ................................................................................................................................... 62 System Setup .......................................................................................................................................................... 6Contour Pre-Configuration .......................................................................................................................................................... 7JIRA Pre-Configuration ................................................................................................................................... 83 Synchronization Configuration .......................................................................................................................................................... 9Creating a Connection .......................................................................................................................................................... 11Synchronizing a Project .......................................................................................................................................................... 12Synchronizing a Set .......................................................................................................................................................... 14Mapping Set Fields ................................................................................................................................... 164 Working with Synchronized Items ................................................................................................................................... 175 FAQ Welcome to Contour 3 © 2010 Jama Software, Inc. 1 Welcome to Contour CONTOUR 2.9.7 JIRA Connector 2.0 Setup Guide OVERVIEW Welcome to Contour. Jama Contour is designed to provide you and your entire team a centralized, light-weight application for managing requirements. This installation guide is written to help you get the JIRA Connector installed in either an evaluation or production environments. Installation is relatively straightforward, but we are happy to remotely install and configure Contour for you if you’d prefer. If you run into trouble, give us a call (Technical Support) at 1-800-679-3058 or support@jamasoftware.com Thanks for choosing Contour. Enjoy the freedom of collaborative requirements management. 503.922.1058 | success@jamasoftware.com | www.jamasoftware.com Contour 2.9.7 JIRA Connector 2.04 © 2010 Jama Software, Inc. 2 JIRA Connector The JIRA Connector helps bridge the gap between Product Management and development. Create items in Contour, and the connector will keep JIRA up-to-date! 2.1 Getting Started Overview The JIRA Connector is a behind the scenes job that runs based on a schedule defined by the administrator. When the job runs it looks for items in Contour that match the synchronization criteria specified by the administrator and for each item either creates a new associated item in JIRA or Contour or synchronizes an existing one based on previous synchronizations. JIRA Connector 5 © 2010 Jama Software, Inc. Reasons for the JIRA Connector Here are some common examples of how the JIRA Connector can be used. Defect to Defect Defects can be created in Contour which will then create defects in JIRA. The defect's life-cycle can subsequently be managed in JIRA by the development team. Once complete, the defect in Contour is updated so the Business Analyst or QA knows the defect is complete and ready for testing or documentation. Requirement to Feature Business Analysts use Contour to gather, collaborate, and define requirements for a product. Once a requirement is ready for implementation the BA can set the requirements to a status of "Approved for development". The JIRA connector can be configured to only synchronize requirements in Contour that match this status. Once a requirement is synchronized and an associated Feature in JIRA is created, the development team can prioritize and schedule the JIRA Feature while knowing the BA is aware of the progress. How long will it take to setup? 45 Minutes for the initial configuration. Each additional Project or Set you'd like to synchronize would only take about 5-10 minutes. How customizable is the synchronization? Very. The diagram below provides an example of a single synchronization definition. As you can see individual fields on a Contour item are mapped to individual fields in a JIRA Item Type. For each field you can define which direction to synchronize. For more details on the mapping rules see the field mapping section. Contour 2.9.7 JIRA Connector 2.06 © 2010 Jama Software, Inc. 2.2 System Setup In order for the synchronization to work there are some important pre-configuration steps. This document assumes the following versions or greater are installed. Supported Versions Contour 2.7 and above JIRA version v3.1 and above 2.2.1 Contour Pre-Configuration This section will help guide you through the necessary pre-configurations. License The JIRA Connector requires an additional license to be activated. Please contact sales@jamasoftare.com to request a trial license. The JIRA Connector is already activated for evaluations. Pick Lists "Pick Lists" in Contour and "Select Lists" in JIRA are synchronized based on string equality. In the diagram below a Contour Pick List and a JIRA Select List contains the same values except for Implemented vs Complete. During synchronization these values will not update in either direction. The synchronization job will log a warning message in the log file when it fails to match a value. JIRA Connector 7 © 2010 Jama Software, Inc. Field Mapping recommendations There are several fields in JIRA that are useful to track in Contour. In order to synchronize with these fields they need to exist in Contour. Here are our recommended fields. Components: JIRA uses Components as a multi-select Pick List. In Contour, create a custom field multi select Pick List with values matching the components in JIRA. JIRA Status: The JIRA status field is specific to JIRA and is used as part of JIRA's workflow process. The status values cannot be updated from Contour and probably shouldn't. However, it is useful to have the status of the JIRA item reflected in Contour for information purposes. In Contour, add a new custom multi-select field called "JIRA Status" with a Pick List whose values match the status values in Contour. ( Assigned to: This is another example where it makes sense to have each system track its own field. For this we recommend creating a "JIRA Assigned To" field in Contour that is of type String (or can be a user type if user names are the same in both Contour and JIRA). Then in JIRA create a "Contour Assigned To". Release: Releases in Contour and Versions in JIRA can also be synchronized. As long as the names match exactly they can be synchronized. The values can be modified in either system. 2.2.2 JIRA Pre-Configuration Before the JIRA Connector can be configured in Contour or activated it will be necessary to do some pre-configuration in JIRA. Enable JIRA SOAP The JIRA Soap services must be enabled to enable the JIRA Connector in Contour to communicate with JIRA. By default, the JIRA SOAP services are disabled. 1. From within JIRA navigate to administration - General Configuration. 2. Then enable the "Accept remote API calls" module. Enable Wiki Render Macro Contour uses rich text (HTML) for comments and item descriptions. In order for this information to render correctly in JIRA the Wiki Renderer needs to be enabled. Contour 2.9.7 JIRA Connector 2.08 © 2010 Jama Software, Inc. 1. From within JIRA navigate to Administration - Plugins. 2. Select "Wiki Renderer Macros Plugin". 3. Enable Plugin. Enable HTML Macro Now that the Wiki plugin has been enabled the HTML Macro should be also be applied to fields that will be synchronized with rich text fields in Contour. Typically this is description and comments. 1. From within JIRA navigate to Administration - Custom Fields - Default field configuration. 2. Select "Renderers" on the JIRA field, such as Description. 3. Set the "Active Renderer" to "Wiki Style Renderer". 4. Click update Field Mapping recommendations There are several fields in Contour that are useful to track in JIRA. In order to synchronize with these fields they need to exist in JIRA. Here are our recommended fields. Contour Status - The Status field in JIRA is managed by the default workflow steps and cannot be modified by the status in Contour. If you'd like to display the status of the Contour item in JIRA it is necessary to create a custom field in JIRA that matches the values of the Status' in Contour. This will enable you to map the Status Pick List in Contour to the Contour Status Select List in JIRA. Contour Assigned To - In the Contour Pre-Configuration if we wanted to track who each item was assigned to we created a "JIRA Assigned To" in Contour. Now in JIRA we create a "Contour Assigned To". With these custom fields in place we can now define a mapping structure that will display on both system who the associated item is assigned to without disrupting each systems workflow. Note: It is recommended to create Components and Releases for the target project in JIRA that are named exactly the same as in Contour for synchronizing release and component fields between Contour and JIRA. 2.3 Synchronization Configuration This section will walk you through configuring the JIRA Connect in Contour. The basic steps are: 1. Creating a Connection - This is the connection between JIRA and Contour. 2. Synchronizing a Project - Multiple projects can be synchronized. 3. Synchronizing a Set - For each Project multiple Set's can be synchronized. 4. Mapping Set Fields - For each Set the individual fields can be mapped with rules defined for each. JIRA Connector 9 © 2010 Jama Software, Inc. 2.3.1 Creating a Connection The connection points Contour to the JIRA Soap so the synchronization job can communicate with JIRA. 1. Select JIRA Connector Note: If you don't see this link you will need to install the JIRA Connector license. Contact sales@jamasoftware.com for a trial. 2. Click on the Add JIRA Connection button. Contour 2.9.7 JIRA Connector 2.010 © 2010 Jama Software, Inc. JIRA URL This is the URL used to access your JIRA instance. JIRA User The JIRA user is any user in JIRA that belongs to the "jira-administrator" group. JIRA Password The password for the specified JIRA user Contour User This is the user in Contour that runs the synchronization job. The user must have organization admin permissions or the job will not run and will be removed from the schedule with appropriate message in log file. Synchroniz ation schedule There are two options for defining the schedule. 1. Simple Scheduling is an interval defined in minutes. We recommend timing to be as infrequent as seems feasible. 60 - 1 hour is good if you need frequent updates. 720 - This is a 12 hour interval which ensures the synchronization happens at least daily. (The advanced options below allow for more control on the timing) 2. Advanced Scheduling for more advanced scheduling techniques you can use a Cron string to specify complex scheduling. JIRA Connector 11 © 2010 Jama Software, Inc. Example Cron Strings "0 0 12 * * ?" Fire at 12pm (noon) every day "0 0/5 14 * * ?" Fire every 5 minutes starting at 2pm and ending at 2:55pm, every day "0 15 10 ? * 6L" Fire at 10:15am on the last Friday of every month Enable synchroniz ation Be sure this is checked for the synchronization job to be activated. Test Connection Click this to test your connections settings 3. Ensure that the Synchronization enabled for this organization is selected. This provides the ability to turn the connector on and off. 2.3.2 Synchronizing a Project Once a connection has been established the option to synchronize a project will be available. 1. Click on the Add Project button. 2. Select the Contour Project and the corresponding JIRA Project. 3. Click the Save & Close button. Contour 2.9.7 JIRA Connector 2.012 © 2010 Jama Software, Inc. 2.3.3 Synchronizing a Set Once the projects have been selected, the groups to be synchronized must be setup. In Contour this is a Set, in JIRA a Type. 1. Click on the row that contains the target project. 2. Click on the Add Set button. It the Synchronized Sets exist then click on the Edit Set link available in the target row. 3. Complete Set Synchronization Settings. JIRA Connector 13 © 2010 Jama Software, Inc. 4. Map Contour Set to JIRA Type. 5. Configure the Comment Synchronization. The comments in Contour and JIRA for the item being synchronized can be included. None - Comments will not be synchronized. One Way: From Contour - Only comments added in Contour will be sent and logged in JIRA. One Way: Into Contour - Only comments added in JIRA will be sent and logged in Contour. Bi-directional - Comments added to either Contour or JIRA will be sent and logged in both systems. 6. Configure the Items Synchronized from Contour. Use these settings to instruct Contour to Contour 2.9.7 JIRA Connector 2.014 © 2010 Jama Software, Inc. push items initial created in Contour to JIRA. Do not synchronize items from Contour to JIRA - No Items in Contour will be created in JIRA or synchronized. Synchronize all items from this Contour Set - This will ensure that all items contained within the Set are synchronized with JIRA. Synchronize only items that match this query - When only certain items need to be synchronized then the Lucene search syntax can be used to create a query that only synchronizes certain items. More information on how to use Lucene syntax in Contour can be found in the User Guide under Search. Example queries: status:"Approved" flag1:true status:"Approved" AND flag1:true 7. Configure Items Synchronized from JIRA for pulling items initially created in JIRA into Contour. Do not synchronize items from JIRA to Contour - Synchronize items that match this JIRA filter - Select the appropriate JIRA filter. Note: Filters in JIRA must marked as a favorite by the JIRA user entered in connector setup. When JIRA items of multiple issue types match the filter criteria Contour will only import the issue type as defined in set mapping. 8. Check Enable synchronization for this Set to turn on/off the sync. 9. Click the Save & Close button. Note: At this point even though the Set is synchronized, only the basic default field mappings have been applied. 2.3.4 Mapping Set Fields Once the Contour Set and JIRA Type have been configured the individual field mapping between the two must be configured. 1. Click on the Edit Field Mappings link within the target Set to Type mapping row. If the list is not available then click on the target Contour to Jira project row in the Synchronized Projects section. JIRA Connector 15 © 2010 Jama Software, Inc. 2. Select the appropriate JIRA Field from the JIRA Fields pick list to map to the Contour Field listed on the far left. Note: Contour does not distinguish or validate between types of fields. It's important to know when mapping the fields what type of field is being mapped. 3. Select the Sync Mode for the mapped fields. None - Selecting "None" or not selecting anything at all (clear) will result in this field being skipped during the synchronization. One Way: From Contour - Selecting this option will only push changes made in Contour to the field in JIRA. Any changes to the corresponding JIRA field will result in the value being changed back to reflect what's in Contour. One Way: Into Contour - Selecting this option will only pull changes made in JIRA into the corresponding item in Contour. Any changes made to the item in Contour will be changed back to reflect what's in JIRA. Note: If this option is selected we recommend making the Contour field read-only to avoid confusion. Bi-directional - Selecting this option will synchronize changes made in either system with the other. If a change is made to both systems the Job will rely on the Conflict Resolution to determine what change to make. Contour 2.9.7 JIRA Connector 2.016 © 2010 Jama Software, Inc. 4. Select the Conflict Resolution for each of the mapped fields that have a Sync Mode of Bi- directional. This option it is necessary to specify which system's data will be used when an Item has been updated in both systems between syncs. Use Contour - Contour's data will always be used when changes have been made in both systems between syncs. Use JIRA - JIRA's data will always be used when changes have been made in both systems between syncs. 5. Click the Save & Close button. Default Mapped Fields When a Set is synchronized, Contour creates several system fields that are necessary for the synchronization. Because these fields are necessary and are predefined they appear in the form as read only. JIRA Key When the synchronization first runs or an item is added or included as part of the query, the job in Contour will create a new item in JIRA. In order to continually synchronize with the same item in JIRA the corresponding JIRA key is stored and displayed for reference in the Contour item. JIRA URL Contour will generate a JIRA URL to provide users in Contour a direct link to the corresponding JIRA item. Last Updated in JIRA The synchronization uses the last updated date to determine possible conflicts and necessary changes. This is also useful from the user perspective to know when the last synchronization took place. 2.4 Working with Synchronized Items Congratulations! At this point you have configured both Contour and JIRA and the synchronization mappings are all in place....now what? At this point users can create and edit items in Contour an watch them magically appear in JIRA. Users in JIRA can now work on the JIRA item adding comments with the confidence that the users in Contour will see the changes. If you do run into any issues check our FAQ's or contact us directly. www.jamasoftware.com/support JIRA Connector 17 © 2010 Jama Software, Inc. 2.5 FAQ I don’t even see the “JIRA Connector” in the Administration view? Q: I don't see the JIRA Connector. A: The JIRA Connector is only available in Contour 2.7 and above and requires an additional license to be activated. Please contact sales@jamasoftware.com to request a trial or to purchase. I added items in JIRA/Contour why are they not in Contour/JIRA? Q: I went to check the other system and my new Items were not there. A: Check the JIRA Connector Set settings to see that both synchronization directions are configured and that your new Items conform to either the search query or filter that may have been applied. Next check that the sync is enabled. Finally look to the sync schedule, there is a chance that the sync has not run since your new Items were entered. If you need them immediately you can click on the Synchronize now button from the main JIRA Connector tab. What happens if I modify my field mappings? Q: I don't like my field mappings, can I change them? A: Once a synchronization has been configured and is running there are some considerations when modifying the settings especially around field mappings. There are three scenarios where field mappings could be modified. Changing any mapping