Skip to main content
Skip table of contents

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

ResultFormat

ResultFormat

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


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.