The Update Node Versions service creates new versions of nodes, changes node types and changes node member types and targets to update a node structure to later node versions.
The typical case, known as a "relink", is that the service is passed a package (known as the context). The latest version of the package node and all nodes within it are examined. If the type or any targets are within the package, but are not the latest version, then these are updated to be the latest version, if necessary creating a new version of the node with the new type version and/or to hold the new version of the targets. This is repeated until there is no more relinking to be done.
- nodeReference – the context node, to be updated
- impact - list the updates that would be made
- force - perform the updates
- true – update the context node and its package content
- false – only update the context node
- true – if the latest node version is not in draft, create a draft versions even if the node's type and targets have not changed
- false – only create new versions of nodes where the type or targets have changed
- node – only update to new versions of the content node, or of the context package if updateContentIndicator is true
- current – update to current version of any node in the source package
- latest – update to latest version of any node in the source package. The latest version is the current version, or the draft version if the user can see the draft.
- manifest – update to the versions in the manifest identified by sourceReference.
- sourceReference - if sourceScope is current or latest, the package from which to read new versions. Default or zero length string means "all packages".
If sourceScope is manifest, then the source identifies a node version, and the members of type Manifest Items (system.MANIFEST_ITEMS) will be used as the source for new versions.
- Relink. Performs an update, but only taking new versions internally to the context package. Required options:
- updateContentIndicator = true
- Update all. Perform an update, and update to current (i.e. latest frozen) version of all nodes. Required options:
- updateContentIndicator = true
- sourceScope = current
The service requires that the user has admin authority on the context node, and all nodes within it if updateContentIndicator is true.
The service requires that the user has link authority on all targets that need to be updated.
The service requires that the user has use type authority on all types that need to be updated.
When run with an action of impact, if there are any authorisation errors the service will return error number 108 (warning).
When run with an action of update, if there are any authorisation errors, the service will return error number 108 (warning), and will bypass any updates that the user can not perform. It is possible for the impact action to return no warnings, and for errors to occur during the update.
The service only returns "not authorised" if the user is not authorised to read the context node.
Running the service
The service may run for a long time on large packages. The service commits after successfully updating each node to prevent locking problems.
<password>password</password> <nodeIdentifier/> <nodeReference/> <action>impact|force</action> <updateContentIndicator>false|true</updateContentIndicator> <alwaysCreateNewVersionIndicator>false|true</alwaysCreateNewVersionIndicator> <sourceScope>node|current|latest|manifest</sourceScope> <sourceReference/>
The context node can be specified by id or reference. If both are given, id takes precedence.
The source node or node version is passed in sourceReference. Where a specific version of a manifest is required, pass it as a full node version reference in sourceReference.
<errorNumber>0</errorNumber> <nodeVersionIdentifier/> <nodeVersionReference/> <nodeName/> <nodeIdentifier/> <nodeReference/> <nodeVersionNumber/> <UpdateList> <Update> <nodeReference/> <nodeVersionNumber/> <nodeName/> <updateType>version|change|warning|error</updateType> <errorMessage/> <typeUpdateType>none|change</typeUpdateType> <nodeReferenceType/> <nodeVersionNumberType/> <nodeNameType/> <MemberUpdateList> <MemberUpdate> <nodeReferenceMemberType/> <nodeVersionNumberMemberType/> <nodeNameMemberType/> <memberUpdateType>change|remove</memberUpdateType> <nodeReferenceTarget/> <nodeVersionNumberTarget/> <nodeNameTarget/> </MemberUpdate> </MemberUpdateList> </Update> </UpdateList>
The identifying fields identify the latest version of the node passed to the service.
The update list shows what will be updated or what has been updated.
Each updated node is returned in a section. The node is identified by its reference, new version number and name. For creates, the impact shows the old version number, and the force shows the new version number. The update type indicates what is required:
- version - a new version is created
- change - the existing version is modified
- warning - the existing version can not be modified and no update was attempted (i.e. the problem was detected during impact processing)
- error - an update was attempted, but did not work. An updateType of error only occurs with an action of force. This is useful to highlight errors that were not detected during impact processing, and to which the user's attention should be drawn.
If warning or error is returned, a suitable explanation will be in errorMessage, but other fields will not be returned.
If the type is updated, typeUpdateType will be set to modify and the new type version number and name are given. (They are not passed if the type is not to be updated.)
The updates for each member are listed. The member update type indicates whether the member will be modified (i.e. the target will be updated to a later version), or removed. If member update type is modify then the new version of the target is shown. If member update is remove, this means that a new version is being created and the type is being updated but the new type does not have a compatible member type and that data for this member type will not be present in the new version. Member type version numbers refer to the version number before the update takes place. If the update involves creating new versions of member types then these updated version numbers will not necessarily be shown in the list of member updates. Nodes which only have member type version changes may not be listed in the update list.
The impact processing reports authorisation and other errors:
- If the user is not authorised to administer nodes that require updates or a new version.
- If the user is not authorised to use new versions of types.
- If the user is not authorised to link to new versions of targets.
- If the update would involve a type change, and the node is already in draft, and the new version of the type would invalidate existing data because some of the populated member types in the old version of the type are not present (as the same or other versions) in the new version of the type. (This error is not raised if the node is frozen, because creating a new draft version without the members does not actually lose any user data, though the remove impact is listed.)
To overcome this "Can not update to type" error, the user has three choices:
- Freeze the draft node version.
- Edit the draft node version to remove the data that can not be migrated.
- Change the type of the draft node version manually, which does allow existing data to be lost.
However, there are errors which the impact processing can not detect. For example:
- If existing data fails validation rules for new versions of node types.
- If changes to node types in draft (either changes to the type of the node types or changes to their targets) would cause either of the following:
- Loss of original data to any node caused by total removal of a member type.
- Loss of original data to any out-of-context node caused by an update of member type version. This does not apply to in-context nodes, because their member type versions can be updated.
When using draft versions, it is always possible to get unintended impacts of version updates, even with this error detection. The principle is simple - always use frozen node types for important data.
Treatment of comments
Node member comments are retained when node versions are updated, but are not carried over when new versions are created.
101 - Not authorised
105 - user error, typically because node reference or node reference source can not be found
108 - warning, partial update would or has taken place