Specifying Parameters

Format

XML / JSON

As part of a request, use the element/object ConfigurationParameters beneath which the various parameters will be set. For example, using Concurrent Merge:

XML

<ConcurrentMerge>
  ...
  <Configuration>
    <WordByWord>true</WordByWord>
    <DoctypePreservationMode>PRESERVE_WHEN_UNCHANGED</DoctypePreservationMode>
    <EntityReferencePreservationMode>PRESERVE_REFERENCES</EntityReferencePreservationMode>
    <ElementSplitting>true</ElementSplitting>
    <CalsTableProcessing>true</CalsTableProcessing>
    <CalsValidationLevel>RELAXED</CalsValidationLevel>
    <HtmlTableProcessing>true</HtmlTableProcessing>
    <InvalidCalsTableBehaviour>PROPAGATE_UP</InvalidCalsTableBehaviour>
    <Indent>false</Indent>
    <WarningReportMode>PROCESSING_INSTRUCTIONS</WarningReportMode>
    <RuleConfiguration>
      <DisplaySimpleAdds>false</DisplaySimpleAdds>
      <DisplaySimpleDeletes>false</DisplaySimpleDeletes>
      <DisplaySimpleModify>false</DisplaySimpleModify>
      <DisplayChangesTo>//*</DisplayChangesTo>
      <VersionPriorityList>
        <VersionPriority>chris</VersionPriority>
        <VersionPriority>ben</VersionPriority>
      </VersionPriorityList>
      <DisplayChangesInvolving>
        <VersionIdentifier>chris</VersionIdentifier>
        <VersionIdentifier>ben</VersionIdentifier>
      </DisplayChangesInvolving>
    </RuleConfiguration>
  </Configuration>
  <ResultType>DELTAV2</ResultType>
</ConcurrentMerge>

An equivalent using JSON:

JS

{
 ...
  "Configuration": {
    "WordByWord": true,
    "DoctypePreservationMode": "PRESERVE_WHEN_UNCHANGED",
    "EntityReferencePreservationMode": "PRESERVE_REFERENCES",
    "ElementSplitting": true,
    "CalsTableProcessing": true,
    "CalsValidationLevel": "RELAXED",
    "HtmlTableProcessing": true,
    "InvalidCalsTableBehaviour": "PROPAGATE_UP",
    "Indent": false,
    "WarningReportMode": "PROCESSING_INSTRUCTIONS",
    "RuleConfiguration": {
      "DisplaySimpleAdds": false,
      "DisplaySimpleDeletes": false,
      "DisplaySimpleModify": false,
      "DisplayChangesInvolving": [
        "chris",
        "ben"
      ],
      "DisplayChangesTo": "//*",
      "VersionPriorityList": [
        "chris",
        "ben"
      ]
    }
  },
  "ResultType": "DELTAV2"
}

multipart/form-data

When using multipart/form-data to make requests, specify each parameter separately:

CODE

....
Content-Disposition: form-data; name="WordByWord"
true

Content-Disposition: form-data; name="DoctypePreservationMode"
PRESERVE_WHEN_UNCHANGED

Content-Disposition: form-data; name="WarningReportMode"
PROCESSING_INSTRUCTIONS

Content-Disposition: form-data; name="RuleConfiguration"
<RuleConfiguration>
      <DisplaySimpleAdds>false</DisplaySimpleAdds>
      <DisplaySimpleDeletes>false</DisplaySimpleDeletes>
      <DisplaySimpleModify>false</DisplaySimpleModify>
      <DisplayChangesTo>//*</DisplayChangesTo>
      <VersionPriorityList>
         <Version>chris</Version>
         <Version>ben</Version>
      </VersionPriorityList>
      <DisplayChangesInvolving>
         <VersionIdentifier>chris</VersionIdentifier>
         <VersionIdentifier>ben</VersionIdentifier>
      </DisplayChangesInvolving>
</RuleConfiguration>
.....

The only exception is RuleConfiguration which is a complex object and would require setting lots of separate parameters, so to make it easier it can be set byusing formatted XML or JSON.

Parameters

General Parameters

There are various configuration parameters available to all merge types:

Parameter	Type	Default Value	Description
WordByWord	boolean	true	Controls the granularity of text/PCDATA comparison, alignment and change reporting.
Catalog	IO	N/A	A Catalog file for resolving external entities used in the inputs. Can be specified as a URI, file path, or raw XML file.
DoctypePreservationMode	DoctypePreservationMode	PRESERVE_WHEN_UNCHANGED	An enum which controls how DOCTYPE declarations appear in the result
EntityReferencePreservationMode	EntityReferencePreservationMode	PRESERVE_REFERENCES	An enum which controls how general entity references appear in the result.
CalsTableProcessing	boolean	true	If the inputs contain CALS tables then setting this to true will cause XML Merge to detect them and invoke specific CALS Table processing. It should provide a better representation of the changes. See the Merging Tablesweb page.
InvalidCalsTableBehaviour	InvalidCalsTableBehaviour	PROPAGATE_UP	Enum specifying how to handle invalid CALS tables.
CalsValidationLevel	ValidationLevel	RELAXED	Some validation errors in the input are known to cause no issue with the CALS processing and so using a level of RELAXED would not prevent processing from running.
WarningReportMode	WarningReportMode	PROCESSING_INSTRUCTIONS	Enum specifying how to handle warnings when comparing CALS tables.
HtmlTableProcessing	boolean	true	If the inputs contain HTML tables then setting this to true should provide a better representation of the changes. See the Merging Tablesweb page.
Indent	boolean	false	Boolean controlling whether to indent the result of the merge.

Merge Type Specific Parameters

There are also a number of parameters specific to one or more merge types:

Parameter	Type	Default Value	Description	Compatibility
ElementSplitting	boolean	true	Boolean controlling whether elements that contain a lot of changes are shown as a single element with the changes shown inside it, or whether it is split into a set of sibling elements one for each version. Splitting can create more readable results.	Three Way Merge Concurrent Merge Sequential Merge
ExistingOxygenTCsProcessingMode	ExistingOxygenTCsProcessingMode	ACCEPT	Enum that controls how existing Oxygen Track Changes processing instructions will be handled.	Three Way Merge
RuleConfiguration	RuleConfiguration	N/A	When XML Merge has been set to use Rules to resolve conflicts between the inputs (see ResultType) this determines how the rules are applied.	Three Way Merge Concurrent Merge
TwoWayResultFormat	TwoWayResultFormat	XML_DELTA	Enum specifying whether the output will be our standard XML Delta or contain Oxygen Track Changes instructions.	Three Way Merge

Rule Configuration

Rule Configurationis available through Concurrent and Three Way Merge. In XML Merge there is a RuleConfiguration Java object.

In the REST service we have RuleConfiguration which is analogous to the underlying RuleConfiguration in XML Merge.

It contains its own parameters:

Parameter	Type	Default Value	Description
DisplaySimpleAdds	boolean	false	Boolean controlling whether "simple additions" are displayed.
DisplaySimpleDeletes	boolean	false	Boolean controlling whether "simple deletions" are displayed.
DisplaySimpleModify	boolean	false	Boolean controlling whether "simple modifications" are displayed.
VersionPrioritiyList	List of Strings	N/A	Specifies the priority version list for resolving simple conflicts. The ancestor should not be included in this list.
DisplayChangesInvolving	Set of Strings	N/A	Specifies the set of versions for which all changes should be displayed.
DisplayChangesTo	String	N/A	Specifies which elements in the result are always displayed to the user. Alternatively these are nodes which are never simplified by rule-based processing.

For example:

Request Excerpt

XML

....
    <RuleConfiguration>
      <DisplaySimpleAdds>false</DisplaySimpleAdds>
      <DisplaySimpleDeletes>false</DisplaySimpleDeletes>
      <DisplaySimpleModify>false</DisplaySimpleModify>
      <DisplayChangesTo>//*</DisplayChangesTo>
      <VersionPriorityList>
        <VersionPriority>chris</VersionPriority>
        <VersionPriority>ben</VersionPriority>
        <VersionPriority>anna</VersionPriority>
      </VersionPriorityList>
      <DisplayChangesInvolving>
        <VersionIdentifier>chris</VersionIdentifier>
        <VersionIdentifier>ben</VersionIdentifier>
      </DisplayChangesInvolving>
    </RuleConfiguration>
....

Result Type

This is treated as a separate case, and is specified outside of configurationParameters. This is due to each merge type using its own underlying result type enumeration.

Merge Type	Values (Default in Bold)	Underlying Type
Concurrent Merge	`ANALYZED_DELTAV2` `DELTAV2` `RULE_PROCESSED_DELTAV2` `SIMPLIFIED_DELTAV2` `SIMPLIFIED_RULE_PROCESSED_DELTAV2`	ConcurrentMerge.MergeResultType
Sequential Merge	`ANALYZED_DELTAV2` `DELTAV2` `SIMPLIFIED_DELTAV2`	SequentialMerge.MergeResultType
Three Way Merge	`ANALYZED_DELTAV2` `DELTAV2` `RULE_PROCESSED_DELTAV2` `RULE_PROCESSED_TWO_WAY_RESULT` `SIMPLIFIED_DELTAV2` `SIMPLIFIED_RULE_PROCESSED_DELTAV2` `THREE_WAY_OXYGEN_TRACK_CHANGES` `TWO_WAY_RESULT`	ThreeWayMerge.ThreeWayMergeResultType