# TicketHub - User Guide

## What is TicketHub?

TicketHub is a modern, open-source ticket tracking system designed for teams of all sizes. Track issues, manage projects, and collaborate with your team.

## Getting Started

### Access

Open TicketHub in your browser: **https://tickethub.startdata.com.br**

### Dashboard

The dashboard gives you a quick overview:
- **Total Tickets**: All tickets across projects
- **Open**: Tickets needing attention
- **In Progress**: Tickets being worked on
- **Resolved**: Completed tickets
- **Critical**: High-priority items

## Features

### 📁 Projects

Projects organize your tickets. Each project has:
- **Name**: Human-readable name
- **Key**: Short code (e.g., "PROJ") used in ticket IDs
- **Description**: What the project is about
- **Webhook URL**: Optional integration endpoint

**Creating a Project:**
1. Go to **Projects** page
2. Click **New Project**
3. Enter name and key
4. Optionally add webhook URL
5. Click **Create**

### 🎫 Tickets

Tickets are individual issues, tasks, or requests.

**Creating a Ticket:**
1. Click **New Ticket** (top right or dashboard)
2. Select a project
3. Enter title and description
4. Set priority
5. Click **Create**

**Ticket Fields:**
- **Key**: Auto-generated (e.g., PROJ-1)
- **Title**: Brief summary
- **Description**: Full details
- **Status**: Open → In Progress → Resolved → Closed
- **Priority**: Low, Medium, High, Critical
- **Assignee**: Who's working on it
- **Reporter**: Who created it

### 📋 Kanban Board

Visual board for tracking ticket progress:
- **Drag & Drop**: Move tickets between columns
- **Filter**: Show only one project
- **Priority Colors**: Visual indicators

### 👥 Team

Manage who has access:
- **Admin**: Full access, can manage settings
- **Member**: Create and edit tickets
- **Viewer**: Read-only access

### 📈 Reports

Analytics and insights:
- Tickets created over time
- Status distribution
- Priority breakdown
- Team performance

### 🔌 Integrations

Connect TicketHub with other tools:
- **JIRA AI Fixer**: Automatic issue analysis
- **Slack**: Notifications
- **GitHub/GitLab**: Link to PRs

### ⚡ Automation

Create rules to automate tasks:
- Auto-assign critical tickets
- Close stale tickets
- Send notifications

## Working with Tickets

### Changing Status

1. Open the ticket
2. Use the **Status** dropdown
3. Select new status:
   - **Open**: New ticket, not started
   - **In Progress**: Being worked on
   - **Resolved**: Fix applied, awaiting verification
   - **Closed**: Complete, no further action

Or use the **Board** and drag tickets between columns.

### Adding Comments

1. Open ticket detail page
2. Scroll to **Activity** section
3. Type your comment
4. Click **Add Comment**

### Assigning Tickets

1. Open ticket
2. Click **+ Assign** in sidebar
3. Select team member
4. Assignment is saved automatically

### Filtering Tickets

On the **Tickets** page:
- **Project**: Show only one project
- **Status**: Filter by status
- **Priority**: Filter by priority
- **Clear Filters**: Reset all

## Webhooks

TicketHub can notify external systems when events occur.

### Setting Up

1. Go to **Projects**
2. Edit your project
3. Add **Webhook URL**
4. Save

### Events

| Event | Trigger |
|-------|---------|
| `ticket.created` | New ticket created |
| `ticket.updated` | Ticket modified |
| `ticket.resolved` | Status changed to resolved |
| `comment.added` | New comment added |

### Payload Format

```json
{
  "event": "ticket.created",
  "timestamp": "2026-02-18T18:00:00Z",
  "data": {
    "id": 1,
    "key": "PROJ-1",
    "title": "Example ticket",
    "description": "...",
    "status": "open",
    "priority": "high",
    "project_id": 1
  }
}
```

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `C` | Create new ticket |
| `/` | Focus search |
| `G D` | Go to Dashboard |
| `G T` | Go to Tickets |
| `G B` | Go to Board |
| `G P` | Go to Projects |

## Settings

### General
- Workspace name
- Timezone
- Language
- Date format

### Notifications
- Email alerts
- Slack integration
- Notification levels

### Security
- SSO configuration
- 2FA settings
- Session timeout

### API
- Generate API keys
- View documentation

## Tips & Best Practices

### Writing Good Tickets

**Good ticket:**
```
Title: Login fails with special characters in password

Steps to reproduce:
1. Go to login page
2. Enter email: test@example.com
3. Enter password containing: @#$%
4. Click Login
5. See error: "Invalid credentials"

Expected: Should log in successfully
Actual: Shows error message

Browser: Chrome 120
OS: Windows 11
```

**Poor ticket:**
```
Title: login broken
Description: doesn't work
```

### Using Priorities

| Priority | Use When |
|----------|----------|
| **Critical** | System down, security issue, data loss |
| **High** | Major feature broken, blocking work |
| **Medium** | Normal bugs and features |
| **Low** | Nice to have, cosmetic issues |

### Staying Organized

1. Use consistent project keys
2. Write clear titles
3. Add relevant labels
4. Keep descriptions updated
5. Close resolved tickets

## Getting Help

- **Documentation**: This guide
- **Support**: support@startdata.com.br
- **GitHub**: Report bugs or request features

---

*TicketHub - Simple, Powerful Issue Tracking*
*Open Source by StartData*