Fluent support

1. YDB FluentSupport Tools — General Documentation

Current working version: v18.5 — Native Reopen Self-Assign
Plugin folder: `wp-content/plugins/ydb-fluentsupport-tools/`
Status: Working / accepted after live testing
Important instruction: Keep the Diagnostics tab until explicitly removed.

---

1. 1. Purpose

YDB FluentSupport Tools extends FluentSupport without modifying FluentSupport core or FluentSupport Pro files.

The plugin adds operational controls for a multi-agent support workflow where agents must be able to work safely on tickets without accidentally taking over or closing tickets handled by other agents.

Main goals:

1. Prevent assignment conflicts between agents.
2. Allow normal agents to manage tickets they own or tickets that are unassigned.
3. Prevent normal agents from changing tickets owned by other agents.
4. Allow closed tickets to be reopened and assigned to the reopening agent.
5. Clear ticket assignment when a ticket is closed.
6. Keep a diagnostic/recovery area for visibility and troubleshooting.
7. Preserve the existing forwarding and concurrency/collision functionality.

---

1. 2. Current confirmed successful behavior

The following behaviors were tested and confirmed working:

Behavior	Result
---	---:
Agent cannot assign to self a ticket assigned to another agent	YES
Agent cannot assign to another agent a ticket assigned to another agent	YES
Agent cannot close a ticket assigned to another agent	YES
Agent can reopen a closed ticket and it is automatically assigned to self	YES
Closing a ticket unassigns it	YES
Agent can assign an unassigned ticket to anyone	YES

---

1. 3. Assignment and close/reopen matrix

1. 3.1 Normal agent

A normal FluentSupport agent can manage assignment only when the ticket is either:

1. Unassigned.
2. Assigned to himself/herself.

Action	Allowed?
---	---:
Assign unassigned ticket to self	YES
Assign unassigned ticket to another agent	YES
Assign own ticket to another agent	YES
Release own ticket / unassign own ticket	YES
Assign ticket owned by another agent to self	NO
Assign ticket owned by another agent to another agent	NO
Release ticket owned by another agent	NO
Close own ticket	YES
Close ticket owned by another agent	NO
Reopen closed ticket	YES, and it self-assigns

1. 3.2 Agent with FluentSupport “Assign Agents” permission

An agent with the FluentSupport Assign Agents permission is treated as a senior assignment agent.

Action	Allowed?
---	---:
Assign/reassign any ticket	YES
Release/unassign any ticket	YES
Close any ticket	YES
Reopen closed ticket	YES

1. 3.3 WordPress administrator

A WordPress administrator is treated as fully privileged.

Action	Allowed?
---	---:
Assign/reassign any ticket	YES
Release/unassign any ticket	YES
Close any ticket	YES
Reopen closed ticket	YES
Access diagnostics	YES

---

1. 4. Native FluentSupport interface behavior

The current version works with the native FluentSupport interface and guards the actions that could bypass the intended workflow.

1. 4.1 Native assignment guard

When FluentSupport tries to update the assigned agent through its native property/action endpoint, YDB FluentSupport Tools checks whether the current user is allowed to change the assignment.

Rules:

1. If the ticket is unassigned, any agent can assign it to anyone.
2. If the ticket is assigned to the current agent, the agent can reassign or release it.
3. If the ticket is assigned to another agent, a normal agent cannot reassign or release it.
4. Agents with Assign Agents permission can manage any ticket.
5. WordPress administrators can manage any ticket.

1. 4.2 Native close guard

When an agent closes a ticket using the native FluentSupport interface:

1. A normal agent can close only a ticket assigned to himself/herself.
2. A normal agent cannot close a ticket assigned to another agent.
3. Senior agents / Assign Agents users / WordPress administrators can close any ticket.
4. After a ticket is closed, its assignment is cleared.

1. 4.3 Native reopen self-assign

When a closed ticket is reopened:

1. The ticket status is reopened/active.
2. The ticket is automatically assigned to the FluentSupport agent who reopened it.
3. This prevents the old assignment from remaining attached after reopen.

---

1. 5. Closed ticket workflow

The accepted workflow is:

```text
Close ticket
→ ticket becomes closed
→ assignment is cleared
→ ticket is no longer owned by the previous agent
```

Then:

```text
Reopen ticket
→ ticket becomes active/open again
→ ticket is assigned to the agent who reopened it
```

This solved the earlier problem where reopened tickets kept the previous assignment.

---

1. 6. YDB Archive and Diagnostics

The plugin includes a YDB Archive / recovery area.

1. 6.1 Why it exists

Testing showed that FluentSupport’s normal All and Closed views may not reliably show all closed tickets for all users, and at one point even admin visibility was not enough for recovery.

Therefore, the plugin includes a YDB-controlled archive/diagnostic browser that reads ticket data directly and helps recover visibility.

1. 6.2 Current instruction

Keep Diagnostics active until explicitly removed.

1. 6.3 Diagnostic purpose

Diagnostics helps inspect:

1. Raw ticket status values.
2. Ticket assignment values.
3. Recent ticket rows.
4. Status counts.
5. Agent assignment counts.
6. Fields/columns used by FluentSupport.
7. Whether closed/reopened tickets are stored correctly.

---

1. 7. Forward ticket feature

The plugin includes a Forward ticket function.

1. 7.1 Behavior

The Forward ticket button allows an agent to forward a ticket transcript by email.

Confirmed behavior from previous accepted versions:

1. To recipient works.
2. CC works.
3. Forwarded email includes ticket information and conversation content.
4. Modal closes after successful send.
5. Sending uses `wp_mail()`, so FluentSMTP handles delivery.

1. 7.2 Delivery path

```text
YDB FluentSupport Tools
→ wp_mail()
→ FluentSMTP
→ configured SMTP / Microsoft / other provider
```

1. 7.3 Current limitation

Attachments are not included yet.

---

1. 8. Conflict / concurrency badge

The plugin includes an almost real-time collision/presence badge.

1. 8.1 Purpose

It warns when more than one agent is viewing the same ticket.

1. 8.2 Current accepted visual behavior

```text
Position: bottom-left
Color: red
Animation: slide in from the left
Meaning: another agent is watching the same ticket
```

1. 8.3 Important note

Collision handling is sensitive. Earlier experiments broke the timing and reliability, so future changes to this logic should be minimal and tested with two browsers/two agents.

---

1. 9. Agent signature marker

The plugin supports the custom marker:

```text
[[YDB_AGENT_SIGNATURE]]
```

This is used because the normal FluentSupport smartcode for agent signatures did not work reliably for agent-started ticket emails in this installation.

The marker is replaced at the `wp_mail` stage with the logged-in agent’s FluentSupport signature when available.

---

1. 10. Frontend support portal improvements

Earlier accepted versions added support for the frontend support-agent portal.

Current preserved behavior includes:

1. Loading on `/support-agent-portal/`.
2. Hash-route protection for FluentSupport routes such as `#/tickets/{id}/view`.
3. Layout improvements for the support portal/list area.
4. Portal/list width centered at approximately 80%.

---

1. 11. Native FluentSupport controls

The plugin previously attempted to hide conflicting native FluentSupport controls.

Current practical position:

1. Native controls can remain visible if guarded properly by backend logic.
2. Backend guards are more important than hiding.
3. Hiding is only a UI convenience, not security.
4. The current accepted behavior depends on server-side enforcement of assignment/close/reopen rules.

---

1. 12. File structure overview

The plugin lives here:

```text
wp-content/plugins/ydb-fluentsupport-tools/
```

Important file areas:

```text
ydb-fluentsupport-tools.php
includes/
assets/js/
README-*.md
```

Known feature modules include:

```text
includes/concurrency.php
assets/js/concurrency.js

includes/ticket-forward.php
assets/js/ticket-forward.js

includes/ticket-assignment.php
assets/js/ticket-assignment.js

includes/ticket-close.php
assets/js/ticket-close.js

includes/ticket-archive.php
assets/js/ticket-archive.js

includes/native-controls-hide.php
assets/js/native-controls-hide.js

includes/agent-signature-smartcode.php
```

Exact file names may vary by version, but these are the functional areas currently maintained.

---

1. 13. Version history summary

1. v13

Stable concurrency/presence baseline.

Included:

1. Custom red concurrency badge.
2. Native People Watching badge hidden.
3. Portal width adjusted to 80%.
4. Single-active-ticket-per-user cleanup.
5. Support portal hash-route guard.

1. v14

Added agent signature marker:

```text
[[YDB_AGENT_SIGNATURE]]
```

1. v16.3

Added forward ticket by email.

1. v16.6

Accepted stable visual version:

1. Forward button blue, bottom-right.
2. Conflict badge red, bottom-left, slide-in animation.

1. v16.9

Implemented ticket assignment matrix.

Accepted concepts:

1. Any agent can manage unassigned tickets.
2. Any agent can manage own assigned tickets.
3. Normal agents cannot manage other agents’ tickets.
4. Assign Agents/admin can manage all.

1. v17.x

Explored close/reopen/archive behavior.

Important lesson:

1. Direct close/reopen logic was risky.
2. Closed tickets could become hard to find in FluentSupport’s normal filters.
3. Diagnostics and read-only recovery browser were added.
4. Reopen behavior was refined repeatedly.

1. v18.x

Integrated protection around native FluentSupport actions.

Key accepted results by v18.5:

1. Native assignment is guarded.
2. Normal agents cannot reassign tickets owned by other agents.
3. Normal agents cannot close tickets owned by other agents.
4. Closing a ticket unassigns it.
5. Reopening a ticket assigns it to the reopening agent.
6. Diagnostics remain available.

---

1. 14. Current accepted version

The current accepted working version is:

```text
v18.5 — Native Reopen Self-Assign
```

Accepted achievements:

```text
NO assign to self tickets assigned to others
NO assign to others tickets assigned to others
NO close tickets assigned to others
YES open closed tickets and automatically assign to self
YES when close ticket unassign it
YES assign to anyone unassigned ticket
```

---

1. 15. Testing checklist

Use at least two different agent accounts and preferably two different browsers.

1. 15.1 Assignment tests

1. Agent A owns a ticket.
2. Agent B tries to assign it to himself.
- Expected: blocked.
3. Agent B tries to assign it to another agent.
- Expected: blocked.
4. Unassigned ticket is opened by Agent B.
5. Agent B assigns it to Agent C.
- Expected: allowed.
6. Agent B owns a ticket.
7. Agent B assigns it to Agent C.
- Expected: allowed.

1. 15.2 Close tests

1. Agent A owns a ticket.
2. Agent B tries to close it.
- Expected: blocked.
3. Agent A closes it.
- Expected: allowed.
4. After close, ticket assignment should be cleared.
- Expected: unassigned.

1. 15.3 Reopen tests

1. Closed ticket is reopened by Agent B.
2. Ticket becomes active/open.
3. Ticket is assigned to Agent B.
- Expected: self-assigned to reopening agent.

1. 15.4 Admin tests

1. WordPress admin attempts to assign/reassign any ticket.
- Expected: allowed.
2. WordPress admin attempts to close any ticket.
- Expected: allowed.
3. Agent with FluentSupport Assign Agents permission attempts to manage any ticket.
- Expected: allowed.

1. 15.5 Regression tests

1. Forward ticket still works.
2. CC still works.
3. Forward modal closes after send.
4. Collision badge still appears when two agents view the same ticket.
5. Diagnostics tab is still visible.

---

1. 16. Operational rules

1. Do not modify FluentSupport core.
2. Do not modify FluentSupport Pro.
3. Do not modify FluentSMTP.
4. Keep all custom behavior inside `ydb-fluentsupport-tools`.
5. Keep diagnostics until explicitly removed.
6. Test with two agents before accepting changes.
7. Prefer small versions and one correction at a time.

---

1. 17. Current limitations and future ideas

1. Current limitations

1. Forwarding does not include attachments.
2. Diagnostics are still visible intentionally.
3. Archive/recovery is YDB-specific, not a native FluentSupport archive model.
4. Native UI hiding can be fragile if FluentSupport changes its markup.

1. Future possible improvements

1. Forward ticket attachments.
2. Log forwarded tickets as internal notes.
3. Cleaner YDB permissions/admin panel.
4. Dedicated YDB closed/archive page with better filtering.
5. Remove diagnostics once the workflow is stable for a longer period.
6. More polished UI integration once backend rules are fully proven.

---

1. 18. Final current workflow

The current accepted ticket lifecycle is:

```text
Unassigned ticket
→ any agent can assign it to any agent
```

```text
Ticket assigned to Agent A
→ Agent A can reassign it, release it, or close it
→ Agent B cannot reassign it or close it
```

```text
Ticket closed by allowed agent
→ ticket becomes closed
→ ticket becomes unassigned
```

```text
Closed ticket reopened by Agent B
→ ticket becomes active/open
→ ticket is assigned to Agent B
```

This is the current working operational model.