Requests as Templates and the Presentation of the Result Data

For each request in a payload, a response is created in the result payload. For requests, which do not query instance properties, but set or create instances, the data are returned which would be returned by the corresponding Tcl command.

<cm-request ...>
  <obj-where>
    <id>2001</id>
  </obj-where>
  <obj-create>
    <name>simplepub</name>
    <objClass>publication</objClass>
  </obj-create>
</cm-request>

The above request which creates a file immediately below the base folder leads to the following response:

<cm-response ...>
  <cm-code numeric="0" phrase="ok">
    <obj>
      <id>32191</id>
    </obj>
  </cm-code>
</cm-response>

For requests with which instance properties are to be obtained using where and the following get, the structure of the request gives the structure of the response. A request is to a certain extent a template which the Content Management Server fills out in order to create the response. In the following example, the request shows that the response is to contain the name and the ID of the selected files.

<cm-request ...>
  <obj-where>
    <objClass>document</objClass>
  </obj-where>
  <obj-get>
    <name/>
    <id/>
  </obj-get>
</cm-request>

The response document to this request will contain a response in which the name and the ID are supplied for each file matching the criteria in the obj-where element:

<cm-response ...>
  <cm-code numeric="0" phrase="ok">
    <obj>
      <name>mary</name>
      <id>92674</id>
    </obj>
  </cm-code>
  <cm-code numeric="0" phrase="ok">
    <obj>
      <name>john</name>
      <id>72941</id>
    </obj>
  </cm-code>
</cm-response>

In both of these example responses above, you can see that for each instance selected with where, a cm-code element is created. The queried instance values are encoded as the content of the class element within such an element. In the above example, this is the obj element.

Some instance properties are references to instances of the same or a different class. Therefore, e.g. the parent of a file (except for the base folder) is a reference to a file instance. The members (users) of a user group (group) are user references, and the mandatory fields (mandatoryAttributes) of a file format are references to fields (attribute). As will be shown later, the properties of instances to which the references refer can also be queried. This is done by extending the request template in the get element.

The following is an example to show how the files contained in the base folder are queried and encoded in the response:

<cm-request ...>
  <obj-where>
    <path>/</path>
  </obj-where>
  <obj-get>
    <children/>
  </obj-get>
</cm-request>

The response has the following pattern:

<cm-response ...>
  <cm-code numeric="0" phrase="ok">
    <obj>
      <children>
        <listitem>92674</listitem>
        <listitem>72941</listitem>
      </children>
    </obj>
  </cm-code>
</cm-response>

In these cases, what is returned are the unique IDs of the instances; i.e. the IDs for files, versions and links and the names for instances of other classes. An ID is not encoded as the content of the corresponding property element, i. e. the ID of a file reference is not the content of an id element and the name of a field is not the content of a name element. Instead, the IDs are encoded as list elements using listitem. See the following example in which those groups are obtained of which a user is a member. The request

<cm-request ...>
  <user-where>
    <login>smith</login>
  </user-where>
  <user-get>
    <groups/>
  </user-get>
</cm-request>

is followed by a response according to the following pattern:

<cm-response ...>
  <cm-code numeric="0" phrase="ok">
    <user>
      <groups>
        <listitem>cmadmins</listitem>
        <listitem>sysadmins</listitem>
      </groups>
    </user>
  </cm-code>
</cm-response>

Extended Queries

If the data obtained in a request are instances of a class, you can extend the request to also obtain data from these instances. Therefore, in the above example, the queried groups are instances of the class group and parameter values of each of these instances can be queried in the same request.

<cm-request ...>
  <user-where>
    <login>smith</login>
  </user-where>
  <user-get>
    <groups>
      <group>
        <realName/>
        <users>
      </group>
    </groups>
  </user-get>
</cm-request>

The above request creates a response according to the following pattern:

<cm-response ...>
  <cm-code numeric="0" phrase="ok">
    <user>
      <groups>
        <group>
          <realName>CM Administrators</realName>
          <users>
            <listitem>smith</listitem>
            <listitem>roberts</listitem>
          </users>
        </group>
        <group>
          <realName>System Administrators</realName>
          <users>
            <listitem>smith</listitem>
          </users>
        </group>
      </groups>
    </user>
  </cm-code>
</cm-response>

Data about the original instances and instances referenced by them, can therefore be obtained in any depth with a single request. To do this, you encode a property to be queried-- as in the above example-- not as an empty element. Instead you designate as its content the template for the next query.

The following example shows how you obtain the names of folders and their file formats. The allowed formats for files contained in the folder are queried from the file formats and also from these the name and the title in English:

<cm-request ...>
  <obj-where>
    <objType>publication</objType>
  </obj-where>
  <obj-get>
    <name/>
    <objClass>
      <name/>
      <validSubObjClasses>
        <name/>
        <title lang="en"/>
      </validSubObjClasses>
    </objClass>
  </obj-get>
</cm-request>

This request creates a response according to the following pattern:

<cm-response ...>
  <cm-code numeric="0" phrase="ok">
    <obj>
      <name>ROOTPUB</name>
      <objClass>
        <name>publication<name/>
        <validSubObjClasses>
          <objClass>
            <name>publication</name>
            <title lang="en">Standard Publication</title>
          </objClass>
          <objClass>
            <name>document</name>
            <title lang="en">Standard Document</title>
          </objClass>
          ...
        </validSubObjClasses>
      </objClass>
    <obj>
  </cm-code>
  <cm-code numeric="0" phrase="ok"> ... </cm-code>
  <cm-code numeric="0" phrase="ok"> ... </cm-code>
  ...
</cm-response>

Please note that a property only becomes a reference to be subsequently followed by not leaving the corresponding element empty but encoding the properties to be obtained in its content. The following request supplies for publication files the ID of their respective parent folder and the IDs of the files in this folder (i.e. the original file and its siblings):

<cm-request ...>
  <obj-where>
    <objType>publication</objType>
  </obj-where>
  <obj-get>
    <parent/>
    <parent>
      <children/>
    </parent>
  </obj-get>
</cm-request>

Whereas the first parent element only retrieves the ID because it is empty, the second supplies the properties of the parent file specified in its content, i.e. the children.