Specifying Parameters

 Table of Contents

1. Format

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

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

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

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

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.

2. Parameters

2.1. General Parameters

There are various configuration parameters available to all merge types:

ParameterTypeDefault ValueDescription
WordByWordbooleantrueControls the granularity of text/PCDATA comparison, alignment and change reporting.
CatalogION/A

A Catalog file for resolving external entities used in the inputs.

Can be specified as a URI, file path, or raw XML file.

DoctypePreservationModeDoctypePreservationModePRESERVE_WHEN_UNCHANGEDAn enum which controls how DOCTYPE declarations appear in the result
EntityReferencePreservationModeEntityReferencePreservationModePRESERVE_REFERENCESAn enum which controls how general entity references appear in the result.
CalsTableProcessingbooleantrue

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.

InvalidCalsTableBehaviourInvalidCalsTableBehaviourPROPAGATE_UPEnum specifying how to handle invalid CALS tables.
CalsValidationLevelValidationLevelRELAXEDSome 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.
WarningReportModeWarningReportModePROCESSING_INSTRUCTIONSEnum specifying how to handle warnings when comparing CALS tables.
HtmlTableProcessingbooleantrue

If the inputs contain HTML tables then setting this to true should provide a better representation of the changes.

See the Merging Tables page.

IndentbooleanfalseBoolean controlling whether to indent the result of the merge.
FormattingOutputTypeFormattingOutputTypeDELTA_V_2_1

Enum specifying the output used to represent changes to formatting elements.

FormatExtractionPriorityListList<String>N/A

List of Strings corresponding to the order of versions used to extract formatting elements.

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

2.2. Merge Type Specific Parameters

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

ParameterTypeDefault ValueDescriptionCompatibility
ExistingOxygenTCsProcessingModeExistingOxygenTCsProcessingModeACCEPTEnum that controls how existing Oxygen Track Changes processing instructions will be handled.Three Way Merge
RuleConfigurationRuleConfigurationN/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

ResultFormatResultFormatXML_DELTAEnum 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
ThreeWayResultPresetThreeWayResultPresetN/AEnum used with three-to-two merge to preset rule processing for different types of changes.Three Way Merge

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

ParameterTypeDefault ValueDescription
DisplaySimpleAddsbooleanfalseBoolean controlling whether "simple additions" are displayed.
DisplaySimpleDeletesbooleanfalseBoolean controlling whether "simple deletions" are displayed.
DisplaySimpleModifybooleanfalseBoolean controlling whether "simple modifications" are displayed.
VersionPrioritiyListList of StringsN/ASpecifies the priority version list for resolving simple conflicts. The ancestor should not be included in this list.
DisplayChangesInvolvingSet of StringsN/ASpecifies the set of versions for which all changes should be displayed.
DisplayChangesToStringN/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>
....

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

ParameterTypeDescription

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)
...
<Configuration>
  ...
  <FormattingElementsConfiguration enabled="true">
    <AddFormattingElements>
      <AddElement>phonenumber</AddElement>
    </AddFormattingElements>
  </FormattingElementsConfiguration>
  ...
</Configuration>
...
Request Excerpt (JSON)
...
"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.

2.5. 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 TypeValues (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

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

ParameterTypeDefault ValueDescription
CatalogION/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
....
    <Configuration>
      	...
		<Catalog type="file"><Path>/usr/loca/example/catalog.xml</Path></Catalog>
    </Configuration>
....



#content .code