Prerequisites
To connect piplanning.io to Jira Software Cloud or Jira Data Center via the ALM Connection, the following prerequisites need to be met:
Allow incoming connections from piplanning.io to the Jira instance on port 80/443 (HTTP/S).
If any network Firewalls/Proxies exist between piplanning.io and your Jira instance, then review our piplanning.io (Cloud) IP Range to be allowed.
It is strongly recommend to use a dedicated Jira Service User account (Systems Account) for the ALM Connection authentication. Authentication options are:
OAuth (recommended for Jira Cloud)
Basic Authentication
The data flow between piplanning.io and Jira uses two different protocols depending on the direction:
Updates from piplanning.io > to > Jira uses direct REST APIs requests.
Updates from Jira > to > piplanning.io, where updates in Jira flow back to piplanning.io, those updates are synchronized to piplanning.io using Jira WebHooks. piplanning.io does not continually poll Jira for updates, this is a good thing as it ensures not performance impact on Jira, and this is a strategic design decision. Important: if you use Jira Data Center then please ensure you allow the IP Range for Jira WebHooks to contact our piplanning.io WebHook Listener endpoints in the same Help Article (above).
piplanning.io only supports Company-Managed Jira Project Types. Note: Team-Managed Jira Project Types are not support.
We require a Jira Scrum Board to map to for each Team because in Jira the Sprint object only lives on a Scrum Board.
IMPORTANT
For performance reasons the Jira instance should respond to API requests relatively fast, ideally < ~3 seconds (approx. less than 3 seconds)
If you are concerned about the impact piplanning.io can have on your instance of Jira then this article will help remediate any issues proactively: Impact on Jira when connected to the piplanning.io.
What types of data does piplanning.io request from Jira?
The following data objects are retrieved or synchronized with Jira:
Jira Issue or Epic records (i.e. Work Items or Issue Types objects) in the Jira Project/s that are mapped to piplanning.io in the ALM Connection. Important: Only a limited amount of fields/attributes on each Issue-Type is synchronized with piplanning.io (see below).
Issue-link Types configured in the Jira Project/s that are mapped
Jira Project/s Workflow and Status and Jira Scrum Board/s metadata
Jira User data that is mapped to their piplanning.io User to map the Assignee or Reported By fields.
What types of data does piplanning.io push to Jira?
CRUDoperations on Issue-Types (Issues/Epics) in the Project/s that are mapped to piplanning.io. Note: allCRUDoperations are dependent on the permissions granted to the Jira Service User account used to authenticate the ALM Connection. See below for more details on what we recommend*👇Create or remove Issue/Epic-links in the Jira Project/s that are mapped to piplanning.io.
Create new Sprints (if you request that from the app, which we recommend if you want to reduce the manual effort and maintenance of setting up PI Session Sprints in Jira).
How to limit piplanning.io's access to Jira?
Ensure the Jira [Service] User account - used to authenticate the ALM Connection - only has the necessary permissions. Recommended
*Remove the DELETE_ISSUES permission from that Jira [Service] User account if you do not wish to grant piplanning.io the ability to delete work items in Jira.
Note: There is also a configuration setting in the SAFe PI sessions that can be set to 'Forbid users from deleting Sticky Notes that are synchronized with Jira'.
Set a JQL filter in the Jira Webhook: This will then only post updates from Jira > to > piplanning.io which are matching that filter. Recommended.
What type of data traffic to expect with the sync?
When a Sticky Note is created or updated in piplanning.io, then piplanning.io will issue a REST API request.
When a User executes a manual synchronization on either the ART Backlog Board or the Team Board or stops/starts sync for the whole PI Session, REST API requests are sent to Jira to fetch the corresponding work items for that Team/ART-level board. piplanning.io will fetch, from the ALM tool, the issue-types, statuses, boards, sprints and issues related to the PI Session.
Jira WebHooks: Dependent on any filtering restrictions on Jira WebHooks; when updates (events) are made in Jira, Jira WebHooks will be sent and received by the piplanning.io servers and the corresponding sticky note in piplanning.io will be updated.
Information stored on our servers from your Jira instance
Please, also review this article about piplanning.io attributes and Jira fields
Jira Project / Issue Metadata
Jira Project, Sprint and Scrum Board IDs
Issue-Key of Issues synced to piplanning.io
Issues-Type
Issues Links (the Issue-Link between Jira Issues)
Issue-Links
Epic-Links
Parent/Child-Links
Issue Status (based on the specific Jira Project Workflow)
Issues fields or metadata that is synced to piplanning.io is limited to:
Summary (text field value)
Story Points value or WSJF (numeric field value)
Assignee (Jira User Key/ID)
Reporter (Jira User Key/ID)
User ID/Key (dependent on ALM User Mapping in piplanning.io)
Team (in case the a team field is synchronised)
Personally Identifiable Information (PII) for Jira Users
Email Address
Username
Jira Account-ID/User-Key
Note: In case user map their piplanning.io user account to their Jira account, we do map the two user ID's. The actual email address, username or other user data is not pulled from Jira into piplanning.io.