XML files structure

There are two files that define the Merge-related functionality:

  1. merge_odata_description.xml
  2. 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 mapping atom: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 is false, then content control is displayed. If the value is true, then content control is hided.

  • link – establishes mapping to atom:link. Only atom:link with type=entry is supported. The structure of link is the same as the structure of staticData. This element is optional.

    • query – relative OData request that contains any allowed OData system query options. The only exceptions are select and expand options that are built based on the property and link elements.
    • addressContext – defines which rule must be applied to handle protected addresses locally and from Merge API. Available values for addressContextare the following: CaseOfficer, CaseResponsibleUnit, RecordOfficer, RecordResponsibleUnit, RecordParty, CaseParty.
  • dynamicData – builds content control menus with items based on queries.
    • key – use together with the query attribute to create an OData query. The value of key is used as an ID of a menu item.
    • additionalKey – use additionally to key if OData entities have complex ID.
    • value – use together with the query attribute to create an OData query. The value of value 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 to atom: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 for addressContextare the following: CaseOfficer, CaseResponsibleUnit, RecordOfficer, RecordResponsibleUnit, RecordParty, CaseParty.
  • linkTemplate – child element of the staticData 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 to atom: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:

  1. {recordId} – ID of the document that a user merges.
  2. {addressId} – ID of an address that belongs to the corresponding case or document party.
  3. {guid} – reference to a dynamicData ID or property ID in merge_odata_description.xml.
  4. {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:

  1. Menus – customizes structure of menus, supertips, and screentips.
  2. Labels – overrides the default menu item names and content control titles.
  3. Content controls – customizes content controls.

Menus

Elements and attributes:

  • menu – describes the static menu. You can create menu items by adding dynamicMenu elements. If you want to create a new sub-menu, you need to add another menu element within this element.
  • displayName – defines a menu name in Word.
  • supertip and screentip – display additional information when users move the mouse over the menu.
  • dynamicMenu – adds menu items based on data from merge_odata_description.xml.
    • contentRefs – a reference to the entries in merge_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 with repeatable="true" is used.

Labels

Elements and attributes:

  • label – overrides the default menu item label for a specific property that is defined in merge_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 a value (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 a staticData and link in the merge_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.