From Tcl to XML

This section describes how applications can access data managed by the Content Management Server via its XML interface. In the examples below, payloads and requests are only given as fragments. How complete payloads and requests can be built is described in section CRUL Payloads.

The functions available via the XML Interface are mostly the same as those for the Tcl Interface, meaning that you can use either to create files or query the values of version fields, for example. This is possible because the Tcl Interface and the XML parser built into the Content Management Server call the same underlying application functions in most cases.

Classes and Instances

To be able to convert Tcl commands to XML fragments you must know that each group of commands refers to a class and that classes have instances. Therefore, the attribute group of commands refers to the class of fields, the obj group of commands refers to files, and so on. Instances of these classes are the individual fields or files. Using the commands of a group of commands, you can access a class entirely, e.g. all files, or individual instances. For example, the list of fields is obtained using the following command:

attribute list

Commands such as list, which you use to access an entire class, are called class methods. create is also a class method of most classes. An instance is added to a class using create.

attribute create name fruit type multienum

You can see by this example that class methods can have arguments. If you, e.g. add an instance to a class, you must be able to clearly reference the instance. For fields, this is done with the name. The name is a property (also "Parameter") of a field, as is, e.g. the type. In the above example, the method create is given the name of a parameter and its value as arguments, in pairs (name = obst, and type = multienum). Arguments are specified in this way for many Tcl commands.

Instances

For Tcl commands that refer to individual instances (such as a file or a user), the value of the parameter which clearly identifies the instance must be given. The following Tcl command obtains the password of the user whose login is smith:

user withLogin smith get password

In this command, user is the class, and the instance of this class to which the command refers, is clearly referenced by smith. A command with which an instance of a class is addressed always has a subcommand. The subcommand specifies the action to be taken with respect to the instance. In the above example, the subcommand get is used. The value of an instance variable, here password, can be obtained using get. In the following example, the parent folder of a file is set:

obj withId 4912 set parent aPublicationObjectId

Here, the file with the ID 4912 is the instance of the class obj to which the subcommand set is applied. Subcommands are called instance methods.

Methods in XML

Class methods and instance methods are encoded in CRUL requests as elements. The tag of the corresponding element is built from the class name and the method name, connected by a hyphen:

<attribute-create> ... </attribute-create>

Using this element, a field is created and the necessary name and values of the instance to be created are specified as subelements:

<cm-request ...>
  <attribute-create>
    <name>Address</name>
    <type>string</type>
  </attribute-create></cm-request>

As in the corresponding Tcl command (attribute create name Address type string), this request creates a response which contains the name of the created field:

<cm-response ...>
  <cm-code numeric="0" phrase="ok">
    <attribute>
      <name>Adresse</name>
    </attribute>
  </cm-code></cm-response>

In the Tcl Interface, the name of the field created is returned without additions using attribute create. In the response documents of the XML Interface, on the other hand, the return value is contained in the class name element (here attribute) as a parameter element (here name). Basically, the XML interface and the Tcl interface both supply the value of the primary key of the instance created for instancing, e.g. the ID for files, the login for users and the name for workflows.

Instance methods are applied to instances of a class. In the Tcl interface, a file instance can be referenced by obj withId or obj withPath, a field instance by attribute withName, a workflow by workflow withName, and so on. The following Tcl code sets the value of the title field to report for the file with the ID 4812. This is done by means of the set instance method.

obj withId 4812 set title report

Alternatively, you can use the class method where to access several instances at once. where produces a list of instances in which a given string is part of or equals the value of a parameter. The following code sets the value of the journal field to no for all files that have the notice format:

foreach id [obj where objClass Notice]
  {obj withId $id set journal No}

In the XML Interface, this Tcl command becomes the following request:

<cm-request ...>
  <obj-where>
    <objClass>notice</objClass>
  </obj-where>
  <obj-set>
    <journal>no</journal>
  </obj-set>
</cm-request>

Of course, the values of more than one field can be set simultaneously in the obj-set element. The obj-where element can also have several subelements in order to further restrict the instances to be modified. This makes it possible to refine the example above by restricting the operation to files that have a draft version:

<cm-request ...>
  <obj-where>
    <objClass>notice</objClass>
    <state>edited</state>
  </obj-where>
  <obj-set>
    <journal>no</journal>
  </obj-set>
</cm-request>

It is important that the class method obj-where is immediately followed by an instance method (here obj-set). This forms a loop in which the instance method is applied to each instance obtained by the where element. For all classes, except obj, the where element is the only one with which instances can be obtained. It covers both the with logic (withName, withId, withPath) and the list class methods of the Tcl Interface. For obj, in addition to where, the class method search exists. search enables you to search for CMS files using the Search Cartridge.

If you search the names of instances in the Tcl Interface using the where method, you obtain those instances whose names contain the given string. On the other hand, the following XML fragment supplies only the field instance whose name exactly matches the given string.

<cm-request ...>
  <attribute-where>
    <name>attr</name>
  </attribute-where>
  <attribute-set>
    <editField parameter="type">textField</editField>
  </attribute-set>
</cm-request>

The reason for this is that the selectors withName, withId and withPath do not exist in the XML Interface. Their function is realized by the name parameter in where and search elements triggering an exact search. However, the parameter nameLike is available in order to be able to select instances whose names only contain a string (instead of corresponding to it). Therefore, the following XML fragment deletes all workflows whose names contain special:

<cm-request ...>
  <workflow-where>
    <nameLike>special</nameLike>
  </workflow-where>
  <workflow-delete/></cm-request>

It is also possible to obtain all the instances of a class using where. In the Tcl Interface, this task has the class method list, which does not exist in the XML Interface: Instead you use an empty where element such as in the following XML fragment with which you can release all files (as long as there is no reason that prevents this action):

<cm-request ...>
  <obj-where/>
  <obj-release/></cm-request>

This can be done using the following code in the Tcl Interface:

foreach id [obj list] {obj withId $id release}

Reading Instance Variables

Using the instance method get, parameters of the instances can be read that were obtained with the previous where. In the following example, the value of the journal field is queried for all fields of the notice file format:

<cm-request ...>
  <obj-where>
    <objClass>notice</objClass>
  </obj-where>
  <obj-get>
    <journal/>
  </obj-get>
</cm-request>

All direct and indirect subelements of a get element must be empty because the Content Management Server processes the element hierarchy in the get element as a template. For each instance obtained using the where element, the template is filled out with the corresponding value and inserted in the response request. This is explained in the section Requests as Templates and the Presentation of the Result Data.

Instance Method Arguments

Instances can have arguments, e.g. there is a method called isOwnerOf in the Tcl Interface. Using it, you can determine whether a user is the administrator of a user or a user group:

user withLogin smith isOwnerOf admins

The instance method isOwnerOf has the login of a user or a group name as an argument (here the group name admins). Arguments are encoded as attributes of the corresponding XML element. The Tcl command above can therefore be translated as follows:

<cm-request ...>
  <user-where>
    <login>smith</login>
  </user-where>
  <user-get>
    <isOwnerOf group="admins"/>
  </user-get></cm-request>

The above example illustrates an important difference between the Tcl Interface and the XML Interface: You can read-access instances only with the get method. As a consequence, all reading instance methods must be used within a get element (here user-get). Such instance methods look like instance variables (such as name for attributes or realName for users), they can however differ due to arguments. Thus, isOwnerOf has exactly one (variable) argument, namely group or user. Arguments of instance methods are (as shown in the above example) specified as tag elements (not as subelements).

This process of encoding instance methods as instance variables is identical for all classes. The following example shows how the instance methods permissionGrantedTo of the class obj are used:

<cm-request ...>
  <obj-where>
    <objClass>publication</objClass>
  </obj-where>
  <obj-get>
    <permissionGrantedTo permission="permissionWrite" user="elton"/>
  </obj-get></cm-request>

Referencing Subproperties

The class of fields is the only one in the Content Management Server whose instances have subproperties: For each field you can define the input field with which the user enters the value of the field. The definition of an input field consists of five parameters; among others its type, set in the Tcl Interface as follows:

attribute withName attr editField set type popup

In the XML Interface, the parameters are referenced with the tag attribute parameter in the editfield tag. The following example shows the equivalent of the above command in the XML Interface:

<cm-request ...>
  <attribute-where>
    <name>attr</name>
  </attribute-where>
  <attribute-set>
    <editField parameter="type">popup</editField>
  </attribute-set></cm-request>

Analogous to this, input field parameters are retrieved in the following way:

<cm-request ...>
  <attribute-where>
    <name>attr</name>
  </attribute-where>
  <attribute-get>
    <editField parameter="type"/>
  </attribute-get></cm-request>

Forming Search Requests

If you have installed the Search Cartridge and have integrated it into the Editorial System, you can search for files in both the Tcl Interface (with the obj search command) and in the XML Interface (with obj-search). How search requests are structured is described in the Tcl Reference as well as the Search Server documentation and the XML Reference.

The obj-search element can be followed by the same elements as obj-where, i.e. you can continue to process the file instances found by the search function using instance methods such as obj-get or obj-set.

Dimensions of Values

Some values of properties are available in the Content Management Server in several languages. Thus, it is possible for versions and other entities to have both a general title field and language-specific versions of this field (title.english etc.). This "ability" of an instance to have several "interpretations" or versions of a property is called a "dimension". The title field of a version or field, a file format and a workflow has the dimension "Language". You can access the versions of properties using a tag attribute in the corresponding XML tag.

"Language" is currently the only property dimension in the Content Manager. It is available in the title, helpText and the description parameters of most classes. The language dimension is encoded using the lang tag attribute:

<cm-request ...>
  <obj-where>
    <objClass>document</objClass>
  </obj-where>
  <obj-get>
    <title lang="en"/>
  </obj-get></cm-request>

Simple and Structured Values

The values of instance properties can be simple or structured values. A simple value is a string, a structured value is a list or a dictionary.

Whereas "string" is a common concept, "list" and "dictionary" require some explanation. A list is an ordered amount of any number of elements. Each element is represented in the XML Interface by a listitem:

<cm-request ...>
  <attribute-where>
    <name>channels</name>
  </attribute-where>
  <attribute-addEnumValues>
    <listitem>books</listitem>
    <listitem>computing</listitem>
    <listitem>music</listitem>
  </attribute-addEnumValues></cm-request>

In the example above, the three possible values books, computing and music are added to the channels attribute (we assume that it is of type enum or multienum). The order in such a list is a result of the order of the list elements. It is not generally relevant.

A dictionary is an unordered amount of any number of allocations of values to names. Each allocation is represented by a dictitem subelement which in turn consists of a name (key) and a value (value):

<myDictionary>
  <dictitem>
    <key>name</key>
    <value>theName</value>
  </dictitem>
  <dictitem>
  ...
  </dictitem>
</myDictionary>

Dictionaries structured with dictitem elements are rarely used in the XML interface (they are used for accessing the user preferences, for example). Most of the name-value pairs are encoded in CRUL using the name as element name and the value as the element’s contents.

The value of a dictionary element and a list element can be a string or list or a dictionary.