Advanced Diagnostics

This guide covers advanced troubleshooting techniques for Organization Admins. Use these procedures when standard troubleshooting has not resolved the issue.

---

Data Validation

Identifying Data Integrity Issues

Common data integrity issues and how to detect them:

Issue	Symptoms	Detection Method
Duplicate time entries	Employee shows double hours	Reports > Time Detail, sort by employee and date
Orphaned shift assignments	Shifts assigned to deactivated employees	Reports > Schedule Audit
Missing clock-outs	Open time entries with no end time	Time Clock > Open Entries (filter for entries older than 24 hours)
Incorrect pay rates	Payroll totals do not match expectations	Reports > Payroll Preview vs. actual rates
Department mismatches	Employee appears in wrong department reports	Team > Employee detail > Department history

Running a Data Validation Check

1. Go to Settings > System > Data Validation
2. Select the validation scope:
   • Time entries: Check for duplicates, overlaps, and open entries
   • Employee records: Check for missing required fields
   • Schedule data: Check for unassigned shifts and conflicts
   • All: Run all validation checks
3. Set the date range to validate
4. Click Run Validation
5. Review the results report:
   • Errors: Issues that must be fixed (e.g., overlapping time entries)
   • Warnings: Potential issues to review (e.g., unusually long shifts)
   • Info: Informational findings (e.g., employees with no scheduled shifts)

Resolving Common Data Issues

Duplicate Time Entries

1. Go to Reports > Time Detail
2. Sort by employee and date to find duplicates
3. Compare the entries to determine which is correct
4. Delete the incorrect entry (Admin permission required)
5. Document the correction in the employee's time record notes

Missing Clock-Outs

1. Go to Time Clock > Open Entries
2. Filter for entries older than 24 hours
3. For each open entry:
   • Contact the employee or their manager to determine the actual clock-out time
   • Edit the entry to add the clock-out time
   • Add a note explaining the manual correction
4. Consider enabling Auto Clock-Out to prevent future occurrences

Overlapping Time Entries

1. Identify the overlap in the time detail report
2. Determine which entry is correct based on schedule and manager input
3. Edit or delete the incorrect entry
4. Review whether the overlap was caused by a system issue or user error

---

Timezone Issues

Timezone problems are among the most common sources of data discrepancies, especially for multi-location organizations.

How Timezones Work in Olympus Cloud

Component	Timezone Used	Configurable
Clock-in/out records	Employee's assigned location timezone	Via location settings
Schedule display	Viewer's location timezone	Automatic
Reports	Organization default or selected timezone	Per report
API timestamps	UTC (ISO 8601)	No (always UTC)
Notifications	Recipient's location timezone	Automatic
Audit log	UTC with local time display	Display only

Diagnosing Timezone Issues

Symptom: Clock-in time shows incorrect hour

1. Verify the employee's location assignment (Team > Employee > Location)
2. Verify the location's timezone setting (Settings > Locations > Edit)
3. Check the employee's device timezone (Profile > Device Info)
4. If the device and location timezones differ, the location timezone is used for records

Symptom: Report data does not match dashboard data

1. Check the timezone setting on the report (Report Settings > Timezone)
2. Compare with the dashboard timezone (always uses your profile timezone)
3. If they differ, the same clock-in will appear at different times in each view

Symptom: Scheduled shift appears at wrong time for employee

1. Verify the schedule was created using the correct location timezone
2. Check if the employee recently moved to a different location
3. Verify daylight saving time (DST) transitions are handled correctly

Daylight Saving Time (DST)

DST Transitions

During DST transitions (spring forward / fall back), shifts that span the transition time may show unexpected durations. For example, a shift from 1:00 AM to 6:00 AM during "spring forward" is actually 4 hours, not 5. Olympus Cloud handles this automatically, but duration displays may confuse employees. Avoid scheduling shifts that span the 2:00 AM DST transition when possible.

Multi-Timezone Best Practices

Practice	Description
Set location timezones correctly	Each location must have the correct timezone
Use location timezone for reports	When comparing locations, specify the timezone explicitly
Communicate shift times in local time	Employees see times in their location's timezone
Be aware of DST transitions	Review schedules near DST change dates
Use UTC for API integrations	External systems should send and receive UTC timestamps

---

Rate Limiting

Olympus Cloud applies rate limits to API requests and certain in-app actions to ensure platform stability.

Rate Limit Tiers

Action Type	Limit	Window	Applies To
API requests	1,000 requests	Per minute	Per API key
Login attempts	5 attempts	Per 15 minutes	Per user
Bulk operations	100 records	Per request	Per operation
Report generation	10 reports	Per hour	Per user
Export operations	5 exports	Per hour	Per user
Webhook deliveries	100 events	Per minute	Per endpoint

Identifying Rate Limit Issues

Symptoms:

• API returns HTTP 429 (Too Many Requests)
• In-app actions show "Please wait" or "Try again later"
• Integration syncs fail with timeout errors
• Reports queue instead of generating immediately

Checking Your Rate Limit Status:

1. Go to Settings > API > Usage
2. View current and historical request volumes
3. Check for rate limit hits (shown as red bars)
4. Identify which endpoints or users are consuming the most requests

Resolving Rate Limit Issues

Cause	Solution
Integration polling too frequently	Reduce sync frequency or use webhooks instead
Bulk import too large	Break imports into smaller batches (under 100 records)
Report generation during peak hours	Schedule reports for off-peak hours
Multiple admins running exports simultaneously	Coordinate export schedules
API client not implementing backoff	Add exponential backoff to retry logic

API Rate Limit Headers

API responses include rate limit information in headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the window resets
Retry-After	Seconds to wait before retrying (on 429 responses)

---

Webhook Verification

Verify that webhooks are functioning correctly and delivering accurate data.

Webhook Health Check

1. Go to Settings > Integrations > Webhooks
2. For each configured webhook, check:

Metric	Healthy	Action Needed
Success rate	Over 99%	Review failures if under 99%
Average latency	Under 2 seconds	Investigate endpoint performance if higher
Last delivery	Within expected interval	Check if events are being generated
Payload size	Under 1 MB	Optimize payload if consistently large

Testing Webhooks

Send a Test Event

1. Go to Integrations > Webhooks > select the webhook
2. Click Send Test Event
3. Choose the event type to simulate
4. Click Send
5. Check the delivery log for the result
6. Verify the payload was received by the endpoint

Verify Webhook Signatures

Olympus Cloud signs webhook payloads with HMAC-SHA256. Your endpoint should verify signatures to ensure authenticity.

Header	Purpose
X-Olympus-Signature	HMAC-SHA256 hash of the payload
X-Olympus-Timestamp	Timestamp of when the event was sent
X-Olympus-Event	Event type (e.g., timesheet.approved)
X-Olympus-Delivery-ID	Unique ID for this delivery attempt

Webhook Event Types

Event	Trigger	Common Use
employee.created	New employee added	HR sync
employee.updated	Employee profile changed	HR sync
employee.deactivated	Employee deactivated	Access revocation
timesheet.submitted	Employee submits timesheet	Notifications
timesheet.approved	Manager approves timesheet	Payroll processing
schedule.published	Schedule is published	Calendar sync
shift.swapped	Shift swap completed	Notifications
timeoff.requested	Time-off request submitted	Approval workflow
timeoff.approved	Time-off request approved	Calendar updates

---

Historical Data Audit

Review and verify historical data for compliance, payroll accuracy, and operational analysis.

Accessing the Audit Trail

1. Go to Settings > Security > Audit Log
2. Use filters to narrow your search:
   • Date range: Specific period to audit
   • User: Actions by a specific person
   • Action type: Specific types of changes
   • Resource: What was changed (employee, schedule, time entry)

Audit Trail Contents

Every change in the system is logged:

Data Logged	Details
Who	User who made the change (name, email, role)
What	What was changed (field, old value, new value)
When	Timestamp in UTC and local time
Where	IP address and device information
Why	Reason field (if provided by the user)

Common Audit Scenarios

Payroll Dispute Investigation

1. Filter audit log by the employee in question
2. Filter by "Time Entry" resource type
3. Review all modifications to their time entries for the disputed period
4. Export the filtered audit log as evidence

Security Incident Review

1. Filter audit log by "Login" action type
2. Look for failed login attempts, especially from unusual IP addresses
3. Check for role or permission changes around the time of the incident
4. Review any data exports performed

Compliance Audit

1. Export the full audit log for the compliance period
2. Filter by break compliance, overtime approvals, and policy changes
3. Verify that all required approvals were obtained
4. Document any exceptions or overrides

Data Retention

Data Type	Retention Period
Audit logs	12 months (Professional), 24 months (Enterprise)
Time entries	7 years
Schedules	3 years
Employee records	Duration of employment + 7 years
Reports	Until manually deleted
Messages	2 years

Extended Retention

For organizations that need longer audit log retention, set up scheduled exports. Go to Settings > Security > Audit Log > Schedule Export to automatically export audit data monthly to CSV for your own archival.

---

Performance Profiling

Diagnose slow loading times and unresponsive behavior.

Measuring Performance

Go to Settings > System > Performance to view:

Metric	Description	Target
Page load time	Average time to load the dashboard	Under 3 seconds
API response time	Average API call duration	Under 500ms
Report generation time	Average time to generate reports	Under 10 seconds
Search response time	Employee and schedule search speed	Under 1 second
Real-time update latency	Time for clock-ins to appear on dashboard	Under 5 seconds

Common Performance Issues

Issue	Likely Cause	Solution
Dashboard loads slowly	Too many widgets	Remove unused widgets, reduce data window
Reports take a long time	Large date range or dataset	Narrow filters, reduce date range
Search is slow	Large employee count without filtering	Use department or location filters
Schedule view lags	Viewing too many departments at once	Filter to specific departments
Export times out	Dataset too large	Break into smaller date ranges or departments

Performance Optimization Tips

Tip	Impact
Limit dashboard widgets to 6-8	Reduces initial load time
Use relative date ranges in reports	Prevents accidentally querying years of data
Archive old schedules	Removes historical data from active queries
Limit concurrent report generation	Prevents resource contention
Use Chrome or Firefox	Better performance than Safari or Edge for data-heavy views
Clear browser cache weekly	Prevents stale assets from slowing rendering

Browser Developer Tools

For advanced debugging, use your browser's developer tools:

1. Open Chrome DevTools: Press F12 or Ctrl+Shift+I
2. Go to the Network tab
3. Reload the page and observe:
   • Red entries: Failed requests (check status codes)
   • Slow entries: Requests taking more than 2 seconds
   • Large entries: Responses larger than 1 MB
4. Go to the Console tab to check for JavaScript errors
5. Share any findings with support when opening a ticket

---

Error Code Reference

When contacting support, provide the error code shown in the application.

Code Range	Category	Example
1xxx	Authentication	1001: Invalid token, 1003: Session expired
2xxx	Authorization	2001: Insufficient permissions, 2003: Role not found
3xxx	Data validation	3001: Required field missing, 3005: Invalid date range
4xxx	Integration	4001: Connection failed, 4003: Sync timeout
5xxx	System	5001: Internal error, 5003: Service unavailable

What to Include in a Support Ticket

When standard troubleshooting has not resolved the issue:

Information	Where to Find It
Error code	Displayed in the error message
Timestamp	When the error occurred (include timezone)
User affected	Email of the user experiencing the issue
Steps to reproduce	Exact actions that trigger the error
Browser/device	Browser name and version, or mobile device model
Screenshots	Capture the error message and surrounding context
Network info	WiFi, cellular, or VPN
Recent changes	Any configuration changes made recently

---

Diagnostic Tools Summary

Tool	Location	Purpose
Data Validation	Settings > System > Data Validation	Find data integrity issues
Audit Log	Settings > Security > Audit Log	Review historical changes
Sync Status	Settings > Integrations > Health	Monitor integration health
Performance Monitor	Settings > System > Performance	Identify slow operations
System Status	status.olympuscloud.ai	Check for service outages
Webhook Logs	Settings > Integrations > Webhooks	Debug webhook deliveries
API Usage	Settings > API > Usage	Monitor rate limits and usage

---

Related Guides

• Common Issues
• Sync & Network Issues
• User Permissions
• API Access