Versions

FrogBot’s powerful Versions functionality allows you to keep a running history of changes over time and extensible to fit any content publishing workflow.

When enabled, FrogBot will automatically scaffold a new Collection in your database to store versions of your document(s) over time, and the Admin UI will be extended with additional views that allow you to browse document versions, view diffs in order to see exactly what has changed in your documents (and when they changed), and restore documents back to prior versions easily. With Versions, you can:

Maintain an audit log / history of every change ever made to a document, including monitoring for what user made which change
Restore documents to prior states in case you need to roll back changes
Build a true Draft Preview mode for your data
Manage who can see Drafts, and who can only see Published documents via Access Control
Enable Autosave on collections to never lose your work again
Build a powerful publishing schedule mechanism to create documents and have them become publicly readable automatically at a future date

Versions are extremely performant. They don’t change the shape of your data at all. All versions are stored in a separate collection. Versions are enabled by default for every collection — set versions: false to opt out.

Options

Versions support a few different levels of functionality that each come with their own impacts to document workflow.

Versions enabled, drafts disabled

If you enable versions but keep draft mode disabled, FrogBot will simply create a new version of a document each time you update a document. This is great for use cases where you need to retain a history of all document updates over time, but always want to treat the newest document version as the version that is “published”. For example, a use case for “versions enabled, drafts disabled” could be on a collection of users, where you might want to keep a version history (or audit log) of all changes ever made to users - but any changes to users should always be treated as “published” and you have no need to maintain a “draft” version of a user.

Versions and drafts enabled

If you have versions and drafts enabled, you are able to control which documents are published, and which are considered draft. That lets you write Access Control to control who can see published documents, and who can see draft documents. It also lets you save versions (drafts) that are newer than your most recently published document, which is helpful if you want to draft changes and maybe even preview them before you publish the changes. Read more about Drafts here.

Versions, drafts, and autosave enabled

When you have versions, drafts, and autosave enabled, the Admin UI will automatically save changes that you make to a new draft version as you edit a document, which makes sure that you never lose your changes ever again. Autosave will not affect your published post at all—instead, it’ll just save your changes and let you publish them whenever you or your editors are ready to do so. Read more about Autosave here.

Collection config

Versions are enabled by default for every collection (maxPerDoc: 100, drafts disabled). You only need to set the versions key explicitly when you want to opt out or customise the behaviour:

// Opt out entirely
export const Users: CollectionConfig = {
  slug: 'users',
  auth: true,
  fields: [],
  versions: false,
}

// Customise — enable drafts and cap history to 50 versions per document
export const Posts: CollectionConfig = {
  slug: 'posts',
  fields: [],
  versions: {
    drafts: { autosave: true },
    maxPerDoc: 50,
  },
}

The available options are:

Option	Type	Default	Description
`maxPerDoc`	`number`	`100`	How many versions to keep for each document. Older versions are deleted. Use `0` to keep every version.
`drafts`	`boolean \| DraftsConfig`	`false`	Enable Drafts mode for this collection. To enable, set to `true` or pass an object with draft options.

Database impact

By enabling versions, a new database collection will be made to store versions for your collection. The collection will be named based on the collection’s slug and will follow this pattern:

_slug_versions

Each document in this new versions collection will store a set of meta properties about the version as well as a full copy of the document. For example, a version’s data might look like this for a Collection document:

{
  "_id": "61cf752c19cdf1b1af7b61f1",
  "parent": "61ce1354091d5b3ffc20ea6e",
  "autosave": false,
  "version": {
    // your document's data goes here
    // all fields are set to not required and this property can be partially complete
  },
  "createdAt": "2021-12-31T21:25:00.992+00:00",
  "updatedAt": "2021-12-31T21:25:00.992+00:00"
}

Version operations

Versions expose operations that let you query versions, find a single version by ID, and publish or restore a version by ID. They are used primarily by the admin UI, but are also available to custom logic through REST, GraphQL, and Local APIs. Collection REST endpoints:

Method	Path	Description
`GET`	`/api/{collectionSlug}/versions`	Find and query paginated versions
`GET`	`/api/{collectionSlug}/versions/:id`	Find a specific version by ID
`POST`	`/api/{collectionSlug}/versions/:id`	Restore a version by ID

Collection GraphQL queries:

Query Name	Operation
`version{collection.label.singular}`	`findVersionByID`
`versions{collection.label.plural}`	`findVersions`

And mutation:

Query Name	Operation
`restoreVersion{collection.label.singular}`	`restoreVersion`

Collection Local API methods:

Find

// Result will be a paginated set of Versions.
// See /queries/pagination for more.
const result = await frogbot.findVersions({
  collection: 'posts', // required
  depth: 2,
  page: 1,
  limit: 10,
  where: {}, // pass a `where` query here
  sort: '-createdAt',
  locale: 'en',
  fallbackLocale: false,
  user: dummyUser,
  overrideAccess: false,
  showHiddenFields: true,
})

Find by ID

// Result will be a Post document.
const result = await frogbot.findVersionByID({
  collection: 'posts', // required
  id: '507f1f77bcf86cd799439013', // required
  depth: 2,
  locale: 'en',
  fallbackLocale: false,
  user: dummyUser,
  overrideAccess: false,
  showHiddenFields: true,
})

Restore

// Result will be the restored collection document.
const result = await frogbot.restoreVersion({
  collection: 'posts', // required
  id: '507f1f77bcf86cd799439013', // required
  depth: 2,
  user: dummyUser,
  overrideAccess: false,
  showHiddenFields: true,
})

Access Control

Versions expose an Access Control function on Collections that lets you control who can see document versions.

Function	Allows/Denies Access
`readVersions`	Used to control who can read versions, and who can’t. Will automatically restrict the Admin UI version viewing access.

For full details on how to use Access Control with Versions, see the Access Control documentation.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Options

Versions enabled, drafts disabled

Versions and drafts enabled

Versions, drafts, and autosave enabled

Collection config

Database impact

Version operations

Find

Find by ID

Restore

Access Control

​Options

​Versions enabled, drafts disabled

​Versions and drafts enabled

​Versions, drafts, and autosave enabled

​Collection config

​Database impact

​Version operations

​Find

​Find by ID

​Restore

​Access Control

Options

Versions enabled, drafts disabled

Versions and drafts enabled

Versions, drafts, and autosave enabled

Collection config

Database impact

Version operations

Find

Find by ID

Restore

Access Control