Getting Started with Oracle BI Publisher Desktop: A Beginner’s Guide

Troubleshooting Common Issues in Oracle BI Publisher Desktop

1. Installation/failures to install

• Symptom: Installer reports “another version already installed” or install fails.
• Quick fixes: Run installer as Administrator; remove prior installations via Control Panel or manually delete install folders; use Oracle Doc ID 1446586.1 for manual uninstall steps.
• If ribbon missing in Word after install: Run TBAddUser.exe (DotNetInstallFiles) as the current user or re-enable the COM add-in in Word → File → Options → Add-ins → COM Add-ins.

2. BI Publisher ribbon/add-in not appearing or not working in Word

• Causes: Wrong bitness (32 vs 64) vs Office, disabled COM add-in, Office security blocking, plugin installed under different Windows user, Java path changed.
• Steps: Ensure installer matches Office bitness; check COM Add-ins and Disabled Items; run TBAddUser.exe for per-user registration; reinstall using an admin account if needed; verify Java location if Desktop uses Java executables.

3. Template rendering problems (blank output, missing data, layout errors)

• Checks: Preview the template with sample XML; validate XML against the data model; open template in Template Builder/Template Viewer to see errors; inspect conditional logic and repeat/for-each tags.
• Fixes: Correct XPath/field names, escape special characters, ensure required fields exist in XML, use diagnostic print statements () for debugging.

4. Data model / SQL errors (ORA- errors, missing rows, duplicates)

• Symptom: Error codes (ORA-xxxx), wrong or incomplete row sets.
• Diagnostic steps: Run the SQL directly in the database to reproduce; enable BI Server/Publisher tracing to capture the executed query; check bind variables and date formats.
• Fixes: Correct SQL, add proper joins/grouping, handle NULLs, and parameterize dates/locale properly.

5. Performance issues (slow report generation, timeouts)

• Causes: Heavy SQL, large result sets, inefficient templates, server resource constraints, caching misconfiguration.
• Actions: Profile SQL and add indexes; paginate or limit result set; simplify templates (avoid nested tables/complex loops); increase JVM heap if necessary; clear caches and monitor server metrics; enable and review performance statistics (DMS Spy, MBean browser).

6. Export/format problems (PDF/RTF/Excel output incorrect)

• Checks: Verify the template output type and transformation; test with Template Viewer; check fonts and embedded resources for PDF; confirm Excel layout uses appropriate table/row definitions.
• Fixes: Update transformation templates, embed required fonts on server, adjust layout anchors and table structures, regenerate output after clearing cache.

7. Logging & diagnostics

• Where to check: BI Publisher logs (presentation, scheduler, admin logs), BI Server logs (obis, nqserver), WebLogic/FMW diagnostic logs.
• How to enable verbose logs: Set Oracle.xdo log level to TRACE in WebLogic or via BI Publisher runtime properties; enable data-model diagnostic in Runtime Configuration. Restart services after changes.

8. Cache/stale output issues

• Symptom: Changes to templates or data not reflected.
• Fix: Admin → Reload Files and Metadata; clear BI Server and presentation caches; restart services if needed.

9. Scheduler/job failures

• Checks: Review scheduler logs and job history, check user permissions and data source connectivity, inspect template parameters and bursting configuration.
• Fixes: Correct permissions, validate data source credentials, fix parameter mapping, test job manually.

10. When to escalate to Oracle Support

• Reproducible server crashes, obscure ORA errors after SQL verification, memory leaks or persistent out-of-memory conditions—collect logs, timestamps, sample XML/data, steps to reproduce, and open an SR with Oracle.

Quick troubleshooting checklist (ordered)

1. Reproduce the issue and note exact error/timestamp.
2. Check BI Publisher, BI Server, and WebLogic logs for matching timestamps.
3. Validate XML/data model and run SQL directly.
4. Test template locally in Template Builder/Viewer.
5. Clear caches and retry.
6. Enable trace logs if needed and gather artifacts for escalation.

If you want, I can produce a one-page printable checklist or specific step-by-step commands for Windows/Word add-in repair.