Skip to content

Serena XML Message Documents

Every Serena XML request and reply message is an XML document. From a syntactic point of view, each document consists of free-format text delimited by nested markup tags. Tags may be nested to any depth, repeated, or exhibit other forms of structure. The nested tag syntax of an XML document is logically equivalent to a hierarchical n-way tree structure.

Serena XML Syntax Example

Syntactically, a Serena XML document begins with a document type declaration, then opens the root <service> tag. The document ends with the closing </service> tag.

The name attribute of the <service> tag determines which <scope> subtags are valid for nesting within the <service> tag for a particular instance document. Similarly, the name attribute of the <scope> tag determines which <message> subtags are valid for nesting within it.

The <message> tag completes the trio of nested tags needed to invoke a low-level service object in the Extended Services layer of XML Services. The name attribute of the <message> tag, in the context provided by the superordinate <service> and <scope> tags, determines which complex data structures are valid within the <message>.

The following Serena XML example illustrates the nested structure of a Serena XML document. The role of the <service> tag as the root node is clear from the indentation — although in practice, both indentation and line breaks are optional in XML.

It should also be clear from this example why markup tags in free-format text are so flexible for data interchange. Adding one more tag to some level in the hierarchy does not change the meaning of any other tag in the message.

...

XML Example — PACKAGE SERVICE CREATE:

<?xml version="1.0"?>
<service name="PACKAGE">
    <scope name="SERVICE">
        <message name="CREATE">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <applName>ACTP</applName>
                <createMethod>0</createMethod>
                <packageLevel>1</packageLevel>
                <packageType>1</packageType>
                <reasonCode>000</reasonCode>
                <requestorDept>IDD</requestorDept>
                <requestorName>USER24</requestorName>
                <requestorPhone>555 5555</requestorPhone>
                <packageTitle> TEST XML PACKAGE SERVICE CREATE</packageTitle>
                <packageDesc>TEST XML PACKAGE SERVICE CREATE</packageDesc>
                <packageImplInst>TEST XML PACKAGE SERVICE CREATE</packageImplInst>
                <siteInfo>
                    <siteName>SERT8</siteName>
                    <installDate>20091231</installDate>
                    <fromInstallTime>0100</fromInstallTime>
                    <toInstallTime>0200</toInstallTime>
                    <contactName>USER24</contactName>
                    <contactPhone>555 5555</contactPhone>
                    <alternateContactName>USER24</alternateContactName>
                    <alternateContactPhone>555 5555</alternateContactPhone>
                </siteInfo>
            </request>
        </message>
    </scope>
</service>

Logical Document Structure

The logical structure of a ChangeMan ZMF XML Services document can be visualized as an n-way hierarchical tree. This structure is illustrated for the high-level nodes common to all services in Exhibit 3-3.

Exhibit 3-3. High-Level XML Document Structure

Diagram conventions for are as follows: Each node of the tree (shown as a rectangle) corresponds to a named data element represented in markup by an XML tag. One or more branches from a node (shown by solid or dashed lines) represent the inclusion of subsidiary nodes in the higher-level node’s contents. Dashed borders indicate an optional data element; solid borders indicate that the node is required. Multiple occurrences of a node are allowed — each occurrence of which includes the node’s subordinate data structure. Mutually exclusive relationships among nodes is shown by a lozenge-shaped octagon labeled “XOR,” from which branches extend to the mutually exclusive nodes with their substructures. Leaf nodes indicate simple data elements containing raw data rather than a substructure of subordinate data elements. An ellipsis (three consecutive dots) indicates the omission of subordinate nodes from the diagram for clarity.

Nodes in the structure diagram are annotated according to the following conventions:

  • Tag names appear in the blue region of the node.

  • If attributes for the tag exist, their names and permitted values appear in a white region appended to the node.

  • If the number of occurrences of a node is variable, the allowed range for the number of repetitions appears below the lower right corner of the node. The number of occurrences can range from zero to unbounded.

  • A mandatory sequence for nodes in a data structure is shown by sequence numbers in solid circles at the left of each node in the sequence.