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:

<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>
XML

An equivalent using JSON:

{
 ...
  "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"
}
JS

multipart/form-data

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

....
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>
.....
CODE

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 by using 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 Tables web 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 Tables web 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

ResultFormat

ResultFormat

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 Configuration is 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
....
    <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>
....
XML

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