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

# Microsoft Fabric Warehouse integration

> Use Voiceflow with Microsoft Fabric Warehouse to answer customer questions from approved SQL data. Your context service connects to the Warehouse SQL endpoint over…

## Overview

Use Voiceflow with Microsoft Fabric Warehouse to answer customer questions from approved SQL data. Your context service connects to the Warehouse SQL endpoint over encrypted TDS and returns a small, authorized result to the agent.

- Read the signed-in customer’s plan and support tier before explaining their service options.
- Use an approved open-case count to give context without exposing raw staff notes.
- Check the source refresh timestamp before presenting warehouse data as current.

The developer hosts the context service and maintains its provider access. The application authenticates the customer; a typed email or customer ID is not authorization. Runtime reads and Knowledge ingestion use separate workflows.

#### Studio

Use a project you can edit, a data owner and an application developer. Obtain a working service and test login before configuring the API tool below.

#### Developer

Use the runnable service recipe and Voiceflow API-tool APIs. Your backend owns customer identity, the provider principal and the runtime session; keep those credentials out of the browser.

<a id="connecting-microsoft-fabric"></a>

## Connecting Microsoft Fabric Warehouse

Prepare the approved view and a working context service.

### Prepare provider access

1. Have the Entra administrator register an application/service principal and provide the tenant ID, client ID and client-secret value through the server’s secret store. Assign an expiry/rotation owner.
2. Have the Fabric administrator enable the required [service-principal tenant setting](https://learn.microsoft.com/en-us/fabric/data-warehouse/entra-id-authentication), grant **connect access to the specific Warehouse item**, and use SQL grants to allow SELECT on the approved view. Avoid a workspace role that grants additional data access when item-level access is sufficient.
3. Complete [Fabric security-token initialization and renewal](https://learn.microsoft.com/en-us/fabric/data-warehouse/service-principals#token-renewal-and-initialization-requirements). A new service principal needs a successful Fabric REST call; a SQL connection alone does not initialize this token. The recipe obtains a Fabric-audience application token, calls [Get Warehouse](https://learn.microsoft.com/en-us/rest/api/fabric/warehouse/items/get-warehouse) for the intended item, requires its ID, and repeats that readiness call after 24 hours of active use before the next SQL read. Using this narrower item-read operation applies Microsoft’s documented “any public Fabric API” initialization rule; the actual account/view path still needs acceptance testing. Obtain the workspace ID and Warehouse item ID and grant the item read permission this operation requires. Keep this lifecycle distinct from the SQL driver’s per-connection database token.
4. Copy the Warehouse’s [SQL connection hostname and exact database name](https://learn.microsoft.com/en-us/fabric/data-warehouse/connectivity). Permit the service’s network path to TCP 1433 and check tenant/firewall rules. Fabric item-management REST permissions do not establish SQL data access.

The data owner maps the approved view to this example contract. This is a deliberate customer-facing projection, not a copy of the raw customer table.

| View column | Meaning and required form |
| --- | --- |
| `tenant_id`, `customer_id` | Authorized application mapping; strings of letters, numbers, underscores or hyphens, at most 80 characters each. One row per pair. |
| `plan_name`, `support_tier` | Approved customer-visible strings, at most 80 characters. |
| `open_cases` | Nonnegative integer with the data owner’s agreed definition of an open case. |
| `last_synced_at` | UTC ISO 8601 text from the last completed source refresh. Do not substitute the query’s current time. |

The adapter opens a SQL connection using Microsoft Entra service-principal authentication, encryption and certificate verification. It binds both identities as VARCHAR parameters and uses SELECT TOP (2) to detect duplicate mappings. The connection pool is closed after the query. The recipe uses the Warehouse SQL endpoint; it does not execute SQL through the Fabric item-management REST API.

### Prepare and connect the service

#### Studio

### 1. Obtain the developer’s tested service

Ask the application developer to deploy the provider-specific context service and authenticated runtime proxy described in the [service recipe](/docs/examples/data-storage/README.md). Have the credential owner create/populate the restricted **warehouse_context_service_token** Secret on the intended test Draft. Obtain the fixed HTTPS service origin, that Secret’s name, a test login and a successful intended-customer readiness check. In this Studio path, you create the variable and API tool in the next steps; the developer hands over the service and identity integration, not a second copy of those resources. The application supplies `warehouse_lookup_token` on every turn; do not collect it from the customer.

### 2. Create the protected variable

Open the project in [Agent studio](https://creator.voiceflow.com). In **More → Variables**, create `warehouse_lookup_token` with an empty default. The developer’s authenticated proxy must overwrite it for every launch, turn and supported resume while retaining runtime credentials server-side.

### 3. Configure the request

In **Agent → Global tools → + → API**, create **Read authorized customer context**. Select **POST**, use the supplied HTTPS origin plus `/v1/customer-context`, add `Authorization: Bearer {service_token}` and `Content-Type: application/json`. Set **Body → Raw → JSON** to `{"lookup_token":"{lookup_token}"}`.

Native API tool configured for the customer context service — Call the protected context service with a provided lookup token.

### 4. Bind the provided inputs

Save the request and open the attached tool’s **Input variables**. For **service_token**, choose **Default value → Secrets → warehouse_context_service_token**. For **lookup_token**, choose **Default value → Variables → warehouse_lookup_token**. Click outside to save, then reopen the rows to confirm the selected references. These inputs are provided values, not model-collected fields.

### 5. Check one authorized read

In the API editor’s **Run** panel, select the service Secret and paste a fresh, developer-issued test lookup token; attached defaults do not populate this test panel. Run once and require HTTP 200, `ok: true`, `found: true`, the intended `customer.customer_id` and a permitted `source_updated_at`. Compare the result with the data owner’s view before testing the conversation below.

#### Developer

Use Node.js 22 or later. Download the example files into an empty directory:

```sh
for file in package.json context.mjs providers.mjs server.mjs tool.mjs context.test.mjs providers.test.mjs README.md; do
  curl --fail --silent --show-error --remote-name \
    "https://www.voiceflow.com/docs/examples/data-storage/$file"
done
npm install
npm test
```

The tests are local contract fixtures. Configure these provider-specific values in the supervised service’s secret/environment configuration; replace every example resource with the administrator’s values:

```dotenv
WAREHOUSE_PROVIDER=fabric
CONTEXT_VIEW=dbo.customer_context
FABRIC_SERVER=YOUR_ITEM.datawarehouse.fabric.microsoft.com
FABRIC_DATABASE=YOUR_WAREHOUSE_NAME
FABRIC_WORKSPACE_ID=YOUR_WORKSPACE_ID
FABRIC_WAREHOUSE_ID=YOUR_WAREHOUSE_ITEM_ID
FABRIC_TENANT_ID=YOUR_ENTRA_TENANT_ID
FABRIC_CLIENT_ID=YOUR_APPLICATION_CLIENT_ID
FABRIC_CLIENT_SECRET=YOUR_SERVER_SIDE_CLIENT_SECRET
```

Also set `CONTEXT_TENANT_ID` to the fixed tenant, `CONTEXT_SERVICE_TOKEN` and `CONTEXT_SIGNING_KEY` to **different random server-only values**, and `CONTEXT_MAX_AGE_SECONDS` to your freshness policy (default 900). Generate each value separately with `crypto.randomBytes(32).toString('hex')`. The [service README](/docs/examples/data-storage/README.md) defines all configuration, deployment and result fields.

Run `node server.mjs` under your supervisor behind the existing HTTPS ingress. The default internal listener is `127.0.0.1:8080`; configure container binding/ingress deliberately. Your application must call `trustedContextTurn` from `context.mjs` behind its real sign-in middleware, using its server-authorized tenant/customer mapping on every launch, text turn and supported resume. That helper strips browser variables, state, identity and config. Keep runtime session credentials on the backend and prevent direct browser runtime access.

Set `SERVICE_ORIGIN`, `VF_TOKEN`, `PROJECT_ID` and `ENVIRONMENT` to your test resources. Use a [Voiceflow bearer credential](/docs/api-reference/authentication) with API-tool, Secret, variable, tool and compile permissions; keep it server-side. Create a restricted Secret **without a default value**, then set its explicit test Draft value:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/secret?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data '{"name":"warehouse_context_service_token","visibility":"restricted"}'
```

Retain `secret.id` as `SECRET_ID`. Prepare `secret-value.json` on your backend as `{"value":"YOUR_CONTEXT_SERVICE_TOKEN","environmentAlias":"YOUR_TEST_ALIAS","versionVariant":"draft"}` using your secret store’s value and the exact test Environment alias. These target fields belong in the request body. Keep it private and remove it after configuration:

```sh
curl --fail-with-body --silent --show-error -X PUT \
  "https://realtime-api.voiceflow.com/v1/stable/secret/$SECRET_ID/value?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @secret-value.json
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data '{"name":"warehouse_lookup_token","defaultValue":null,"color":"#515A63"}'
node tool.mjs "$SERVICE_ORIGIN" > tool.json
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @tool.json
```

Retain `apiTool.id` as `API_TOOL_ID`. Read `GET /v2/stable/api-tool-variable?apiToolID=$API_TOOL_ID&projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT` with the same bearer header. Match `variables[].name` to `id` for `service_token` and `lookup_token`. Those returned input IDs are needed for attachment.

Use `issueLookupToken` from `context.mjs` **on the backend** with the authorized test mapping, provider `fabric` and signing key to create a fresh 120-second token. Save `inputs.json` with `{"inputs":{"service_token":"{warehouse_context_service_token}","lookup_token":"SIGNED_TEST_TOKEN"}}`, replacing only `SIGNED_TEST_TOKEN`. Execute the saved Draft:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @inputs.json
```

Require `success: true`, `error: null`, `truncated: false`, `output.status: 200`, `output.body.ok: true` and the intended `output.body.customer.customer_id` when `found` is true. A 200 with `found: false` means no matching context. Standalone execution does not attach or publish the tool.

<a id="reading-customer-context"></a>

## Reading customer context

Use the current authorized result in the customer’s conversation.

**Invocation:** Attach **Read authorized customer context** when the signed-in customer asks about their support plan or open-case count. The application provides the lookup token; the service provides the approved fields. The customer and model supply neither SQL nor a customer ID.

**Current result:** Answer only from the current successful result with `ok: true` and `found: true`. A missing customer, stale source or rejected lookup follows a general-help path without a claim about their plan. `fetched_at` records the request; `source_updated_at` records upstream freshness. A freshly executed query can still read stale source data.

**Conversation test:** Ask “What support does my plan include?” through the authenticated test application. Inspect the selected tool, provided inputs, returned customer/tier and the agent’s answer. Repeat for a second customer, a later-turn identity override, an expired token and a stale view; only the permitted current customer’s fresh context may appear.

### Attach and test the lookup

#### Studio

### 1. Describe when to use the tool

Open **Agent → Global tools → Read authorized customer context**. Set **Trigger** to “Read the signed-in customer’s support plan or open-case count when they ask.” Keep the two inputs bound to their provided Secret/variable references. Trigger text guides selection; the service enforces authorization.

### 2. Use the current result

In the agent’s instructions, tell it to answer from `customer.plan_name`, `customer.support_tier` and `customer.open_cases` only after a current successful lookup. On `found: false` or failure, explain that account context is unavailable and continue with general help. Do not interpret a tier name as a policy the data owner has not defined.

### 3. Run the customer journey

Use the developer’s authenticated application and the conversation test above. API-editor **Run** is a separate standalone check. Confirm the tool result and the actual customer answer before [publishing the reviewed Environment](/docs/documentation/deploy/environments/publishing).

#### Developer

After the standalone test, use `attachment` in `tool.mjs` with `API_TOOL_ID` and the two returned input IDs to write `attachment.json`:

```js
import fs from 'node:fs';
import { attachment } from './tool.mjs';
fs.writeFileSync('attachment.json', JSON.stringify(attachment({
  toolID: process.env.API_TOOL_ID,
  tokenInputID: process.env.TOKEN_INPUT_ID,
  lookupInputID: process.env.LOOKUP_INPUT_ID
})));
```

Save that script as `attach.mjs`, set both input-ID environment values, then run `node attach.mjs`. The attachment binds `service_token` to `{warehouse_context_service_token}` and `lookup_token` to `{warehouse_lookup_token}`, with both marked provided (`required: false`). Create the attachment:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @attachment.json
```

Resolve `unresolvedReferences` from the tool/resource creation and attachment responses before compiling. Then run:

```sh
curl --fail-with-body --silent --show-error -X PUT \
  "https://realtime-api.voiceflow.com/v1/stable/environment/$ENVIRONMENT/compile?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN"
```

Run the conversation test through your authenticated application. Keep its trusted mapping and fresh token on every forwarded turn/resume; the attachment default is not the access boundary. Inspect the actual invocation, current tool result and answer. Compilation does not publish. Before a reviewed Published agent is used, populate its explicit Published Secret target and verify that version’s lookup; the Draft value alone is insufficient.

For API-tool **Capture response**, paths begin in the service JSON: `ok`, `found`, `customer.plan_name`, `customer.support_tier` and `source_updated_at`. The standalone envelope adds `output.body`; do not include that prefix in a native capture path. Clear retained output variables before a new attempt when your workflow relies on them. Missing fields or a failed request can leave earlier values intact; an old plan or ID is not current success.

<a id="maintaining-data-access"></a>

## Maintaining data access

Keep authorization, source freshness and failure handling explicit.

The service first initializes/refreshes Fabric’s own security token through the item-read REST call. Its 24-hour readiness cache keeps active use within the documented 30-day lifecycle; after an idle period, the next lookup refreshes before SQL. The driver separately authenticates each new database connection with the service principal. Rotate its Entra client secret in the service’s secret configuration before expiry and retest after reload. Review Warehouse item access and SELECT grants independently. A successful Entra token exchange does not verify the initial catalog or view permission.

#### Studio

Have the application owner confirm rotation and freshness checks for the same project/Environment you test. If access is revoked or the service is unavailable, keep the general-help path active and stop presenting account-specific answers. Ask the data owner to inspect the source pipeline when `source_updated_at` is stale.

#### Developer

Monitor the service’s unavailable response, provider permission failures, credential expiry and source age without logging tokens or returned private rows. The service has a 10-second response deadline; a timeout does not prove the remote query stopped. Update the gateway service token in its server configuration and every deliberate Voiceflow Draft/Published Secret target together. Review [Secret version behavior](/docs/documentation/build/data/secrets#publishing-reverting-and-discarding-changes) after publish, revert or discard.

### Rotate and recheck the selected connection

### 1. Confirm the credential owner and target

Identify the service deployment, provider principal and the Voiceflow project/Environment using it. Have the owner check the provider-specific expiry and permissions above before changing any value. Keep provider credentials in the service’s secret store; only the context-service token belongs in Voiceflow.

### 2. Apply the reviewed credential change

#### Studio

Obtain confirmation from the service owner that the new provider credential is installed and the supervised service has reloaded. If the context-service token also changed, have the operator update the restricted Secret’s explicit Draft/Published targets. Do not paste a provider credential into the tool’s inputs.

#### Developer

Update the chosen provider’s server configuration and reload the supervised service. If rotating `CONTEXT_SERVICE_TOKEN`, use the Secret-value operation from the connection section with the same explicit Environment/version body fields, and install the matching value on the service. Keep the previous value’s consumers accounted for during the change; the signing key and provider credential are separate secrets.

### 3. Verify the current customer result after rotation

Issue a fresh signed test lookup token, run the saved request and require the intended customer ID, `ok: true`, `found: true` and permitted source timestamp. Then test the same authenticated conversation and a revoked/expired-token case. A working credential before rotation or an old retained response is not evidence that the new connection works.

### Diagnose missing or unavailable context

Separate authorization, source age and unfinished provider work.

- **401/403 from the context service:** verify the service Secret, signed lookup token, tenant/provider audience and its 120-second expiry. Obtain a fresh backend token for a new test.
- **200 with `found: false`:** inspect the authorized mapping and approved view; do not search other customer IDs or treat this as a default plan.
- **503:** the service rejects provider failures, duplicate identities, stale timestamps and incomplete results. Use controlled server-side diagnostics and the [Microsoft Fabric Warehouse connection contract](https://learn.microsoft.com/en-us/fabric/data-warehouse/service-principals); do not send driver errors or SQL to the customer.
- **Fresh request, old source:** repair or wait for the upstream refresh. Changing the fetch timestamp does not refresh customer data.

### Revoke access deliberately

Disable the lookup without changing customer data.

Remove or disable the attached tool, revoke the provider principal/token and stop the service under its owner’s control. Review the service-token Secret’s consumers before clearing values. This read-only recipe does not modify warehouse rows; stopping access does not delete data or imported Knowledge.
