Node Migration Reference

Node migrations can be used to deal with renamed node types and property names, set missing default values for properties, adjust content dimensions and more.

Node migrations work by applying transformations on nodes. The nodes that will be transformed are selected through filters in migration files.

The Content Repository comes with a number of common transformations:

AddDimensions
AddNewProperty
ChangeNodeType
ChangePropertyValue
RemoveNode
RemoveProperty
RenameDimension
RenameNode
RenameProperty
SetDimensions
StripTagsOnProperty

They all implement the Neos\ContentRepository\Migration\Transformations\TransformationInterface. Custom transformations can be developed against that interface as well, just use the fully qualified class name for those when specifying which transformation to use.

Migration files

To use node migrations to adjust a setup to changed configuration, a YAML file is created that configures the migration by setting up filters to select what nodes are being worked on by transformations. The Content Repository comes with a number of filters:

DimensionValues
IsRemoved
NodeName
NodeType
PropertyNotEmpty
PropertyValue
Workspace

They all implement the Neos\ContentRepository\Migration\Filters\FilterInterface. Custom filters can be developed against that interface as well, just use the fully qualified class name for those when specifying which filter to use.

Here is an example of a migration, Version20140708120530.yaml, that operates on nodes in the “live” workspace that are marked as removed and applies the RemoveNode transformation on them:

up:
  comments: 'Delete removed nodes that were published to "live" workspace'
  warnings: 'There is no way of reverting this migration since the nodes will be deleted in the database.'
  migration:
    -
      filters:
        -
          type: 'IsRemoved'
          settings: []
        -
          type: 'Workspace'
          settings:
            workspaceName: 'live'
      transformations:
        -
          type: 'RemoveNode'
          settings: []

down:
  comments: 'No down migration available'

Like all migrations the file should be placed in a package inside the Migrations/ContentRepository folder where it will be picked up by the CLI tools provided with the content repository:

./flow node:migrationstatus
./flow node:migrate

Use ./flow help <command> to get detailed instructions. The migrationstatus command also prints a short description for each migration.

Note

Node migrations in Migrations/TYPO3CR directories are also supported for historic reasons

Transformations Reference

AddDimensions

Add dimensions on a node. This adds to the existing dimensions, if you need to overwrite existing dimensions, use SetDimensions.

Options Reference:

dimensionValues (array): An array of dimension names and values to set.
addDefaultDimensionValues (boolean): Whether to add the default dimension values for all dimensions that were not given.

AddNewProperty

Add a new property with the given value.

Options Reference:

newPropertyName (string): The name of the new property to be added.
value (mixed): Property value to be set.

ChangeNodeType

Change the node type.

Options Reference:

newType (string): The new Node Type to use as a string.

ChangePropertyValue

Change the value of a given property.

This can apply two transformations:

If newValue is set, the value will be set to this, with any occurrences of the currentValuePlaceholder replaced with the current value of the property.
If search and replace are given, that replacement will be done on the value (after applying the newValue, if set).

This would simply override the existing value:

transformations:
  -
    type: 'ChangePropertyValue'
    settings:
      property: 'title'
      newValue: 'a new value'

This would prefix the existing value:

transformations:
  -
    type: 'ChangePropertyValue'
    settings:
      property: 'title'
      newValue: 'this is a prefix to {current}'

This would prefix existing value and then apply search/replace on the result:

transformations:
  -
    type: 'ChangePropertyValue'
    settings:
      property: 'title'
      newValue: 'this is a prefix to {current}'
      search: 'something'
      replace: 'something else'

And in case your value contains the magic string “{current}” and you need to leav it intact, this would prefix the existing value but use a different placeholder:

transformations:
  -
    type: 'ChangePropertyValue'
    settings:
      property: 'title'
      newValue: 'this is a prefix to {__my_unique_placeholder}'
      currentValuePlaceholder: '__my_unique_placeholder'

Options Reference:

property (string)

The name of the property to change.

newValue (string)

New property value to be set.

The value of the option currentValuePlaceholder (defaults to “{current}”) will be used to include the current property value into the new value.

search (string)

Search string to replace in current property value.

replace (string)

Replacement for the search string.

currentValuePlaceholder (string)

The value of this option (defaults to {current}) will be used to include the current property value into the new value.

RemoveNode

Removes the node.

RemoveProperty

Remove the property.

Options Reference:

property (string): The name of the property to be removed.

RenameDimension

Rename a dimension.

Options Reference:

newDimensionName (string): The new name for the dimension.
oldDimensionName (string): The old name of the dimension to rename.

RenameNode

Rename a node.

Options Reference:

newName (string): The new name for the node.

RenameProperty

Rename a given property.

Options Reference:

from (string): The name of the property to change.
to (string): The new name for the property to change.

SetDimensions

Set dimensions on a node. This always overwrites existing dimensions, if you need to add to existing dimensions, use AddDimensions.

Options Reference:

dimensionValues (array): An array of dimension names and values to set.
addDefaultDimensionValues (boolean): Whether to add the default dimension values for all dimensions that were not given.

StripTagsOnProperty

Strip all tags on a given property.

Options Reference:

property (string): The name of the property to work on.

Filters Reference

DimensionValues

Filter nodes by their dimensions.

Options Reference:

dimensionValues (array): The array of dimension values to filter for.
filterForDefaultDimensionValues (boolean): Overrides the given dimensionValues with dimension defaults.

IsRemoved

Selects nodes marked as removed.

NodeName

Selects nodes with the given name.

Options Reference:

nodeName (string): The value to compare the node name against, strict equality is checked.

NodeType

Selects nodes by node type.

Options Reference:

nodeType (string): The node type name to match on.
withSubTypes (boolean): Whether the filter should match also on all subtypes of the configured node type. Note: This can only be used with node types still available in the system!
exclude (boolean): Whether the filter should exclude the given NodeType instead of including only this node type.

PropertyNotEmpty

Filter nodes having the given property and its value not empty.

Options Reference:

propertyName (string): The property name to be checked for non-empty value.

PropertyValue

Filter nodes having the given property with the corresponding value.

Options Reference:

propertyName (string): The property name to filter for with the given property value.
propertyValue (string): The property value to filter for.

Workspace

Filter nodes by workspace name.

Options Reference:

workspaceName (string): The workspace name to match on.