Pivotal Tracker Help


Integrations

Tracker can publish activity in your project to Twitter, a Campfire chatroom, or a custom application that listens to HTTP requests. You can create integrations, in any project you own, that allow you to import from and link to Tracker stories, to tickets or issues in external bug tracking, or to customer support applications. You can also associate your source code commits with stories and update story state automatically via special commit message syntax.

Integrations can be enabled and managed in Project Settings on the Integrations tab. If you're in your project, you can choose Configure Integrations after clicking the Settings icon toward the top right of the Sidebar.

You may need to open up your firewall to allow incoming requests from Tracker integrations (e.g., if you have an internal JIRA instance). If this is needed, ask your network administrator to allow the following IP addresses:

  • app01.pivotaltracker.com
  • app02.pivotaltracker.com
  • app03.pivotaltracker.com
  • app04.pivotaltracker.com
  • worker01.pivotaltracker.com
  • worker02.pivotaltracker.com
  • worker03.pivotaltracker.com
  • worker04.pivotaltracker.com

However, please note that the IPs assigned to these addresses may change without notice.

Note: If the description field for an item in an integration exceeds 20,000 characters, the content will be truncated in its Tracker story.

Contents

Available Integrations

Twitter

To share project activity on Twitter, click the button on the project’s 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 and 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 Remove Twitter Credentials 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.

Campfire

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 and Epics?: Check this box to enable notifications when new stories and epics are created.

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. It’s possible to add multiple web hooks per project on the Integrations page.

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

The POST body of these requests will contain JSON 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 one activity so an activities element will not be present. This is an example of a request that your URL will receive when Darth Vader accepts a story:

{
  "occurred_at": 1382568826000,
  "highlight": "accepted",
  "primary_resources": [
    {
      "story_type": "feature",
      "name": "Reactor leak reported in Detention Block AA-23",
      "url": "http:///story/show/563",
      "id": 563,
      "kind": "story"
    }
  ],
  "changes": [
    {
      "story_type": "feature",
      "name": "Reactor leak reported in Detention Block AA-23",
      "new_values": {
        "accepted_at": 1382568827000,
        "before_id": 6024,
        "after_id": 559,
        "current_state": "accepted",
        "updated_at": 1382568826000
      },
      "original_values": {
        "accepted_at": null,
        "before_id": 6643,
        "after_id": 565,
        "current_state": "delivered",
        "updated_at": 1382568825000
      },
      "id": 563,
      "change_type": "update",
      "kind": "story"
    }
  ],
  "message": "Darth Vader accepted this feature",
  "project_version": 1037,
  "performed_by": {
    "name": "Darth Vader",
    "initials": "DV",
    "id": 101,
    "kind": "person"
  },
  "guid": "99_1037",
  "project": {
    "name": "Death Star",
    "id": 99,
    "kind": "project"
  },
  "kind": "story_update_activity"
}
    

The format of the JSON feed is the same as the API activity feed (see Activity Response Formats). To experiment with the activity web hook, and see the notification requests, we recommend using RequestBin. Make a RequestBin, enter the bin's URL in the Web Hook URL in Tracker (on the project Integrations page), then watch that RequestBin 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 JSON body), so that your web hook-based integration will not break when a new version of the API is introduced.

Source Code Integrations

The Tracker API supports integration with post-commit hooks of Source Control Management (SCM) systems such as Subversion, Git/Github, etc. When a commit is made to the SCM, a trigger can call the Tracker API to add a story comment with the commit ID, author and message. It can also optionally change story state.

For all the details, including commit syntax as well as instructions on how to enable SCM integration, please see the API Help page.

Bug/Issue Tracking Tool Integrations

Tracker allows your team to prioritize and collaborate around stories that are linked to issues/tickets in other systems (e.g., 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 dropdown. 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 option in your project’s Sidebar (e.g., JIRA). If you've configured the integration properly, when you open the Integrations panel, 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 dropdown 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 (e.g., 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.


You can integrate your project with your hosted or local jira instances that are externally accessible. This integration works with Jira versions 5.0 and above. Select JIRA from the dropdown 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.

Note: The filter you use for the integration should be shared (made public) in JIRA, otherwise the integration may fail. Also, the integration might fail if the filter you have chosen returns too many results. There isn’t a numeric limit, but the integration will timeout if it takes more than 60 seconds to retrieve all results, due to number of issues, Internet speed, and/or the size of the issues themselves.

Base URL: This is the URL of your JIRA instance (e.g., http://yourcompany.atlassian.net).

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 copy of the default 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 nonstandard workflow, issue state updates from Tracker may not work. Also, you may 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 dropdown on your project's Integrations page, and enter the following:

Company: You can find this in the URL in your company's community on Satisfaction(e.g., 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 (e.g., 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 completed. Topics of type other than idea or problem (e.g., 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.

Note: The integration might fail if the community site you have chosen returns too many results. There isn’t a numeric limit, but the integration will timeout if it takes more than 60 seconds to retrieve all results, due to number of topics, Internet speed, and/or the size of the topics themselves.


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

URL: This is your Zendesk URL (e.g., https://yourcompany.zendesk.com, or any vanity URL you have configured, e.g., https://support.yourcompany.com).

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 and looking at the URL of the page (e.g., https://yourcompany.zendesk.com/rules/5678 or https://yourcompany.zendesk.com/agent/#/filters/5678). You can either use one of the default views (e.g., "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.

Note: The integration might fail if the view you have chosen returns too many results. There isn’t a numeric limit, but the integration will timeout if it takes more than 60 seconds to retrieve all results, due to number of tickets, Internet speed, and/or the size of the tickets themselves. Try creating another view which returns a smaller set of tickets for your integration.


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 dropdown on 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, and 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.

Note: The integration might fail if the Bug Status values, product, and/or component you have chosen returns too many results. There isn’t a numeric limit, but the integration will timeout if it takes more than 60 seconds to retrieve all results, due to number of issues, Internet speed, and/or the size of the issues themselves. Try changing Bug Status values, product, and component to values that return a smaller set of issues for your integration.

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

Password: This is 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 "insider group" for this to work.

Update State?: This 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 specified above). If you're having difficulties getting the Bugzilla integration to work, please see this troubleshooting article.

Other Integration

The Other integration type allows you to add an editable named external ID field to stories, or to create your own custom integration that allows importing of stories from external sources via drag and drop. To configure a custom integration, select Other from the dropdown 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 (note that the story type must be one of feature, bug, chore or release):

    <?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.

You can drag these into the Icebox or Backlog, which will create Tracker stories, with links to the external resources based in the external_id element in the XML. It's possible to keep stories and corresponding external resources synchronized via the Activity Web Hook and API.