# Data Sources

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

### <span style="color: rgb(53, 152, 219);">**1. Overview**</span>

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.

### <span style="color: rgb(53, 152, 219);">**2. When to Use**</span>

- 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.

### <span style="color: rgb(53, 152, 219);">**3. Concepts**</span>

- **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.

### <span style="color: rgb(53, 152, 219);">**4. Set Up Guide**</span>

##### <span style="color: rgb(53, 152, 219);">Step 1: Open Vantage</span>

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

##### <span style="color: rgb(53, 152, 219);">Step 2: Explore the Navigation</span>

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.

##### <span style="color: rgb(53, 152, 219);">Step 3: Open Sources</span>

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.

### <span style="color: rgb(53, 152, 219);">**5. Best Practices**</span>

- 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.

### <span style="color: rgb(53, 152, 219);">**6. Related Links / FAQs**</span>

**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.

### <span style="color: rgb(53, 152, 219);">**7. Version Notes**</span>

Last Updated: 04 Sep 2026

# How do I connect a REST API source?

### <span style="color: rgb(53, 152, 219);">**1. Overview**</span>

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.

### <span style="color: rgb(53, 152, 219);">**2. When to Use**</span>

- 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.

### <span style="color: rgb(53, 152, 219);">**3. Concepts**</span>

- **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.

### <span style="color: rgb(53, 152, 219);">**4. Set Up Guide**</span>

##### <span style="color: rgb(53, 152, 219);">Step 1: Add a New Source</span>

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

##### <span style="color: rgb(53, 152, 219);">Step 2: Enter the Endpoint URL</span>

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

##### <span style="color: rgb(53, 152, 219);">Step 3: Configure Authentication</span>

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

##### <span style="color: rgb(53, 152, 219);">Step 4: Set the Data Path</span>

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

##### <span style="color: rgb(53, 152, 219);">Step 5: Sync</span>

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

##### <span style="color: rgb(53, 152, 219);">Step 6: Verify</span>

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

### <span style="color: rgb(53, 152, 219);">**5. Best Practices**</span>

- 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.

### <span style="color: rgb(53, 152, 219);">**6. Related Links / FAQs**</span>

**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.

### <span style="color: rgb(53, 152, 219);">**7. Version Notes**</span>

Last Updated: 04 Sep 2026

# How do I sync Converse forms into Vantage?

### <span style="color: rgb(53, 152, 219);">**1. Overview**</span>

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.

### <span style="color: rgb(53, 152, 219);">**2. When to Use**</span>

- 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.

### <span style="color: rgb(53, 152, 219);">**3. Concepts**</span>

- **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.

### <span style="color: rgb(53, 152, 219);">**4. Set Up Guide**</span>

##### <span style="color: rgb(53, 152, 219);">Step 1: Open Sources</span>

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

##### <span style="color: rgb(53, 152, 219);">Step 2: Select Connector Type</span>

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

##### <span style="color: rgb(53, 152, 219);">Step 3: Choose the Form</span>

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

##### <span style="color: rgb(53, 152, 219);">Step 4: Sync</span>

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.

##### <span style="color: rgb(53, 152, 219);">Step 5: Verify</span>

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.

### <span style="color: rgb(53, 152, 219);">**5. Best Practices**</span>

- 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.

### <span style="color: rgb(53, 152, 219);">**6. Related Links / FAQs**</span>

**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.

### <span style="color: rgb(53, 152, 219);">**7. Version Notes**</span>

Last Updated: 04 Sep 2026<script src='//in.fw-cdn.com/30395390/222989.js' chat='true'></script>