Pivotal Tracker Integration

A Comprehensive Guide to Craft.io Integration with Pivotal Tracker

Maayan Ayalon avatar
Written by Maayan Ayalon
Updated over a week ago

Craft.io allows you to set up two-way synchronization with Pivotal Tracker. 

There are two steps required to integrate Craft.io and Pivotal Tracker. Follow them carefully so that the integration succeeds.

Important: In order to connect to Pivotal Tracker, you will need to have the login credentials to Pivotal Tracker.

Synchronize Craft.io to Pivotal Tracker

Data synchronization from Craft.io to Pivotal Tracker is by manual push. The first step of the configuration will connect Craft.io to Pivotal Tracker. 

Connecting Craft.io to Pivotal Tracker

Click Integrations from the user menu at the lower left, and choose to connect to Pivotal Tracker:

You will be asked to enter your Pivotal Tracker API Token;

To generate an API token, open your Profile page on Pivotal Tracker.

Scroll to the bottom of the page and copy the token. 

In Craft.io, paste the token into the text field and click Next.

For more about the Pivotal Tracker API Token, go here.

Select a Pivotal Tracker project from the drop-down menu, and click Next.

Note that a Workspace in Craft.io connects to a single project in Pivotal Tracker.

The Mapping Between Craft.io and Pivotal Tracker

The following items will be synced through the two-way integration between Craft.io and Pivotal Tracker. Note that syncing will never delete any items on both sides.

Type Mapping

Field Mapping

Important: 

  • Delivered/accepted items in Pivotal Tracker will immediately release the item in Craft.io and vice versa.

  • Releasing an item in Craft.io will mark the story in Pivotal Tracker as delivered/accepted upon sync, and vice versa.

Congratulations! You are now ready for your first sync!

You can synchronize the systems for the first time, or do it later. You can also choose to skip this step and sync selected items instead. For more information about syncing a specific item, see the Sync a Single Item section below. 

Note: You can always return to this step by clicking the Push button:

First Time Sync Between Craft.io and Pivotal Tracker

Note: On the first sync, the Pivotal Tracker project is synced into Craft.io. The import is performed once. To enable automatic updates from Pivotal Tracker to Craft.io, you will need to set up a webhook in Pivotal Tracker. See ‘Syncing Pivotal Tracker back to Craft.io’ below for more.

Select the parts of your product in Craft.io that you want to push to Pivotal Tracker.

The following options are available:

  • All Workspace - Syncs the entire Craft.io workspace to Pivotal tracker.

  • Releases - Allows you to select one or more Craft.io releases to be pushed to Pivotal tracker.

  • Sprint Backlog - Allows you to select one or more Craft.io sprint backlogs to be pushed to Pivotal Tracker.

Once you have completed your selection, click Sync. Depending on the size of your request, the procedure could take several minutes to complete.

When the sync is completed, you will see messages showing what was synced and/or skipped. Note that all Pivotal Tracker stories are created in Craft.io under the PivotalTracker Theme Product. You can move them to different Products across Craft.io using drag and drop in the Editor, or by bulk action in the Search and Filter tool. For more about Search and Filtering, look Here

Syncing Pivotal Tracker Back to Craft.io

The second step in synchronizing Pivotal Tracker with Craft.io is to configure a webhook in Pivotal Tracker so that changes made in Pivotal Tracker will be automatically updated in Craft.io. 

In Craft.io, select Integrations from user menu and click Sync Pivotal Tracker Back to Craft.io. You will see information on how to create a webhook in Pivotal Tracker, as well as the webhook listener URL to use in the webhook configuration. This is a unique URL that contains your product ID. Copy the URL to your clipboard and continue to the webhook configuration in Pivotal Tracker.

In Pivotal Tracker, open the Settings page of your project and select Webhooks in the sidebar.

Paste the webhook URL you copied earlier and select v5 from the drop-down menu. Click Add.

Syncing a Single Item

At times you may want to update or send a single Craft.io item to Pivotal Tracker. This can be a new item that you created or one that you updated. You can do this from the Pivotal Tracker section in the item’s right panel: 

Click Sync Item to sync the item to Pivotal Tracker. 

View the item’s status in Pivotal Tracker.

Click the Pivotal Tracker story title to open the corresponding issue in Pivotal Tracker.

The Pivotal Tracker integration Menu

You can always access the last sync log or disconnect the integration from the 3 dots integration menu: 

Did this answer your question?