Connecting and Syncing

An integration definition says how to talk to a provider. A connection says which provider, as which account, with which credential, in one deployment. Credentials never appear in your code: they are stored privately in the deployment and only the host uses them, for the requests the definition declares. You set up a connection with the bijection integration commands, or from the Sources page of the console.

Deploy the integration and schema

Push the integration definition and the schema that binds its collections, for example with bijection dev. Synced tables exist from this point on, empty.

Store the credential

Create a private credential from a file or from piped stdin:

bijection integration credential-create CRM_CREDENTIAL --from-file crm-credential.json

Configure the connection

Name the connection, point it at the integration’s address and the provider’s base URL, and reference the credential:

bijection integration configure crm \
  --module crm.js --export crm \
  --base-url https://crm.example.com/api \
  --credential-ref CRM_CREDENTIAL

Verify the account

Admit an identity check under a request ID of your choice, then run it:

bijection integration identify crm verify-1
bijection integration run verify-1

Install the source

Install the synced table’s source on the verified connection:

bijection integration install crm customers

The command prints the new source’s ID. From now on the collection is read on its sync.every schedule and the customers table fills in.

Store the credential

credential-create reads the value from --from-file or from piped stdin, never from an argument, and never prints it. The value must be valid UTF-8 and at most 8 KiB, and every byte is kept, including a trailing newline. Use credential-rotate with the same name to replace it later, and credential-status to inspect its metadata. For an HTTP integration, the credential is a JSON envelope that names its kind and the origins it may be sent to:

crm-credential.json

{
  "kind": "bearer",
  "token": "…",
  "allowed_resource_origins": ["https://crm.example.com"]
}

allowed_resource_origins lists one to eight origins, and one of them must be the origin of the connection’s base URL. The credential is never sent anywhere else. A bare secret is refused with IntegrationCredentialEnvelope.

`kind`	Fields
`bearer`	`token`
`keyword`	`scheme`, `token`, optional `parameter`: an `Authorization` scheme other than `Bearer`
`basic`	`username`, `password`
`api_key`	`name`, `value`, `placement` (`header`, `query` or `body`)
`oauth_refresh`	`token_endpoint`, `client_id`, `client_secret`, `refresh_token`, optional `scope`
`oauth_client_credentials`	`token_endpoint`, `client_id`, `client_secret`, optional `scope` and `resource_headers`
`sigv4`	`access_key_id`, `secret_access_key`, `region`, `service`, optional `session_token`
`goog4`	`access_key_id`, `secret_access_key`

Every kind also takes allowed_resource_origins. PostgreSQL and mail integrations use their own private configuration instead of an envelope.

Configure the connection

configure creates or updates a named connection. The name, crm above, is how the other commands refer to it.

--module and --export name the integration’s address: the module path inside bijection/, with .js, and the export name.
--base-url is the provider’s API address. It must use https (plain http only for a loopback address) and carry no query, fragment or user info. The contracts’ routes are appended to it. Omit it for PostgreSQL and mail integrations.
--credential-ref names the credential.
--component selects a component; the default is the root.
--setup key=value supplies a setup field the definition declares. --show-setup lists them without changing anything.

Changing a connection’s configuration clears its verification and stops work started under the old configuration. Verify it again before its sources sync.

Verify the account

identify admits a run of the definition’s identify handler, and run executes it. The provider account it reads becomes the connection’s verified identity, and later syncs are checked against it. The request ID is yours to choose and identifies the work. If a command’s response is lost, run it again with the same ID to recover the same request instead of starting another. bijection integration status <request-id> shows where a request stands.

Install sources

install <connection> <table> installs the source that fills one synced table from a verified connection. It prints the source ID, the same value synced documents carry in source_id. Install each synced table of the integration you want to fill. bijection integration sources lists the installed sources with their connection and sync health.

Following syncs

bijection integration source-status <source> shows a source’s schedule, its state and any work it retains. The console’s Sources page shows the same information for every source, grouped by connection. A source is in one of these states:

Scheduled: it syncs on its interval.
Retrying: a sync failed in a way that can succeed later, and a retry is scheduled.
Blocked: a sync can’t continue without you. Published data stays readable.

Sync history

Sync history is in beta.

Each source keeps its open sync and its newest 50 finished syncs. For each run you see when it started, what started it (the schedule, a manual request, a provider notification, reconciliation or a repair), its state, and what it admitted: pages, requests, response bytes and records received. Records received count what the run admitted, not the rows that changed in the table: a sync that found nothing new completes with records received and nothing published. The history appears under each source in the console, and in the syncs field of source-status.

Sync now

To sync a source before its next scheduled run:

bijection integration refresh <source>

or click Sync now on the source in the console. If a sync is already running, the request is served by the next one rather than starting a second sync.

Test connection

Connection checks are in beta.

Test connection on a source in the console runs the connection’s identify handler again and compares the answer with the verified account, without changing the connection. The result is one of:

Confirmed: the connection answers as the account it was verified as.
Identity differs: the connection now answers as a different account. Syncs keep their verified connection; reconfigure or verify it again.
Unverified: the connection answered, but was never verified.
Failed, with the reason.

From your application

Sync history, Sync now and connection checks in applications are in beta.

An application built with applicationQueries from bijection/server also exposes three functions for its synced collections, for signed-in users only:

sourceSyncs({ collection, source? }) lists the collection’s sources, each with its handle (the source_id its rows carry), status, open and latest sync and connection check. Name a source to also get its history, newest first, at most 50 syncs. Counts and times are exact bigints. A user who may not read the collection’s rows is refused.
requestSourceSync({ collection, source }) is Sync now. It answers accepted, or coalesced when a sync was already requested. It is refused for a source whose connection was reconfigured since it was installed; install it again first.
requestConnectionCheck({ collection, source }) records a check for the calling user and answers its request ID. The user then runs it with runConnectionCheck from bijection/apps and their own token. If the response is lost, running the same ID again finishes the check or returns its result.

Both requests spend provider budget, so nobody can make them until you decide who may, with sourceControl. It runs after your authorize function, and only true allows the request. The user also needs read access to the source’s rows.

bijection/application.ts

import { applicationQueries } from "bijection/server";
import { requireMember, isAdmin } from "./membership";

export const { sourceSyncs, requestSourceSync, requestConnectionCheck } =
  applicationQueries({
    collections: { customers: { label: "Customers" } },
    operations: {},
    authorize: requireMember,
    // Admins may sync any source; everyone else may only read the history.
    sourceControl: async (ctx) => isAdmin(ctx),
  });

import { applicationApi, runConnectionCheck } from "bijection/apps";

const api = applicationApi();
const { request } = await client.mutation(api.requestConnectionCheck, {
  collection: "customers",
  source,
});
const result = await runConnectionCheck(deploymentUrl, token, {
  source,
  request,
});

When a sync stops

When a source is blocked, source-status reports the reason and the ID of the retained work. After fixing the cause, resume exactly that work:

bijection integration resume <source> <request-id>

To give up on the current sync instead, cancel it; future syncs stay scheduled:

bijection integration cancel-source <source> <request-id>

Deploying a changed integration definition stops work that started under the old code. If a source is blocked after a deploy, run install again for the same connection and table to update its binding, then resume it. The console does both with Update binding and resume.

Connected accounts

Connected accounts are in beta.

A connection configured with configure uses one deployment credential. An integration can instead be connected by an application user with their own provider account, through the provider’s authorization flow. The account-* commands and the connected accounts panel on the Sources page drive this flow:

account-authorize starts an authorization for an application user and returns the provider URL to visit.
account-callback completes it with the code the provider returns.
account-resources lists what the account offers to read, and account-select installs the chosen resources.

Four lifecycle operations have different effects:

Operation	Syncing	Provider authority	Synced records
`account-pause`	Stopped	Kept	Kept
`account-resume`	Resumed	Kept	Kept
`account-disconnect`	Stopped	Revoked	Kept
`account-erase`	Stopped	Revoked	Removed

Disconnecting is final for that authorization: reconnecting starts a new one. Erasing requires a disconnected account and removes the records its sources published, but not effects already delivered to the provider. See the CLI reference for every option.

Get Started

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

Connecting and Syncing

Store the credential

Configure the connection

Verify the account

Install sources

Following syncs

Sync history

Sync now

Test connection

From your application

When a sync stops

Connected accounts

​Store the credential

​Configure the connection

​Verify the account

​Install sources

​Following syncs

​Sync history

​Sync now

​Test connection

​From your application

​When a sync stops

​Connected accounts

Store the credential

Configure the connection

Verify the account

Install sources

Following syncs

Sync history

Sync now

Test connection

From your application

When a sync stops

Connected accounts