Script Node

There are three different ScriptNode classes.

  • ScriptNode provides read-only access to the derived data of any node.
  • Script Node Writable Derived provides read-write access to the derived data. This is only available for the context node, i.e. a script can not update the derived data of any node other than the one against which it should be running.
  • Script Node Writable Original provides read-write access to the original data of a node, or of a new node. This is available for any node that the user is authorised to update.

The Script Node classes also provide a complete set of error fields. See Scripting errors for more details.

int = getNodeVersionIdentifier() Get the node version identifier.
int = getNodeIdentifier() Get the node identifier.
String = getNodeVersionReference() Get the node version reference.
String = getNodeReference() Get the node reference.
String = getLocalReference() Get the local reference.
String = getPackageReference() Get the node reference of the containing package, or "" if there is none.
int = getNodeVersionNumber() Get the node version number.
int = getNodeFrozenVersionNumber() Get the frozen version number.
String = getNodeName() Get the node name.
String = getNodeDescription() Get the node description.
ScriptNode = getNodeType() Get the node type, as a node.
String = toString() Returns the node version reference.
ScriptNode = getPackage() Get the node that acts as a package for this node. May return null if the user can not access the package.
ScriptNode[] = listMemberTypes() List all the member types available for this node. NB this does not necessarily list all the available derived member types, but should list all the member types defined through the node's type.
ScriptMember = getMember(memberType[,sequence]) Get a member of a member type. Sequence defaults to 1. Return null if not found or not authorised.

Member type can be specified by nodeVersionIdentifier, nodeVersionReference or by a script node.

String = getValue(memberType) Shorthand for getMember(memberType).getValue()
ScriptNode = getTarget(memberType) Shorthand for getMember(memberType).getTarget()
double = getScale(memberType) Shorthand for getMember(memberType).getScale()
ScriptMember = getMemberByValue(memberType,value[,scale]) Get (the first) member of a member type with the given value. Return null if not found or not authorised.

If a scale is passed, match on the scale also.

Number = getScaleByValue(memberType,value) Shorthand for getMemberByValue(memberType,value).getScale();
ScriptNode = getTargetByValue(memberType, value) Shorthand for getMemberByValue(memberType,value).getTarget();
ScriptMember = getMemberByTarget(memberType, target[,scale]) Get (the first) member of a member type with the given target. Return null if not found or not authorised.

If a scale is passed, match on the scale also.

String = getValueByTarget(memberType,target) Shorthand for getMemberByTarget(memberType,target).getValue();
Number = getScaleByTarget(memberType,target) Shorthand for getMemberByTarget(memberType,target).getScale();
ScriptMember[] = listMembers(memberType) Get all the members of a member type.

Member type can be specified by nodeVersionIdentifier, nodeVersionReference or by a script node.

ScriptNode[] = listTargets(memberType) Return list of targets for members of a member type. Null targets are excluded.
boolean = targetExists(memberType, target [,anyVersion])

Indicates whether the member type has the given target.

If anyVersion is passed and set to true, indicates whether the member type has any version of the given target.

ScriptNode = getBinding(reference[,searchParents]) Search for the target of member type system.BINDINGS, with the given reference as the key.

If searchParents is true (the default), then if the binding is not found, search the parent package, and its parent, and so on, until it is found. searchParents defaults to false. If searchParents is false, then parents are not searched.

Return null if the binding can not be found. (Unlike application.getBinding(), no error is set.)

The user does not need to have permission to read the node or parent packages, but their permission on the returned node is respected.

The latest version of the parent package is used. It may be stale when it is read. However, the returned bound node will be fresh if the calling node is fresh.

getBinding is fundamentally a read operation that looks at derived data. Its action on a ScriptNodeWritableOriginal object is undefined.

ScriptNode[] = listPackageContent() Return a list of nodes within a package.
int = getPackageContentCount() Return the number of nodes within a package.
ScriptNode[] = listInboundLinks(memberType [,folder])

Return a list of nodes that link to this node with a given member type, and which the current user can read, in name sequence. This is based on both derived and original data.

Coming in 4.1.5. Optionally, return only nodes contained with the given folder. This does not return the folder itself, if it has a link to the node.

The list of linking nodes can change continuously, and this node will not be forced to update when they are. It is not therefore safe to cache the results of this method in a derived member.

The list of linking nodes may not be complete (for example, because the current user can not read them, or because the derived data is not up-to-date). This method should be used for the navigational convenience of the user, not for definitive processing.

Be cautious of listing inbound links during derivation processing, as it can trigger premature derivation of dependents based on an incomplete state of the context. Using a stale version of the context, something like application.getNode(context,0).listInboundLinks(field), may be necessary to avoid premature derivation.

object = getExtension(request) Retrieve extension data associated with the node.

request is optional, and can be a string, service message writer or xpath evaluator. It will always be passed to the extension as an xpath evaluator.

The extension returns one of:

  • null
  • a string
  • an XPathEvaluator object

If the extension encounters an error, it will return null but set the error on the Node.

object = getMemberTypeExtension(memberType,request) Retrieve extension data associated with a member type.

Member type can be specified by id, string or as a script node.

request is optional, and can be a string, service message writer or xpath evaluator. It will always be passed to the extension as an xpath evaluator.

The extension returns one of:

  • null
  • a string
  • an XPathEvaluator object

If the extension encounters an error, it will return null but set the error on the Node.

boolean = mayRead([user]) Return whether the user may read the node. The user may always read the node version identifier, reference and name, even if they can not otherwise read the node.

The user defaults to the current user. If specified, the user can be passed by identifier or logon reference.

boolean = mayReadMember([user,]memberType) Return whether the user may read members of the given member type.

Member type can be specified by nodeVersionIdentifier, nodeVersionReference or by a script node.

The user defaults to the current user. If specified, the user can be passed by identifier or logon reference.

boolean mayUpdateMember([user,]memberType) Return whether the user may update members of the given member type.

Updating is only possible using ScriptNodeWritableOriginal (nothing can be updated on ScriptNode, and any derived data can be updated on ScriptNodeWritableDerived).

The user defaults to the current user. If specified, the user can be passed by identifier or logon reference.

boolean = mayLink([user]) Return whether the user may link to a node.

The user defaults to the current user. If specified, the user can be passed by identifier or logon reference.

boolean = mayUseType([user]) Return whether the user may use a node as a type.

The user defaults to the current user. If specified, the user can be passed by identifier or logon reference.

boolean = mayExecute([user]) Return whether the user may execute scripts on the node.

The user defaults to the current user. If specified, the user can be passed by identifier or logon reference.

boolean = mayUsePackage([user]) Return whether the user may use the node as a package.

The user defaults to the current user. If specified, the user can be passed by identifier or logon reference.

boolean = mayAdminister([user]) Return whether the user may administer a node.

The user defaults to the current user. If specified, the user can be passed by identifier or logon reference.

string = getReadToken()
string = getReadMemberToken(memberType)
string = getUpdateMemberToken(memberType)
string = getLinkToken()
string = getUseTypeToken()
string = getExecuteToken()
string = getUsePackageToken()
string = getAdministerToken()

Return a permission token for a permission on this node.

The parameters are similar to those for the mayXXX() methods.

ScriptMember = newMember() Create an empty script member.
boolean = deleteNode() Delete the node. Return true if successful, or false if the delete can not be carried out. If the delete can not be carried out, errors will be set in the script node object.

The node must be in draft for you to delete it. If you delete the one and only version of a node (i.e. the node has never been frozen), then nodes and members that depend on it as a node type, member type, target or package are also deleted, even if you do not otherwise have permission to modify those things. If you delete a later draft, then nodes and members that depend on it as a node type, member type or target are downgraded, i.e. pointed to the previous version, and nodes that are contained by the node are not modified.

boolean = changeNodeType(nodeType) Change the type of the node. Return true if successful, or false if the type change can not be carried out. If the change can not be carried out, errors will be set in the script node object.

This performs the change type immediately, and re-retrieves the underlying data. If called on ScriptNodeWritableOriginal, it will ignore and reset any changes made since the last apply().

boolean = changeNodeReference(newReference) Change the node reference. This does not occur within set processing (unlike setNodeReference on ScriptNodeWritableOriginal). It can be applied to any node over which the user has admin authority. Return true if successful, false and sets errors if not.

boolean = grant(permissionTypes, userGroup[,deleteOtherPermissions])

Grant permissions of the given types on the node to the specified user group. Permission types is passed as a id, or a whitespace-delimited list of references. userGroup can be passed by id or reference. Return true if successful, return false and set the error fields if not successful.

If deleteOtherPermissions is true, then any permissions other than those specified are deleted. Using permissionTypes of "" with the delete other permissions deletes all the user group's permissions for the node. Permissions are not deleted if the user is not authorised to delete them, and the user can not delete their own admin permissions on the node.

To grant to an individual user, pass their userLogonRefrence field in as the user group (every user has a individual user group with the same reference).

The script node object holds a cache of permissions. You may need to refresh the node in order to pick up permission changes.

See Permissions for a list of permissions.

boolean = makeAdministrator([userGroup])

Make the given user group an administrator of this node, if they are not already an administrator. The user group defaults to the individual user group of the user who retrieved the node.

Unlike grant(), this searches for an administrator permission on this node or any parent package. For example, user1 creates node A, permits user2 to use A as a package, user 2 creates nodes A.B and A.B.C. User1 can not grant permissions on A.B to allow others to see A.B.C. However, user1 can make themselves administrator on A.B and thus perform the grant.

refreshManifestPermissions() For a node used as a Manifests, refresh all permissions defined on the manifest.
refresh([setOutOfDate]) Re-retrieve the node from the database. This resets error fields, recalculates permissions, and discards all changes to ScriptNodeWritableOriginal objects made since the last apply().

If setOutOfDate is true, then the node is set out of date before it is refreshed. This forces the node to be re-derived, as well as setting all dependents of the node out of date.

touch() Update the last amended timestamp and user fields to the current time and the current user. User must have permission to update the node. Return true if successful. Return false and set error fields if not successful.

Re-read the node to retrieve the updated timestamp and user fields.

Touch does not trigger a refresh.

int = getUserIdentifierCreated() Get the internal id of the user who created the node, or 0 if not set.
int = getUserIdentifierAmended() Get the internal id of the user who last amended the node, or 0 if not set.
int = getUserIdentifierOwner() Get the internal id of the user who owns the node, or 0 if not set.
String = getTimestampCreated() Get the timestamp when the node was created, in yyyy-mm-ddThh:mm:ss.sss format, or null if not set.
String = getTimestampAmended() Get the timestamp when the node was last amended, in yyyy-mm-ddThh:mm:ss.sss format, or null if not set.
String = getTimestampUpToDate() Get the timestamp when the node was last made up to date, in yyyy-mm-ddThh:mm:ss.sss format.
boolean = isUpToDate() Return true if node is up to date, false if derivation is pending.