Editing XML documents

This article applies to:

• Trustwave MailMarshal (SEG)
• Trustwave ECM/MailMarshal Exchange
• WebMarshal

Question:

• What are recommended practices for editing XML settings documents?

Background:

A number of Trustwave (Marshal Product Line) products use XML documents to store settings and configuration information.

For instance WebMarshal configuration, SEG SQM themes, and SEG Category Script files are all in XML format.

• When you edit these files, you must ensure they remain in valid XML format.
  • If the XML documents are not well formed, then the affected products may be unable to start.

• As standard practice, back up any file before editing.

General notes about XML

XML has special character encoding and syntax requirements.

• All values inside an XML document are CASE SENSITIVE. For example, the following elements with different case are not interchangeable.

<Debug fullTrace=”false” /> 
<Debug fullTrace=”False” />

• When evaluated by SEG. ECM, or WebMarshal, an item entered in the wrong case will generally be ignored.
• However in case of nodes with the "same" name but different case, unexpected results such as services stopping can occur.

• Data values in an XML document must be correctly encoded. In particular, if you need to enter & (ampersand character) as data, use the HTML encoding &amp;

Trustwave recommends that you use an XML editing program that validates the XML code.

You can use XML Notepad (a free tool from Microsoft).

• Download XML Notepad

WebMarshal specific issues

It is important to note that while XML is a defined structure, there are still many ways that applications can store data into this structure.  WebMarshal uses a number of XML documents that define settings for each of the services that make up the WebMarshal application.

When WebMarshal parses an XML configuration file it searches for a specific section in the XML document and loads each of the settings that are contained there.

Typically a path to a configuration element will be shown much like a directory path, such as WebMarshal\Engine\Config

Within an XML document, the structure is represented like this:

<WebMarshal>
     <Engine>
           <Config> 

           </Config>
     </Engine>
</WebMarshal>

In WebMarshal configuration, normally the element to be created is placed in the "Config Node" of the XML(between the <Config> and the </Config> tags of the XML document).

Values are included as "attributes" within the node. In the XML document, attribute values are always placed in quotes.

Example

The following example of an XML file containing a node with attributes comes from article Q11896:

<WebMarshal>
      <Proxy>
          <Config>
        <ProxySettings minFreeSpace="{size in MB}" [other attributes...] />
          </Config>
      </Proxy>
</WebMarshal>

Multiple nodes

When parsing an XML document the products look for configuration elements in the first occurrence of the path to those elements that it finds. If an additional section is created with the same node name (for instance a new Config section), then only the first node with that name will be processed. 

Additional items will be ignored and not processed.

When editing a WebMarshal XML configuration document, it is important to search for existing nodes.

• Validate that your entry is created ONLY in the path indicated.
• Only create one of each named node, and one of each named attribute in the node.
• Do not create an additional section elsewhere in the document.