Portavio User Guide

Everything you need to know to get the most out of your portfolio intelligence platform.

🚀 Quick Start (5 Minutes)

Step 1: Connect Your Jira Instance

1. Click "Connect Jira" in your Portavio dashboard
2. Enter your Jira Cloud URL (e.g., yourcompany.atlassian.net)
3. Generate an API token:
   • Go to Atlassian API Tokens
   • Click "Create API token"
   • Give it a name (e.g., "Portavio")
   • Copy the token
4. Paste the token in Portavio
5. Click "Connect"

Step 2: Sync Your First Project

1. After connecting, click "Sync Now"
2. Portavio will automatically fetch:
   • All your projects
   • Epics and stories
   • Teams (if configured)
   • Sprint data
   • Issue relationships
3. First sync takes 30-60 seconds depending on data volume
4. Subsequent syncs are faster (incremental updates)

Step 3: Explore Your Dashboard

Once synced, you'll see:

• Overview: High-level portfolio metrics
• Projects: All projects with health status
• Teams: Velocity, capacity, and load
• Epics: Progress and dependencies
• Risks: Detected blockers and issues

🔌 Connecting Jira Cloud

Prerequisites

• Jira Cloud account (not Jira Server/Data Center)
• Project access (view permissions at minimum)
• Admin permissions recommended for full features

API Token Permissions

The API token inherits your Jira permissions. Portavio can only access data you can see in Jira.

Security

• Tokens are encrypted in our database
• We never share your data with third parties
• You can revoke access anytime in Jira settings
• Read-only access (Portavio never modifies Jira data)

🔄 First Sync

What Gets Synced?

Portavio imports the following data from Jira:

Projects

• Project name, key, and description
• Project type (Business, Software, Service Desk)
• Project lead
• Project status

Epics

• Epic name and key
• Epic status and progress
• Story points (total and completed)
• Start and due dates
• All child issues

Issues (Stories, Tasks, Bugs)

• Issue key, summary, description
• Issue type, status, priority
• Assignee and reporter
• Story points
• Sprint assignments
• Labels and components
• Parent/child relationships

Sprints

• Sprint name and goal
• Start and end dates
• Sprint status (active, closed, future)
• Committed vs completed story points

Teams (if configured in Jira)

• Team name
• Team members
• Associated projects

Sync Frequency

• Manual: Click "Sync Now" anytime
• Automatic: Every 6 hours (configurable in Settings)
• Incremental: Only changed data is fetched after first sync

📝 Issue Types - Best Practices

Portavio works best when you follow these Jira issue type conventions:

Epic

When to use: Large feature or initiative spanning multiple sprints

• Should contain 10-50 story points worth of work
• Duration: 2-8 weeks typical
• Has clear acceptance criteria
• Assigned to one or more teams

Example: "User Authentication System", "Payment Gateway Integration"

Story

When to use: User-facing functionality deliverable in one sprint

• Should be 1-8 story points
• Completable in 1-5 days
• Has clear definition of done
• Assigned to one person

Example: "As a user, I can reset my password via email"

Task

When to use: Technical work not directly user-facing

• Infrastructure, refactoring, documentation
• 1-5 story points
• Supporting work for stories

Example: "Set up CI/CD pipeline", "Write API documentation"

Bug

When to use: Something broken that needs fixing

• Use priority field: Blocker, Critical, Major, Minor
• Link to affected epic/story
• Track separately from feature velocity

Portavio uses bugs for:

• Risk detection (too many bugs = quality issues)
• Team load calculation
• Sprint predictability

Sub-task

When to use: Breaking down a story into smaller pieces

• Technical steps to complete parent story
• Don't estimate sub-tasks separately (story points on parent only)
• Use for task distribution among team members

🏷️ Labels & Tags - What Portavio Looks For

Portavio uses specific labels to enhance risk detection and insights. Here are the recommended labels:

Risk Labels

Add one of these labels to any Jira issue to flag it as a manual risk:

You can also trigger a high-severity risk by setting the issue Priority to Highest or Critical — no label needed.

Blocker Labels

Any of these will create an entry in the Blockers page:

Category Labels

Priority Labels (If Not Using Priority Field)

• urgent - Must do now
• high-priority - Important, do soon
• nice-to-have - Can be deferred

⚙️ Custom Fields Portavio Recognizes

Story Points

Field Name: "Story Points" or "Estimate"

• Used for velocity calculation
• Epic progress tracking
• Sprint capacity planning

Best Practice: Use Fibonacci sequence (1, 2, 3, 5, 8, 13, 21)

Epic Link

Field Name: "Epic Link"

• Links stories to epics
• Required for epic progress tracking
• Portavio automatically rolls up story points to epic

Sprint

Field Name: "Sprint"

• Assigns issues to sprints
• Used for velocity calculation
• Sprint burndown tracking

Team (Optional)

Field Name: "Team" (if you have a team custom field)

• Associates issues with specific teams
• Enables team-based velocity tracking
• Team load balancing

🏃 Sprint Setup for Best Results

Sprint Naming Convention

Use consistent naming for better tracking:

• Good: "Sprint 24", "Team Alpha Sprint 15", "2024-W12"
• Bad: "The Sprint", "New Sprint", "Sprint"

Sprint Duration

Recommended: 2 weeks (10 business days)

• Long enough to complete meaningful work
• Short enough for quick feedback
• Easier velocity comparison

Sprint Planning Checklist

1. Set sprint start and end dates
2. Define sprint goal
3. Assign story points to all stories
4. Link stories to epics
5. Assign stories to team members
6. Mark dependencies with labels

Sprint Commitment

Portavio tracks committed vs. completed points per sprint:

• Committed: Total story points in the sprint at start
• Completed: Story points of "Done" issues at sprint end
• Velocity: Average completed points across the last 6 sprints

📊 Dashboard Overview

Overview Page

Your portfolio at a glance:

• Total Projects: Count and breakdown by health
• Active Epics: In progress vs. completed
• Team Velocity: Average across all teams
• Risks: Current blockers and issues

Projects Page

All projects with health indicators:

• Green On track, no blockers
• Yellow Minor issues, needs attention
• Red Critical blockers or delays

Teams Page

Team performance metrics:

• Velocity: Average story points per sprint
• Capacity: Max story points team can handle
• Current Load: % of capacity used
• Predictability: Delivery consistency score

Epics Page

Epic progress and status:

• Progress bar (completed / total story points)
• Start and due dates
• Assigned teams
• Blocking issues

🚨 Risk Detection

Portavio detects risks in two ways: manual labels you apply in Jira, and automatic detection based on data patterns that runs on every sync. Risks are grouped into five types, each with its own tab on the Risks page.

You can filter risks by Project and Team using the dropdowns at the top of the Risks page.

🏷️ Labeled Risks (Manual)

Issues you explicitly label in Jira with risk, risk-high, risk-medium, risk-low, or RISK, or with priority set to Highest / Critical.

📈 Epic Risks (Auto-detected)

Portavio flags an epic as at-risk when any of the following are true:

• The epic is past its due date (overdue)
• Less than 50% complete with 7 or fewer days remaining until due date
• Has story points estimated but 0% progress

🏃 Sprint Risks (Auto-detected)

Active sprints are flagged when:

• The sprint end date has passed and completion is below 100%
• Less than 50% of issues are done with 3 or fewer days remaining

👥 Team Overload (Auto-detected)

Raised when a team's current workload exceeds their average velocity:

• High severity — load exceeds 100% of velocity
• Medium severity — load exceeds 90% of velocity

🎫 Issue Risks (Auto-detected)

Individual issues are flagged as at-risk for any of these patterns:

• Unassigned high-priority — a Highest or Critical priority issue with no assignee
• Stalled — an issue that has been In Progress for more than 7 days with no updates
• Large story in a tight sprint — an 8+ point story in an active sprint with fewer than 3 days left, not yet started
• Unassigned critical bug — a Blocker or Critical priority bug with no assignee

📈 Velocity Tracking

How Velocity is Calculated

Velocity = Σ(Completed Story Points) / Number of Sprints

Portavio uses the last 6 sprints by default (configurable).

Understanding Your Velocity

• 20-30 points/sprint: Small team (2-3 people)
• 30-50 points/sprint: Medium team (4-6 people)
• 50-80 points/sprint: Large team (7-10 people)

Velocity Trends

Portavio shows velocity over time:

• Upward trend: Team improving, getting faster
• Stable: Consistent delivery (good!)
• Downward trend: Investigate: too much WIP? Blockers? Team changes?

Predictability Score

Predictability measures how consistent a team's velocity is across recent sprints — not just whether they finish what they start.

Predictability = (Consistent Sprints / Total Sprints) × 100%

A sprint is "consistent" if its velocity is within ±20% of the team's average
Portavio looks at the last 6 completed sprints

What scores mean:

• 80–100% ● Highly predictable — delivery is reliable and plannable
• 60–79% ● Moderately predictable — some variance, review sprint planning
• 0–59% ● Unpredictable — velocity swings significantly sprint to sprint

Predictability requires at least 2 completed sprints. Scores improve naturally as more sprint history accumulates.

⚖️ Team Load Management

How Load is Calculated

Load = (Current Sprint Points / Team Velocity) × 100%

Load Indicators

• 0-70%: Under capacity - team can take more work
• 70-90%: Optimal - good utilization
• 90-110%: Near capacity - watch closely
• >110%: Overloaded - at risk of burnout/missed commitments

Balancing Team Load

When teams are overloaded:

1. Move non-critical stories to next sprint
2. Defer "nice-to-have" work
3. Check for hidden work (bugs, support)
4. Distribute work to underutilized teams

🗂️ Managing Multiple Projects

Project Organization

Portavio supports portfolios with dozens of projects. Best practices:

Naming Convention

• Use prefixes: MOBILE-, API-, WEB-
• Keep names under 30 characters
• Avoid generic names like "Project 1"

Project Health

Set health manually or let Portavio auto-detect:

• Green: All epics on track, no blockers
• Yellow: 1-2 minor issues
• Red: Critical blockers or delayed epics

Cross-Project Dependencies

Use Jira issue links to connect dependencies across projects:

• "Blocks" / "Is blocked by"
• "Relates to"
• "Depends on"

Portavio visualizes cross-project dependencies in the Epics view.

🔗 Managing Dependencies

Types of Dependencies

1. Epic Dependencies

One epic blocks another:

• Link epics in Jira: "Epic A blocks Epic B"
• Portavio shows dependency chain
• Alerts if blocking epic is delayed

2. Team Dependencies

One team waiting on another:

• Label stories with dependency
• Mention blocking team in comments
• Track in Portavio's dependency view

3. External Dependencies

Waiting on vendors, partners, or other systems:

• Create "External Dependency" issue type (or use Task)
• Link to dependent stories
• Label with external

Dependency Best Practices

1. Make dependencies explicit - always create Jira links
2. Identify early - flag dependencies during sprint planning
3. Track in standup - "What are you blocked by?"
4. Escalate delays - if blocking work is delayed, escalate immediately

🔄 Custom Workflows

Standard Workflow

Portavio works best with this flow:

To Do → In Progress → Code Review → Testing → Done

Custom Status Mapping

If you use different status names, Portavio maps them automatically:

What "Done" Means

For velocity calculation, Portavio counts issues as complete when:

• Status is in "Done" category
• Resolution is set (if your workflow uses resolutions)
• Issue is in closed sprint

❓ Frequently Asked Questions

How often should I sync?

Default is every 6 hours. Sync manually after sprint planning, major epic updates, or before important meetings.

Why is my velocity zero?

Check:

• Story points field is populated
• Issues are in closed sprints
• Issues have "Done" status
• At least one sprint is complete

Can I use Portavio with Jira Server?

Not yet. Portavio currently supports Jira Cloud only. Jira Server/Data Center support is on our roadmap.

What if I don't use story points?

Some features (velocity, predictability) require story points. You can still use Portavio for project tracking and risk detection.

How do I invite team members?

Team member invitations are coming soon. The feature is being built — stay tuned for an update.

Can I export data?

Data export is on the roadmap and will be available in a future release.

Is my Jira data secure?

Yes. We use bank-level encryption, never share data with third parties, and are SOC 2 compliant.

Last updated: May 14, 2026 • Back to Dashboard