Package Description
Grain Ledger Giving Sync connects Rock RMS to Grain Ledger for churches that want giving and donor data available in fund-accounting workflows while keeping Rock as the ministry source of truth. The default workflow is read-only from Rock: Rock sends authorized giving, donor, household, fund, batch, pledge, and recurring gift data to Grain over outbound HTTPS, with no inbound access to the Rock server required.
Read-only sync first
The plugin is built around a scheduled Rock job named Grain Ledger Giving Sync. Because Rock core save hooks are not available to third-party plugins for these entities, the job uses ModifiedDateTime watermarks and incremental polling. After the initial setup, each run sends only new or changed records to Grain using idempotent event IDs.
Rock administrators can keep the integration in a read-only posture by leaving Grain outbound commands disabled. In that mode, the plugin reads from Rock and posts to Grain; it does not create or update Rock people, families, pledges, documents, or financial records.
What it installs
- A scheduled Rock job named Grain Ledger Giving Sync.
- A Finance > Grain Ledger setup and dashboard page in Rock.
- Secure pairing from Rock to Grain Ledger through a Grain-issued connection.
- A small Rock state table,
_com_grainledger_GrainSyncState, for credentials, dashboard status, feature preferences, and sync watermarks.
- Fund, campus, and Person document type bootstrap data so setup can be completed in Grain before historical sync begins.
- Optional read-only Grain insight blocks for person, household, batch, and financial account context.
What it syncs to Grain
- Campuses: Rock campus ID, name, short code, active flag, campus type, and campus status.
- Households: Rock giving groups from
Person.GivingGroupId, including members, primary giver, campus, and home address when available.
- People and aliases: names, email, mobile phone, birth date, record status, connection status, title, suffix, primary family context, giving group fields, and PersonAlias merge identity.
- Financial accounts and funds: Rock financial account ID, public name or name, description, GL code, and active status.
- Financial batches: batch ID, name, start date, control amount, and Rock batch status. Closed Rock batches map to Grain batch commit semantics.
- Gifts and split gifts: batched financial transactions, transaction date, donor person ID and alias ID, payment method, masked last four, card brand, transaction code, campus, processing fee fields when exposed by the Rock version, and each transaction detail line with account and amount.
- Pledges: Rock FinancialPledge ID, donor, account, amount, frequency, start and end dates, status, modified timestamp, and configured pledge attributes.
- Recurring gifts: Rock scheduled transaction ID, donor, account, amount, frequency, status, start date, end date, next payment date, and gateway schedule metadata when available.
Read-only insight blocks
The package includes optional Obsidian blocks that can be placed on Rock pages to show Grain context without writing data back to Rock:
- Grain Giving Snapshot for person and family pages.
- Grain Batch Status for financial batch pages.
- Grain Fund Snapshot for financial account pages.
These blocks use the stored Rock integration credentials server-side and respect Rock page and block security. They do not require browser-side Grain credentials.
Optional pledge sync back to Rock
For churches that want pledge workflows in Grain to update Rock, the scheduled job can optionally process Grain outbound commands. This is separate from the read-only sync and should be enabled only when pledge write-back is part of the implementation plan.
- PUSH_PLEDGE: creates or updates a Rock pledge for a donor already linked to Rock.
- UPSERT_DONOR_AND_PUSH_PLEDGE: creates the Rock person, family or giving group context needed for an unlinked Grain donor, then pushes the pledge.
- ATTACH_PLEDGE_CARD_TO_PERSON: downloads a signed pledge card file from Grain and attaches it to the matched Rock person as a Person Document when the job's pledge card attachment setting is enabled.
Pledge write-back uses fund mappings to choose the Rock financial account, idempotency keys such as pledge:{id} and pledge-card:{fileId}, per-command result reporting back to Grain, and retry limits for failed commands.
How the sync works
The plugin runs inside the church's Rock instance and sends authorized server-side requests to Grain Ledger. Requests use Authorization: Bearer credentials, the Grain organization header, and optional HMAC-SHA256 request signing when a webhook secret is configured. The plugin verifies credentials before each run, posts batches to Grain, retries transient HTTP failures, and records current phase, last run status, entity counts, watermarks, and recent errors on the Finance > Grain Ledger dashboard.
Setup requirements
- Rock RMS 1.14.0 or newer.
- A Rock administrator who can install plugins and manage scheduled jobs.
- Outbound HTTPS access from the Rock server to
https://api.grainledger.com.
- A Grain Ledger user with permission to manage integrations.
- Fund mapping in Grain before historical giving sync begins.
- Campus mapping in Grain when the organization uses campuses.
- A Person document type in Rock only if pledge card attachment write-back is enabled.
Notes
- Use a Rock staging environment first when possible.
- The first historical sync can take longer on large Rock databases.
- The scheduled job defaults to incremental sync; batch size and max batches per run can be adjusted for large Rock environments.
- Settlement sync and Grain-to-Rock pledge write-back are optional advanced workflows and should be enabled only when part of your implementation plan.