Gravity Forms Versioning is an experimental Gravity Labs feature that can export one or all form versions as JSON and import them into another site. Imports can create a missing form or overwrite versions of an existing form. That is useful for rollback and deployment, but a matching form title does not prove that field IDs, feeds, conditional logic, confirmations, entries, and custom code will still align.
Use this for agencies, regulated forms, staging-to-production promotion, long-lived surveys, payment forms, multilingual sites, disaster recovery, form refactoring, and teams that need an auditable history of form definition changes.
Quick answer
Enable Gravity Forms Versioning only in a controlled environment first. Export all versions and store the untouched JSON with site, form ID, Gravity Forms version, UTC time, and checksum. On a staging clone, import into a new form ID before testing overwrite. Compare field IDs, choices, calculations, conditional logic, confirmations, notifications, feeds, saved entries, merge tags, custom hooks, and front-end rendering. Overwrite an existing form only after a database backup and a verified rollback import.
Test scenarios to run
Run the same controlled fixture across these branches. Write down the expected result before testing so a surprising response is easy to identify.
| Scenario | Fixture | Expected result |
|---|
| Single version | New destination form | Expected definition created |
| All versions | Clean staging site | History retained |
| Overwrite | Existing form and entries | Mappings preserved |
| Rollback | Prior JSON plus backup | Previous behavior restored |
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence | Verification |
|---|
| Export and checksum history | Record source and destination URLs, WordPress and Gravity Forms versions, form ID, version count, export scope, JSON checksum, active theme, add-ons, locale, and database backup ID. | The imported active version renders and validates exactly as expected for every conditional branch. |
| Import as a new form | Inspect the JSON for form identity, field IDs, page breaks, choices, calculations, conditional logic, confirmations, notifications, save-and-continue, and any environment-specific URLs. | Existing entries, exports, merge tags, notifications, feeds, payments, and webhooks retain correct mappings. |
| Run complete workflow tests | Import as a new form on staging, then test display, validation, entries, exports, notifications, feeds, payments, webhooks, merge tags, and custom code that references the old form or field IDs. | Version history and checksums identify what came from which environment and when. |
| Rehearse overwrite and rollback | Run an overwrite rehearsal with preexisting entries and compare version history, active definition, entry readability, add-on feed mapping, and the ability to restore the previous version. | A tested rollback restores the previous behavior without losing entries or exposing the export artifact. |
What to check first
- Record source and destination URLs, WordPress and Gravity Forms versions, form ID, version count, export scope, JSON checksum, active theme, add-ons, locale, and database backup ID.
- Inspect the JSON for form identity, field IDs, page breaks, choices, calculations, conditional logic, confirmations, notifications, save-and-continue, and any environment-specific URLs.
- Import as a new form on staging, then test display, validation, entries, exports, notifications, feeds, payments, webhooks, merge tags, and custom code that references the old form or field IDs.
- Run an overwrite rehearsal with preexisting entries and compare version history, active definition, entry readability, add-on feed mapping, and the ability to restore the previous version.
- Store exports outside the public web root with access controls, retention, provenance, and a rule preventing secrets or personal entry data from entering source control.
Field notes
- Write the pass condition before changing anything and keep one repeatable synthetic fixture for the full test window.
- Record exact versions and UTC timestamps because deployments, caches, retries, scheduled actions, and background jobs can change the evidence.
- Test the public path and the stored server-side result, not only an admin preview, isolated command, or API response.
- Repeat verification after the relevant cache, queue, cron, webhook, and observation window has completed.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
shasum -a 256 gravity-form-7-all-versions.json
wp plugin get gravityforms --field=version
wp option get timezone_string
Why this usually happens
- A form definition is promoted without its add-on feeds or environment-specific settings.
- Custom code uses numeric field IDs that changed during an import.
- An overwrite is mistaken for a reversible edit even though entries and feeds depend on the active definition.
- JSON exports are stored in a public uploads folder or a repository without provenance.
Decision rule
Use overwrite only when the import has passed on a representative clone, field and feed mappings reconcile, historical entries remain readable, and both database and JSON rollback paths have been proved.
Production verification checklist
- The imported active version renders and validates exactly as expected for every conditional branch.
- Existing entries, exports, merge tags, notifications, feeds, payments, and webhooks retain correct mappings.
- Version history and checksums identify what came from which environment and when.
- A tested rollback restores the previous behavior without losing entries or exposing the export artifact.
Safe fix order
Use a sequence that makes each result easy to prove. Stop when new evidence changes the scope or owner of the problem.
- Export and checksum history
- Import as a new form
- Run complete workflow tests
- Rehearse overwrite and rollback
- Store artifacts securely
Mistakes to avoid
- Changing production before recording exact versions, UTC timestamps, a stable fixture, the expected result, and a tested rollback point.
- Treating one successful screen as proof while stored records, logs, queues, caches, emails, APIs, and downstream systems remain unchecked.
- Testing only as an administrator instead of using the role, device, locale, cache state, payment state, and failure branch that customers reach.
- Leaving temporary exclusions, debug output, test accounts, broad permissions, or one-off repair code active after verification.
Questions teams ask during testing
Can I run this directly in production?
Begin with read-only evidence and use staging for package, database, checkout, form, permission, or security changes. If a production canary is necessary, make it identifiable, reversible, monitored, and unable to expose personal data or charge a customer.
How do I avoid a false positive?
Repeat the same fixture with the same versions, role, URL, locale, cache state, and integrations. Compare browser, stored, API, and log evidence instead of relying on one screen.
What should the evidence packet contain?
Keep UTC time, exact versions, synthetic record ID, expected result, actual result, relevant log lines, change made, rollback point, owner, and final verification. Redact secrets and personal data.
When is the test complete?
Close the work when the primary path passes, failure branches are understood, stored and downstream records reconcile, temporary changes are removed, and monitoring covers the next update.
What to tell the client or owner
Give the owner a concise packet with the affected workflow, exact versions, UTC test time, fixture ID, expected result, actual result, key logs, change made, rollback point, final result, unresolved risks, owner, and next review date. Remove credentials and personal data before sharing it.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, security, paid media reporting, or a client production site. HandL WP can trace the issue through WordPress, hosting, cache, tracking, and Search Console, then verify the workflow after the technical fix.
If this is active on a production site, have HandL WP test a form deployment.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Verify duplicate detection in the version history
Before treating version history as a complete audit trail, run the Gravity Forms Versioning no-change checksum audit. It tests which form objects create a snapshot, which changes stay outside the version payload, and whether notification delivery agrees with the stored revision.
Complete the form version integrity review
A safe import is only one boundary. Reconcile stored revisions with failed change emails, test JSON key-order checksum stability, and map the external credential boundary during version restore before relying on history for production rollback.
Helpful references