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 mapping atom: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 is false, then merge field is displayed. If the value is true, then merge field is hidden.

  • 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 merge field 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 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 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 merge field 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 merge field titles.
  3. Content controls – customizes merge fields.

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 merge field. When repeat section is used around the merge field, 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 merge field placeholder.
    • format – use this to format a value (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 a staticData and link in the merge_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.