> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/ticketing-and-bugtracking.md).

# Ticketing and Bugtracking

Learn how Pharos integrates bidirectionally with Jira and Azure DevOps to bridge  the gap between error detection and development workflow.

The connection with bugtrackers is essential for the Action and Collaboration step in resolving issues. Pharos integrates with Jira and Azure DevOps to automatically create tickets, sync status, and maintain context throughout the resolution lifecycle.

## Why Bugtracker Integration Matters

In most organizations, development work happens in Jira (or Azure DevOps). But errors happen in Salesforce and get detected by Pharos. Without integration, there's a manual gap.

{% hint style="warning" %}
**The Cost of Manual Processes**

Without integration, teams waste 15-30 minutes per issue copying data between systems, lose critical context in translation, and struggle to keep tickets synchronized as errors evolve.
{% endhint %}

**The Broken Workflow:**

1. Error detected in Pharos → Manual copy-paste to Jira
2. Context lost in translation → Developers ask for more info
3. Issue evolves in Pharos → Jira ticket becomes stale
4. Fix deployed → Manual update needed in both systems
5. Error recurs → New manual ticket creation needed

**The Business Impact:**

* **Time waste:** 15-30 minutes per ticket for manual data entry
* **Context loss:** Stack traces, impact metrics, and related logs don't make it to Jira
* **Stale data:** Developers work with outdated information as Issues evolve
* **Tracking failures:** No automated connection between errors and fixes

Pharos integration solves this by:

* **Automating ticket creation** with full context
* **Maintaining live links** between Issues and tickets
* **Synchronizing status** bidirectionally
* **Preserving context** as Issues evolve

## Integration Architecture

Pharos connects to Jira/Azure DevOps through REST APIs with bidirectional synchronization.

```mermaid
graph LR
    subgraph Pharos["PHAROS"]
        P[Issue Record<br/>Fingerprint • Status: Open → Actioned<br/>Priority: High • Related Logs: 3,247<br/>Jira Ticket: PROJ-1234]
    end
    subgraph Sync["Bidirectional Sync via API"]
        S[API]
    end
    subgraph Jira["JIRA"]
        J[Ticket: PROJ-1234<br/>Summary • Description • Status • Priority<br/>Labels • Epic • Comments]
    end
    Pharos <--> Sync <--> Jira
```

### What Gets Synchronized

Synchronization runs in both directions, but on different schedules:

| Direction               | What Syncs                                                                       | When                               |
| ----------------------- | -------------------------------------------------------------------------------- | ---------------------------------- |
| **Pharos → bugtracker** | Ticket creation, issue details, priority, relationship links, threshold comments | As the triggering change happens   |
| **Bugtracker → Pharos** | Completed status, priority, relationship and duplicate links                     | On a polling cycle, roughly hourly |

The inbound direction is the slower of the two because it polls rather than being pushed — Salesforce batch scheduling puts a practical floor of about an hour on how often it can run. Plan around that when you expect a status change in Jira to be reflected in Pharos.

## Ticket Creation Methods

Pharos provides three ways to create bugtracker tickets from Issues.

### Method 1: Manual Button Click

**Use Case:** Triage-then-ticket workflow where admins review Issues before escalating to development.

**Process:**

1. Admin reviews Issue in Pharos
2. Assigns priority, adds triage notes
3. Clicks "Create Ticket" button on Issue record
4. Selects Jira project and ticket template
5. Ticket created instantly with pre-populated context

**Advantages:**

* Human-in-the-loop quality control
* Prevents ticket spam for non-actionable Issues
* Allows triage context to be added before developers see it

### Method 2: Status-Based Automation

**Use Case:** Tickets created automatically when Issue reaches a specific status.

**Configuration:**

```
WHEN: Issue Status changed to "Actioned"

THEN:
  - Create Jira ticket automatically
  - Use template: "Production Bug"  
  - Assign to project: "SALESFORCE"
  - Set priority based on Issue priority
```

**Advantages:**

* No extra button click needed
* Consistent workflow: Status change = Ticket created
* Batch operations possible (bulk status update)

### Method 3: Ticketing Rules (Fully Automated)

**Use Case:** Tickets created immediately for Issues meeting specific criteria.

**Configuration:**

```
Rule: "Auto-Create for Critical Production"

WHEN: New Issue Created

WHERE:
  AND Org Type = "Production"
  AND Priority = "Highest"
  AND Category IN ["Apex", "Flow"]
  AND Functional Area = "Order Processing"

THEN:
  - Create Jira ticket automatically
  - Project: SALESFORCE
  - Issue Type: Bug
  - Priority: High
  - Epic: "Production Stability"
  - Component: "Order Management"
  - Assign to: "DevOps Team"
```

**Advantages:**

* Zero manual intervention for critical Issues
* Tickets created within seconds of error detection
* Developers notified immediately via Jira

{% hint style="warning" %}
**Best Practice:** Start with manual or status-based creation. Graduate to fully automated rules only after establishing clear criteria through historical data.

Automated ticket creation without guardrails can spam your Jira backlog with low-value tickets.
{% endhint %}

## Bidirectional Synchronization

Once a ticket is created, Pharos keeps the two systems aligned. Synchronization is **selective rather than total** — it covers completion, priority, and relationships, not every field. Each behavior below is an individual toggle, so you decide how much coupling you want; see [Jira Defaults](https://docs.pharos.ai/configuration-guide/integrations/jira/defaults.md) or [Azure DevOps Defaults](https://docs.pharos.ai/configuration-guide/integrations/azure/defaults.md) to turn them on.

**From the bugtracker into Pharos**, on a polling cycle that runs about once an hour — a consequence of Salesforce batch scheduling rather than a Pharos setting:

| Change in Jira / Azure DevOps           | Effect on the Pharos issue                       |
| --------------------------------------- | ------------------------------------------------ |
| Ticket marked Done, Closed, or Resolved | Issue status becomes **Completed**               |
| Ticket priority changed                 | Issue priority updated to match                  |
| Tickets linked as related or duplicate  | The corresponding issues are linked the same way |

**From Pharos into the bugtracker:**

| Change in Pharos                       | Effect on the ticket                                        |
| -------------------------------------- | ----------------------------------------------------------- |
| Issue priority changed                 | Ticket priority updated to match                            |
| Issue reoccurs after completion        | A **new** ticket is created and linked to the previous one  |
| Issues linked as related or duplicate  | The corresponding tickets are linked the same way           |
| Occurrence or impact threshold crossed | A comment is added, when you've configured a comment action |

{% hint style="info" %}
**Regression returns an issue to New.** If a completed issue starts occurring again, its status goes back to **New** rather than staying Completed — which is what makes the reoccurrence path (new linked ticket rather than reopening a closed one) work cleanly against finished sprints.
{% endhint %}

Priority sync deserves one caution: enabling both directions makes the bugtracker authoritative. Once a priority has synced inbound, Pharos keeps taking priority from the ticket, overriding changes made directly on the issue.

## Ticket Content & Formatting

Jira tickets created by Pharos include rich context to enable immediate action.

### Ticket Summary

**Format:**

```
[{Category}] {Error Type} in {Functional Area}
```

**Examples:**

* `[Apex] DML Exception in Order Processing`
* `[Flow] Validation Error in Case Management`
* `[Apex] Callout Timeout in Payment API`

### Ticket Description

**Template:**

```markdown
## Error Summary
{ErrorMessage}

## Impact
- **Users Affected:** {UserCount}
- **Occurrences:** {OccurrenceCount}  
- **First Seen:** {FirstOccurrenceDate}
- **Last Seen:** {LastOccurrenceDate}
- **Frequency:** {AveragePerDay} per day

## Technical Details
**Category:** {Category}
**Type:** {ExceptionType}
**Functional Area:** {FunctionalArea}

**Stack Trace:**
{StackTracePreview}

## Related Data
**Objects Involved:** {ObjectTypes}
**Record Count:** {RecordCount}

## Debugging Resources
- [View Full Issue in Pharos]({PharosIssueURL})
- [View Related Logs]({PharosLogsURL})
- [Environment Snapshot]({AuditTrailURL})

## Recent Environment Changes
{RecentAuditTrailEntries}
```

## In This Section

This section covers the following topics:

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>🎯 Issue-level Ticketing</strong></td><td>Creating tickets from issues with manual, create-based, and update-based triggering.</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/ticketing-and-bugtracking/issue-level-ticketing.md">Issue-level Ticketing</a></td></tr><tr><td><strong>📝 Log-level Ticketing</strong></td><td>Creating tickets from individual logs (seldom needed).</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/ticketing-and-bugtracking/log-level-ticketing.md">Log-level Ticketing</a></td></tr><tr><td><strong>📊 Order of Execution</strong></td><td>Understanding how ticketing rules are executed and preventing duplicate tickets.</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/ticketing-and-bugtracking/order-of-execution.md">Order of Execution</a></td></tr></tbody></table>

## Best Practices

### Start Manual, Automate Gradually

Introduce automation in phases rather than switching everything on at once:

**Phase 1 (Weeks 1-2):**

* Manual ticket creation only
* Learn which Issues warrant tickets
* Refine triage criteria

**Phase 2 (Weeks 3-4):**

* Add status-based automation (Actioned → Ticket)
* Still requires human triage decision
* Observe pattern of tickets created

**Phase 3 (Month 2+):**

* Add targeted automated rules for proven scenarios
* Monitor false positive rate
* Refine criteria based on data

### Measure Effectiveness

Track these metrics to confirm your ticketing rules add value rather than noise:

| Metric                     | Target                              | Action If Not Meeting                      |
| -------------------------- | ----------------------------------- | ------------------------------------------ |
| **Ticket Action Rate**     | >80% of tickets lead to code change | Tighten creation criteria                  |
| **Time to First Response** | <4 hours                            | Improve notification routing               |
| **False Ticket Rate**      | <10% closed as "Not a Bug"          | Improve fingerprinting or add triage step  |
| **Reopened Ticket Rate**   | <15%                                | Review fix quality, add regression testing |

{% hint style="success" %}
**Next Steps**

1. Set up Jira/Azure DevOps connection in Pharos
2. Create your first ticket template
3. Manually create tickets for 1-2 weeks to establish baseline
4. Add status-based automation for "Actioned" Issues
5. After 1 month, consider targeted automated rules for critical scenarios

→ Explore [Issue-level Ticketing](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/ticketing-and-bugtracking/issue-level-ticketing.md) to understand the different ticket creation methods in detail.
{% endhint %}
