05_versioning.md

title	summary
Versioned content	A guide on how DataObjects with the Versioned extension behave in GraphQL schemas

Working with DataObjects

[CHILDREN asList]

[info] You are viewing docs for silverstripe/graphql 4.x. If you are using 3.x, documentation can be found in the github repository [/info]

Versioned content

For the most part, if your DataObject has the Versioned extension applied, there is nothing you need to do explicitly - but be aware that it will affect the operations and fields of your type. You can also disable versioning for your schema if you don't need it.

See model versioning for general information about versioning your DataObjects.

Versioned plugins

There are several plugins provided by the silverstripe/versioned module that affect how versioned DataObjects appear in the schema. These include:

• The versioning plugin, applied to the DataObject type
• The readVersion plugin, applied to the queries for the DataObject
• The unpublishOnDelete plugin, applied to the delete mutation

Let's walk through each one.

The versioning plugin

Defined in the VersionedDataObject class, this plugin adds several fields to the DataObject type, including:

The version field

The version field on your DataObject will include the following fields:

• author: Member (Object -- the author of the version)
• publisher: Member (Object -- the publisher of the version)
• published: Boolean (True if the version is published)
• liveVersion: Boolean (True if the version is the one that is currently live)
• latestDraftVersion: Boolean (True if the version is the latest draft version)

[info] Note that author and publisher are in relation to the given version of the object - these are not necessarily the same as the author and publisher of the original record (i.e. the author may not be the person who created the object, they're the person who saved a specific version of it). [/info]

Let's look at it in context:

query readPages {
  nodes {
    title
    version {
      author {
        firstname
      }
      published
    }
  }
}

The versions field

The versions field on your DataObject will return a list of the version objects described above. The list is sortable by version number, using the sort parameter.

query readPages {
  nodes {
    title
    versions(sort: { version: DESC }) {
      author {
        firstname
      }
      published
    }
  }
}

The readVersion plugin

This plugin updates the read operation to include a versioning argument that contains the following fields:

• mode: VersionedQueryMode (An enum of [ARCHIVE, LATEST, DRAFT, LIVE, STATUS, VERSION])
• archiveDate: String (The archive date to read from)
• status: VersionedStatus (An enum of [PUBLISHED, DRAFT, ARCHIVED, MODIFIED])
• version: Int (The exact version to read)

The query will automatically apply the settings from the versioning input type to the query and affect the resulting DataList.

The unpublishOnDelete plugin

This is mostly for internal use. It's an escape hatch for tidying up after a delete.

Versioned operations

DataObjects with the Versioned extension applied will also receive four extra operations by default. They include:

• publish
• unpublish
• copyToStage
• rollback

All of these identifiers can be used in the operations config for your versioned DataObject. They will all be included if you use operations: '*'.

app/_graphql/models.yml

  MyProject\Models\MyObject:
    fields: '*'
    operations:
      publish: true
      unpublish: true
      rollback: true
      copyToStage: true

Using the operations

Let's look at a few examples:

Publishing

mutation publishSiteTree(id: 123) {
  id
  title
}

Unpublishing

mutation unpublishSiteTree(id: 123) {
  id
  title
}

Rolling back

mutation rollbackSiteTree(id: 123, toVersion: 5) {
  id
  title
}

Copying to stage

mutation copySiteTreeToStage(id: 123, fromStage: DRAFT, toStage: LIVE) {
  id
  title
}

Disabling versioning on your schema {#disable}

Versioning is great for Content APIs (e.g. previews), but often not necessary for public APIs focusing on published data. You can disable versioning for your schema in the modelConfig section:

app/_graphql/config.yml

modelConfig:
  DataObject:
    plugins:
      versioning: false
    operations:
      read:
        plugins:
          readVersion: false
      readOne:
        plugins:
          readVersion: false
      delete:
        plugins:
          unpublishOnDelete: false

Further reading

[CHILDREN]