Create configuration

Enter valid connection information to create a bug tracker “configuration”:
– Name: will identify the connection and be used as a tag for synchronized stories so it must be unique.
– Type: choose your bug tracker tool: Mantis BT, Bugzilla, Trac, Redmine or Jira.
– URL: the URL of your bug tracker.
– Login: the username of a user having sufficient permissions on your bug tracker, according to what you want to do.
– Password: the password of a user having sufficient permissions on your bug tracker, according to what you want to do.

iceScrum will try to connect to your bug tracker automatically when you enter the password. If the connection fails, an error message will be displayed underneath but a closer look to the logs (icescrum.log and catalina.out) will give you more insights about the issue.

If the connection succeeds, additional fields will be displayed. Remote projects will be fetched and you will have to choose the one you want to integrate with your iceScrum project (for Trac, there is only one possible Project for a given URL).

Don’t forget to click on “Save configuration”.

Update or delete configuration

You can update connection information on existing configurations.

If you want to stop all automatic imports and synchronizations, you can either disable the configuration or delete it.

Refresh remote fields

In order to create import and synchronization rules, you will use fields and values that are fetched from the bug tracker. They are automatically fetched on the first connection and cached in iceScrum. If you want to use the latest versions of these fields, click on “Refresh remote fields”.

Bugzilla configuration

This integration requires a XML-RPC endpoint on your Bugzilla server. It is enabled by the XMLRPC::Lite Bugzilla Perl module (alternatively, it seems that Test::Taint could do the job).

You can check that your Bugzilla server has the XMLRPC::Lite Perl module installed by checking this URL in your browser: http://bugzilla.yourserver.com/xmlrpc.cgi, it should display a blank page. You may also try this cURL command that returns the version of your Bugzilla server:

curl http://bugzilla.yourserver.com/xmlrpc.cgi 
     -H "Content-Type: text/xml" 
     -d "<?xml version='1.0' encoding='UTF-8'?><methodCall><methodName>Bugzilla.version</methodName><params></params></methodCall>"

If an error is returned then there is a problem on your Bugzilla server, probably related to missing modules. You can log in as root on your Bugzilla server and check the installed modules:

./checksetup.pl --check-modules

You should have XMLRPC::Lite and all the required modules installed. If it is not the case, here is how to install a module (repeat for each required module):

./install-module.pl XMLRPC::Lite

Then check that it is correctly installed with:

./checksetup.pl --check_modules

If an installation fails, it may be related to a missing XML parser library: XML::Parser. The installation of this module via CPAN may fail so here is how you can install it with apt-get (on Debian-base operating systems):

sudo apt-get install libxml-parser-perl

Trac configuration

This integration requires a XML-RPC endpoint on your Trac server. It is provided by the XML-RPC plugin (see http://trac-hacks.org/wiki/XmlRpcPlugin).

You can install the plugin with the following command:

sudo easy_install -Z -U http://trac-hacks.org/svn/xmlrpcplugin/trunk

Then, you need to enable it in your trac.ini configuration file:

[components] 
tracrpc.* = enabled

You can check that this plugin is properly installed by checking this URL in your browser: http://yourTracServer.com/YourProject/rpc. It should display the RPC API documentation, including the API version. The iceScrum integration requires the API version 1.1.2 or greater (this is not the Trac version). This page also displays the required permissions for each action.

The Trac user used by iceScrum must have the following permissions (pick one):
– either XML_RPC, TICKET_VIEW and TICKET_MODIFY,
– or XML_RPC and TICKET_ADMIN,
– or TRAC_ADMIN
Permissions may be inherited from groups such as “authenticated” or “anonymous”.

If you use the AccountManager plugin login module, please read the following instructions:

In order to use the XML-RPC API, iceScrum needs to authenticate through automatic means. The default Trac HTTP login module (trac.web.auth.loginmodule) allows automatic authentication, while the AccountManager HTML login module (acct_mgr.web_ui.loginmodule) does not. Fortunately, the HttpAuthPlugin plugin reinstalls the HTTP authentication on specific paths. Here are the instructions to use it:

1. Install HttpAuthPlugin :

easy_install -Z -U http://trac-hacks.org/svn/httpauthplugin/trunk/

2. Enable the plugin in trac.ini

[components]
httpauth.* = enabled

3. Configure the path for HTTP authentication in trac.ini

[httpauth]
paths = /login/xmlrpc

4. Configure Apache so it does not strip the authorization information (in httpd.conf):

WSGIPassAuthorization On

Redmine configuration

On the Redmine side, you only need to enable the REST web services when logged in with an administrator account, as follow:
Administration > Settings > Authentication > Enable REST web service

The Redmine user that will be used by iceScrum needs “Save queries” “View issues” and “Edit issues” permissions on the projects you want to integrate. If you want iceScrum to retrieve custom fields or users from Redmine then the user will need to be an administrator (this may seem overkill but Redmine seems to require that).

Please note that when creating the configuration, you will not get an error if you enter wrong credentials. Instead of failing, Redmine will provide the list of public projects that are available for anonymous users. Thus, please ensure that the projects match the projects associated to the iceScrum Redmine user before saving the configuration.

Jira configuration

Jira REST API
The Jira REST API is required by this integration. It should be enabled by default on your Jira instance.

Jira user
The Jira user that will be used by iceScrum needs sufficient permissions depending on what you want to do. Basic usages require browsing projects and issues and updating issues. Most advanced ones require resolving issues, closing issues and changing the issue assignee and reporter.

When creating the configuration, if you enter a wrong password several times in a row then the authentication for this user through the API will be disabled and you will get a “403 forbidden” error message. In such case, you will need to authenticate through the Jira application and enter a CAPTCHA to re-enable the API authentication.

Transitions
The Jira REST API lacks proper support for transitions so we apologize for the limitations you will come across in this integration.

If you want to get a nice list of available transitions then the iceScrum Jira user will need to be an administrator. In this case, all the transitions will be displayed, grouped by workflow, for all the workflows of your Jira server (because Jira provides no way to filter the workflows associated to a specific project). Otherwise, you will have to enter the transition name by hand, which is more error prone. In both cases, the transition will be triggered according to its name and only its name (there is no technical id check nor workflow check) so it needs to match the name displayed in Jira when logged in as the iceScrum Jira user (ensure that you use the same language).

If the synchronization rules defined on a given story for a given state include a transition update and if the transition is associated with a screen, iceScrum will automatically try to complete the screen according to the other rules. Remaining rules will be executed through a regular update. Please note that updates provided with the transition may be overridden by Post Functions defined on the transition.

Workflow schemes allow defining different workflows depending on the issue type. Be careful when defining transition rules: the transitions must be available for all the issue types that will be imported in your iceScrum Jira configuration. If you have to manage issue types that have different workflows then we recommend that you create an iceScrum Jira configuration for each issue type.

Create import rules

Once your connection is set up, you can create import rules in order to import issues from your bug tracker into iceScrum. They will be imported as iceScrum stories.

You can filter the issues to import according to remote fields:
– Mantis BT: Mantis filter: a filter that exists in Mantis. You cannot create multiple import rules for the same filter.
– Bugzilla: Component, Status.
– Trac: Component, Status, Type, Resolution, Priority, Version, Milestone. If you choose no field then all the issues will be fetched.
– Redmine: Query: a query saved on the Redmine user account used by iceScrum. You cannot create multiple import rules for the same query.
– Jira: Filter: a favourite filter saved from a search on the Jira account used by iceScrum. You cannot create multiple import rules for the same filter.

Then you can customize the new stories:
– Tags of created stories: you can choose tags to categorize the stories (e.g. depending on the import rule) and find them easily later.
– State of created stories: you can create “Suggested” stories that go in the sandbox and “Accepted” stories that go in the backlog. Further states aren’t supported since they rely on the iceScrum workflow.
– Type of created stories: you can choose “User story”, “Story defect”” or “Technical story”.
– Associate to feature: optional feature to associate the story with.

Finally, configure the import:
– Pull every: you can choose manual import (see explanation below) or periodic ones (every 1, 5, 15, 30 or 60 minutes).
– Allow duplicate stories from issues: whether iceScrum should create new stories for issues that have already been imported. For regular usages, duplicates should be avoided.

Don’t forget to click on “Add import rule”. You can add as many import rules as needed.

Manual imports can be triggered from the sandbox and the backlog by clicking on the “Refresh import” button in the toolbar. In the sandbox, only rules for “Suggested” stories will be triggered. In the backlog, only rules for “Accepted” stories will be triggered.

Imported stories

Imported stories are created according to the imported issue data (values may be truncated to fit iceScrum fields) and your custom configuration. Some fields receive “special” values:
– creator: filled with the first Product Owner or Scrum Master found in your team.
– tags: in addition to custom tags, the configuration name is added (capitalized and without spaces). This tag is displayed in the configuration summary, click on it in order to display all its imported stories.
– origin: combines the configuration name and the issue ID that materialize the link between the story and the issue.

Delete import rules

Import rules cannot be updated. You can delete them by clicking on the cross.

Create synchronization rules

When imported stories change state in iceScrum, you can automatically update the corresponding issue thanks to synchronization rules. Only stories that have been imported from a bug tracker can trigger updates of remote issues through the synchronization process.

First, choose the state that triggers the update.

Then, choose the remote field to update and its new value.

For textual fields, you can enter a string with optional variables which value depends on the context of the story:
– Story: id, name, description, notes, origin, effort, rank, affectVersion, suggestedDate, acceptedDate, plannedDate, estimatedDate, inProgressDate, doneDate
– User: lastName, firstName, username, email
– Product: id, name, pkey, description, startDate, endDate
– Release (for stories planned in a sprint): orderNumber, name, startDate, endDate
– Sprint (for stories planned in a sprint): orderNumber, goal, velocity, capacity, deliveredVersion, startDate, endDate
To use these dynamic values, wrap them into ${…}, e.g. ${story.name} … ${user.username}.

Delete synchronization rules

Synchronization rules cannot be updated. You can delete them by clicking on the cross.