XML files structure
There are two files that define the merge-related functionality:
merge_odata_description.xml
menu_description.xml
To edit an existing merge field, you only need to customize the merge_odata_description.xml
file. To add a completely new merge field, you need to customize both files.
You can define the following:
- Merge fields and their order on the Insert merge field tab of the WorkZone pane in Word. See About merge fields.
- Titles and placeholders of the merge fields
- Merge functionality
Merge_odata_description.xml
This file describes data that is used for merging merge fields and values from the database. Merge of multiple entities is not supported, so make sure that you only select single items in your queries. To edit the file, you must have knowledge about OData.
Elements and attributes:
property
– establishes mappingatom:content -> metadata:properties
.internal
– attribute for internal usage only. You can use it to display or hide a merge field in menu on UI. If the value isfalse
, then merge field is displayed. If the value istrue
, then merge field is hidden.
-
link
– establishes mapping toatom:link
. Onlyatom:link
withtype=entry
is supported. The structure oflink
is the same as the structure ofstaticData
. This element is optional.query
– relative OData request that contains any allowed OData system query options. The only exceptions areselect
andexpand
options that are built based on theproperty
andlink
elements.addressContext
– defines which rule must be applied to handle protected addresses locally and from Merge API. Available values foraddressContext
are the following: CaseOfficer, CaseResponsibleUnit, RecordOfficer, RecordResponsibleUnit, RecordParty, CaseParty.
dynamicData
– builds merge field menus with items based on queries.key
– use together with thequery
attribute to create an OData query. The value ofkey
is used as an ID of a menu item.additionalKey
– use additionally tokey
if OData entities have complex ID.value
– use together with thequery
attribute to create an OData query. The value ofvalue
is used as a label of a menu item.
staticData
– builds merge field menus with items based on static properties. The element reflects the OData atom payload for a specific entity.See also Naming conventions and Atom format.
href
– mapping toatom:link
.query
– relative OData request that contains any allowed OData system query options.group
– groups related data for the repeating content, for example, Information or Dates in the Contact menu.addressContext
– defines which rule must be applied to handle protected addresses locally and from Merge API. Available values foraddressContext
are the following: CaseOfficer, CaseResponsibleUnit, RecordOfficer, RecordResponsibleUnit, RecordParty, CaseParty.
linkTemplate
– child element of thestaticData
element and also reflects the OData atom payload for a specific entity. This element is only used for ID 81E576F0-FFAA-4229-8B46-2BEC4972B474 (Record staticData) and has an additional attribute.href
– mapping toatom:link
.queryForLocalData
– describes OData query based on 'local' Record data. The attribute refers to run-time dependency {record.<SOM field name>}.
Run-time dependencies
During the merge, all run-time dependencies will be replaced with the correspondent values. All dependencies are wrapped in '{}'. There are 4 types of dependencies:
{recordId}
– ID of the document that a user merges.{addressId}
– ID of an address that belongs to the corresponding case or document party.{guid}
– reference to adynamicData
ID orproperty
ID inmerge_odata_description.xml
.{record.<SOM field name>}
– where '<SOM field name>' is a direct document field name. This dependency was created for the scenarios when a document is not yet saved on a server.
Menu_description.xml
This file describes the UI elements. Use the file to make a new merge field available to users in Microsoft Word.
There are three main sections in the file:
- Menus – customizes structure of menus, supertips, and screentips.
- Labels – overrides the default menu item names and merge field titles.
- Content controls – customizes merge fields.
Menus
Elements and attributes:
menu
– describes the static menu. You can create menu items by addingdynamicMenu
elements. If you want to create a new sub-menu, you need to add anothermenu
element within this element.displayName
– defines a menu name in Word.supertip
andscreentip
– display additional information when users move the mouse over the menu.dynamicMenu
– adds menu items based on data frommerge_odata_description.xml
.contentRefs
– a reference to the entries inmerge_odata_description.xml
.repeatable
– identifies item in menu that must be used to repeat merge field. When repeat section is used around the merge field, the menu item withrepeatable="true"
is used.
Labels
Elements and attributes:
label
– overrides the default menu item label for a specific property that is defined inmerge_odata_description.xml
.dataItemRef
– specifies the reference to the property of an entry.
value
– specifies a language-specific label. It will also be used as a merge field placeholder.format
– use this to format avalue
(optionally).
Content controls
Elements and attributes:
NoEntityRules
– defines the behavior, if a user clicks Merge, but no value exists for this merge field.<Rule rule="Unchanged">
– add merge field into this element, if you want to display this merge field in the user interface with no changes.<Rule rule="Empty">
– add merge field into this element, if you want to hide this merge field from the user interface.menuDataRefs
– specifies a reference to astaticData
andlink
in themerge_odata_description.xml
file.
cc
– defines which information to include in the merge field title.dynamicMenuRef
– specifies the name of a sub-menu or a menu item for which you want to apply this title.titleFormat
– specifies the merge field title.{displayName}
– displays the name of the menu item that a user has clicked.
holderFormat
– optionally, specify the merge field placeholder.