> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wcr.is/llms.txt
> Use this file to discover all available pages before exploring further.

# NocoDB data integration

> Use NocoDB as the structured data layer for WeCareRemote — manage cases, resources, and contacts with a spreadsheet UI and a REST API.

[NocoDB](https://nocodb.com) is the structured-data layer that sits alongside WeCareRemote. While the AI assistant handles unstructured conversation, the blog handles long-form content, and the recordings backend handles video — NocoDB handles everything that fits naturally into rows and columns: cases, contacts, resources, referrals, eligibility checklists, content calendars.

NGO staff interact with NocoDB through a spreadsheet-style web UI. Other parts of the stack — the AI assistant, [n8n workflows](/integrations/n8n), the blog — read and write the same tables through NocoDB's REST API.

## What NocoDB is used for

Typical tables in a WeCareRemote NocoDB deployment:

| Table              | Purpose                                                               |
| ------------------ | --------------------------------------------------------------------- |
| `cases`            | One row per refugee case: assigned NGO, status, last contact, summary |
| `contacts`         | Refugees and NGO staff, linked to WeCareRemote user IDs               |
| `services`         | Catalogue of services and resources the AI assistant can reference    |
| `recordings`       | Index of Jitsi meeting recordings with case linkage                   |
| `referrals`        | Hand-offs between NGOs, with timestamps and notes                     |
| `content_calendar` | Blog posts planned and published, owners, target audience             |

The exact schema is up to each deployment — NocoDB makes it easy to evolve tables as needs change.

## How NocoDB connects to WeCareRemote

NocoDB is **not** authenticated through WeCareRemote's JWT. Instead, NocoDB issues its own API tokens, which other services (n8n, the AI assistant, custom scripts) attach to their requests.

```http theme={null}
xc-token: <your-nocodb-api-token>
```

Two access patterns are common:

* **Direct from n8n** — n8n's built-in NocoDB node handles credentials and CRUD. Use this for most automation.
* **Direct from the AI assistant** — when your organization wires up a NocoDB-backed knowledge source, the assistant can query NocoDB rows the same way it queries any other knowledge base.

## Setting up NocoDB

### Before you begin

You need:

* A running NocoDB instance reachable from n8n and from any service that needs to query it
* A NocoDB workspace and base created for WeCareRemote
* An NGO admin who can issue API tokens

### Issuing an API token

<Steps>
  <Step title="Open your NocoDB account">
    Click your avatar in the top-right of NocoDB and choose **Account Settings**.
  </Step>

  <Step title="Go to Tokens">
    Open the **Tokens** tab and click **Create token**.
  </Step>

  <Step title="Name and copy the token">
    Give the token a descriptive name (for example, `wcr-n8n-prod`) and copy the generated value — NocoDB shows it only once.
  </Step>

  <Step title="Store the token securely">
    Save the token in your n8n credentials store, an environment variable, or a secrets manager. Do not commit it to version control.
  </Step>
</Steps>

### Designing a case table

A minimal `cases` table works well as a starting point:

| Column            | Type             | Notes                                              |
| ----------------- | ---------------- | -------------------------------------------------- |
| `id`              | Auto Number      | Primary key                                        |
| `thread_id`       | Single Line Text | Matches the AI assistant `thread_id`               |
| `refugee_email`   | Email            | Links to the WeCareRemote user                     |
| `assigned_ngo`    | Single Select    | NGO responsible for the case                       |
| `status`          | Single Select    | `new`, `in_progress`, `waiting`, `closed`          |
| `topic`           | Single Select    | `housing`, `legal`, `health`, `education`, `other` |
| `summary`         | Long Text        | Short human-readable summary                       |
| `last_contact_at` | Date Time        | Updated on every interaction                       |
| `created_at`      | Created Time     | Auto-managed by NocoDB                             |

You can extend this with linked records to a `contacts` table, attachments for documents, and rollups for case counts per NGO.

## Reading and writing rows via API

NocoDB exposes a REST API per table. The endpoint pattern is:

```http theme={null}
GET    /api/v2/tables/{tableId}/records
POST   /api/v2/tables/{tableId}/records
PATCH  /api/v2/tables/{tableId}/records
DELETE /api/v2/tables/{tableId}/records
```

### Example: create a case from a webhook

```bash theme={null}
curl -X POST "https://nocodb.example.org/api/v2/tables/<tableId>/records" \
  -H "xc-token: <your-nocodb-api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "session-abc123",
    "refugee_email": "jane@example.org",
    "assigned_ngo": "Sunflower Care",
    "status": "new",
    "topic": "housing",
    "summary": "Refugee asked about emergency housing in Berlin."
  }'
```

### Example: list cases filtered by status

```bash theme={null}
curl "https://nocodb.example.org/api/v2/tables/<tableId>/records?where=(status,eq,new)" \
  -H "xc-token: <your-nocodb-api-token>"
```

NocoDB returns paginated JSON. Iterate with the `offset` and `limit` query parameters when reading large datasets.

## Linking NocoDB to the AI assistant

To let the AI assistant reference NocoDB content (for example, the catalogue of services in a `services` table), your administrator can connect NocoDB as a knowledge source. The mechanism depends on which AI model and retrieval setup your deployment uses, but the high-level flow is:

<Steps>
  <Step title="Expose the data">
    Make the relevant NocoDB table queryable — either through the NocoDB REST API with a scoped token, or by syncing rows into the assistant's vector store.
  </Step>

  <Step title="Configure the assistant">
    In the WeCareRemote AI assistant configuration, register the NocoDB endpoint (or the synced index) as a retrieval source.
  </Step>

  <Step title="Test with a question">
    Ask the assistant something that should be answered from NocoDB — for example, "What housing services are available in Berlin?" The response should pull from the `services` table.
  </Step>
</Steps>

<Note>
  Knowledge-source configuration is administrator-only. If you want to expose a NocoDB table to the assistant, contact your WeCareRemote administrator with the table name and the columns the assistant should be able to read.
</Note>

## Security and best practices

* **Use scoped tokens.** NocoDB tokens can be scoped to specific bases. Create separate tokens per integration so a leaked token has a small blast radius.
* **Mirror the JWT role model.** Decide which NocoDB users correspond to `blog` vs `org_admin` and grant table permissions accordingly.
* **Audit changes.** NocoDB's row history makes it easy to see who changed what; turn on audit logs in production.
* **Avoid storing secrets in rows.** NocoDB is the wrong place for credentials, raw JWTs, or other sensitive material.
* **Back up regularly.** A nightly export of critical tables to object storage protects you against accidental deletions.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The API returns 401 Unauthorized">
    Double-check the `xc-token` header — NocoDB does not accept Bearer tokens. Also confirm the token has not been revoked in **Account Settings → Tokens**.
  </Accordion>

  <Accordion title="POST returns 422 Unprocessable Entity">
    A column type does not match. Single Select columns reject values that are not in the option list; date columns reject strings that are not ISO 8601. Inspect the response body for the offending field.
  </Accordion>

  <Accordion title="Rows are missing from API responses">
    NocoDB paginates by default (often 25 rows). Pass a higher `limit` or iterate with `offset` to fetch the full table.
  </Accordion>

  <Accordion title="n8n NocoDB node cannot find the table">
    The node lists tables by base. Make sure the base ID in the credentials matches the base that contains your table. Re-authenticating sometimes refreshes the table list.
  </Accordion>
</AccordionGroup>

## Where to go next

<CardGroup cols={2}>
  <Card title="n8n integration" icon="diagram-project" href="/integrations/n8n">
    Wire NocoDB into automated workflows triggered by WeCareRemote events.
  </Card>

  <Card title="Platform overview" icon="map" href="/platform-overview">
    See where NocoDB and n8n fit in the overall WeCareRemote architecture.
  </Card>
</CardGroup>