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 knowledge base, 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 XoomXML file containing those settings could see their content. It also meant that these settings would be persistently stored in cases where there is a configuration library or in configuration versioning, which would often contravene the security policy. In order to address these situations, Xoom offered the Remove Sensitive Information report that, as its name suggests, removed the sensitive information entirely from configuration. This has the unfortunate side-effect of making it necessary to re-enter that information on the target system after deploying XoomXML files that have been cleaned in this way.

In this release we comprehensively address this concern. We introduce the capability of transparently encrypting sensitive settings in such a way that fully preserves all use cases at the same time as making that information irretrievable from XoomXML files. The approach 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. 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.

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. Parameters and the settings they encrypt are as follows:

Table 1. Xoom parameters: `Encrypt`
Parameter	Encrypts	Takes values	Default	Xoom release
`Product.W6.Objects.EncryptAuditConnectionString`	Connection strings inside Audit Definition’s connection settings.	`true/false`	`true`	3.7
`Product.W6.Objects.EncryptClickForecastDataSourcesConnectionString`	Connection strings inside ClickForecast General Settings data sources definitions.	`true/false`	`true`	3.7
`Product.W6.Objects.EncryptGisProviderSettingsPassword`	Passwords inside GIS Provider List Settings provider configuration sets’ country parameters.	`true/false`	`true`	3.7
`Product.W6.Objects.EncryptMapperDestinationPassword`	Passwords inside Integration Manager’s destination credentials	`true/false`	`true`	3.7

It is important to note that the definition of sensitive information will often differ from project to project, and it is therefore recommended you 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 (+). The variations are as follows:

+ (plus) behaves as it always did. It reports an error when the two documents being combined contain the same item.
*+ (star-plus) when both documents contain the same item, this operator takes the item from its left operand.
+* (plus-star) when both documents 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 Xoom servers that it’s connecting to are properly installed and licensed.

New parameters

Previous versions of Xoom always removed Revision and Stamp Properties from the XoomXML representation of those Service Optimization Objects that have them. From 3.7 the behaviour has been changed so that they are kept by default. Restore the behaviour by setting the following parameter to the value true. The major use case is in configuration versioning, where it would usually be desirable to see who made the last change.

Table 2. Xoom parameters: Remove Revision and Stamp
Parameter	Description	Takes values	Default	Xoom release
`Product.W6.Objects.RemoveRevisionAndStamp`	On retrieval, removes Revision and Stamp from Objects that possess these Properties.	`true/false`	`false`	`3.7`

New reports

Bad References report report. 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. Bad references often result in subtle, hard to identify problems in the behaviour of Service Optimization.

Extract Components report report. The report lists all ProgIDs (whether COM or .NET) and assembly references that appear in configuration, and from where in 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.

Scheme Customisations report. 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 Property they have, and for product Collections it lists all custom Property and how they are defined.

Sort W6 Xoom File transformation. The report reorders a XoomXML file into canonical order so that it is more suitable for text exploration and comparison. All Xoom tools already do this automatically, so this report is intended for XoomXML files that were produced by other means, such as: copying parts of different configuration together, or generating the file programmatically.

Note: the ordering of types and items in XoomXML is not important for Xoom tools (including for deployment). 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.

Unreferenced Items report report. The report lists all items in 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 configuration clean-up.

Improvements to existing reports

Active Schedule Agents report report. When the Decomposition covers all territories the report now explicitly says so. Previously information about the territories was omitted in such situations.

Decomposition by Geography report. 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 (*).

Groups by Geography. The report now has separate sections for Regions and Districts, very similar to the Decomposition by Geography report above. In addition, it no longer lists Groups without any geographical references, which is most or all Groups in many cases.

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

Synchronisation report

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

A minimum XoomXML file containing everything that needs to be deployed to move from original to modified configuration. This XoomXML file will not contain any items that are only in original or are the same in both files.
An SXP file that, when executed, deletes all the items that are in original but not in modified. 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 XoomXML files, 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 the uniform representational structure of the Scheme.

Diagnostic Snapshot and Xoom Corpus Generator

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

Diagnostic Snapshot forms 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 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 corpora for potential Xoom customers without their needing to install Xoom first.

Licensing

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

Installer

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 upgrades much more palatable in production systems.

Detection of inconsistent references

When multiple key-values are used to determine the referenced item during 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 transportation 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. To restore the behaviour as it was in previous versions of Xoom, change the value of the parameter to true: the reference will be ‘good’ and the optional key-values will be recreated during deployment, consistent with the targeted item.

Table 3. Xoom parameters: Should Correct Mismatched References
Parameter	Description	Takes values	Default	Xoom release
`Xoom.DataProcessing.ShouldCorrectMismatchedReferences`	Determines whether Xoom should correct mismatched references in cases where required key-values are consistent but optional key-values are inconsistent.	`true/false`	`false`	3.7

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 Reference 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 a transformation. This is very useful when developing and testing a new transformation, because the file can be changed and used to transform the XoomXML file again without having to reopen the tool and reload 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 configuration 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 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.

Bug fixes

Fixed: scheduling workflow BGO steps in Active Schedule Agents report 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.