In this article, you’ll get the background on how to use the integration once it’s been set up.
The following articles will help you in setting up the integration for the various tools. Read them first if you’d like to actually use the integration.
- Setting up synchronization with JIRA
- Setting up synchronization with Trello
- Setting up synchronization with Pivotal Tracker
- Setting up GitHub integration
The recommended workflow
When we planned and developed the integration with JIRA, Trello and Pivotal Tracker (let’s call them issue tracking tools), we had some basic concepts in mind about how would be the most straightforward to use it in most projects. The following workflow reflects these concepts. Of course, each project and organization differs in some way, so please be aware of the recommended workflow, but don’t take it too seriously. Also we’d like to ask for your feedback if you find that the integration in its current implementation doesn’t fit well into your environment.
So let’s see how we imagined working with StoriesOnBoard and an issue tracker:
1. The team/product owner/customer is planning in StoriesOnBoard. They are brainstorming, coming up with ideas, putting them onto the board
- in the unscheduled task if it's just a fuzzy idea
- or in a distant release if they think it's needed but not so important at the moment
- or in the next release if it's a must
They take notes of their ideas in the descriptions to help them remember later what they thought about.
2. On a sprint/release planning session, the team selects and discusses the most important stories and moves them into the next release. For the selected stories they (or the customer or a business analyst) identify acceptance criteria, write high-level specification (only with the details that's needed to understand the requirements).
3. When the team begins its work on the release, the Product Owner sends the stories into the issue tracking tool (all of them in the release, or just the specified ones). Issues automatically created in the issue tracking tool with the title and the description taken from StoriesOnBoard.
4. The team is working on the release: discussing the specifications, modifying/completing them in the issue tracking tool, also updating the issue's statuses there and they automatically get refreshed in StoriesOnBoard too.
5. While they are working on the release they can always have a high-level overview of how the release is progressing in StoriesOnBoard. They can select new stories into the current release or defer some to latter releases. If they have new ideas then they can put those also onto the board to the appropriate release (see step 1 above). These are not reflected in the issue tracking tool, till the Product owner is not sending them there (see step 2).
6. When they are finished with the release (all the tasks set to done in the issue tracking tool), they archive the release in StoriesOnBoard, so it disappears from the board with all its stories.
7. Repeat with step 2.
So the basic principles are:
- create and edit stories while they are just planned (or even they are only fuzzy ideas) on your map
- detail them only that’s essential for the planning and scheduling (high-level acceptance criteria, a few sketches)
- send them into your favorite issue tracking tool to support your implementation process
- put the implementation details there (implementation tasks, task assignments to team members, detailed specifications, test cases, documentation)
- leave the planning details to your story map (releases, themes, epics)
- get an overview in StoriesOnBoard
Let’s see how you can achieve this in StoriesOnBoard.
Push new cards into an issue tracking tool
This will create new issues in the connected issue tracking tool and set their title and description from your card. In JIRA type of the new issue will be the one you’ve selected for the export type in settings, in Pivotal Tracker it will be “Feature”. There are two ways of pushing cards:
Pushing cards individually
Pushing all cards in a release
Either way you’ll get a sign on the pushed cards that shows they are connected to an issue in the issue tracking tool and of course you’ll get a new issue there.
Status in the issue tracking tool
Please note that with the integration enabled you can’t change the status of the cards on the board. That’s because the issue tracking tool may have restrictions on it’s workflow. For example, only a person with the given role may have the permission to mark an issue done, or some fields could be mandatory for a given state. StoriesOnBoard wouldn’t know about those restrictions, nor it would be able to do anything about them (couldn’t ask for any arbitrary mandatory field’s value). That’s why it follows the status changes of the connected issue tracking system.
So for example when I hit “Start progress” for the “See details of selected product” in JIRA the card will look like the following on the board:
Change title and description
The way of changing cards’ title or description is the same as without any integration. The difference is that the change will be visible right away in the other tool (after a refresh). In the story map’s integration settings, you can choose which field to sync automatically (title, description).
Import issues from the issue tracking tool
If you have an already started project in your issue tracking tool or you created some issues there, you can import them into StoriesOnBoard. New cards will be created in StoriesOnBoard from the other tool’s issues that did not exist on your story map yet. Title, description and status are set from the issue’s respective attributes
The imported cards will be placed under “Cards imported from …” blue cards / Unscheduled cards: