Data Sources

• How do I upload an Excel or CSV file as a source?
• How do I connect a REST API source?
• How do I sync Converse forms into Vantage?

How do I upload an Excel or CSV file as a source?

1. Overview

Vantage is the analytics and dashboard module inside Converse. As a Vantage Admin, you can upload data, build dashboards, configure AI queries, set up alerts, and share insights with your team. This page helps you find your way around when you open Vantage for the first time.

2. When to Use

• When you are accessing Vantage for the first time.
• When you need to understand the main navigation areas before setting up dashboards.
• When you want to locate the Sources section to start bringing data in.

3. Concepts

• Vantage Admin – A user with the Vantage Admin role. Only admins can create sources, build dashboards, configure widgets, and manage sharing. The admin role is assigned within Converse.
• Sources – Where all your data lives. Every file you upload, form you connect, or API you sync becomes a source. Sources are the foundation — dashboards, widgets, and AI queries all read from sources.
• Dashboards – The main screen your team will see. Each dashboard holds one or more widgets (charts, tables, KPIs) built on top of your sources.
• Ask AI – A chat panel where you can type natural-language questions and get answers from your data.

4. Set Up Guide

Step 1: Open Vantage

1. Log in to Converse.
2. Open the sidebar menu.
3. Click Vantage to enter the module.

Step 2: Explore the Navigation

When Vantage opens, you will see the main sections:

• Sources – Add and manage your data connections.
• Dashboards – Create and view dashboards.
• Ask AI – Ask questions over your data.

Step 3: Open Sources

1. Click Sources from the navigation.
2. You will see the Sources listing — this is empty when you start.
3. From here you can add your first data source using the Add Source button.

5. Best Practices

• Start with Sources before building dashboards — you need at least one source before you can create any widget.
• Prepare your data file (Excel or CSV) before opening Vantage so you can upload it right away.
• If you plan to use form data, make sure the form is already created in the Converse form builder.

6. Related Links / FAQs

Can non-admin users access Vantage?
Non-admin users can view shared dashboards and receive alerts, but they cannot create sources, build dashboards, or configure widgets.

What should I do first after opening Vantage?
Go to Sources and add your first data source. Once data is in, you can start building dashboards.

7. Version Notes

Last Updated: 04 Sep 2026

How do I connect a REST API source?

1. Overview

The REST API connector lets you pull data from an external HTTP endpoint into Vantage. You provide the URL, authentication details, and a JSON path to the data array — Vantage fetches the response and ingests the results into ClickHouse like any other source.

The API connector currently supports manual sync only. You trigger each pull by clicking "Sync now" in the source settings. Scheduled or automatic API polling is not yet available.

2. When to Use

• When you have an internal or third-party API that returns tabular data in JSON format.
• When you want to bring CRM records, ERP data, or other system data into Vantage for analysis.
• When you need a structured alternative to downloading CSVs and re-uploading them manually.

3. Concepts

• Authentication – Vantage supports three auth methods for API connections: Bearer token, API key, and Basic (username/password).
• Data Path – The JSON path that tells Vantage where the data array lives in the API response. For example, if the response is {"results": [{...}, {...}]}, the data path would be "results".
• Manual Sync – Each sync is triggered by an admin clicking "Sync now". The connector fetches the latest data from the API and replaces the previous dataset. There is no automatic or scheduled sync.

4. Set Up Guide

Step 1: Add a New Source

1. In Vantage, click Sources from the navigation.
2. Click Add Source.
3. Select API as the connector type.

Step 2: Enter the Endpoint URL

1. Provide the full URL of the API endpoint that returns your data.

Step 3: Configure Authentication

1. Choose your auth method:
   • Bearer token
   • API key
   • Basic auth (username/password)
2. Enter the credentials.

Step 4: Set the Data Path

1. Specify the JSON path pointing to the data array in the response.

Step 5: Sync

1. Click Sync now to pull the data.
2. Vantage fetches the response, extracts data at the specified path, and ingests it into ClickHouse.

Step 6: Verify

1. Confirm the row count in the Sources listing.
2. Spot-check column values in the source view.

5. Best Practices

• Test your API endpoint independently (e.g., in Postman or a browser) before configuring it in Vantage.
• If your API returns paginated results, point Vantage at a single-page or bulk export endpoint.
• Remember to sync manually whenever the upstream data changes — there is no automatic refresh.
• If your API credentials rotate, update them in the source settings promptly to avoid failed syncs.

6. Related Links / FAQs

Can I schedule automatic API syncs?
Not currently. API sources require a manual "Sync now" action each time. Scheduled pulls are planned for a future release.

What if my API needs custom headers?
The supported auth methods (Bearer, API key, Basic) cover most common patterns. Custom header configurations beyond these are not available in the current version.

Does the API connector support pagination?
No. Vantage makes a single request to the configured URL. Use an endpoint that returns the full dataset in one response.

7. Version Notes

Last Updated: 04 Sep 2026

How do I sync Converse forms into Vantage?

1. Overview

Converse forms (built using the form builder) can be synced into Vantage as an internal data source. This lets you build dashboards, run AI queries, and set up alerts over your form submission data — bringing field-collected data directly into analytics.

When a form is added as a Vantage source, its submitted data is written to ClickHouse. The sync can be triggered manually by an admin, and will include all current submissions.

2. When to Use

• When you have a Converse form collecting store visits, audits, surveys, or any field data.
• When you want to visualise form responses on dashboards with KPI cards, charts, and tables.
• When you want to ask AI questions over form data (e.g., "Which stores had the lowest audit scores last week?").
• When you plan to set up instant alerts or exception alerts based on form submissions.

3. Concepts

• Add to Analytics – The action that registers a Converse form as a Vantage internal source. Until a form is added to analytics, its data exists only in the form builder database and is not available for Vantage dashboards or AI.
• Sync / Resync – The process that reads form submissions and writes them into ClickHouse. An initial sync happens when the form is first added. Subsequent resyncs are triggered manually to pick up new submissions.
• User Enrichment – Vantage automatically joins submitter information (name, email, role, region, manager — from user profile attributes) onto each submission row. This enrichment refreshes on a daily cycle.
• Form Columns – Each form question becomes a column in the Vantage source, plus system columns like submission date, submitter ID, and enriched user attributes.

4. Set Up Guide

Step 1: Open Sources

1. In Vantage, click Sources from the navigation.
2. Click Add Source.

Step 2: Select Connector Type

1. Select Internal (Converse Form) as the connector type.

Step 3: Choose the Form

1. Select the form you want to bring into Vantage from the list of available forms.

Step 4: Sync

1. Vantage syncs the form's submission data into ClickHouse.
2. The initial sync may take a moment depending on the volume of existing submissions.

Step 5: Verify

1. Check the row count in the Sources listing.
2. Browse the data to confirm columns and values look correct.
3. Verify that enriched user columns (name, region, manager, etc.) are populated.

5. Best Practices

• Add a form to analytics early — even before submissions start flowing — so the source is ready when you build dashboards.
• Resync before important reviews or presentations to ensure you have the latest data.
• User attribute enrichment (manager, region, etc.) refreshes daily. If you just updated user profiles, the change may not reflect in Vantage until the next day.
• If you modify the form structure (adding or removing questions), resync the source so the ClickHouse schema picks up the new columns.

6. Related Links / FAQs

Does Vantage sync form data automatically?
Currently, form data syncs when you trigger it manually (initial add or resync). Automatic periodic sync is planned.

Can I use alerts on a form that hasn't been added to analytics?
Instant alerts (on-submit notifications) work on any form. Exception alerts that query the ClickHouse table require the form to be added to analytics first.

What columns appear in the Vantage source?
Each form question becomes a column, plus system columns like submission date, submitter ID, and enriched user attributes (name, email, region, manager, etc.).

I added a new question to my form but it doesn't appear in Vantage. What do I do?
Resync the source. New form questions only appear as ClickHouse columns after a resync.

Can I add the same form as a source more than once?
No. Each form maps to one source in Vantage.

7. Version Notes

Last Updated: 04 Sep 2026