SystemExecute Procedures

The system-execute mechanism of the Content Manager and the Template Engine is used during export (and in the Content Manager also when files are previewed) to export file or version data which cannot be determined using NPSOBJ-insertvalue instructions. SystemExecute procedures are called as follows:

<npsobj insertvalue="systemExecute" name="procAlias">content</npsobj>

This instruction executes the procedure with the procAlias alias and inserts the return value into the export file instead of the instruction. SystemExecute alias names are registered in the export system configuration entry as the value of the tclSystemExecuteCommands key. The corresponding entry in the configuration file of the Content Manager or the Template Engine has the following format:

<tclSystemExecuteCommands>
  <procAlias>sysExecProc</procAlias>
</tclSystemExecuteCommands>

With the above configuration entry, the name="procAlias" part in the NPSOBJ instruction causes the sysExecProc procedure to be called. SystemExecute procedures need to be stored in the instance-specific script/cm/serverCmds directory and are sourced during the start-up process of the Content Manager and the Template Engine. Please note that the Tcl code of system procedures only has read-access to the CMS data.

The ID of the file or link in whose context the instruction is evaluated is passed as the first argument to a systemExecute procedure. As the second argument it receives the evaluated content of the calling NPSOBJ element. The following example procedure sysExecProc returns (as a result) a formatted text which contains both these values.

proc sysExecProc {objId content} {
  set result "<b>ObjId: $objId</b>\n"
  append result "<pre>$content</pre>\n"
  return $result;
}

File dependencies on the live server

SystemExecute procedures have read access not only to the file being exported but also to all other files. If you use the Template Engine and a referenced file was updated, then the file containing the systemExecute call has possibly also become out-of-date and needs to be exported again. This file depends on the referenced file.

If, for example, during the export of file A a systemExecute procedure is called which reads one or more of file B’s version fields and has them incorporated into A’s export result, then modifying B’s version fields should invalidate not only B’s but also A’s web page. This would cause A to be exported again when a web site visitor requests A’s page. By defining a dependency A’s web page can be kept up-to-date even if no changes are made to the file A itself.

Dependencies can be made known to the Template Engine by using the global additionalDependencies variable in the systemExecute procedure. In additionalDependencies you can store a list of value pairs. Each pair consists of a dependency type and a file ID. The following example expresses that the file which is currently beeing exported depends on the contents of the file with the path /path/to/file:

global additionalDependencies
set additionalDependencies [list content [obj withPath /path/to/file]]

The dependency type determines which kind of changes to the specified file cause the file dependent on it to be deleted from the cache and exported again. In the following overview the available dependency types and their modification conditions are listed:

Dependency type Modification conditions
children The number of subfiles in a folder, one of its subfiles itself or the sorting in the folder has changed.
content The draft version of a file has changed.
object A file field has changed.
reference A field which is relevant for links (such as title or destinationUrl) has changed.
usesAll Any file or its draft version has changed. With this type the file ID is irrelevant and will be ignored. Nevertheless it must be specified.