XML files structure
There are two files that define the Merge-related functionality:
merge_odata_description.xml
menu_description.xml
If you want to edit an existing content control, you only need to customize the merge_odata_description.xml
file. To add a completely new content control, you need to customize both files.
You can define the following:
- Content controls and their order in the menus in Word. See About content controls.
- Titles and placeholders of the content controls
- Merge functionality
merge_odata_description.xml
This file describes data that is used for merging content controls 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 content control in menu on UI. If the value isfalse
, then content control is displayed. If the value istrue
, then content control is hided.
-
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 content control 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 content control 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 content control 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 content control titles.
- Content controls – customizes content controls.
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 content control. When repeat section is used around the content control, 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 content control placeholder.format
– use this to format avalue
(optionally).
Content controls
Elements and attributes:
NoEntityRules
– defines the behavior of a content control if a user clicks Merge, but no value exists for the content control.<Rule rule="Unchanged">
– adds the content control into this element if you want to remain the content control in the user interface without changes.<Rule rule="Empty">
– adds the content control into this element if you want to hide the content control 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 content control title.dynamicMenuRef
– specifies the name of a sub-menu or a menu item for which you want to apply this title.titleFormat
– specifies the content control title.{displayName}
– displays the name of the menu item that a user has clicked.
holderFormat
– optionally, specify the content control placeholder.