Xoom 3.7 has been released

We are pleased to announce the release of Xoom 3.7. This is a major release including both significant new functionality and performance improvements.

“Keep target” functionality

Some aspects of settings are specific to a particular environment, and therefore shouldn’t be overwritten during the deployment of configuration changes even when the rest of the setting in question has changed. Examples are environment specific connection settings and credentials, and server names.

The ability to preserve such information is now supported by Xoom. The nodes that are affected need to be specified in the Xoom configuration, and those nodes will be marked with xpi:keep-target attribute that will specify whether the target node’s value should be kept or not by giving them the values “true” or “false” respectively. This allows users to easily review and change the behaviour on deployment (i.e. whether to keep the target environment’s value, or overwrite it) as desired for a particular node using simple search and replace.

Encryption of sensitive information

In configuration, there are settings that contain sensitive information, such as connection strings to external databases or just passwords used to connect to external resources. In Service Optimization configuration, these settings are often stored in clear text, which means that they are clearly readable to anyone with suitable access.

In the past, Xoom stored those settings in their clear text form (essentially keeping the information retrieved from Service Optimization in the same form), which meant that anyone with access to a Xoom file containing those settings could see their content. It also meant that these settings would be persistently stored in cases of configuration library or configuration versioning, which would often contravene the security policy. In order to address these situations, Xoom offered RemoveSensitiveInformation report which, as its name suggests, removed the sensitive information entirely from the configuration, with an unfortunate side effect of making it necessary to re-enter that information on the target system after deployment of such stripped XoomXML files.

In this release we address this concern comprehensively by introducing the capability to transparently encrypt the settings that are defined as sensitive in a way that fully preserves all use cases while preventing the information from being retrieved from XoomXML files. The approach in use has the following properties:

  • Configuration retrieval and deployment work seamlessly using all client tools without change.
  • The content of an actual XML node containing sensitive information is replaced with a string “xoom-encrypted:” followed by the encrypted content. Xoom will automatically encrypt the content on retrieval and decrypt it on deployment.
  • The same setting within the same item will be encrypted consistently. This makes the encryption compatible with configuration versioning.
  • One occasional exception to this (depending on quite complex criteria) is when the structure of the XML around the sensitive setting changes. When that happens, the encrypted value may be different even though the sensitive information itself remains the same, but in those cases the item as a whole will have changed anyway so there is no false positive from the point of view of configuration versioning or difference detection.
  • The same content in different places in the configuration will be encrypted differently. This adds security, as it makes it impossible for the attacker that knows one password  to find out where else that same password may be of use.

Obviously, while this feature fully addresses the storing of sensitive information in XoomXML documents, it does nothing to address the underlying problem of storing that information in clear text in Service Optimization database.

The encryption of settings that are marked as sensitive out of the box is controlled by the corresponding parameters, which all default to true, which means the encryption is enabled. The following is the list of such settings, with their corresponding parameters:

  • Connection strings inside Audit Definition’s connection settings (parameter Product.W6.Objects.EncryptAuditConnectionString).
  • Connection strings inside ClickForecast General Settings data sources definitions (parameter Product.W6.Objects.EncryptClickForecastDataSourcesConnectionString).
  • Passwords inside GIS Provider List Settings provider configuration sets’ country parameters (parameter Product.W6.Objects.EncryptGisProviderSettingsPassword).
  • Passwords inside Integration Manager’s destination credentials (parameter Product.W6.Objects.EncryptMapperDestinationPassword).

It is important to note that the definition of sensitive information will often differ from project to project, and it is therefore recommended to verify that all sensitive settings are indeed defined in each case.

Xoom Processor

XSL transformations that result in an HTML or text file are now supported, as long as the XSLT in question correctly declares the result type. Because Xoom Processor works with sequences of XML documents, the results of these transformations can only be saved to a file or printed to the console, and can’t take part in further processing. However, the change enables HTML and text reports to be created automatically and en masse using Xoom Processor scripts.

Xoom Processor now supports refined variations of the “combine” (+) operator. The variations are as follows:

  • + (plus) behaves as it always did. It reports an error when the two configurations being combined contain the same item.
  • *+ (star-plus) when both configurations contain the same item, this operator takes the item from its left operand.
  • +* (plus-star) when both configurations contain the same item, this operator takes the item from its right operand.
  • +! (plus-exclamation point) excludes the item from the combination when both items exist.

Also in this release, Xoom Processor (xp.exe) has become a stand-alone tool that doesn’t need any other Xoom files to be present in order to run. This means that xp.exe can now be copied to a folder where it’s needed, and used from there without the need for installation, as long as the servers that it’s connecting to are properly installed and licensed.

New parameters

Product.W6.Objects.RemoveRevisionAndStamp – Specifies whether Revision and Stamp properties should be removed in the Xoom representation of Service Optimization objects that have those properties. Previous versions of Xoom always removed these properties, but from 3.7 on the behaviour has been changed so that they are kept by default. This parameter allows one to change the behaviour back to pre-3.7 behaviour by setting its value to true.

The major use case where the new functionality is very useful is in configuration versioning, where it would usually be desirable to see who made the last change.


ActiveScheduleAgentsReport – When the decomposition covers all territories the report now explicitly says so. Previously information about the territories was omitted in such situations.

BadReferencesReport – [NEW] The report lists all items containing bad references. For each bad reference, it lists all paths within the item where the same bad reference is present. The report is very useful for identifying and correcting bad references in the configuration, which is important as bad references often result in subtle and hard to identify problems in the behaviour of Service Optimization.

DecompositionByGeography – The report now has separate sections for regions and districts. In both cases, it distinguishes the items that are included in various decompositions through region (indicated with letter R), district (D) or by virtue of all territories being included (*).

ExtractComponents – [NEW] The reports lists all ProgIDs (whether COM or .NET) and assembly references that appear in the configuration, and from where in the configuration they are referenced. Its main use is in the maintenance and upgrade scenarios, where there is a need to know which code components (in particular customisations) are actually in use.

GroupByGeography – The report now has separate sections for regions and districts, very similar to the DecompositionByGeography report above. In addition, it no longer lists groups without any geographical references, which is most or all groups in many cases.

ReferencesReport – The report now contains hyper-links from any dependents or dependencies to the target item. This makes it incredibly easy to explore the configuration in both directions of dependency to understand which items are related.

SchemeCustomisationsReport – [NEW] The report lists all scheme customisations in the system (based on the value of IsProduct property). For custom collections it lists their type and the properties they have, and for product collections it lists all custom properties and how they are defined.

SchemeCustomisationsSummary – [NEW] The report produces a CSV file summarising the number of scheme customisations by collection. The report must be run using Xoom Processor.

SortW6XoomFile – [NEW] The report reorders a Xoom file into canonical order that is more suitable for text exploration and comparison. All Xoom tools already do this automatically, so this report is intended for Xoom files that were produced by other means, such as copying parts of different configurations together, or generating the file programmatically.  Note: the ordering of types and items in a Xoom file is not important for actual Xoom tools (including for deployment), so this report is mostly intended for cases where the ordering is important for other reasons, such as a user being able to easily navigate the file and find items within.

UnreferencedItemsReport – [NEW] The report lists all items in the configuration that are not referenced from anywhere, together with their dependencies, in order to make it easier to understand their context. This report is particularly useful in the context of a configuration clean-up.

Synchronisation report

The somewhat misleadingly named Synchronisation Report is actually a tool that, when provided with two Xoom files – let’s call them original and modified – produces three outputs:

  • A minimum Xoom file containing everything that needs to be imported to move from original to modified configuration. This Xoom file will not contain any items that are only in the original configuration or are the same in both configurations.
  • An SXP file that, when executed, deletes all the items that are in the original configuration but not in the modified configuration. This is useful when there is a desire to bring two environments to exactly the same configuration, including removing the items that are not present in the reference (i.e. modified) environment.
  • An HTML file that summarises all the differences between the two configurations, including sections on what was added, modified and deleted. For modified settings, it also lists the user who made the modification, when that information is available. The report has a separate section for the scheme, where the documentation of the changes can be much more detailed due to scheme’s uniform representational structure.

Diagnostic Snapshot and Xoom Corpus Generator

AutoCapture tool was replaced with two new tools: Diagnostic Snapshot and Xoom Corpus Generator. Like AutoCapture before them, both are command line tools.

Diagnostic Snapshot is part of the Xoom installation. It is designed for support scenarios, and when run it compiles information about the local Xoom system, including various logs and other diagnostic information. This information can be sent back to Zany Ants for further processing. The tool is run from the command line with a single parameter, which specifies the folder in which the information will be stored. The tool collects the following information:

  • An up-to-date Xoom corpus.
  • The results of all defined named queries.
  • Xoom log files.
  • The application event log from the last 24 hours (only on Windows 7 / Server 2008 or later).

Xoom Corpus Generator is a very similar tool, but is intended to be used without an existing Xoom installation. It is most relevant for capturing the corpora of new Xoom customers without needing to install Xoom first.


All Xoom client tools now alert the user when the license is no longer compliant.


The installer has been rewritten from scratch in order to support future extensions for additional products, both in terms of what Xoom manages and in terms of add-on functionality for Service Optimization. In practice, the most important difference is that in the vast majority of cases the Service Optimization server no longer needs to be shut down in order to upgrade Xoom, making timely Xoom upgrades much more palatable in production systems.

Detection of inconsistent references

When multiple key values are used to determine the referenced item during configuration retrieval, Xoom has hitherto used the required key values to determine the targeted items, ignoring the optional key values. If the targeted item was found successfully, then the optional key values were recreated on the target environment so as to be consistent with the targeted item, regardless of their values in the source environment.

This is almost always exactly the desired behaviour. However, there are cases where optional key values in the source environment are inconsistent with required key values due to misconfiguration, and the desired targeted item is the one that is actually referenced by the optional key values (it all depends on how the setting was originally created and transported into the source environment). In those cases, automatic correction of those key values during transport is not the desired behaviour. In response to this, we made the decision to err on the side of caution from 3.7 onwards.

So what happens?

  • If the required key values are inconsistent, you’ll get a bad reference without a warning, just as with previous versions of Xoom.
  • If the required key values are consistent but the optional key values are inconsistent with the targeted item, then Xoom will place a warning with the description of the problem on the reference, including the key values that are mismatched. The type of reference created will then depend on the value of the new parameter, Xoom.DataProcessing.ShouldCorrectMismatchedReferences. By default the parameter is set to false: the reference will be marked as a bad reference, and will show as such during deployment (for example in Settings Migration Tool), allowing the user to address the problem at source. Change the value of the parameter to true and the behaviour of previous versions of Xoom is restored: the reference will be ‘good’ and the optional key values will be recreated during deployment, consistent with the targeted item.

Interpretation improvements

  • Extensive improvements in the interpretation of ClickMobile Client administrative settings (templates).
  • Significant improvements in the interpretation ClickSchedule Web Client administrative settings (templates).
  • Refined the interpretation of rules and objectives for ClickPlan actions.
  • Added interpretations of the settings within Schedule Tuning Parameters, including referenced agents, background optimizations and decompositions.

Other improvements

  • Custom business objects that are cached and have an entry in SXP object references are now included in Settings Migration Tool under a new node called Business Objects.
  • In Settings Migration Tool, the message informing users that scheme changes have been detected now makes it clear that nothing will be deployed automatically and that there will be a chance to review the changes first.
  • Xoom Explorer now has a new ‘Transform and Launch’ button that is convenient when going through reports and opening them in a web browser.
  • Xoom Explorer no longer locks the transformation (XSLT) files that are used during the transformation. This is very useful when developing and testing a new transformation, because the file can be changed and used to transform the Xoom file again without having to reopen the tool and reload the configuration.
  • Most of the reports now have a more unified and more pleasant formatting, making them easier to read and publish.
  • Increased the breadth of documents supported in order to accommodate more complex configurations encountered in the field.
  • The comments that are present in reference nodes are now preserved, as is white space. This is all insignificant from a functional point of view, but it may be significant to administrators maintaining configuration. Xoom now allows this information to be preserved in full.
  • Added the capability to store insignificant white space information in order to make it possible to preserve the formatting of XML within the configuration that has been deliberately formatted in a certain way for whatever reason.
  • Added support for Service Optimization 8.0 to 8.1.3, the versions that were previously omitted due to the lack of suitable features in the ClickSoftware API (those features were only introduced in Service Optimization 8.1.4). The support of the scheme in these versions is limited to read-only functionality.
  • Significantly improved the usability of incomplete corpora by better utilising the information that is inside them but in the wrong form, and by emitting fewer error messages when the information isn’t present.
  • Significant performance improvements both during retrieval and deployment of configuration.

Bug fixes

  • Fixed: scheduling workflow BGO steps in Active Schedule Agents report did not include the scheduling workflow in use.
  • Fixed: problems referencing items with identifiers that contain both single and double quotes.
  • Fixed: some changes to items with bad references failed to be identified during retrieval.
  • Fixed: the body of GIS settings that contain inner XML stored as strings was misformed during retrieval.
  • Fixed: the body of Extended Match Properties Objective lacked reference meta-data in cases of multi-value matches.