AccuBridge Integration Services. AIS for Atlassian JIRA: Quick-Start

Size: px

Start display at page:

Download "AccuBridge Integration Services. AIS for Atlassian JIRA: Quick-Start"

Joseph Todd
5 years ago
Views:

1 The TimeSafe Configuration Management System AccuBridge Integration Services AIS for Atlassian JIRA: Quick-Start Version January, 2007 AccuBridge Integration Services for Atlassian JIRA 1

2 This document provides instructions for installing and setting up the AccuBridge Integration Service for Atlassian JIRA ( AIS for JIRA ). It does not present a full description of AIS for JIRA s features or its architecture. Name Mappings The setup process can involve working on multiple computers, and involves entering usernames, passwords, and filenames in configuration files. For simplicity and clarity, the instructions include examples that consistently use the following set of generic names, using this font: Generic Name Actual Name Description ais-mach Machine on which AIS for JIRA is installed ais-install Location on ais-mach where AIS for JIRA is installed accu-issues Name of AccuRev depot containing AccuWork issue database accu-mach Machine on which AccuRev Server runs jira-mach Machine on which JIRA runs jira-proj Name of JIRA project accu-chg-pkg Field in JIRA project that gets AccuRev change package data ais-user AccuRev user identity used by AIS for JIRA ais-user-pswd Password of AccuRev user identity used by AIS for JIRA jira-filt JIRA filter that selects the records to be processed by AIS for JIRA jira-projkey Three-character string that identifies the JIRA project to be processed by AIS for JIRA We recommend that you replace these generic names with names that are meaningful for your organization. Use the Actual Name column in the table above to keep track of the names you choose. You ll need a complete set of mappings to perform the customization of AIS for JIRA configuration files, starting at Step 11. Assumptions About Your Current Development Environment These instructions make the following assumptions about your development environment: The AccuRev Server is installed on your network (machine name: accu-mach). JIRA is installed on your network (machine name: jira-mach). JIRA and the AccuRev Server can be installed on the same machine; in this case, you ll use the same machine name where the examples below use the generic names accu-mach and jira-mach. AccuBridge Integration Services for Atlassian JIRA 2

3 An AccuWork issue database has been created in the AccuRev data repository (depot name: accu-issues) A JIRA project has been created (project name: jira-proj). AIS for JIRA will transfer data in both directions between AccuWork issue database accuissues and JIRA project jira-proj. (But this is not an architectural limitation; AIS for JIRA can be configured to involve multiple AccuWork issue databases and multiple JIRA projects.) The JIRA project serves as your organization s main issue tracking system (ITS). When AIS for JIRA is deployed, the AccuWork issue database will serve as a mirror of the JIRA project. In addition, AccuRev change packages maintained in the AccuWork issue database will be mirrored in a newly created field in the JIRA project (field name: accu-chg-pkg). Step 1 Verify network connectivity On machine accu-mach, execute the operating system s ping command to verify the connection to machine jira-mach. Step 2 Select a machine on which to install AIS for JIRA The machine you select can run Unix/Linux or Windows (machine name: ais-mach). It must have access, through the IP network protocol, to both jira-mach and accu-mach, the machines on which JIRA and the AccuRev Server are installed. Use the operating system s ping command to verify the connectivity. ais-mach can be the same machine as jira-mach or accu-mach. In general, minimizing the number of separate machines involved results in better AIS for JIRA performance. But take care not to overload the CPU resources of any single machine. Step 3 Create an AIS for JIRA user identity 3.1 Have the system administrator for machine ais-mach create a new OS-level user identity (username: ais-user, password: ais-user-pswd). The Perl scripts that implement AIS for JIRA will run under this user identity. 3.2 Have the AccuRev administrator for accu-issues create an AccuRev user identity with the same username and password: ais-user / ais-user-pswd. For optimal security, this identity should be used only by AIS for JIRA. It must have full read/write access to the accu-issues issue database. The AccuRev administrator should verify that ACL permissions are set appropriately. 3.3 Have the JIRA administrator for jira-proj create a JIRA user identity with the same username and password: ais-user / ais-user-pswd. For optimal security, this identity should be used only by AIS for JIRA. It can be a member of the jira-developers group; it s not necessary for it to be a member of jira-administrators. AccuBridge Integration Services for Atlassian JIRA 3

4 Step 4 Modify the AccuWork issue database schema 4.1 Have the AccuRev administrator for machine accu-mach add two data fields to the schema for the accu-issues issue database: issuekey (field type: Text) will store the unique JIRA record identifier of each issue record. This field is independent of the issuenum field, which uniquely identifies the issue record at the AccuWork level. issuelink (field type: Attachment) field will store a URL that AccuWork users can use to launch a Web browser and access the JIRA record. Step 5 In addition to making these changes on the Schema subtab, the administrator should add the new fields to the issue database s edit form, using the Layout subtab. Set up AccuRev client access 5.1 Install the AccuRev client software on machine ais-mach. (If necessary, download the installation program from Log in to machine ais-mach as user ais-user. 5.3 Set up AccuRev authentication of user ais-user on this machine, using AccuRev CLI commands: If the AccuRev Server uses the traditional user-authentication scheme, make sure this user s password is accessible on this machine: accurev setlocalpasswd ais-user-pswd If the AccuRev Server uses the AccuRev login user-authentication scheme (introduced in AccuRev 4.5), perform an AccuRev login: accurev login -n ais-user Enter the password ais-user-pswd when prompted. AccuBridge Integration Services for Atlassian JIRA 4

5 5.4 To test AccuRev client access through the new user identity, execute these AccuRev CLI commands: accurev info The output of this command should indicate that the Principal (AccuRev-level username) is ais-user and the Server is accu-mach. accurev secinfo The output of this command should be the single word authuser, indicating that the AccuRev Server recognizes ais-user as a user with a valid password. 5.5 Have the AccuRev administrator for machine accu-mach give you a copy of the XMLformat file that defines the database schema for AccuRev issue database accu-issues. This file is located in the AccuRev installation area: Step 6.../storage/depots/accu-issues/dispatch/config/schema.xml Alternatively, use a screen shot of the Schema subtab of the AccuWork Schema Editor. Install Perl 6.1 Install a distribution of the Perl scripting language on machine ais-mach. We recommend the free ActivePerl distribution from ActiveState ( You don t need to install any optional Perl modules, just the base distribution. 6.2 Verify the Perl installation with this command: Step 7 > perl v This is perl, v5.8.7 built for MSWin32-x86-multi-thread... Install AIS for JIRA 7.1 On machine ais-mach, use a Web browser to visit Under Other Downloads, click the AccuBridge Installation Packages link. 7.3 Download the ZIP archive for AccuBridge for Atlassian JIRA. 7.4 Uncompress the AIS for JIRA files into a directory in the local file system (directory name: ais-install). Step 8 Configure JIRA to accept remote API calls The next few steps must be performed by a JIRA user who is a member of the jiraadministrators group. AccuBridge Integration Services for Atlassian JIRA 5

3 In the Global Settings subsection, click the General Configuration link: 8.

6 8.1 Login to the JIRA server, using a Web browser on any machine in the network. 8.2 Go to the Administration section: 8.3 In the Global Settings subsection, click the General Configuration link: 8.4 Scroll to the bottom of the screen, and click Edit Configuration: 8.5 Click the Accept remote API calls radio button: AccuBridge Integration Services for Atlassian JIRA 6

8.6 Click the Update button at the bottom of the screen.

Step 9 Create a JIRA custom field for change package data This step must be performed by someone who has a

1 In the Issue Fields subsection, click the Custom Fields link: 9.2 Click the Add Custom Field link: 9.

7 8.6 Click the Update button at the bottom of the screen. Staying logged in to JIRA as a member of the jira-administrators group, continue to the next step. Step 9 Create a JIRA custom field for change package data This step must be performed by someone who has a JIRA username and is a member of the jiraadministrators group. 9.1 In the Issue Fields subsection, click the Custom Fields link: 9.2 Click the Add Custom Field link: 9.3 Select the field type Free Text Field, and click the Next button: 9.4 Enter a name for the new field (field name: accu-chg-pkg), and click the Finish button: AccuBridge Integration Services for Atlassian JIRA 7

9.5 Place the new field on one of the project s screens typically the Default Screen, to ensure that

Step 10 Create a JIRA filter to select the records to be processed 10.

JIRA. You might need to go to the Browse Projects section.

8 9.5 Place the new field on one of the project s screens typically the Default Screen, to ensure that the field will be visible to users. Then click the Update button. Step 10 Create a JIRA filter to select the records to be processed 10.1 Determine the three-character key string for the JIRA project that will be processed by AIS for JIRA. You might need to go to the Browse Projects section. (You might also need to click the All Projects link in that section.) Note the key for the desired project (key: jira-projkey): 10.2 Go to the Find Issues section: AccuBridge Integration Services for Atlassian JIRA 8

10.3 Enter the specifications for a search that locates the records to be transferred to AccuWork. For example, these specifications define a search that selects all Bugs in project Curly.

4 When you are satisfied that the search is correctly defined, save it as a named filter (filter name: jira-filt): 10.5 Click the XML link, to view the results of the filter/search in XML-format: 10.

9 10.3 Enter the specifications for a search that locates the records to be transferred to AccuWork. For example, these specifications define a search that selects all Bugs in project Curly. Click the View button to run the search, and verify that you ve entered the specifications correctly. Revise the specs and click View again, as many times as necessary When you are satisfied that the search is correctly defined, save it as a named filter (filter name: jira-filt): 10.5 Click the XML link, to view the results of the filter/search in XML-format: 10.6 Using cut-and-paste, save a copy of the complete URL (Web address). Also, save enough of the XML data so that you have a complete <item> element everything between an occurrence of <item> and the next occurrence of </item>. AccuBridge Integration Services for Atlassian JIRA 9

This ends the work with the JIRA Web interface. You can close the Web browser window. Step 11 Prepare to customize the AIS for JIRA configuration files 11.

10 This ends the work with the JIRA Web interface. You can close the Web browser window. Step 11 Prepare to customize the AIS for JIRA configuration files 11.1 Make sure that the table at the beginning of this document, mapping generic names to actual names, is complete. The next steps incorporate the actual names into the AIS for JIRA configuration files If you are not already logged into machine ais-mach, as user ais-user, do so now Go to the subdirectory within the AccuBridge installation area where the AIS for JIRA configuration files are stored: ais-install/src/jiraexample AccuBridge Integration Services for Atlassian JIRA 10

11 Step 12 Customize configuration file ApplicationSetup.xml Set the value of the accurevexecutable attribute appropriately: If ais-mach is running on Unix/Linux:... accurevexecutable="accurev" /> If ais-mach is running on Windows:... accurevexecutable="accurev.exe" /> Step 13 Customize configuration file DepotTransaction.xml In the <depot> element, set the value of the name attribute: <depot name="accu-issues"... Step 14 Customize configuration file IssueTrackingSystemMap.xml 14.1 Set attribute values in the top-level <issuetrackingsystem> element: <issuetrackingsystem... itsservername="ais-mach" accurevservername="accu-mach" accurevusername="ais-user" In the <depotmap> subelement, set the value of the name attribute: <depotmap name="accu-issues" In the <destinationconditions>/<condition> subelement, set the value of the values attribute: <condition operator="eq" fieldname="project" values="jira-projkey"/> 14.4 Use the <fieldmap> subelements within <depotmap> to configure the JIRA-to-AccuWork data transfer on a field-by-field basis. JIRA field names: determine these names using the copy of the <item> element you made in Step Code the field names with name attributes in the <fieldmap> subelements. AccuBridge Integration Services for Atlassian JIRA 11

<item> element IssueTrackingSystemMap.xml AccuWork field names: determine these names using the copy of the AccuWork issue database schema you obtained in Step 5.

12 <item> element IssueTrackingSystemMap.xml AccuWork field names: determine these names using the copy of the AccuWork issue database schema you obtained in Step 5.5. Be sure to use the values of the name attribute, not the label attribute. Code the field names with accuworkname attributes in the <fieldmap> subelements. AccuWork database schema IssueTrackingSystemMap.xml Exactly one <fieldmap> subelement must include the attribute primarykey="true", to indicate that this JIRA field is the issue s primary key field. Set the value of the accuworkname attribute to IssueKey, the AccuWork field you created in Step 4. Example: <fieldmap name="key" accuworkname="issuekey" primarykey="true"/> 14.5 In the <versionsmap> element, set the values of the name attribute: <versionsmap name="accu-chg-pkg"/> Step 15 Customize configuration file JiraConfiguration.xml 15.1 Set attribute values in the <JiraConfiguration> element: <JiraConfiguration serverurl=" <see note below> " AccuBridge Integration Services for Atlassian JIRA 12

13 username="ais-user" userpassword="ais-user-pswd" Get the value for the serverurl attribute from URL you copied in Step Example: Step 16 Customize configuration file JiraFilters.xml 16.1 Set attribute values in the <filterdata> element: <filterdata name="jira-filt" filteroptions=" <see note below> "/> The filteroptions attribute must record certain keyword=value options in the URL you copied in Step Ignore everything in the URL up to the question mark (?). And exclude these option specifications: view sorter/field sorter/order tempmax reset decorator Example: What s left after the ignoring and excluding is this string: type=1&pid=10002 Enter this string as the filteroptions value, replacing the special character ampersand (&) with the corresponding XML entity reference (&): type=1&pid=10002 You may also need to use other XML entity references instead of special characters in the :filteroptions value. Here s the complete set: Character XML Entity Reference < < > > & & ' " " Step 17 Customize configuration file LastModified.xml 17.1 Set the name attribute value in the <descriptor> element: <descriptor name="jira-filt"... AccuBridge Integration Services for Atlassian JIRA 13

14 Step 18 Test the AIS for JIRA Configuration 18.1 Go to directory ais-install/src Create three subdirectories: ITSErrorIssues, CPErrorIssues, and Logs Run AIS for JIRA in test mode: perl AccuBridgeIntegrationApplication.pl JiraExample/ApplicationSetup.xml t d (Adjust the directory-separator character, if necessary.) This validates all your configuration work, but does not perform any data transfers. If no errors are reported, proceed to the next step. Step 19 Perform an initial data transfer 19.1 Transfer JIRA data records to the AccuWork issue database, creating a set of new AccuWork issue records: perl AccuBridgeIntegrationApplication.pl JiraExample/ApplicationSetup.xml i d (Adjust the directory-separator character, if necessary.) The i option specifies that data transfer is to take place in the JIRA-to-AccuWork direction. If no errors are reported, you are ready to run AIS for JIRA in continuous mode. Step 20 Customize the Start AIS Script The start AIS script for Windows is a batch file, StartService.bat. The start AIS script for Unix/Linux is a Bourne (or Bash) shell script, StartService.sh. Edit the script appropriate for ais-mach, using the comments for guidance. The main customizations are: Establishing and authenticating the user identity ais-user. Specifying the wait period between cycles. Step 21 Start ongoing operation of AIS for JIRA 21.1 Run the start AIS script in a command shell: StartService StartService.sh (Windows) (Unix/Linux) AIS for JIRA will cycle indefinitely, sending diagnostic output to the command shell window, and pausing the specified interval between cycles. Each cycle will transfer data in both directions: JIRA-to-AccuWork and AccuWork-to-JIRA. AccuBridge Integration Services for Atlassian JIRA 14