About merge fields configuration

About merge fields

Merge fields help WorkZone users create templates in Microsoft Word. From a WorkZone point of view, a merge field represents a specific property of an entry. An entry is an object in OData that refers to the WorkZone database. Entries in OData are used to retrieve specific values from the database.

When creating a template, the user fills in mandatory fields on the Document tab of the WorkZone pane in Microsoft Word, clicks Merge fields, and adds the needed merge fields by selecting relevant menu items from the Insert merge field tab. Once the user clicks Merge, WorkZone will replace each inserted merge field with relevant values from the WorkZone database.

You can create sub-menus and define which menu items would be displayed in each merge fields category. Available merge fields are divided into 4 categories:

• Document
• Case
• Document contact
• Case contact

Merge fields configuration files

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 the merge_odata_description.xml and menu_description.xml files.

You can define the following:

• Merge fields and their order on the Insert merge field tab of the WorkZone pane in Word.
• 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.

Menu_description.xml

This file describes the UI elements. Use it to make a new merge field available to your WorkZone users in Microsoft Word.

There are three main sections in the file:

1. Menus: Customize structure of menus, supertips, and screentips.
2. Labels: Override the default menu item names and merge field titles.
3. Content controls: Customize the merge fields.

Create a merge field

For example, you want to create a new merge field called Entity updated overrided that will represent the Entity updated property of the MruRecords entry. To create such merge field, you need to create a reference to the database through OData and add a new menu item that will appear in Word.

1. Open the merge_odata_description XML file. To request a specific entry, create a query to OData. Use the following example:
   Copy

   <staticData id="E34FE056-129F-46D2-B7E7-A20D91F9F47C" query="MruRecords?$filter=Value eq 
               '{recordId}' and User_Value eq '{record.officer}'">

where:

• staticData: use this element to request an entry.
• E34FE056-129F-46D2-B7E7-A20D91F9F47C: insert a unique ID that will be used internally as a reference to the OData entry.

You may use any unique ID, however, it is recommended to use a GUID generator to generate the ID.

• query: an OData request that retrieves the entry that you need. In this example, it is a call to the MruRecords entry.
2. Within the staticData element, bind a merge field with the required property. To do this, you need to add and define the property element.

   You may add as many properties as you need.

   Copy

   <staticData id="E34FE056-129F-46D2-B7E7-A20D91F9F47C" query="MruRecords?$filter=Value eq 
                           '{recordId}' and User_Value eq '{record.officer}'">
                           <property id="C5D4237E-2DEF-4D5A-B714-1F5CA88518F5" name="EntityUpdated " />
               </staticData>

where:

• property: use this element to request a property.
• E34FE056-129F-46D2-B7E7-A20D91F9F47C: insert a unique ID that will be used internally as a reference to the property of the entry.
• name: specify property's name in OData.=
3. Add a new menu item to the Word application. You can do this in the menu_description XML file. Open the file and find a proper place for the new menu item. The current example represents how to search for the Document category.
Expand to find a proper category for your menu item:
• <menu id="Case"> refers to Case.
• <menu id="Record"> refers to Document.
• <menu id="CaseParty"> refers to Case contacts.
• <menu id="RecordParty"> refers to Document contacts.

In the code source, the Document category refers to Record. Therefore, the new sub-menu must be added under the <menu id="Record"> element:

Copy

<menu id="Mru">
                    <displayName xml:lang="en-GB">Mru test</displayName>
                    <displayName xml:lang="da-DK">Mru test</displayName>
                    <dynamicMenu id="Mru_Items">
                    <contentRefs>
                    <ref>E34FE056-129F-46D2-B7E7-A20D91F9F47C</ref>
                    </contentRefs>
                    </dynamicMenu>
                </menu>;

where:

• menu: use this element to create a sub-menu.
• displayName: define a menu name to be displayed in Word.
• dynamicMenu: use this element to create new menu items.
• ref : specify reference to the unique ID in the merge_odata_description XML file.
4. Optionally, define customized labels (names) for the new menu item and merge field:
   Copy

   <label dataItemRef="C5D4237E-2DEF-4D5A-B714-1F5CA88518F5">        
                           <value xml:lang="en-GB">Entity updated overrided</value>
                           <value xml:lang="da-DK">Entity updated overrided</value>
               </label>

   where:

   • label: specifies a customized name.
   • dataItemRef: specifies a reference to the property of the entry from the merge_odata_description XML file.
   • xml:lang: is a localization parameter.
5. You can define how the merge field must behave in Word when there is no value. There are two options:
   • Display merge field with no changes. To do so, specify the unique ID of the entry within the <Rule rule="Unchanged"> section.
     Copy

     <Rule rule="Unchanged">
                                     <menuDataRefs>
                                     <ref>E34FE056-129F-46D2-B7E7-A20D91F9F47C</ref>    
                                     </menuDataRefs>
                         </Rule>

   • Hide the merge field. To do so, specify the unique ID of the entry within the <Rule rule="Empty"> section.
     Copy

     <Rule rule="Empty">
                                     <menuDataRefs>
                                     <ref>17EDE3E5-43D3-4B88-8E6E-F336D916B916</ref>    
                                     </menuDataRefs>
                 </Rule>

where:

• ref: is a reference to the unique ID in the merge_odata_description XML file.

6. Optionally, you can define which information should be included in the merge field title.

   Copy

   <cc dynamicMenuRef="Mru_Items">
                           <titleFormat xml:lang="en-GB">(Document, Mru) {displayName}</titleFormat>
                           <titleFormat xml:lang="da-DK">(Document, Mru) {displayName}</titleFormat>
                       </cc>

   where:

   • dynamicMenuRef: specifies a reference to a menu item.
   • TitleFormat: defines the merge field title for each language.
   • {displayName}: displays the name of the menu item that a user can click.