Xoom Processor (xp.exe) is a command line tool for retrieving, transforming, storing and applying configuration information using Xoom and its capabilities. Xoom Processor enables users to execute a pipeline of operations. At each stage of the pipeline, a distinct operation can be performed, and the result of the operation stored, applied and/or fed into further operations in the pipeline.

Syntax Examples

The basic syntax of Xoom Processor can be most easily understood by examining the examples bellow, then referring to the detailed documentation that follows.

xp : default.xml
Retrieves the default query from the local Xoom server and saves the result to a file named default.xml.
xp zeus:All # t.xsl zeus-all-transformed.xml
Retrieves the query named All from the Xoom server zeus, transforms the result using the XSLT stylesheet in the file named t.xsl and saves the result to a file named zeus-all-transformed.xml.
xp :Settings settings.xml # t.xsl settings-transformed.xml
Retrieves the query named Settings from the local Xoom server, saves the result to a file named settings.xml, then transforms the result using the XSLT stylesheet in the file named t.xsl and saves the transformed result to a file named settings-transformed.xml.
xp : default.xml # t1.xsl # t2.xsl default-t1-t2.xml
Retrieves the default query from the local Xoom server, saves the result to a file named default.xml, then transforms the result using the XSLT stylesheet in the file named t1.xsl, then transforms the result of the previous transform using the XSLT stylesheet in the file named t2.xsl and saves the twice-transformed result to a file named default-t1-t2.xml.
xp : default.xml # t1.xsl default-t1.xml # t2.xsl default-t1-t2.xml
Retrieves the default query from the local Xoom server, saves the result to a file named default.xml, then transforms the result using the XSLT stylesheet in the file named t1.xsl, saves the result of the transformation to a file named default-t1.xml, then applies a second transform using the XSLT stylesheet in the file named t2.xsl and saves the twice-transformed result to a file named default-t1-t2.xml.
When familiarising oneself with Xoom Processor, the -d option is very helpful. This option instructs Xoom Processor to not actually perform any operations, but instead to output a plain English description of the steps that would be performed:
xp -d : default.xml # t1.xsl # t2.xsl default-t1-t2.xml
```
Get from query 'DEFAULT' on server 'localhost'
Write to file 'default.xml'
Transform using XSL stylesheet from file 't1.xsl'
Transform using XSL stylesheet from file 't2.xsl'
Write to file 'default-t1-t2.xml'
```

Simplified Syntax

xp [options] <source> [ [ <target> | <operation> [ <parameter> ... ] ] ... ]

source: Provides XML document input into the processing pipeline.
target: Provides a destination for the current pipelined XML document.
operation: Performs a specific operation involving the current pipelined XML document and typically one additional parameter which is typically a source.
parameter: An additional parameter or input to an operation, typically a source.

Sources and targets

The Xoom Processor pipeline operates on an XML document. Some operations require XML in the format of a Xoom file. source and target can be any of the following:

an XML file specified by its path (if required) and name, such as XoomFile.xml. When used as a source, the file is read; when used as a target, the file is written.
a folder specified by its path, such as ConfigDir\. The trailing directory separator character \ is always required in order to distinguish between file names and folders. When used as a source, all XML files in the folder and recursively its sub-folders will be read and combined: the files must be Xoom XML format; when used as a target the folder and file-per-item hierarchy will be created and written. When used as a target, the folder must be empty or an error will be reported. See Xoom Folders for further information.
a live Xoom server specified as [hostname]:[queryname], where hostname defaults to localhost, and queryname defaults to DEFAULT. The colon : is always required in order to distinguish between Xoom servers and file names. When used as a source, the query is retrieved from the server; when used as a target, the queryname part is ignored and a set operation is performed on the server (see also the --enable-set option).

Operations

The following operations are supported:

# <xslt-file>: Transforms the current pipeline XML using the XSLT stylesheet in the file specified by xslt-file, such as one of the supplied Xoom reports (see further examples). The output of the transformation must be valid XML (this includes XHTML), but is not required to be Xoom format XML: in such case, subsequent operations that require Xoom XML cannot be used.
+ <source>: Combines the contents of the current pipeline XML document and the Xoom XML document specified by source by creating a configuration that contains all items from both documents. This operation is only supported if the two sources contain no common items, and will report an error otherwise. Both documents must be in Xoom XML format.
- <source>: Calculates the difference between the current pipeline XML document and the Xoom XML document specified by source, or, in other words, the relative complement of the Xoom XML document specified by source in the current pipeline XML document. The operation results in a configuration containing all items that are in the current pipeline XML document but aren’t in the Xoom XML document specified by source, with the value they have in current pipeline XML document. This is the quickest way to obtain a Xoom file that will take you from the baseline configuration (source) to the final configuration (the current pipeline XML document). Both documents must be in Xoom XML format.

Options

--describe or -d: Describes what the current command will do in normal English, but doesn’t actually do anything. This option is useful to verify that the command will have the intended effect before it is executed.
--enable-set: By default, Xoom Processor will not apply any configuration changes to live Xoom servers in order to avoid doing so accidentally due to user error. Therefore, this option needs to be specified to indicate that there is indeed an explicit intention by the user to change the configuration of one or more servers. Without it, Xoom Processor will issue a warning and skip the set operation.
-vn: Specifies the verbosity level of the output to stderr. Where n is: 0 – silent; 1 – (default) errors and warnings; 2-4 – further levels of increasingly more detailed trace information.
--comparer-config file.xml: Specifies the file that specifies the configuration of what Xoom items are considered to be the same. Defaults to XoomConfig_Compare.xml in the Xoom folder. For example, this compare configuration specifies that Keys can be ignored for Service Optimization items, and that the order in which rule types are defined doesn’t matter. This option is not typically intended for user use, and we recommend that Zany Ants support is consulted prior to making changes to the compare configuration in a production setting.

Scoping

Consider the following example:

xp : ( # trans1.xsl res1.xml ) ( # trans2.xsl res2.xml )

The matching parentheses ( and ) create an independent scope: the operations inside the scope operate on a copy of the current pipeline XML document which is taken at the start of the scope, and discarded at the end of the scope. Operations inside the scope do not affect the pipeline XML document outside the scope. The example shows how a server can be queried once (a potentially time-consuming operation), and the result of that query can be transformed and saved independently by two different transformations. The -d option outputs a hierarchical representation of scopes, and is as follows for the example above:

Get from query 'DEFAULT' on server 'localhost'
+-> Transform using XSL stylesheet from file 'trans1.xsl'
|   Write to file 'res1.xml'
+-> Transform using XSL stylesheet from file 'trans2.xsl'
|   Write to file 'res2.xml'

Notes:

The spaces around parentheses (and indeed all operation symbols) are required.
Scopes may be nested, for example:
```
xp : ( # trans1.xsl ( # trans2a.xsl res2a.xml ) ( # trans2b.xsl trans2b.xml ) )
```
Note that the outer scope in the example is not actually needed, this is intentionally a simple expression.
Avoid creating unnecessary scopes as each scope will create a copy (in memory) of the current pipeline XML document at the start of the scope, which could be a resource-intensive operation with large XML documents.

Xoom Folders

Xoom Processor introduces the concept of Xoom Folders, an alternative to a single Xoom file where instead each Xoom item is stored in a separate Xoom file with a well-defined name within a well-defined hierarchy of folders. The main use case for the use of such Xoom Folders is configuration versioning, as having file-per-item versioning makes it easy to identify exactly which items changed between any two revisions, and to see the full history of each individual item.

The folders have the following structure (in this example our Xoom configuration only contains Assignment and Task under Scheme, one BundlerConfiguration item, and CurrentTimeForDebug and agents manager settings):

FolderRoot
  BundlerConfiguration
    BundlerConfiguration
      Break Dedication.X.xml
  Scheme
    Collection
      Assignment.1.xml
      Task.1.xml
  Setting
    Setting
      [Application]~Agents~AgentsManager~.52NEP.xml
      [Application]~Internal~CurrentTimeForDebug~.4GXRS3L.xml

The folder structure is similar to the way items are organised in a Xoom file. The folders under the root folder (which can have any name) have the same names as elements under the root XML element in the Xoom file. Each of these folders then contains a further folder that contains all items of the same type (with Service Optimization there is always only one such folder). Finally, these folders in turn contain Xoom files for each item. In other words, each item file is a full Xoom file that can be imported separately or combined with other files (using the combine operation) into Xoom files containing several desired items.

The file names for the Xoom files contain all key values that are part of their Xoom ID (in the example above, that would be Name for BundlerConfiguration, IdName for Collection, and Owner, Category, SubCategory and Name for Setting). When there are multiple keys, they are separated by ~, such as with settings in the example. Any characters that are not permitted in a file name are replaced with an underscore _ . This is then followed by a dot and a calculated sequence of characters that encodes unique characteristics in the item’s identity that cannot be reliably encoded in the file name, where without the calculated character sequence non-unique file names could be generated. The characteristics encoded include replaced non-permitted characters and the capitalization of letters as some common file systems either aren’t case-sensitive or present significant usability issues with file names which differ only by letter case (for example, the FAT32 file system commonly used on portable storage devices, and NTFS as used by default in Windows).

Further Examples

xp :All default.xml Default\

Retrieves the query called All from the local Xoom server and saves the result in both a file called default.xml and a folder called Default.

xp : # BGOReport.xsl bgo.xls

Retrieves the default query from the local Xoom server, transforms the configuration using Xoom’s BGOReport.xsl and saves the result as bgo.xls which can then be opened using Excel. (The resulting file is actually an HTML file, but Excel supports opening HTML files. Also, unless XoomReport.css is copied into the same folder with bgo.xls, the formatting will be missing, although that’s not as much of a problem with Excel.)

xp zeus:All ( # BGOReport.xsl bgo.html ) ( # LogicDomainMatrix.xsl ldm.html ) ( # ActiveScheduleAgentsReport.xsl sch.html )

Retrieves the query called All from a Xoom server called zeus and produces three reports (without rerunning the query) saved into three HTML files. The -dflag produces the following with this command:

Get from query 'All' on server 'zeus'
+-> Transform using XSL stylesheet from file 'BGOReport.xsl'
|   Write to file 'bgo.html'
+-> Transform using XSL stylesheet from file 'LogicDomainMatrix.xsl'
|   Write to file 'ldm.html'
+-> Transform using XSL stylesheet from file 'ActiveScheduleAgentsReport.xsl'
|   Write to file 'sch.html'

The file paths have been abbreviated from the above output to ease readability.

This method can be very useful to automatically (via a scheduled task) or on demand (using a batch file) produce all desired Xoom reports, which can in turn dramatically ease the understanding of the configuration and help work on its modifications.

xp :All - ConfigRepo\ diff.xml Diff\

Calculates the configuration changes that need to be applied to get from the baseline configuration stored in ConfigRepo Xoom folder to the current state of the All query on the local Xoom server, and stores the result in both a Xoom file named diff.xml and a Xoom folder named Diff.

xp --enable-set patch.xml server1: server2: server3:

Applies the Xoom configuration contained in the file named patch.xml to live Xoom servers server1, server2 and server3. Note the --enable-set option, as without it warnings will be issued without making any changes to the configuration of the three servers.

Zany Ants

Configuration, enlightened.

Xoom Processor