# The AI engine Source: https://docs.btsscorp.com/finops/account/ai-engine The model that powers chat and insight explanations — and the evidence guardrail Koala uses a language model to **explain** your cost data — to narrate insights and answer chat questions in plain language. The model is configurable per tenant. ## Two ways to power the AI You configure this in **Settings → AI Providers**, and there are two modes: Use the **Koala-provided** model. Nothing to set up — usage is **capped by your plan**, and a banner shows tokens used, your limit, and tier. When you reach the cap, Koala prompts you to add your own key. Add your **own provider key** (OpenAI by default) for **uncapped** usage on your own account. Manage, test, and reset usage from the same tab. | Setting | Default | | ------------ | ----------------------------------------------------------------- | | **Provider** | `openai` — swappable behind a common interface. | | **Model** | `gpt-4o-mini`. | | **Base URL** | `https://api.openai.com/v1` (override for a compatible endpoint). | Your API key is **encrypted at rest** and shown only as a masked hint. Use **Test** to validate it, and view or export **token usage** from the AI Providers tab. ## The evidence guardrail The most important thing to understand about Koala's AI is what it does **not** do: **The model never invents numbers.** Every figure in an insight or a chat answer comes from SQL over your own data. The language model only turns those verified results into readable explanations — it is given the evidence and asked to explain it, never to produce the numbers itself. This is why Koala's answers are safe to act on: each one can be traced back to the exact query and aggregates that produced it. See [How it works](/finops/how-it-works) for the full pipeline. ## Next steps Query your cloud costs in plain language. Evidence-backed findings and recommendations. # Tenancy & users Source: https://docs.btsscorp.com/finops/account/tenancy-and-users Sign-in, tenants, roles, and access Koala FinOps is **multi-tenant**. Everything you do lives inside a **tenant** — one organization's isolated space, with its own connections, cost data, users, and settings. Each business unit sees only its own data, while platform admins keep central oversight. ## Signing in Sign-in is powered by **Auth0**. You access Koala through your **tenant** — enter your tenant slug (for example `acme`), then authenticate. Organizations that use **SSO** sign in through their own identity provider. ## Roles Each user has a role within a tenant. Roles are cumulative — each includes what the ones below it can do. | Role | Can do | | ---------------- | ------------------------------------------------------------------------------------------------ | | **Viewer** | See dashboards, the explorer, allocation, and chat. | | **Analyst** | Everything a Viewer can, plus run ingestion and work with allocation and tagging. | | **Tenant Admin** | Full control of the tenant — connections, the AI engine, settings, and managing users and roles. | **Super admins** are a BTSS-internal, platform-level role that can see and manage all tenants (and edit the shared service ontology) — how new customer tenancies are provisioned. Regular tenants never see other tenants' data. ## Managing users Tenant admins add and manage users, and set each user's role, from the **Admin** area. A safeguard prevents removing or demoting the **last active Tenant Admin**, so a tenant can't be locked out of its own administration. ## Isolation and governance * **Tenant isolation** — data never crosses between tenants; each request is scoped to the caller's tenant. * **Role-based access** — what a user can do follows their role. * **Audit-ready** — SSO, isolation, and role-based access make the platform suitable for governed, enterprise use. ## Next steps Configure the model that powers chat and insight explanations. # Allocation Source: https://docs.btsscorp.com/finops/allocation Attribute spend to applications — even when resources aren't tagged Accurate showback and chargeback depend on knowing **which application each dollar belongs to**. In practice, plenty of resources go untagged. Koala's **application allocation** closes that gap. ## Coverage first Start by checking how much of your spend is already attributed. In the [cost explorer](/finops/explorer), pivot by `tag:Application` to see labeled coverage and spend per application — and how much remains untagged. ## Recommending application labels For resources with **no application tag**, Koala recommends a label. The recommendation engine is a **transparent, similarity-based classifier** — not a black box: Koala reads existing app tags (`Application`, `app`, `product`, `project`, and similar keys) to build labeled profiles for each application. Resources without an app tag are grouped by resource to cut line-item noise. Each candidate is matched to the closest application profile and returned with a **confidence score**. You control a minimum-confidence threshold, and Koala reports **diagnostics** (sample rows, how many fell below the threshold) so an empty result is always explained. Because the classifier is transparent and confidence-scored, you can see *why* a label was suggested and tune how aggressive the matching is — rather than trusting an opaque model. ## Tag untagged resources You don't have to fix tags back in each cloud. From the allocation page you can **apply an `Application` tag to a resource in Koala**; it's picked up on the next [ingestion](/finops/connections/ingestion) run. You can also **export your Koala tags** (to CSV or as a clipboard runbook) to push them back into your cloud tagging, so the two stay in sync. ## Split a shared resource Some costs belong to more than one owner. **Split allocation** lets you divide a single resource's cost across segments — owner, department, or cost center — with weighted percentages, so shared spend lands accurately on each business unit. ## From coverage to chargeback With more spend labeled, application pivots become complete enough to drive **showback and chargeback** — giving each business unit an accurate, self-serve view of what it spends. ## Next steps Validate coverage and spend by application. See what's driving each application's cost. # Ask Koala Source: https://docs.btsscorp.com/finops/chat Query your cloud costs in plain language and get answers with charts and totals Ask Koala is the fastest way to answer a cost question. Type it in plain language on the **Chat** page and get back an answer with the **charts and totals** to match — in seconds, no query writing required. ## What you can ask Questions about cost and usage across your clouds — for example: * "What was our daily spend last month? Show it as a bar chart." * "Top 5 services by cost this quarter, by provider." * "How much did the `payments` application cost in June?" * "Which regions grew the most month over month?" ## How it answers Koala's chat is an agent that turns your question into a real query and runs it: It classifies your intent and pulls out the **time window** and **dimensions** you asked about. If a question is ambiguous, it asks a **clarifying question** rather than guessing. It compiles and runs SQL over your ingested data, then formats the result as a readable answer with a chart and totals. As with insights, **the numbers come from SQL, never from the model** — the AI phrases the answer, the query provides the figures. See [The evidence principle](/finops/how-it-works#the-evidence-principle). You can also ask Koala **what it can do** or **what data it has**, and it will answer from its own capabilities and schema. ## Quick prompts, follow-ups, and memory * **Quick prompts** get you started with one click — for example *"Show me my top 5 most expensive services,"* *"Show me optimization opportunities this month,"* *"Spend trend for the last 30 days,"* or *"Quick wins."* * After each answer, Koala suggests **follow-up questions** to keep the thread going. * A chat remembers its **session context** so you can refer back to earlier turns; **New chat** clears it and starts fresh. Chat needs an AI provider configured. If none is set — or a plan's token cap is reached — Koala prompts you to set one up in **Settings → AI Providers**. See [The AI engine](/finops/account/ai-engine). ## Next steps Which model powers chat, and the evidence guardrail. The findings Koala surfaces without being asked. # Connect your clouds Source: https://docs.btsscorp.com/finops/connections/connect-clouds Point Koala at your OCI, AWS, Azure, and GCP cost exports Each cloud connection tells Koala **where your FOCUS cost export lives and how to read it**. You can add more than one configuration per cloud, mark one as the default, and turn on automatic scheduled ingestion. Credentials are **encrypted at rest** and shown only as masked hints. Set connections up in **Settings → Cloud accounts**. Each provider is below. ## Oracle Cloud (OCI) Koala reads FOCUS reports from an **OCI Object Storage** bucket using an API-key signing key. | Field | What it is | | ---------------------------- | ------------------------------------------------------------------- | | **Tenancy OCID / User OCID** | The identities the API key belongs to. | | **Fingerprint** | Your API signing key's fingerprint. | | **Private key (PEM)** | The signing key content. | | **Region** | e.g. `us-ashburn-1`. | | **Bucket & FOCUS prefix** | The bucket and path (default `FOCUS Reports/`) holding the exports. | OCI connections authenticate with an **API key** (instance principals aren't used). ## Amazon Web Services (AWS) Koala reads FOCUS exports from an **S3 bucket**. | Field | What it is | | ----------------------------- | --------------------------------------------------------------------------------------------------------- | | **S3 bucket, prefix, region** | Where the exports live and which region. | | **File pattern** | Which objects to match (default `*.csv.gz`). | | **Credentials** | An access key + secret (optionally a session token), **or** an **IAM role ARN** for cross-account access. | ## Microsoft Azure Koala reads FOCUS exports from an **Azure Blob** container. | Field | What it is | | ------------------------------- | ----------------------------------------------------------- | | **Storage account & container** | Where the exports live. | | **Authentication** | A **service principal** *or* a **SAS token** — provide one. | ## Google Cloud (GCP) Koala reads billing data from a **BigQuery billing export**. | Field | What it is | | ------------------------------ | --------------------------------------------------------------- | | **Project ID & dataset** | The project and BigQuery dataset holding the export. | | **Table pattern** | The export tables to match (default `gcp_billing_export_v1_*`). | | **Location** | The dataset location (default `US`). | | **Service account key (JSON)** | Optional — if omitted, application default credentials apply. | ## Defaults and scheduling Every provider supports the same two options: * **Default configuration** — the one Koala uses when you don't pick another. * **Automatic ingestion** — turn on a schedule (a cron expression) and a **look-back window** (how many days of files to re-check on each run), and Koala keeps your data current on its own. ## Next steps Upload files, run a load on demand, or schedule automatic ingestion. # Ingestion Source: https://docs.btsscorp.com/finops/connections/ingestion Upload FOCUS files, run loads on demand, or schedule automatic ingestion Ingestion is how your cost data gets into Koala. Every load is a tracked **run**, so you always know what was ingested and when. ## Two ways to get data in On the **Upload** page, drop in a FOCUS export (for example a `.csv` or `.csv.gz`). Good for a quick look or a one-off. Once a [cloud connection](/finops/connections/connect-clouds) is set up, Koala pulls FOCUS files straight from OCI Object Storage, AWS S3, Azure Blob, or GCP BigQuery. ## On demand or on a schedule * **On demand** — trigger a load for a chosen date range whenever you want. Each manual run uses **replace-then-load** for that window, so re-running a range cleanly refreshes it rather than double-counting. * **Scheduled** — turn on **automatic ingestion** on a connection (a cron schedule plus a look-back window) and Koala keeps the data current without anyone lifting a finger. ## Tracking runs The **Tasks** page shows ingestion runs and their status, so you can confirm a load finished and see what it covered. After a successful run, the dashboard's daily rollups refresh automatically, so charts and KPIs reflect the new data. Koala ingests **FOCUS** (FinOps Open Cost and Usage Specification) exports. Configure the export in each cloud, then point a Koala connection at it — see [Connect your clouds](/finops/connections/connect-clouds). ## Next steps See your spend once data is in. Explainable, evidence-backed findings. # Dashboard Source: https://docs.btsscorp.com/finops/dashboard Live spend visibility across every cloud The dashboard is your **one view of spend** — real-time cost across OCI, AWS, Azure, and GCP, without merging any spreadsheets. ## What you see * **KPI tiles** — total spend plus a breakdown by service category (compute, database, storage, network, integration, analytics, web) for the selected period, with month-over-month deltas. * **Trend chart** — spend over time, with a **day / month** grain toggle. * **Region × service heatmap** — where spend concentrates across regions and services. * **Top SKUs** — the costliest line items at a glance. * **Department / business report** — top resources by cost, split across your business segments. * **Insight Panel** — a plain-language narrative of what's driving the current view (see [Insights](/finops/insights)). ## Day, month, and date range The dashboard works over whatever window you choose: * **Day** — a single calendar day. * **Month** — a calendar month, aggregated from daily data. * **Date range** — any arbitrary start-to-end window. Under the hood, Koala keeps a pre-aggregated **daily** rollup and computes months and ranges from it at request time, so charts stay fast even over long histories. Rollups refresh automatically after each [ingestion](/finops/connections/ingestion) run. ## Filtering Narrow any view by provider, account, service, or region to focus on the slice you care about — a single team's footprint, one provider, or one region. ## Next steps Drill from a chart down to the underlying line items. Let Koala surface what changed and why. # Cost explorer Source: https://docs.btsscorp.com/finops/explorer Slice your cost data and trace any total to its line items Where the dashboard gives you the headline view, the **cost explorer** lets you get down to the individual FOCUS line items and trace any number back to its source. ## Filter and browse Narrow the data with filters — date range, provider, service category, subscription/tenancy, region, and resource group — then browse the matching **line-item records** (resource name and ID, compartment, cost). Because every figure comes from SQL over your ingested data, what you see always reconciles back to the source. ## Export and clean up * **Export** the current view to **CSV** for offline analysis or sharing. * **Purge** ingested data for a scope when you need to clear or re-load it (a confirmation step guards against accidents). To break spend down by an application tag or split shared costs, use the [Allocation](/finops/allocation) page — that's where tag pivots and split allocation live. ## Next steps Attribute untagged spend to applications. Ask the same questions in plain language. # How it works Source: https://docs.btsscorp.com/finops/how-it-works The ingest-to-insight pipeline, and why every number is evidence-backed Koala FinOps turns raw cloud billing exports into a single, explainable view of your spend. The pipeline is the same for every cloud. Point Koala at each cloud's cost export — OCI Object Storage, AWS S3, Azure Blob, or GCP BigQuery — or upload a file directly. Koala loads your **FOCUS** cost and usage exports, either on demand or on a schedule, and tracks every run. Line items from all clouds are mapped into one canonical cost model, so a "service" or a "region" means the same thing everywhere. The normalized data powers dashboards, the cost explorer, evidence-backed insights, application allocation, and the Ask Koala chat. ## FOCUS: one format across clouds Koala ingests **FOCUS** (FinOps Open Cost and Usage Specification) exports — the industry-standard billing format that OCI, AWS, Azure, and GCP can each produce. Because every cloud lands in the same shape, you get true side-by-side, apples-to-apples comparison instead of four incompatible bill formats. ## The evidence principle This is the idea that everything else rests on: **Every number comes from SQL over your own data. The AI never invents numbers.** Insights and chat answers are generated by the language model, but the figures inside them are produced by queries — and each carries its evidence: the query, the aggregates, and sample rows. That means an insight or a chat answer is always something you can trust and trace back to the underlying line items — not a plausible-sounding guess. ## Multi-tenant from the ground up Everything lives inside a **tenant** — one organization's isolated space. Each business unit sees only its own data, while platform admins keep central oversight. See [Tenancy & users](/finops/account/tenancy-and-users). ## Next steps Set up OCI, AWS, Azure, and GCP cost exports. Upload files or schedule automatic loads. # Insights Source: https://docs.btsscorp.com/finops/insights Explainable, evidence-backed findings and recommendations Insights are Koala's answer to *"what changed, why, and what should I do about it?"* — surfaced for you instead of hunted for. Each one is **explainable and evidence-backed**. You'll meet insights in two places today: the **Insight Panel** on the [dashboard](/finops/dashboard) narrates what's driving the current view, and [Ask Koala](/finops/chat) answers optimization questions like *"show me optimization opportunities this month."* A dedicated insights view is emerging alongside them. ## What an insight tells you Every insight carries a consistent set of facts: * **Impact** — the amount and currency at stake. * **Severity & confidence** — how much it matters and how sure Koala is. * **Time window & scope** — the period and the part of your estate it applies to. * **Drivers** — what's actually moving the number (the services, regions, or resources behind it). * **Recommendation** — the suggested action. * **Explanation** — a plain-language narrative that ties it together. ## Always backed by evidence Every insight includes its **evidence** — the query, the aggregates, and sample rows that produced it. The narrative is written by the AI, but the numbers are not: they come from SQL over your own data. See [The evidence principle](/finops/how-it-works#the-evidence-principle). This is what separates a Koala insight from a generic alert: you can open it, see exactly which line items drive it, and trust the figure before you act. ## What insights help you catch * **Spikes and overage** — costs rising faster than expected, month over month. * **Cost drivers** — the services, regions, or resources responsible for a change. * **Waste and optimization** — spend that looks reducible. * **Trends for planning** — patterns that inform budgets and forecasts. ## Next steps Trace a driver down to its line items. Follow up on an insight in plain language. # Introduction Source: https://docs.btsscorp.com/finops/introduction Multi-cloud cost intelligence — see your spend and ask Koala ## What is Koala FinOps? Koala FinOps™ is a **multi-cloud cost intelligence platform**. It brings your **OCI, AWS, Azure, and GCP** spend into one place, turns it into live dashboards and explainable insights, and lets anyone ask about their cloud costs in plain language — *"See spend. Ask Koala."* It ingests your clouds' standard **FOCUS** cost and usage exports, normalizes them into one model, and gives you a single source of truth for visibility, optimization, and allocation — no CSV merges, no spreadsheet reconciliation. ## Why Koala FinOps? ### One view, every cloud Real-time dashboards by service, region, and provider — OCI, AWS, Azure, and GCP together, not four separate consoles. ### Every number is evidence-backed All figures come from SQL over your own data. **The AI explains; it never invents numbers.** Every insight carries its evidence — the query, the aggregates, and sample rows. ### Tenant-first by design Each business unit sees only its own data, with central oversight. Role-based access, tenant isolation, and SSO make it audit-ready. ## Who uses it? Detect anomalies, cut waste, and improve showback/chargeback accuracy. Establish cost visibility and accountability across teams and services. Track spend against budgets, plan, and forecast with confidence. A trusted, data-driven view of where every cloud dollar goes. ## How it works, in one line You **connect** your clouds' cost exports, Koala **ingests** the FOCUS data, and then you **see** it on dashboards, **explore** the detail, get **insights**, and **ask Koala** in plain language. ## Next steps The ingest-to-insight pipeline and the evidence principle. Point Koala at your OCI, AWS, Azure, and GCP cost exports. Sign-in, tenants, roles, and access. Query your cloud costs in plain language. # Getting help Source: https://docs.btsscorp.com/finops/support/getting-help Support channels and common questions for Koala FinOps Need help with Koala FinOps? Reach us through any of these channels, or check the common questions below. ## Support channels Our support portal — the fastest way to get help. [support@btsscorp.com](mailto:support@btsscorp.com) btsscorp.com Talk to us about a rollout or a demo. ## Common questions * **My dashboard is empty.** Data appears after a successful ingestion run. Check that a [cloud connection](/finops/connections/connect-clouds) is set up and that a [load](/finops/connections/ingestion) has completed on the **Tasks** page. * **The numbers don't look right.** Every figure comes from SQL over the ingested data — use the [cost explorer](/finops/explorer) to trace a total back to its line items, and confirm the right date range and filters. * **Chat says it can't answer.** Ask about cost, usage, services, regions, providers, or time windows. If a question is ambiguous, Koala asks a clarifying question — see [Ask Koala](/finops/chat). * **Spend isn't attributed to an application.** Untagged resources need labels — see [Allocation](/finops/allocation) for how Koala recommends application labels. * **I can't see another team's data.** That's by design — tenant isolation means each business unit sees only its own data. See [Tenancy & users](/finops/account/tenancy-and-users). # Data Sources Explorer Source: https://docs.btsscorp.com/kdes/advanced/data-sources Browse Oracle objects without leaving Koala Studio ## What You Can See * Oracle Fusion subject areas, folders, and columns. * BI Publisher data models (where permissions allow). * Recently used tables/views for quick access. ## Using the Explorer 1. Click the database icon in the left rail to open the explorer. 2. Choose your connection from the dropdown. 3. Expand folders to view available tables/columns. 4. Click a column to copy its name into your clipboard or insert it into the active editor tab. ## Filters & Search * Use the search bar to find objects by name. ## Notes * The explorer reflects your Oracle privileges; if you don’t see a schema, request access from your admin. * Data isn’t queried until you run SQL—browsing metadata doesn’t incur heavy database load. # Multiple Tabs Source: https://docs.btsscorp.com/kdes/advanced/multiple-tabs Work on several queries simultaneously ## Creating & Managing Tabs * `Ctrl/Cmd+N` or the **+** button creates a tab. * Drag tabs to reorder them; a blue indicator shows the drop target. * Right-click a tab for **Duplicate**, **Close Others**, or **Move to New Window** (forthcoming). ## Per-Tab State * Each tab keeps its own connection, SQL text, history, and result cache. * Switching connections in one tab does not affect others. * Tab metadata is stored on disk so Koala restores your workspace exactly as you left it. ## Tips * Keep dedicated tabs for production vs. sandbox to avoid mistakes. * Duplicate a tab before experimenting so you always have the original SQL handy. # SQL History Source: https://docs.btsscorp.com/kdes/advanced/sql-history Review and reuse previously executed queries ## Accessing History * Click the clock icon in the left explorer or press `Ctrl/Cmd+Shift+H`. * Use the right-rail History panel to see per-tab history if you prefer inline access. ## Features * Stores up to 500 entries per user (mirrors your license tier). * Each entry shows timestamp, connection, row count, and execution time. * Click **Insert** to copy the query into a new tab, or **Run** to execute immediately with the same connection. ## Filters * Filter by connection, tab name, or keyword. * Use the date range picker to narrow history to specific windows (e.g., “last week”). ## Cleanup * Clear individual entries via the **···** menu. * Use **Clear History** to wipe everything (helpful before sharing screenshots or handing off the machine). History syncs via Koala Cloud, so you’ll see the same list on every device signed into your Koala account. # App Settings Source: https://docs.btsscorp.com/kdes/config/app-settings Customize Koala Studio to match your workflow ## Accessing Settings 1. Click your profile avatar → **Settings**. 2. Use the left sidebar to switch between categories (General, Editor, Updates). 3. Changes save automatically; some require restarting Koala. ## General * **Theme** – follow system, force light, or force dark. * **Start-up** – reopen last session or start with a blank window. ## Editor * Toggle minimap, line numbers, and word wrap. * Choose preferred font size and family (Monaco defaults). * Enable/disable “Warn on destructive statements” safety prompts. ## Updates * View your current version number and release notes. * Use the quick link to open the Koala download portal when you’re ready to install the latest build manually. ## Resetting * Use **Reset to defaults** at the bottom of each section to restore factory settings. * Resetting does not affect your connections, history, or saved queries. # Logging & Diagnostics Source: https://docs.btsscorp.com/kdes/config/logging-diagnostics Collect logs to troubleshoot Koala Studio ## Viewing Logs * Open Settings → **Logging & Diagnostics** or use the profile menu → **View Logs**. * Renderer logs include editor events, query status, and UI actions. * Main-process logs capture installer events, file-system operations, and SSO helper events. ## Log Levels * **Normal** – default; logs warnings and errors. * **Verbose** – adds info-level messages useful when working with Support. * **Debug** – only enable when Support requests it; may include extra network details. ## Exporting Logs 1. Go to **Settings → Logging & Diagnostics**. 2. Click **Export logs**. 3. Choose a destination; Koala zips recent logs for easy sharing with BTSS Support. ## Additional Diagnostics * Enable **Telemetry** (if your org allows it) to help BTSS monitor crash/update rates. * Toggle **Capture network traces** when troubleshooting SSO or Koala Cloud connectivity; Koala stores the trace alongside logs and clears it after export. # Performance Settings Source: https://docs.btsscorp.com/kdes/config/performance-settings Tune Koala Studio for large workloads ## Result Cache * Configure how many result sets Koala keeps in memory before writing to disk. * Lower the value on low-RAM machines; raise it if you switch between recent queries frequently. ## Grid Rendering * Toggle virtualization (on by default) to improve scrolling through large result sets. * Disable animations if you prefer instant row rendering. ## Auto-Cleanup * Set how often Koala clears the `temp/` directory and stale tab results (default: 7 days). * Run **Clean now** to reclaim disk space immediately. ## Hardware Acceleration * On Windows, you can disable GPU acceleration if you encounter driver issues. * Restart Koala after toggling this option for it to take effect. # Timeout Settings Source: https://docs.btsscorp.com/kdes/config/timeout-settings Control how long Koala waits for Oracle responses ## Why Adjust Timeouts? Different environments have different SLAs. Some customers need aggressive cancellation to protect shared resources, while others need to allow long-running reports. Koala Studio lets you tune both app-side and Oracle request timeouts. ## Query Timeout * Default: 5 minutes. * Change under **Settings → Query Execution**. * When the limit is reached, Koala cancels the request and shows a timeout error. Increase it if you routinely run heavy OTBI queries. ## Export Timeout * Applies when exporting large result sets to CSV/XLSX. * Default matches the query timeout; extend it if you export millions of rows. ## Idle Session Timeout * Configure how long inactive tabs keep connections alive before Koala releases them. * Lower values reduce load on Oracle but may require reconnecting when returning to a tab. ## Tips * Coordinate with your Oracle administrators—app-side timeouts should be slightly below server-side ones so Koala handles the cancellation gracefully. * If you consistently hit timeouts, consider refining your SQL or leveraging filters before exporting entire datasets. # Basic Authentication Source: https://docs.btsscorp.com/kdes/connections/basic-auth Sign in with Oracle username and password ## Overview Basic authentication lets you connect to Oracle Fusion by entering the same username and password you use in the web UI. It’s available on every Koala Studio plan. ## Prerequisites * Oracle Fusion Cloud account with report access * Username/password that are allowed to run OTBI or BI Publisher queries * Network access to your Oracle environment (VPN if required) ## Step-by-Step 1. Open Koala Studio and sign in with your Koala account. 2. Click **Connections** in the left rail or use `Ctrl/Cmd+,`. 3. Choose **Add Connection** → **Basic Authentication**. 4. Fill in: * **Name** – e.g., “Prod Financials”. * **Server URL** – your Oracle Fusion host ([https://xxxx.oraclecloud.com](https://xxxx.oraclecloud.com)). * **Username/Password** – saved securely and encrypted. * Optional **Description/Default schema** to label the connection. 5. Click **Test Connection**. If it succeeds, choose **Save**. The new connection now appears in every query tab’s dropdown so you can run SQL immediately. ## Security Notes * Credentials are encrypted locally and in Koala Cloud—Koala never stores them in plain text. * Password changes on Oracle require you to edit the connection and update the stored password. ## Troubleshooting * **Invalid credentials** – confirm the account isn’t locked and that MFA isn’t required for API access. * **Connection timeout** – verify VPN/proxy settings or try again after switching networks. # Managing Connections Source: https://docs.btsscorp.com/kdes/connections/managing-connections Organize, edit, export, and import your Koala Studio connections ## Viewing Connections * Open the **Connections** drawer from the left rail or press `Ctrl/Cmd+,`. * Use the search bar to filter by name or server. * Icons indicate the auth type (Basic, OAuth PKCE, Windows SSO authentication). ## Editing or Duplicating 1. Hover a connection and click **···**. 2. Choose **Edit** to change names, servers, or credentials. 3. Use **Duplicate** when you need the same settings but with a different schema or environment. ## Export / Import (`.kdex`) * **Export**: click **···** → **Export connections**. Choose a passphrase to encrypt the `.kdex` file. * **Import**: click **Import**, select the `.kdex`, and provide the passphrase. Existing connections update if the IDs match; new ones are added automatically. * Use exports to share configurations between Koala Studio and the VS Code extension. ## Deleting * Click **Delete** from the **···** menu. Koala asks for confirmation and removes both the metadata and any stored credentials. * Deleting a connection removes it from all tabs; open tabs prompt you to choose another connection. ## Tips * Keep production and sandbox environments clearly labeled. * Periodically export your list as a backup—files are encrypted, so it’s safe to store them in password managers or secure drives. # OAuth PKCE Authentication Source: https://docs.btsscorp.com/kdes/connections/oauth-pkce Use OAuth 2.0 with Proof Key for Code Exchange ## When to Use OAuth PKCE Choose OAuth PKCE when your organization requires modern OAuth flows with rotating tokens instead of static passwords. Koala Studio mirrors the KDEE experience, but the prompts open inside the native window instead of VS Code. ## Prerequisites * OAuth client registered in Oracle Identity/IDCS with redirect URI pointing to Koala (`https://auth.koala.app/callback` or your tenant-specific URL). * Client ID, authorization endpoint, token endpoint, and scopes provided by your admin. * Koala Studio signed in with your Koala account. ## Setup Steps 1. Open **Connections** → **Add Connection** → **OAuth PKCE**. 2. Provide the basics: **Name**, **Server URL**, and optional description/default schema. 3. Enter the OAuth configuration: * **Client ID** * **Authorization URL** * **Token URL** * **Redirect URL** (pre-filled for Koala; override only if your org uses a custom callback) * **Scope** (usually `https://fa.oraclecloud.com/OA_HTML/AppsLocalLogin.jsp` but follow your admin’s guidance) 4. Click **Test Connection**. A secure popup guides you through the OAuth login. 5. After consent, Koala stores the refresh token encrypted and keeps the access token refreshed automatically. ## Token Handling * Access tokens are refreshed silently as long as your Koala session is active. * If your admin revokes consent, Koala prompts you to reauthenticate the next time you run a query. ## Troubleshooting * **Blank popup** – ensure embedded browser access isn’t blocked by security software. * **Invalid redirect URI** – confirm the value registered for your client matches Koala’s callback URL. # Windows SSO Authentication Source: https://docs.btsscorp.com/kdes/connections/windows-sso Authenticate with your Windows credentials via WebView2 ## Overview On Windows, Koala Studio bundles the Koala SSO Helper (WebView2) to launch a native Oracle login window. Use this option when your organization enforces Integrated Windows Authentication or other SSO providers that rely on Windows credentials. ## Prerequisites * Windows 10 or 11 with the Microsoft WebView2 runtime installed (bundled with Koala, but corporate devices may remove it—reinstall from Microsoft if needed). * Network access to the Oracle SSO endpoint. * Koala Studio version 1.0.0 or later. ## Connecting with Windows SSO Authentication 1. Go to **Connections** → **Add Connection** → **Windows SSO Authentication**. 2. Fill in the basic connection details (name, server URL, optional description/schema). 3. Click **Sign in with Windows**. 4. A branded Windows login window appears. Complete the MFA/SSO prompts required by your org. 5. When the window closes, Koala saves the resulting token securely and tests the connection automatically. ## Token Renewals * Tokens expire per your IdP policy. Koala notifies you to reauthenticate when needed. * Switching Windows users on the same machine may invalidate the stored token, so sign in again if queries fail. ## Troubleshooting * **SSO window never appears** – install/reinstall WebView2 and restart Koala Studio. * **Stuck loading screen** – ensure the Oracle SSO URL is reachable (VPN, proxy, firewall). * **“Token expired” errors** – re-open the connection, click **Sign in with Windows**, and finish the flow again. # KDEE vs. KDES Source: https://docs.btsscorp.com/kdes/differentiators Two ways to use Koala, one feature set ## Side-by-Side Comparison | Area | KDEE (VS Code) | KDES (Native Desktop) | | ------------------- | ------------------------------------------------------ | ------------------------------------------------------------ | | How you install | From the VS Code Marketplace | Download a signed DMG/MSI installer | | Where it runs | Inside VS Code (as an extension) | Stand-alone window with native menus | | Authentication | No Koala account required (VS Code SecretStorage only) | Requires Koala Cloud sign-in plus Windows SSO authentication | | Local storage | VS Code global state & secrets | Dedicated Koala folder with tab/results caches | | Sharing connections | VS Code Settings Sync or export/import | Encrypted `.kdex` today, automatic sync coming | | Updates | Managed by VS Code | Download latest DMG/MSI from Koala portal | ## Choosing the Right Surface * Stay on KDEE if your team already lives inside VS Code or extensions are easier to deploy. * Pick KDES when you need native clipboard/file access, richer OS integration, or a self-contained installer for locked-down environments. * Mix and match—both apps has similar features and connections can be exported and imported across apps # Account Access Source: https://docs.btsscorp.com/kdes/installation/account-access Create or recover your Koala account for Studio ## Creating a Koala Account Unlike the VS Code extension (which relies on VS Code’s own identity and SecretStorage), Koala Studio requires a Koala Cloud account. If you’re new to Koala: 1. Launch Koala Studio and click **Create account** on the sign-in screen. 2. Enter your work email and click **Send code**. 3. Check your inbox for a one-time verification code (OTP) and enter it in Koala. 4. Choose a display name and accept the terms. Your account is ready immediately. > Already using the VS Code extension? Sign in with that same email—no extra setup required. ## Staying Signed In * Koala stores a secure cloud session token on your device, so you don’t need to sign in every time. * If you switch machines, just sign in once per device; each one maintains its own session. * Use **Profile → Sign out** only when you need to revoke access (e.g., shared computer). ## Password & OTP Reset * On the sign-in screen, click **Forgot password?** (available if your org uses password-based login). * Koala emails a one-time code. Enter it to set a new password securely. * For OTP-only tenants, simply request a new verification code whenever you need to sign in—no static password required. ## MFA / SSO Notes * Organizations using SSO (OAuth PKCE or Windows SSO authentication) control login policies centrally. Koala follows whatever MFA/OTP rules your IdP enforces. * If your account is locked or you don’t receive OTP emails, contact your identity admin or BTSS Support to unblock the user. # Download & Install Source: https://docs.btsscorp.com/kdes/installation/download-install How to install Koala Data Explorer Studio on your machine ## 1. Get the Installer 1. Visit the [Koala download portal](https://www.btsscorp.com/koala-data-explorer/) (the same link appears in your license email and Freshdesk articles). 2. Choose the installer for your OS: * **macOS:** `.dmg` * **Windows:** `.msi` ## 2. Install ### macOS 1. Double-click the downloaded `.dmg`. 2. Drag **Koala Data Explorer Studio** into your `Applications` folder. 3. If macOS flags the app as “from an unidentified developer,” right-click the app, choose **Open**, and confirm. ### Windows 1. Double-click the downloaded `.msi`. 2. Follow the on-screen wizard to complete installation. 3. Launch Koala Studio from the Start Menu or desktop shortcut. ## 3. Sign In * Launch the app and sign in with your Koala credentials. # First Connection Source: https://docs.btsscorp.com/kdes/installation/first-connection Create your first Oracle connection inside Koala Studio ## Step 1 – Sign In 1. Open Koala Studio. 2. Sign in with your Koala Cloud account (email OTP or SSO, depending on your tenant). If you previously used only the VS Code extension, create a Koala account first—the extension itself does not require one. ## Step 2 – Launch the Connection Drawer 1. Click **Connections** in the left rail or use `Ctrl/Cmd+,`. 2. Choose **Add Connection**. ## Step 3 – Choose the Auth Method * **Basic Auth:** supply the Oracle Fusion username/password. * **OAuth PKCE:** enter client ID, auth/token endpoints, and redirect URI (matches your org settings). * **Windows SSO authentication:** available on Windows when the WebView2 helper is installed—launches a native window to capture your JWT. ## Step 4 – Save & Test 1. Provide a friendly name and optional description so you can recognize the connection later. 2. Click **Test Connection** to validate credentials. 3. Save; the connection now appears in the tab selector and is synced to Koala Cloud so other machines can reuse it. ## Step 5 – Run Your First Query 1. Open a new tab (Ctrl/Cmd+N). 2. Pick the connection you just created. 3. Paste or type your SQL and press `Ctrl/Cmd+Enter`. 4. Inspect results, export to CSV/XLSX, or copy cells/rows as needed. Your connection metadata remains available the next time you open Koala Studio, and it can be exported to KDEE via encrypted `.kdex` files when needed. # System Requirements Source: https://docs.btsscorp.com/kdes/installation/prerequisites What end users need before installing Koala Studio ## Supported Platforms * **macOS:** Monterey (12) or later on Intel or Apple Silicon. * **Windows:** Windows 10 (21H2) or Windows 11 with the WebView2 runtime. ## Account Access * A Koala Cloud account to sign in. If you previously only used the VS Code extension (which does not require a Koala account), sign up from the Koala Studio login screen before proceeding. * Network access to your Oracle Fusion OTBI/BIP environments. * Optional: BTSS license key if you plan to unlock paid features. * License tiers and activation flow match the VS Code extension (`koala/licensing/*`). ## Hardware & Permissions * 8 GB RAM minimum recommended for handling multiple result sets. * \~1 GB free disk space for the application plus additional space for cached query results. * Ability to install signed applications (admin rights may be required on locked-down machines). # Introduction Source: https://docs.btsscorp.com/kdes/introduction Professional native SQL tool for Oracle Fusion Cloud ## What is Koala Data Explorer Studio? Koala Data Explorer Studio™ (KDES) is the native desktop edition of Koala. It delivers the same Oracle Fusion OTBI power as the VS Code extension but in a stand-alone macOS and Windows app with its own installer, menus, and update flow. * Ships as signed DMG/MSI installers with native menus, window controls, and OS integrations. * Includes Monaco-powered editing, multi-tab workflows, saved queries, SQL history, CSV/XLSX export, and copy helpers. * Stores results locally for offline review while credentials stay encrypted in Koala’s cloud service. ## Why Koala Studio? ### Native Convenience Launch Koala like any other application—no VS Code dependency, no extension updates to manage. ### Enterprise Friendly Give analysts and consultants a self-contained tool that respects OS security controls, supports SSO, and works in locked-down environments. ### Seamless Switching Connections, query history, and features mirror the extension, so teams can move between KDEE and KDES without relearning anything. ## Key Benefits macOS and Windows builds with their own menus, window controls, and tray integration Monaco tabs, semicolon-scoped execution, smart query history, and tab-specific connections Interactive grid with copy helpers, CSV/XLSX export, and an embedded CSV viewer for shared files Download new macOS/Windows builds from the Koala portal and install over your current version in minutes ## Who Uses Koala Studio? ### Analysts & Consultants Sometimes prefer a dedicated desktop window (or don’t have VS Code installed) but still want the same Koala capabilities. ### Enterprise Users Operate under strict install policies but still require Oracle query access. ### Developers & Integrators Prefer a native shell that keeps SQL tasks separate from coding sessions yet stays in sync with the extension. ## Getting Started 1. [Download the installer](/kdes/installation/download-install) for your OS. 2. Sign in with your Koala account and create your first connection. 3. Explore the SQL editor and CSV tooling using the guides in this section. # Activating Koala Studio Source: https://docs.btsscorp.com/kdes/licensing/activating-license Enter your Koala license key in the native app ## Before You Start * Purchase a license through the BTSS store or retrieve your key from the email receipt. * Make sure Koala Studio is signed in with the same Koala account you used for the purchase. ## Activation Steps 1. Open Koala Studio. 2. Click your profile avatar → **License**. 3. Paste your license key (e.g., `KOALA-XXXX-XXXX`). 4. Click **Activate**. Koala validates the key and unlocks paid features immediately. ## Troubleshooting * **Key already in use** – deactivate it from another machine via the license portal first. * **Expired key** – renew via the store; Koala applies the renewal instantly after purchase. # Free vs Paid Features Source: https://docs.btsscorp.com/kdes/licensing/free-vs-paid Understand what’s included in each Koala Studio tier ## Free Tier Ideal for light usage or evaluation. * Single query tab * Basic authentication * 50 rows per query limit * CSV/JSON export * SQL history capped at 50 entries ## Paid License Unlock the full desktop experience. * Unlimited query tabs and saved queries * OAuth PKCE + Windows SSO authentication * Unlimited rows per query * Excel export * Data sources explorer * Performance monitor * Extended history (up to 500 entries) Licenses purchased for the VS Code extension also apply to Koala Studio—activate once and use both products interchangeably. # Managing Licenses Source: https://docs.btsscorp.com/kdes/licensing/managing-license Move Koala Studio licenses between machines ## View License Status * Profile avatar → **License** shows the current key, plan, and renewal date. * Click **Manage in portal** to open the Lemon Squeezy customer portal (same as KDEE). ## Deactivate a Machine 1. In Koala, go to **Profile → License**. 2. Click **Deactivate** to free the seat. 3. Restart Koala or close the app; the license detaches from that device. Use this when switching laptops or before re-imaging a device. ## Update Billing * In the customer portal you can update payment methods, download invoices, or change plan tiers. * All changes sync back to Koala automatically—no new key required. ## Lost Keys * Retrieve license keys from the original receipt email or the portal. * If the email address changed, contact BTSS Support with proof of purchase to transfer ownership. # Refund Policy Source: https://docs.btsscorp.com/kdes/licensing/refund-policy How Koala Studio handles refunds and cancellations ## Trial Period * Koala Studio’s free tier lets you evaluate the native app without a purchase. * Paid licenses follow the same policy as the VS Code extension. ## Refunds * Within 14 days of purchase, contact BTSS Support with your order number to request a refund. * Refunds are processed via the original payment method. * Seats obtained through enterprise agreements follow the master contract terms—contact your account manager. ## Cancellations * Subscriptions renew automatically. Cancel anytime via the customer portal to stop future charges. * After cancellation, your license remains active until the end of the current billing period. ## Need Help? * Email [support@btsscorp.com](mailto:support@btsscorp.com) or submit a Freshdesk ticket with your license email and order ID. # Koala Studio Privacy Policy Source: https://docs.btsscorp.com/kdes/policies/privacy-policy Customer-facing summary of how Koala Studio handles data, security, and user rights. Koala Studio is designed for enterprise data teams, so its privacy policy stays simple and customer-friendly. This page highlights what data is collected, what never leaves your device, and how BTSS keeps information secure while supporting regional compliance (GDPR, CCPA, etc.). ## 1. Data We Collect | Category | Details | Why we collect it | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | **Account details** | Email, password hash, and identity-provider metadata captured by Supabase Authentication during sign-up/sign-in. | Manage your Koala account, enforce licensing, and secure device sessions. | | **Connection labels** | Display names, notes, and metadata that help you organise Oracle Fusion / OTBI endpoints. Usernames/passwords stay encrypted locally. | Show friendly names in the UI and keep your workspace consistent across sessions. | | **Usage signals** | Anonymous counts such as “queries executed this week” or “update applied.” No query text or table names are transmitted. | Keep auto-updates, licensing, and error alerts working without tracking individual SQL. | | **Support content** | Logs, screenshots, or documents you send voluntarily to BTSS support. | Diagnose issues and deliver fixes or advice. | ## 2. Data That Stays on Your Device * **Query text and result sets**: Stored as JSON/SQL within your operating system’s `userData` folder\ (`~/Library/Application Support/Koala Data Studio`, `%APPDATA%\Koala Data Studio`, or `~/.config/Koala Data Studio`). * **Session state**: Tab layouts, connection selections, and editor history so Koala reopens exactly where you left off. * **Exports and attachments**: CSV, XLSX, and `.kdex` export files live in your Documents folder; Koala does not upload them. You can delete these files at any time. The app never transmits raw query content or exports back to BTSS. ## 3. How BTSS Uses Information | Purpose | How it helps you | | ----------------------- | --------------------------------------------------------------------------------------- | | **Account security** | Authenticates via Supabase, prevents abuse, and enforces device session limits. | | **Product experience** | Restores tabs, manages automatic query-history cleanup, and notifies you about updates. | | **Customer assistance** | Enables BTSS to troubleshoot tickets, share fixes, and send critical release notes. | | **Compliance** | Maintains the records required for licensing, audits, and App Store submissions. | BTSS does **not** sell personal data or use it for advertising. ## 4. Retention & User Controls * **Automatic cleanup**: Query history can auto-purge daily or weekly during off-peak hours. You control retention days and max record counts, or run “Cleanup Now” from Settings for immediate deletion. * **Account deletion**: Contact `info@btsscorp.com` to close your account. BTSS removes Supabase authentication records and revokes licenses within 30 days unless regulations require a longer retention period. * **Exports**: You manage CSV/XLSX/`.kdex` files locally. Deleting them from your filesystem removes them permanently. ## 5. Security Practices * **On-device encryption**: Connection credentials are encrypted with Electron `safeStorage`, which binds keys to your OS profile (Keychain on macOS, DPAPI on Windows, libsecret on Linux). If safeStorage is unavailable, Koala warns you before storing credentials in plaintext. * **Encrypted transport**: All communication with Supabase, licensing, and update services uses HTTPS with certificate validation and signature checks on downloaded builds. * **Least-privilege cloud usage**: Supabase is used strictly for authentication. Query data, results, and exports never leave your machine. * **Signed releases**: macOS and Windows installers are code-signed, and auto-updates verify signatures before install. ## 6. Third-Party Providers | Provider | Role | Notes | | ---------------------------------------- | ----------------------------------------------- | ------------------------------------------------ | | **Supabase** | Authentication and minimal account metadata. | Stores hashed passwords + email. No SQL content. | | **Apple / Microsoft / Linux repos** | Deliver signed installers and update manifests. | Standard OS app stores / update feeds. | | **Billing partner (e.g., LemonSqueezy)** | Processes payments and invoices. | Payment data never touches Koala Studio. | All vendors must meet SOC 2 or equivalent security standards and honour their own privacy agreements. ## 7. Children’s Data Koala Studio targets enterprise professionals and is **not** intended for users under 16. BTSS does not knowingly collect information from children. If you believe a child has provided data, email `info@btsscorp.com` and BTSS will delete it promptly. ## 8. Regional Privacy Rights * **EU / UK (GDPR/UK GDPR)**: Request access, correction, deletion, or export of your personal data. * **California (CCPA/CPRA)**: Ask for disclosure or deletion. Koala does not sell personal data, so opt-out requests are automatically honoured. * **Other regions**: BTSS complies with local privacy acts (PDPA, DPDP, etc.) and can host Supabase data in-region for enterprise contracts. Submit requests via `info@btsscorp.com`. BTSS responds within 30 days (or faster where laws require). ## 9. Contact BTSS Need more details or want to report a concern? * **Email:** `info@btsscorp.com` * **Support portal:** [https://www.btsscorp.com/contact-us](https://www.btsscorp.com/contact-us) * **Mail:** BTSS Corporation, 400 Spectrum Center Drive, Suite 1900, Irvine, CA 92618 USA Major changes to this policy are announced through release notes and in-app notifications so teams always understand how their data is handled. # Bind Variables Source: https://docs.btsscorp.com/kdes/query-editor/bind-variables Use bind variables in Koala Studio queries ## Why Use Bind Variables * Prevents SQL injection by separating parameters from the statement. * Speeds up repeated executions because Oracle can reuse execution plans. ## Syntax Use `:variableName` inside your SQL, e.g.: ```sql theme={null} SELECT * FROM gl_balances WHERE ledger_id = :ledger AND period_name = :period; ``` ## Running with Prompts 1. Execute the query. Koala detects the bind variables and opens a prompt dialog. 2. Enter values for each variable. Koala remembers recent values per tab. 3. Click **Run** to execute with those values. ## Managing Bind Definitions * Use the **Bind Variables** panel in the right rail to prefill defaults. * Toggle “Remember values” if you want Koala to reuse them the next time. * Clear stored values via the panel menu if you switch contexts. ## Tips * Keep variable names descriptive (`:start_period` vs `:p1`). * Combine with Saved Queries so teammates can run the same template and simply fill in the prompts. # Executing Queries Source: https://docs.btsscorp.com/kdes/query-editor/executing-queries Run SQL safely and understand what executes ## Run Commands * **Ctrl/Cmd+Enter** – runs the highlighted selection or the statement around your cursor. * **Shift+Enter** – runs the current statement but keeps focus in the editor. * **Run button** – executes the active statement; click the dropdown arrow for “Run All”. * **Stop button** – cancels long-running queries. ## Semicolon-Scoped Execution Koala analyzes the SQL around your cursor: * If you highlight text, only the selection runs. * If there’s no selection, the statement between the nearest semicolons runs. * Empty lines count as boundaries, matching the VS Code extension’s behavior. ## Safety Nets * Koala warns you before running statements flagged as destructive (e.g., `DELETE` without `WHERE`) if Safety Mode is on. * Large exports paginate automatically so you don’t freeze the UI. ## Viewing Progress * The status bar shows “Running…” plus elapsed time. * Results appear in the lower pane with tabs for Grid, JSON, and Messages (including Oracle warnings). # Interface Guide Source: https://docs.btsscorp.com/kdes/query-editor/interface-guide Tour the Koala Studio editor layout ## Layout Overview 1. **Top bar** – New Tab, connection picker, Run/Stop buttons, export shortcuts, profile avatar. 2. **Tabs row** – rename, drag to reorder, duplicate using the context menu. 3. **Main Monaco editor** – syntax highlighting, minimap, gutter breakpoints, and inline error messages. 4. **Result pane** – appears after execution with tabs for Grid, JSON, or Messages. 5. **Right rail** – optional SQL history, saved queries, and tab metadata. 6. **Left explorer** – data sources browser, quick links to query history and connections. ## Customizing the View * Toggle the explorer or right rail using their icons on the left. * Drag the divider between editor and results to resize. * Switch to light/dark mode from the profile menu; Koala remembers per device. ## Tab Controls * Use the **+** button or `Ctrl/Cmd+N` to open new tabs. * `Ctrl/Cmd+W` closes the current tab. * Tabs automatically persist; when you reopen Koala, your previous tabs and their contents reload. ## Connection Picker * Located above the editor; shows the currently selected connection. * Clicking opens the dropdown with search plus any groups you’ve defined in the Connections drawer. # Keyboard Shortcuts Source: https://docs.btsscorp.com/kdes/query-editor/keyboard-shortcuts Native shortcuts available in Koala Studio Koala Studio mirrors most KDEE shortcuts so you can move between products without relearning habits. Platform-specific modifiers adjust automatically (Ctrl on Windows, Cmd on macOS). ## Core Actions * `Ctrl/Cmd+N` – New query tab * `Ctrl/Cmd+O` – Open SQL file * `Ctrl/Cmd+S` – Save SQL to a `.sql` file * `Ctrl/Cmd+W` – Close current tab ## Running & Viewing Queries * `Ctrl/Cmd+Enter` – Run selection/current statement * `Shift+Enter` – Run but keep focus in the editor * `Ctrl/Cmd+J` – Toggle results panel visibility * `Alt+F` (Option+F) – Format SQL * `Ctrl/Cmd+P` – Open Profile/Settings page * `Ctrl/Cmd+Shift+H` – Open Query History Use these shortcuts along with standard Monaco commands (find, replace, multi-caret) to stay in flow while working in the native app. # Large SQL Queries Source: https://docs.btsscorp.com/kdes/query-editor/large-sql Handle big scripts and result sets with confidence ## Editing Large Scripts * Koala streams editor state to disk so massive scripts don’t block the UI. * Use the tab history panel to split long scripts into separate tabs—duplicate the tab and delete unused sections. * Enable the “Show minimap” option to navigate quickly. ## Running Heavy Statements * Split statements with semicolons and run them one at a time to avoid hitting Oracle limits. * Keep an eye on the elapsed time indicator; click **Stop** if it exceeds your org’s timeout policy. ## Result Management * Results are paginated in 1,000-row chunks stored under `tabs/results//`. * Use the pagination controls to fetch additional pages only when needed, reducing memory use. * Exporting to CSV/XLSX streams data to disk, so you can export millions of rows without freezing the UI (disk space permitting). ## Tips * Close unused tabs to free memory—Koala persists their contents, so you can reopen them later. * For scheduled jobs, save the SQL to a `.sql` file via the editor’s **Save As** option and store it in version control. # Writing Queries Source: https://docs.btsscorp.com/kdes/query-editor/writing-queries Compose SQL efficiently in Koala Studio ## Editor Essentials * Monaco provides syntax highlighting for Oracle SQL, auto-indentation, bracket matching, and error underlining. * Use snippets and multi-caret editing (`Alt+Click` on Windows, `Option+Click` on macOS) to modify repeated clauses. * The minimap on the right helps you navigate large statements quickly; click it to jump to sections. ## Templates & History * Click the history icon to insert any recently executed query into the current tab. ## Organizing Scripts * Separate multiple statements with semicolons. Koala’s semicolon-scoped runner figures out which statement to run based on cursor position. * Add comments (`-- inline` or `/* block */`)—they’re ignored during execution and stored with history for context. ## Formatting * Press `Alt+F` (Option+F on macOS) to format the current statement using Koala’s formatter. * Adjust formatting preferences (uppercase keywords, indentation style) under **Settings → Editor**. # Excel Export Source: https://docs.btsscorp.com/kdes/results/excel-export Generate native Excel files directly from Koala Studio ## Why Excel Export? Some teams require perfectly formatted `.xlsx` files with headers, data types, and multiple sheets. Koala Studio uses the same exporter as the VS Code extension, so your downstream workflows stay consistent. ## Steps 1. Run your query. 2. Click **Export** → **Excel (.xlsx)**. 3. Choose whether to export the entire result set or just the current page. 4. Pick a save location (defaults to your OS download folder) and confirm. ## What’s Included * Column headers exactly as displayed in the grid. * Data types preserved (dates, numbers, text) when possible. * Pagination is transparent; Koala fetches all pages before writing the file. ## Tips * For multi-sheet workbooks, export each query to a separate Excel file, then merge them in Excel. * If Excel flags the file as coming from the internet, right-click → **Properties** → **Unblock** before opening on Windows. # Exporting Data Source: https://docs.btsscorp.com/kdes/results/exporting-data Download query results as CSV or JSON ## Export Options * **CSV** – great for spreadsheets or lightweight sharing. * **JSON** – preserves nested structures if your query returns JSON payloads. * Access both via the **Export** dropdown above the grid. ## Partial vs Full Exports * By default Koala exports the entire result set, fetching additional pages automatically. * Select **Export current page only** from the dropdown if you only need what’s visible. ## File Destinations * Files save to your system download folder. * Koala names files using the tab name plus a timestamp so they’re easy to track. ## Tips * Keep an eye on disk space—large exports can produce multi-gigabyte files. * Use filters or adjust your SQL if you only need a subset to reduce export time. # In-Grid Search Source: https://docs.btsscorp.com/kdes/results/in-grid-search Quickly find values within the current result page ## Quick Search * Click anywhere in the grid and press `Ctrl/Cmd+F`. * A search bar appears above the grid—type text to highlight matching cells on the current page. * Hit `Enter`/`Shift+Enter` to cycle through matches. ## Column-Specific Search * Use the filter row beneath the column headers to limit results to cells containing certain strings. * Supports partial matches by default; wrap in quotes for exact matches. ## Jump to Row * Use the row number box (bottom-left of the grid) to jump directly to a specific row index on the current page. Remember that in-grid search operates on the loaded page; navigate to other pages if the data you need is further down the result set. # Sorting & Filtering Source: https://docs.btsscorp.com/kdes/results/sorting-filtering Interact with result grids without rerunning queries ## Sorting * Click a column header to sort ascending; click again for descending; a third click clears sorting. * Multi-sort by holding `Shift` and clicking additional columns. * Sorting happens client-side, so there’s no extra round-trip to Oracle. ## Filtering * Use the inline filter row (toggle via the funnel icon) to type conditions for each column. * Text columns support contains/equals comparisons; numeric columns support equals/greater/less-than. * Clear filters with the **Reset Filters** button above the grid. ## Column Search * Press `Ctrl/Cmd+F` while focused in the grid to search the current page. * For global search across pages, rerun the query with your desired `WHERE` clauses or use the in-grid filter row to narrow results. These tools let you refine data on the fly while keeping the original query results intact. # Viewing Data Source: https://docs.btsscorp.com/kdes/results/viewing-data Navigate result sets in Koala Studio ## Grid Basics * After running a query, results appear in the lower pane’s **Grid** tab. * Columns auto-size to content; double-click a header edge to fit. * Hover to reveal tooltips for truncated text or numbers. ## Pagination * Large result sets are broken into 1,000-row pages. * Use the pagination controls in the top-right corner of the grid to move between pages without rerunning the query. ## Columns Panel * Click the column chooser icon to hide/show columns. * Drag headers to reorder columns; Koala remembers per tab. ## Messages & JSON Views * Switch to the **Messages** tab to see Oracle warnings/errors. * Choose **JSON** if your query returns JSON output or if you used the JSON export option. # Troubleshooting & Support Source: https://docs.btsscorp.com/kdes/support/troubleshooting Quick fixes and how to contact Koala ## Quick Checks * **App won’t start:** make sure you’re running the latest installer and that antivirus tools haven’t quarantined Koala. Reboot if an update just finished. * **Can’t sign in:** confirm you can reach koala.btss.dev in a browser. If you recently reset your Koala password, sign out (profile menu) and sign back in. * **SSO window doesn’t appear (Windows):** install or repair the Microsoft WebView2 runtime, then retry. ## Connection or Query Issues * Re-enter credentials or import a fresh `.kdex` file if your connection list looks empty. * If a query hangs, cancel it from the toolbar, adjust your SQL, and rerun. Clearing old result folders (see Storage page) can free disk space for large exports. * Close and reopen a tab (or duplicate it) if you suspect a tab-specific state issue; this refreshes the editor without losing your SQL. ## Update Problems * If you install a new build but the version number doesn’t change, re-run the installer as admin to ensure antivirus tools didn’t block file replacement. * Still seeing the previous version number under **About Koala Studio**? Contact support with the version listed plus the date of your last successful update. ## Talk to Support * [Open a Freshdesk ticket](https://btsscorp.freshdesk.com/support/tickets/new) and include logs/screenshot if possible. * Enterprise customers can also reach their BTSS account manager for priority help. When Support requests additional data (logs, storage folders, etc.), they’ll guide you through exporting only what’s needed. # Auto-Deployment Source: https://docs.btsscorp.com/koala/advanced/auto-deployment Learn how Koala's hash-based deployment verifies and deploys BIP catalog artifacts to Oracle Fusion Cloud. ## Overview Koala automatically deploys required BIP catalog artifacts every time you connect. It compares local assets to what exists in Oracle Fusion using content hashes and deploys only when changes are detected. Auto-deployment runs on first connection and on reconnects. No manual steps are required unless you choose to force a redeploy. ## How it works * **Hash verification**: Local artifact hash is compared to the remote hash stored in Oracle Fusion. * **Local vs remote check**: When hashes differ, Koala redeploys the updated artifact set. * **Per-connection tracking**: Hashes are stored per connection in VS Code global state, along with the last deployed version. ### Tracking & storage * **Global state**: Koala records the last deployed hash, timestamp, and package version per connection in VS Code global state. * **Storage structure**: `{ connectionId, hash, deployedAt, version }` for each environment you connect. * **Version awareness**: If the local package version changes, Koala treats it as a mismatch and redeploys even when hashes match. ### SOAP calls used Koala uses standard BIP SOAP operations during deployment: * `downloadObject` (x2) to read existing artifacts and hashes * `uploadObject` to push the updated catalog payload ### Deployment flow 1. **First connection**: Koala calculates local hashes, downloads the remote version, and uploads if they differ. 2. **Reconnect (hashes match)**: Hashes align, so no deployment is needed. 3. **Reconnect (hashes differ)**: Koala uploads the updated package and stores the new hash. ### Progress notifications * Toast notifications show deployment start, progress, and completion. * Status bar indicates when validation or upload is running. * Success and failure messages include the connection name for clarity. ## Verification & control * **Force Redeploy**: Use the Force Redeploy Catalog button in Managing Connections to run deployment regardless of hash state. * **Hash status**: The connection details panel shows the last deployed hash and timestamp. * **Activity log**: Deployment events are recorded in the output channel for review. ## Troubleshooting * **Hash mismatch errors**: Trigger a Force Redeploy to refresh remote artifacts. * **Missing artifacts**: Run Force Redeploy; Koala will re-upload the full package. * **Slow uploads**: Large catalog assets may take longer; watch the progress notification and keep VS Code open until completion. * **Verification failures**: If hash download fails, Koala retries with a fresh `downloadObject` call before prompting for redeploy. * **Audit trail**: Check the Output channel for the exact SOAP calls and hash values that were compared. After a successful redeploy, run a quick query to confirm the connection and catalog access are healthy. # Data Sources Source: https://docs.btsscorp.com/koala/advanced/data-sources Explore Oracle Fusion Cloud data sources and schemas ## Overview The Data Sources explorer in Koala Data Explorer Extension provides a view of your Oracle Fusion Cloud database structure. This feature helps you discover tables, views, and understand the available data. Data Sources explorer is available in the paid version of Koala Data Explorer. ## Accessing Data Sources ### Opening the Explorer Access the Data Sources explorer: 1. Click the Koala icon in VS Code Activity Bar 2. Expand the "Data Sources" section 3. Explorer appears in the sidebar showing your schema structure ### Auto-refresh The explorer automatically refreshes when you connect to a database, loading the available schemas, tables, and views. ## Schema Structure ### What You'll See The explorer shows: ``` 📁 Connection Name ├── 📊 Schema1 │ ├── 📋 Tables │ │ ├── EMPLOYEES │ │ ├── DEPARTMENTS │ │ └── JOBS │ └── 👁️ Views │ ├── EMP_DETAILS_VIEW │ └── DEPARTMENT_VIEW └── 📊 Schema2 ``` ### Schema Information For each schema you can see: * **Schema name**: Database schema identifier * **Tables**: Regular database tables * **Views**: Database views and materialized views * **Object count**: Number of objects in each category ## Exploring Tables and Views ### Table Information When you expand a table, you can see: * **Table name**: Database table name * **Basic structure**: Available for browsing ### Quick Actions Right-click on any table or view for options: * **Generate SELECT**: Creates a basic SELECT statement * **Copy Name**: Copies table/view name to clipboard ### Drag and Drop You can drag table names from the explorer directly into your query editor to quickly add them to your SQL. ## Search Functionality ### Finding Objects Use the search box in the Data Sources panel to: * Search for table names * Find views by name * Locate specific database objects quickly The search is case-insensitive and searches across all visible schemas. ## Working with Schemas ### Available Schemas The explorer shows schemas that: * You have access to query * Contain tables or views you can SELECT from * Are part of your Oracle Fusion environment ### Schema Access Only schemas and objects you have SELECT permissions for will appear in the explorer. This respects your database security settings. ## Favorites ### Bookmark Important Tables Mark frequently used tables as favorites: 1. Right-click on a table 2. Select "Add to Favorites" 3. Favorites appear at the top for quick access This helps you quickly find the tables you use most often. ## Performance and Refreshing ### Auto-refresh Settings The Data Sources explorer can be configured to: * Automatically refresh when connecting * Update schema information periodically * Refresh manually when needed ### Manual Refresh To manually refresh the schema information: 1. Right-click in the Data Sources panel 2. Select "Refresh" 3. Schema information updates with current database state ## Troubleshooting ### Schema Not Showing If expected schemas don't appear: 1. **Check permissions**: Ensure you have SELECT access 2. **Verify connection**: Confirm you're connected to the right instance 3. **Refresh manually**: Try refreshing the data sources 4. **Contact DBA**: May need additional database permissions ### Slow Loading If the Data Sources panel loads slowly: 1. **Network latency**: Check connection to Oracle Fusion 2. **Large schemas**: Many objects can slow loading 3. **Permissions**: Complex permission structures may impact performance ## Best Practices ### Organization To make the most of Data Sources: 1. **Use favorites**: Bookmark your most-used tables 2. **Descriptive queries**: Use the generated SELECT as starting points 3. **Explore gradually**: Start with familiar schemas ### Security Remember that: * Only accessible objects are shown * Respect data sensitivity * Follow your organization's data access policies ## Integration with Queries ### Generated SQL When you use "Generate SELECT" from the context menu: * Basic SELECT statement is created * Includes ROWNUM limit for safety * Ready to execute or modify ### Query Building Use the Data Sources explorer to: 1. **Discover tables**: Find relevant data sources 2. **Build joins**: Identify related tables 3. **Understand structure**: See what data is available ## Settings ### Configure Data Sources You can configure the Data Sources behavior through VS Code settings: ```json theme={null} { "koalaDataExplorer.autoRefreshDataSources": true, "koalaDataExplorer.maxRows": 1000 } ``` ## Limitations ### Current Limitations The Data Sources explorer: * Shows basic schema structure * Provides table and view browsing * Offers simple search functionality * Includes favorites management ### Future Enhancements Planned improvements include: * Column details view * Relationship information * Enhanced search capabilities * Additional metadata display ## Next Steps Start writing SQL queries Manage your query history # Multiple Tabs Source: https://docs.btsscorp.com/koala/advanced/multiple-tabs Work with multiple query tabs for efficient development ## Overview Koala Data Explorer Extension supports multiple query tabs, allowing you to work on several SQL queries simultaneously. This feature improves productivity by letting you switch between different queries without losing your work. Multiple tabs are available in the paid version of Koala Data Explorer. The free version supports only one active tab. ## Working with Tabs ### Creating New Tabs Create additional query tabs by clicking the **+** button in the tab bar. Each new tab provides a fresh query editor with its own: * SQL editor space * Independent connection (can connect to different databases) * Results area * Execution context ### Tab Navigation Switch between tabs by: * **Click tabs**: Click on any tab name to switch to it * **Tab indicators**: Visual cues show tab status ### Tab Management Manage your open tabs: * **Close tabs**: Click the "×" on any tab * **Tab titles**: Tabs show query content preview or file names * **Unsaved changes**: Indicated by a dot (●) in tab title ### Tab isolation and switching * Each tab runs queries in its own execution context; cancelling one tab does not stop others. * You can switch tabs while a query runs in the background, then return to monitor progress or cancel. * Tabs remember their active connection and results independently. ## Tab Features ### Independent Contexts Each tab maintains its own: * **Query content**: Separate SQL editor with independent content * **Connection**: Each tab can connect to different databases or use different connections * **Results display**: Separate results panel showing results only for that tab's queries * **File association**: Tabs can be linked to saved .sql files ### File explorer integration * Right-click a file-backed tab and choose **Reveal in Explorer** to open its folder. * Hover over a tab title to see the full file name and path. * Improved tab sizing keeps more of the file name visible when many tabs are open. ### Tab States Visual indicators show tab status: * **Clean tabs**: No unsaved changes * **Modified tabs**: Dot (●) indicator for unsaved changes * **File path**: Tab title shows file path when query is saved ## Productivity Features Multiple tabs enable efficient workflow: 1. **Compare results**: Run different queries and compare results side-by-side 2. **Reference data**: Keep lookup queries open in separate tabs 3. **Multi-environment work**: Connect different tabs to different Oracle Fusion environments 4. **Organized development**: Separate complex analysis into multiple focused queries ## Best Practices ### Effective Tab Usage 1. **Organize by purpose**: Use different tabs for different types of queries 2. **Save frequently**: Use `Ctrl+S` / `Cmd+S` to save your work in each tab 3. **Close when finished**: Click the × to close tabs you no longer need 4. **Use descriptive content**: Start queries with meaningful SQL comments so tab titles are clear ### Multi-Environment Workflow * **Production queries**: Keep production environment queries in one tab * **Development testing**: Use separate tabs for development environment * **Reference queries**: Maintain lookup or reference queries in dedicated tabs * **Comparison analysis**: Use multiple tabs to compare different approaches to the same problem ## File Management with Tabs ### Saving Tab Content * **Save individual tabs**: Each tab can be saved as a separate .sql file * **File associations**: When saved, the tab title shows the file path * **Drag and drop**: Open existing .sql files by dragging them into the editor (creates new tabs) ### Tab Indicators * **Dot (●)**: Indicates unsaved changes in the tab * **File path**: Shows in tab title when query is saved to file * **Query preview**: Shows first line of SQL content when not saved to file ## Next Steps Configure query timeout settings Customize Koala settings # Performance Monitor Source: https://docs.btsscorp.com/koala/advanced/performance-monitor Monitor query execution performance and timing ## Overview Koala Data Explorer Extension includes performance monitoring features to help you track query execution times and optimize your SQL performance. This helps identify slow queries and improve overall database interaction efficiency. Performance monitoring is available in the paid version of Koala Data Explorer. ## Performance Tracking ### Execution Timing Every query execution is automatically timed: * **Start time**: When query execution begins * **End time**: When results are received * **Total duration**: Complete execution time * **Network latency**: Time spent in network communication ### Performance Display Performance information appears in: * **Results panel**: Execution time shown below results * **Status bar**: Quick timing information * **History entries**: Performance data saved with each query ## Timing Information ### What's Measured Performance monitoring tracks: * **Query execution**: Actual SQL processing time on Oracle server * **Data transfer**: Time to receive results over network * **Parsing time**: Time to process query results * **Total time**: End-to-end execution duration ### Time Formats Timing displayed in appropriate units: * **Milliseconds**: For fast queries (\< 1 second) * **Seconds**: For normal queries (1-60 seconds) * **Minutes**: For long-running queries (> 60 seconds) ## Performance Indicators ### Visual Feedback Performance feedback includes: * **Green indicators**: Fast queries (\< 5 seconds) * **Yellow indicators**: Moderate queries (5-30 seconds) * **Red indicators**: Slow queries (> 30 seconds) * **Progress bars**: For long-running queries ### Performance Warnings Automatic warnings for: * **Timeout approaching**: When query nears timeout limit * **Very slow queries**: Queries taking longer than expected * **Large result sets**: When returning many rows * **Network issues**: Slow network response times ## Query Optimization ### Performance Insights Koala provides basic optimization guidance: #### Common Issues * **Missing row limits**: Queries without ROWNUM or LIMIT * \*\*SELECT \*\*\*: Selecting all columns unnecessarily * **Large result sets**: Queries returning many rows * **Complex joins**: Multiple table joins #### Optimization Suggestions * **Add row limits**: Use `WHERE ROWNUM <= 1000` * **Select specific columns**: Avoid `SELECT *` * **Use indexes**: Filter on indexed columns * **Reduce data volume**: Apply WHERE clauses ### Performance Best Practices Improve query performance: 1. **Limit result sets**: Always use row limits for exploration 2. **Specific columns**: Select only needed columns 3. **Efficient filters**: Use indexed columns in WHERE clauses 4. **Avoid functions**: Don't use functions on indexed columns ## Performance History ### Historical Tracking Performance data is maintained in: * **Query history**: Each execution includes timing * **Performance trends**: Track improvements/degradation over time * **Comparison data**: Compare similar queries ### Performance Analysis Review performance patterns: * **Query comparison**: Compare different versions of same query * **Time trends**: See if queries are getting slower * **Optimization results**: Measure improvement after changes ## Monitoring Features ### Real-time Monitoring During query execution: * **Progress indicators**: Visual feedback for long queries * **Elapsed time**: Running timer * **Cancel option**: Stop slow queries if needed * **Estimated completion**: Time estimates for large queries ### Performance Alerts Automatic notifications for: * **Slow query detection**: Queries exceeding normal times * **Timeout warnings**: Approaching configured timeout * **Performance degradation**: Queries slower than usual * **Resource usage**: High memory or CPU usage ## Configuration ### Performance Settings Configure monitoring through VS Code settings: ```json theme={null} { "koalaDataExplorer.performance.trackTiming": true, "koalaDataExplorer.performance.slowQueryThreshold": 30000, "koalaDataExplorer.performance.showWarnings": true, "koalaDataExplorer.timeout": 120000 } ``` ### Threshold Settings Customize performance thresholds: * **Fast query**: Under 5 seconds * **Normal query**: 5-30 seconds * **Slow query**: Over 30 seconds * **Timeout limit**: Maximum execution time ## Performance Tips ### Database-Side Optimization Improve Oracle Fusion performance: 1. **Use appropriate indexes**: Ensure filtered columns are indexed 2. **Optimize joins**: Use efficient join strategies 3. **Partition awareness**: Use partition elimination 4. **Statistics currency**: Ensure optimizer statistics are current ### Client-Side Optimization Improve Koala performance: 1. **Reduce row limits**: Don't fetch unnecessary data 2. **Column selection**: Select only needed columns 3. **Connection efficiency**: Use stable network connections 4. **Result processing**: Limit result set size ## Troubleshooting Performance ### Slow Queries If queries are running slowly: 1. **Check execution plan**: Look for full table scans 2. **Review filters**: Ensure WHERE clauses use indexes 3. **Reduce scope**: Add more restrictive conditions 4. **Network check**: Verify connection quality ### Network Issues For network-related slowness: 1. **Connection stability**: Check VPN or network connectivity 2. **Latency testing**: Test connection to Oracle Fusion 3. **Bandwidth**: Ensure adequate network bandwidth 4. **Timeout settings**: Adjust timeout values if needed ### Memory Issues For memory-related performance: 1. **Result size**: Limit rows returned 2. **Column count**: Reduce number of columns 3. **Data types**: Large text fields can impact performance 4. **VS Code memory**: Monitor VS Code memory usage ## Performance Reporting ### Basic Metrics Standard performance information: * **Average execution time**: For repeated queries * **Fastest/slowest**: Performance ranges * **Success rate**: Percentage of successful executions * **Common patterns**: Frequently executed query types ### Performance Comparison Compare query performance: * **Before/after optimization**: Measure improvements * **Different approaches**: Compare alternative queries * **Historical trends**: Track performance over time * **Connection differences**: Compare performance across environments ## Integration with Other Features ### History Integration Performance data in history: * **Query history includes timing**: All executions tracked * **Performance search**: Find slow queries in history * **Optimization tracking**: Compare query versions ### Export Integration Performance data in exports: * **Metadata inclusion**: Export timing information * **Performance reports**: Generate performance summaries * **Analysis data**: Export for further analysis ## Limitations ### Current Limitations Performance monitoring: * **Basic timing**: Execution time measurement * **Simple thresholds**: Basic fast/slow categorization * **Manual optimization**: User-driven performance improvements * **Client-side focus**: Limited server-side analysis ### Future Enhancements Planned improvements: * **Detailed execution plans**: Query plan analysis * **Performance recommendations**: Automated suggestions * **Historical analysis**: Long-term performance trends * **Comparative analysis**: Benchmark against similar queries ## Next Steps Work with multiple query tabs Learn query optimization techniques # SQL History Source: https://docs.btsscorp.com/koala/advanced/sql-history Track and reuse your query history in Koala Data Explorer ## Overview Koala Data Explorer Extension automatically tracks your query history, allowing you to easily recall and reuse previously executed SQL statements. This feature helps you build on previous work and maintain a record of your database interactions. ## Accessing Query History ### Open History Panel Access your query history: 1. Press `Ctrl+H` (Windows/Linux) or `Cmd+H` (Mac) 2. Or click the History icon in the toolbar 3. History panel opens showing recent queries ### History Location Query history appears in: * **Dedicated history panel**: Full query text and execution details * **Quick access**: Recent queries in dropdown menus * **Search functionality**: Find specific queries ## History Features ### What's Stored Each history entry includes: * **Complete SQL text**: Full query as executed * **Execution timestamp**: When the query was run * **Execution time**: How long the query took * **Row count**: Number of rows returned * **Connection used**: Which database connection * **Success/failure status**: Whether query completed successfully ### History Limits Query history storage limits: * **Free version**: Last 50 executed queries * **Paid version**: Last 500 executed queries Older queries are automatically removed when limits are reached. ## Using History ### Recall Previous Queries To reuse a query from history: 1. Open the history panel (`Ctrl+H`) 2. Browse through your previous queries 3. Click on any query to load it into the editor 4. Modify as needed and execute ### History Search Find specific queries: * Type in the search box to filter by query content * Search looks through SQL text and table names * Results update as you type ### Quick Navigation Navigate through history: * **Most recent first**: Newest queries at the top * **Chronological order**: Easy to find recent work * **Date grouping**: Queries grouped by day (paid version) ## History Management ### Automatic Cleanup History is automatically managed: * **Persistent storage**: Survives VS Code restarts * **Automatic pruning**: Old queries removed when limit reached * **Error handling**: Failed queries also stored for reference ### Manual Management You can manually manage history: * **Clear all history**: Remove all stored queries * **Delete specific entries**: Remove individual queries * **Export history**: Save queries to file (paid version) ## Working with History Entries ### Query Details Each history entry shows: * **SQL preview**: First few lines of the query * **Timestamp**: Exact execution time * **Performance**: Execution duration * **Results**: Row count or error message ### Context Actions Right-click on history entries for options: * **Load query**: Copy to current editor * **Copy SQL**: Copy query text to clipboard * **Delete entry**: Remove from history * **View details**: See full execution information ## Search and Filter ### Search Functionality Find queries quickly: * **Text search**: Search within SQL content * **Table search**: Find queries using specific tables * **Date range**: Filter by execution date (paid version) ### Filter Options Filter history by: * **Success/failure**: Show only successful or failed queries * **Connection**: Queries from specific databases * **Date range**: Recent queries or specific time periods ## Best Practices ### Organizing Queries Make the most of query history: 1. **Use descriptive comments**: Add comments to important queries 2. **Test queries first**: Build up complex queries incrementally 3. **Save important queries**: Copy critical queries to files 4. **Regular cleanup**: Clear history periodically if needed ### Development Workflow Effective use of history: 1. **Iterative development**: Build on previous query attempts 2. **Error learning**: Review failed queries to avoid mistakes 3. **Pattern reuse**: Find similar queries for new requirements 4. **Performance comparison**: Compare execution times ## History Settings ### Configuration Options Configure history behavior through VS Code settings: ```json theme={null} { "koalaDataExplorer.history.maxEntries": 50, "koalaDataExplorer.history.searchEnabled": true, "koalaDataExplorer.history.groupByDate": false } ``` ### Privacy Settings Control what's stored: * **Query text**: Full SQL statements * **Parameter values**: Bind variable values (if any) * **Results metadata**: Row counts and timing * **Error details**: Failure reasons ## Integration Features ### Parameter History For queries with bind variables: * **Parameter values**: Previous values remembered * **Parameter suggestions**: Auto-suggest based on history * **Parameter patterns**: Common value combinations ### Export Integration History works with exports: * **Export queries**: Save history entries to files * **Import patterns**: Use history for new query development * **Documentation**: Generate query documentation from history ## Troubleshooting ### History Not Saving If history isn't working: 1. **Check settings**: Verify history is enabled 2. **Storage permissions**: Ensure VS Code can write to workspace 3. **Memory limits**: Check if storage quota exceeded 4. **Restart extension**: Reload Koala Data Explorer ### Performance Issues If history is slow: 1. **Large history**: Clear old entries 2. **Complex queries**: Large SQL statements may slow search 3. **Search optimization**: Use specific search terms 4. **Limit results**: Reduce history display size ### Missing Queries If queries don't appear in history: 1. **Execution status**: Only completed executions are stored 2. **Connection issues**: Failed connections may not save 3. **Storage errors**: Check for storage problems 4. **Manual execution**: Only manual queries stored (not automated) ## Keyboard Shortcuts ### History Navigation | Action | Shortcut | Description | | -------------- | -------------- | ----------------------- | | Open History | `Ctrl+H` | Open history panel | | Search History | `Ctrl+Shift+H` | Focus on history search | | Previous Query | `Alt+Up` | Load previous query | | Next Query | `Alt+Down` | Load next query | ### Quick Actions | Action | Shortcut | Description | | ----------------- | ------------ | ---------------------- | | Load from History | `Ctrl+Click` | Load query into editor | | Copy Query | `Ctrl+C` | Copy query text | | Clear History | `Ctrl+Del` | Clear all history | ## Future Enhancements ### Planned Features Upcoming history improvements: * **Query tagging**: Label important queries * **History sync**: Share history across installations * **Advanced search**: More sophisticated filtering * **Query analytics**: Usage patterns and insights ## Next Steps Monitor query performance Work with multiple query tabs # Extension Settings Source: https://docs.btsscorp.com/koala/config/extension-settings Configure Koala Data Explorer to match your workflow ## Accessing Settings ### Via VS Code Settings 1. Open VS Code Settings: * Windows/Linux: `Ctrl+,` * Mac: `Cmd+,` 2. Search for "Koala" 3. Modify settings as needed ### Via Settings JSON 1. Open Command Palette (`Ctrl+Shift+P`) 2. Type: "Preferences: Open Settings (JSON)" 3. Add Koala settings ## Core Settings ### Query Execution ```json theme={null} { // Request timeout in milliseconds (default: 120000 = 2 minutes) "koalaDataExplorer.timeout": 120000, // Maximum rows to return (default: 1000) // Note: Locked to 50 in free mode "koalaDataExplorer.maxRows": 1000, // Auto-refresh data sources on connection "koalaDataExplorer.autoRefreshDataSources": true } ``` Max Rows applies a server-side `ROWNUM` restriction to every query, even when additional WHERE filters are present. **UI change**: The Max Rows control is now a dropdown with presets `10, 50, 100, 500, 1000, 2500, 5000` plus an **Unlimited** checkbox for larger result sets (paid). The free tier remains capped at 50 rows even when higher values are selected. ### Timeout Configuration Adjust timeout for different scenarios: ```json theme={null} { // Quick queries (30 seconds) "koalaDataExplorer.timeout": 30000, // Standard queries (2 minutes) "koalaDataExplorer.timeout": 120000, // Complex queries (5 minutes) "koalaDataExplorer.timeout": 300000, // Very long queries (10 minutes) "koalaDataExplorer.timeout": 600000 } ``` Longer timeouts may cause VS Code to become unresponsive. Use scheduled reports for very long-running queries. ## Logging Settings ### Enable Logging ```json theme={null} { // Enable debug logging "koalaDataExplorer.logging.enabled": true, // Set logging level "koalaDataExplorer.logging.level": "INFO", // Maximum log entries to keep "koalaDataExplorer.logging.maxLogs": 1000 } ``` ### Logging Levels | Level | Description | Use Case | | ------- | ------------------- | --------------- | | `ERROR` | Only errors | Production use | | `WARN` | Warnings and errors | Normal use | | `INFO` | General information | Default | | `DEBUG` | Detailed debugging | Troubleshooting | ### View Logs 1. Open Command Palette 2. Type: "Koala: View Logs" 3. Review log entries in the panel ## Scheduled Report Settings For large dataset processing: ```json theme={null} { // Maximum wait time for scheduled reports (15 minutes) "koalaDataExplorer.scheduleReport.maxPollTime": 900000, // Download chunk size in KB (50MB) "koalaDataExplorer.scheduleReport.chunkSizeKB": 50000, // Enable for large datasets "koalaDataExplorer.scheduleReport.enableForLargeDatasets": true } ``` ## SQL History Settings ```json theme={null} { // Maximum SQL history entries (default: 500) // Note: Limited to 50 in free mode "koalaDataExplorer.sqlHistory.maxEntries": 500 } ``` ## Performance Settings ### Memory Management For large result sets: ```json theme={null} { // Limit rows for better performance "koalaDataExplorer.maxRows": 500, // Disable auto-refresh for slow connections "koalaDataExplorer.autoRefreshDataSources": false } ``` ### Network Optimization ```json theme={null} { // Shorter timeout for fast networks "koalaDataExplorer.timeout": 60000, // Smaller chunks for slow connections "koalaDataExplorer.scheduleReport.chunkSizeKB": 10000 } ``` ## Development Settings ### Testing and QA ```json theme={null} { // Force free mode for testing "koalaDataExplorer.license.forceFreeMode": true, // Enable verbose logging "koalaDataExplorer.logging.enabled": true, "koalaDataExplorer.logging.level": "DEBUG" } ``` ## Workspace vs User Settings ### User Settings (Global) Applied to all VS Code projects: ```json theme={null} // ~/.config/Code/User/settings.json { "koalaDataExplorer.timeout": 120000, "koalaDataExplorer.logging.enabled": false } ``` ### Workspace Settings (Project) Applied only to current project: ```json theme={null} // .vscode/settings.json { "koalaDataExplorer.maxRows": 5000, "koalaDataExplorer.autoRefreshDataSources": false } ``` Workspace settings override user settings for the current project. ## Environment-Specific Configuration ### Development Environment ```json theme={null} { "koalaDataExplorer.timeout": 300000, "koalaDataExplorer.maxRows": 10000, "koalaDataExplorer.logging.enabled": true, "koalaDataExplorer.logging.level": "DEBUG" } ``` ### Production Environment ```json theme={null} { "koalaDataExplorer.timeout": 120000, "koalaDataExplorer.maxRows": 1000, "koalaDataExplorer.logging.enabled": false, "koalaDataExplorer.autoRefreshDataSources": true } ``` ## Proxy Configuration For corporate networks: ```json theme={null} { // Proxy server URL "http.proxy": "http://proxy.company.com:8080", // Disable SSL verification (development only) "http.proxyStrictSSL": false, // Proxy authentication "http.proxyAuthorization": null } ``` ## Reset to Defaults ### Reset All Settings 1. Open Command Palette 2. Type: "Preferences: Open Settings (JSON)" 3. Remove all `koalaDataExplorer.*` entries 4. Reload VS Code ### Default Values ```json theme={null} { "koalaDataExplorer.timeout": 120000, "koalaDataExplorer.maxRows": 1000, "koalaDataExplorer.autoRefreshDataSources": true, "koalaDataExplorer.logging.enabled": false, "koalaDataExplorer.logging.level": "INFO", "koalaDataExplorer.logging.maxLogs": 1000, "koalaDataExplorer.scheduleReport.maxPollTime": 900000, "koalaDataExplorer.scheduleReport.chunkSizeKB": 50000, "koalaDataExplorer.scheduleReport.enableForLargeDatasets": true, "koalaDataExplorer.sqlHistory.maxEntries": 500, "koalaDataExplorer.license.forceFreeMode": false } ``` ## Troubleshooting Settings ### Settings Not Applied 1. Check for syntax errors in settings.json 2. Reload VS Code window (`Ctrl+R`) 3. Verify setting names are correct 4. Check workspace vs user settings ### Performance Issues If extension is slow: ```json theme={null} { "koalaDataExplorer.maxRows": 100, "koalaDataExplorer.autoRefreshDataSources": false, "koalaDataExplorer.logging.enabled": false } ``` ### Connection Problems For connection issues: ```json theme={null} { "koalaDataExplorer.timeout": 180000, "http.proxyStrictSSL": false, "koalaDataExplorer.logging.enabled": true, "koalaDataExplorer.logging.level": "DEBUG" } ``` ## Settings Priority Settings are applied in this order (highest priority first): 1. Workspace settings (`.vscode/settings.json`) 2. User settings (`~/.config/Code/User/settings.json`) 3. Default settings (extension defaults) ## Export/Import Settings ### Export Settings ```bash theme={null} # Copy settings to share with team cp ~/.config/Code/User/settings.json ./koala-settings-backup.json ``` ### Import Settings ```bash theme={null} # Import settings from backup cp ./koala-settings-backup.json ~/.config/Code/User/settings.json ``` ## Next Steps Configure timeouts for your network Set up logging for debugging Configure your first connection Resolve configuration issues # Logging & Diagnostics Source: https://docs.btsscorp.com/koala/config/logging Enable diagnostic logging for troubleshooting and support ## Overview When you encounter issues with Koala Data Explorer Extension, enabling diagnostic logs helps identify problems and collect information for support. The extension includes a built-in log viewer for easy troubleshooting. Logging may impact performance and should be disabled when not troubleshooting. ## Quick Start - Log Viewer **🎯 Easiest Method:** 1. **Enable logging** in VS Code settings (see below) 2. **Open Koala Data Explorer** 3. **Click the "Show Debug Logs" button** 📊 in the top toolbar 4. **Reproduce the problem** while watching the logs The built-in log viewer provides: * Real-time updates as events happen * Professional interface with timestamps * Export to file for support tickets * Clear logs to focus on current issues ## When to Enable Logging Enable logging when experiencing: * **Connection Issues**: Authentication failures, timeouts * **Query Problems**: Execution errors, syntax issues * **Data Issues**: Missing data sources, export problems * **Performance Issues**: Slow queries, freezing * **General Issues**: Extension crashes, unexpected behavior ## How to Enable Logging ### Step 1: Enable in Settings 1. **Open VS Code Settings**: * Press `Ctrl+,` (Windows/Linux) or `Cmd+,` (Mac) * Or go to **File** → **Preferences** → **Settings** 2. **Search for "Koala Data Explorer Logging"** 3. **Configure settings**: * ✅ Check **"Koala Data Explorer: Logging: Enabled"** * 📊 Set **"Koala Data Explorer: Logging: Level"** to **"DEBUG"** ### Step 2: Use Log Viewer 1. **Open Koala Data Explorer** 2. **Click "Show Debug Logs" button** 📊 in toolbar 3. **Log viewer panel opens** showing real-time information 4. **Reproduce the issue** while monitoring logs ## What to Look For ### Connection Issues Look for entries containing: * `[CONNECTION_MANAGER] Connection failed` * `[AUTH] Authentication error` * HTTP error codes: `401`, `403`, `500` * Network timeout messages ### Query Execution Problems Look for entries containing: * `[QUERY_EXECUTION] Query failed` * `[BIP_SERVICE] SOAP error` * SQL syntax error messages * Permission denied errors ### Error Indicators * **ERROR level** entries (red text) * **WARN level** entries (yellow text) * Stack traces showing detailed error information * HTTP status codes indicating problems ## Log Levels * **ERROR**: Critical problems preventing functionality * **WARN**: Issues that might cause problems but don't stop operation * **INFO**: General information about extension operations * **DEBUG**: Detailed diagnostic information (recommended for troubleshooting) ## Collecting Logs for Support ### Using the Log Viewer 1. **Enable logging** and reproduce the problem 2. **In the log viewer panel**: * Click **"Export Logs"** to save to file * Or select and copy relevant log entries 3. **Attach exported file** to support email ### Support Information When contacting [support](https://btsscorp.freshdesk.com/support/tickets/new), include: * **What you were trying to do** (step-by-step) * **What happened** (exact error message or behavior) * **When it started** (after update, always happening, etc.) * **Connection type** (Basic Auth, OAuth PKCE, Windows SSO) * **Environment** (Oracle Fusion instance details if known) * **Exported log file** from the log viewer ## Advanced Log Access ### Extension Host Logs For power users who need direct access: 1. Press `Ctrl+Shift+P` / `Cmd+Shift+P` 2. Type "Developer: Show Logs" 3. Select **"Extension Host"** 4. Look for entries starting with `[KOALA]` ### Browser Console (UI Issues) For webview-related problems: 1. With Koala open, press `F12` 2. Go to **Console** tab 3. Set filter to **Verbose** 4. Look for `[UI]`, `[STATE]`, `[BACKEND_MSG]` entries ## Common Error Messages | Error Message | Meaning | Solution | | ----------------------- | ----------------------------- | ------------------------------------- | | "BIP catalog not found" | Required Oracle setup missing | Click "Deploy to BIP" button | | "Authentication failed" | Invalid credentials | Check username/password in connection | | "Connection timeout" | Network or server issue | Check VPN, firewall, try again later | | "Invalid SQL syntax" | Query syntax error | Review SQL in editor | | "Permission denied" | No data access | Contact Oracle admin for permissions | | "Token expired" | OAuth token needs refresh | Disconnect and reconnect | | "Row limit exceeded" | Too much data returned | Add ROWNUM or WHERE limits | ## Performance Considerations ### Disable When Finished **Remember to disable logging** after troubleshooting: 1. Go to **VS Code Settings** 2. Search for **"Koala Data Explorer Logging"** 3. **Uncheck** "Koala Data Explorer: Logging: Enabled" 4. This improves performance and reduces resource usage ### Impact on Extension * **Debug logging**: Detailed information, higher performance impact * **Info logging**: General information, moderate impact * **Error logging**: Only critical issues, minimal impact * **Disabled**: Best performance for daily use ## Getting Help ### Self-Service Steps 1. **Use the log viewer** - easiest way to see what's happening 2. **Check common error messages** table above 3. **Try basic troubleshooting** (restart VS Code, check connection) ### Contact Support If you need help: 1. **Export logs** using built-in export feature 2. **Submit ticket** at [support portal](https://btsscorp.freshdesk.com/support/tickets/new) 3. **Include logs** and detailed problem description 4. **Response time**: Typically 1-2 business days ## Next Steps Configure other extension settings Troubleshoot connection problems # Performance Settings Source: https://docs.btsscorp.com/koala/config/performance Tune Koala for faster query execution and efficient resource use ## Overview Optimize execution speed, memory, and network efficiency with a few targeted settings. ## Recommended settings ```json theme={null} { "koalaDataExplorer.maxRows": 1000, "koalaDataExplorer.timeout": 120000, "koala.execution.fetchSize": 200, "koala.execution.stopOnError": true } ``` * **Max Rows**: Applies a ROWNUM guard server-side to prevent runaway result sets. * **Timeout**: Stops long-running requests that exceed your SLA. * **Fetch size**: Balances memory and network calls when streaming results. ## Execution optimizations * **Query cancellation**: Stops work at the tab level while other tabs keep running. * **Chunked uploads**: Large SQL is compressed and chunked to reduce SOAP payload size. * **Streaming results**: Fetch size tuning keeps memory flat even on wide datasets. * **Network efficiency**: Gzip is applied automatically for medium/large SQL payloads. ## Benchmarks * Compression reduces large SQL payload size by \~60% on average. * Tab isolation keeps memory stable when multiple queries run concurrently. * Auto column width and virtual scrolling reduce render time for wide datasets. * Background execution keeps the editor responsive while long queries stream results. ### Before/after examples * **SQL payloads**: 240 KB uncompressed → \~90 KB compressed (62% reduction). * **Multi-tab memory**: 3 concurrent tabs leveled at the same memory footprint as a single tab after streaming. * **Export speed**: Unlimited Excel export completes in roughly the same time as CSV when `fetchSize` is set between 200–500. ## Optimization tips * Prefer targeted column lists instead of `SELECT *`. * Apply WHERE filters early; ROWNUM limits are enforced even with filters present. * Use bind variables to improve plan reuse. ### Real-world configurations ```json theme={null} { "koalaDataExplorer.maxRows": 5000, // guardrail for busy tenants "koalaDataExplorer.timeout": 180000, // 3-minute ceiling for ad-hoc work "koala.execution.fetchSize": 300, // balanced streaming "koalaDataExplorer.logging.level": "INFO" // keep logs light in production } ``` Set a lower `maxRows` in shared environments, then temporarily raise it for exports to keep memory and network usage predictable. # Timeout Settings Source: https://docs.btsscorp.com/koala/config/timeout-settings Configure query timeout and connection settings ## Overview Koala Data Explorer Extension provides configurable timeout settings to control how long queries can run before being cancelled. This helps prevent runaway queries and manage system resources effectively. ## Timeout Configuration ### Default Timeout The default query timeout is: * **120 seconds (2 minutes)**: Standard timeout for most queries * **Configurable**: Can be adjusted based on your needs * **Per-connection**: Can be set differently for different environments ### Setting Timeout Values Configure timeout through VS Code settings: ```json theme={null} { "koalaDataExplorer.timeout": 120000 } ``` Timeout value is specified in milliseconds: * `30000` = 30 seconds * `120000` = 2 minutes (default) * `300000` = 5 minutes ## Timeout Types ### Query Execution Timeout Controls how long queries can run: * **Execution time**: Maximum time for SQL execution * **Automatic cancellation**: Queries stopped when timeout reached * **User notification**: Warning when timeout occurs * **Resource protection**: Prevents long-running queries ### Connection Timeout Controls connection establishment: * **Connection time**: Maximum time to establish database connection * **Network issues**: Handles slow network responses * **Authentication delays**: Accounts for slow authentication * **Retry logic**: Automatic retry for temporary issues ## Configuring Timeouts ### VS Code Settings Access timeout settings: 1. Open VS Code Settings (`Ctrl+,`) 2. Search for "koala" 3. Find "Koala Data Explorer: Timeout" 4. Set desired value in milliseconds ### Settings File Direct settings.json configuration: ```json theme={null} { "koalaDataExplorer.timeout": 180000, "koalaDataExplorer.connectionTimeout": 30000 } ``` ### Per-Environment Settings Different timeouts for different environments: ```json theme={null} { "koalaDataExplorer.timeout": 120000, "koalaDataExplorer.environments": { "production": { "timeout": 60000 }, "development": { "timeout": 300000 } } } ``` ## Timeout Behavior ### When Timeout Occurs When a query times out: 1. **Query cancellation**: SQL execution is stopped 2. **Error message**: Timeout error displayed 3. **Connection preservation**: Database connection remains active 4. **Partial results**: Any received data is discarded ### Warning Notifications Before timeout occurs: * **Progress indication**: Shows query is still running * **Time elapsed**: Displays current execution time * **Cancel option**: Manual cancellation available * **Timeout warning**: Alert when approaching timeout ## Timeout Strategies ### Short Timeouts (30-60 seconds) Good for: * **Interactive queries**: Quick data exploration * **Production environments**: Prevent resource overload * **Testing queries**: Fast feedback during development * **Shared systems**: Avoid impacting other users ### Medium Timeouts (2-5 minutes) Good for: * **Complex queries**: Multi-table joins and aggregations * **Development work**: Building and testing complex SQL * **Data analysis**: Reasonable time for analysis queries * **General use**: Balanced approach for most scenarios ### Long Timeouts (5+ minutes) Good for: * **Reports**: Complex reporting queries * **Data migration**: Large data processing * **Analytics**: Deep data analysis * **Batch processing**: Scheduled or background queries ## Managing Long-Running Queries ### Query Optimization Instead of increasing timeouts: 1. **Add row limits**: Use `ROWNUM <= 1000` 2. **Optimize filters**: Use indexed columns 3. **Reduce scope**: Filter data more specifically 4. **Check execution plan**: Look for performance issues ### Alternative Approaches For very long queries: * **BIP Integration**: Use Oracle BIP for large reports * **Scheduled execution**: Run during off-peak hours * **Incremental processing**: Break into smaller chunks * **Asynchronous processing**: Use Oracle's async capabilities ## Timeout Troubleshooting ### Frequent Timeouts If queries often timeout: 1. **Review query complexity**: Check for performance issues 2. **Network connectivity**: Verify stable connection 3. **Server performance**: Check Oracle Fusion performance 4. **Resource contention**: Avoid peak usage times ### Timeout Too Short If legitimate queries are timing out: 1. **Increase timeout**: Adjust timeout setting 2. **Optimize query**: Improve query performance 3. **Environment check**: Verify system performance 4. **Query rewrite**: Consider alternative approaches ### Timeout Too Long If timeout is too generous: 1. **Reduce timeout**: Set appropriate limits 2. **Resource protection**: Prevent runaway queries 3. **User experience**: Provide faster feedback 4. **System stability**: Protect shared resources ## Best Practices ### Setting Appropriate Timeouts Choose timeout values based on: 1. **Query complexity**: More complex queries need more time 2. **Environment type**: Production vs development needs 3. **Network conditions**: Account for latency 4. **User expectations**: Balance patience vs productivity ### Environment-Specific Settings Consider different timeouts for: * **Production**: Shorter timeouts (60-120 seconds) * **Development**: Longer timeouts (300-600 seconds) * **Testing**: Medium timeouts (120-300 seconds) * **Training**: Longer timeouts for learning ### Monitoring and Adjustment Regularly review timeout settings: 1. **Query performance**: Monitor average execution times 2. **Timeout frequency**: Track how often timeouts occur 3. **User feedback**: Listen to user experiences 4. **System performance**: Adjust based on infrastructure changes ## Advanced Configuration ### Dynamic Timeouts Future enhancement considerations: * **Query-based timeouts**: Different timeouts for different query types * **Adaptive timeouts**: Automatic adjustment based on query complexity * **User-specific timeouts**: Per-user timeout preferences * **Connection-aware timeouts**: Adjust based on connection quality ### Integration Settings Timeout interaction with other features: * **Performance monitoring**: Track timeout vs execution time * **Query history**: Record timeout events * **Error handling**: Proper timeout error reporting * **Resource management**: Coordinate with system resources ## Common Timeout Values ### Recommended Settings | Environment | Timeout | Reasoning | | ----------- | --------------- | ----------------------------------- | | Production | 60-120 seconds | Protect resources, fast feedback | | Development | 300-600 seconds | Allow complex query development | | Testing | 120-300 seconds | Balance testing needs and resources | | Training | 300+ seconds | Allow learning and experimentation | ### Query Type Considerations | Query Type | Suggested Timeout | Notes | | ------------- | ----------------- | -------------------- | | Simple SELECT | 30-60 seconds | Fast exploration | | Complex joins | 120-300 seconds | Multi-table analysis | | Aggregations | 300-600 seconds | Summary calculations | | Reports | 600+ seconds | Complex reporting | ## Error Handling ### Timeout Error Messages Clear error messages for timeouts: * **Timeout reason**: Why the query was cancelled * **Execution time**: How long the query ran * **Suggestions**: Recommendations for resolution * **Retry options**: How to try again ### Recovery Options When timeout occurs: 1. **Optimize query**: Improve performance 2. **Increase timeout**: Adjust settings if appropriate 3. **Break down query**: Split into smaller parts 4. **Use alternatives**: Consider BIP or other tools ## Next Steps Configure logging and diagnostics Monitor query performance # Basic Authentication Source: https://docs.btsscorp.com/koala/connections/basic-auth Connect to Oracle Fusion Cloud using username and password ## Overview Basic authentication allows you to connect to Oracle Fusion Cloud using your standard username and password. This is the simplest authentication method and is included in the free version of Koala Data Explorer Extension. ## Prerequisites * Valid Oracle Fusion Cloud user account * User credentials (username and password) * Network access to your Oracle Fusion instance ## Setting Up Basic Authentication ### Step 1: Open Connection Manager 1. Open VS Code with Koala Data Explorer installed 2. Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (Mac) to open the command palette 3. Type "Koala: Manage Connections" and select it ### Step 2: Add New Connection 1. Click the "Add Connection" button 2. Select "Basic Authentication" as the authentication type ### Step 3: Enter Connection Details Fill in the following required fields: * **Connection Name**: A descriptive name for this connection (e.g., "Production", "Test Environment") * **Host URL**: Your Oracle Fusion Cloud URL (e.g., `https://your-instance.oraclecloud.com`) * **Username**: Your Oracle Fusion username * **Password**: Your Oracle Fusion password Credentials are securely stored in VS Code's secret storage and are never saved in plain text. ### Step 4: Test Connection 1. Click "Test Connection" to verify your credentials 2. Wait for the connection test to complete 3. If successful, you'll see a green checkmark 4. If failed, verify your credentials and network connectivity ### Step 5: Save Connection Click "Save" to store the connection for future use. ## Using Basic Authentication Once configured, you can: 1. Select your connection from the dropdown in the Koala panel 2. The connection will be automatically established 3. Start writing and executing queries immediately ## Security Considerations ### Password Storage * Passwords are stored using VS Code's built-in secret storage * Credentials are encrypted at rest * Never shared or transmitted except to Oracle Fusion Cloud ### Best Practices For enterprise environments, OAuth PKCE authentication is also available in the paid version. * Use strong, unique passwords * Rotate passwords regularly * Enable multi-factor authentication in Oracle Fusion when available * Avoid sharing connections or credentials ## Limitations Basic authentication in the free version includes: * Single active connection at a time * Manual password updates when changed * No SSO integration * Limited to 50 rows per query ## Troubleshooting ### Invalid Credentials If you receive an authentication error: 1. Verify your username and password are correct 2. Check if your account is locked or expired 3. Ensure you're using the correct Oracle Fusion instance URL ### Connection Timeout If the connection times out: 1. Check your network connectivity 2. Verify firewall settings allow HTTPS traffic 3. Confirm the Oracle Fusion instance is accessible ### Password Changes When your Oracle Fusion password changes: 1. Open Connection Manager 2. Edit the existing connection 3. Update the password field 4. Test and save the connection ## OAuth PKCE Authentication For enterprise environments, the paid version also offers: * OAuth 2.0 PKCE authentication * Single Sign-On (SSO) support * Automatic token refresh * Enterprise integration features See [OAuth PKCE & SSO Authentication](/koala/connections/oauth-sso) for more details. ## Next Steps Start writing SQL queries Learn to manage multiple connections # Managing Connections Source: https://docs.btsscorp.com/koala/connections/managing-connections Create, edit, and switch between Oracle Fusion connections ## Overview Koala Data Explorer Extension allows you to manage multiple connections to different Oracle Fusion Cloud instances. This guide covers how to create, edit, and switch between connections. ## Connection Manager Access the Connection Manager through: 1. **Command Palette**: `Ctrl+Shift+P` → "Koala: Manage Connections" 2. **Status Bar**: Click the connection indicator in the bottom status bar 3. **Koala Panel**: Click the Koala icon in VS Code Activity Bar ## Creating Connections ### Add New Connection 1. Open Connection Manager 2. Click "Add Connection" 3. Choose authentication type: * Basic Authentication (free) * OAuth 2.0 PKCE (paid) * SSO (paid) 4. Enter connection details 5. Test connection 6. Save connection ### Connection Properties Each connection stores: * **Name**: Unique identifier for the connection * **Host URL**: Oracle Fusion instance URL * **Authentication**: Type and credentials * **Connection Timeout**: Custom timeout settings ## Editing Connections ### Update Connection Details 1. Select connection in manager 2. Click "Edit" 3. Modify fields as needed 4. Test changes 5. Save updates ### Copy a connection Duplicate an existing configuration to speed up onboarding new environments: 1. Open Connection Manager. 2. Select the connection you want to copy. 3. Click **Copy Connection**. 4. Update the name and host, then save. ### Change Authentication Method To switch authentication types: 1. Edit connection 2. Select new authentication type 3. Enter new credentials 4. Re-test connection 5. Save changes Changing authentication type will clear existing credentials. Ensure you have new credentials ready. ## Hash verification and deployment * Koala stores a hash of deployed artifacts per connection and compares it on each connect. * The connection details pane shows the last deployed hash and timestamp. * **Force Redeploy Catalog** uploads the latest package even when hashes match. Use Force Redeploy after Oracle-side catalog changes or when you see "hash mismatch" errors. ## Switching Connections ### Connection Switching Switch between connections: * Use connection dropdown in status bar * Select from connection manager * Active connection shown in status bar ### Connection Context Each connection maintains: * Query history * Current session state * Authentication tokens ## Connection Security ### Credential Storage * Stored in VS Code's secure storage * Encrypted at rest * Never in plain text files ### Best Practices * Use OAuth PKCE for production environments * Use descriptive connection names * Remove unused connections * Rotate credentials regularly ## Troubleshooting Connections ### Connection Failed Common solutions: 1. **Network Issues** * Check internet connectivity * Verify firewall settings 2. **Authentication Problems** * Verify credentials * Check account status * Refresh OAuth tokens 3. **Oracle Fusion Issues** * Verify instance is running * Check maintenance windows * Confirm user permissions ### Slow Connections 1. Check network connectivity 2. Adjust timeout settings in extension settings 3. Verify Oracle Fusion instance performance ## Next Steps Start querying your data Configure connection defaults # OAuth PKCE Authentication Source: https://docs.btsscorp.com/koala/connections/oauth-sso Enterprise authentication with OAuth 2.0 PKCE for Oracle Fusion Cloud ## Overview OAuth 2.0 PKCE authentication provides enterprise-grade security for connecting to Oracle Fusion Cloud. This feature integrates with your organization's existing Single Sign-On (SSO) through Oracle Identity and Access Management (IAM). OAuth PKCE authentication requires a paid license. See [Free vs Paid Features](/koala/licensing/free-vs-paid) for more information. ## Benefits of OAuth PKCE ### Enhanced Security * No password storage in VS Code * Token-based authentication with PKCE * Automatic token refresh * Leverages existing enterprise SSO and MFA ### Enterprise Integration * Uses your existing Oracle Identity Domain * Centralized access management through Oracle IAM * Compliance with corporate security policies * Full audit trail in Oracle systems ### User Experience * Single sign-on with enterprise credentials * No password management required * Seamless re-authentication * Session persistence across VS Code restarts ## Authentication Flow Koala Data Explorer Extension implements OAuth 2.0 PKCE authentication specifically with: * **Oracle Identity Domains** (part of Oracle Cloud Infrastructure) * **Oracle Fusion Cloud Applications** resource access * **PKCE (Proof Key for Code Exchange)** for enhanced security ## Setting Up OAuth PKCE Authentication OAuth PKCE setup requires coordination between your Oracle administrator and end users. The process has two phases: ### Phase 1: Administrator Setup (One-Time) Your Oracle administrator must first configure OAuth in Oracle Identity and Access Management (IAM). #### Prerequisites for Administrators * Access to Oracle Cloud console * Administrator privileges in the Fusion Identity Domain * Same identity domain used by your Oracle Fusion instance #### Admin Configuration Steps **Step 1: Access Oracle IAM Console** 1. Log into Oracle Cloud console 2. Navigate to **Identity & Security** → **Identity Domains** 3. Select your Fusion Identity Domain 4. Go to **Applications** **Step 2: Create OAuth Application** 1. Click **Add Application** 2. Select **Mobile Application** (creates a public PKCE client) 3. Click **Launch Workflow** **Step 3: Configure Application Details** *Basic Information:* * **Name**: `Koala Data Explorer OAuth Client` * **Description**: `VS Code extension for Oracle Fusion data access` *Client Configuration:* * **Client Type**: Public (automatically set) * **Grant Types**: Select "Authorization Code" * **PKCE**: Enabled (automatic for mobile apps) * **Redirect URI**: Add exactly: ``` vscode://btss-corp.koala-data-explorer/oauth/callback ``` This URI must match exactly - no trailing slashes or variations *Resource and Scope Configuration:* * **Add Resource**: Select "Oracle Applications Cloud (Fusion)" * **Scopes**: System auto-generates required scope like: ``` urn:opc:resource:fa:instanceid=12345urn:opc:resource:consumer::all ``` * **Bypass Consent**: Enable (recommended for internal use) * **Trust Scope**: Enable for all selected scopes **Step 4: Collect Configuration Values** Document these values for end users: * **Client ID**: Found in General → Client ID * **Authorization Endpoint**: `https://your-idcs-instance.identity.oraclecloud.com/oauth2/v1/authorize` * **Token Endpoint**: `https://your-idcs-instance.identity.oraclecloud.com/oauth2/v1/token` * **Scope**: The auto-generated resource identifier from Step 3 ### Phase 2: End User Setup Once administrators complete Phase 1, end users can configure OAuth connections: #### Step 1: Add OAuth Connection 1. Open Koala Data Explorer in VS Code 2. Press `Ctrl+Shift+P` → "Koala: Manage Connections" 3. Click **Add Connection** 4. Select **OAuth PKCE** as authentication type #### Step 2: Enter Configuration Details Use the values provided by your administrator: * **Connection Name**: Descriptive name (e.g., "Production OAuth") * **Oracle Fusion URL**: Your Fusion instance URL * **Client ID**: From administrator * **Authorization Endpoint**: From administrator * **Token Endpoint**: From administrator * **Scope**: From administrator #### Step 3: Authenticate 1. Click **Save** to save the connection 2. Select the connection and click **Connect** 3. Your browser opens for SSO authentication 4. Log in with your enterprise credentials 5. Complete any MFA requirements 6. VS Code receives the authentication token 7. Connection is established #### Step 4: BIP Catalog Deployment OAuth connections cannot automatically deploy the required BIP catalog. After successful authentication: 1. Click **Deploy to BIP** button in the query editor 2. Select **Download Catalog** option 3. Save the `Koala.catalog` file 4. Send this file to your Oracle administrator 5. Request deployment to `/Custom/Koala/` in the BIP catalog ## Token Management OAuth PKCE authentication uses secure token-based access with automatic refresh capabilities. ### Automatic Token Refresh Koala Data Explorer automatically: * Monitors token expiration * Refreshes tokens before expiry * Handles refresh failures gracefully * Prompts for re-authentication when needed ### Token Security * Tokens stored in VS Code's secure credential storage * Encrypted at rest and in transit * Never logged or exposed in diagnostics * Automatically cleared when connection is removed ## Troubleshooting OAuth PKCE ### Common Issues **"Client authentication failed"** * Verify application is configured as Mobile/Public client in Oracle IAM * Ensure PKCE is enabled in grant types * Check Client ID matches exactly **"Invalid redirect URI"** * Verify redirect URI matches exactly: `vscode://btss-corp.koala-data-explorer/oauth/callback` * Check for typos or extra characters * Ensure no trailing slashes **"Invalid scope"** * Verify scope string from Oracle administrator * Check that Fusion resource is properly configured in Oracle IAM * Ensure identity domain matches Fusion instance **Browser doesn't open for authentication** * Check that default browser is set in your system * Try copying the authorization URL manually to browser * Verify network firewall settings allow browser communication **Authentication successful but connection fails** * Verify token endpoints are correct * Check Oracle Fusion URL is accessible * Ensure user has proper Fusion access rights and roles ## Best Practices ### For Administrators * Use descriptive names for OAuth applications in Oracle IAM * Document configuration values for end users * Regularly review OAuth application permissions * Monitor authentication logs in Oracle IAM console * Keep identity domain aligned with Fusion instance ### For End Users * Use OAuth PKCE for production environments * Leverage existing enterprise SSO and MFA policies * Test connections after Oracle system maintenance * Remove unused connections to maintain security * Contact administrators for configuration issues ### Security Considerations * OAuth PKCE provides enhanced security over Basic authentication * No passwords stored in VS Code * Centralized access control through Oracle IAM * Full audit trail in Oracle systems * Automatic compliance with corporate identity policies ## Next Steps Manage multiple connections Configure security settings # SSO Authentication (Windows) Source: https://docs.btsscorp.com/koala/connections/windows-sso Simple Single Sign-On integration with Oracle Fusion Cloud SSO ## Overview Koala Data Explorer Extension supports connecting to Oracle Fusion Cloud using your organization's existing SAML-based SSO. This is different from OAuth PKCE authentication - it works directly with Oracle Fusion's built-in SSO without requiring additional setup. SSO authentication requires a paid license and is currently available only on Windows. See [Free vs Paid Features](/koala/licensing/free-vs-paid) for more information. ## Why Use SSO? ### Simple Setup * **No OAuth configuration required**: Works with your existing Oracle Fusion SSO * **No administrator setup**: Uses SSO already configured in Oracle Fusion * **One-click authentication**: Just enter your Oracle URL and connect ### Enterprise Integration * **Uses your existing SSO**: Works with whatever SSO method your organization uses * **Multi-factor authentication**: Supports MFA when configured in your SSO * **Familiar experience**: Same login process you use for Oracle Fusion web portal ## Requirements * **Windows 10/11**: Currently Windows-only * **Runtime dependencies**: Extension automatically downloads required components when needed ## Setting Up SSO ### Step 1: Create SSO Connection 1. **Open Connection Manager**: Click "Manage Connections" in the query editor 2. **Add new connection**: Click "Add Connection" 3. **Select authentication type**: Choose "SSO - Windows Only" 4. **Enter connection details**: * **Connection Name**: Descriptive name (e.g., "Production SSO") * **Host URL**: Your Oracle Fusion Cloud instance URL 5. **Save connection**: Click "Save" ### Step 2: Connect 1. **Select your SSO connection** from the dropdown 2. **Click Connect**: The extension handles the rest 3. **Complete SSO login**: Use your normal Oracle Fusion login process 4. **Start querying**: You're connected and ready to query data On first use, the extension may download required components (this happens automatically). ## How It Works SSO authentication connects you to Oracle Fusion using the same login process you use in your web browser. The extension opens a secure login window where you complete your organization's SSO process. ## BIP Catalog Setup Like OAuth PKCE connections, SSO connections require manual BIP catalog deployment: 1. **Click "Deploy to BIP"** in the query editor after connecting 2. **Download the catalog file** 3. **Send to your Oracle administrator** for deployment to `/Custom/Koala/` ## Troubleshooting ### Common Issues **"Runtime components missing"** * Accept the download prompt when shown * Restart VS Code after installation **"SSO dialog won't open"** * Restart VS Code * Check with IT if antivirus software is blocking the connection **"Authentication timeout"** * Verify SSO is working in your regular browser * Contact your Oracle administrator if SSO login fails ## When to Use SSO vs OAuth PKCE ### Use SSO When: * Your team uses Windows computers * You want the simplest setup (no OAuth configuration needed) * Your Oracle Fusion already has SSO configured ### Use OAuth PKCE When: * You need cross-platform support (Mac/Linux users) * Your organization requires OAuth-based authentication * You need centralized OAuth management ## Next Steps Alternative enterprise authentication method Learn to manage multiple connections # Bind Variables Source: https://docs.btsscorp.com/koala/editor/bind-variables Use parameters and bind variables for dynamic, reusable queries ## Overview Bind variables (also called parameters) allow you to create dynamic, reusable queries with values that can be supplied at runtime. This feature improves query performance, security, and maintainability. ## Benefits of Bind Variables ### Performance * Query plans are cached and reused * Reduces parsing overhead * Improves database performance ### Security * Prevents SQL injection attacks * Safely handles user input * Automatic escaping of special characters ### Reusability * Same query with different values * Create query templates * Share parameterized queries ## Basic Syntax ### Colon Notation Standard Oracle bind variable syntax: ```sql theme={null} SELECT * FROM employees WHERE department_id = :dept_id AND hire_date > :start_date; ``` ### Named Parameters Use descriptive parameter names: ```sql theme={null} SELECT e.employee_id, e.first_name, e.last_name, d.department_name FROM employees e JOIN departments d ON e.department_id = d.department_id WHERE e.salary BETWEEN :min_salary AND :max_salary AND e.job_id = :job_code; ``` ## Using Bind Variables ### Interactive Input When you execute a query with bind variables: 1. Koala detects all parameters 2. Opens input dialog 3. Enter values for each parameter 4. Query executes with supplied values ### Input Dialog Features The parameter input dialog provides: * **Parameter Name**: Clear identification * **Data Type**: Automatic type detection * **Default Values**: Previously used values * **Validation**: Type and format checking * **Help Text**: Optional descriptions ## Parameter Types ### String Parameters ```sql theme={null} SELECT * FROM employees WHERE last_name = :last_name AND email LIKE :email_pattern; ``` Input examples: * `:last_name` → 'Smith' * `:email_pattern` → '%@oracle.com' ### Numeric Parameters ```sql theme={null} SELECT * FROM orders WHERE total_amount > :min_amount AND quantity <= :max_quantity; ``` Input examples: * `:min_amount` → 1000.00 * `:max_quantity` → 50 ### Date Parameters ```sql theme={null} SELECT * FROM transactions WHERE transaction_date BETWEEN :start_date AND :end_date; ``` Input formats: * 'YYYY-MM-DD' * 'DD-MON-YYYY' * 'MM/DD/YYYY' ### Boolean Parameters ```sql theme={null} SELECT * FROM products WHERE is_active = :active_flag; ``` Input values: * 'TRUE' or 'FALSE' * '1' or '0' * 'Y' or 'N' ## Advanced Features ### Default Values When you execute a query with bind variables, Koala will prompt you to enter values for each parameter. Previously used values are remembered and suggested as defaults. ## Common Usage Patterns ### IN Clause with Multiple Values For queries that need multiple values, you can use bind variables with IN clauses: ```sql theme={null} SELECT * FROM employees WHERE department_id = :dept_id AND job_id IN ('IT_PROG', 'SA_REP'); ``` ## Query Templates You can create reusable query patterns with bind variables: ```sql theme={null} -- Employee Search Template SELECT employee_id, first_name || ' ' || last_name as full_name, email, hire_date, salary FROM employees WHERE department_id = :dept_id AND hire_date >= :start_date ORDER BY employee_id; ``` ## Performance Considerations ### Query Plan Caching Bind variables improve performance: 1. Query plan generated once 2. Reused for different values 3. Reduces database load 4. Faster execution ### Best Practices 1. Use bind variables for frequently changing values 2. Don't use for static values 3. Name parameters clearly 4. Group related parameters ## Security Benefits ### SQL Injection Prevention Bind variables prevent injection: ```sql theme={null} -- Safe: Uses bind variable SELECT * FROM users WHERE username = :username; -- Unsafe: String concatenation (never do this!) SELECT * FROM users WHERE username = '" + userInput + "'; ``` ### Data Sanitization Automatic handling of: * Special characters * Quotes and escapes * Null values * Data type conversion ## Troubleshooting ### Common Issues #### "Invalid parameter value" * Check data type matches column * Verify format (especially dates) * Ensure value within valid range #### "Parameter not found" * Check parameter name spelling * Ensure colon prefix (`:param`) * Verify parameter is used in query #### "Too many bind variables" * Oracle limit: 65,535 per query * Simplify complex queries * Use temporary tables for large datasets ## Integration with Query History When you use bind variables: * Parameters are saved with query history * Previous parameter values are remembered * You can recall and reuse parameterized queries ## Examples ### Financial Report ```sql theme={null} -- @param fiscal_year = 2024 -- @param department = 'SALES' -- @param min_revenue = 10000 SELECT d.department_name, TO_CHAR(t.transaction_date, 'Q') as quarter, SUM(t.amount) as total_revenue, COUNT(*) as transaction_count FROM transactions t JOIN departments d ON t.department_id = d.department_id WHERE EXTRACT(YEAR FROM t.transaction_date) = :fiscal_year AND d.department_name = :department AND t.amount >= :min_revenue GROUP BY d.department_name, TO_CHAR(t.transaction_date, 'Q') ORDER BY quarter; ``` ### Employee Search ```sql theme={null} SELECT employee_id, first_name || ' ' || last_name as name, email, department_id, salary FROM employees WHERE department_id = :dept_id AND salary >= :min_salary ORDER BY employee_id; ``` ## Next Steps Learn query execution options Create reusable templates # Executing Queries Source: https://docs.btsscorp.com/koala/editor/executing-queries Execute SQL with per-tab isolation, background execution, and instant cancellation in Koala Data Explorer. ## Overview Koala Data Explorer Extension provides multiple ways to execute SQL queries against your Oracle Fusion Cloud data. This guide covers query execution methods, options, and best practices. ## Execution Methods ### Quick Execute The fastest way to run queries: 1. **Keyboard Shortcut**: `Ctrl+Enter` (Windows/Linux) or `Cmd+Enter` (Mac) 2. **Button**: Click the green "Run" button in the editor toolbar 3. **Context Menu**: Right-click → "Execute Query" ### Execute Selection Run only selected SQL: 1. Select the SQL text you want to run 2. Press `Ctrl+Shift+Enter` or click "Run Selection" 3. Only the selected text will be executed This is useful when you have multiple queries in one editor and want to run them individually. ### Execute Current Statement Automatically detect and run the statement at cursor position: 1. Place cursor anywhere in a SQL statement 2. Press `Alt+Enter` 3. Koala will identify statement boundaries and execute ## Query Execution Options ### Execution Settings Configure how queries are executed: ```json theme={null} { "koala.execution.timeout": 30000, "koala.execution.fetchSize": 100, "koala.execution.maxRows": 1000, "koala.execution.stopOnError": true } ``` ### Row Limits Control how many rows are returned: * **Free Version**: Maximum 50 rows per query * **Paid Version**: Configurable, unlimited rows Set custom limits: 1. Click the settings icon in query editor 2. Adjust "Max Rows" value 3. Use `FETCH FIRST n ROWS ONLY` in SQL for precise control ### Timeout Configuration Prevent long-running queries: * Default timeout: 30 seconds * Maximum timeout: 5 minutes * Configure per-query or globally To set query-specific timeout: ```sql theme={null} -- @timeout: 60000 SELECT * FROM large_table; ``` ## Multi-Statement Execution ### Sequential Execution (Paid) Execute multiple statements in order: ```sql theme={null} -- Statement 1 SELECT COUNT(*) FROM employees; -- Statement 2 SELECT department_id, COUNT(*) FROM employees GROUP BY department_id; -- Statement 3 SELECT * FROM departments; ``` Press `Ctrl+Shift+Enter` to run all statements sequentially. ### Multi-Statement Execution When executing multiple statements: * Each statement executes sequentially * Execution stops on first error * Results shown for each completed statement ## Query Parameters ### Bind Variables Use bind variables for dynamic queries: ```sql theme={null} SELECT * FROM employees WHERE department_id = :dept_id AND hire_date > :start_date; ``` When executed, Koala will prompt for parameter values in an input dialog. ## Execution Status ### Progress Indicators Monitor query execution: * **Spinner**: Query is running * **Progress Bar**: Shows fetch progress for large results * **Timer**: Displays elapsed time * **Cancel Button**: Stops the active tab's query without affecting others ### Status Messages Execution feedback appears in: * Status bar (brief summary) * Output panel (detailed logs) * Results panel (row count, execution time) ## Cancel Query Execution ### How to Cancel Stop a running query: 1. Click the "Cancel" button in the toolbar 2. Press `Ctrl+Alt+C` 3. Click "Stop" in the progress notification ### What Happens on Cancel * Query execution stops on the server for the active tab only * Partial results may be returned * Connection remains active * Transaction is rolled back (if applicable) * Other tabs continue running their own queries Some queries may continue running on the Oracle server even after cancellation. Check with your DBA if concerned about long-running queries. ## Tab isolation and background execution * Each tab has an isolated execution context; cancelling one tab does not interrupt others. * You can switch tabs while a query runs in the background; status and cancel remain available from the originating tab. * Switching connections within a tab will cancel any in-flight query for that tab. ## Execution History ### View Recent Queries Access query history: 1. Press `Ctrl+H` or click History icon 2. Browse executed queries 3. Click to reload any query 4. Filter by date, status, or connection ### History Features * **Free Version**: Last 50 queries * **Paid Version**: Last 500 queries with search Each history entry includes: * SQL text * Execution time * Row count * Timestamp * Connection used ## Performance Optimization ### Query Performance Tips 1. **Use Indexes**: Include indexed columns in WHERE clauses 2. **Limit Rows**: Add FETCH FIRST or ROWNUM conditions 3. **Select Specific Columns**: Avoid SELECT \* 4. **Use Bind Variables**: Improve query plan caching ### Query Performance Monitor query performance: * Execution time displayed in results * Row count shown * Timeout warnings if query runs long ## Error Handling ### Common Execution Errors #### ORA-00942: Table or view does not exist * Verify table name and schema * Check user permissions * Ensure correct connection #### ORA-00936: Missing expression * Check SQL syntax * Verify all columns exist * Review JOIN conditions #### ORA-01017: Invalid username/password * Re-authenticate connection * Update stored credentials * Check account status ### Error Display Errors appear in: * **Inline**: Red squiggly lines in editor * **Problems Panel**: Detailed error list * **Output Panel**: Full error stack trace ## Export Results After query execution, you can export results: 1. Click Export button in results toolbar 2. Choose format (CSV, JSON, or Excel for paid version) 3. Select save location 4. Results are saved to file ## Best Practices ### Before Execution 1. Review query for errors 2. Estimate result size 3. Consider adding row limits 4. Use explain plan for complex queries ### During Execution 1. Monitor progress for long queries 2. Be ready to cancel if needed 3. Watch for timeout warnings 4. Check connection stability ### After Execution 1. Verify result accuracy 2. Check execution time 3. Save useful queries 4. Export important results ## Keyboard Shortcuts | Action | Windows/Linux | Mac | | ----------------- | ------------------ | ----------------- | | Execute Query | `Ctrl+Enter` | `Cmd+Enter` | | Execute Selection | `Ctrl+Shift+Enter` | `Cmd+Shift+Enter` | | Cancel Execution | `Ctrl+Alt+C` | `Cmd+Option+C` | | Query History | `Ctrl+H` | `Cmd+H` | ## Next Steps Master all keyboard shortcuts Work with query results # Interface Guide Source: https://docs.btsscorp.com/koala/editor/interface-guide Complete guide to Koala Data Explorer's user interface elements and buttons ## Overview This guide covers all the interface elements, buttons, and UI components in Koala Data Explorer Extension to help you navigate and use the extension effectively. ## Main Interface Elements ### Query Tab Bar Located at the top of the query editor: * **Tab Names**: Show query content preview or file paths * **+ Button**: Create new tabs (paid feature only) * **× Button**: Close individual tabs * **● Indicator**: Shows unsaved changes in tab ### Connection Controls Located in each query tab: * **Connection Dropdown**: Select from saved connections * **Connect Button**: Establish connection to selected database * **Disconnect Button**: Close current database connection * **Connection Status**: Shows current connection state ### Query Editor Area The main SQL editing area with: * **Syntax Highlighting**: Automatic SQL color coding * **Line Numbers**: Shows line numbers for reference * **IntelliSense**: Auto-completion suggestions (paid feature) ### Action Buttons #### Primary Actions * **Execute Button**: Run the current SQL query * **Export Button**: Export query results to various formats * **Save Button**: Save current query to file (via `Ctrl+S` / `Cmd+S`) #### Connection Management * **Manage Connections Button**: Opens connection management interface * **Add Connection Button**: Create new database connections * **Test Connection Button**: Verify connection settings * **Save Button**: Save connection configuration #### Data Management * **Deploy to BIP Button**: Deploy or download BIP catalog for Oracle Fusion * **Refresh Button**: Refresh data sources panel (paid feature) ## Connection Management Interface ### Adding Connections When clicking **Manage Connections** → **Add Connection**: 1. **Authentication Type Selection**: * Basic Authentication (free) * OAuth PKCE (paid) 2. **Connection Form Fields**: * **Connection Name**: Friendly identifier * **Host URL**: Oracle Fusion instance URL * **Username/Password**: For Basic Authentication * **OAuth Settings**: Client ID, endpoints for OAuth PKCE 3. **Action Buttons**: * **Test Connection**: Verify settings before saving * **Save**: Store connection configuration * **Cancel**: Discard changes ### Managing Existing Connections * **Connection List**: Shows all saved connections * **Edit Button**: Modify existing connection settings * **Delete Button**: Remove connections * **Set as Default**: Mark preferred connection ## Query Execution Interface ### Execution Controls * **Execute Button**: Primary execution control * **Keyboard Shortcut**: `Ctrl+Enter` / `Cmd+Enter` for execution * **Partial Execution**: Select text and execute only selection ### Execution Status * **Progress Indicator**: Shows when query is running * **Execution Time**: Displays query duration after completion * **Row Count**: Shows number of rows returned * **Error Messages**: Displays any execution errors ## Results Interface ### Results Grid * **Column Headers**: Click to sort ascending/descending * **Row Selection**: Click row numbers to select * **Cell Content**: View query results * **Scroll Bars**: Navigate large result sets ### Results Controls * **Export Button**: Export visible results * **Copy Function**: `Ctrl+C` / `Cmd+C` to copy selected data * **Select All**: `Ctrl+A` / `Cmd+A` to select all results * **Clear Selection**: `Escape` to deselect ### Export Options When clicking **Export Button**: 1. **Format Selection**: * CSV (free) * JSON (free) * Excel (paid, with 10K row limit) * XML (free) 2. **Export Scope**: * All results * Selected rows only ## Side Panels ### Data Sources Panel (Paid Feature) * **Tree View**: Shows available tables and views * **Search Box**: Filter data sources by name * **Refresh Button**: Reload data source list * **Table/View Items**: Click to insert into query ### History Panel * **Query List**: Shows recent executed queries * **Timestamps**: When queries were executed * **Search Filter**: Find specific historical queries * **Load Button**: Insert historical query into current tab ## BIP Catalog Management ### For Basic Authentication Users * **Auto-Deploy Prompt**: Appears when catalog is missing * **Deploy Button**: Automatically deploys required catalog * **Credential Prompt**: Enter credentials for deployment ### For OAuth PKCE Users * **Deploy to BIP Button**: Manual catalog management * **Download Catalog Option**: Save `.catalog` file locally * **Upload Instructions**: Guidance for administrator deployment ## Status Indicators ### Connection Status * **Connected**: Green indicator with instance name * **Connecting**: Yellow with spinning indicator * **Disconnected**: Red or gray indicator * **Error**: Red with error message ### Tab Status * **Clean**: No visual indicator * **Modified**: Dot (●) in tab title * **Saved File**: Shows file path in tab title * **New Query**: Shows query preview in tab title ### Execution Status * **Ready**: No indicator * **Executing**: Progress spinner * **Completed**: Row count and timing * **Error**: Red error message ## Settings and Configuration ### Extension Settings Access through VS Code settings: * **Timeout Settings**: Query execution limits * **Row Limits**: Default maximum rows returned * **Auto-refresh**: Data sources refresh behavior * **Export Settings**: Default export formats ### Keyboard Shortcuts Customize through VS Code keyboard shortcuts: * **Execute Query**: Default `Ctrl+Enter` / `Cmd+Enter` * **Save Query**: Default `Ctrl+S` / `Cmd+S` * **Find/Replace**: Standard VS Code shortcuts ## Interface Tips ### Efficiency Tips 1. **Use keyboard shortcuts** for common actions 2. **Right-click context menus** for additional options 3. **Drag and drop** .sql files to open in new tabs 4. **Double-click connections** to quick-connect ### Visual Cues * **Hover effects**: Buttons highlight when hoverable * **Disabled states**: Grayed out when unavailable * **Loading states**: Spinners during operations * **Error states**: Red indicators for problems ## Accessibility ### Keyboard Navigation * **Tab key**: Navigate between interface elements * **Enter key**: Activate buttons and controls * **Arrow keys**: Navigate results grid * **Escape key**: Cancel operations or clear selections ### Screen Reader Support * **ARIA labels**: All buttons have descriptive labels * **Status announcements**: Important state changes announced * **Keyboard shortcuts**: All functions accessible via keyboard ## Next Steps Learn how to run SQL queries Set up and manage database connections # Keyboard Shortcuts Source: https://docs.btsscorp.com/koala/editor/keyboard-shortcuts Essential keyboard shortcuts for efficient query development ## Overview Koala Data Explorer Extension includes essential keyboard shortcuts to improve your productivity when writing and executing SQL queries. The shortcuts work within the VS Code environment alongside standard VS Code shortcuts. ## Essential Shortcuts The following shortcuts are implemented and available in Koala Data Explorer: ### Query Execution | Action | Windows/Linux | Mac | Description | | ------------- | ------------- | ----------- | --------------------------------- | | Execute Query | `Ctrl+Enter` | `Cmd+Enter` | Run entire query or selected text | | Save Query | `Ctrl+S` | `Cmd+S` | Save current query to file | ### Editor Features | Action | Windows/Linux | Mac | Description | | -------------------- | ------------- | ----------- | ------------------------------------ | | Find | `Ctrl+F` | `Cmd+F` | Find text in query | | Replace | `Ctrl+H` | `Cmd+H` | Find and replace text | | Comment/Uncomment | `Ctrl+/` | `Cmd+/` | Toggle line comment | | Trigger IntelliSense | `Ctrl+Space` | `Cmd+Space` | Show autocomplete suggestions (Paid) | ### Results Management | Action | Windows/Linux | Mac | Description | | ------------------ | ------------- | -------- | -------------------------- | | Select All Results | `Ctrl+A` | `Cmd+A` | Select all rows in results | | Copy | `Ctrl+C` | `Cmd+C` | Copy selected results | | Clear Selection | `Escape` | `Escape` | Clear result selection | ### Editor Navigation | Action | Shortcut | Description | | ----------------- | ------------- | ---------------------------- | | Move Line Up/Down | `Alt+↑/↓` | Move current line up or down | | Duplicate Line | `Shift+Alt+↓` | Duplicate current line below | ## Standard VS Code Shortcuts Koala Data Explorer works within VS Code, so all standard VS Code shortcuts also apply: ### File Operations * **New File**: `Ctrl+N` / `Cmd+N` * **Open File**: `Ctrl+O` / `Cmd+O` * **Save**: `Ctrl+S` / `Cmd+S` * **Save As**: `Ctrl+Shift+S` / `Cmd+Shift+S` ### Text Editing * **Undo**: `Ctrl+Z` / `Cmd+Z` * **Redo**: `Ctrl+Y` / `Cmd+Y` * **Cut**: `Ctrl+X` / `Cmd+X` * **Copy**: `Ctrl+C` / `Cmd+C` * **Paste**: `Ctrl+V` / `Cmd+V` * **Select All**: `Ctrl+A` / `Cmd+A` ## Customizing Shortcuts You can customize any shortcuts through VS Code's keyboard shortcuts settings: 1. Open Command Palette: `Ctrl+Shift+P` / `Cmd+Shift+P` 2. Type "Preferences: Open Keyboard Shortcuts" 3. Search for specific commands to modify ## Productivity Tips ### Essential Shortcuts for Koala Focus on these key shortcuts for maximum productivity: 1. **`Ctrl+Enter` / `Cmd+Enter`** - Execute queries (most important) 2. **`Ctrl+S` / `Cmd+S`** - Save your work frequently 3. **`Ctrl+/` / `Cmd+/`** - Comment/uncomment SQL lines 4. **`Ctrl+F` / `Cmd+F`** - Find text in large queries 5. **`Escape`** - Clear result selections ### Workflow Tips * **Partial Execution**: Select SQL text and press `Ctrl+Enter` / `Cmd+Enter` to run only the selection * **Line Management**: Use `Alt+↑/↓` to move lines up/down when organizing queries * **Duplicate Lines**: Use `Shift+Alt+↓` to quickly duplicate useful query patterns ## Next Steps Use parameters in queries SQL query best practices # Large SQL Queries Source: https://docs.btsscorp.com/koala/editor/large-sql Execute large SQL statements with compression and chunking ## Overview Koala handles large SQL statements by compressing and chunking requests so you can run complex queries without manual changes. ## Query size tiers * **Small**: Under 24 KB (sent as-is) * **Medium**: 24–120 KB (gzip compression applied) * **Large**: 120 KB+ (smart chunking plus compression) Size is calculated from the raw SQL text. Whitespace and comments count toward total size. ## How large SQL is handled * **Gzip compression**: Automatically compresses SQL payloads before sending. * **Smart chunking**: Splits very large statements into SOAP-safe chunks while preserving statement boundaries. * **SOAP parameter optimization**: Uses efficient parameter encoding to reduce overhead. ## Best practices 1. Keep comments concise to reduce payload size. 2. Use bind variables to avoid repeating literal values. 3. Validate SQL formatting before execution to avoid chunk boundary errors. 4. Prefer CTEs over deeply nested subqueries for readability. ## Example: large SQL ```sql theme={null} WITH employee_data AS ( SELECT person_id, department_name, salary, hire_date, manager_id FROM fusion_employees WHERE hire_date > DATE '2015-01-01' ) SELECT department_name, COUNT(*) AS headcount, AVG(salary) AS avg_salary FROM employee_data GROUP BY department_name ORDER BY headcount DESC; ``` If a query approaches 1 MB of text, consider breaking it into smaller, reusable CTEs across multiple tabs. # Writing Queries Source: https://docs.btsscorp.com/koala/editor/writing-queries Master the SQL query editor and write efficient Oracle Fusion queries ## Query Editor Overview The Koala SQL Editor is powered by Monaco Editor (the same editor used in VS Code) providing a professional SQL development experience. ## Basic Query Structure ### Simple SELECT Query ```sql theme={null} -- Basic query structure SELECT column1, column2, column3 FROM table_name WHERE condition = 'value' ORDER BY column1 DESC; ``` ### Oracle Fusion Example ```sql theme={null} -- Get recent invoices SELECT INVOICE_NUM, INVOICE_DATE, SUPPLIER_NAME, INVOICE_AMOUNT FROM AP_INVOICES_ALL WHERE CREATION_DATE >= SYSDATE - 30 AND ROWNUM <= 100 ORDER BY CREATION_DATE DESC; ``` ## Editor Features ### Syntax Highlighting The editor provides full SQL syntax highlighting: * **Keywords**: Blue (SELECT, FROM, WHERE) * **Strings**: Red ('value') * **Numbers**: Green (123) * **Comments**: Gray (-- comment) ### IntelliSense (Paid Feature) Auto-completion for: * SQL keywords * Table names * Column names * Functions Trigger with `Ctrl+Space` or start typing. ### Code Formatting Format your SQL for readability: * Automatic indentation * Keyword capitalization * Consistent spacing ## Query Best Practices ### 1. Always Use Row Limits ```sql theme={null} -- Good: Limits rows for performance SELECT * FROM large_table WHERE ROWNUM <= 1000; -- Bad: No limit on large table SELECT * FROM large_table; ``` ### 2. Use Specific Columns ```sql theme={null} -- Good: Select only needed columns SELECT employee_id, first_name, last_name FROM employees; -- Bad: Select all columns unnecessarily SELECT * FROM employees; ``` ### 3. Add Meaningful Aliases ```sql theme={null} SELECT emp.EMPLOYEE_ID AS "Employee ID", emp.FIRST_NAME || ' ' || emp.LAST_NAME AS "Full Name", dept.DEPARTMENT_NAME AS "Department" FROM PER_EMPLOYEES emp JOIN HR_DEPARTMENTS dept ON emp.DEPARTMENT_ID = dept.DEPARTMENT_ID; ``` ## Common Oracle Fusion Tables ### Human Resources ```sql theme={null} -- Employees SELECT * FROM PER_ALL_PEOPLE_F WHERE ROWNUM <= 10; -- Assignments SELECT * FROM PER_ALL_ASSIGNMENTS_M WHERE ROWNUM <= 10; -- Jobs SELECT * FROM PER_JOBS WHERE ROWNUM <= 10; ``` ### Financials ```sql theme={null} -- Invoices SELECT * FROM AP_INVOICES_ALL WHERE ROWNUM <= 10; -- Suppliers SELECT * FROM POZ_SUPPLIERS WHERE ROWNUM <= 10; -- Payments SELECT * FROM AP_INVOICE_PAYMENTS_ALL WHERE ROWNUM <= 10; ``` ### Supply Chain ```sql theme={null} -- Purchase Orders SELECT * FROM PO_HEADERS_ALL WHERE ROWNUM <= 10; -- Inventory Items SELECT * FROM EGP_SYSTEM_ITEMS_B WHERE ROWNUM <= 10; -- Shipments SELECT * FROM RCV_SHIPMENT_HEADERS WHERE ROWNUM <= 10; ``` ## Advanced Query Techniques ### Using WITH Clauses (CTEs) ```sql theme={null} WITH recent_invoices AS ( SELECT INVOICE_ID, INVOICE_NUM, INVOICE_AMOUNT FROM AP_INVOICES_ALL WHERE INVOICE_DATE >= ADD_MONTHS(SYSDATE, -3) ) SELECT ri.*, s.SUPPLIER_NAME FROM recent_invoices ri JOIN POZ_SUPPLIERS s ON ri.VENDOR_ID = s.VENDOR_ID WHERE ROWNUM <= 100; ``` ### Analytical Functions ```sql theme={null} SELECT EMPLOYEE_ID, SALARY, DEPARTMENT_ID, AVG(SALARY) OVER (PARTITION BY DEPARTMENT_ID) AS dept_avg_salary, RANK() OVER (PARTITION BY DEPARTMENT_ID ORDER BY SALARY DESC) AS salary_rank FROM PER_EMPLOYEES WHERE ROWNUM <= 100; ``` ### Date Operations ```sql theme={null} -- Common date filters SELECT * FROM table_name WHERE: -- Last 30 days creation_date >= SYSDATE - 30 -- Current month EXTRACT(MONTH FROM creation_date) = EXTRACT(MONTH FROM SYSDATE) -- Date range creation_date BETWEEN DATE '2024-01-01' AND DATE '2024-12-31' -- Fiscal year creation_date >= ADD_MONTHS(TRUNC(SYSDATE, 'YEAR'), -3) ``` ## Query Optimization Tips ### 1. Use Indexes ```sql theme={null} -- Check available indexes SELECT INDEX_NAME, TABLE_NAME, COLUMN_NAME FROM USER_IND_COLUMNS WHERE TABLE_NAME = 'AP_INVOICES_ALL'; ``` ### 2. Avoid Functions on Indexed Columns ```sql theme={null} -- Bad: Function prevents index use SELECT * FROM employees WHERE UPPER(last_name) = 'SMITH'; -- Good: Use exact match when possible SELECT * FROM employees WHERE last_name = 'Smith'; ``` ### 3. Use EXISTS Instead of IN ```sql theme={null} -- Better performance with EXISTS SELECT * FROM invoices i WHERE EXISTS ( SELECT 1 FROM invoice_lines il WHERE il.invoice_id = i.invoice_id ); ``` ## Working with Bind Variables ### Declaring Variables ```sql theme={null} -- Use bind variables for dynamic queries SELECT INVOICE_NUM, INVOICE_DATE, INVOICE_AMOUNT FROM AP_INVOICES_ALL WHERE SUPPLIER_NAME = :supplier_name AND INVOICE_DATE >= :start_date AND ROWNUM <= :max_rows; ``` When executed, you'll be prompted to enter values for: * `:supplier_name` * `:start_date` * `:max_rows` See [Bind Variables Guide](/koala/editor/bind-variables) for detailed usage ## Multi-line Queries ### Formatting Long Queries ```sql theme={null} SELECT -- Employee Information emp.EMPLOYEE_NUMBER, emp.FIRST_NAME, emp.LAST_NAME, emp.EMAIL_ADDRESS, -- Job Information job.JOB_TITLE, job.JOB_CODE, -- Department Information dept.DEPARTMENT_NAME, dept.DEPARTMENT_CODE, -- Assignment Details asg.ASSIGNMENT_STATUS, asg.EFFECTIVE_START_DATE, asg.EFFECTIVE_END_DATE FROM PER_ALL_PEOPLE_F emp INNER JOIN PER_ALL_ASSIGNMENTS_M asg ON emp.PERSON_ID = asg.PERSON_ID AND SYSDATE BETWEEN asg.EFFECTIVE_START_DATE AND asg.EFFECTIVE_END_DATE LEFT JOIN PER_JOBS job ON asg.JOB_ID = job.JOB_ID LEFT JOIN HR_DEPARTMENTS dept ON asg.ORGANIZATION_ID = dept.ORGANIZATION_ID WHERE emp.PERSON_TYPE = 'EMPLOYEE' AND asg.ASSIGNMENT_TYPE = 'E' AND asg.PRIMARY_FLAG = 'Y' AND ROWNUM <= 100 ORDER BY emp.EMPLOYEE_NUMBER; ``` ## Query Templates ### Data Audit Query ```sql theme={null} -- Audit trail query template SELECT TABLE_NAME, CREATION_DATE, CREATED_BY, LAST_UPDATE_DATE, LAST_UPDATED_BY FROM your_table WHERE LAST_UPDATE_DATE >= SYSDATE - 7 ORDER BY LAST_UPDATE_DATE DESC; ``` ### Count and Group Query ```sql theme={null} -- Summary statistics template SELECT CATEGORY_COLUMN, COUNT(*) AS record_count, SUM(AMOUNT_COLUMN) AS total_amount, AVG(AMOUNT_COLUMN) AS avg_amount, MIN(DATE_COLUMN) AS earliest_date, MAX(DATE_COLUMN) AS latest_date FROM your_table GROUP BY CATEGORY_COLUMN HAVING COUNT(*) > 10 ORDER BY record_count DESC; ``` ## Keyboard Shortcuts | Action | Windows/Linux | Mac | | ------------- | ------------- | ---------------- | | Execute Query | `Ctrl+Enter` | `Cmd+Enter` | | Format SQL | `Shift+Alt+F` | `Shift+Option+F` | | Comment Line | `Ctrl+/` | `Cmd+/` | | Find | `Ctrl+F` | `Cmd+F` | | Replace | `Ctrl+H` | `Cmd+H` | | Save Query | `Ctrl+S` | `Cmd+S` | ## Common Issues and Solutions ### Query Too Slow 1. Add `ROWNUM` limit 2. Use specific columns instead of `*` 3. Add WHERE conditions to filter data 4. Check indexes on filtered columns ### Out of Memory 1. Reduce row limit in settings 2. Select fewer columns 3. Use scheduled reports for large datasets ### Syntax Errors 1. Check for missing commas 2. Verify table/column names 3. Ensure quotes match 4. Check parentheses balance ## Next Steps Learn query execution features Use dynamic query parameters Work with query results Optimize query performance # Features Source: https://docs.btsscorp.com/koala/features Comprehensive overview of Koala Data Explorer capabilities ## Core Features ### SQL Query Editor Professional-grade SQL editing experience powered by Monaco Editor: * **Syntax Highlighting**: Full SQL syntax highlighting for better readability * **IntelliSense** (Paid): Auto-completion for tables, columns, and SQL keywords * **Quick Execute**: Run queries with `Ctrl+Enter` (Windows/Linux) or `Cmd+Enter` (Mac) * **Multi-tab Support** (Paid): Work with multiple queries simultaneously * **Save Queries**: Persist your queries for later use ### Query Execution Powerful query execution with enterprise features: * **Bind Variables**: Support for parameterized queries * **Performance Monitoring** (Paid): Track query execution time and performance metrics * **Row Limits**: Configurable maximum rows (50 in free mode, unlimited in paid) * **Timeout Settings**: Configurable request timeouts for long-running queries * **Error Handling**: Detailed error messages with SOAP fault parsing ### Results Management Advanced data viewing and manipulation: * **Grid View**: Professional data grid powered by AG-Grid * **Sorting & Filtering**: Sort and filter results without re-querying * **Column Selection**: Choose which columns to display * **Cell Selection**: Select and copy individual cells or ranges * **Virtual Scrolling**: Handle large datasets efficiently ### Data Export Multiple export formats for different use cases: * **CSV Export**: Standard comma-separated values format * **JSON Export**: Structured JSON for programmatic use * **Excel Export** (Paid): Native Excel format with formatting preserved * **Clipboard Copy**: Copy selected data to clipboard ## Connection Management ### Authentication Methods * **Basic Authentication**: Username and password (Free) * **OAuth 2.0 PKCE** (Paid): Secure OAuth with Proof Key for Code Exchange * **Windows SSO** (Paid): Simple SAML-based SSO integration with Oracle Fusion * **Enterprise SSO Support**: Integration with identity providers ### Connection Features * **Multiple Connections**: Manage multiple Oracle Fusion environments * **Secure Storage**: Credentials stored using VS Code's SecretStorage API * **Connection Testing**: Validate connections before saving * **Quick Switch**: Easily switch between different connections ## Data Exploration ### Data Sources Explorer (Paid) Browse and explore your Oracle Fusion data model: * **Searchable Catalog**: Find tables and views quickly * **Schema Information**: View table structures and relationships * **Auto-refresh**: Automatically load data sources on connection * **Favorites**: Mark frequently used tables for quick access ### SQL History Track and reuse your query history: * **Recent Queries**: Access your recently executed queries * **Search History**: Find previous queries by content * **History Limits**: 50 entries (Free), 500 entries (Paid) * **Persistent Storage**: History preserved across sessions ## Advanced Features ### Performance Monitor (Paid) Detailed performance analytics: * **Execution Timing**: Track query execution time * **Performance Metrics**: View detailed performance statistics * **Historical Tracking**: Monitor performance trends over time * **Optimization Hints**: Suggestions for query optimization ### BIP Integration Oracle Business Intelligence Publisher integration: * **Report Execution**: Run BIP reports directly from VS Code * **Scheduled Reports**: Support for large dataset processing * **CSV Processing**: Advanced CSV parsing and handling * **Catalog Deployment**: Deploy BIP catalogs ## Configuration Options ### Extension Settings Customize Koala to your workflow: ```json theme={null} { "koalaDataExplorer.timeout": 120000, "koalaDataExplorer.maxRows": 1000, "koalaDataExplorer.autoRefreshDataSources": true, "koalaDataExplorer.logging.enabled": false, "koalaDataExplorer.logging.level": "INFO" } ``` ### Logging & Diagnostics Comprehensive logging for troubleshooting: * **Debug Logging**: Configurable logging levels * **Log Viewer**: Built-in log viewing panel * **Performance Logs**: Track performance issues * **Secure Logging**: Sensitive data redaction ## Security Features ### Data Protection * **Read-Only Access**: Only SELECT queries are allowed * **Encrypted Storage**: Credentials encrypted at rest * **Session Management**: Secure session handling * **No Telemetry**: No usage data collected ### Enterprise Compliance * **OAuth 2.0**: Industry-standard authentication * **SSO Support**: Integration with enterprise identity providers * **Audit Trail**: Query history for compliance tracking * **Secure Communication**: HTTPS-only connections ## User Experience ### Interface Design * **Intuitive Layout**: Clean, professional interface * **Dark Theme Support**: Follows VS Code theme preferences * **Responsive Design**: Adapts to different window sizes * **Keyboard Shortcuts**: Comprehensive keyboard navigation ### Productivity Features * **Quick Actions**: Common tasks accessible via buttons * **Context Menus**: Right-click actions for efficiency * **Status Bar**: Real-time connection and query status * **Progress Indicators**: Visual feedback for long operations ## Feature Comparison | Feature | Free Mode | Paid Mode | | ------------------- | ----------- | ------------------------------ | | Query Tabs | 1 | Unlimited | | Max Rows | 50 (locked) | Configurable | | Authentication | Basic only | Basic, OAuth PKCE, Windows SSO | | Data Sources | ❌ | ✅ | | Excel Export | ❌ | ✅ | | IntelliSense | ❌ | ✅ | | Performance Monitor | ❌ | ✅ | | SQL History | 50 entries | 500 entries | | CSV/JSON Export | ✅ | ✅ | | Bind Variables | ✅ | ✅ | | Grid Features | ✅ | ✅ | ## Coming Soon We're constantly improving Koala Data Explorer Extension. Features in development: * Query templates and snippets * Advanced query builder UI * Data visualization charts * Query sharing and collaboration * Custom keyboard shortcuts * Extended Oracle dialect support ## Next Steps Get started with installation Set up your first connection Learn query editor features Compare free vs paid features # Activity Bar Source: https://docs.btsscorp.com/koala/installation/activity-bar Access Koala Data Explorer from the VS Code Activity Bar ## Quick access Koala adds a dedicated icon to the VS Code Activity Bar (left sidebar) so you can open the full experience with one click. ## Open Koala from the Activity Bar 1. Click the **Koala** icon in the Activity Bar. 2. The Koala panel opens with the query editor at the top and results pane below. 3. Use the left sidebar to switch between **Connections**, **Data Sources**, and recent activity. You can drag the Koala icon to reorder it in the Activity Bar if you use it frequently. ## Panel layout * **Query editor**: Monaco-based SQL editor with execution controls. * **Results grid**: Interactive grid with sorting, filtering, and export actions. * **Data sources sidebar**: Table and view explorer for connected environments. The Activity Bar entry appears after installation. If you do not see it, ensure the extension is enabled for the workspace. # First Connection Setup Source: https://docs.btsscorp.com/koala/installation/first-connection Set up your first connection to Oracle Fusion Cloud ## Quick Start Get connected to Oracle Fusion Cloud in minutes with this step-by-step guide. ## Step 1: Open SQL Query Editor First, open the Koala Data Explorer Extension interface: 1. Open VS Code Command Palette: * Windows/Linux: `Ctrl+Shift+P` * Mac: `Cmd+Shift+P` 2. Type: **"Koala Data Explorer: Open SQL Query Editor"** 3. Press Enter The SQL Query Editor will open in a new tab. ## Step 2: Open Connection Manager In the SQL Query Editor: 1. Look for the **Manage Connections** button in the top-left corner 2. Click the button to open the Connection Manager dialog The Manage Connections button looks like a database icon with a gear. ## Step 3: Add New Connection In the Connection Manager dialog: 1. Click **Add Connection** button 2. Choose your authentication type: * **Basic Auth** (Free): Username and password * **OAuth PKCE** (Paid): Enterprise SSO * **SSO** (Paid): Single Sign-On ## Step 4: Configure Connection ### Basic Authentication (Free) Fill in the connection details: ```json theme={null} { "name": "Production Oracle Fusion", "host": "your-instance.fa.ocs.oraclecloud.com", "username": "your.username@company.com", "password": "your-password" } ``` **Field Descriptions**: * **Name**: Friendly name for this connection (e.g., "Prod", "Test", "Dev") * **Host**: Your Oracle Fusion instance URL (without https\://) * **Username**: Your Oracle Fusion username * **Password**: Your Oracle Fusion password Do not include `https://` in the host field. Enter only the domain name. ### OAuth/SSO Authentication (Paid) For OAuth PKCE authentication: ```json theme={null} { "name": "Production SSO", "host": "your-instance.fa.ocs.oraclecloud.com", "clientId": "your-client-id", "scope": "your-scope", "authorizationUrl": "https://idcs.oracle.com/oauth2/v1/authorize", "tokenUrl": "https://idcs.oracle.com/oauth2/v1/token" } ``` **OAuth Configuration**: * **Client ID**: OAuth application client ID * **Scope**: Required OAuth scopes * **Authorization URL**: IDCS authorization endpoint * **Token URL**: IDCS token endpoint Contact your Oracle Fusion administrator for OAuth configuration details. ## Step 5: Test Connection Before saving: 1. Click **Test Connection** button 2. Wait for the connection test to complete 3. Look for success message: "Connection successful!" If the test fails, check: * Network connectivity to Oracle Fusion * Correct hostname (no typos) * Valid credentials * Firewall/proxy settings ## Step 6: Save Connection Once the test passes: 1. Click **Save** button 2. Connection appears in your connections list 3. Click **Done** to close the dialog ## Step 7: Connect to Oracle Fusion Back in the SQL Query Editor: 1. Find the connection dropdown in the query tab header 2. Select your newly created connection 3. Click the **Connect** button 4. Wait for "Connected" status ## Automatic deployment on first connection Koala verifies and deploys required BIP catalog artifacts automatically when you connect. * **Hash check**: Local artifacts are compared to the remote hash; mismatches trigger a redeploy. * **Progress notifications**: Watch for deployment start, upload, and completion toasts. * **Force redeploy**: Use the button in Managing Connections if you need to push a fresh copy manually. Auto-deployment also runs on reconnect when the remote catalog hash changes. When connected successfully, you'll see: * Green "Connected" status * Data sources loading in the sidebar (Paid feature) * Ready to execute queries ## Step 8: Run Your First Query Try a simple query to verify everything works: ```sql theme={null} -- Get current user information SELECT USER_NAME, USER_GUID, CREATED_BY, CREATION_DATE FROM PER_USERS WHERE ROWNUM <= 10; ``` Press `Ctrl+Enter` (Windows/Linux) or `Cmd+Enter` (Mac) to execute. ## Connection Best Practices ### Naming Conventions Use clear, descriptive names: * ✅ "Production - Finance" * ✅ "DEV Environment" * ✅ "Test Instance - US" * ❌ "Connection 1" * ❌ "Oracle" ### Security Recommendations 1. **Never share credentials**: Each user should use their own account 2. **Use SSO when available**: More secure than basic auth 3. **Rotate passwords regularly**: Update connections after password changes 4. **Limit access**: Only connect to instances you need ### Multiple Environments Organize connections by environment: ``` Production - Primary Production - DR Test - Integration Test - UAT Development - Sprint 1 Development - Sprint 2 ``` ## Common Connection URLs ### Oracle Fusion Cloud ``` # Production your-prod.fa.ocs.oraclecloud.com # Test your-test.fa.ocs.oraclecloud.com # Development your-dev.fa.ocs.oraclecloud.com ``` ### Regional Instances ``` # US Commercial instance.fa.us2.oraclecloud.com # EU Frankfurt instance.fa.eu-frankfurt-1.oraclecloud.com # UK London instance.fa.uk-london-1.oraclecloud.com ``` ## Troubleshooting Connection Issues ### "Connection Failed" Error **Check these common causes**: 1. **Incorrect Host**: * Remove `https://` prefix * Verify no trailing slashes * Check for typos 2. **Invalid Credentials**: * Verify username format * Check password is current * Ensure account isn't locked 3. **Network Issues**: * Test Oracle Fusion access in browser * Check VPN connection if required * Verify firewall rules ### "Timeout" Error Increase timeout in settings: ```json theme={null} { "koalaDataExplorer.timeout": 180000 } ``` ### "Certificate" Error For self-signed certificates: ```json theme={null} { "http.proxyStrictSSL": false } ``` Only disable SSL verification for development/test environments. ### Proxy Configuration If behind a corporate proxy: ```json theme={null} { "http.proxy": "http://proxy.company.com:8080", "http.proxyAuthorization": null } ``` ## Managing Multiple Connections ### Switch Between Connections 1. Use the dropdown in the query tab 2. Select different connection 3. Click Connect ### Edit Existing Connections 1. Open Manage Connections 2. Click edit icon next to connection 3. Update details 4. Test and save ### Delete Connections 1. Open Manage Connections 2. Click delete icon 3. Confirm deletion Deleting a connection doesn't affect saved queries or history. ## Connection Status Indicators | Status | Meaning | Action | | --------------- | ---------------------- | ------------------------- | | 🔴 Disconnected | Not connected | Click Connect button | | 🟡 Connecting | Connection in progress | Wait for completion | | 🟢 Connected | Active connection | Ready to query | | ⚠️ Error | Connection failed | Check credentials/network | ## Next Steps Now that you're connected: Learn to write and execute SQL queries Explore available tables and views Master productivity shortcuts Export query results # Manual Installation Source: https://docs.btsscorp.com/koala/installation/manual-install Install Koala Data Explorer from a VSIX file ## When to Use Manual Installation Manual installation using a VSIX file is useful when: * Your organization blocks VS Code Marketplace access * You need to install a specific version * You're testing a pre-release version * You're in an air-gapped environment * You want to distribute the extension internally ## Obtaining the VSIX File ### Download from Publisher Contact BTSS Corp for the VSIX file: * **Support Portal**: [Submit a request](https://btsscorp.freshdesk.com/support/tickets/new) (recommended) * **Email**: [support@btsscorp.com](mailto:support@btsscorp.com) (alternative) * **Subject**: Request Koala Data Explorer Extension VSIX * Specify the version you need ### Building from Source If you have access to the source code: ```bash theme={null} # Clone the repository git clone [repository-url] cd koala-data-explorer-ext # Install dependencies npm install # Build the extension npm run vscode:prepublish # Package the extension npx vsce package ``` This creates a `.vsix` file in the project directory. ## Installation Methods ### Method 1: Using VS Code UI 1. Open VS Code 2. Go to Extensions view (`Ctrl+Shift+X`) 3. Click the **...** menu at the top of Extensions view 4. Select **Install from VSIX...** 5. Browse to your `.vsix` file 6. Select the file and click **Install** 7. Reload VS Code when prompted ### Method 2: Using Command Palette 1. Open Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`) 2. Type: **Extensions: Install from VSIX...** 3. Select the command 4. Browse to your `.vsix` file 5. Confirm installation ### Method 3: Using Command Line ```bash theme={null} # Basic installation code --install-extension koala-data-explorer-1.1.0.vsix # Force installation (overwrites existing) code --install-extension koala-data-explorer-1.1.0.vsix --force # Install for VS Code Insiders code-insiders --install-extension koala-data-explorer-1.1.0.vsix ``` ### Method 4: Manual Copy (Advanced) For system-wide installation or automation: ```bash theme={null} # Windows copy koala-data-explorer-1.1.0.vsix "%USERPROFILE%\.vscode\extensions\" cd "%USERPROFILE%\.vscode\extensions\" tar -xf koala-data-explorer-1.1.0.vsix # macOS/Linux cp koala-data-explorer-1.1.0.vsix ~/.vscode/extensions/ cd ~/.vscode/extensions/ unzip koala-data-explorer-1.1.0.vsix -d btss-corp.koala-data-explorer-1.1.0 ``` ## Verification After installation, verify the extension: ### Check Extension List 1. Open Extensions view (`Ctrl+Shift+X`) 2. Search for "Koala" 3. Verify "Koala Data Explorer" appears with correct version ### Test Command Availability 1. Open Command Palette (`Ctrl+Shift+P`) 2. Type: "Koala" 3. Verify you see **"Koala Data Explorer: Open SQL Query Editor"** ### Check Installation Directory ```bash theme={null} # List installed extensions code --list-extensions # Should include: # btss-corp.koala-data-explorer ``` ## Offline Installation For completely offline environments: ### 1. Prepare Installation Package On a machine with internet access: ```bash theme={null} # Download extension and dependencies code --install-extension btss-corp.koala-data-explorer cd ~/.vscode/extensions/ tar -czf koala-complete.tar.gz btss-corp.koala-data-explorer-* ``` ### 2. Transfer and Install On the offline machine: ```bash theme={null} # Extract to extensions folder cd ~/.vscode/extensions/ tar -xzf koala-complete.tar.gz # Restart VS Code ``` ## Managing Multiple Versions ### Installing Specific Versions Keep multiple VSIX files with version numbers: ``` koala-data-explorer-1.0.0.vsix koala-data-explorer-1.0.1.vsix koala-data-explorer-1.1.0.vsix ``` ### Switching Versions 1. Uninstall current version 2. Install desired version from VSIX 3. Reload VS Code ### Version Downgrade ```bash theme={null} # Uninstall current version code --uninstall-extension btss-corp.koala-data-explorer # Install older version code --install-extension koala-data-explorer-1.0.0.vsix --force ``` ## Troubleshooting Manual Installation ### VSIX File Not Recognized If VS Code doesn't recognize the VSIX file: * Ensure file extension is `.vsix` (not `.zip`) * Check file isn't corrupted (try re-downloading) * Verify file permissions allow reading ### Installation Permissions Error On Windows: ```powershell theme={null} # Run VS Code as Administrator Start-Process code -Verb RunAs ``` On macOS/Linux: ```bash theme={null} # Fix permissions chmod 644 koala-data-explorer-1.1.0.vsix ``` ### Extension Not Loading After Install 1. Fully restart VS Code (not just reload) 2. Check for conflicts with other extensions 3. Review errors in Help → Toggle Developer Tools 4. Clear extension cache: ```bash theme={null} rm -rf ~/.vscode/extensions/.obsolete ``` ### Dependency Issues If the extension fails due to missing dependencies: 1. Ensure VS Code version >= 1.74.0 2. Install Visual C++ Redistributable (Windows) 3. Check Node.js native modules are compatible ## Deployment Automation ### For IT Administrators Deploy to multiple machines using scripts: **PowerShell (Windows)**: ```powershell theme={null} # Deploy to all users $vsixPath = "\\server\share\koala-data-explorer-1.1.0.vsix" $users = Get-ChildItem "C:\Users" -Directory foreach ($user in $users) { $codePath = Join-Path $user.FullName ".vscode\extensions" if (Test-Path $codePath) { code --install-extension $vsixPath --force } } ``` **Bash (macOS/Linux)**: ```bash theme={null} #!/bin/bash # Deploy to current user VSIX_PATH="/path/to/koala-data-explorer-1.1.0.vsix" for user in /home/*; do if [ -d "$user/.vscode" ]; then sudo -u $(basename "$user") code --install-extension "$VSIX_PATH" fi done ``` ### Using Configuration Management **Ansible Playbook**: ```yaml theme={null} - name: Install Koala Data Explorer hosts: workstations tasks: - name: Copy VSIX file copy: src: koala-data-explorer-1.1.0.vsix dest: /tmp/ - name: Install extension shell: code --install-extension /tmp/koala-data-explorer-1.1.0.vsix become_user: "{{ ansible_user }}" ``` ## Post-Installation Configuration After manual installation: 1. **Verify Installation**: Check extension appears in list 2. **Configure Settings**: Adjust timeout, logging, etc. 3. **Set Up Connection**: Add Oracle Fusion credentials 4. **Activate License**: Enter license key if you have one ## Security Considerations When installing manually: Only install VSIX files from trusted sources. Verify the publisher and file integrity before installation. ### Verify File Integrity Check SHA256 hash if provided: ```bash theme={null} # Windows certutil -hashfile koala-data-explorer-1.1.0.vsix SHA256 # macOS/Linux sha256sum koala-data-explorer-1.1.0.vsix ``` ### Scan for Malware Run security scans before installation: ```bash theme={null} # Example with ClamAV clamscan koala-data-explorer-1.1.0.vsix ``` ## Next Steps After successful manual installation: Set up your Oracle Fusion connection Configure extension settings Activate your license Resolve common issues # Pre-Release Versions Source: https://docs.btsscorp.com/koala/installation/pre-release Try new features early with pre-release versions ## Overview Get early access to new Koala Data Explorer Extension features through VS Code's pre-release channel. Test upcoming improvements and help shape the extension's development. The "Switch to Pre-Release Version" button only appears when a pre-release version is available. ## How to Install ### Switch to Pre-Release 1. **Open Extensions** (`Ctrl+Shift+X` / `Cmd+Shift+X`) 2. **Search for "Koala Data Explorer"** 3. **Click the extension** to view details 4. **Click "Switch to Pre-Release Version"** (when available) 5. **Reload VS Code** when prompted Switch to Pre-Release Version button in VS Code Extensions view The button only appears when there's a pre-release version to install. VS Code automatically manages the pre-release channel. ### Identifying Pre-Release When using a pre-release version: * **"Pre-Release" badge** appears in the Extensions view * **Version info** shows in the extension's About dialog * **More frequent updates** than the stable channel ## Why Try Pre-Release? * **Early access** to new features and improvements * **Help shape development** with your feedback * **Get fixes faster** for reported issues ## Providing Feedback ### Report Issues Submit feedback through our [support portal](https://btsscorp.freshdesk.com/support/tickets/new) or email [support@btsscorp.com](mailto:support@btsscorp.com). Include: * Pre-release version number * Steps to reproduce any issues * Your VS Code version * Operating system ## Switch Back to Stable To return to the stable version: 1. **Open Extensions** 2. **Find Koala Data Explorer** 3. **Click "Switch to Release Version"** 4. **Reload VS Code** ## FAQ ### Is it safe to use? Yes, pre-release versions maintain the same read-only access and security. They may have minor bugs in new features. ### Does it need a separate license? No, your existing license works with both stable and pre-release versions. ### How often are updates released? Pre-release updates are more frequent than stable releases, typically weekly when new features are being developed. ## Next Steps Alternative installation methods Submit feedback or report issues # VS Code Marketplace Installation Source: https://docs.btsscorp.com/koala/installation/vscode-marketplace Install Koala Data Explorer from the VS Code Marketplace ## Quick Installation The easiest way to install Koala Data Explorer Extension is directly from the VS Code Marketplace. ### Method 1: Install from VS Code 1. Open VS Code 2. Click the Extensions icon in the Activity Bar (or press `Ctrl+Shift+X`) 3. Search for "Koala Data Explorer" 4. Click **Install** on the extension by BTSS Corp 5. Wait for installation to complete Make sure you select the official extension published by **btss-corp** ### Method 2: Install from Marketplace Website 1. Visit the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=btss-corp.koala-data-explorer) 2. Click **Install** 3. VS Code will open automatically 4. Confirm the installation in VS Code ### Method 3: Command Palette 1. Open VS Code Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`) 2. Type: `ext install btss-corp.koala-data-explorer` 3. Press Enter to install ## Verify Installation After installation, verify the extension is installed correctly: 1. Open Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`) 2. Type: "Koala" 3. You should see **"Koala Data Explorer: Open SQL Query Editor"** If you see the command, the extension is installed successfully! ## Post-Installation Steps ### 1. Open the SQL Query Editor ```bash theme={null} # Using Command Palette Ctrl+Shift+P (Windows/Linux) Cmd+Shift+P (Mac) # Then type: Koala Data Explorer: Open SQL Query Editor ``` ### 2. Initial Configuration The extension works out of the box, but you can customize settings: 1. Open VS Code Settings (`Ctrl+,` or `Cmd+,`) 2. Search for "Koala" 3. Configure options like timeout, max rows, and logging ### 3. Set Up Your First Connection Once installed, you'll need to: 1. Open the SQL Query Editor 2. Click **Manage Connections** in the top-left 3. Add your Oracle Fusion connection details See [First Connection Setup](/koala/installation/first-connection) for detailed connection instructions ## Extension Information ### Publisher Details * **Publisher**: BTSS Corp (btss-corp) * **Extension ID**: btss-corp.koala-data-explorer * **Version**: Check marketplace for latest * **Size**: \~15 MB ### What Gets Installed The extension includes: * SQL Query Editor with Monaco Editor * Data grid components (AG-Grid) * Oracle Fusion SOAP client * Authentication providers * Export utilities ### Installation Location The extension is installed in your VS Code extensions folder: **Windows**: ``` %USERPROFILE%\.vscode\extensions\btss-corp.koala-data-explorer-x.x.x ``` **macOS/Linux**: ``` ~/.vscode/extensions/btss-corp.koala-data-explorer-x.x.x ``` ## Updating the Extension ### Automatic Updates VS Code automatically checks for extension updates by default. When an update is available: 1. You'll see a notification 2. Click **Update** to install 3. Reload VS Code when prompted ### Manual Update Check 1. Open Extensions view (`Ctrl+Shift+X`) 2. Click the **...** menu 3. Select **Check for Extension Updates** 4. Update Koala Data Explorer if available ### Update Settings Configure auto-update behavior in VS Code settings: ```json theme={null} { "extensions.autoUpdate": true, "extensions.autoCheckUpdates": true } ``` ## Troubleshooting Installation ### Extension Not Found If you can't find the extension: * Ensure VS Code version is 1.74.0 or higher * Check your internet connection * Try searching for "Oracle Fusion" or "BTSS" ### Installation Failed If installation fails: 1. Check VS Code output panel for errors 2. Restart VS Code and try again 3. Clear VS Code cache: ```bash theme={null} # Windows rmdir /s "%APPDATA%\Code\Cache" # macOS/Linux rm -rf ~/.config/Code/Cache ``` ### Extension Not Loading If the extension doesn't appear after installation: 1. Reload VS Code window (`Ctrl+R` or `Cmd+R`) 2. Check extension is enabled in Extensions view 3. Look for errors in Help → Toggle Developer Tools ### Behind Corporate Proxy Configure proxy settings if behind a firewall: ```json theme={null} { "http.proxy": "http://proxy.company.com:8080", "http.proxyStrictSSL": false } ``` ## Uninstalling To remove the extension: 1. Open Extensions view (`Ctrl+Shift+X`) 2. Find Koala Data Explorer 3. Click the gear icon → **Uninstall** 4. Reload VS Code Uninstalling removes the extension but preserves your connections and settings. To completely remove all data, manually delete the extension's storage folder. ## License Activation After installation, the extension runs in Free mode by default. To unlock all features: 1. Open the SQL Query Editor 2. Click the **Manage License** button (key icon) 3. Choose to start a trial or enter a license key 4. Follow the activation prompts See [Licensing Guide](/koala/licensing/activating-license) for detailed license management instructions ## Next Steps Now that you have Koala Data Explorer installed: Set up your first Oracle Fusion connection Configure extension settings Start querying your data Learn all features # Introduction Source: https://docs.btsscorp.com/koala/introduction Professional SQL tool for Oracle Fusion Cloud ## What is Koala Data Explorer Extension? Koala Data Explorer Extension™ (KDEE) is a powerful VS Code extension that enables you to query Oracle Fusion Cloud data directly from your development environment. Built for developers, analysts, and consultants who work with Oracle Fusion, it provides instant access to your enterprise data without the need to navigate slow web portals or complex interfaces. ## Why Koala Data Explorer? ### Save Time Stop wasting hours navigating through Oracle's web interfaces. Connect instantly and query your data in seconds, not minutes. ### Stay in Your Flow Write code, query data, export results - all without leaving VS Code. Perfect for developers who need to validate data while coding. ### Enterprise-Ready Built with security in mind, featuring read-only access, OAuth 2.0 authentication, encrypted credential storage, and enterprise-grade security. ## Key Benefits Connect to Oracle Fusion Cloud and start querying data within seconds Monaco-based editor with syntax highlighting, IntelliSense, and quick execute Sort, filter, and export data in multiple formats including Excel OAuth 2.0, SSO support, and encrypted credential storage ## Who Uses Koala? ### Support Teams Quickly troubleshoot user issues with real-time data access. No more waiting for data extracts or navigating slow portals. ### Implementation Consultants Validate configurations and data conversions during Oracle Fusion implementations. ### Business Analysts Build and test report queries before deployment to production. ### Developers Debug integrations, verify data flows, and validate API responses against actual data. ### Data Migration Teams Validate converted data and reconcile differences during migration projects. ## Free vs Paid Features Koala Data Explorer includes a free mode with essential features, and offers a paid license for advanced capabilities: ### Free Mode * Single query tab * Basic authentication * 50 rows per query limit * CSV/JSON export * SQL History (up to 50 entries) ### Paid Mode * Unlimited query tabs * OAuth PKCE and Windows SSO authentication * Unlimited rows * Excel export * Data sources explorer * IntelliSense autocomplete * Performance monitor * Extended SQL history (500 entries) ## Getting Started Ready to boost your productivity? Here's how to get started: 1. [Install the extension](/koala/installation/vscode-marketplace) from the VS Code marketplace 2. [Set up your first connection](/koala/installation/first-connection) to Oracle Fusion Cloud 3. [Start querying](/koala/editor/writing-queries) your data immediately Want early access to new features? Try our [pre-release versions](/koala/installation/pre-release) and help shape development with your feedback. The extension is designed for read-only access to ensure data safety. It only executes SELECT queries and cannot modify any data in your Oracle Fusion instance. ## System Requirements * **VS Code**: Version 1.74.0 or higher * **Network**: Access to Oracle Fusion Cloud * **Credentials**: Valid Oracle Fusion user credentials ## Support Need help? The BTSS team is here to support you: * **Support Portal**: [Submit a ticket](https://btsscorp.freshdesk.com/support/tickets/new) (recommended) * **Email**: [support@btsscorp.com](mailto:support@btsscorp.com) (alternative contact) * **Response Time**: Within 1-2 business days * **Documentation**: Comprehensive guides and troubleshooting ## Next Steps Learn how to install Koala Data Explorer Explore all available features Set up your first connection Start writing queries # Activating License Source: https://docs.btsscorp.com/koala/licensing/activating-license How to activate your Koala Data Explorer license after purchase ## Overview After your 7-day free trial ends and you decide to continue with Koala Data Explorer Extension, you'll need to activate your paid license. This guide walks you through the activation process. ## Automatic Activation In most cases, your license activates automatically: 1. **Trial ends** after 7 days 2. **Payment processed** via LemonSqueezy 3. **License activated** automatically in VS Code 4. **Full features unlocked** immediately You should see a notification in VS Code confirming your license activation. ## Manual Activation If automatic activation doesn't work, follow these steps: ### Step 1: Locate Your License Key 1. **Check your email** for the purchase confirmation 2. **Visit LemonSqueezy portal**: [My Orders](https://app.lemonsqueezy.com/my-orders/) 3. **Find your order** and copy the license key ### Step 2: Enter License in Extension 1. **Open Koala Data Explorer** in VS Code 2. **Click the Settings gear** in the extension toolbar 3. **Select "License Settings"** 4. **Paste your license key** in the provided field 5. **Click "Activate License"** ### Step 3: Verify Activation After activation, you should see: * ✅ **License status**: "Active" in settings * ✅ **Premium features**: All features unlocked * ✅ **No row limits**: Unlimited query results * ✅ **Excel export**: Available in results panel ## License Features ### Free Mode (Trial/Unlicensed) * Single query tab * Basic authentication only * 50 rows per query limit * CSV/JSON export only * Basic SQL history ### Licensed Mode (Paid) * Unlimited query tabs * OAuth PKCE and Windows SSO authentication * Unlimited rows * Excel export * Data sources explorer * IntelliSense autocomplete * Performance monitor * Extended SQL history ## Troubleshooting Activation ### License Key Not Working **Check these common issues:** 1. **Correct key**: Ensure you copied the full license key 2. **No extra spaces**: Remove any leading/trailing spaces 3. **Active subscription**: Verify your subscription is current 4. **Internet connection**: License validation requires internet access ### Still Not Activating? **Try these steps:** 1. **Restart VS Code** completely 2. **Clear extension cache**: * Close VS Code * Clear VS Code workspace state (if needed) * Reopen and try activation again 3. **Check subscription status** in [LemonSqueezy portal](https://app.lemonsqueezy.com/my-orders/) ### Contact Support If activation still fails: * **Support Portal**: [Submit a ticket](https://btsscorp.freshdesk.com/support/tickets/new) * **Email**: [support@btsscorp.com](mailto:support@btsscorp.com) * **Include**: * Your order number * License key (last 4 characters only) * Error messages or screenshots * VS Code version ## License Management ### Checking License Status To view your current license status: 1. **Open Koala Data Explorer** 2. **Click Settings gear** → **License Settings** 3. **View license information**: * Status (Active/Inactive) * Expiration date * Features included ### Multiple Devices Your license allows installation on: * **Multiple devices** for the same user * **Development and personal use** * **Not for team sharing** (each user needs a license) ### License Renewal Licenses are subscription-based: * **Automatic renewal** through LemonSqueezy * **Email reminders** before expiration * **Grace period** for payment issues * **Reactivation** available after payment resolution ## Subscription Management ### Updating Payment Method 1. **Visit** [LemonSqueezy customer portal](https://app.lemonsqueezy.com/my-orders/) 2. **Find your subscription** 3. **Update payment details** 4. **Save changes** ### Canceling Subscription 1. **Visit** [LemonSqueezy customer portal](https://app.lemonsqueezy.com/my-orders/) 2. **Find your subscription** 3. **Cancel subscription** 4. **Access continues** until current period ends ## Frequently Asked Questions ### Q: Can I use my license on multiple computers? A: Yes, you can install on multiple devices for your personal use. ### Q: What happens if my subscription expires? A: The extension reverts to free mode with basic features only. ### Q: Can I transfer my license to another user? A: No, licenses are non-transferable between users. ### Q: Do I need internet for license validation? A: Yes, initial activation and periodic validation require internet access. ### Q: Can I downgrade from paid to free? A: Yes, cancel your subscription and the extension will revert to free mode. ## Getting Help Need assistance with license activation? * **Documentation**: Check our [troubleshooting guides](/koala/troubleshooting/connection-issues) * **Support Portal**: [Submit a ticket](https://btsscorp.freshdesk.com/support/tickets/new) * **Email**: [support@btsscorp.com](mailto:support@btsscorp.com) * **Response Time**: 24-48 hours We're here to ensure your activation goes smoothly! # Free vs Paid Features Source: https://docs.btsscorp.com/koala/licensing/free-vs-paid Compare free and paid features of Koala Data Explorer ## Feature Comparison Koala Data Explorer Extension offers both free and paid modes to suit different needs. ## Quick Comparison | Feature | Free Mode | Paid Mode | | ------------------------- | ----------- | ------------------------------ | | **Query Tabs** | 1 | Unlimited | | **Max Rows** | 50 (locked) | Unlimited | | **Authentication** | Basic only | Basic, OAuth PKCE, Windows SSO | | **Data Sources Explorer** | ❌ | ✅ | | **Excel Export** | ❌ | ✅ | | **IntelliSense** | ❌ | ✅ | | **Performance Monitor** | ❌ | ✅ | | **SQL History** | 50 entries | 500 entries | | **CSV/JSON Export** | ✅ | ✅ | | **Query Execution** | ✅ | ✅ | | **Grid Features** | ✅ | ✅ | ## Free Mode Features ### What's Included Perfect for basic Oracle Fusion data queries: ✅ **Core Functionality** * Full SQL query editor * Monaco-based editing with syntax highlighting * Query execution with results grid * Basic authentication (username/password) ✅ **Data Export** * CSV export for spreadsheet analysis * JSON export for programmatic use * Copy to clipboard functionality ✅ **Essential Tools** * 50 SQL history entries * Bind variable support * Error handling and messages * Sort and filter results ### Limitations Free mode has these restrictions: ❌ **Single Tab Only** * Work with one query at a time * No multi-tab workflows ❌ **Row Limit** * Maximum 50 rows per query * Cannot be changed in settings ❌ **No Advanced Auth** * Basic authentication only * No OAuth PKCE or Windows SSO support ❌ **No Premium Features** * No data sources explorer * No Excel export * No IntelliSense autocomplete * No performance monitoring ## Paid Mode Features ### Unlimited Productivity 🚀 **Multiple Query Tabs** * Open unlimited query tabs * Work on multiple queries simultaneously * Compare results side-by-side * Organize complex analysis workflows ### Advanced Authentication 🔐 **Enterprise Security** * **OAuth 2.0 PKCE**: Secure token-based authentication with Oracle IAM * **Windows SSO**: Simple SAML-based SSO integration with Oracle Fusion * **Session Management**: Persistent secure sessions * **Multi-factor Authentication**: Supported through enterprise SSO ### Data Exploration 📊 **Data Sources Explorer** * Browse all available tables and views * Search for specific objects * View table structures * Auto-refresh on connection * Favorites for quick access ### Enhanced Export Options 📁 **Excel Export** * Native .xlsx format * Preserve formatting * Multiple sheets support * Large dataset handling * Formula-safe export ### Developer Productivity ⚡ **IntelliSense Autocomplete** * Table name suggestions * Column name completion * SQL keyword hints * Function suggestions * Context-aware recommendations ### Performance Tools 📈 **Performance Monitor** * Query execution timing * Resource usage metrics * Performance history * Optimization suggestions * Bottleneck identification ### Extended History 📝 **SQL History (500 entries)** * 10x more history than free mode * Search through past queries * Persistent across sessions * Quick re-execution * History management tools ## Use Case Recommendations ### When Free Mode is Sufficient Perfect for: * ✅ Occasional data queries * ✅ Simple troubleshooting * ✅ Learning Oracle Fusion * ✅ Basic reporting needs * ✅ Personal use Example users: * Students learning Oracle Fusion * Occasional users checking data * Basic support tasks ### When to Upgrade to Paid Essential for: * ✅ Daily Oracle Fusion work * ✅ Complex data analysis * ✅ Enterprise environments * ✅ Team collaboration * ✅ Production support Example users: * Implementation consultants * Business analysts * Support teams * Data migration specialists * Report developers ## ROI Calculator ### Time Savings **Free Mode Workflow**: * Open web portal: 2 minutes * Navigate to BI: 1 minute * Run query: 3 minutes * Export data: 2 minutes * **Total: 8 minutes per query** **Paid Mode Workflow**: * Already in VS Code: 0 minutes * Run query with IntelliSense: 30 seconds * Excel export: 10 seconds * **Total: 40 seconds per query** **Savings**: 7+ minutes per query ### Monthly Impact For a typical user running 10 queries per day: * Time saved: 70 minutes/day * Monthly savings: 23 hours * Annual savings: 280 hours (7 work weeks!) ## Pricing ### License Options | Plan | Price | Duration | Best For | | ---------- | ------------- | --------- | --------------------- | | **Annual** | Contact Sales | 12 months | Teams & regular users | | **Trial** | Free | Variable | Evaluation | ### Volume Discounts Available for: * 5+ licenses: 10% discount * 10+ licenses: 15% discount * 25+ licenses: 20% discount * Enterprise: Custom pricing Contact [support](https://btsscorp.freshdesk.com/support/tickets/new) or email [support@btsscorp.com](mailto:support@btsscorp.com) for quotes. ## Upgrade Process ### How to Upgrade 1. **Open SQL Editor**: Launch Koala Data Explorer 2. **Click License Button**: Key icon in toolbar 3. **Choose Option**: * Start trial (if available) * Enter license key * Purchase license 4. **Activate**: Follow prompts to activate 5. **Restart**: Reload VS Code if prompted ### Instant Activation * ⚡ No reinstallation needed * ⚡ Immediate feature unlock * ⚡ Preserves all settings * ⚡ Keeps connection data ## License Management ### Check License Status 1. Open SQL Editor 2. Look for license indicator: * 🔓 Free Mode * 🔑 Licensed Mode * ⏰ Trial Mode ### License Transfer Licenses can be transferred: 1. Deactivate on old machine 2. Activate on new machine 3. Contact support for assistance ### Team Licenses For organizations: * Centralized license management * Bulk activation codes * Usage reporting * Priority support ## Frequently Asked Questions ### Can I try before buying? Yes! The extension includes free mode to test basic functionality. Trial licenses may be available in your region. ### What happens when license expires? The extension reverts to free mode. All your data and settings are preserved. ### Can I purchase a license at any time? Yes, you can purchase an annual license at any time. Your subscription begins on the purchase date and renews automatically on the same date next year. ### Is the license per-user or per-machine? Licenses are per-user. You can use on multiple machines you personally use. ### Do you offer educational discounts? Yes, contact [support](https://btsscorp.freshdesk.com/support/tickets/new) or email [support@btsscorp.com](mailto:support@btsscorp.com) with your .edu email for special pricing. ## Making the Decision ### Stay with Free Mode if: * You query data occasionally * 50 rows is sufficient * You don't need Excel export * Single tab meets your needs * Basic auth works for you ### Upgrade to Paid Mode if: * You work with Oracle Fusion daily * You need unlimited data access * Excel export saves you time * SSO is required by your org * Multiple tabs improve workflow * IntelliSense speeds development * Performance monitoring helps optimization ## Support ### Free Mode Support * Documentation access * Community resources * Email support (best effort) ### Paid Mode Support * Priority email support * 1-2 business day response * Technical assistance * License management help ## Next Steps Learn how to activate your license Install the extension Set up your connection Get a quote for your team # Managing License Source: https://docs.btsscorp.com/koala/licensing/managing-license Manage your Koala Data Explorer license, subscription, and billing ## License Dashboard Access your license information through multiple channels: ### In VS Code Extension 1. **Open Koala Data Explorer Extension** 2. **Click Settings gear** → **License Settings** 3. **View current status**: * License status (Active/Inactive/Trial) * Subscription type * Renewal date * Features included ### LemonSqueezy Customer Portal Access your complete subscription details: * **Portal**: [My Orders](https://app.lemonsqueezy.com/my-orders/) * **View**: Order history, invoices, payment methods * **Manage**: Subscription settings, cancellations, updates ## Subscription Types ### Free Trial * **Duration**: 7 days * **Features**: Full access to all premium features * **Billing**: No payment required * **Cancellation**: Cancel anytime with no charges ### Annual Subscription * **Billing**: Every 12 months * **Features**: All premium features included * **Cancellation**: Cancel anytime, access until period ends * **Renewal**: Automatic unless cancelled ## Managing Your Subscription ### Updating Payment Method **Via LemonSqueezy Portal:** 1. **Visit** [customer portal](https://app.lemonsqueezy.com/my-orders/) 2. **Log in** with your purchase email 3. **Find your subscription** 4. **Click "Manage Subscription"** 5. **Update payment details** 6. **Save changes** **Payment Methods Accepted:** * Credit/Debit cards (Visa, MasterCard, Amex) * PayPal * Apple Pay * Google Pay ### Changing Subscription Plan **Upgrade/Downgrade Process:** 1. **Contact support** for plan changes 2. **Email**: [support@btsscorp.com](mailto:support@btsscorp.com) 3. **Include**: Current order number and desired plan 4. **Processing**: Changes take effect next billing cycle ### Canceling Subscription **Option 1: LemonSqueezy Portal** 1. **Visit** [customer portal](https://app.lemonsqueezy.com/my-orders/) 2. **Find your subscription** 3. **Click "Cancel Subscription"** 4. **Confirm cancellation** 5. **Access continues** until current period ends **Option 2: Contact Support** * **Support Portal**: [Submit a ticket](https://btsscorp.freshdesk.com/support/tickets/new) * **Email**: [support@btsscorp.com](mailto:support@btsscorp.com) * **Subject**: "Cancel Subscription - \[Order Number]" ### Reactivating Cancelled Subscription **To reactivate after cancellation:** 1. **Visit** [VS Code marketplace](https://marketplace.visualstudio.com/items?itemName=btss-corp.koala-data-explorer) 2. **Start new trial** or **purchase directly** 3. **Or contact support** to restore previous subscription ## License Validation ### How Validation Works * **Internet required**: Initial activation and periodic checks * **Automatic**: Validates in background during use * **Frequency**: Daily validation when extension is active * **Offline grace**: Works offline for limited time ### Validation Issues **Common problems and solutions:** | Issue | Cause | Solution | | ------------------- | ------------------------ | --------------------------------------- | | "License expired" | Subscription ended | Renew subscription or contact support | | "Validation failed" | Internet connectivity | Check internet connection and retry | | "Invalid license" | Corrupted key | Re-enter license key or contact support | | "License in use" | Used on too many devices | Contact support to reset device count | ## Billing and Invoices ### Accessing Invoices **Via LemonSqueezy:** 1. **Visit** [customer portal](https://app.lemonsqueezy.com/my-orders/) 2. **Find your order** 3. **Download invoice** (PDF format) 4. **View payment history** **For Business/Tax Purposes:** * **VAT included** (where applicable) * **Business details** can be added to invoices * **Receipt emails** sent automatically * **Support available** for invoice questions ### Payment Failures **If payment fails:** 1. **Automatic retry** after 3 days 2. **Email notification** sent to registered email 3. **Grace period** of 7 days to update payment 4. **License deactivated** if payment not resolved **To resolve payment issues:** 1. **Update payment method** in portal 2. **Contact your bank** if card is declined 3. **Email support** if issues persist ## Multi-Device Management ### License Terms * **Single user**: License is for individual use * **Multiple devices**: Install on your computers/devices * **No sharing**: Cannot share with other users * **Team licenses**: Contact sales for team pricing ### Device Limits * **Standard license**: Up to 5 active devices * **Device reset**: Contact support if you need to remove old devices * **New computer**: Automatically activates on new installations ## Account Security ### Protecting Your License **Best practices:** 1. **Keep email secure**: License tied to purchase email 2. **Don't share keys**: License keys are personal 3. **Monitor usage**: Check for unauthorized access 4. **Update passwords**: Keep LemonSqueezy account secure ### Suspicious Activity **If you suspect unauthorized use:** 1. **Contact support immediately** 2. **Change LemonSqueezy password** 3. **Request license reset** 4. **Monitor your account** for unusual activity ## Enterprise Options ### Team Licensing For organizations needing multiple licenses: * **Volume discounts** available * **Centralized billing** options * **Admin controls** for license management * **Contact sales**: [support@btsscorp.com](mailto:support@btsscorp.com) ### Custom Agreements * **Enterprise contracts** available * **Custom payment terms** * **Dedicated support** * **On-premise options** (contact for details) ## Support and Assistance ### License-Related Support **Common requests we help with:** * License activation issues * Payment and billing questions * Subscription changes * Device management * Invoice requests * Refund processing ### Contact Methods * **Support Portal**: [Submit a ticket](https://btsscorp.freshdesk.com/support/tickets/new) * **Email**: [support@btsscorp.com](mailto:support@btsscorp.com) * **Response Time**: 24-48 hours * **Priority**: License issues receive high priority ### Self-Service Resources * **LemonSqueezy Portal**: Manage subscriptions independently * **Documentation**: Complete guides and troubleshooting * **FAQs**: Common questions answered * **Status checks**: Real-time license validation ## Frequently Asked Questions ### Q: Can I pause my subscription temporarily? A: No pause option, but you can cancel and reactivate later. ### Q: What happens to my data if I cancel? A: Local data remains, but premium features become unavailable. ### Q: If I cancel, do I get a refund for unused time? A: No refunds for partial periods, but your access continues until your annual subscription period ends. ### Q: Can I use my license while traveling? A: Yes, but periodic internet validation is required. ### Q: What if my company pays for my license? A: Company can purchase and assign license to your email. ## Getting Started New to license management? Start here: 1. **Check current status** in VS Code extension 2. **Bookmark** [LemonSqueezy portal](https://app.lemonsqueezy.com/my-orders/) 3. **Set calendar reminder** for renewal dates 4. **Contact support** with any questions We're here to make license management as simple as possible! # Refund Policy Source: https://docs.btsscorp.com/koala/licensing/refund-policy 7-day free trial and refund terms for Koala Data Explorer ## 7-Day Free Trial - No Payment Required Try Koala Data Explorer Extension completely **FREE for 7 days** - no credit card required, no payment upfront. Cancel anytime during the trial period with zero charges. ## How Our Risk-Free Trial Works ### Days 1-7: Completely Free * **Full access** to all premium features * **No payment** - trial starts immediately * **Cancel anytime** - no questions asked, no charges * **Keep all data** you've exported during trial * **Automatic billing** only starts after day 7 if you don't cancel ### After Trial: 30-Day Technical Issues Refund * If you continue past the 7-day trial and experience technical issues * **Full refund available** up to 30 days from first payment * Must provide technical details: * VS Code version * Operating system * Error messages or screenshots * We'll work to resolve issues before processing refund * **Full refund** if we cannot resolve the problem ### Subscription Cancellation * Cancel anytime to stop future billing * Access continues until current billing period ends * No refunds for unused portion of current period * Reactivate anytime to restore full access ## Refund Limitations * **After 30 days from first payment**: No refunds available * **Trial period abuse**: Repeated trial signups may be blocked * **Excessive usage**: Refunds may be declined for accounts that have processed extraordinary amounts of data * **Violation of terms**: No refunds for accounts terminated for misuse ## How to Request a Refund ### During Trial Period (Days 1-7) **Cancel anytime with zero charges:** * Via [LemonSqueezy customer portal](https://app.lemonsqueezy.com/my-orders/) (easiest) * Submit a ticket through our [support portal](https://btsscorp.freshdesk.com/support/tickets/new) * Email: [support@btsscorp.com](mailto:support@btsscorp.com) * No order number needed - just your email address ### After Trial Period Submit a ticket through our [support portal](https://btsscorp.freshdesk.com/support/tickets/new) or email [support@btsscorp.com](mailto:support@btsscorp.com). Include the following information: * **Order number** (from your purchase email) * **Email address** used for purchase * **Technical issue details** (VS Code version, OS, error messages) * **Steps you've tried** to resolve the issue ### Processing Time * **Trial cancellation**: Immediate (no payment to refund) * **Technical refund review**: 1-2 business days * **Refund processing**: 2-3 business days * **Refund appears**: 3-5 business days (depending on payment method) ### License Deactivation * License automatically deactivated upon refund or trial end * Extension returns to free mode (basic features only) * All saved connections and settings preserved ## Payment Methods | Payment Method | Refund Method | Processing Time | | -------------- | --------------- | ----------------- | | Credit Card | Same card | 3-5 business days | | PayPal | PayPal account | 1-2 business days | | Apple Pay | Original method | 3-7 business days | | Google Pay | Original method | 3-7 business days | ## Customer Support ### Before Requesting a Refund We'd love to help resolve any issues you're experiencing: * **Support Portal**: [Submit a ticket](https://btsscorp.freshdesk.com/support/tickets/new) * **Email**: [support@btsscorp.com](mailto:support@btsscorp.com) (alternative contact) * **Response Time**: 24-48 hours * **Documentation**: [Help Center](https://docs.btsscorp.com) ### Common Issues We Can Resolve * License activation problems * Connection configuration * Oracle Fusion compatibility * VS Code integration issues * Performance optimization * Feature usage questions ## Data Privacy When you request a refund: * All personal data deleted from our systems * License key immediately deactivated * Subscription cancelled in LemonSqueezy * No further billing * Local VS Code data remains (your choice to remove) ## Common Scenarios ### Scenario 1: Not What You Expected *"I tried the extension but it doesn't meet my needs."* * **During 7-day trial**: Simply cancel - no charges, no questions asked * **Action**: Cancel via [LemonSqueezy portal](https://app.lemonsqueezy.com/my-orders/) or contact support ### Scenario 2: Technical Problems During Trial *"The extension crashes every time I try to connect to Oracle Fusion."* * **During trial**: We'll help troubleshoot to ensure you get full trial value * **Action**: Contact support immediately with error details ### Scenario 3: Technical Problems After Trial *"The extension worked fine during trial but now has issues."* * **Within 30 days of first payment**: We'll troubleshoot first, refund if unfixable * **Action**: Contact support with detailed error information ### Scenario 4: Subscription Management *"I want to pause my subscription for a few months."* * **Any time**: Cancel subscription, access continues until current period ends * **Action**: Visit [LemonSqueezy customer portal](https://app.lemonsqueezy.com/my-orders/) or contact support ### Scenario 5: Forgot to Cancel Trial *"I forgot to cancel and was charged, but I don't need the extension."* * **Within 30 days**: Technical issues refund policy applies * **Action**: Contact support - we'll work with you on this ## Fair Use Policy Our trial and refund policy is designed to be fair to all customers. We reserve the right to: * Block repeated trial signups from the same user/organization * Decline refunds for accounts showing signs of abuse * Request additional verification for unusual usage patterns * Permanently ban accounts that abuse our trial or refund system ## International Refunds * **All regions supported** where LemonSqueezy operates * **Currency**: Refunded in original purchase currency * **Taxes**: Tax refunds processed according to local regulations * **Bank fees**: Not covered by us (rare, usually minimal) ## Terms and Conditions This refund policy is part of our Terms of Service. By purchasing Koala Data Explorer, you agree to these terms. * Policy subject to change with 30-day notice * Changes don't affect existing purchases * Most restrictive policy applies (our policy vs. platform policy) ## Our Commitment At BTSS Corp, we're committed to: * **Risk-free trial** - 7 days to evaluate, no payment required * **Transparent pricing** - no hidden fees, clear billing * **Fair policies** - reasonable and customer-friendly * **Excellent support** - we want you to succeed * **Continuous improvement** - your feedback makes us better ## Quick Contact **Questions about your trial or need to cancel?** * **Support Portal**: [Submit a ticket](https://btsscorp.freshdesk.com/support/tickets/new) * **Email**: [support@btsscorp.com](mailto:support@btsscorp.com) * **Response**: Within 24-48 hours * **Subject**: * "Cancel Trial" (during trial period) * "Technical Issue Refund - \[Order Number]" (after trial) **Customer Portal**: [LemonSqueezy Account](https://app.lemonsqueezy.com/my-orders/) We're here to help make your Oracle Fusion Cloud experience amazing! *** *Last updated: December 2024*\ *BTSS Corp - Koala Data Explorer Team* # System Requirements Source: https://docs.btsscorp.com/koala/requirements Prerequisites and system requirements for Koala Data Explorer ## Minimum Requirements Before installing Koala Data Explorer Extension, ensure your system meets these requirements: ### VS Code * **Version**: 1.74.0 or higher * **Platform**: Windows, macOS, or Linux * **Architecture**: x64, ARM64, or Universal You can check your VS Code version by going to **Help → About** in the menu bar. ### Operating System #### Windows * Windows 10 version 1809 or higher * Windows 11 * Windows Server 2019 or higher #### macOS * macOS 10.15 (Catalina) or higher * Apple Silicon (M1/M2) supported #### Linux * Ubuntu 18.04 or higher * Debian 9 or higher * RHEL 7 or higher * Fedora 28 or higher ### Network Requirements #### Oracle Fusion Access * Network connectivity to your Oracle Fusion Cloud instance * HTTPS access (port 443) to Oracle Fusion endpoints * Firewall rules allowing outbound HTTPS connections #### Proxy Support * HTTP/HTTPS proxy configuration supported * Authentication proxy support via VS Code settings * SOCKS proxy support If your organization uses a corporate proxy, you may need to configure VS Code's proxy settings. See [Proxy Configuration](#proxy-configuration) below. ### Oracle Fusion Requirements #### User Account * Valid Oracle Fusion Cloud user account * Appropriate data access permissions * BI Publisher access (for report features) #### Supported Versions * Oracle Fusion Cloud Release 13 or higher * Oracle Cloud Infrastructure (OCI) hosted instances * On-premise Oracle Fusion (with internet connectivity) #### Required Services * Oracle BI Publisher Web Services * Oracle Fusion Security Token Service * Oracle Fusion Data Model access ## Recommended Specifications For optimal performance, we recommend: ### Hardware * **CPU**: 2+ cores, 2.0 GHz or faster * **RAM**: 8 GB or more * **Storage**: 500 MB free space for extension and cache * **Display**: 1920x1080 resolution or higher ### Network * **Bandwidth**: 10 Mbps or higher * **Latency**: \< 100ms to Oracle Fusion instance * **Stable Connection**: Persistent connection recommended ## Browser Requirements For OAuth/SSO authentication (Paid feature): ### Supported Browsers * Chrome 90 or higher * Edge 90 or higher * Firefox 88 or higher * Safari 14 or higher The default system browser is used for OAuth authentication flows. ## Dependencies Koala Data Explorer automatically manages its dependencies, but these are installed: ### Runtime Dependencies * Monaco Editor for SQL editing * AG-Grid for data grid functionality * React for UI components * Node-fetch for API calls * Fast-xml-parser for SOAP parsing ### Optional Dependencies * XLSX library for Excel export (Paid feature) * PapaParse for CSV processing ## Proxy Configuration If you're behind a corporate proxy, configure VS Code settings: ```json theme={null} { "http.proxy": "http://proxy.company.com:8080", "http.proxyStrictSSL": false, "http.proxyAuthorization": null } ``` ### Proxy Authentication For authenticated proxies: 1. Open VS Code settings (`Ctrl+,` or `Cmd+,`) 2. Search for "proxy" 3. Configure `http.proxy` with credentials: ``` http://username:password@proxy.company.com:8080 ``` Storing passwords in settings is not recommended. Consider using environment variables or proxy auto-configuration. ## Permissions Required ### VS Code Permissions * File system access for query storage * Secret storage for credentials * Webview for UI rendering * Network access for API calls ### Oracle Fusion Permissions The user account needs these minimum permissions: * **Data Access**: Read access to required tables/views * **BI Publisher**: View and execute reports * **Web Services**: Access to SOAP endpoints ### Recommended Roles * BI Administrator * BI Consumer * Data Analyst * Report Developer ## Troubleshooting Requirements ### Check VS Code Version ```bash theme={null} code --version ``` ### Test Network Connectivity ```bash theme={null} # Test Oracle Fusion connectivity curl -I https://your-instance.fa.ocs.oraclecloud.com ``` ### Verify Proxy Settings ```bash theme={null} # Check environment variables echo $HTTP_PROXY echo $HTTPS_PROXY ``` ## Platform-Specific Notes ### Windows * May require Windows WebView2 Runtime for SSO features * Administrator rights not required for installation ### macOS * May prompt for keychain access for credential storage * Gatekeeper approval may be needed on first run ### Linux * libsecret required for credential storage * May need to install gnome-keyring or similar ## Performance Considerations ### Large Datasets * For datasets > 10,000 rows, consider using scheduled reports * Increase VS Code memory limit if needed: ```bash theme={null} code --max-memory=4096 ``` ### Multiple Connections * Each connection consumes \~50-100 MB RAM * Limit concurrent connections for better performance ### Query Optimization * Use row limits for exploratory queries * Add WHERE clauses to reduce data transfer * Consider indexing frequently queried columns ## Security Requirements ### Network Security * TLS 1.2 or higher required * Certificate validation enabled by default * Support for custom CA certificates ### Credential Storage * VS Code SecretStorage API used * Platform-specific secure storage: * Windows: Credential Manager * macOS: Keychain * Linux: libsecret ## Next Steps Once you've verified all requirements are met: Install from VS Code Marketplace Install from VSIX file Set up your first connection Resolve common issues # Excel Export Source: https://docs.btsscorp.com/koala/results/excel-export Export query results to Excel format with professional formatting ## Overview Koala Data Explorer Extension's Excel export feature creates professional .xlsx files from your query results. This feature is available in the paid version and provides formatted spreadsheets ready for business use. Excel export (.xlsx) is available in the paid version of Koala Data Explorer and supports unlimited rows up to Excel's native sheet capacity. ## Excel Export Features ### Professional Formatting Excel exports include: * **Formatted headers**: Bold column headers * **Data types**: Numbers, dates, and text properly formatted * **Auto-sized columns**: Column widths adjusted to content * **Professional appearance**: Clean, business-ready formatting ### Data Type Handling Koala automatically formats data types in Excel: * **Numbers**: Right-aligned with appropriate decimal places * **Dates**: Proper Excel date format * **Text**: Left-aligned with proper spacing * **Null values**: Displayed as empty cells ## How to Export to Excel ### Quick Export 1. Execute your query to get results 2. Click the "Export" button in the results toolbar 3. Select "Excel (.xlsx)" format 4. Choose save location 5. File is created with professional formatting ### What's Included Each Excel export contains: * **Data sheet**: Your query results with formatting * **Column headers**: Descriptive column names * **Proper data types**: Numbers, dates, text formatted correctly * **Professional styling**: Clean, readable format ## Excel File Features ### Formatting * **Headers**: Bold formatting for easy identification * **Data alignment**: Numbers right-aligned, text left-aligned * **Column sizing**: Automatic width adjustment * **Clean appearance**: Professional business format ### Compatibility Excel files work with: * **Microsoft Excel**: All modern versions * **Google Sheets**: Import and edit online * **LibreOffice Calc**: Open source alternative * **Apple Numbers**: Mac spreadsheet application ## Use Cases ### Business Reporting Perfect for: * **Financial reports**: Formatted numbers and dates * **Data analysis**: Ready for Excel pivot tables and charts * **Presentations**: Professional appearance for meetings * **Sharing data**: Universal Excel format ### Data Analysis Excel files enable: * **Further analysis**: Use Excel's built-in tools * **Pivot tables**: Create summaries and aggregations * **Charts**: Visualize your data * **Formulas**: Add calculations and analysis ## File Size Considerations ### Large Datasets For large result sets: * **Koala streaming**: Koala streams rows until Excel's native limit (1,048,576 rows per sheet). * **File size**: Larger datasets create bigger files; allow extra time for saving. * **Performance**: Very large files may open slowly in Excel; consider CSV if you only need raw data. ### Row Limitations Excel export limitations: * **Free version**: Limited to 50 rows * **Paid version**: Unlimited until Excel's sheet limit * **Configured Max Rows**: If you set `maxRows`, Koala honors it before export ### Optimization Tips For better performance: 1. **Adjust row limits**: Configure `maxRows` setting for your needs 2. **Use SQL limits**: Add `WHERE ROWNUM <= n` in queries 3. **Select specific columns**: Avoid SELECT \* for wide tables 4. **Filter data**: Apply WHERE clauses to reduce data volume ## Troubleshooting ### Common Issues #### "Excel export not available" * Check that you are on the paid version (Excel export is disabled in free mode) * Verify no workspace policy is forcing CSV/JSON only * If the button is disabled, confirm a result set exists and the query finished executing #### "File too large" * Reduce the number of rows in your query if Excel opens slowly * Select fewer columns to decrease file size * Use CSV format for extremely large datasets or automation #### "Excel won't open file" * Ensure you have Excel or compatible software * Check file isn't corrupted * Try opening in Google Sheets or LibreOffice #### "Formatting looks wrong" * Verify data types in your query * Check for special characters in data * Ensure proper date formats in Oracle ### Performance Issues If Excel export is slow: 1. **Reduce data size**: Add ROWNUM limits to queries 2. **Fewer columns**: Select only needed columns 3. **Check available memory**: Close other applications 4. **Try CSV first**: Test with smaller datasets ## Best Practices ### Query Optimization For best Excel exports: 1. **Use column aliases**: `SELECT employee_id AS "Employee ID"` 2. **Format dates**: Use TO\_CHAR for specific date formats 3. **Limit rows**: Add `WHERE ROWNUM <= 1000` for testing 4. **Select specific columns**: Avoid `SELECT *` ### File Management Organize your Excel exports: 1. **Descriptive names**: Include date and query purpose 2. **Consistent location**: Save to organized folder structure 3. **Regular cleanup**: Remove old export files 4. **Version control**: Track different versions if needed ### Business Use Make exports business-ready: 1. **Clear column names**: Use meaningful aliases 2. **Appropriate data types**: Ensure proper formatting 3. **Complete data**: Include all necessary columns 4. **Document purpose**: Note what the data represents ## Comparison with Other Formats ### Excel vs CSV | Feature | Excel | CSV | | ------------- | --------------------- | ---------------- | | Formatting | ✅ Professional | ❌ Plain text | | Data types | ✅ Preserved | ❌ All text | | File size | Larger | Smaller | | Compatibility | Excel software needed | Universal | | Business use | ✅ Ready to present | Needs formatting | ### When to Use Excel Choose Excel export when: * **Presenting to business users**: Professional appearance matters * **Further analysis needed**: Will use Excel features * **Moderate data size**: Under 100,000 rows typically * **Mixed data types**: Numbers, dates, text all present ### When to Use CSV Choose CSV export when: * **Very large datasets**: Over 100,000 rows * **System integration**: Importing to other systems * **Universal compatibility**: No Excel software available * **Smaller file size**: Storage or transfer limitations ## Next Steps Explore available data sources Manage your query history # Exporting Data Source: https://docs.btsscorp.com/koala/results/exporting-data Export query results to CSV, JSON, and Excel formats ## Overview Koala Data Explorer Extension allows you to export your query results to common file formats for further analysis, sharing, or reporting. Right-click anywhere in the results grid to open the export menu for one-click CSV, JSON, Excel, or **Export Selected** actions. ## Available Export Formats ### Free Version * **CSV**: Comma-separated values * **JSON**: JavaScript Object Notation ### Paid Version * **Excel (.xlsx)**: Excel workbook format with unlimited rows (subject only to Excel's native limits) ## How to Export ### Export Steps 1. Execute your query to get results 2. Click the "Export" button in the results toolbar **or** right-click inside the grid and choose an export option 3. Select your desired format (CSV, JSON, or Excel) 4. Choose save location 5. File is saved You can also right-click inside the grid to open the export context menu for quick CSV/JSON/Excel export. ### Export Button Location The Export button appears in the results panel toolbar after you run a query and get results. ## Export Formats ### CSV Export **Comma-Separated Values** format: * Universal compatibility with spreadsheet applications * Plain text format * Includes column headers * Configurable delimiter (comma, semicolon, tab) Example CSV output: ```csv theme={null} employee_id,first_name,last_name,email 100,Steven,King,SKING@oracle.com 101,Neena,Kochhar,NKOCHHAR@oracle.com ``` ### JSON Export **JavaScript Object Notation** format: * Structured data format * Good for API integration * Array of objects format Example JSON output: ```json theme={null} [ { "employee_id": 100, "first_name": "Steven", "last_name": "King", "email": "SKING@oracle.com" }, { "employee_id": 101, "first_name": "Neena", "last_name": "Kochhar", "email": "NKOCHHAR@oracle.com" } ] ``` ### Excel Export (Paid) **Excel (.xlsx)** format: * Professional formatting * Proper data types * Ready for business use * See [Excel Export Guide](/koala/results/excel-export) for detailed information * Unlimited export size for paid users; Koala streams data until Excel's native sheet limit ### Export selected rows * Highlight one or more rows and choose **Export Selected** from the context menu. * Useful for sharing filtered subsets without re-running the query. * Right-click → **Export** also shows CSV/JSON/Excel options scoped to your current selection. ## Export Options ### Basic Options When exporting, you can configure: * **Include headers**: Column names in first row * **File location**: Where to save the export * **Delimiter** (CSV only): Comma, semicolon, or tab ### Row Limits Exports respect the configured row limits: * **Free version**: Maximum 50 rows * **Paid version**: Unlimited Excel exports; CSV/JSON follow your configured `maxRows` value if set ## Use Cases ### CSV Export * **Spreadsheet analysis**: Open in Excel, Google Sheets * **Data exchange**: Universal format for sharing * **System integration**: Import into other applications ### JSON Export * **API development**: Structured data for applications * **Web development**: JavaScript-friendly format * **Data processing**: Programmatic data handling ### Excel Export (Paid) * **Business reporting**: Professional formatted reports * **Presentations**: Ready-to-share spreadsheets * **Analysis**: Use Excel's built-in tools ## Best Practices ### Before Exporting 1. **Limit your data**: Use appropriate row limits 2. **Select needed columns**: Avoid SELECT \* for large tables 3. **Clean your query**: Remove test data or filters ### Choosing Format * **CSV**: For general data sharing and analysis * **JSON**: For technical/development use * **Excel**: For business reports and presentations ### File Management * **Descriptive names**: Include date and query purpose * **Organized storage**: Keep exports in project folders * **Regular cleanup**: Remove old export files ## Troubleshooting ### Export Issues #### "No data to export" * Ensure your query returned results * Check that query execution completed successfully #### "Export failed" * Check file permissions at save location * Ensure sufficient disk space * Try a different save location #### "Excel export not available" * Excel export requires the paid version; verify your license * Ensure the query finished and results are visible before exporting * If the button stays disabled, check workspace policies that may force CSV/JSON only #### "File too large" * Reduce row count in your query * Use CSV instead of Excel for very large datasets * Apply more restrictive WHERE clauses ### Performance Tips For large exports: 1. **Use row limits**: Add `WHERE ROWNUM <= 50000` when you want faster Excel saves 2. **Select specific columns**: Avoid unnecessary columns 3. **Choose appropriate format**: Use CSV for automation or extremely large datasets; Excel for analysis and presentation ## File Compatibility ### CSV Files * **Excel**: Opens directly * **Google Sheets**: Import capability * **Text editors**: Readable as plain text * **Database tools**: Universal import format ### JSON Files * **Code editors**: Syntax highlighting and formatting * **Web browsers**: Can view formatted JSON * **Programming languages**: Native support in most languages ### Excel Files (Paid) * **Microsoft Excel**: Native format * **Google Sheets**: Import and convert * **LibreOffice Calc**: Open and edit * **Numbers (Mac)**: Import capability ## Next Steps Learn about Excel export features Working with query results # In-Grid Search Source: https://docs.btsscorp.com/koala/results/in-grid-search Search results with Ctrl/Cmd + F and jump through matches instantly. ## Overview Use in-grid search to quickly locate values without exporting data. ## Start a search 1. Click inside the results grid. 2. Press `Ctrl+F` (Windows/Linux) or `Cmd+F` (Mac). 3. The search bar appears above the grid with the first match highlighted. ## Navigate matches * **Next/Previous**: Use the arrows in the search bar or press `Enter` / `Shift+Enter`. * **Highlighting**: All matches are highlighted; the active match stays focused as you navigate. * **Selection aware**: Searches the current results set, respecting applied filters and sorting. ## Tips * Use column sorting first to cluster similar values before searching. * Combine with row selection to export only the rows that match. # Sorting & Filtering Source: https://docs.btsscorp.com/koala/results/sorting-filtering Sort and filter query results to analyze your data effectively ## Overview Koala Data Explorer Extension provides powerful sorting and filtering capabilities to help you analyze query results. These features allow you to focus on specific data subsets and organize results for better insights. ## Sorting Data ### Basic Sorting #### Single Column Sort Click any column header to sort: 1. **First click**: Sort ascending (A-Z, 0-9, oldest-newest) 2. **Second click**: Sort descending (Z-A, 9-0, newest-oldest) 3. **Third click**: Remove sort (return to original order) #### Sort Indicators Column headers show sort direction: * **▲**: Ascending sort * **▼**: Descending sort * **No arrow**: No sort applied ### Multi-Column Sorting Multi-column sorting is available in the paid version. Sort by multiple columns for complex ordering: 1. Click first column header 2. Hold `Ctrl` and click additional columns 3. Sort priority shown by numbers (1, 2, 3...) 4. Drag columns in sort panel to reorder priority #### Sort Priority When sorting by multiple columns: * Primary sort: Most important ordering * Secondary sort: Applied within primary groups * Tertiary sort: Applied within secondary groups Example: Sort employees by Department (primary), then Salary (secondary) ### Sort Types by Data Type #### Text Sorting * **Ascending**: A-Z alphabetical * **Descending**: Z-A reverse alphabetical * **Case sensitivity**: Configurable (default: case-insensitive) * **Natural sorting**: Numbers in text sorted numerically #### Numeric Sorting * **Ascending**: Smallest to largest * **Descending**: Largest to smallest * **NULL handling**: NULLs first or last (configurable) * **Scientific notation**: Handled correctly #### Date Sorting * **Ascending**: Oldest to newest * **Descending**: Newest to oldest * **Time component**: Included in sort order * **Time zones**: Respected in sorting ### Custom Sort Options #### Sort Settings Configure sorting behavior: ```json theme={null} { "koala.results.sorting.nullsFirst": true, "koala.results.sorting.caseSensitive": false, "koala.results.sorting.naturalSort": true, "koala.results.sorting.maxColumns": 5 } ``` #### Sort Menu Right-click column header for advanced options: * Sort A-Z / Z-A * Custom sort * Clear sort * Sort options ## Filtering Data ### Quick Filter #### Text Filter Use the filter box at the top of results: 1. Type text to search across all visible columns 2. Results immediately update as you type 3. Case-insensitive by default 4. Searches all text-based columns #### Filter Operators Use operators for precise filtering: ``` =value Exact match !=value Not equal >value Greater than >=value Greater than or equal value * **Greater than or equal**: >= value * **Less than**: \< value * **Less than or equal**: \<= value * **Between**: Range of values * **Top N**: Highest N values * **Bottom N**: Lowest N values #### Date Column Filters For date columns: * **Equals**: Specific date * **Before**: Earlier than date * **After**: Later than date * **Between**: Date range * **Last N days**: Recent period * **This week/month/year**: Current period * **Custom range**: Flexible date picker ### Advanced Filtering #### Multiple Filters Apply filters to multiple columns: 1. Each column filter is independent 2. Results show rows matching ALL filters (AND logic) 3. Filter summary shows active filters 4. Clear individual or all filters #### Filter Expressions Advanced filter expressions are available in the paid version. Create complex filter expressions: ```sql theme={null} -- Filter by expression department_id IN (10, 20, 30) AND salary > 50000 AND hire_date > '2020-01-01' ``` #### Saved Filters Save frequently used filters: 1. Apply desired filters 2. Click "Save Filter" 3. Name the filter configuration 4. Reuse with one click ### Filter Panel #### Filter Manager Access the filter panel: * Click filter icon in toolbar * Press `Ctrl+Shift+F` * Shows all active filters * Modify or remove filters #### Filter Information The filter panel displays: * **Active filters**: Currently applied filters * **Affected rows**: Count of matching rows * **Filter logic**: How filters combine * **Performance**: Filter execution time ## Combined Sorting and Filtering ### Workflow Common workflow for data analysis: 1. **Filter first**: Reduce data to relevant subset 2. **Then sort**: Order the filtered results 3. **Analyze**: Focus on specific patterns 4. **Export**: Save the filtered and sorted view ### Performance Optimization #### Efficient Filtering Best practices for performance: 1. Filter early in the query when possible 2. Use indexed columns for filtering 3. Apply most selective filters first 4. Combine filters in SQL for better performance #### Sorting Performance Optimize sorting: 1. Sort by indexed columns when possible 2. Limit result set before sorting 3. Use database sorting (ORDER BY) for large datasets 4. Consider composite indexes for multi-column sorts ## Visual Indicators ### Active Filters Visual cues for active filters: * **Column headers**: Filter icon shows when filtered * **Status bar**: Shows "Filtered: X of Y rows" * **Filter panel**: Lists all active filters * **Row striping**: Maintains readability ### Sort Indicators Visual cues for sorting: * **Arrow icons**: Show sort direction * **Numbers**: Show sort priority for multi-column * **Column highlighting**: Sorted columns highlighted * **Status bar**: Shows current sort configuration ## Keyboard Shortcuts ### Sorting Shortcuts | Action | Shortcut | Description | | ----------------- | ------------ | ------------------------------- | | Sort ascending | `Alt+↑` | Sort current column ascending | | Sort descending | `Alt+↓` | Sort current column descending | | Clear sort | `Alt+0` | Remove sort from current column | | Multi-column sort | `Ctrl+click` | Add column to sort | ### Filtering Shortcuts | Action | Shortcut | Description | | ------------- | -------------- | ------------------------------ | | Open filter | `Ctrl+F` | Open quick filter box | | Column filter | `Alt+F` | Open filter for current column | | Clear filters | `Ctrl+Shift+F` | Clear all filters | | Next filtered | `F3` | Jump to next filtered result | ## Common Use Cases ### Data Analysis #### Find Top Performers ``` 1. Filter: department_id = 'SALES' 2. Sort: commission_pct DESC 3. Result: Top sales performers by commission ``` #### Identify Recent Changes ``` 1. Filter: last_update_date > '2024-01-01' 2. Sort: last_update_date DESC 3. Result: Most recently updated records ``` #### Range Analysis ``` 1. Filter: salary BETWEEN 50000 AND 100000 2. Sort: salary ASC 3. Result: Salary distribution in range ``` ### Quality Assurance #### Find Data Issues ``` 1. Filter: email NOT LIKE '%@%' 2. Result: Invalid email addresses ``` #### Null Value Detection ``` 1. Filter: important_field IS NULL 2. Result: Records missing critical data ``` ## Common Filter Types ### Text Filters * **Contains**: Search for text within values * **Equals**: Exact match * **Starts with**: Values beginning with text * **Ends with**: Values ending with text ### Numeric Filters * **Equals**: Exact numeric value * **Greater than**: Values above threshold * **Less than**: Values below threshold * **Between**: Values within range ### Date Filters * **Equals**: Specific date * **Before**: Earlier than date * **After**: Later than date * **Between**: Date range ## Troubleshooting ### Performance Issues If sorting/filtering is slow: 1. Check result set size 2. Consider database-side filtering (WHERE clause) 3. Reduce number of columns 4. Use simpler filter expressions ### Memory Issues For large result sets: 1. Apply filters before sorting 2. Use database sorting when possible 3. Limit visible columns 4. Consider exporting filtered results ### Filter Not Working If filters don't work as expected: 1. Check data types 2. Verify null value handling 3. Test with simpler expressions 4. Clear and reapply filters ## Best Practices ### Performance 1. Filter first, then sort 2. Use SQL WHERE clauses for large datasets 3. Be specific with filter criteria ### Data Analysis 1. Start with broad filters, then narrow down 2. Combine sorting and filtering for better insights 3. Export filtered results for further analysis ## Next Steps Export filtered and sorted results Advanced Excel export features # Viewing Data Source: https://docs.btsscorp.com/koala/results/viewing-data Navigate and explore query results in Koala Data Explorer ## Overview Koala Data Explorer Extension provides a powerful results viewer that helps you explore, analyze, and understand your Oracle Fusion Cloud data. This guide covers all features available for viewing and interacting with query results. ## Results Panel ### Layout The results panel appears below the query editor and includes: * **Data Grid**: Tabular display of results * **Status Bar**: Row count, execution time, and messages * **Toolbar**: Actions for export, refresh, and settings * **Column Headers**: Sortable column names with data types ### Panel Controls #### Resize Panel * Drag the divider between editor and results * Double-click to auto-resize * Use `Ctrl+R` to focus on results panel #### Toggle Visibility * Hide/show results with `Ctrl+Shift+R` * Pin results to keep visible * Minimize to status bar only * Collapse/expand using the chevron in the results header ## Data Grid Features ### Column Display Each column shows: * **Column Name**: Original database column name * **Data Type**: Oracle data type (VARCHAR2, NUMBER, DATE, etc.) * **Null Indicator**: Shows if column allows NULL values * **Sort Direction**: Arrow indicating sort order ### Row Display Each row includes: * **Row Number**: Sequential number starting from 1 * **Data Values**: Formatted according to data type * **NULL Values**: Displayed as "(null)" in italic gray * **Row Selection**: Click row number to select entire row ### Cell Features #### Data Types Different data types are formatted distinctly: ``` VARCHAR2/CHAR : Left-aligned text NUMBER : Right-aligned numbers with appropriate decimals DATE/TIMESTAMP : Formatted date/time strings CLOB/BLOB : Shows data type with size indicator NULL : (null) in gray italics ``` #### Cell Selection * Click any cell to select * Drag to select multiple cells * Use keyboard arrows to navigate * `Ctrl+A` selects all data #### Cell Content * Long text shows first 100 characters * Hover for full content tooltip * Double-click to open in detailed view * Right-click for context menu ## Navigation ### In-grid search (Ctrl/Cmd + F) 1. Click inside the grid and press `Ctrl+F` (Windows/Linux) or `Cmd+F` (Mac). 2. A search bar appears above the grid; the first match is highlighted. 3. Use the arrows in the search bar or `Enter` / `Shift+Enter` to move between matches. In-grid search respects current sorting and filters, so narrow results first for faster navigation. ### Keyboard Navigation | Key | Action | | ------------------- | ----------------------------- | | `Arrow Keys` | Move between cells | | `Home/End` | First/last column in row | | `Ctrl+Home/End` | First/last cell in grid | | `Page Up/Down` | Scroll one page | | `Ctrl+Page Up/Down` | First/last page | | `Tab` | Next cell (wraps to next row) | | `Shift+Tab` | Previous cell | ### Mouse Navigation * **Click**: Select cell * **Double-click**: Open detailed view * **Scroll wheel**: Vertical scrolling * **Shift+scroll**: Horizontal scrolling * **Right-click**: Context menu ### Large Result Sets For results with many rows: * **Virtual scrolling**: Only visible rows are rendered * **Status indicator**: Shows "Showing rows 1-100 of 5,000" * **Load more**: Button to fetch additional rows (paid version) * **Jump to row**: `Ctrl+G` to go to specific row number ## Data Formatting ### Automatic Formatting Koala automatically formats data based on type: #### Numbers * Integers: No decimal places * Decimals: Appropriate decimal places * Currency: With currency symbols (when detected) * Large numbers: Optional thousands separators #### Dates * Default Oracle format: 'DD-MON-YYYY' * Timestamps: Include time component * Time zones: Displayed when present * Relative dates: "3 days ago" (optional) #### Text * Preserves original spacing * Shows invisible characters option * Word wrapping for long text * Encoding detection for special characters ### Custom Formatting Configure display preferences: ```json theme={null} { "koala.results.dateFormat": "YYYY-MM-DD", "koala.results.numberFormat": "#,##0.00", "koala.results.nullDisplay": "", "koala.results.maxCellWidth": 200 } ``` ## Column Operations ### Resizing Columns * **Drag border**: Manual resize * **Double-click border**: Auto-fit to content * **Right-click header**: Resize options menu * **Ctrl+0**: Reset all columns to default width * **Auto column width**: Use the toolbar option to fit all columns to current data ### Reordering Columns * Drag column header to new position * Right-click → "Move Left/Right" * Reset to original order with "Reset Column Order" ### Column Visibility Hide/show columns: 1. Right-click column header 2. Select "Hide Column" 3. Use "Column Visibility" to show hidden columns 4. Or use column selector in toolbar ## Row Operations ### Row Selection * **Single row**: Click row number * **Multiple rows**: `Ctrl+click` row numbers * **Range selection**: `Shift+click` row numbers * **All rows**: `Ctrl+A` ### Row Details View detailed row information: 1. Select row 2. Press `Enter` or double-click 3. Opens detailed view dialog 4. Shows each column with full content ### Row Context Menu Right-click row for options: * Copy row * Copy row as SQL INSERT * View row details * Filter by row values * Export selected rows ## Data Types and Display ### Text Data #### Short Text (VARCHAR2, CHAR) * Displayed inline in cells * Truncated if longer than cell width * Full content in tooltip #### Long Text (CLOB) * Shows data type indicator * Content size in KB/MB * Click to view in text editor * Search and highlight capabilities ### Numeric Data #### Integers * Right-aligned * No decimal places * Optional thousands separators #### Decimals * Right-aligned * Configurable decimal places * Scientific notation for very large/small numbers #### Currency * Formatted with currency symbols * Respect locale settings * Configurable currency display ### Date and Time #### DATE * Oracle standard format * Configurable display format * Date picker for filtering #### TIMESTAMP * Includes time component * Millisecond precision * Time zone information ### Binary Data #### BLOB * Shows size indicator * Download option * Preview for common formats (images, etc.) #### RAW * Hexadecimal display * Copy as hex string * Size information ## Special Value Handling ### NULL Values NULL values are displayed: * As "(null)" in gray italics by default * Configurable display text * Distinguished from empty strings * Sortable (typically appear first or last) ### Empty Strings Empty strings vs NULL: * Empty: Shows as empty cell * NULL: Shows as "(null)" * Both clearly distinguished * Different behavior in filters ### Large Text For very long text fields: * Truncated display with "..." indicator * Full content in tooltip * Click to open in editor * Word wrap option * Find in text capability ## Performance Features ### Lazy Loading Results load efficiently: * Initial page loads quickly * Additional rows loaded on demand * Virtual scrolling for smooth performance * Progress indicator for large queries ### Caching Result caching improves experience: * Recently viewed results cached * Quick navigation between pages * Cache size configurable * Clear cache option available ### Memory Management Efficient memory usage: * Only visible rows in memory * Large results don't overwhelm system * Automatic cleanup of old results * Memory usage indicator ## Accessibility ### Screen Reader Support * Column headers announced * Cell content read clearly * Navigation announces position * Data type information included ### Keyboard Access All features accessible via keyboard: * Full navigation without mouse * Context menus via keyboard * All actions have shortcuts * Focus indicators clearly visible ### High Contrast Support for high contrast themes: * Clear cell boundaries * High contrast colors * Readable fonts * Proper contrast ratios ## Best Practices ### Viewing Large Results 1. Use LIMIT clauses in queries 2. Sort by indexed columns first 3. Consider using filters 4. Export to files for analysis ### Performance 1. Limit column width for better performance 2. Hide unused columns 3. Use virtual scrolling settings 4. Clear old results regularly ### Data Analysis 1. Use sorting to find patterns 2. Apply filters to focus on subsets 3. Copy specific cells/rows as needed 4. Export filtered results for further analysis ## Troubleshooting ### Slow Result Display If results load slowly: 1. Check query performance 2. Reduce number of columns selected 3. Add appropriate LIMIT clause 4. Check network connectivity ### Display Issues For formatting problems: 1. Check data type handling 2. Verify character encoding 3. Adjust column widths 4. Reset formatting to defaults ### Memory Issues If experiencing memory problems: 1. Clear result cache 2. Reduce visible row limit 3. Close unused result tabs 4. Restart VS Code if needed ## Next Steps Learn to sort and filter results Export results to various formats # Getting help Source: https://docs.btsscorp.com/koala/support/getting-help Support channels for Koala Data Explorer Need a hand with Koala Data Explorer Extension? Here's how to reach us. ## Support channels Our support portal — the fastest way to get help. [support@btsscorp.com](mailto:support@btsscorp.com) Manage your license and orders. btsscorp.com ## Before you reach out Many issues have a quick fix in the **Common Issues** pages: Can't connect to your Oracle pod. Queries fail or return errors. Slow queries or a sluggish grid. Auto-deployment isn't working. # Connection Issues Source: https://docs.btsscorp.com/koala/troubleshooting/connection-issues Troubleshoot Oracle Fusion Cloud connection problems ## Overview This guide helps you resolve common connection issues when connecting Koala Data Explorer Extension to Oracle Fusion Cloud. ## Common Connection Problems ### "Authentication Failed" #### Basic Authentication Issues **Symptoms:** * Login fails with correct username/password * "Invalid credentials" error message **Solutions:** 1. **Verify credentials**: Double-check username and password 2. **Check account status**: Ensure account is not locked or expired 3. **Test in browser**: Try logging into Oracle Fusion web interface 4. **Contact administrator**: Verify account has appropriate permissions #### OAuth PKCE Issues **Symptoms:** * OAuth flow fails during authentication * Browser doesn't redirect back to VS Code **Solutions:** 1. **Check client configuration**: Verify OAuth client ID and settings 2. **Clear browser cache**: Remove cached OAuth tokens 3. **Verify redirect URL**: Ensure `vscode://btss.koala-data-explorer/oauth-callback` is configured 4. **Network restrictions**: Check if corporate firewall blocks OAuth flows ### "Connection Timeout" **Symptoms:** * Connection takes too long and fails * Timeout error messages **Solutions:** 1. **Check network connectivity**: Verify internet connection 2. **VPN issues**: Ensure VPN is connected if required 3. **Firewall settings**: Verify HTTPS traffic is allowed 4. **Increase timeout**: Adjust timeout settings in extension preferences 5. **Try different network**: Test on different network connection ### "Host Not Found" / "Invalid URL" **Symptoms:** * Cannot resolve Oracle Fusion hostname * "Host not found" error **Solutions:** 1. **Verify URL format**: Ensure URL starts with `https://` 2. **Check instance URL**: Confirm correct Oracle Fusion instance URL 3. **DNS issues**: Try accessing URL in browser first 4. **Corporate network**: May need to use internal URLs on corporate networks ## Network-Related Issues ### Proxy Settings If your organization uses a proxy: 1. **VS Code proxy settings**: Configure in VS Code settings 2. **System proxy**: Ensure system proxy is configured correctly 3. **Authentication**: Proxy may require separate authentication 4. **Bypass list**: Add Oracle Fusion domains to proxy bypass ### SSL/TLS Issues **Symptoms:** * SSL certificate errors * "Insecure connection" warnings **Solutions:** 1. **Certificate verification**: Ensure valid SSL certificates 2. **Corporate certificates**: Install corporate root certificates 3. **TLS version**: Verify TLS 1.2+ is supported 4. **Contact IT**: May need corporate certificate configuration ## Permission Issues ### Database Access **Symptoms:** * Connection succeeds but queries fail * "Insufficient privileges" errors **Solutions:** 1. **Verify SELECT permissions**: Ensure user has SELECT rights on required tables 2. **Schema access**: Check access to specific schemas 3. **Role assignments**: Verify proper Oracle Fusion roles are assigned 4. **Data security**: Check if row-level security policies apply ### Application Access **Symptoms:** * Cannot access specific Oracle Fusion modules * Limited data visibility **Solutions:** 1. **Module licenses**: Verify licenses for required modules 2. **User provisioning**: Ensure user is provisioned for specific applications 3. **Security roles**: Check Oracle Fusion security role assignments 4. **Data access sets**: Verify appropriate data access sets are assigned ## Environment-Specific Issues ### Development vs Production **Common differences:** * Different authentication methods * Network restrictions * Data access permissions * URL formats **Solutions:** 1. **Environment-specific connections**: Create separate connections for each environment 2. **Check documentation**: Verify environment-specific connection details 3. **Contact administrators**: Different environments may have different requirements ### Multi-tenant Environments **Issues:** * Wrong tenant/pod connections * Cross-tenant data access restrictions **Solutions:** 1. **Verify tenant URL**: Ensure connecting to correct tenant 2. **Tenant-specific authentication**: May require different credentials per tenant 3. **Data isolation**: Understand tenant data boundaries ## Performance Issues ### Slow Connections **Symptoms:** * Connection takes long time to establish * Queries run slowly **Solutions:** 1. **Network latency**: Check ping times to Oracle Fusion 2. **Geographic location**: Connection speed varies by location 3. **Peak usage times**: Avoid peak usage periods 4. **Query optimization**: Use efficient queries with appropriate limits ### Connection Drops **Symptoms:** * Frequent disconnections * Need to reconnect often **Solutions:** 1. **Network stability**: Check for network interruptions 2. **Idle timeouts**: Oracle may disconnect idle sessions 3. **Firewall timeouts**: Corporate firewalls may drop long connections 4. **Keep-alive settings**: Configure connection keep-alive if available ## Windows SSO Issues ### Common Problems **"Runtime components missing"** * Accept the download prompt when shown by the extension * Restart VS Code after installation **"SSO dialog won't open"** * Restart VS Code completely * Check with IT if antivirus software is blocking connections **"Authentication timeout"** * Verify SSO works in your regular browser first * Contact Oracle administrator if SSO login fails * Try connecting again after a few minutes **"Download failed"** * Check internet connection * Contact IT support if corporate firewall blocks downloads ## Diagnostic Steps ### Basic Diagnostics 1. **Test in browser**: Try accessing Oracle Fusion in web browser 2. **Network connectivity**: Ping Oracle Fusion hostname 3. **Port accessibility**: Verify HTTPS (443) port is accessible 4. **DNS resolution**: Verify hostname resolves correctly ### Advanced Diagnostics 1. **Network traces**: Use network monitoring tools 2. **SSL handshake**: Verify SSL negotiation succeeds 3. **Authentication flow**: Debug OAuth or SAML flows 4. **Log analysis**: Check VS Code and extension logs ## Getting Help ### Before Contacting Support Gather this information: 1. **Error messages**: Copy exact error text 2. **Connection details**: URL, authentication type (without passwords) 3. **Network environment**: Corporate network, VPN status 4. **Timing**: When issue started, frequency 5. **Screenshots**: Visual error messages ### Log Collection Enable detailed logging: 1. Open VS Code settings 2. Search for "Koala logging" 3. Enable debug logging 4. Reproduce the issue 5. Collect logs from VS Code Output panel ### Contact Information * **Support Portal**: [Submit a ticket](https://btsscorp.freshdesk.com/support/tickets/new) (recommended) * **Email Support**: [support@btsscorp.com](mailto:support@btsscorp.com) (alternative) * **Include**: Error details, environment info, logs * **Response Time**: 1-2 business days ## Prevention Tips ### Best Practices 1. **Save working configurations**: Export connection settings that work 2. **Test regularly**: Verify connections work before important tasks 3. **Keep credentials current**: Update passwords before expiration 4. **Monitor announcements**: Watch for Oracle Fusion maintenance windows 5. **Backup plans**: Have alternative access methods available ### Regular Maintenance 1. **Update extension**: Keep Koala Data Explorer updated 2. **Refresh tokens**: Refresh OAuth tokens periodically 3. **Test connections**: Verify connections work after system updates 4. **Review permissions**: Ensure access rights remain current ## Next Steps Troubleshoot SQL query execution issues Resolve performance and speed problems # Deployment Issues Source: https://docs.btsscorp.com/koala/troubleshooting/deployment-issues Resolve auto-deployment and hash verification problems ## Symptoms * Repeated deployment prompts on connect * "Hash mismatch" or "artifact missing" errors * Catalog features unavailable after connection * Deployment progress notification never completes ## Quick fixes 1. Click **Force Redeploy Catalog** in Managing Connections. 2. Reconnect and watch for the deployment progress notification. 3. Verify hash status shows "up to date" in the connection details. ## Common causes * Remote catalog differs from local package (hash mismatch). * Required artifacts were removed on the Oracle side. * Previous upload was interrupted by network loss. * Hash verification failed because the remote catalog could not be read. * Version of the bundled package changed but remote hash stayed stale. ## Verification checklist 1. Confirm the hash shown in the connection details matches your last deployment time. 2. Check the Output channel for the `downloadObject` requests and their hashes. 3. If the hash is missing or mismatched, run **Force Redeploy Catalog**. 4. Reconnect and confirm the new hash is stored. ## Still seeing issues? * Check network stability during uploads. * Confirm you have rights to deploy BIP artifacts. * Capture the output log and share with support for deeper analysis. * Note the hash values shown in the Output channel; include them when opening a support ticket. # Performance Issues Source: https://docs.btsscorp.com/koala/troubleshooting/performance-issues Diagnose and resolve performance problems in Koala Data Explorer ## Overview This guide helps you diagnose and resolve performance issues when using Koala Data Explorer Extension with Oracle Fusion Cloud. ## Slow Query Performance ### Identifying Slow Queries **Symptoms:** * Queries take long time to execute * Timeout errors * VS Code becomes unresponsive during query execution **Diagnostic Steps:** 1. **Check query execution time**: Monitor timing in results panel 2. **Compare similar queries**: See if specific queries are slower 3. **Test with row limits**: Add `WHERE ROWNUM <= 100` to test ### Common Causes of Slow Queries #### Large Result Sets **Problem:** Returning too many rows ```sql theme={null} -- Slow: No row limit SELECT * FROM ap_invoices_all; -- Better: With reasonable limit SELECT * FROM ap_invoices_all WHERE ROWNUM <= 1000; ``` **Solutions:** 1. **Add row limits**: Always use `ROWNUM` or `FETCH FIRST` 2. **Filter data**: Use specific WHERE clauses 3. **Select specific columns**: Avoid `SELECT *` #### Missing WHERE Clauses **Problem:** Full table scans on large tables ```sql theme={null} -- Slow: Full table scan SELECT * FROM per_all_people_f; -- Better: Filtered query SELECT * FROM per_all_people_f WHERE effective_end_date = DATE '4712-12-31' AND ROWNUM <= 1000; ``` #### Inefficient Joins **Problem:** Joining large tables without proper conditions ```sql theme={null} -- Slow: Cartesian product SELECT e.*, d.* FROM per_all_people_f e, hr_all_organization_units d; -- Better: Proper join with conditions SELECT e.person_number, d.name FROM per_all_people_f e JOIN per_all_assignments_m a ON e.person_id = a.person_id JOIN hr_all_organization_units d ON a.organization_id = d.organization_id WHERE e.effective_end_date = DATE '4712-12-31' AND a.effective_end_date = DATE '4712-12-31' AND ROWNUM <= 1000; ``` ## Network Performance Issues ### Slow Connection to Oracle Fusion **Symptoms:** * Long delays before queries start executing * Intermittent timeouts * Slow authentication **Causes:** 1. **Network latency**: Distance to Oracle Fusion servers 2. **VPN overhead**: Corporate VPN adding latency 3. **Bandwidth limitations**: Slow internet connection 4. **Proxy servers**: Corporate proxies adding delays **Solutions:** 1. **Test network speed**: Use network speed tests 2. **Check VPN**: Try without VPN if possible 3. **Use wired connection**: Ethernet instead of WiFi 4. **Peak hours**: Avoid peak usage times ### DNS Resolution Issues **Symptoms:** * Initial connection delays * Intermittent "host not found" errors **Solutions:** 1. **Use IP addresses**: If DNS is slow, try IP address 2. **DNS cache**: Clear DNS cache on your machine 3. **Alternative DNS**: Try different DNS servers (8.8.8.8, 1.1.1.1) ## VS Code Performance Issues ### High Memory Usage **Symptoms:** * VS Code becomes slow or unresponsive * High memory usage in Task Manager * System becomes sluggish **Causes:** 1. **Large result sets**: Too much data loaded in memory 2. **Multiple query tabs**: Many tabs with results open 3. **Query history**: Large query history accumulation **Solutions:** 1. **Clear results**: Close result tabs when done 2. **Limit query results**: Use smaller row limits 3. **Restart VS Code**: Periodically restart to clear memory 4. **Close unused tabs**: Keep only necessary tabs open ### Slow UI Response **Symptoms:** * Typing lag in query editor * Slow scrolling through results * Delayed button clicks **Solutions:** 1. **Reduce result set size**: Display fewer rows 2. **Close large results**: Clear memory-intensive results 3. **Disable extensions**: Temporarily disable other VS Code extensions 4. **Check system resources**: Monitor CPU and memory usage ## Oracle Fusion Performance ### Database-Side Performance **Common Oracle Issues:** 1. **Peak usage times**: High load during business hours 2. **Maintenance windows**: Scheduled maintenance affecting performance 3. **Resource contention**: Other users running heavy queries **Solutions:** 1. **Off-peak usage**: Run queries during low-usage times 2. **Check announcements**: Monitor Oracle Fusion maintenance schedules 3. **Optimize queries**: Use efficient SQL patterns ### Query Optimization Techniques #### Use Indexes Effectively ```sql theme={null} -- Good: Filter on indexed columns SELECT * FROM ap_invoices_all WHERE invoice_date >= DATE '2024-01-01' AND ROWNUM <= 1000; -- Avoid: Functions on indexed columns SELECT * FROM ap_invoices_all WHERE TO_CHAR(invoice_date, 'YYYY') = '2024'; ``` #### Efficient Date Filtering ```sql theme={null} -- Efficient: Date range filtering SELECT * FROM transactions WHERE transaction_date BETWEEN DATE '2024-01-01' AND DATE '2024-12-31' AND ROWNUM <= 1000; -- Less efficient: Date functions SELECT * FROM transactions WHERE EXTRACT(YEAR FROM transaction_date) = 2024; ``` ## Data Export Performance ### Slow Export Operations **Symptoms:** * Export operations take very long * Export failures due to timeouts * Large file generation delays **Solutions:** #### For Large Datasets: 1. **Use CSV instead of Excel**: CSV is faster for large data 2. **Export in batches**: Break large exports into smaller chunks 3. **Filter before export**: Reduce data size with WHERE clauses #### Excel Export Optimization: ```sql theme={null} -- For Excel export (10K row limit) SELECT specific_columns FROM your_table WHERE filter_conditions AND ROWNUM <= 10000; ``` #### CSV Export for Large Data: ```sql theme={null} -- For large CSV exports SELECT specific_columns FROM your_table WHERE filter_conditions AND ROWNUM <= 50000; -- Adjust based on needs ``` ## Performance Monitoring ### Built-in Performance Tracking **Available Metrics:** * Query execution time (displayed in results) * Row count returned * Connection response time **How to Use:** 1. **Monitor timing**: Check execution time for each query 2. **Compare performance**: Track changes over time 3. **Identify patterns**: Note which queries are consistently slow ### Performance Benchmarking **Simple Benchmarks:** ```sql theme={null} -- Test connection speed SELECT 1 FROM dual; -- Test simple table access SELECT COUNT(*) FROM hr_all_organization_units; -- Test filtered query SELECT COUNT(*) FROM per_all_people_f WHERE effective_end_date = DATE '4712-12-31'; ``` ## System Resource Optimization ### Computer Performance **Recommended Specifications:** * **RAM**: 8GB+ (16GB recommended) * **CPU**: Modern multi-core processor * **Storage**: SSD recommended for better performance * **Network**: Stable broadband connection **Optimization Tips:** 1. **Close unnecessary applications**: Free up system resources 2. **Regular restarts**: Clear memory and temporary files 3. **Disk cleanup**: Ensure adequate free disk space 4. **Update drivers**: Keep network and graphics drivers current ### VS Code Optimization **Settings to Consider:** ```json theme={null} { "koalaDataExplorer.maxRows": 1000, "koalaDataExplorer.timeout": 120000, "koalaDataExplorer.autoRefreshDataSources": false } ``` **Extension Management:** 1. **Disable unused extensions**: Reduce VS Code overhead 2. **Update regularly**: Keep Koala and VS Code updated 3. **Reset settings**: Restore default settings if issues persist ## Troubleshooting Workflow ### Step-by-Step Performance Diagnosis 1. **Identify the issue**: * Slow queries? * Slow connections? * Slow UI? * Slow exports? 2. **Isolate the cause**: * Test simple queries first * Check network connectivity * Monitor system resources * Compare with known working queries 3. **Apply targeted solutions**: * Query optimization for slow queries * Network troubleshooting for connection issues * Resource management for UI issues 4. **Verify improvement**: * Test the same operations again * Monitor performance over time * Document what worked ### Performance Testing Queries **Connection Test:** ```sql theme={null} SELECT SYSDATE FROM dual; ``` **Small Table Test:** ```sql theme={null} SELECT COUNT(*) FROM fnd_lookup_values WHERE ROWNUM <= 1; ``` **Filtered Query Test:** ```sql theme={null} SELECT * FROM hr_all_organization_units WHERE organization_id < 1000 AND ROWNUM <= 100; ``` ## Best Practices for Performance ### Query Writing Best Practices 1. **Always use row limits**: Protect against accidentally large results 2. **Filter early and often**: Use WHERE clauses to reduce data 3. **Select only needed columns**: Avoid SELECT \* 4. **Use appropriate date ranges**: Don't query all historical data 5. **Test with small datasets first**: Verify query logic before scaling up ### Usage Patterns 1. **Plan your queries**: Think about what data you need before writing SQL 2. **Reuse successful patterns**: Save and reuse well-performing queries 3. **Monitor your usage**: Be aware of peak times and system load 4. **Batch similar work**: Group related queries together 5. **Clean up regularly**: Close unused tabs and clear old results ### Environment Considerations 1. **Development vs Production**: Performance may vary between environments 2. **Time zones**: Consider Oracle Fusion server time zone for peak usage 3. **Geographic location**: Distance from Oracle servers affects latency 4. **Corporate networks**: Internal networks may have different performance characteristics ## Getting Performance Help ### Information to Collect Before contacting support about performance issues: 1. **Query details**: The specific query experiencing issues 2. **Timing information**: How long queries take vs. expected time 3. **System information**: Your computer specs and network type 4. **Environment details**: Which Oracle Fusion environment 5. **Reproducibility**: Whether issue is consistent or intermittent ### Performance Logs Enable performance logging: 1. Open VS Code settings 2. Search for "Koala performance" 3. Enable performance monitoring 4. Reproduce the issue 5. Collect timing information ## Next Steps Learn to write efficient SQL queries Resolve connection and network problems # Query Errors Source: https://docs.btsscorp.com/koala/troubleshooting/query-errors Troubleshoot SQL query execution errors and issues ## Overview This guide helps you resolve common SQL query errors when using Koala Data Explorer Extension with Oracle Fusion Cloud. ## Common Oracle Errors ### ORA-00942: Table or View Does Not Exist **Symptoms:** * Query fails with "table or view does not exist" * Table shows in Data Sources but query fails **Causes:** 1. **Schema qualification**: Table exists in different schema 2. **Permissions**: No SELECT permission on table 3. **Typos**: Misspelled table or column names 4. **Case sensitivity**: Oracle is case-sensitive with quoted identifiers **Solutions:** 1. **Use schema prefix**: `SCHEMA_NAME.TABLE_NAME` 2. **Check permissions**: Verify SELECT access with DBA 3. **Verify spelling**: Double-check table and column names 4. **Use Data Sources**: Drag table names from explorer to avoid typos ### ORA-00936: Missing Expression **Symptoms:** * "Missing expression" error * SQL syntax appears correct **Common Causes:** 1. **Missing SELECT columns**: Empty SELECT clause 2. **Trailing commas**: Extra comma after last column 3. **Missing FROM clause**: SELECT without FROM 4. **Reserved words**: Using Oracle reserved words as identifiers **Solutions:** ```sql theme={null} -- Bad: Trailing comma SELECT employee_id, first_name, FROM employees; -- Good: No trailing comma SELECT employee_id, first_name FROM employees; -- Bad: Missing expression SELECT FROM employees; -- Good: Specify columns SELECT * FROM employees; ``` ### ORA-01017: Invalid Username/Password **Symptoms:** * Authentication fails during query execution * Previously working queries now fail **Solutions:** 1. **Refresh connection**: Reconnect to Oracle Fusion 2. **Update credentials**: Password may have expired 3. **Check session**: Session may have timed out 4. **Re-authenticate**: Use connection manager to re-authenticate ### ORA-00904: Invalid Identifier **Symptoms:** * Column name not recognized * "Invalid identifier" error **Causes:** 1. **Column doesn't exist**: Column name is incorrect 2. **Case sensitivity**: Quoted identifiers are case-sensitive 3. **Reserved words**: Using Oracle reserved words 4. **Special characters**: Invalid characters in names **Solutions:** 1. **Verify column names**: Check in Data Sources explorer 2. **Use proper quoting**: `"Column Name"` for case-sensitive names 3. **Avoid reserved words**: Use different names or quote them 4. **Check spelling**: Ensure correct column spelling ## Query Syntax Issues ### JOIN Problems **Common JOIN errors:** ```sql theme={null} -- Bad: Missing JOIN condition SELECT e.first_name, d.department_name FROM employees e JOIN departments d; -- Good: Proper JOIN condition SELECT e.first_name, d.department_name FROM employees e JOIN departments d ON e.department_id = d.department_id; -- Bad: Ambiguous column reference SELECT employee_id, department_id FROM employees e JOIN departments d ON e.department_id = d.department_id; -- Good: Qualified column names SELECT e.employee_id, e.department_id FROM employees e JOIN departments d ON e.department_id = d.department_id; ``` ### Date Format Issues **Common date problems:** ```sql theme={null} -- Bad: Incorrect date format SELECT * FROM employees WHERE hire_date > '2023-01-01'; -- Good: Proper Oracle date format SELECT * FROM employees WHERE hire_date > DATE '2023-01-01'; -- Alternative: TO_DATE function SELECT * FROM employees WHERE hire_date > TO_DATE('2023-01-01', 'YYYY-MM-DD'); ``` ### NULL Handling **NULL comparison issues:** ```sql theme={null} -- Bad: Won't find NULL values SELECT * FROM employees WHERE manager_id = NULL; -- Good: Proper NULL check SELECT * FROM employees WHERE manager_id IS NULL; -- Bad: NULL in calculations SELECT salary + commission FROM employees; -- Good: Handle NULLs SELECT salary + NVL(commission, 0) FROM employees; ``` ## Performance-Related Errors ### Query Timeout **Symptoms:** * Query runs for long time then fails * Timeout error messages **Solutions:** 1. **Add row limits**: Use `WHERE ROWNUM <= 1000` 2. **Optimize WHERE clauses**: Filter data more effectively 3. **Check indexes**: Ensure filtered columns are indexed 4. **Increase timeout**: Adjust timeout in extension settings **Example optimization:** ```sql theme={null} -- Slow: No row limit SELECT * FROM large_table WHERE status = 'ACTIVE'; -- Better: With row limit SELECT * FROM large_table WHERE status = 'ACTIVE' AND ROWNUM <= 1000; -- Best: Most selective filter first SELECT * FROM large_table WHERE creation_date >= SYSDATE - 7 AND status = 'ACTIVE' AND ROWNUM <= 1000; ``` ### Memory Issues **Symptoms:** * Out of memory errors * VS Code becomes unresponsive **Solutions:** 1. **Reduce result size**: Select fewer columns 2. **Add row limits**: Limit rows returned 3. \*\*Avoid SELECT \*\*\*: Select only needed columns 4. **Process in batches**: Break large queries into smaller parts ## Data Type Issues ### Number Format Errors **Common problems:** ```sql theme={null} -- Bad: Incorrect number format SELECT * FROM products WHERE price = '19.99'; -- Good: Proper number comparison SELECT * FROM products WHERE price = 19.99; -- String to number conversion SELECT * FROM products WHERE TO_NUMBER(price_text) > 100; ``` ### Character Set Issues **Symptoms:** * Special characters display incorrectly * Encoding errors **Solutions:** 1. **Check database encoding**: Verify Oracle character set 2. **Use proper functions**: CONVERT or TRANSLATE functions 3. **Escape special characters**: Use proper escaping for special chars ## Bind Variable Errors ### Parameter Issues **Common problems:** 1. **Undefined parameters**: Using `:param` without defining value 2. **Type mismatches**: Parameter type doesn't match column type 3. **Missing parameters**: Not providing all required parameters **Solutions:** ```sql theme={null} -- Ensure parameter types match SELECT * FROM employees WHERE employee_id = :emp_id; -- emp_id should be number -- Handle optional parameters SELECT * FROM employees WHERE (:dept_id IS NULL OR department_id = :dept_id); ``` ## Row Limit Errors ### Export Limitations **Symptoms:** * "Too many rows" errors * Excel export not available **Solutions:** 1. **Add ROWNUM limits**: `WHERE ROWNUM <= 10000` for Excel compatibility 2. **Use CSV for large datasets**: CSV supports more rows than Excel export 3. **Filter data**: Use more restrictive WHERE clauses 4. **Process in batches**: Split large results into multiple queries ## Debugging Strategies ### Systematic Approach 1. **Start simple**: Begin with basic SELECT \* FROM table 2. **Add complexity gradually**: Add WHERE, JOIN, ORDER BY one at a time 3. **Test components**: Test each part of complex queries separately 4. **Use EXPLAIN PLAN**: Check query execution plan ### Common Debugging Techniques ```sql theme={null} -- Test table access SELECT COUNT(*) FROM table_name; -- Verify column names SELECT * FROM table_name WHERE ROWNUM <= 1; -- Test JOIN conditions SELECT COUNT(*) FROM table1 t1 JOIN table2 t2 ON t1.id = t2.id; -- Check data types SELECT column_name, data_type FROM user_tab_columns WHERE table_name = 'YOUR_TABLE'; ``` ## Error Message Reference ### Understanding Oracle Error Messages Oracle error messages follow this pattern: * **ORA-#####**: Oracle error number * **Description**: Brief error description * **Cause**: What caused the error * **Action**: Suggested resolution ### Most Common Errors | Error Code | Description | Common Cause | | ---------- | ---------------------------- | ----------------------------------- | | ORA-00942 | Table or view does not exist | Missing permissions or wrong schema | | ORA-00904 | Invalid identifier | Wrong column name | | ORA-00936 | Missing expression | Syntax error in SELECT | | ORA-01017 | Invalid username/password | Authentication expired | | ORA-00001 | Unique constraint violated | Duplicate key values | | ORA-01400 | Cannot insert NULL | Required field is NULL | ## Getting Help ### Before Reporting Query Errors Collect this information: 1. **Complete error message**: Copy full Oracle error text 2. **SQL query**: The exact query that failed 3. **Table structure**: Column names and types 4. **Sample data**: Example of data you're querying 5. **Expected result**: What you expected to happen ### Query Optimization Help For performance issues: 1. **Execution plan**: Use EXPLAIN PLAN if available 2. **Row counts**: Table sizes and expected result size 3. **Index information**: Available indexes on tables 4. **Timing**: How long query takes to fail ## Best Practices ### Writing Robust Queries 1. **Always use row limits**: Protect against large result sets 2. **Qualify column names**: Use table aliases for clarity 3. **Handle NULLs explicitly**: Use IS NULL, IS NOT NULL, NVL 4. **Test incrementally**: Build complex queries step by step 5. **Use bind variables**: For dynamic values ### Error Prevention 1. **Use Data Sources explorer**: Drag table/column names to avoid typos 2. **Start with simple queries**: Test basic connectivity first 3. **Understand your data**: Know table structures and relationships 4. **Save working queries**: Keep copies of successful queries 5. **Document complex logic**: Add comments to complex queries ## Next Steps Resolve query performance problems Fix connection and authentication problems # SQL Validation Source: https://docs.btsscorp.com/koala/troubleshooting/sql-validation Understand Koala's validation rules and fix common errors ## Validation rules * **Read-only guard**: Only `SELECT` statements are allowed; DML/DDL is blocked. * **Injection protection**: Patterns resembling unsafe concatenation or execution are rejected. * **Bind variables**: Must use `:name` syntax; invalid placeholders are flagged. ## Common false positives * Colons inside quoted strings (e.g., `'http://example.com:8080'`). * Commented-out DML statements in multi-statement scripts. * Bind variables inside complex string concatenations. ## Fixes 1. Ensure non-SELECT statements are removed or commented out. 2. Escape or move colons that are part of literal strings. 3. Keep bind variable names alphanumeric and consistent (`:startDate`). If validation blocks a legitimate query, simplify the statement and retry. Complex scripts are easier to validate when split across tabs. # The AI engine Source: https://docs.btsscorp.com/orca/account/ai-engine The Anthropic API key, model routing, and the autonomous agent ORCA's **domain expertise is built into the product**. Templates, deterministic HDL/FBDI generation, the mappings you set, preview, and loads all run **without any AI key** — the conversion engine works on its own. Adding an **Anthropic Claude** key layers the agentic experience on top: discovery, guided mapping, conversational chat, and error learning — the smoothness, finesse, and speed, not the foundation. ## Add your Anthropic API key An admin sets the key in **Settings → API Keys**. Click **Add API Key** and paste your Anthropic key (it starts with `sk-ant-`). Click **Save Key**. Use **Test** to validate, or **Update** / **Remove** later. The key is **encrypted at rest and never shown in plaintext** — the card displays only a masked hint. It's a **per-tenant** key that only admins can manage; analysts can view the tab but see no controls. **Without a key, ORCA still works.** You can use templates, set mappings, generate load files, and load to Oracle with the built-in deterministic engine. What a key switches on is the **AI layer** — the conversion agent, chat, the workspace agent panel, **Propose Mappings**, and background jobs. Add a key and ORCA gets faster and smarter; it doesn't stop working without one. ## How ORCA chooses a model You don't pick a model — ORCA routes each request across Claude's **Haiku, Sonnet, and Opus** tiers to balance cost and capability: lighter, faster models for simple turns, and stronger models for complex reasoning and error diagnosis. In interactive chat this is a quick per-turn choice; heavier conversion reasoning can escalate further. Model selection is automatic and not shown per answer. The chat **cost bar** surfaces spend, tokens, and calls for the session — useful for keeping an eye on usage. ## The ORCA Autonomous Agent On the same tab, an admin can enable **ORCA Autonomous Agent** — project-level orchestration and interview-driven setup. It layers on top of the API key: the project-level chat mode needs both the key and this toggle on. ## Next steps Point ORCA at an Oracle Fusion pod and run discovery. # Tenancy & users Source: https://docs.btsscorp.com/orca/account/tenancy-and-users The multi-tenant model, roles, and user management ORCA is **multi-tenant**. Everything you do lives inside a **tenant** — one organization's isolated space, with its own users, connections, API key, projects, and data. Nothing crosses between tenants. ## How tenancy works * **Sign up creates a tenant.** You provide an Organization Name (which becomes a URL slug), your name, email, and password. The first user is the tenant **Admin**. * **Sign in is two-step.** Enter your tenant name, then your credentials. If you belong to more than one tenant, use **Switch tenant** to pick another. * **Data is scoped by tenant.** Every connection, project, and key belongs to exactly one tenant. Sign-in uses ORCA's own email/password accounts, independent of Oracle. There is no SSO today. ## Roles Each user has one role per tenant. There are two: | Role | Can do | | ----------- | --------------------------------------------------------------------------------------------------------------- | | **Admin** | Manage users, connections, the API key, and agent settings — plus everything an Analyst can do. | | **Analyst** | Use the app: run conversions, chat, and view connections and users. Cannot manage users or admin-only settings. | **Platform admins** are a special case — an Admin whose tenant is the BTSS platform tenant. They manage tenants (see below). It's a derived capability, not a third role. ## Manage users Admins add and manage users in **Settings → User Management**. Click **Add User**, then enter an **Email**, a **Password**, an optional **Display Name**, and a **Role** (Analyst or Admin). Click **Add User**. Use the row actions to change a role or remove a user later. Adding a user **creates the account immediately with the password you set** — no invitation email is sent. Share the credentials securely and have the user change the password. ## Platform admins: managing tenants BTSS platform admins get a **Tenants** tab (only visible from the platform tenant). From **Settings → Tenants** they can **Create Tenant** (Name + Slug), see all tenants with user counts, and expand a tenant to add or remove its users. This is how new customer tenancies are provisioned. Regular tenant admins never see this tab — it's BTSS-internal provisioning. ## Next steps Add the Anthropic key that powers the ORCA agent. # The agent & chat Source: https://docs.btsscorp.com/orca/agent/agent-and-chat The autonomous conversion agent and ask-anything chat ORCA gives you two ways to work, and you'll use both. Runs an entity through validate → transform → preview → load → error loop, and consolidates the result into one review per entity instead of field-by-field prompts. It classifies Oracle load errors, applies what it has learned, and re-runs. Ask anything against the connected pod, inside the app — "does this user exist", "what shift are they on", "what's our headcount" — or drive the conversion conversationally. ## Start a chat On the **Chat** page, click **New Chat** (or just start typing). Your default connection attaches automatically. Use the **Set context** bar to pin an **entity / project / cycle / connection** when you want the answer scoped. The chat is **built from the session's connection**, and that binding decides which tools exist. Answers come back as formatted Markdown with a running cost/usage bar beneath them. ## Next steps Pre-built expert playbooks the chat applies automatically. The SQL consent moment and how tasks earn autonomy. # Governance & autonomy Source: https://docs.btsscorp.com/orca/agent/governance-and-autonomy The SQL consent moment and how tasks earn autonomy ## The SQL consent moment Sometimes the governed REST API genuinely can't answer, and SQL could. If — and only if — SQL is enabled on the connection, chat **stops and asks first**: > "The governed API can't answer \. OK to query the database directly? (Bypasses per-user data security; I'll label anything it finds.)" Say yes and the answer is labelled **"via SQL (user-approved)"** — or **"via SQL (standing consent)"** if you've granted standing consent on that connection. On a **Production** connection it always re-asks. The ask exists because REST answers respect each user's Oracle data security and SQL does not. It keeps a human in the loop the moment ORCA is about to step outside your security posture, and the label keeps that visible in the answer forever. Consent removes the question, never the visibility. **Why did ORCA ask permission before answering?** Because it needed to fall back to direct SQL, which bypasses Oracle's per-user data security. ORCA always asks first and labels the result "via SQL". If it never asked, it answered entirely through the governed REST API — within your own Oracle security. ## How ORCA earns autonomy Each task earns autonomy as it proves accurate, and auto-downgrades if error rates spike or you override it. It's a safety-first ratchet that runs **under the hood** per (entity, field) — there's no dashboard to watch; you feel it as ORCA asking fewer questions each cycle. | Level | Behaviour | | ----------------- | -------------------------------- | | `L0 · Manual` | You decide everything. | | `L1 · Guided` | ORCA proposes, you confirm. | | `L2 · Supervised` | ORCA applies, you spot-check. | | `L3 · Autonomous` | ORCA applies with no model call. | | `L4 · Lights-Out` | Fully autonomous, no overrides. | # Skills Source: https://docs.btsscorp.com/orca/agent/skills Pre-built expert playbooks ORCA chat applies automatically When a question matches a known shape, ORCA chat automatically reaches for a pre-built **skill** — a consultant's playbook with pre-validated Oracle calls — before improvising. Three ship today: Role assignments, data access, security profiles, and AOR for a user. What shift someone works, schedules, rosters, and who's on a given day. Headcount and worker-type breakdowns. ## How skills are cited The answer cites the calls it made **inline in its own text** — the skills require it to quote the exact REST call or query as evidence (even "no rows" is stated as evidence). There is no separate citations panel, so read the prose for the sourcing. Skills only appear once the connection's REST catalog has been discovered. If discovery hasn't run, the chat won't have skills to reach for. # Governed REST vs SQL Source: https://docs.btsscorp.com/orca/connections/governed-rest-vs-sql How ORCA stays inside your Oracle security, and when direct SQL is allowed This is the most important idea in ORCA. Everything ORCA does over Oracle's **REST APIs is governed** — Oracle checks the connection user's own function and data security on every call, so ORCA only ever sees what that user is allowed to see. New connections are **REST-only by default**. Direct **SQL through BIP bypasses per-user data security**. It stays off until an admin deliberately enables it, and even then the agent must ask before using it. ## The SQL toggle Each connection card has an amber **SQL** toggle. When an admin turns it on, a panel explains the trade-off: SQL bypasses Oracle's per-user data security, the agent must ask before falling back to it, and every SQL-derived answer is labelled "via SQL". When SQL is **off**, the agent never even sees the SQL tools (`run_sql`, `search_tables`, `describe_table`) — the model cannot call what does not exist. ## Production connections The **Production connection** checkbox is stricter still: * The agent **always re-asks** before running SQL on a prod connection. * **Standing consent can never apply** to a prod connection. ## Standing consent On a trusted non-production connection, an admin can grant **standing consent** — the "don't ask me again on this connection" toggle. It lets the agent skip the per-question ask, records **who granted it and when**, and is **revocable in Settings** at any time. Consent removes the question, never the visibility. Even with standing consent, every SQL answer is still labelled — "via SQL (standing consent)". ## FAQ **Why don't I see any SQL tools?** Because the connection's SQL toggle is off — the default. REST-only connections never expose the SQL tools to the agent. An admin must enable SQL on that connection first. **The `table` discovery chip says skipped — is it broken?** No. Table discovery reads comments over SQL, so it's skipped whenever SQL is disabled. Enable SQL and re-run discovery if you want it. # Oracle connections Source: https://docs.btsscorp.com/orca/connections/oracle-connections Create a connection and let ORCA discover the pod's metadata A connection is **one Oracle Fusion pod, its credentials, and its own discovered metadata catalog**. Everything ORCA does runs through a connection, and each pod carries its own catalog — nothing is shared between connections. ## Create a connection Go to **Settings → Oracle Connections** and click **Add Connection**. In **New Connection**, enter a **Name**, the **Oracle URL** (your pod base URL), a **Username**, and a **Password**. Optionally tick **Set as default connection**. Leave **Production connection** unticked for a test pod. Click **Save**. The moment you save, ORCA starts **background metadata discovery** against the pod — you don't trigger it manually. ## Metadata discovery A **Discovery** row of chips appears on the connection card, one per source. Each starts grey (`never run`), spins while it works (`pending → running`), and turns green (`done`) with an object count — or red (`failed`) if the pod refused. Re-trigger the whole sweep any time with the **Re-run discovery** button. | Source | Discovers | Feeds | | ------- | ----------------------------------------- | ---------------------------------------------------- | | `rest` | HCM + FSCM REST resource catalog | The "Discovered APIs" table and the chat/query tools | | `hdl` | HCM Data Loader business objects | HDL generation for HCM conversions | | `fbdi` | Finance / SCM / Projects import processes | The "FBDI Processes" table and FBDI loads | | `table` | Table / column comments (SQL only) | `search_tables`; skipped when SQL is off | Two more chips (`fsm`, `soap`) render but are placeholders today — they always record as skipped. For HCM work, `rest` and `hdl` are the ones that matter. ## What a connection powers One connection powers **ORCA chat**, the **conversion loads** a cycle submits, and the **MCP connector** that lets Claude query the pod from outside the app. Flip the **MCP** toggle and ORCA surfaces a shared **OAuth URL** (recommended) plus a legacy token URL. Query your Oracle data from Claude Desktop or Claude Code over MCP. ## Next steps How ORCA stays inside your Oracle security — and when SQL is allowed. # How ORCA works Source: https://docs.btsscorp.com/orca/how-orca-works The building blocks, the conversion lifecycle, and the Configuration Workbench ORCA is organized around five building blocks. You set them up roughly in this order, and everything downstream depends on the ones before it. Your organization's isolated space, its users, and their roles. The Anthropic API key and model routing that power the agent. One Oracle Fusion pod, its credentials, and its discovered metadata. Projects, cycles, and entities — where a conversion runs. The autonomous conversion agent and ask-anything chat. ## The conversion lifecycle A real conversion isn't one load — it's a series of cycles that get faster and cleaner as they move toward go-live. You start with a POC on a test pod (`cycle-0`), work the errors until it's clean, then promote cycle by cycle toward the production cutover — each one faster because ORCA carries your mappings and learnings forward. The full cycle-by-cycle flow, how promotion works, and why each cycle is faster than the last. ## Moving configuration between environments Alongside conversion, the **Configuration Workbench** uses the same connections to manage Oracle setup across environments — migrate it from one to the next, detect what has drifted, push a targeted set of changes, and keep every state versioned. Pull, review, check for drift, and push Oracle setup between environments. # Connect to Claude Source: https://docs.btsscorp.com/orca/integrations/connect-to-claude Query your Oracle Fusion data from Claude over MCP — governed, within your own Oracle security ORCA lets you work with your Oracle Fusion (SaaS) data in plain language — every request is **governed** and runs **within your own Oracle security**. Whatever your role, ORCA puts our consultants' expertise on tap: the same checks, lookups, and playbooks a seasoned Oracle practitioner would run — a question away, no ticket, no wait. The same governed agent — **same skills, same consent rules** — is reachable from **Claude Desktop** or **Claude Code** over MCP (Model Context Protocol). Connect it to Claude once and just ask. ## Prerequisites In **Settings → Oracle Connections**, flip the **MCP** toggle on the connection you want to expose. ORCA shows your MCP URL in the app (it looks like `https:///api/mcp`). There's **no token in the URL** — you authenticate by signing in to ORCA. ## Claude Desktop In Claude Desktop, open **Settings**. Claude Desktop settings Select the **Connectors** section. Connectors section in Claude settings Click **Add custom connector**. Add custom connector dialog Give it any name you like — **ORCA** works well (the name is just a local label). Paste your MCP URL, click **Add**, then **Connect**. Naming the connector and pasting the MCP URL Claude opens your browser. Sign in to ORCA, then pick the Oracle connection to grant and click **Approve**. Your Oracle credentials never leave ORCA — Claude only receives a short-lived, scoped token. Approving an Oracle connection for the application in ORCA Approve the tool permissions (**Always allow for all tools** is fine). Done — ask away in any chat. Setting tool permissions to Always allow in Claude ## Claude Code (CLI) Same flow — add the server once, then Claude Code opens your browser for the identical sign-in and consent. Run `/mcp` to trigger or inspect auth. ```bash theme={null} claude mcp add --transport http orca ``` ## How access stays governed * You sign in to ORCA and approve which Oracle connection Claude may use. * Claude receives a short-lived, scoped token — your Oracle credentials never leave ORCA. * Every request runs within your own Oracle security, exactly as it does inside the app. Governed **REST** is the default path; **SQL**, if enabled on the connection, still asks for consent and labels its answers. ## Skills that keep getting better The connector ships with **skills** — pre-built expert playbooks with pre-validated Oracle calls that a seasoned consultant would run. Claude reaches for the right one automatically when your question matches its shape. Role assignments, data access, security profiles, and AOR for a user. What shift someone works, schedules, rosters, and who's on a given day. Headcount and worker-type breakdowns. We ship **new skills continually** — and they're delivered to your connector automatically. Your ORCA connector gets smarter over time with nothing to install or configure on your side. ## Build dashboards, not just answers Because ORCA answers over MCP, any **MCP client** — an AI assistant that speaks the protocol, such as Claude Desktop or Claude Code — can do more than return a single answer. Ask it to chart the results, assemble a report, or stand up a **live dashboard** over your governed Oracle data, and it queries ORCA for the numbers and builds the view for you. The data stays within your own Oracle security the whole time. * "Build me a workforce dashboard: headcount by department and location, with month-over-month trend." * "Chart active workers by location, then lay it out as a report I can share." * "Track FBDI import processes for General Ledger and show their status at a glance." ## What you can ask Plain-language questions across users, roles, security, HCM data, and analytics — a few to get started: * "Investigate the gender distribution across the company and chart it." * "Show me headcount by department, and flag any that grew more than 10% this year." * "How many active workers do we have by location? Put it in a bar chart." * "Audit the data-access permissions and security profiles for a given user." * "Which roles grant access to payroll data, and how does row-level access resolve?" * "List the FBDI import processes available for General Ledger." * "Does user JSMITH exist, and what roles are assigned to them?" * "Why can this user see that employee's record — walk me through it." * "What shift is a given worker scheduled for this week?" # Introduction Source: https://docs.btsscorp.com/orca/introduction Convert data and manage configuration in Oracle Fusion Cloud ## What is ORCA? ORCA™ is an AI platform for the teams who stand up and maintain Oracle Fusion Cloud — HCM, Finance, and Supply Chain. It works directly against your environment on the two jobs that consume most of an implementation: getting data into Fusion, and managing configuration across environments. **Data conversion.** ORCA takes legacy data from any source system into Oracle Fusion — preparing and validating it, generating the HDL and FBDI load files Oracle expects, submitting them, and working the error cycle with you until the load is clean. Every fix it learns is carried into the next cycle, so each pass is faster than the last. **Configuration Workbench.** ORCA manages Oracle setup across your environments — the migration from one to the next, the drift between them, and a versioned history of both. Pull configuration — value sets, user-defined tables, fast formulas, and other Functional Setup Manager tasks — into a workbook, review and edit it, see what has drifted from its source, and push a targeted set of changes into the next environment as governed inserts and updates. Everything happens inside your own Oracle security: each read and write is a governed Oracle call made as the connection's user. And when you simply need an answer — who holds a role, what's driving a license count, which workers are scheduled — you can ask ORCA in plain language, from the app or from Claude, where a question can just as easily become a chart or a live dashboard over your governed data. ## Who uses ORCA? Drive the full conversion — map, validate, transform, preview, load, and work the error cycle. Pull setup from one environment, clean it up, and push it to another with the Configuration Workbench. Prepare and own the source data, guided by ORCA instead of a consultant. Ask questions about Oracle data in plain language, from the app or from Claude. ## How it works, in one line You set up a **connection** to an Oracle pod and add your **AI key**. Then you either **convert** legacy data through a **project** with **cycles** and **entities**, or use the **Configuration Workbench** to move setup between environments — while **ORCA chat** answers questions along the way. ## Next steps The building blocks and the two things ORCA does with them. Pull, edit, and push Oracle setup between environments. Point ORCA at an Oracle Fusion pod. Add the Anthropic key that powers the agent. # Getting help Source: https://docs.btsscorp.com/orca/support/getting-help Support channels and common questions for ORCA Need help with ORCA? Reach us through any of these channels, or check the common questions below. ## Support channels Our support portal — the fastest way to get help. [support@btsscorp.com](mailto:support@btsscorp.com) btsscorp.com Talk to us about your implementation. ## Common questions The ORCA docs answer many common questions where the feature is explained: * **Why don't I see any SQL tools?** The connection is REST-only by default — see [Governed REST vs SQL](/orca/connections/governed-rest-vs-sql). * **Why did ORCA ask permission before answering?** It needed to fall back to direct SQL — see [Governance & autonomy](/orca/agent/governance-and-autonomy). * **The chat has no skills to reach for.** Skills appear once the connection's REST catalog is discovered — see [Skills](/orca/agent/skills). * **A discovery chip says `skipped` or `failed`.** Each source has its own conditions — see [Oracle connections](/orca/connections/oracle-connections). * **The agent, chat, or Propose Mappings are off.** These are the AI layer; add an Anthropic key to switch them on — see [The AI engine](/orca/account/ai-engine). # Configuration Workbench Source: https://docs.btsscorp.com/orca/workspace/configuration-workbench Migrate, reconcile, and version Oracle setup across environments The Configuration Workbench manages Oracle Fusion **setup configuration** — value sets, user‑defined tables, fast formulas, and other Functional Setup Manager tasks — across your environments. Pull configuration out of a source environment into a versioned **workbook**, review and edit it, detect what has drifted, and push a targeted set of changes into a target environment. Every state is versioned, and every push only adds or updates — never deletes. ## Prerequisites * A **connection** to your source environment and a connection to your target environment. See [Oracle connections](/orca/connections/oracle-connections). * The source connection must be **harvested** — run discovery on it first so its setup tasks are available. Discovery uses SQL, so SQL must be enabled on the connection. * Permission to run the setup export and import on both environments. ## Create a workbook Select **Configuration Workbench** in the left navigation, then **Create**. Pick the **source connection**, then choose the **offering** and **functional area** to pull — or switch to **choose tasks** to select individual setup tasks. Give the workbook a name. ORCA exports the selected tasks from the source environment and creates the workbook as a **draft**. Each task appears in the left panel with its business objects and row counts. ## Review and edit Open the workbook to review what you pulled. * **Edit in the grid.** Each business object shows its rows in a grid. Edit cells directly. * **Edit in Excel.** Use **Download Excel** to export the workbook, edit it in Excel, then **Upload Excel** to replace each business object's data with your edited copy. * **Keep only what you need.** Uncheck a row to drop it. Dropped rows stay in the workbook for reference but are **excluded from a push** — they are never deleted from any environment. Use **Download package** to see the exact setup package a push would send, before you push it. ## Publish a version Publishing saves a numbered, read‑only **version** of the workbook so you have a fixed point to push and to return to. * **Publish** — save the current draft as the next version. * **Edit as draft** — start a new draft from a published version to make further changes. * **Discard draft** / **Reset to source** — throw away draft edits, or re‑pull the whole workbook fresh from the source. ## Check for drift **Detect drift** compares the workbook against the **environment it was pulled from**, so you can see whether that environment has changed since you pulled — and reconcile it. Select **Detect drift**. The check runs in the background; you can keep working, and the drift view updates itself when it finishes. Each drifted business object gains a **Drift** view showing rows that were added, changed, or removed in the source. Switch a section between **Data** and **Drift** to inspect it. Accept the source changes you want and **Apply to draft** to merge them into your workbook. Everything else is left untouched. Detect drift compares against the workbook's **source** environment. Comparing one workbook against a *different* target environment is not part of this workflow. ## Push to a target environment Pushing writes to a live environment. It **only inserts or updates records — it never deletes** — but confirm the version and the target before you push. Use the version selector to choose the version you want. Confirm the **Push** button names that version (for example, **Push v2**) — this is what will be sent. Choose the **target connection** in the connection selector. Select **Push** and confirm. ORCA sends each task to the target as an Oracle setup‑import request, waits for each to finish, and reports how many tasks succeeded. ## Verify the load in Oracle Each task is submitted as an Oracle scheduled process. To confirm what landed: 1. In the target environment, open **Tools → Scheduled Processes**. 2. Search for the process by its request ID (or by name, for example *Manage Value Sets*). 3. Open the process and **View Output / Log** to see the per‑object records loaded and rejected. ## Next steps Add and harvest the source and target environments. How ORCA reads and writes within your Oracle security. # The conversion lifecycle Source: https://docs.btsscorp.com/orca/workspace/conversion-lifecycle From POC to prod cutover across cycles and environments A real conversion isn't one load — it's a series of cycles that get faster and cleaner as they move toward go-live. Each cycle is bound to one connection, and a connection is one **environment** (test → … → production), so promoting a cycle means running the next one against the next environment. Create the project, pick the source system, and identify the entities to convert. Plan your cycles. Run a sample conversion on a test pod: map, validate, preview, load a slice, and work the errors until it's clean. Open the next cycle against the next environment's connection. **Import from cycle** carries mappings forward and learnings carry automatically. Repeat, faster each time. The final cycle runs against the production connection for the go-live load. ## Promoting a cycle "Copying a cycle" means: 1. Create a new cycle bound to the **next environment's connection**. 2. Use **Import from cycle** to pull the previous cycle's mappings forward (with a diff preview). 3. The **ORCA Learnings** come with it automatically. This is why cycle-1 onward is dramatically faster than the cycle-0 POC — the mappings and every confirmed error fix are already in place. Environments are modelled as **connections**, not a separate concept — a cycle points at whichever connection (test, UAT, prod) you're promoting into. There is no one-click "clone cycle across environments" button today; you create the next cycle and use Import from cycle. # Inside an entity Source: https://docs.btsscorp.com/orca/workspace/entity-workspace Source data, mappings, preview, run, and ORCA Learnings Open an entity to reach its **workspace** — the room where one entity's work happens, laid out as numbered sections you work top to bottom. Upload the source extract (CSV, Excel, HDL, or a zip). If the template ships an MVT, use **Download Template**, fill it in, and ORCA auto-maps the fields. Map source columns to Oracle's import components. MVT fields auto-map; **Propose Mappings** drafts the rest; **Import from cycle** pulls a previous cycle's mappings forward. Inspect the exact Oracle-format `.dat` ORCA will generate, before anything is sent. Download it to eyeball it. Submit to Oracle — **Run** / **Load to Oracle** for HDL, or the UCM → Load → Import → Purge pipeline for FBDI. Every load's results and errors, kept per entity. Confirmed error fixes, in three tiers: **Silent** (auto-handled), **Auto-fix** (applied automatically), and **Ask** (needs confirmation). ## Never answer the same question twice **ORCA Learnings** is what makes each cycle faster. Once a fix is confirmed, ORCA captures it with provenance and reapplies it automatically in later cycles — so it never asks you the same question twice. The section starts empty: *"No learned error patterns yet. ORCA learns from confirmed fixes during chat."* Field **mappings** carry forward when you click **Import from cycle** — opt-in per entity, with a diff preview. The **learnings** carry forward automatically. # Projects, cycles & entities Source: https://docs.btsscorp.com/orca/workspace/projects-cycles-entities The workspace hierarchy where a conversion runs A conversion lives inside a **project → cycle → entity** hierarchy. Set it up top-down. | Level | What it is | | ----------- | ---------------------------------------------------------------------------------------------------- | | **Project** | One client conversion — the top-level container. | | **Cycle** | One full practice run of the conversion. Each is faster than the last because ORCA remembers. | | **Entity** | One Oracle business object (Worker, Assignment, Payroll) with its own template, mappings, and state. | ## Create a project Go to **Projects → Create Project**, type a **Project Name** (ORCA derives a short ID from it), and pick the **Source System** (e.g. PeopleSoft, SAP, Workday, ADP, UKG / Kronos, or CSV). Click **Create Project**. ## Start a cycle In the project, click **New Cycle**, give it a **Cycle ID** (e.g. `cycle-0`), and choose the **Oracle Connection** the cycle loads against. Click **Create Cycle**. It opens in `PLANNING`; edit its status to move it to `IN_PROGRESS` and `COMPLETED`. The cycle **carries the connection** — everything it loads or queries runs through that pod. There's no separate "start" button; you advance a cycle by editing its status. ## Add entities In the **Entities** card, use **+ Add Entity** to pick from the templates loaded for this pod (Worker, Assignment, Salary, Payroll, …). Each row shows **Status**, **Files**, **Errors**, **Iteration**, and an **Attention** flag. Oracle entities have a real dependency order (Organization / Location first, Payroll last) and the conversion respects it — but the grid does not render a load-order column today. Treat sequencing as consultant knowledge, not a screen. ## Next steps From POC to prod cutover across cycles and environments. Source data, mappings, preview, run, and learnings.