Cloudifi Retainers — Admin Guide (v1.5.5) 10-4-2025

For Admins (Owner/Staff Guide)

A) First-time setup

Install & Activate the plugin.
Go to Retainers → Settings and set:
- Default hourly rate
- Default low-balance threshold
- Notification emails (comma-separated)
- Whether to email clients when they’re low
- Notification cooldown (hours between email alerts)
Create your portal page and add the shortcode:
- [[retainer_portal]]
- Protect the page so only clients can see it (e.g., SureMembers).

Roles & Access

A Retainer Manager role is added with the manage_retainers capability.

Administrators automatically get manage_retainers.

Only users with manage_retainers can access the Retainers admin menu.

B) Creating clients

You have two options:

Option 1: Sync existing WordPress users

Go to Retainers → Sync Users.
Check the users you want to convert to clients.
Set a default rate and threshold for the new clients.
Click Create Client Records.

Option 2: Add a client manually

Go to Retainers → Add Client.
(Optional) Map the client to a WP user now or later.
Fill in Name, Email, Rate, Threshold, then Create Client.

Tip: Clients only see the portal if they’re mapped to a WordPress user.

C) Day-to-day operations

1) View all clients (Dashboard)

Retainers → Retainers (Dashboard) shows:
- Balance, Rate, Threshold, Last Activity, and quick actions.

2) Client detail view

Click a client name to open their detail page.
At the top you’ll see Balance, Rate, Time Left.
Right-column actions:
- Add Funds (records a deposit)
- Add Time (records minutes worked; amount is auto-calculated at the chosen rate)
- Export CSV (full ledger export)
- Show/Hide Deleted (to see soft-deleted entries)

3) Editing a client

On the client page, use Edit Client:
- Change Name, Email, Mapped WP User, Default Rate, Low Threshold.
- Save to update.
  (This affects projections like Time Left and future entries; existing entries remain untouched.)

4) Ledger edits

Next to each entry:
- Edit → update minutes/rate/amount, note, or the entry’s date/time.
- Delete → soft delete (can be restored later).
- Restore (when viewing deleted entries).

5) CSV export

From the client page, click Export CSV to download the full ledger.

D) Top-up requests (from clients)

Clients submit Request a Top-Up in the portal. Requests appear in:
- Retainers → Top-Up Requests
For each request:
1. Approve (marks it approved, but does not add funds).
2. Mark Paid & Add Deposit (after you process payment) → this inserts a deposit and marks the request paid.
3. Dismiss if you won’t process it.

This ensures funds show in the balance only after payment is confirmed.

E) Low-balance alerts

A scheduled job checks balances hourly.
Emails go to the addresses set in Settings (and optionally to clients).
The cooldown prevents spamming (no duplicate reminder inside that window).

Heads-up: WordPress’ WP-Cron runs on page hits. For reliable timing, consider a real server cron calling wp-cron.php.

Shortcodes (for your site)

[[retainer_portal]]
Client portal (summary, request top-up, ledger). Shows data for the logged-in user’s mapped client.
[[retainer_balance]]
Prints the logged-in client’s balance.
(Optional advanced usage in newer builds may allow client_id attributes, but the standard use is “current client”.)

Tips & Best Practices

Naming notes: Encourage your team to write helpful notes when logging time (e.g., “Plugin bugfix—ticket #5321”).
Rates per client: If you change a client’s default rate, future time left reflects the new rate; previous entries stay exactly as recorded (correct for audit).
Soft delete = reversible: Use Show Deleted to review or Restore an entry anytime.
Portal access: If a client says they can’t see the portal, confirm the page is protected for members and the client is mapped to a WP user.
Email deliverability: Use an SMTP plugin (e.g., WP Mail SMTP) if you aren’t receiving alerts.

Troubleshooting

“Client not found” (after clicking through)

Usually means you followed a link to a client ID that doesn’t exist yet or was removed.
Fix: Create or sync the client first, then open their detail page from the Dashboard.

Blank page after submitting a form

Ensure you’re submitting from inside WordPress (nonce required); don’t post directly to admin-post.php.
Make sure you’re logged in with proper permissions (manage_retainers).
Turn on logging to see details: define WP_DEBUG and WP_DEBUG_LOG in wp-config.php.

Duplicate key / DB errors on activation

Deactivate → Activate again (the plugin’s schema ensures & self-heals tables/keys).
If it persists, check your DB prefix permissions and that the tables were actually created (cfr_clients, cfr_ledger, cfr_requests).

Low-balance emails not arriving

Check Settings → Notification emails.
Verify your site can send email (install SMTP).
Remember the cooldown—you won’t get repeated emails during that window.

Top-up still not in balance

That’s expected until you Mark Paid & Add Deposit. Approve ≠ deposit.

Quick Admin Checklist (handy)

Settings saved (rate, threshold, emails, cooldown).
Portal page created with [[retainer_portal]] and protected.
Clients added (via Sync Users or Add Client) and mapped to WP users.
Tested Add Funds, Add Time, and CSV Export on a sample client.
Verified Top-Up Requests flow end-to-end: Pending → Approved → Mark Paid & Add Deposit.
Confirmed low-balance alerts are working (use a low threshold for a quick test).
SMTP set up for reliable email delivery.