Skip to main content

Developers · Guide

Connect Tableau

Connect Tableau Desktop to the OData reporting feed with the credential as a user name and password, and load it into other tools and warehouses.

Tableau reads your organisation’s records through the OData reporting feed, the same records your Backed reports read, and only your own organisation’s.

Before you start

  • A credential with the read:reporting_feed scope (`Read reporting feed` on the `API Access` tab). Only an Administrator who can generate reports can give it. Without it the feed answers `403 insufficient_scope`.
  • Your organisation’s address plus /odata/v4/, such as https://your-org.backed.giving/odata/v4/.

The feed is OData v4. /odata/v4/ lists its entity sets and /odata/v4/$metadata describes every column. The entity sets are Applications, Applicants, RegistrationEntities, FundingRounds, Assessments, Decisions, Contracts, Milestones, Payments, Funds. The OpenAPI document points to the feed (x-odata-feed) but does not describe it: $metadata does.

Signing in

A tool that can only ask for a user name and password signs in to the feed with the credential itself: the Client ID as the user name and the Client Secret as the password. The pair is checked on every request, so there is no token to renew. Only the feed takes a user name and password; the rest of the API takes a token alone. A tool that can send headers may instead send Authorization: Bearer <token>, with a token from POST /oauth/token.

With the OData connector

  1. In Tableau Desktop, under Connect, select To a Server, then OData.
  2. Under Server, enter https://your-org.backed.giving/odata/v4/ with your organisation’s address.
  3. Under Authentication, choose Username and Password. Enter the Client ID as the Username and the Client Secret as the Password, and select Sign In.
  4. Pick the entity set you want, such as Applications, and build your view. Add another OData connection for each further entity set.

Other tools and data warehouses

Any tool that can send an Authorization header can read the feed, with a token or with the pair as Basic authentication. A loader that runs on a schedule should ask for a new token at each run.

Read only what changed

  1. Read an entity set in full with the header Prefer: odata.track-changes, following every @odata.nextLink. Leave out $filter: delta links are issued for unfiltered reads only.
  2. The last page ends with @odata.deltaLink. Keep that address.
  3. Next time, read the @odata.deltaLink. It returns the rows changed since, and its last page ends with a new @odata.deltaLink.
  4. A delta link works only for the credential it was issued to, for 30 days. An older or unknown one answers 410 delta_token_expired: read the entity set in full again.
Start change tracking
curl "https://your-org.backed.giving/odata/v4/Payments" \
  -H "Authorization: Bearer $BACKED_TOKEN" \
  -H "Prefer: odata.track-changes"

Deleted rows, Field Tag columns and value formats are in OData feed for BI tools and data warehouses. Power BI is in Connect Power BI.