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 & Blocker Labels

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:

• Committed: Total story points at sprint start
• Completed: Story points of "Done" issues at sprint end
• Predictability: Completed / Committed ratio

📊 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 automatically detects these risks:

Blocker Detection

• Issues with blocked or blocker labels
• Issues in "Blocked" status
• Issues with links to blocking issues

Epic at Risk

Portavio flags epics as at-risk when:

• Less than 30% complete with less than 30% time remaining
• No progress in 2+ weeks
• Multiple blocking issues
• Assigned team is overloaded (>100% capacity)

Team Overload

• Current sprint commitment > team's average velocity
• Team assigned to too many simultaneous epics
• Sprint contains too many critical bugs

Velocity Drop

• Current sprint velocity < 70% of team average
• Downward trend over 3+ sprints
• Predictability score < 60%

📈 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 = (Completed Points / Committed Points) × 100%

What scores mean:

• 90-100%: Excellent - team delivers consistently
• 80-89%: Good - minor variance is normal
• 70-79%: Fair - review sprint planning process
• <70%: Poor - team overcommitting or facing blockers

⚖️ 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?

Go to Settings → Team Members → Invite. They'll receive an email invitation.

Can I export data?

Yes! Go to Settings → Export Data to download CSV or JSON of your portfolio data.

Is my Jira data secure?

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

Last updated: March 8, 2026 • Back to Dashboard