Step by Step for Salesforce Pivotal Tracker Integration

Summary

This post does its best to give information about Salesforce Pivotal Tracker Integration as well as code samples and process workflow diagrams to support getting a base Salesforce and Pivotal Tracker Integration running by the end of the post, with references and more details included at the bottom for further playing around.

Table of Contents

Salesforce and Pivotal Tracker – Connecting the Systems

Salesforce and Pivotal Tracker have been two systems that I have used consistently for over a decade.  I started out using Pivotal Tracker as a tool for a Consulting Agency I worked for, and at that time I didn’t realize the full potential of utilizing those types of systems for all of their features. 

• Managing week to week expectations
• Planning your sprints based on historical performance
• Detailed reporting on status changes and story lagging in certain areas
• Integrations with outside systems natively

Whether you are more on the Salesforce Development side of the fence, or on the Project Management side of the fence, there are things that are built into Pivotal Tracker that make it easy to extend and do what we want.

Also, if you are a big Salesforce nerd you understand that the Force.com platform is amazingly extendable, with their being options for doing just about anything you could conjure up inbound and outbound.

It has its downsides and nuance and people complain about their rapid releases and quality assurance problems, but Salesforce is such a behemoth that they have their hands in EVERYTHING features wise.  It may be a reinvention of the wheel or a “not ready for primetime gaff”, but with Events and buying Mulesoft and Slack and other ventures they have gotten to a point where the platform is very malleable..

Pivotal Tracker as an Agile Project Management Tool

Pivotal Tracker on the other hand is not such a whale, they are more of a niche it seems and they don’t claim to be anything different.  They do have a lot of integrations set up as add-ons to their functionality, and I noticed that there is no out of box Salesforce connector for Pivotal Tracker.

Pivotal Tracker does have Github integrations which we get into in depth over here, but they also have generic integration options to do things via their flexible rest API or do things via their web-hooks that you can setup.  If you are familiar with Jira, Azure, or any Ticketing system that kanbans sprints, you’re familiar. Pivotal Tracker is a great alternative to those complex other PM systems so if you need something lightweight look into it if you haven’t already.

If you aren’t familiar with CRM or PM Systems I have no idea how you found your way to reading this, but I do my best here to explain it from every angle, simple and technical.  You can always reach out and contact me as well if there is something I can answer that my diatribes don’t address.

But getting back into the capabilities of connecting Salesforce and Pivotal Tracker systems… they give us the options to do a bi directional sync and support most anything we could dream up.

Integration Options per features of Salesforce and Pivotal Tracker

Inbound to Pivotal Tracker

Inbound to Pivotal Tracker we have the options for their REST API.

Outbound from Pivotal Tracker

Outbound from Pivotal Tracker we have the options to get updates sent to wherever we please.

Here is a GIF showing the path to the web-hooks URL entry once you are in the project view:

Handling Outbound Data from Pivotal Tracker to Salesforce

So what URL are we sending our Pivotal Tracker updates to get to Salesforce?

The JSON update that we get from Pivotal Tracker is an “activity” update, with some key fields to indicate what fields were changed and what the actual update is.  I have created a run of the mill Apex Class to store their update, which you can find below.  Note how they have the original and new values as objects they are sending, and what they refer to as a “Primary Source”.   For our intents and purposes we are going to count on that being our story ID.

Data Structure Examples

Pivotal Tracker Payload as Apex Class Type (JSON to Apex)

PivotalTrackerUpdatePayload.cls for Payload sent from webhook

Recap Our Progress….

What have we done so far?

Integrations can be complicated so I want to take stock of what we’ve looked at and make sure I haven’t lost anyone. Here is a high level list of what we’ve done:

• Decided to embark on a connection of Pivotal Tracker and Salesforce via the SF REST Apex Class we will make
• Created a Wrapper Class for the data structure from Pivotal Tracker they send as an activity update
• Decided we will use a Community/Experience Public Page to get a free REST API public that we can hit from Pivotal Tracker.

What is left?

• Create Apex Class mapped so we have an endpoint
• Create Logic in Class that will take the data and store it in memory in the form of our Wrapper Class, and then we will save to objects
  • Custom Objects for Project and Project Item are used with Tasks as part of this example.

I will assume you are with me so far and we will continue on, and the end product with an example script to activate the community from a shell script can be found on this Github link, that has a finished product you can reverse engineer.

https://github.com/sfboss/pt-sf

Saving Pivotal Tracker Web-hook Data to Salesforce

There are several other objects that you can see in their REST API documentation, and in our connector we utilized a structure that left Projects and Project Items objects in Salesforce that mapped to stories and Projects in Pivotal Tracker.  There are other things like labels and reporting details available on demand but we are going to “persist” the stories in Salesforce so that we can have that bi-directional sync. There are other use cases where we may get into talking more to Pivotal Tracker, but for now we will keep it simple with just projects and stories.

That means we will need to create Objects and fields in Salesforce that match up with the Pivotal Tracker JSON in a way that allows for them to be easily worked with as normal Salesforce Fields. We will keep the names to avoid confusion and will have the __c suffix on our fields since custom.

We will need to know how it maps, and have some options to create the fields, so let’s start with the mapping side of it. I have created a document that lays out the objects and fields involved that will tell you how it’s going to map.

Data Mapping Document

Creating the Objects and Fields in Salesforce

Custom Object Creation via Spreadsheet

We can also use a spreadsheet to create the fields quickly. We need two custom objects so let’s look at two easy ways to create fields and objects in Salesforce. They have out of box options that allow for a spreadsheet to specify the fields and details, and there is also an SFDX plugin that is handy once you get the hang of it that we can check out for the hell of it… but not as part of this post.

Here is a trailhead you can use and look at to follow along.  The details are dead simple though.  You have to populate the first row from left to right when you are putting down the labels, or what would have been the headers in your spreadsheet.   Below that you have the field type and have a selection to make there, but it will default and let you upload without it and map in their interface.  It comes down to populating the spreadsheet or pointing and clicking 30 times, I will let you decide how to proceed on that.

Here is a CSV that should be “plug and play” to be able to use, but I still suggest doing the trailheads and don’t shortcut yourself the knowledge. As long as no shortcutting happens I do think as part of learning seeing a working example is stress relief and I want to make sure I am following that.

Create From Package

The source is here for the information contained in this post and can be downloaded or worked with as an SFDX Package in a variety of ways, which are out of scope for this document. But use the Download .zip button in Github for the source and then use SFDX and workbench to deploy the objects folder… but that has some nuance with formats of the files that aren’t inviting to newbie SFDX users. That being said use at your own discretion as a separate way to easily deploy the fields into a SF org for this setup.

https://github.com/sfboss/pt-sf

Processing the Pivotal Tracker Web-hook Data in Salesforce via Apex REST

Creating a Public API Endpoint to Receive the Data

So this is crazy in my opinion that it works, and even crazier that it works on a scratch org in my opinion as well, but it does.  So take in these steps, and then watch the video provided underneath to get a visual, and then put it all together in an org yourself! We are taking advantage of the simple fact that an Apex Class granted access in a Guest profile for a Publicly available site in Experience Sites, means it is a public endpoint when the class is an Apex Rest Class. As mentioned several times this is for hobby not for enterprise use, so plan accordingly if security needs consideration as this is a hammer approach.

Prerequisite items:

If you are going to glide through this setup, you will probably want to be a bit functional in these areas:

• SFDX and Scratch Orgs
• Dev Hub enabled so you can get scratch orgs if you don’t have a Prod org enabled
  • A free developer edition account can work as a low level dev hub with low limits, but hey it works!
• Experience Sites

Feel free to keep reading but I wanted to give those to you as references at least first.

Get on with it!

1. Clone the project/create folder/get SFDX project going with src listed in the repository here
2. Create a scratch org with base settings (shape files and such are way out of scope for this, the generic project-scratch-def.json is fine)
3. Log into the scratch org and go into the Setup menu
4. Goto Digital Experiences > Settings
5. Enable Digital Experiences
6. Accept Defaults for domain etc.
7. Create a new Experience Site once they are enabled
   1. Note:  We actually don’t even have to publish the site!  The simple act of enabling the Apex class will make it available
8. In the Administration settings, goto “Pages” on the left menu
9. Goto Force.com Sites link
10. Goto Public Access Settings
    1. This is our “Guest” user for anything we made public on this community the permissions would be set here.
11. We want to enable the apex classes with PivotalTracker in the name, PivotalTrackerEndpoint and PivotalTrackerUpdatePayload
12. Grant Access to Project and Project Items in the “Objects” section
13. Save and exit back to Digital Experiences in the setup menu
14. Note your baseURL for your Community , as it will be used for the endpoint URL.

Creating an Apex REST class to Process the Payload

Here is the example APEX REST class I’ve mentioned over and over.  This would be installed in tandem with the other items in the repository, and then some quick steps can be taken to enable to Public endpoint connectivity.

I’ve commented it quite a bit and have 100% test coverage on the src in Github so I hope you are helped by it.

Tada!  Finished! …. Wait

That is a lot to unpack but let’s head over to the Pivotal Tracker test Project we have setup that I haven’t informed you about, and add in the Web-hook URL. It will be in the form of

[community base url] / services / apexrest / handleInboundPayload

You will plug in this full URL here as in this animated GIF, and as long as its plugged in and checked (activated), PT is going to forward updates for that Project into your URL.

Note:  If PT Failed to connect to your endpoint, It will uncheck this option for the web-hook URL and have an error.  If you do any activity in PT, it is instant so if the URL for the web-hook is still checked after you’ve updated some statuses you should be good.

Verifying our Changes

The easiest way without getting too fancy to verify our changes is two fold, one – check a report like this one and see if the data just shows up and you got lucky. Second way — enable logging in Developer Console for the Guest User and uncheck “Show my logs only” and view logs as the data hits your API.  You can start to narrow it down by even having the presence of a log, searching the log for “Exc” exception text, and digging deep into the log if needed, but hopefully it’s not too bad. If the Guest user has the proper permissions, and the Web-hook is configured in Pivotal Tracker, and your URL is correct, it should just start to flow.

Video of the Salesforce and Pivotal Tracker integration Steps

I know this is a gross over simplification all around with this setup but a video always helps.  Here is a start to finish voyeuristic view at the process of getting a folder project going in VSCode for the code in my repository, and creating a scratch org to do the magic with, and finally configuring PT and verifying connectivity.

Wrapping it up

There is real power in some of the real time updating you can do with these connectors and integrations, and I have witnessed first hand some of the time savings automating certain tasks can bring.  There are benefits across the board of the departments and company spectrums, with updates about location of Development items, and status updates automated by developer actions can solve some really annoying human error issues.  “Oh i forgot to update blah blah blah”.

Reporting on sprints data available?  Automate release notes.  Labels and tags available per story?  Tag components to stories to get data on which files are constantly breaking.  There are more and more use cases that a fully connected setup could bring to PMs and Devs on Salesforce Teams.

Some of the highlights I am going to show towards these benefits are listed in the below post series related to this page.  They are more tailored towards a very direct problem statement and solution or tool for success, but get the points across about benefit that you may not even have realized was able to be manifested with a tool like this.

• Trifecta Pivotal Tracker — Salesforce — Github integration allows for so many source control related branch automation/status update automation it can go a really long way
• Quality Assurance features like the creation of Sandboxes and prepping of hotfix environments after subscribing to the Apex Email Notifications
• Visibility into changes that allows for component level analysis of change impact and frequency
• As advanced as a dashboard with Project Items and Development Items (not mentioned here, but this is the Github work-item version of a Project Item) that can give visibility into the software life cycle PMs are usually lacking, at the mercy of Devs to share transparent honest updates.
• Branch management and out of box Pivotal Tracker-Github integrations make Branch and story association extremely straightforward, and with a hint of some CLI customizations we can script source package creation/ diff for a quick update of components involved in the change, and much more.

If you are looking for something more than this MVP detailed on this page, drop me a line or check out this offering of a DYI unlocked package to get some extra functionality and not have to worry about hiring developers for a complex implementation. Thanks for reading and if you have any questions let me know!  I will keep adding details slowly but surely.

References

• APEX Rest Class setup to accept outbound web-hook updates from Pivotal Tracker
  • Data Model Details
• Pivotal Tracker REST API documentation
• Salesforce Developer Documentation for APEX REST and HTTP adventures
• How to get a Public Endpoint open to the public internet with a Salesforce Org in 5 minutes! (to accept your PT REST Updates)
• Pivotal Tracker REST API Documentation
• Salesforce Public Digital Experience Page
• sfboss Salesforce Pivotal Tracker Integration MVP repository