Tracker can publish activity in your project to Twitter, a Campfire chatroom, or a custom application that listens to http requests. You can also create integrations that allow you to import from, and link stories to tickets or issues in external bug tracking or customer support applications.

Integrations can be enabled and managed in project settings, on the Integrations tab. If you're in your project, choose Configure Integrations in the Project drop-down menu.

You may need to open up your firewall to allow incoming requests from Tracker integrations (for example, if you have an internal JIRA instance). If this is needed, ask your network administrator to allow the IP addresses of "api.pivotaltracker.com" and "api2.pivotaltracker.com". However, please note that the IPs assigned to these addresses may change without notice. You can use the commands host api.pivotaltracker.com and host api2.pivotaltracker.com to confirm the current IP addresses.

NOTE: Integrations are a new feature, and things may not always work as expected when interacting with external applications and resources. We will be adding new integrations, and improving how they work incrementally, based on your feedback. Please let us know about your experience with Tracker integrations, as well as what you'd like to see added or improved. Email us at tracker@pivotallabs.com, or share your feedback with the Feedback.

To share project activity on Twitter, click the button on the project Integrations page to authorize your project with Twitter. After being passed to Twitter to confirm Tracker's access to your Twitter account, Tracker should begin sending updates about new stories, comments, and when stories are delivered, accepted, or rejected.

If you want to turn off Twitter integration, return to the Integrations page and click the Twitter disable button.

Note: By default, tweets are public (and searchable), so if your project is confidential, enable the 'Protect My Updates' option in your project's Twitter account settings.

See Tracker project activity in your Campfire chat room!

To enable Campfire room notifications, enter the following on your project Integrations page:

Campfire Subdomain: This is the name of your Campfire account, and the first part of your Campfire URL (http://yourcompany.campfirenow.com).

Campfire API Authentication token: Find this by clicking the My Info link in Campfire.

Room ID: The room ID is the last part of the URL when in a Campfire room (http://yourcompany.campfirenow.com/room/225611).

Use SSL?: Check this box if you have SSL enabled for your Campfire room.

Publish New Stories?: Check this box to enable notifications of new stories.

Publish Story State Changes?: Check this box to enable notifications when stories are accepted, delivered, or rejected.

Publish Story Comments?: Check this box to enable notifications when comments are added to stories.

Note: We've noticed that if you're logged into a Campfire room as the same user as the API token, in the same browser, you may not see your Tracker notifications in the Campfire room. We recommend creating a new Campfire user, specifically for the integration, and using that user's API token for the integration.

Activity Web Hook

The activity web hook allows your application to listen for activity in your project, as HTTP POST requests.

Tracker will send POST requests to the URL that you specify here every time a story activity occurs, for example when someone creates or edits a story, adds a comment, changes a story's state, etc.

The POST body of these requests will contain XML describing the activity, as well as the affected story, in the exact same format as the API activity resource, except in this case there is only 1 activity so an activities element will not be present. This is an example of a request that your URL will receive when Captain Kirk accepts a story:

    <?xml version="1.0" encoding="UTF-8"?>
    <activity>
      <id type="integer">1031</id>
      <version type="integer">175</version>
      <event_type>story_update</event_type>
      <occurred_at type="datetime">2009/12/14 14:12:09 PST</occurred_at>
      <author>James Kirk</author>
      <project_id type="integer">26</project_id>
      <description>James Kirk accepted &quot;More power to shields&quot;</description>
      <stories>
        <story>
          <id type="integer">109</id>
          <url>https:///projects/26/stories/109</url>
          <accepted_at type="datetime">2009/12/14 22:12:09 UTC</accepted_at>
          <current_state>accepted</current_state>
        </story>
      </stories>
    </activity>
    

To experiment with the activity web hook, and see the notification requests, we recommend using PostBin. Make a PostBin, enter the bin's URL in the Web Hook URL in Tracker (on the project Integrations page), then watch that PostBin URL as you make changes to stories in your project.

Note: You can specify which version of the API to use (for the format of the POST XML body), so that your Web Hook based integration will not break when a new version of the API is introduced.

Bug/Issue Tracking Tool Integrations

Tracker allows your team to prioritize and collaborate around stories that are linked to issues/tickets in other systems, for example bug tracking applications, customer support ticket systems, etc.

In general, external tool integrations will involve these steps:

1. Create a new integration: On your project's Integrations page, choose the type of integration from the drop down. Details on all supported integrations types can be found below.
   
2. Configure and activate the integration: Then enter integration-specific configuration details. Most will require some form of user credentials, location/URL information, and possibly the ID of a saved search or a filter.
   
3. Import stories from external tool: After you create an integration, you should see a new panel in your project, in the More drop-down menu (for example JIRA). If you've configured the integration properly, you should see a list of tickets or issues from the external tool:
   
   
4. Drag an issue or ticket into the icebox or backlog. This will create a new story, linked to the external issue/ticket. Stories that have external links have an 'e' in the story icon, like this:
   
5. Work on linked stories in Tracker. Depending on the integration type, state changes and comments to linked stories will be reflected in the integrated external tool/application. For example, starting a linked story will mark the corresponding JIRA issue as in-progress, and when the story gets accepted, the ticket will be marked as resolved.
   

Tracker integrates with Lighthouse, a simple web-based issue tracking application. To integrate your project with Lighthouse, select Lighthouse from the drop down on your project's Integrations page, and enter the following:

Account: This is your Lighthouse account name, and can be found in the first part of your Lighthouse URL, for example http://yourcompany.lighthouseapp.com.

Token: You'll need to generate an API Token in Lighthouse. We recommend you create a Lighthouse user specifically for the integration. You can generate and see tokens on your Lighthouse user page. Note - Public Lighthouse accounts should leave the token blank.

External Project ID: This is the unique ID of your Lighthouse project, which can be found in a project URL, for example http://yourcompany.lighthouseapp.com/projects/1234-project-name/overview. Enter just the numeric part.

Bin ID: With this integration, you can control which tickets to import based on a saved Lighthouse ticket bin. A bin is a named saved search, and has an ID, which you can see in the bin URL: http://yourcompany.lighthouseapp.com/projects/1234-projectname/bins/5678.

Stories created from Lighthouse tickets will be linked to the corresponding ticket, and you will see a link to the Lighthouse ticket on the story. Any comments added to the story will appear as notes in the Lighthouse ticket. Also, as the Tracker story is started, finished, and accepted, the state of the linked Lighthouse ticket will be updated accordingly.

To integrate your project with your JIRA instance (hosted or local instances that are externally accessible), select JIRA from the drop down on your project's Integrations page, and enter the following:

API Username: This is the username of a JIRA user that has read/write access to your JIRA instance, via the JIRA API. We recommend creating a user specifically for this integration.

API Password: Password of the JIRA user.

Filter ID: For this integration, Tracker uses a saved JIRA filter to choose which issues to show in the JIRA import panel. You can save a search in JIRA as a filter, and filters appear on your JIRA dashboard. Grab the ID out of the filter URL, which you can see in your browser by hovering over the filter link. Look for requestId=10000 in the URL.

Base URL: This is the URL of your JIRA instance, for example http://yourcompany.onjira.com.

Update JIRA to allow Tracker Integration:

1. Create a new user with username 'tracker_integration'
2. Create a new group called 'tracker_integration' and add a 'tracker_integration' user
3. Grant the following permissions to the new 'tracker_integration' group or user: Edit Issues, Assign Issues and Close Issues
4. Create a custom workflow in JIRA with additional conditions on each transition to allow users in a designated tracker integration group to complete that transition, as described in the JIRA docs. To do this, edit the Transitions and add the tracker integration group as an "OR" condition for the following Transitions: Open -> Start Progress, In Progress -> Stop Progress, Resolved -> Reopen Issue, Reopened -> Start Progress, Closed -> Reopen Issue
5. On the Project Admin page change the Workflow Scheme to the new scheme

Stories created from JIRA issues will be linked to the corresponding issue, and you will see a link to the JIRA issue on the story. Any comments added to the story will appear as comments in the JIRA issue. Also, as the Tracker story is started, finished, and accepted, the state of the linked JIRA issue will be updated accordingly.

Currently, only the default JIRA issue workflow is supported. If you've configured your JIRA instance with a non-standard workflow, issue state updates from Tracker may not work. Also, you'll need to enable API access for your JIRA instance, in Administration/General Configuration (it's the Accept remote API calls option).

This integration will let you see unresolved topics from your Satisfaction support community, and create corresponding stories. To enable it, select Satisfaction from the drop down and enter the following:

Company: You can find this in the URL in your company's community on Satisfaction. For example - http://www.getsatisfaction.com/yourcompany.

Product: This can be found in your company's Satisfaction URL, when you're looking at topics for a specific product. Example - http://www.getsatisfaction.com/yourcompany/products/yourproduct.

Once enabled, The Satisfaction import panel (under the More drop-down menu in your project) should list ideas and problems that you see in your Satisfaction management view (http://www.getsatisfaction.com/yourcompany/admin/topics), that are not marked as complete. Topics of type other than idea of problem, for example praise, will not appear.

Dragging from the Satisfaction panel will create stories with links to the corresponding Satisfaction topics. Because Satisfaction topics are publicly visible to your user community, they are not automatically updated based on story comments or state changes in Tracker.

Zendesk is an on demand customer support help desk. To integrate your project with it, select Zendesk from the drop down on your project's Integrations page, and enter the following:

URL: This is your Zendesk URL, for example http://yourcompany.zendesk.com or any vanitiy URL you have configured.

Zendesk User Email: The email of the Zendesk user which you want to use for integration purposes. We recommend you create a Zendesk user specifically for the integration.

Zendesk User Password: The password of the Zendesk user which you want to use for integration purposes.

View Id: This lets you control which tickets are shown in the Zendesk import panel, by specifying the ID of a Zendesk view. You can find a view's ID by clicking on a view in Zendesk (in the Views dropdown) and looking at the URL of the page (eg. http://yourcompany.zendesk.com/rules/5678). You can use one of the default views, for example "All unresolved tickets", or a custom one.

Stories created from Zendesk tickets will be linked to the corresponding ticket, and you will see a link to the Zendesk ticket on the story. Comments added to the story in Tracker will be pushed to Zendesk as a private comment. All story state changes in Tracker will add a private comment to the Zendesk Ticket. When a Zendesk ticket in the 'New' status is started in Tracker the Ticket will be transitioned to 'Open'.

Bugzilla is a widely used, free defect tracking system. This integration works with Bugzilla versions 3.4 and above. To integrate your Tracker project with Bugzilla, select Bugzilla from the drop down on your project's Integrations page, and enter the following:

URL: This is the URL of your Bugzilla server, for example http://www.my-bugzilla.com:8081.

Bug 'Status' values to exclude: This is the comma separated list of status names that should be excluded from the imported bugs. The default values are RESOLVED, VERIFIED, CLOSED. If this field is left blank, all bugs will be imported.

Product: Enter the name of your Bugzilla Product. Use this in conjunction with the Component field to narrow the bugs to be imported. This field is optional.

Component: Enter the name of your Bugzilla Component. Use this in conjunction with the Product field to narrow the bugs to be imported. This field is optional.

Username: The username/email of the Bugzilla user which you want to use for integration purposes.

Password: The password of the Bugzilla user which you want to use for integration purposes.

Update Comments?: If enabled, comments created in Tracker will be added to the linked Bugzilla bug.

Comments Private?: If enabled, comments will be marked as private. Note: the user that is used for the integration must be a member of an 'insidergroup' for this to work.

Update State?: Adds a state change comment to the Bugzilla bug.

Stories created from Bugzilla bugs will be linked to the corresponding bug, and you will see a link to the Bugzilla bug on the story.

Note: In order for this integration to work, your Bugzilla installation must be exposed outside of your firewall (at the URL specifed above).

Other Integration

The Other integration type alows you to add an editable named external ID field to stories, or to create your own, custom integration that allows import of stories from external sources via drag and drop. To configure a custom integration, select Other from the drop down on your project's Integrations page and enter the following:

Name: Give this integration a name, for example "My Ticket System". This will be the label of the external ID field in stories, and, if you specify an Import API URL as well, this will be the name of the import panel.

Base URL: This URL will be used to link stories to the external system. If your stories are to be linked to http://www.myticketsystem/1234, enter http://www.myticketsystem/ in this field.

Import API URL: This is optional. If you enter a URL, you'll see an import panel in your project, with data fetched from that URL. The URL has to return XML in the following format:

    <?xml version="1.0" encoding="UTF-8"?>
    <external_stories type="array">
      <external_story>
        <external_id>foo</external_id>
        <name>More power to shields</name>
        <description></description>
        <requested_by>James Kirk</requested_by>
        <created_at type="datetime">2008/12/10 00:00:00 UTC</created_at>
        <story_type>feature</story_type>
        <estimate type="integer">1</estimate>
      </external_story>
      <external_story>
        <external_id>bar</external_id>
        <name>I am story 2</name>
        <description>I am a description</description>
        <requested_by>I am the reporter</requested_by>
        <created_at type="datetime">2009/12/10 00:00:00 UTC</created_at>
        <story_type>bug</story_type>
        <estimate type="integer">2</estimate>
      </external_story>
    </external_stories>
    

Based on the above XML example, you would see the following in your project.