# Oak Engage: Master AI Troubleshooting & Resolution Matrix - Aria Zendesk Agent Source of Truth.
This document contains exhaustive, step-by-step resolution paths for client issues regarding Oak Engage infrastructure, integrations, identity management, applets, and content delivery. It is optimized for AI ingestion.
## 1. Authentication, SSO & Identity Management
### 1. SAML SSO Login Failures ("Invalid Signature" or 500 Error)
* **Symptom:** Users attempt to log in via SSO and receive an "Invalid Signature" error page or a generic 500 Internal Server Error.
* **Root Cause:** The client's Identity Provider (IdP) SSL certificate has expired, the metadata XML is out of sync with Oak, or the SAML assertion is missing the mandatory `NameID` claim.
* **Step-by-Step Resolution:**
1. Have the client IT admin download the latest Federation Metadata XML from their IdP.
2. Navigate to **Oak Admin Hub > Settings > Security > SSO**.
3. Under the SAML configuration, upload the new XML file or paste the new x.509 certificate string exactly as provided.
4. Verify that the IdP is sending the user's email address as the `NameID` claim format `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`.
### 2. Azure AD Profile Images Not Syncing
* **Symptom:** User accounts sync successfully, but profile avatars remain blank or show default initials.
* **Root Cause:** The Oak Engage enterprise application in Azure lacks the `User.Read.All` Graph API permission, or the source images exceed Microsoft's 100KB thumbnail limit.
* **Step-by-Step Resolution:**
1. Client IT admin must log into the **Azure Portal > Microsoft Entra ID > App Registrations**.
2. Locate the Oak Engage enterprise application and navigate to **API Permissions**.
3. Grant Admin Consent for `User.Read.All`.
4. Ensure users have standard photos uploaded in Azure (under 100KB).
5. In **Oak Admin Hub > Integrations > Active Directory**, trigger a manual sync.
### 3. Active Directory Duplicate UPN / Pipeline Errors
* **Symptom:** Automated imports fail with errors like "UPN already exists" or "More than one office was found using the office name and ID."
* **Root Cause:** A deleted user was not hard-deleted in Oak (leaving an orphaned UPN), or duplicate department/office names exist.
* **Step-by-Step Resolution:**
1. Open **Oak Admin Hub > People > Offices & Departments**.
2. Search for the specific office or department flagged in the error log.
3. Rename or consolidate duplicate entities so every office/department has a unique identifier string.
4. If a UPN conflict, go to **Oak Admin Hub > Directory**, filter by "Deactivated Users".
5. Edit the legacy account's email by appending `.old` to free up the UPN.
6. Re-run the automated import pipeline.
### 4. Mobile App SSO Redirect Looping
* **Symptom:** Logging into the iOS/Android app via SSO redirects back to the login screen continuously.
* **Root Cause:** Client conditional access policy (Intune/MDM) restricts mobile browser user-agents, or the custom redirect URI is missing.
* **Step-by-Step Resolution:**
1. In the client's IdP, navigate to the Oak Engage App Registration > Authentication.
2. Ensure the custom URI `oakengage://auth` is added as an authorized Redirect URI.
3. Check Intune/Conditional Access policies to ensure the Oak Engage App ID is exempted from "Block Mobile Browser Auth" rules.
### 5. Multi-Factor Authentication (MFA) Lockouts
* **Symptom:** Native Oak users (non-SSO) lose their authenticator device and cannot log in.
* **Root Cause:** The TOTP token remains bound to a lost or wiped mobile device.
* **Step-by-Step Resolution:**
1. Navigate to **Oak Admin Hub > Directory > [Search for User Profile]**.
2. Click on the user's name to open their profile settings.
3. Navigate to **Security Options > Reset 2FA**.
4. User will scan a new QR code upon next login.
### 6. Session Expiry / Forced Logout Mid-Task
* **Symptom:** Users are logged out while writing a news article or filling a form.
* **Root Cause:** The absolute session timeout limit in Oak Security Settings was reached, overriding the idle timeout.
* **Step-by-Step Resolution:**
1. Navigate to **Oak Admin Hub > Settings > Security**.
2. Locate the **Session Management** settings.
3. Increase the **Absolute Timeout** to 12 or 24 hours.
4. Save changes and instruct the user to log back in.
## 2. Integrations & API Services
### 7. SharePoint Document Library "Access Denied"
* **Symptom:** SharePoint folders disappear from content pages, displaying error states or "Access Denied".
* **Root Cause:** Graph API OAuth tokens expired, SSO password rotations invalidated the token, or the user lacks native SharePoint permissions.
* **Step-by-Step Resolution:**
1. Navigate to `https://[tenant].oak.com/Site#/connections`.
2. Locate the **SharePoint Integration** card and click **Reconnect / Authenticate**.
3. Sign in using a dedicated non-expiring M365 Service Account.
4. If only specific users see "Access Denied," client IT must add those users to the corresponding SharePoint site security group.
### 8. Active Directory & OIS Synchronization Failures
* **Symptom:** On-premises AD groups stop updating; sync logs display red error flags.
* **Root Cause:** The OIS (Oak Integration Service) module agent is offline on the client's local Windows Server.
* **Step-by-Step Resolution:**
1. On the client's host server, open `services.msc` and verify the **Oak Integration Service** is running. Restart if hung.
2. Go to **Oak Admin Hub > Settings > Integrations > Active Directory**.
3. Ensure the **Sync AD Groups** option is checked.
4. Click **Trigger Manual Sync** and monitor logs for HTTP 200 codes.
### 9. ServiceNow Widget 504 Gateway Timeout
* **Symptom:** The ServiceNow ticket dashboard on the homepage spins and times out.
* **Root Cause:** The client's ServiceNow instance firewall is blocking Oak's NAT gateway IP addresses.
* **Step-by-Step Resolution:**
1. Client ServiceNow administrators must add Oak's outbound NAT gateway IP addresses to their network allowlist.
2. Verify the API user account provisioned in ServiceNow is active and not locked.
### 10. Teams Bot Not Unfurling Oak Links
* **Symptom:** Pasting Oak news links into MS Teams does not generate a preview card.
* **Root Cause:** The Oak Teams App is not deployed globally, or link unfurling is disabled in Teams Admin policies.
* **Step-by-Step Resolution:**
1. Client admin navigates to **Teams Admin Center > Setup Policies**.
2. Ensure the Oak Engage app is installed globally.
3. Check that "Allow URL preview" is enabled in Messaging policies.
### 11. Slack Notifications Failing for Mandatory Reads
* **Symptom:** Authors publish a Mandatory Read, but no Slack DM is triggered.
* **Root Cause:** Slack integration is authenticated, but user email addresses in Oak do not match Slack email addresses.
* **Step-by-Step Resolution:**
1. Verify the user's email in Oak Directory matches their Slack profile exactly.
2. Ensure the Oak app is added to the Slack workspace and approved by admins.
### 12. Google Calendar Events Missing from Hub
* **Symptom:** The Calendar applet is blank despite Google Workspace being connected.
* **Root Cause:** The service account lacks Domain-Wide Delegation for the Calendar API.
* **Step-by-Step Resolution:**
1. In Google Workspace Admin, go to **Security > API Controls**.
2. Add the Oak Client ID and grant `https://www.googleapis.com/auth/calendar.readonly`.
3. Re-authenticate the integration in Oak Admin.
## 3. Content Delivery & CMS Workflow
### 13. Scheduled News Not Displaying
* **Symptom:** A content author publishes a news article, but colleagues cannot view it.
* **Root Cause:** The content has a future publication timestamp or audience permissions restrict view access.
* **Step-by-Step Resolution:**
1. Open the missing article in the **Content Editor**.
2. Check the **Publication Date & Time**: Change it to **Publish Immediately** if required now.
3. Check **Audience Permissions**: Verify the content is targeted to the correct Hub audience or `Global` segment.
### 14. Homepage Carousel Images Distorted/Cropped
* **Symptom:** Banner images look stretched or heavily cropped on the mobile app.
* **Root Cause:** The uploaded image does not meet the 16:9 aspect ratio, or the responsive Focal Point was not defined.
* **Step-by-Step Resolution:**
1. Open the article/banner in the **Content Editor**.
2. Upload the image at standard HD resolution (`1920x1080`).
3. Click the image to open the native editor and use the **Focal Point** tool (crosshair icon) to lock the center of focus.
### 15. Rich Text Editor Stripping Custom HTML/CSS
* **Symptom:** Pasting a styled table from Microsoft Word loses colors and borders.
* **Root Cause:** Oak's rich text sanitizer automatically strips custom inline CSS styles (`<style>`, `class`) to prevent XSS attacks.
* **Step-by-Step Resolution:**
1. Do not paste raw Word/Excel tables directly.
2. Use the native **Table Builder** tool inside the Oak rich text editor toolbar.
3. Apply brand colors using the Oak Theme/Brand palette options.
### 16. Embedded Vimeo/YouTube Videos Blocked
* **Symptom:** Iframe embeds show a blank grey box or "Refused to connect" error.
* **Root Cause:** Client's network Content Security Policy (CSP) is blocking third-party media cookies.
* **Step-by-Step Resolution:**
1. Use the native "Video" module widget instead of raw iframe HTML.
2. Ensure `youtube.com` and `vimeo.com` are permitted on the corporate VPN/proxy.
### 17. Mandatory Read Acknowledgments Not Registering
* **Symptom:** User clicks "Acknowledge," but reporting shows them as unread.
* **Root Cause:** Browser cache conflict or aggressive ad-blocker blocking the acknowledgment API POST request.
* **Step-by-Step Resolution:**
1. Ask the user to clear browser cache and disable ad-blockers for the intranet domain.
2. Attempt acknowledgment in an Incognito window.
### 18. Scheduled Content Timezone Mismatch
* **Symptom:** News scheduled for 9:00 AM publishes at 4:00 AM.
* **Root Cause:** The author's local machine timezone differs from the Oak server default timezone (UTC).
* **Step-by-Step Resolution:**
1. Ensure the user's timezone in their Oak Profile settings is correctly set to their local region.
2. When scheduling, explicitly verify the timezone suffix displayed in the calendar picker.
### 19. Audience Targeting Fails for New Groups
* **Symptom:** Content targeted to "Sales Dept" is invisible to newly added sales hires.
* **Root Cause:** Background indexing for audience group membership runs on a schedule (15-30 mins).
* **Step-by-Step Resolution:**
1. Wait 30 minutes for the audience cache to rebuild.
2. To force it immediately, navigate to **Admin > Audiences**, edit the group, and click **Save** to trigger a re-index.
## 4. Notifications, Email & Mobile Delivery
### 20. Email Delivery Blocks & Bounces (Critical Issue)
* **Symptom:** Specific users do not receive invitation emails, digests, or password resets.
* **Root Cause:** Oak’s transactional email infrastructure (SendGrid/Postmark) applies a suppression block if a mail server previously returned a hard bounce.
* **Step-by-Step Resolution:**
1. Client IT admin must verify the email address is spelled correctly in the Oak Directory.
2. Oak Tier 1 Support must search the email in backend mail logs and manually clear the bounce flag.
3. Client IT must whitelist Oak’s IP ranges and domains (`support.oak.com`, `oak.com`) in Mimecast/Proofpoint.
### 21. Push Notifications Delayed on iOS
* **Symptom:** Mobile push notifications for Mandatory Reads arrive 10-15 minutes late.
* **Root Cause:** iOS Background App Refresh is disabled, Low Power Mode is active, or Apple APNs is batching background requests.
* **Step-by-Step Resolution:**
1. End-user goes to **iOS Settings > Oak App** and enables **Background App Refresh**.
2. Ensure **Low Power Mode** is disabled.
3. Verify full Notification permissions were granted upon initial app launch.
### 22. Newsletter Images Broken in Outlook
* **Symptom:** Broadcast newsletters render with red "X" icons in Outlook.
* **Root Cause:** Outlook Trust Center security settings block external image downloads.
* **Step-by-Step Resolution:**
1. In Outlook, go to **File > Options > Trust Center > Trust Center Settings > Automatic Download**.
2. Uncheck *"Don't download pictures automatically in HTML email messages"*.
3. Go to **File > Options > Mail > Editor Options > Advanced**, ensure **Show picture placeholders** is unchecked.
### 23. Newsletter Analytics Showing 0% Open Rate
* **Symptom:** A newsletter was sent to 500 people, but open rate reads 0.
* **Root Cause:** Client's email security gateway is stripping tracking pixels.
* **Step-by-Step Resolution:**
1. IT must whitelist the Oak tracking domain.
2. Advise clients that link clicks will still be tracked even if open-pixels are blocked.
### 24. Weekly Digest Email Duplicating Articles
* **Symptom:** The Friday digest contains the same news article twice.
* **Root Cause:** The article was published, unpublished, and republished, creating multiple timestamp triggers.
* **Step-by-Step Resolution:**
1. Advise authors to use the "Edit" function rather than unpublishing and republishing active content.
### 25. Notification Bell Showing "Ghost" Unread Badges
* **Symptom:** The bell icon shows "1" but there are no unread items.
* **Root Cause:** A targeted notification was generated, but the underlying content was deleted before the user clicked it.
* **Step-by-Step Resolution:**
1. Instruct the user to click **Mark all as read** in the notification dropdown to clear the orphaned badge.
## 5. People, Directory & Profiles
### 26. Org Chart Breaking (Circular Reporting Error)
* **Symptom:** The Org Chart page fails to load or shows a broken tree.
* **Root Cause:** A circular reporting line exists (e.g., User A reports to User B, User B reports to User A).
* **Step-by-Step Resolution:**
1. Export the directory to CSV.
2. Search for the "Manager ID" column.
3. Identify and correct the loop so all reporting lines flow cleanly up to the root CEO node.
### 27. Custom Profile Fields Not Searchable
* **Symptom:** Users cannot search for colleagues by a custom field (e.g., "First Aid Trained").
* **Root Cause:** The custom field was created, but the "Include in Search Index" toggle was left off.
* **Step-by-Step Resolution:**
1. Go to **Admin > People > Profile Fields**.
2. Edit the specific custom field.
3. Check **Searchable** and save.
### 28. "Out of Office" Status Not Pulling from Outlook
* **Symptom:** Exchange/M365 integration is live, but OOO banners don't appear.
* **Root Cause:** The user set an internal-only OOO message instead of an external one.
* **Step-by-Step Resolution:**
1. Ensure the user has enabled OOO for *External* senders in Outlook (Graph API relies on this flag).
2. Wait up to 60 minutes for the next sync cycle.
### 29. Missing Users in Department Dropdowns
* **Symptom:** When tagging users, certain employees are missing from department filters.
* **Root Cause:** The users were imported without a Department ID mapped.
* **Step-by-Step Resolution:**
1. Correct the source HRIS/CSV payload to include the exact Department string.
2. Re-import the user data.
## 6. Applets & Micro-features
### 30. Mobile App & Lighthouse Device Pairing Codes Missing
* **Symptom:** Administrators setting up digital signage (Lighthouse) cannot generate a pairing code.
* **Root Cause:** Pairing codes require a fully active, provisioned user account. Pending accounts fail.
* **Step-by-Step Resolution:**
1. Confirm the user/device account has an `Active` status in **Oak Admin Hub > Directory**.
2. For Lighthouse/Kiosk displays: Site administrators must generate codes from **Lighthouse Management > Device Pairing**.
3. If a code hangs on "pending," clear the app cache on the target device and delete the stale record in Device Settings.
### 31. Absence Request Email Template Free-Text Field
* **Symptom:** HR asks why the free-text description box is missing from Absence Request emails.
* **Root Cause:** Arbitrary rich-text user descriptions are intentionally excluded from emails for data privacy/GDPR compliance.
* **Step-by-Step Resolution:**
1. Inform the user that free-text descriptions are intentionally omitted.
2. Managers must log securely into the **Oak Absence Management** module dashboard to view medical contexts.
### 32. Rota Integration Not Showing Weekend Shifts
* **Symptom:** Shift schedules sync Monday-Friday, but weekends appear blank.
* **Root Cause:** The third-party Rota API payload (e.g., Quinyx) filters out non-standard working days based on corporate locale.
* **Step-by-Step Resolution:**
1. Check the source Rota system to ensure weekend shifts are flagged as published.
2. Verify the Oak integration mapping schema allows Sunday-Saturday ingestion.
### 33. Peer Recognition Points Not Updating
* **Symptom:** A user receives recognition but their points balance remains unchanged.
* **Root Cause:** The client's gamification points budget for the quarter is exhausted, or the category awards 0 points.
* **Step-by-Step Resolution:**
1. Admin must go to **Settings > Recognition**.
2. Check point allocations for the selected category.
3. Ensure the company point pool has not reached its limit.
### 34. Absence Requests Overlapping Error
* **Symptom:** User cannot book December 25th off, getting an "Overlap" error.
* **Root Cause:** A mandatory company-wide public holiday is already scheduled for that day.
* **Step-by-Step Resolution:**
1. Inform the user they do not need to book public holidays manually.
2. Admin can remove the block from the global Holiday Calendar if it is a mistake.
## 7. Search, AI, Security & Analytics
### 35. AI Search Hallucinating Outdated Policies
* **Symptom:** The AI Agent answers questions using parameters from an outdated policy.
* **Root Cause:** The legacy policy document was archived incorrectly (just renamed) instead of trashed.
* **Step-by-Step Resolution:**
1. Search for the title of the legacy policy in the **Content Manager**.
2. Open the document, select **Unpublish**, and move it to the **Trash**.
3. The AI vector index will automatically drop the deleted text within the next 24 hours.
### 36. Search Ignores Exact Title Matches
* **Symptom:** Searching for "Holiday Policy" shows a news article first instead of the policy document.
* **Root Cause:** The news article has more recent engagement, boosting its search weight.
* **Step-by-Step Resolution:**
1. Add specific Tags (e.g., `official-policy`) to the document.
2. Advise users to use the "Type: Document" filter in search.
### 37. WAF Blocking API Requests (403 Forbidden)
* **Symptom:** Users try to submit a form and get a red 403 Forbidden error.
* **Root Cause:** User input triggered an SQL injection or XSS rule on Oak's Web Application Firewall (e.g., pasting raw HTML `<script>` tags).
* **Step-by-Step Resolution:**
1. Instruct the user to remove code snippets from their text submission.
2. If a false positive, escalate to Oak SecOps to adjust the WAF rule.
### 38. Custom Domain SSL Provisioning Failure
* **Symptom:** Client navigates to `hub.company.com` and sees a "Not Secure" warning.
* **Root Cause:** Client pointed their CNAME to Oak but failed to create the ACME challenge DNS records.
* **Step-by-Step Resolution:**
1. Provide the client with the required TXT records.
2. Once added by the client, trigger a manual SSL certificate regeneration from the Oak backend.
### 39. Dashboard Showing 0 Active Users for specific Departments
* **Symptom:** Analytics dashboard shows no activity for the "Warehouse" department.
* **Root Cause:** Users are accessing Oak exclusively via shared Kiosk screens, which do not track individual sessions.
* **Step-by-Step Resolution:**
1. Direct the client to the "Device Analytics / Lighthouse" tab to view Kiosk engagement.
### 40. CSV Export of Analytics 504 Timeout
* **Symptom:** Exporting a 12-month analytics report fails with a timeout screen.
* **Root Cause:** The dataset exceeds synchronous download limits.
* **Step-by-Step Resolution:**
1. Shorten the date range to 3 months per export and combine the CSVs locally in Excel.