IT Troubleshooting Guide Template

Example — Fictional content for illustration purposes

VPN connection failure — remote users (macOS)

Symptom Category
Network & Connectivity
Affected System
VPN — GlobalProtect
Priority
P2 — High
Resolution Owner
SVSophie Vermeersch

🔍 Problem statement

Remote users on macOS Sonoma 14.3+ report that the GlobalProtect VPN client connects briefly (2–5 seconds) then drops with error SSL handshake failed: certificate expired. The issue began on 20 January 2026, the day after a routine gateway certificate renewal. Users on macOS Ventura and Windows are unaffected. Approximately 35% of remote macOS users are impacted.

🔧 Diagnostic steps

Step 1 — Verify network connectivity

Ask the user to open Terminal and run ping vpn-gateway.corp.local. If the gateway is unreachable, the issue is upstream (ISP or DNS) — route to the Network team. If the ping succeeds, proceed to Step 2.

Step 2 — Check GlobalProtect client version

Open GlobalProtect → Settings → About. If the client version is below 6.2.1, the user is running a version that does not support the renewed SHA-256 intermediate certificate. Ask the user to update via Self Service, then retry the connection.

Step 3 — Validate the certificate chain

In Terminal, run openssl s_client -connect vpn-gateway.corp.local:443 -showcerts. Verify that the intermediate certificate has a "Not After" date in the future. If the intermediate shows as expired, the macOS Keychain has cached the old certificate — proceed to Step 4.

Step 4 — Clear cached certificates

Open Keychain Access → System → Certificates. Search for "corp-intermediate-ca". Delete the expired entry, then restart the GlobalProtect client. The client will fetch the renewed certificate on its next connection attempt.

✅ Resolution

Immediate fix

Delete the cached expired intermediate certificate from the macOS Keychain (Step 4 above) and restart GlobalProtect. The client automatically downloads the renewed certificate on reconnection. Confirmed working on macOS Sonoma 14.3, 14.4, and 14.5.

Permanent fix (deployed 22 January)

MDM profile pushed via Jamf that removes the old intermediate certificate and installs the renewed one. Applied to all managed macOS devices. New devices receive the correct certificate at enrolment.

🔄 Known workarounds

  • Manual certificate import: Download the renewed intermediate certificate from the IT portal and double-click to install in the System keychain. Requires local admin rights.
  • Web-based VPN fallback: Users can access https://vpn-portal.corp.local for browser-based access while the client issue is resolved. Limited to web applications only — no RDP or file share access.

⬆️ Escalation criteria

ConditionEscalate toSLA
Gateway unreachable (Step 1 fails)Network Operations30 min
Certificate chain valid but connection still dropsSecurity Engineering1 hour
More than 10 users affected simultaneouslyIncident Manager (P1 bridge)15 min

🔗 Related articles

  • VPN Gateway Certificate Renewal Procedure (SOP-NET-012)
  • macOS Keychain Management for IT Admins
  • GlobalProtect Client Deployment via Jamf — version compatibility
This is an example — create yours in Elium

Structure how your IT team diagnoses and resolves recurring technical issues. This template captures the diagnostic path from initial symptom through verification steps to confirmed resolution — so agents spend less time searching and more time solving.

Try now in Elium

What is an IT troubleshooting guide?

An IT troubleshooting guide is a structured document that walks support teams through the diagnostic and resolution steps for a specific technical issue. It maps the path from initial symptom to confirmed fix, including verification checks, known workarounds, and escalation criteria.

Unlike incident reports — which document what happened after the fact — troubleshooting guides are proactive. They codify the diagnostic reasoning of experienced engineers so less experienced agents can resolve issues independently. Each guide reduces mean time to resolution by giving agents a tested path rather than starting from scratch.

Without documented guides, resolution quality depends on who picks up the ticket — senior engineers resolve intuitively while junior agents escalate prematurely, creating uneven service.

Who should use this template?

This IT troubleshooting guide is for teams responsible for IT service delivery:

  • IT Service Desk Managers — standardise diagnostic workflows so quality stays consistent across shifts
  • CIOs and IT Directors — reduce escalation rates by equipping frontline agents with tested diagnostic paths
  • Knowledge Managers — capture troubleshooting expertise in a structured, searchable format before senior engineers leave
  • L1 and L2 Support Agents — follow step-by-step diagnostic guides instead of guessing or escalating to Tier 3 by default

What’s included in this template?

The template has two parts: structured metadata fields and narrative sections.

Metadata fields capture the context agents need:

  • Symptom category (e.g. network, authentication, performance)
  • Affected system or service
  • Priority level (P1–P4)
  • Operating system and environment
  • Resolution owner — the engineer who validated the fix

Narrative sections walk through the diagnostic path:

  • Problem statement — symptoms as reported, with error messages and reproduction steps
  • Diagnostic steps — numbered checks ordered from quickest to most involved
  • Resolution — the confirmed fix, including commands, settings, or configuration changes
  • Known workarounds — temporary measures while the permanent fix is pending
  • Escalation criteria — when to stop diagnosing and route to a specialist
  • Related articles — links to related troubleshooting guides, SOPs, or vendor documentation

How to create and customise this template in Elium

  1. Open the Template Builder — Go to your profile menu and select the Template Builder tab, or click “+ Create” and choose “Create a new template”.
  2. Set the scope — Choose an icon, enable the template, and decide whether it applies platform-wide or to specific spaces (e.g. your IT Support space only).
  3. Add structured fields — Click “Field” to add metadata: tag field for symptom category (pre-populate with “Network”, “Authentication”, “Performance”), text field for affected system, tag fields for priority and OS/environment, and user field for resolution owner. Mark symptom category and priority as mandatory.
  4. Build the body structure — Use the “+” button to add content blocks for each narrative section: problem statement, diagnostic steps (numbered list block), resolution, known workarounds, escalation criteria, and related articles.
  5. Preview and save — Review the template layout, then save. Team members can now select it when creating new articles, and you can apply it to existing content in bulk.

Decision Tree ready: This template also works as an Elium Decision Tree — instead of reading through a static document, guide your team through step-by-step questions that lead directly to the right answer. Learn more about Decision Trees.

How AI helps you create and use this template

Capture faster. After resolving a tricky issue, feed Elium’s AI the ticket notes or terminal output. It generates a structured guide — problem statement, diagnostic steps, resolution — that your engineer reviews instead of writing from scratch.

Retrieve smarter. When a similar issue appears, agents ask Elium’s AI directly: “How do I fix VPN timeout errors for remote users on macOS?” The AI surfaces the exact diagnostic steps and resolution — your team’s tested solution with the commands that worked.

Why teams use Elium for IT troubleshooting

Troubleshooting guides are only useful if agents find them when they need them. A library in a shared drive helps no one when resolution time is measured in minutes. Elium makes troubleshooting knowledge actionable with structured templates, AI-powered search, and Decision Trees — interactive flows that guide agents through branching questions to the right resolution.

VINCI Energies — 97,000 employees across 61 countries — centralised IT knowledge in Elium after years of procedures scattered across Word, SharePoint, and email. The result: 4,000+ articles maintained by 500+ daily users across 110 dedicated spaces, with expiration-date governance ensuring guides stay current.

When an IT troubleshooting guide is published in Elium, agents find the right answer before they escalate, new hires resolve issues sooner, and senior engineers spend less time answering the same questions.

Frequently asked questions

A troubleshooting guide is a structured document that walks support agents through diagnosing and resolving a specific technical issue. Without documented guides, resolution quality depends on individual experience. Consistent documentation reduces escalation rates, shortens mean time to resolution, and ensures proven fixes are available to every agent.
A complete troubleshooting template includes metadata (symptom category, affected system, priority, OS/environment) and narrative sections: problem statement with reproduction steps, numbered diagnostic checks, confirmed resolution, known workarounds, and escalation criteria. The best templates also link to related guides and vendor documentation so agents have everything in one place.
Elium’s AI works with troubleshooting guides two ways. During capture, it drafts guides from raw inputs like ticket notes or chat logs. During retrieval, agents ask — “How do I fix the VPN timeout on macOS?” — and the AI returns specific diagnostic steps and resolution from your knowledge base.
Start with the exact symptom — not the root cause. Describe what the user sees, then list diagnostic steps from quickest to most involved. Keep each step actionable: “Run ping gateway-ip” rather than “check network connectivity.” End with clear escalation criteria so agents know when to stop and route upward.
A troubleshooting guide is proactive — it documents how to diagnose and resolve a known issue before it recurs. An incident report is reactive — it records what happened during a specific event. Troubleshooting guides prevent repeat escalations; incident reports capture lessons from individual events. Both feed your knowledge base but serve different moments.

Related reading: Read more on our blog