Integration Concepts

Documentation Index

Fetch the complete documentation index at: https://help.statisfy.com/llms.txt

Use this file to discover all available pages before exploring further.

Most data-source integrations in Statisfy share the same configuration model. Whether you are syncing a Snowflake table, a PostHog HogQL query, or a Jira project, the self-serve settings page exposes the same building blocks: what to pull, how to match rows to accounts, and how often to run. This page explains those shared concepts once. Each per-integration guide then focuses on the specifics — credentials, dialect, and any integration-only knobs. Applies to:

• BigQuery
• Snowflake
• Redshift
• PostgreSQL
• PostHog
• Jira and Jira Service Desk

Salesforce, HubSpot, and Gainsight have related but separate settings flows — see their own pages for details.

​

Where to find the settings

Once an integration is connected, open Integrations → {integration} → Settings. The settings page is the single place to:

• Add or edit queries / project rules
• Map result columns to Statisfy fields
• Pick how rows match to accounts
• Set a sync cadence
• Run a one-off sync on demand
• Review the active configuration version

You need Admin access in Statisfy to view or change these settings.

​

Query types

For warehouse and PostHog integrations, every query you author has a type that tells Statisfy what to do with the result rows. For Jira, the equivalent unit is a project rule — each rule says “for this project (and optionally these issue types), apply these field mappings and customer-matching logic”. See the Jira page for details.

​

Account resolvers

Every row that comes out of a query has to be matched to a Statisfy account before it can be stored. The account resolver is the rule that tells Statisfy which column on the row identifies the account, and what kind of value it contains.

​

Fuzzy matching cutoff

The Account Name resolver does approximate matching to absorb small typos, casing, and “Inc.” vs. “Inc” differences. The cutoff (0.0–1.0) controls how strict the match has to be. The default suits most cases; raise it if you see false positives, lower it if legitimate matches are being missed.

​

Person resolvers (warehouse and PostHog only)

For custom_field queries that target people (contacts) instead of accounts, pick an email column. Optionally also map first name, last name, or a single full-name column — Statisfy will use these to upsert the person record. Internal vs. external is decided by comparing the email domain against your tenant domain.

​

Column transformers

Sometimes a column has the right value embedded in something else — a CRM ID with a org_ prefix, an email field with extra whitespace, a hostname when you want just the domain. Column transformers let you reshape a column before it’s used. Available transforms: Transforms run in order — chain them to combine effects. They apply both to resolver columns (before account matching) and to value columns (before being written to a field).

​

Field and metric mappings

A query’s columns become useful only when they are mapped to Statisfy fields.

• For custom_field queries, pick a Statisfy custom field for each value column. The field must exist on the target entity (account or people); create it in Object Manager first if needed.
• For product_usage queries, pick the metric (product dimension) the value belongs to, and the timestamp column that places it in time. Create new product dimensions in Object Manager.
• For custom_object queries, map each attribute on the custom object record.

If you want a single column to land in multiple places, add it to the mapping more than once with different targets.

​

Schedule

Each query and each Jira rule can run on its own cadence. The available cadences: HOURLY · TWO_HOURS · FOUR_HOURS · SIX_HOURS · TWELVE_HOURS · DAILY · WEEKLY · MONTHLY If a query doesn’t set its own cadence, it inherits the integration default (typically WEEKLY). For warehouse product_usage queries that aggregate by week, the Week Start Day at the integration level decides which day of the week the snapshot is anchored to (0 = Monday, 6 = Sunday).

​

Date placeholders (warehouse only)

Warehouse queries can reference the active sync window via placeholders:

• {START_DATE} — the start of the current window, as YYYY-MM-DD
• {END_DATE} — the end of the current window, as YYYY-MM-DD
• {END_DATE_SQL} — the end as a SQL-quoted literal, ready to drop into a WHERE clause

The window is derived from the query’s cadence — for WEEKLY, the previous Monday through Sunday; for MONTHLY, the first to last day of the previous month; for DAILY, the previous day. Use these to keep queries incremental.

​

Preview and validation

Before saving a query, use the Preview button to run it against your data source and inspect a sample of rows. The preview is also the validation step:

• For SQL warehouses, syntax is checked against the warehouse’s dialect (Postgres, Redshift, BigQuery Standard SQL, Snowflake) before execution. Dialect-specific functions that aren’t supported are flagged at save time.
• For PostHog, HogQL has no static schema browser, so preview-by-execution is the only way to validate.
• For Jira, validation happens against the JIRA REST API at save — invalid project keys, unknown field IDs, or unsupported issue type filters surface immediately.

​

Configuration history

Every save creates a new configuration version. The settings page header shows where the active config came from: Older versions are preserved for rollback. If you need to revert, contact support@statisfy.com — there is no in-app rollback yet.

​

Running a sync on demand

Each integration’s settings page has a Run Sync Job button that enqueues an immediate sync without waiting for the next scheduled run. The most recent job’s status (queued / running / completed / failed) and timestamps are shown on the same page.

​

Bootstrap vs. periodic

When you first connect a data source, Statisfy runs a bootstrap sync covering the last 30 days of data. After that, scheduled periodic syncs run on the cadence you’ve configured, pulling only the active window each time. Both kinds of jobs show up in the job history on the settings page.

​

What you can’t do (yet) from the UI

• Rollback to an older version — supported via the database but not yet wired into the UI. Ask support.
• Bulk-edit queries across integrations — each integration has its own settings page.
• Pause an integration globally — you can mark individual queries / rules as inactive (is_active = false), but there is no single off-switch beyond disconnecting.

​

Troubleshooting checklist

Rows are not landing in Statisfy

1. Confirm the account resolver is using a column whose values exist in Statisfy — for CRM ID resolvers, the matching accounts must already be synced from your CRM.
2. Run the Preview and verify the resolver column actually contains the expected values for those rows (no nulls, no stray prefixes).
3. Check whether column transformers are inadvertently filtering rows (skip_if_* transforms).
4. For product_usage, confirm the metric (product dimension) exists in Object Manager.
5. Look at the latest job status — a failed job will show the error.

Some rows match but most don't

• Try a different resolver. CRM ID and Statisfy Account ID are the most exact; Email Domain and Account Name are best-effort.
• For Account Name, raise or lower the fuzzy cutoff depending on whether you’re seeing false matches or missing matches.
• For Custom Field resolvers, make sure the field is populated on the target accounts — empty values can’t be matched.

The query is too slow or times out

• Tighten the date range using {START_DATE} / {END_DATE_SQL}.
• Drop the cadence to DAILY so each run covers a smaller window.
• For warehouses, push filters into the query rather than relying on Statisfy to discard rows post-hoc.

A saved configuration isn't taking effect

• Confirm the version badge in the header shows Database (vN) and not Default (Code) — if it still says Default, your save didn’t land.
• Check that the query is marked active — inactive queries are kept for reference but don’t run.
• Trigger a manual sync with Run Sync Job and watch the job history.

​

Need help?

If you get stuck wiring up the resolver, picking the right query type, or understanding why a row isn’t matching, reach out to support@statisfy.com with the integration name and (if possible) the query you’re trying to save. Support can also help with multi-version rollbacks and one-off backfills outside the standard cadence.