> ## Documentation Index
> Fetch the complete documentation index at: https://guide.bajeti-ufahamu.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Webapp: Connectors

> Bringing feedback in automatically from external platforms.

## The Connectors tab

Every flow has a **Connectors** tab. It has two sections:

* **Direct Input**: always-on channels that are already configured: PDF Upload (Champion-submitted aggregated feedback reports) and whatsapp bot.
* **External Connections**: KoboToolbox and Google Sheets connections that pull structured submissions in as feedback automatically. This is where you add, edit, or remove connectors.

<Frame caption="The Connectors tab, showing Direct Input and External Connections">
  <img src="https://mintcdn.com/bajeti-ufahamu/lKb_jxRH0kWfficP/images/webapp-connectors/connectors-tab.png?fit=max&auto=format&n=lKb_jxRH0kWfficP&q=85&s=2daf29bcd2cee151cc7c224645f50eca" alt="Connectors tab on a flow" width="1427" height="795" data-path="images/webapp-connectors/connectors-tab.png" />
</Frame>

Viewing this tab is open to all rolesvc. Adding, editing, deleting, or manually syncing a connector requires **Facilitator and above**, within your location.

## Add a connector

<Steps>
  <Step title="Click Add a connection">
    From the Connectors tab, click **Add a connection** (or **Add your first connection** if none exist yet).
  </Step>

  <Step title="Choose a connection type">
    Pick **KoboCollect** or **Google Sheets**. (SMS/USSD and WhatsApp Bot connection types are listed but not yet available.) Kobo allows only one connection per flow; you can add multiple Google Sheets connections.

    <Frame>
      <img src="https://mintcdn.com/bajeti-ufahamu/lKb_jxRH0kWfficP/images/webapp-connectors/add-connection-picker.png?fit=max&auto=format&n=lKb_jxRH0kWfficP&q=85&s=864274ee588091f4270f9026dffc7508" alt="Choosing a connector type" width="449" height="415" data-path="images/webapp-connectors/add-connection-picker.png" />
    </Frame>
  </Step>
</Steps>

### Configure a KoboToolbox connection

<Steps>
  <Step title="Enter the server URL">
    Choose your Kobo server (`https://kf.kobotoolbox.org`, `https://eu.kobotoolbox.org`, or a custom URL). Use the "Help me find this" link if you're not sure which one applies.
  </Step>

  <Step title="Enter your API key">
    Paste your Kobo API key. There's a "Help me find this" link here too.
  </Step>

  <Step title="Connect to the server">
    Click **Connect to server**. This confirms your credentials and loads the list of Kobo assets (forms) available to you.

    <Frame>
      <img src="https://mintcdn.com/bajeti-ufahamu/lKb_jxRH0kWfficP/images/webapp-connectors/kobo-connect.png?fit=max&auto=format&n=lKb_jxRH0kWfficP&q=85&s=d0516ce94cd0dfbbaf99e2a1c1f082fc" alt="Connecting to a Kobo server" width="450" height="503" data-path="images/webapp-connectors/kobo-connect.png" />
    </Frame>
  </Step>

  <Step title="Select the asset and create the connection">
    Choose the Kobo asset (form) to pull submissions from, then click **Create Connection**.
  </Step>
</Steps>

### Configure a Google Sheets connection

<Steps>
  <Step title="Share the sheet with the service account">
    Give the service account `pfm-sheets-service-account@pfm-flows.iam.gserviceaccount.com` view access to your Google Sheet. The connection will fail without this.
  </Step>

  <Step title="Enter the sheet URL and connect">
    Paste the Google Sheet URL and click **Connect**. This loads the list of worksheets in that spreadsheet.

    <Frame>
      <img src="https://mintcdn.com/bajeti-ufahamu/lKb_jxRH0kWfficP/images/webapp-connectors/sheets-connect.png?fit=max&auto=format&n=lKb_jxRH0kWfficP&q=85&s=ca74f398291d9be9c279c7d2136066da" alt="Connecting to a Google Sheet" width="458" height="657" data-path="images/webapp-connectors/sheets-connect.png" />
    </Frame>
  </Step>

  <Step title="Select the worksheet and header row">
    Choose the worksheet, set the **Header Row Number** (which row contains column headers), then click **Create Connection**.
  </Step>
</Steps>

## Ingest data

Once a connector is connected, click **Ingest data** on its card to pull in new submissions/rows on demand. The card shows last sync time and how many items have been ingested so far.

<Frame>
  <img src="https://mintcdn.com/bajeti-ufahamu/lKb_jxRH0kWfficP/images/webapp-connectors/ingest-data.png?fit=max&auto=format&n=lKb_jxRH0kWfficP&q=85&s=7872ef452561cdd41558c75c334a2e58" alt="Ingest data button on a connector card" width="1095" height="288" data-path="images/webapp-connectors/ingest-data.png" />
</Frame>

## Edit or refresh a connector

Click the **⚙** (gear) icon on a connector's card to reopen its configuration, update the server/sheet details, or use the refresh button next to the asset/worksheet selector to reload the list without re-entering credentials.

## Delete a connector

From the connector's configuration dialog, click the trash icon, then confirm. This can't be undone. Any feedback already ingested through that connection stays, but the connection itself and its sync history are removed.

<Frame>
  <img src="https://mintcdn.com/bajeti-ufahamu/lKb_jxRH0kWfficP/images/webapp-connectors/delete-confirm.png?fit=max&auto=format&n=lKb_jxRH0kWfficP&q=85&s=1a7ae4dda4a3609373ab6b08ad6e2802" alt="Delete connector confirmation dialog" width="458" height="384" data-path="images/webapp-connectors/delete-confirm.png" />
</Frame>