Specifying Parameters

Format

XML / JSON

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

XML

<ConcurrentMerge>
  ...
  	<Configuration>
        <WordByWord>true</WordByWord>
        <ElementSplitting>true</ElementSplitting>
        <CalsTableProcessing>true</CalsTableProcessing>
        <HtmlTableProcessing>true</HtmlTableProcessing>
        <Indent>false</Indent>
        <RuleConfiguration>
            <DisplaySimpleAdds>false</DisplaySimpleAdds>
            <DisplaySimpleDeletes>false</DisplaySimpleDeletes>
            <DisplaySimpleModify>false</DisplaySimpleModify>
            <DisplayChangesInvolving>
            	<VersionIdentifier>ben</VersionIdentifier>	
            </DisplayChangesInvolving>
        </RuleConfiguration>
        <FormattingElementsConfiguration enabled="true">
		  <AddFormattingElements>
		    <AddElement>b</AddElement>
		    <AddElement>i</AddElement>
		  </AddFormattingElements>
		  <RemoveFormattingElements>
		    <RemoveElement>cite</RemoveElement>
		  </RemoveFormattingElements>
		</FormattingElementsConfiguration>
        <DoctypePreservationMode>PRESERVE_WHEN_UNCHANGED</DoctypePreservationMode>
        <EntityReferencePreservationMode>PRESERVE_REFERENCES</EntityReferencePreservationMode>
        <CalsValidationLevel>RELAXED</CalsValidationLevel>
        <InvalidCalsTableBehaviour>PROPAGATE_UP</InvalidCalsTableBehaviour>
        <WarningReportMode>PROCESSING_INSTRUCTIONS</WarningReportMode>
  	</Configuration>
</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"
      ]
    },
    "FormattingElementsConfiguration": {
	  "enabled": "true",
      "AddFormattingElements": [
    	"b",
    	"i"
	  ],
      "RemoveFormattingElements": [
      	"cite"
      ]
	}
  },
  "ResultType": "RULE_PROCESSED_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>

Content-Disposition: form-data; name="FormattingElementsConfiguration"
<FormattingElementsConfiguration enabled="true">
	<AddFormattingElements>
		<AddElement>b</AddElement>
		<AddElement>i</AddElement>
	</AddFormattingElements>
	<RemoveFormattingElements>
	    <RemoveElement>cite</RemoveElement>
	</RemoveFormattingElements>
</FormattingElementsConfiguration>
.....

The exceptions are RuleConfiguration and FormattingElementsConfiguration which are complex objects and would require setting lots of separate parameters, so to make it easier they 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 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 page.
Indent	boolean	false	Boolean controlling whether to indent the result of the merge.
FormattingOutputType	FormattingOutputType	DELTA_V_2_1	Enum specifying the output used to represent changes to formatting elements.
FormatExtractionPriorityList	List<String>	N/A	List of Strings corresponding to the order of versions used to extract formatting elements.
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.

Merge Type Specific Parameters

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

Parameter	Type	Default Value	Description	Compatibility
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 used with three-to-two merge specifying whether the output will be our standard XML Delta, use Oxygen Track Changes instructions, or mark changes using DITA specific `rev` and `status` attributes.	Three Way Merge
ThreeToTwoResultPreset	ThreeToTwoResultPreset	N/A	Enum used with three-to-two merge to preset rule processing for different types of changes.	Three Way Merge

Rule Configuration

Rule Configuration is available through Concurrent and Three Way Merge.

In the REST service we have RuleConfiguration which is analogous to the underlying RuleConfiguration Java object.

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

Formatting Elements

In REST configuration there is a FormattingElementsConfiguration object analogous to the FormattingElementsConfiguration Java object.

It contains an elements for interacting with the set of elements considered for formatting elements handling. There is also an attribute enabled used to enable this functionality, this is useful for just enabling formatting elements handling and using the default set.

Parameter	Type	Description
AddFormattingElements	Set<String>	Set of Strings, each specified under an "AddElement" element. The elements you specify will be added to the default set.
RemoveFormattingElements	Set<String>	Set of Strings, each specified under a "RemoveElement" element. The elements you specify will be removed from the default set (if present).
SetFormattingElements	Set<String>	Set of Strings, each specified under a "SetElement" element. This will override the default set.
enabled default: false	boolean	Note: this is an attribute, instead of an element. Necessary to enable the formatting elements handling feature.

For example:

Request Excerpt (XML)

XML

...
<Configuration>
  ...
  <FormattingElementsConfiguration enabled="true">
    <AddFormattingElements>
      <AddElement>phonenumber</AddElement>
    </AddFormattingElements>
  </FormattingElementsConfiguration>
  ...
</Configuration>
...

Request Excerpt (JSON)

JS

...
"Configuration" : {
  ...
  "FormattingElementsConfiguration" : {
    "enabled" : true,
    "AddFormattingElements" : ["phonenumber"]
  }
  ...
}
...

For simplicity, there is an additional multipart/form-data boolean parameter EnableFormattingElements. This is useful for if you just want to enable formatting elements handling, without interacting with the set of formatting elements.

Result Type

This is treated as a separate case, and is specified outside of Configuration. 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`	ConcurrentMergeResultType
Sequential Merge	`ANALYZED_DELTAV2` `DELTAV2` `SIMPLIFIED_DELTAV2`	SequentialMergeResultType
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`	ThreeWayMergeResultType

Catalog

If you wish to use additional catalogs that are searched before the in-built catalog you need to supply the location(s) using the Catalog parameter

Parameter

Type

Default Value

Description

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.

Catalog Example

XML

....
    <Configuration>
      	...
		<Catalog type="file"><Path>/usr/loca/example/catalog.xml</Path></Catalog>
    </Configuration>
....