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

# Release updates

> Major Darpan updates grouped by release tag.

Darpan releases from newest to oldest, with product and operator changes that affect upgrade, validation, or rollback decisions. Work already on `main` but not yet tagged appears first, marked as unreleased — for release principles and review questions, see [Release discipline](/engineering/release-discipline).

Backend and UI tags are coordinated for major and minor releases; patch tags between them are backend-only.

## v1.5.1 — August 31, 2026

Cut together with app `v2.6.1` and `shopify-darpan v0.6.1`. One section covers the 1.5 line: `v1.5.0` (August 26, with app `v2.6.0`, `darpan-hotwax v0.8.0`, `shopify-darpan v0.6.0` and `database-darpan v0.2.0`) and the `v1.5.1` patch. NetSuite (`v0.2.0`), `darpan-hotwax` and `database-darpan` are unchanged by the patch.

**Product**

* **Slack alerts.** Run-completion alerts reach Slack as well as Google Chat. A workspace is connected once per tenant — through a one-click install where the deployment allows it, or by pasting a bot token where Slack administrators do not permit installing apps — and each chat space then picks the channel it posts to.
* **Alerts lead with a verdict.** Messages open with the verdict rather than a table of counts, name value mismatches on their own line, and vary their wording with the time of day in the tenant's own timezone.
* **Databases are a first-class source.** MySQL, PostgreSQL and IBM Db2 join files, SFTP and APIs, with a saved connection and a `SELECT` that may take the run's window.
* **Same-system comparison.** A run can compare two instances of the same system, so staging against production, or one database against another, is now a normal reconciliation.
* **Schemas from a CSV header row.** A schema can be inferred instead of typed field by field, and CSV sides pick columns from a list rather than typing field paths, with likely primary-key columns ranked first.
* **Automation drift is visible.** An automation reports when it has drifted from its saved run, and can be re-synced from it.
* **Automation schedules and state.** Schedules are interpreted in the tenant's timezone rather than UTC, and an automation can be activated or deactivated from the dashboard.
* **Ask Darpan gains a command mode.** Type `/` to run something rather than navigate to it, starting with `/switch-tenant`.
* **Returns reconciliation drops impossible differences.** Three classes that cannot exist by definition are suppressed: whole-order cancellations, superseded return drafts, and refunds for items that were never shipped. Records reported missing are re-checked by point lookup before they are reported.
* **Scheduled runs do that re-check too, from `v1.5.1`.** An automation and a hand-started run over the same window report the same numbers, and a scheduled run records the same steps a hand-started one does — including the notification step, so whether an alert fired is answerable from the timeline. **On `v1.5.0` this takes effect for database sources only; upgrade to `v1.5.1` for OMS and Shopify automations** — and see Before you deploy, because the counts move.
* **A run says when it did not verify.** If verification is switched off, a configuration cannot be resolved, or a difference document cannot be read, the run records a verification step with the reason instead of publishing counts that look verified. Deliberately silent when nothing was missing, when rules failed, or when neither side has a lookup to re-check against — two uploaded CSVs have no source of record.
* **Exclude in-progress Shopify returns.** Shopify return references gain a **Return workflow status** field on the rules board. Excluding `REQUESTED,OPEN` drops returns that have no OMS counterpart yet. Requires `shopify-darpan v0.6.1` alongside the backend.
* **Alerts stop repeating themselves.** The trailing audit paragraph is gone; the numbers an operator acts on are in the details block above it. A fully clean run is now just the verdict. The run-result page's audit trail is unchanged.
* **Suppression counts add up.** A returns run's per-reason suppression tallies now sum to the number of rows actually removed, where a row qualifying under two rules was previously counted under both.
* **Runs are named and timed correctly.** Alerts name the system a count belongs to rather than the endpoint the extract came through, and the run-result page reads the run's time from the stored instant instead of a zone-less string. The rules board titles its columns with the system too, including for newly created runs.
* **Every displayed time names its zone.** `Aug 31, 2026, 11:37 AM IST` rather than `11:37 AM`, across run results, run history, the automation dashboard, the diff page and settings. Correct across daylight-saving changes. Date-only labels are left alone, where a zone misleads across midnight.
* **Tenant timezone wins.** A tenant's timezone takes precedence over a viewer's personal one, and takes effect immediately when changed.
* **Returns extraction is more resilient.** A transient gateway failure no longer discards a whole returns extraction.

**Operators**

* Slack needs no deployment configuration for the bot-token route. The one-click install additionally needs `darpan.slack.clientId`, `darpan.slack.clientSecret` and a resolvable redirect URI.
* One-time data migrations run through a registry with a ledger, prerequisites and a supervisor, exposed to the admin application and as a `Migrations` screen. `run#PendingMigrations` is idempotent and safe to run on every deployment.
* Source configurations carry explicit per-endpoint access. Endpoints not enabled are disabled, including endpoints added to the registry later.
* Blank CSV cells are now read as empty values rather than as absent fields, which changes what a comparison reports for files with blank cells.
* A database source fails an extraction that exceeds its max-rows cap rather than truncating it.
* Scheduled-run verification is on by default and needs no configuration. The kill switch is `-Ddarpan.reconciliation.automation.verifyMissingDiffs=false`, and only an exact `false` disables it, so an unrecognised value leaves verification on. From `v1.5.1` it gates all three verification passes. Verification adds roughly 46 seconds to a scheduled run.
* A scheduled run's steps are `RESOLVE / EXTRACT_FILE1 / EXTRACT_FILE2 / COMPARE / VERIFY / WRITE_OUTPUT / NOTIFY` — the same list a hand-started run records. Counting them is how to tell a verified run from an unverified one.
* Backend `v1.5.1` and `shopify-darpan v0.6.1` deploy together. The connector emits the return status the rules-board field selects; with only one of the pair, a rule on that field matches nothing and reports zero exclusions, which is indistinguishable from a rule that is simply not deployed.
* HotWax OMS configurations gain `returnsPageSize` (1–1000) for shrinking the returns page when the gateway struggles at the default.
* The one-time cleanup for chat webhooks that cannot be decrypted now covers both the legacy and the provider-agnostic column, and validates each against its own provider, so a working Slack webhook is not cleared by it.

**API**

* 20 methods added and one response field removed across the line, so the contract version moves from `2` to `3`. The contract moves from 90 to 110 methods (86 public facade, 24 administrative). `v1.5.1` adds no methods and changes no shapes; it moves the contract's version string only.
* Added on the public surface: five Slack methods, three config-sharing methods, two source-endpoint methods, `infer#JsonSchemaFromCsvText`, `sync#Automation` and `change#ExpiredPassword`.
* `get#Automation` gains a `syncStatus` response field.
* Administrative additions are the seven migration methods, which are not part of the public tenant surface.
* The one removal: `list#TenantChatSpaces` no longer returns `chatSpaces[].googleChatWebhookUrlMasked`, dropped when chat webhooks moved to clear text — read `chatSpaces[].googleChatWebhookUrl` instead, or the provider-agnostic `chatSpaces[].webhookUrl` and `chatSpaces[].webhookConfigured`. No method was removed.
* `returnsPageSize` is added to `save#HotWaxOmsRestSourceConfig` and `list#HotWaxOmsRestSourceConfig` as an additional field on existing methods, so integrations need no change for it.
* See the [API changelog](/api-reference/changelog).

**Before you deploy**

* Scheduled runs verify their differences, which they never did before. The counts your automations report will drop, and the drop can be large — on one production automation it went from 532 to 2.
* Nothing about the data changed: the earlier number counted records that a direct lookup shows are present, and the new number is what a hand-started run of the same rule set already produced.
* Counts can also rise on orders runs, where the exchange check adds Shopify exchanges that are genuinely absent from HotWax. The returns checks remove false positives; the exchange check adds real differences.
* Tell whoever reads those counts before the deploy rather than after, because a count moving by two orders of magnitude overnight reads as a broken reconciliation unless it is expected.

**Upgrade**

* Coming from `v1.4.0`: load `v1.5.0`'s 54 seed records via `./gradlew loadDarpanUpgradeData`, then `v1.5.1`'s 2. `v1.4.0`'s upgrade data is a prerequisite.
* Already on `v1.5.0`: load `v1.5.1`'s 2 records only. They add the **Return workflow status** field to the rules board and let the Shopify returns connector carry exclusion rules. Until they load, the exclusion control is hidden for that connector.
* Then run `run#PendingMigrations` once, or use the Migrations screen: it walks the registered one-time migrations, skips any already applied, and is safe to run again. That covers the `v1.2.0` and `v1.3.0` one-time services, so an environment behind on either no longer needs to chase them separately.
* **One step is not covered by that sweep.** The Shopify return-status field was renamed within `v1.5.1`, and a seed load never deletes, so the superseded field must be swept explicitly, once per environment, after the load: run the `RETIRED_FIELDS` migration with force set, from the Migrations screen or as `admin.MigrationAdminServices.run#Migration migrationId=RETIRED_FIELDS force=true`. It is safe to run more than once. Skip it and the rules board offers two return-status fields, one of which matches nothing.
* Any exclusion rule saved against the superseded field keeps its stored expression and matches nothing. Re-add it on **Return workflow status** with values `REQUESTED,OPEN`.
* Of `v1.5.0`'s 54 records, fifty-one are additions. Three restate rows that already exist: the stored `OMS` and `SHOPIFY` names become "HotWax" and "Shopify" wherever a system is named, and HotWax transfer orders group under HotWax in the source picker. Renaming affects future runs only — a run's file labels are recorded when it executes, so past runs keep the names they were given.
* No schema migration is required; new tables and fields are created on startup.

**Rollback**

* Schema and seed additions are additive and the restatements only correct display names, a picker grouping and one connector's field list, so rolling the backend to `v1.4.0` is safe and the loaded records do not need reverting — `v1.4.0` ignores what it does not know.
* Keep the app on `v2.5.0` if the backend goes back to `v1.4.0`, since `v2.6.x` depends on methods `v1.4.0` does not expose.
* Rolling the backend to `v1.5.0` while leaving `shopify-darpan` at `v0.6.1` is safe — the extract carries one field nothing reads. The combination to avoid is backend `v1.5.1` against `shopify-darpan v0.6.0`.
* Setting `darpan.reconciliation.automation.verifyMissingDiffs` to false restores the unverified scheduled counts without a redeploy, and records a verification step saying why.
* An integration reading `googleChatWebhookUrl` keeps working on `v1.4.0`, which returns both that field and the masked one; an integration that moved to `webhookUrl` or `webhookConfigured` will not, as those are new in the 1.5 line.
* Roll all component pins back together.

## v1.4.0 — August 7, 2026

Cut together with app `v2.5.0` and `darpan-hotwax v0.7.0`. Shopify (`v0.5.0`), NetSuite (`v0.2.0`), and database (`v0.1.0`) component pins are unchanged.

**Product**

* **Run now, followed end to end.** Running an automation by hand is now something you can follow start to finish. "Run now" opens the live progress view of the run it just started, on both API and SFTP automations, and the timeline advances through resolve, extract, compare, and write as the run works.
* **Cancel.** Stops the run and records it as cancelled.
* **No start-up timeout.** Long-starting automations no longer time out before their run begins.
* **Errors in full.** A failed run shows its full error text rather than a message cut short, and error messages stay on screen until you dismiss them.
* **Notifications hold up across retries.** If you ask to be told how a run ends, you are told once, including when an automation gives up after its last attempt. Failing SFTP automations now alert the same way API automations do.
* **Clean runs read clean.** A run that finishes clean is no longer headlined as having issues.
* **Transfer orders as their own source system.** HotWax transfer orders can be reconciled directly, matched on order date so a transfer that moved inside your window is not missed.
* **Rule-aware trimming.** A rule set with rules keeps the fields those rules reference in the extract instead of switching trimming off entirely, and "Product store" is available as an exclusion field for OMS sources.
* **Typed text is kept.** Text typed into the exclusion and primary-id boxes is kept when you click Save.
* **Schedules in your timezone.** Automation schedules display in your preferred timezone.

**Operators**

* Production images pin `DARPAN_REF=v1.4.0` with `darpan-hotwax` at `v0.7.0` — move these together, since the transfer-order connector row this release adds names an extract service that exists only in the v0.7.0 component.
* Deploy the backend before the app: app `v2.5.0` reads run detail and the transfer-order source type that exist only in `v1.4.0`.
* Transfer-order reconciliation covers extraction and comparison; there is no transfer-order-specific verification pass.
* A status-defined extract is capped at 50,000 records and stops with a clear message naming the limit rather than returning a short result.
* Exclusion filters still reach the HotWax OMS getters only.

**API**

* No methods are added or removed — the published contract stays at 90 methods and the contract version stays at `2`.
* Run status gains a full-detail error field, so integrations need no change to keep working.

**Upgrade**

* Existing environments load three seed records — the transfer-order source system, its connector registry row, and one window-mode value — via `./gradlew loadDarpanUpgradeData`. All three are additions; nothing existing is changed, so the load does not alter how current reconciliations behave.
* Until it runs, transfer orders do not appear as a source-system option.
* This release adds no one-time service to run.
* This upgrade file carries only what is new in `v1.4.0`. If an environment has not yet loaded the `v1.3.0` upgrade data and run its one-time `migrate#AutomationExcludeFilters` service, do that first, or exclusion filters stay inert there. That service is safe to run again if its status is unknown.
* No schema migration is required; four fields are added to existing tables on startup.

**Rollback**

* Schema and seed additions are additive, so rolling the backend to `v1.3.0` is safe and the loaded records do not need reverting — `v1.3.0` code ignores them.
* Keep the app on `v2.4.0` if the backend goes back, since app `v2.5.0` expects run detail and a source type a `v1.3.0` backend does not return.
* Roll all component pins back together.

## v1.3.0 — August 5, 2026

Cut together with app `v2.4.0` and `darpan-hotwax v0.6.0`. Shopify (`v0.5.0`), NetSuite (`v0.2.0`), and database (`v0.1.0`) component pins are unchanged.

**Product**

* **Exclusion filters per source system.** A rule set can carry them, so records you expect to differ stop being reported as differences run after run.
* **Automations inherit them.** Scheduled automations carry their own copy of those filters, seeded once from the rule set when the automation is created, so a scheduled run starts out lined up with what an interactive run would produce.
* **Excluded during extraction.** Excluded records are dropped before they are written to the extract file and compared, so the stored extract and the comparison both shrink — the source is still queried in full.
* **The rules board is the last step of creating a run.** The exclusion editor is reachable from it, with an exclusions summary on the rule set manager. The board also shows a ghost rule before you have written one, and reveals what a term means on hover.
* **Live elapsed clock.** Runs in progress tick one.
* **Consistent source naming.** Source systems are named the same way everywhere — the readable name rather than the internal code, with the connection shown beneath it.
* **One shared design system.** The app draws its type, spacing, and surfaces from it, so headers, chips, selects, and empty states line up across pages, and only one font weight is downloaded.

**Operators**

* Production images pin `DARPAN_REF=v1.3.0` with `darpan-hotwax` at `v0.6.0` — move these together, since the connector registry row this release updates names a parameter the v0.6.0 orders getter reads.
* Deploy the backend before the app: app `v2.4.0` calls facade fields that exist only in `v1.3.0`.
* Exclusion filters reach the HotWax OMS orders getter only; Shopify and NetSuite getters accept no filter parameter yet, and the missing-diff verify pass applies no exclusion rules by design.
* An automation's filters are frozen when it is created — editing a rule set's filters later does not reach automations that already exist, so re-create an automation if its filters must follow a changed rule set.
* Extract progress now reports a count on both file sides while a stage runs, instead of holding its starting value until the stage finished.

**API**

* No methods are added or removed — the published contract stays at 90 methods and the contract version stays at `2`.
* Exclusion filters ride on existing rule-set and automation methods as additional fields, so integrations need no change to keep working.

**Upgrade**

* Existing environments load one seed record — the OMS connector registry row gains its filter parameter name — via `./gradlew loadDarpanUpgradeData`.
* Until that load runs, exclusion filters are inert: the rules board saves exclusions that never reach the OMS query, and the exclusion popover shows nothing.
* After the load, run the one-time internal service `reconciliation.ReconciliationNotificationServices.migrate#AutomationExcludeFilters` once server-side; it seeds exclusion rows for automations that existed before this release. It is safe to run more than once — a side is seeded only when it has no filter rows — and automations created after this release do not need it.
* No schema migration is required; the two new entity groups are created on startup.

**Rollback**

* Schema and seed additions are additive, so rolling the backend to `v1.2.0` is safe and the loaded record does not need reverting — `v1.2.0` code ignores it.
* Keep the app on `v2.3.0` if the backend goes back, since app `v2.4.0` exposes exclusion controls a `v1.2.0` backend cannot persist.
* Roll all component pins back together.

## v1.2.0 — August 1, 2026

Cut together with app `v2.3.0` and matching integration-component tags (`darpan-hotwax v0.5.0`, `shopify-darpan v0.5.0`).

**Product**

* **Named chat spaces.** Google Chat destinations are now a registry of named chat spaces per tenant, replacing the single tenant-wide webhook — automations pick a space, and each person can set their own default.
* **Notifications on every terminal state.** They arrive for every run that reaches one, including failures.
* **Watch and stop a run.** Runs can be watched while they are still going, with steps and files appearing as they land, and stopped mid-run from the app. You can also subscribe to a single run and be told when it finishes.
* **Failed runs stay visible.** Runs that failed early now appear in run history instead of disappearing, and failed runs read as needing attention rather than looking like they are still going.
* **Connections can be tested from their dashboard.** Saved Shopify and OMS connections report each check as it completes, with a plain verdict at the top.
* **Preferred timezone.** One setting drives timestamps, day windows, and reconciliation date ranges across the app.
* **Shopify exchange checking moved to a presence rule.** Every exchange created in Shopify within the return window is expected in OMS, and confirmed absences are reported as differences — returns still in transit are no longer reported as missing.

**Operators**

* Production images pin `DARPAN_REF=v1.2.0` with `darpan-hotwax`/`shopify-darpan` at `v0.5.0` — these move together, since this release's connector registry references services introduced in the v0.5.0 components.
* Deploy the backend before the app.
* The MySQL driver moves to Connector/J 9.7.0, which is what supports a MySQL 8.4 server — do not upgrade the database server ahead of this release.
* Scheduled automations resolve their tenant reliably and surface failures instead of ending quietly, so schedules that had stopped producing runs will start again.

**API**

* This release removes the two tenant-wide notification-setting methods, replaced by the chat-space methods, and adds twenty-six methods. The published contract version moves from `1` to `2`.
* Integrations calling the removed methods must move to the chat-space methods; backend and app pins must move together.

**Upgrade**

* Existing environments load twelve seed records (platform-admin API security, chat-space and run-subscription entity security, a cancelled-run status, and two connector-registry rows) via `./gradlew loadDarpanUpgradeData`.
* After that load, run the one-time internal service `reconciliation.ReconciliationNotificationServices.migrate#TenantNotificationSettings` once server-side — it copies each tenant's existing webhook into a chat space named "Default space" and links that tenant's automations to it. It is safe to run more than once; tenants that already have a chat space are skipped.
* Until it runs, tenants keep their webhook but see an empty chat-space list.

**Rollback**

* Schema and seed additions are additive, and the notification migration copies rather than moves, so the earlier webhook rows survive and `v1.1.0` behavior still works if the backend is rolled back.
* Keep the app on `v2.2.0` if the backend goes back to `v1.1.0` — app `v2.3.0` depends on the chat-space methods, which do not exist there.
* Roll all component pins back together.

## v1.1.0 — July 27, 2026

First minor release on the new baseline, cut together with app `v2.2.0` and matching integration-component tags (`darpan-hotwax v0.4.0`, `shopify-darpan v0.4.0`).

**Product**

* **Composite matching keys.** Rule sets can match records on a combination of key fields, entered as chips in the rule builder and saved-run settings, with run summaries showing every key field. Single-field rule sets behave exactly as before.
* **Live run progress.** Current stage in the runs list, and a step-by-step timeline on the run page that refreshes when the run completes.
* **Verified missing-in-Shopify rows.** Rows that would be reported as missing are verified with direct lookups before they reach the result, so bulk-export lag no longer produces false differences.
* **Long-running saved runs.** They complete reliably, independent of the API request window.
* **Session and clarity fixes.** Signing out ends only the current session, automation schedule times are labeled UTC, app pages load noticeably faster, and the app gets clearer not-found, access-denied, offline, and session-expiry states.
* **Database source type.** Automated runs can pull one side from a database query where the database connector component is deployed.

**Operators**

* Production images pin `DARPAN_REF=v1.1.0` with `darpan-hotwax`/`shopify-darpan` at `v0.4.0` — these move together, since v1.1.0's connector registry references services introduced in the v0.4.0 components.
* Deploy the backend before the app; app `v2.2.0` reads the run-status service introduced in this release.
* OMS extraction is substantially faster and lighter (streaming, compression, field projection).

**Upgrade**

* Existing environments load six seed records (two source-type enums, composite-key entity security, two connector-registry rows) via `./gradlew loadDarpanUpgradeData`; environments with the startup seed load enabled pick them up automatically.

**Rollback**

* Schema additions are additive, so rolling the backend to `v1.0.3` is structurally safe — but do not roll back once composite-key rule sets exist, and keep the app on `v2.1.0` if the backend goes back.
* Roll all component pins back together.

## v1.0.3 — July 3, 2026

First release on Darpan's new independent repository baseline, and the version production images pin to and build from. Backend-only tag; the app is unaffected and versions independently. (Deploy `v1.0.3` — the interim `v1.0.0`/`v1.0.1`/`v1.0.2` tags were folded into it.)

**Product**

* No behavior changes — the baseline is identical to the last pre-move state.

**Operators**

* Production images build directly from this tag with no overrides.
* Integration components (HotWax OMS, Shopify, NetSuite) are pinned to matching tags.
* First-time provisioning of new MySQL-backed environments is reliable end to end.
* In-container data loads (`types=darpan-seed-initial,darpan-seed`) work from a plain exec shell.

**Upgrade**

* No data-load action for existing environments.
* An environment whose initial data load did not complete should run it once on this tag.
* Fresh environments use the standard full data load.

**Rollback**

* No earlier deployable tag exists on the new baseline; interim folded tags are superseded and are not deployment targets.
* Retired pre-move tags must not be used as fallback targets.

## Versioning restarted — July 2026

Darpan moved to a new, independent repository baseline on July 3, 2026. Releases tagged before the move (`v1.0.0` through `v2.1.3`) were retired along with the old repository history, so their tags, release pages, and compare links no longer resolve.

Versioning restarted with the release above; entries appear here from that release onward.

Nothing changed in the product itself: the new baseline is identical to the last pre-move state, and deployed environments are unaffected.