M-FILES CORPORATION

CONFIGURING THE METADATA CARD

(M-FILES 2015.3)
LAST UPDATED JANUARY 27, 2017

VERSION 2.1
Abstract

This document provides the instructions for modifying the behavior of the metadata card with the JSON-based
metadata configuration editor. The editor allows you, among other things, to add an additional header to the metadata
card for a specific object type or class, assign set values for properties, add tooltip texts and description texts for
individual properties, create collapsible property groups, and control the order in which properties are displayed on the
metadata card.

The document contains an overview of the editor and the instructions for using it, as well as concrete examples of how
you can apply metadata card configurations with the editor.

Keywords: metadata card, configuration, metadata

Contents
1. Introduction ........................................................................................................................................................................ 5

1.1 Prerequisites ............................................................................................................................................................. 6

1.1.1 M-Files Software Requirements ...................................................................................................................... 6

1.1.2 Other Requirements ........................................................................................................................................ 6

2. JSON Syntax ........................................................................................................................................................................ 6

3. Using the Metadata Card Editor ......................................................................................................................................... 7

3.1 Opening the Metadata Card Editor ........................................................................................................................... 7

3.2 Editor Overview ........................................................................................................................................................ 7

3.2.1 Adding a New Rule ........................................................................................................................................... 8

3.2.2 Adding a New Subordinate Rule ...................................................................................................................... 9

3.2.3 Discarding Changes or Deleting an Existing Rule ............................................................................................. 9

3.2.4 Changing the Evaluation Order of the Rules .................................................................................................... 9

3.3 Assigning Aliases for Metadata Elements and Determining GUIDs and IDs ........................................................... 10

3.3.1 Assigning Aliases for Metadata Elements ...................................................................................................... 10

3.3.2 Determining Metadata Element GUIDs ......................................................................................................... 11

3.3.3 Determining Object GUIDs............................................................................................................................. 11

3.3.4 Determining Metadata Element IDs .............................................................................................................. 12

3.4 Rule Conditions ....................................................................................................................................................... 12

3.4.1 No Condition .................................................................................................................................................. 12

3.4.2 Class-Based Conditions .................................................................................................................................. 13

3.4.3 Object Type Based Conditions ....................................................................................................................... 13

3.4.4 Property-Based Conditions ............................................................................................................................ 13

3.4.5 Combining Conditions.................................................................................................................................... 15

3.5 Rule Behaviors ........................................................................................................................................................ 15

3.5.1 Rule Behavior Definitions for Properties ....................................................................................................... 16

3.5.2 Rule Behavior Definitions for Property Groups ............................................................................................. 19

3.5.3 Rule Behavior Definitions for the Metadata Card.......................................................................................... 19

3.5.4 Rule Behavior Definitions for Value List Items ............................................................................................... 20

3.5.5 Rule Behavior Definitions for Defining Custom Placeholders for Set Values ................................................. 20

4. Metadata Card Configurations.......................................................................................................................................... 21

4.1 Adding an Additional Header to the Metadata Card .............................................................................................. 21

 4.2 Modifying the Appearance of the Metadata Card Elements .................................................................................. 24

4.3 Adding Tooltips and Description Fields for Individual Properties ........................................................................... 25

4.4 Adding Tooltips for Value List Items ....................................................................................................................... 26

4.5 Replacing Property Names with Labels ................................................................................................................... 27

4.6 Creating Collapsible Property Groups ..................................................................................................................... 28

4.7 Controlling the Order of Properties and Property Groups on the Metadata Card ................................................. 29

4.8 Assigning Set Values for Properties ........................................................................................................................ 30

4.8.1 Determining the Data Types of Properties .................................................................................................... 31

4.9 Using Placeholders and Custom Placeholders in Set Values ................................................................................... 32

4.10 Assigning Set Dates and Times for Properties ........................................................................................................ 35

4.11 Managing Automatically Added Properties ............................................................................................................ 37

4.12 Hiding Properties from the Metadata Card ............................................................................................................ 37

4.13 Using Alternative User Interface Controls for Selecting Property Values ............................................................... 38

4.14 Adding Localized Strings ......................................................................................................................................... 40

5. Troubleshooting ................................................................................................................................................................ 41

6. Change History .................................................................................................................................................................. 42

7. Reference Documents ...................................................................................................................................................... 42

Appendix A: M-Files Language Codes........................................................................................................................................ 43

Appendix B: Behavior of the SetValue Definition ...................................................................................................................... 44

SetValue Behavior when Creating a New Object .................................................................................................................. 44

SetValue Behavior for Existing Objects ................................................................................................................................. 44

SetValue and Placeholders .................................................................................................................................................... 44

1. Introduction

This document provides instructions for modifying the behavior of the metadata card with the JSON-based metadata
configuration editor in M-Files Admin. The editor allows you to:
 add an additional header, including text and an image, for a certain object type or a class.
 modify the appearance of the metadata card elements.
 add tooltips and description fields for individual properties.
 create collapsible property groups.
 control the order in which properties and groups are displayed on the metadata card.
 assign set values for properties.
 manage automatically added (mandatory and optional) properties based on, for instance, object type and class.
 hide properties from the metadata card.

Metadata card configurations are created by defining hierarchical rules that consist of a name, a condition (which delineates
the condition that must be fulfilled for the rule to be applied) and a behavior (which defines the configurations that are
applied once the condition is fulfilled). The figure below illustrates the anatomy of a metadata card configuration rule with
an example of each rule element in parentheses and a list of the rule building blocks: the condition types and the behavior
definitions.

Image 1: The structure of a metadata configuration rule.

These instructions guide you through the process of configuring the metadata card, and they provide a detailed description
of each rule condition type and behavior definition that are used for creating metadata card configuration rules.

Note: Metadata card configurations are applied only when the metadata card is positioned on the right-side of
the M-Files user interface. They are thus not applied when the metadata card is moved to the bottom of the M-
Files user interface.

5
1.1 Prerequisites

Please make sure your environment meets these requirements before moving forward.

1.1.1 M-Files Software Requirements

Make sure your M-Files software meets these minimum requirements:

M-FILES PRODUCT VERSION

M-Files Desktop M-Files 2015.3 or later

M-Files Server M-Files 2015.3 or later

Certain Theme definitions require version 11.3.4330.150 or newer. See chapter 3.5.3 for more information.

Certain placeholders that can be used with the SetValue definition require version 11.3.4330.151 or newer. See chapter
3.5.1 for more information.

1.1.2 Other Requirements

You must have sufficient rights to modify the metadata structure.

2. JSON Syntax

JSON (JavaScript Object Notation) is an open standard format for storing and transporting data in an attribute–value pair
syntax. Metadata card configurations in M-Files are defined using a JSON schema. A JSON structure consists of the following:
 Objects (delimited with curly brackets)
 Arrays (delimited with square brackets)
 Name–value pairs (of the format "name: value")
o Names
o Values
 String
 Integer
 Boolean (true or false)
 Object
 null (equals to an empty value)

6
 {
"Name1": {
"Name2": [
{
"Name1": 1,
"Attribute1": "Value1"
},
{
"Name2": 2,
"Attribute2": "Value2"
}
]
}
}

JSON structures always start with an object. The above example contains four JSON objects, each delimited with curly
brackets. The first object contains a nested object and the nested object contains a nested array. The array in turn contains
two additional nested objects. The difference between arrays and objects is that objects store and retrieve values by name
whereas arrays store and retrieve values by numerical index.

The first and second objects both contain only one name element, whereas the objects nested in the array consist of two
name–value pairs. Names are delimited with double quotes and a colon. Multiple pairs need to be separated with a comma.
In the metadata card editor, values may be strings (delimited with double quotes), numbers, Boolean, null, or nested
objects.

Note: Only the keys within a single JSON object have to be unique, so a nested object may use a key with the
same name as its parent object.

3. Using the Metadata Card Editor

This chapter contains basic instructions for opening and operating the user interface of the metadata card editor as well as
information on how to assign aliases for metadata elements and how to determine metadata element and object identifiers.

3.1 Opening the Metadata Card Editor

The metadata card editor is located in M-Files Admin:

1. Open M-Files Admin.
2. In the left-side tree view, expand the desired connection to M-Files Server.
3. In the left-side tree view, expand the desired document vault.
4. Still in the left-side tree view, select Metadata Card Configuration.

3.2 Editor Overview

The user interface of the editor is comprised of four parts:

 The hierarchical rules list (left)
 The rule name (top right)

7
  The rule condition (middle right)
 The rule behavior (bottom right)

The buttons below the rule list enable you to manage the content of the list.

Image 2: The metadata card editor.

The rule list is a hierarchical tree, meaning that you can add subordinate rules for further specifying parent or even ancestor
rules. For example, say you have a rule condition for the Employee class. Its behavior then applies to all the objects with the
Employee class. And say the main rule contains a subordinate rule that applies, for example, to all the objects in which the
Department property has the value Marketing. The behavior of the subordinate rule, in conjunction with that of the main
rule, would thus apply to all the objects with the Employee class and the Department property set to Marketing.

The Rule name field should contain a descriptive name for the rule. The name is visible in the rule editor only.

The Rule condition field defines the JSON-formatted condition or conditions that must be fulfilled for the rule to be applied.
You may want to, for example, add a condition that is fulfilled only if an object has a specific class.

The Rule behavior field is used for defining in JSON syntax what happens when the above-mentioned condition is met. For
instance, when the object class is Customer, you might want to add to the metadata card the property groups Contact
information, Subscription and Responsible employee.

Notice that the object names in the editor (condition and behavior definitions) are case-sensitive.

3.2.1 Adding a New Rule

1. Ensure that you don't have any existing rule selected in the Rules tree.
2. Click the (New Rule) icon on top of the Rules tree.
3. In the Rule name field, enter a name for the rule.

8
 4. In the Rule condition field, enter the JSON-formatted condition that must be fulfilled for the rule to be applied.
5. In the Rule behavior field, enter the JSON-formatted behavior definitions, which contain the metadata card
configurations that are applied if the rule condition is fulfilled.
6. Click Save on the lower right corner once you are done.

3.2.2 Adding a New Subordinate Rule

1. In the Rules tree, highlight the desired rule for which you want to add a subordinate rule.
2. Either:
a. Click the (New Rule) icon on top of the Rules tree.
or
b. Right-click the desired rule and select New Rule from the context menu.
3. In the Rule name field, enter a name for the rule.
4. In the Rule condition field, enter the JSON-formatted condition that must be fulfilled alongside its parent or
ancestor rule conditions for the rule to be applied.
5. In the Rule behavior field, enter the JSON-formatted behavior definitions, which contain the metadata card
configurations that are applied if the rule condition is fulfilled.
6. Click Save on the lower right corner once you are done.

Note: If you have conflicting rules on the same rule path, the bottommost descendant rule with a conflicting rule
always overrides similar rules defined in its ancestor rules. In other words, the more specific rule always takes
precedence over a more general one.

3.2.3 Discarding Changes or Deleting an Existing Rule

If you wish to discard any unsaved changes you have made in the editor, click the Discard button. This removes any unsaved
rules and unsaved changes you may have done to any existing rules.

If you want to delete any existing rule, do the following steps:

1. In the Rules tree, highlight the rule that you want to delete.
2. Either:
a. Click the (Delete Rule) icon on top of the Rules tree.
or
b. Right-click the desired rule and select Delete Rule from the context menu.

3.2.4 Changing the Evaluation Order of the Rules

The hierarchical rule list is evaluated from top to bottom. The higher a rule is in the list, the earlier it is evaluated. Do either
of the following to change the evaluation order of a rule:

 Right-click a rule and select Move Up to move it up in the list.

 Right-click a rule and select Move Down to move it down in the list.

9
 Note: When a rule becomes effective, it always overwrites any overlapping behaviors of rules that have
previously come into effect. In other words, a rule always overwrites any overlapping behaviors of other rules
higher up in the hierarchical rule list.

Image 3: Changing the evaluation order of the rules.

3.3 Assigning Aliases for Metadata Elements and De termining GUIDs and IDs

You need to assign aliases or determine the IDs or GUIDs for the metadata elements for which you want to create metadata
card configuration rules. It is preferable to use aliases instead of IDs for the following reasons:

 Metadata configuration rules that use aliases are more readable than those that use IDs.
 Aliases are easier to remember than IDs.
 It is easier to use the same metadata configurations rules in a replicated vault because while metadata element IDs
may change during replication, aliases retain their original reference.

3.3.1 Assigning Aliases for Metadata Elements

Do the following steps to assign an alias for a specific metadata element:

1. Open M-Files Admin.

2. In the left-side tree view, expand a desired connection and then expand a desired document vault.
3. Expand Metadata Structure (Flat View).
4. Either:
a. Select Object Types to open the Object Types list and double-click the desired object type.
or
b. Select Property Definitions to open the Property Definitions list double-click the desired property
definition.
or
c. Select Classes to open the Classes list and double-click the desired class.
5. In the properties dialog that opens, go to the Advanced tab and enter a suitable name for the alias in the Aliases
field.
6. Click OK once you are done.
7. Take note of the alias and add it to your configuration rule.

10
 Note: Aliases cannot be assigned for value list items. In metadata configuration rules, it is advisable to refer to
value list items using GUIDs instead of IDs.

3.3.2 Determining Metadata Elemen t GUIDs

In some cases, for example when referring to value list items, you may want to use GUIDs to refer to metadata elements in
your metadata card configuration rule. In order to retrieve metadata element GUIDs, you need to export your vault
metadata structure by completing the following steps:

1. Open M-Files Admin.

2. In the left-side tree view, expand a desired connection and then expand a desired document vault.
3. Select Content Replication and Archiving and click the One-time Export… button.
4. Click the Package Location tab and click the … button to set the content package location.
5. Go to the Structure tab and check the Export structure, All Elements and Export contents of the selected value lists
check boxes.
6. Click OK to start the export process.
7. Navigate to the content package location and locate the following XML files:

<content package location>\{<vault GUID>}_<export date>\Metadata\Structure.xml

<content package location>\{<vault GUID>}_<export date>\Metadata\VLI_Content<n>.xml

8. Open Structure.xml in a text editor of your choice.

a. Object types: Use the text editor search to locate the objtype element whose name attribute value
matches the name of the relevant object type, copy the value of its guid attribute and paste it to your rule.
b. Property definitions: Locate the propertydef element whose name attribute value matches the name
of the relevant property definition, copy the value of its guid attribute and paste it to your rule.
c. Classes: Use the text editor search to locate the class element whose name attribute value matches the
name of the relevant property definition, copy the value of its guid attribute and paste it to your rule.
9. Open VLI_Content<n>.xml in a text editor of your choice.
10. Use the text editor search to locate the vlitem element whose value attribute value matches the name of the
relevant value list item, copy the value of its guid attribute and paste it to your metadata card configuration rule.
11. You can close the XML files once you are done.

3.3.3 Determining Object GUIDs

When you need to refer to the GUID of metadata items in your rules, you can find the GUID by following the steps below.

1. Follow the steps from 111 to 7 presented in chapter 3.3.2.

2. Open Content<n>.xml in a text editor of your choice.
3. Use the text editor to locate the property element whose name attribute value is "Name or title" and whose
content matches the name of the object you are looking for.
4. Locate the ancestor object element, copy the value of its guid attribute without the curly brackets (for example
3FAD8281-5A22-42E6-8438-540B7C5B0233), and paste it to your rule.
5. Close the XML file once you are done.

11
3.3.4 Determining Metadata Element IDs

Alternatively, you can refer to metadata elements using IDs instead of aliases or GUIDs in your metadata card configuration
rule. You can find the relevant IDs in M-Files Admin by completing the following steps:

1. Open M-Files Admin.

2. In the left-side tree view, expand a desired connection and then expand a desired document vault.
3. Expand Metadata Structure (Flat View).
4. Either:
a. Select Object Types to open the Object Types list and locate the ID for the relevant object type in the ID
column.
or
b. Select Property Definitions to open the Property Definitions list and locate the ID for the relevant property
in the ID column.
or
c. Select Classes to open the Classes list and locate the ID for the relevant class in the ID column.
or
d. Select Value Lists to open the Value Lists list and right-click the relevant value list name, select Contents…
and locate the ID for the relevant value list item in the ID column.
5. Take note of the ID and add it to your configuration rule.

3.4 Rule Conditions

Rule conditions may be based on:

 Class values
 ObjectType values
 property values
 a combination of the above values

Note: Currently only SSLU (single-select lookup) and MSLU (multi-select lookup) properties are supported in
property-based conditions.

3.4.1 No Condition

If you want your metadata card configuration rule to be universally applied in the selected vault, enter the following in the
Rule condition field:

{
}

For example, if you want a specific tooltip for a certain property to be always displayed regardless of object type, class, or
any other condition, make a new rule consisting of the configuration for the tooltip and enter the above content in the Rule
condition field.

12
3.4.2 Class-Based Conditions

If you, for example, want to add a metadata configuration for the Customer class, add the rule condition in the following
fashion, using the alias that you have set for the Customer class or the Customer class ID in the rule condition:

{
"Class": "CustomerClass"
}

You can also define a rule condition that applies to several different classes. If you want to define a set of rule behaviors that
applies, for example, to both Customer and Customer Project classes, you need to store the class aliases or IDs in an array:

{
"Class": ["CustomerClass", "CustomerProjectClass"]
}

A rule with the above condition is applied to both Customer objects and Customer Project objects.

3.4.3 Object Type Based Conditions

If you want to add a metadata configuration for the Document object, add the rule condition in the following fashion, using
the Document object type ID or an alias in the rule condition:

{
"ObjectType": 0
}

If you need to define a rule that applies to multiple object types, list the object type IDs or aliases in an array:

{
"ObjectType": ["Customer", 101]
}

3.4.4 Property-Based Conditions

If you want to have a metadata configuration for a certain property value, define the rule condition in the following fashion:

{
"Properties": {
"CustomerProperty": 2
}
}

The above condition is fulfilled when the ID of the Customer property has the value "2". Alternatively, you can refer to the
property value with its GUID (see chapter 3.3.3). Using GUIDs is strongly encouraged in environments where content is
replicated between two or more vaults, or when content is imported from an external database.

13
If you want to use an automatic property value as a rule condition, you need to set the AllowIndirect definition to true
when defining the condition, like this:

{
"Properties": {
"<Property ID or alias>": {
"Value": <Automatic value ID>,
"AllowIndirect": true
}
}
}

You can also use workflows (built-in ID 38) and workflow states (built-in ID 39) as property conditions. You may use aliases
or IDs for workflows or workflow states in the condition:

{
"Properties": {
"38": "Processing job applications",
"39": "Applicant selected for interview"
}
}

In the example above, the rule is applied when an object is in the Applicant selected for interview workflow state of the
Processing job applications workflow. This example condition refers to the workflow and the workflow state by their aliases
("Processing job applications" and "Applicant selected for interview") that can be specified in M-Files Admin.

If you want the rule to apply to more than one workflow state, list the IDs of the workflow states in an array:

{
"Properties": {
"38": "Processing job applications",
"39": [128, 129]
}
}

Operators for Property-Based Conditions

You can use various operators with property-based conditions for further refining your condition.

The available operators are listed in the following table:

OPERATOR DESCRIPTION

is Specifies a single value list item or object.

isNot Excludes a single value list item or object from the condition.

hasAny Specifies multiple value list items or objects. Accepts any of the items specified in the condition.

hasAll Specifies multiple value list items or objects. Requires all of the items to be present in the property.

The operator hasAny can be used implicitly. It only requires you to insert the ID or the GUID of the value list item or object
after the colon, like this:

14
 {
"Properties": {
"<Property alias or ID>": 5
}
}

To define a condition with multiple items that accepts any of the defined value list items or objects, insert an array of IDs,
GUIDs, or both, after the colon:

{
"Properties": {
"<Property alias or ID>": [2, "FC4AA3DA-5A87-490E-8607-5934826CA27C"]
}
}

In addition, you can insert any of the four operators explicitly into the condition. For example, this is how you would
explicitly use the hasAny operator:

{
"Properties": {
"Country": {
"Operator": "hasAny",
"Value": [4, 5, 6]
}
}
}

The value in the syntax can be either a single ID or GUID, or an array of IDs, GUIDs, or both.

Note: The operators is and isNot can only be used for properties of the Choose from list data type, and the
operator hasAll only for properties of the Choose from list (multi-select) data type. The hasAny operator can
be used with properties of both the Choose from list and Choose from list (multi-select) data type.

3.4.5 Combining Conditions

You might also want to filter your condition with a combination of definitions, for instance:

{
"Class": 78,
"Properties": {
"CountryProperty": 1
}
}

The above condition is fulfilled once the class is Customer (ID 78) and the property Country (alias CountryProperty) is
USA (ID 1).

3.5 Rule Behaviors

The configuration for a rule behavior consists of defining the behavior category, the behavior target, and finally a set of
behavior definitions.

15
 {
"Properties": {
"DescriptionProperty": {
"Description": "Description for the property.",
"Tooltip": "Tooltip for the property."
}
}
}

The above example would create a description and a tooltip for the property represented with the alias
DescriptionProperty, which in our example scenario is the Description property.

Below are listed the definitions that may be set in a rule behavior. Following each definition in parentheses is the
appropriate data type or types for each respective definition value.

3.5.1 Rule Behavior Definitions f or Properties

 Tooltip (string): The tooltip text, which is shown when the user moves the mouse cursor on top of the property.
Tooltips can also be added for group headers.
o Content (object): An object containing the localized text string variants.
 <Language code> (string): A localized variant of the text string.
 Description (string): The description text, which is shown when the user selects the property.
o Content (object): An object containing the localized text string variants.
 <Language code> (string): A localized variant of the text string.
 Label (string): A label that replaces the name of a property once the rule condition is fulfilled.
o Content (object): An object containing the localized text string variants.
 <Language code> (string): A localized variant of the text string.
 Priority (integer): The priority of the property. Properties are ordered on the metadata card by their priority
value, so that the uppermost property has the lowest priority value. Properties with the same priority are ordered
by their original order. If the property belongs to a group, the priority value is effective only within that group (the
priority is defined in relation to other properties in the same group). If no priority is given, the default priority
"1000" is given for properties. Note that property priorities are used to set the order in relation to other properties,
not to groups. Properties without groups are always added above any property groups.

Note: You cannot add the Priority definition for the Class property because Class is always shown at the
top of the property listing.

 SetValue (string, array, integer, object, true or false): This definition allows you to define a preset value for a
property. A set value is added automatically for the property on the metadata card once the rule condition is
fulfilled if the property is already found on the metadata card, or if the user adds the property to the metadata
card manually or changes the class of the object to one that contains the said property. SetValue does not add
the property and its value to the metadata card if the property does not already exist on the metadata card. You
can use the IsAdditional or IsRequired definition in conjunction with SetValue to force the property with
the set value to be added to the metadata card.
o Content (string, integer, array): The set value string to be set with SetValue if additional parameters,
such as IsForced or localizations are used in conjunction with SetValue. If only the set value string
needs to be set, the string can be set as a value for SetValue directly, and Content need not be used.

16
  <Language code> (string): A localized variant of the text string.
o IsForced (true or false): When true, any existing value is overwritten. The default it false.

Note: SetValue is applied once its rule condition is fulfilled. It is reapplied only if the rule condition at
some point is no longer fulfilled and later becomes valid again. That is to say, if you modify the value of a
SetValue definition, the new value is not applied before the rule condition has been fulfilled again.
Placeholders in set values are an exception, as they are updated whenever their referenced property values
are modified.

For more information on the behavior of SetValue, see Appendix B: Behavior of the SetValue Definition.

Note: You may use the following placeholders to add the original filename of a file to a property value:

%FILENAME%: The original filename of the file that has been added to M-Files.
%FILENAMEWITHEXTENSION%: The original filename and extension of the file that has been added to M-
Files.

These placeholders can only be used when creating a new document by adding a new file to M-Files. The
placeholders cannot be applied to existing objects. If you are adding several files at once to M-Files, you
must click Create separately for each file (that is, you cannot use the Create All option) to add the correct
filename to the object metadata.

Using these placeholders requires M-Files version 11.3.4330.151 or newer.

Note: SetValue cannot be used with properties that use automatic values.

 IsAdditional (true or false): When true, defines the property as an additional property. This adds an optional
property to the metadata card.
 IsRequired (true or false): When true, sets the property as a mandatory property. This adds a mandatory
property to the metadata card, or defines an existing, optional property as mandatory. This definition can be used
to overrule the "Allow using this property with the following object type" option in M-Files Admin.
 IsReadOnly (true or false): When true, the value of the property cannot be edited.
 IsHidden (true or false): Defines whether the property is hidden or visible.

Note: Objects can still be found by searching for the value of a hidden property.

 Group (string): The property group to which the property belongs.

Note: You cannot add the Group definition for the Class property because Class is always shown at the top
of the property listing.

 After (string, integer, array): Takes an ID or an alias of a so-called trigger property, after which the property
should appear on the metadata card. If the given trigger property ID or alias is found, then the property appears
after it. This value overwrites the priority value of the property. If the trigger property belongs to any group, the

17
 property is moved to the same group. You can also list multiple trigger property IDs or aliases inside an array. In
such a case, the property appears after the first trigger property listed in the array that is found on the metadata
card.
 SingleLine (true or false): Forces a multi-line text property value to be displayed on a single line without line
breaks.
 Control (object): For properties of the Choose from list, Choose from list (multi-select), and Boolean (yes/no)
data type. Allows you to use alternative user interface controls on the metadata card for selecting the value of such
properties. You can use a group of check boxes or radio buttons instead of the default drop-down menu.
o Type ("Checkbox", "RadioButton", or "Default"): Sets the user interface element to be used
for choosing a value or values for the selected property. Provide the value "Checkbox" to use a group of
check boxes for choosing values for the property – for properties of the Choose from list (multi-select) or
Boolean (yes/no) data type – or the value "RadioButton" to use a group of radio buttons for selecting a
value for a property of the Choose from list and Boolean (yes/no) data type. You may use the value
"Default" to explicitly configure a property to use the default drop-down menu control. The
"Default" value is useful if you need to make exceptions to a general rule that includes the Control
definition, or if you want to use the drop-down menu control for a property with selectable values that
does not use the drop-down menu by default.

Note: The property Is template uses the check box control by default.

Note: If you use the check box control for a Boolean (yes/no) property, the default selected value is
false, meaning that the check box is unchecked by default. In all other instances when either the
check boxes or the radio buttons are used, no value is selected by default.

o Parameters (object): Parameters for configuring the user interface control. This definition can be
omitted if the default values are to be used.
 MaxNumberOfItems (integer): Defines the maximum number of items that can be shown
using check boxes or radio buttons. If the items exceed the set maximum, an error message is
displayed in place of the items. If nothing is defined, the maximum is 50 by default. If you are
experiencing performance issues when opening the metadata card, you should try decreasing
this number.
 Text (string): If the Type definition is set to Checkbox and the property is of the Boolean
(yes/no) data type, you can use the Text definition to specify a text label to be displayed to the
right of the check box. If no text is specified, no text label is displayed.
 NullText (string): If the Type definition is set to RadioButton, you can use the NullText
definition to set the label for a null or empty value. Selecting this value is the same as selecting
no value. If no string is specified, the default value is "Not specified".
 HideNullItem (true of false): When true, the null value is not displayed on the metadata
card. This definition is false by default.
 TrueText (string): If the Type definition is set to RadioButton, you can use the TrueText
definition to change the label for the true radio button option. The default value is "Yes".
 FalseText (string): If the Type definition is set to RadioButton, you can use the
FalseText definition to change the label for the false radio button option. The default value is
"No".

18
3.5.2 Rule Behavior Definitions f or Property Groups

 Title (string): The title text of the group.

o Content (object): An object containing the localized text string variants.
 <Language code> (string): A localized variant of the text string.
 IsCollapsible (true or false): Defines whether the group is collapsible or not.
 IsCollapsedByDefault (true or false): Defines whether the group is collapsed by default.
 Priority (integer): The priority of the property group. Property groups are ordered on the metadata card by
their priority value, so that the uppermost group has the lowest priority value. Note that group priorities are used
to set the order in relation to other groups, not to properties. Groups are always added below the properties that
do not belong to any group.
 HasHeader (true or false): Defines whether the group has a visible header (title text).
 IsHidden (true or false): Defines whether the group is hidden or visible.
 IsDefault (true or false): Defines whether the group is the default group. All the properties without a group are
added to the default group.
 Tooltip (string): The tooltip text shown when the user moves the mouse cursor on top of the group header.
o Content (object): An object containing the localized text string variants.
 <Language code> (string): A localized variant of the text string.

3.5.3 Rule Behavior Definitions f or the Metadata Card

 Description (string): The description text, which is displayed at the top of the metadata card, above properties.
You can also define a picture for the metadata card in the description field.
o Content (object): An object containing the localized text string variants.
 <Language code> (string): A localized variant of the text string.
 Theme (object): You can modify the appearance of certain metadata card elements by adding subordinate JSON
objects under the theme object. The available elements are Ribbon, DescriptionField, ObjectIdField,
ObjectVersionField, Groups, Properties, AddPropertyLink, Footer, and Buttons.
o Ribbon (object): The ribbon between the header and the property listing of the metadata card.
 BackgroundColor:Edit (string): The CSS-formatted color of the ribbon in edit mode.
 BackgroundColor (string): The CSS-formatted color of the ribbon in view mode.
o DescriptionField (object): The description field on the metadata card (see the first main-level list
item of this list).
 Color (string): The text color of the description field in CSS color format.
 BackgroundColor (string): The background color of the description field in CSS color format.
o ObjectIdField (object): The area displaying the M-Files ID of the object.
 IsHidden (true or false): The field can be hidden by using the value true.
o ObjectVersionField (object): The area displaying the M-Files version of the object.
 IsHidden (true or false): The field can be hidden by using the value true.
o Groups (object): Any property group.
 Header (object): The header of the property group.
 Color (string): The text color of the group header in CSS color format.
 BackgroundColor (string): The background color of the group header in CSS color
format.
o Properties (object): Any property field.
 DescriptionField (object): The description displayed for a selected property.
 Color (string): The text color of the description field in CSS color format.
 BackgroundColor (string): The background color of the description field in CSS color
format.

19
  RelatedObjectLink (object): The link button next to a property allowing the user to open
the referenced object in a new window.
 IsHidden (true or false): The button can be hidden by using the value true.
o AddPropertyLink (object): The "Add property" link.
 IsHidden (true or false): The link can be hidden by using the value true.
 Color (string): The color of the link in CSS color format (for version 11.3.4330.150 and above).
o Footer (object): The area for permission and workflow settings.
 IsHidden (true or false): The area can be hidden by using the value true.
 BackgroundColor (string): The background color of the area in CSS color format (for version
11.3.4330.150 and above).
 BackgroundColor:Hover (string): The CSS-formatted color of the area while hovered (for
version 11.3.4330.150 and above).
o Buttons (object): The action buttons at the bottom of the metadata card (Save, Discard, etc.).
 BackgroundColor (string): The CSS-formatted color of the buttons while unselected.
 BackgroundColor:Hover (string): The CSS-formatted color of the buttons while hovered.
o LocationButton (object): The "Toggle Metadata Card Location" option in the metadata card Settings
(the cogwheel icon) menu (for version 11.3.4330.150 and above).
 IsHidden (true or false): The option can be hidden by using the value true.

3.5.4 Rule Behavior Definitions f or Value List Items

 Items (object): You can modify the appearance of value list items by adding subordinate JSON objects under the
items object.
o Tooltip (string): The tooltip text, which is shown when the user moves the mouse cursor on top of the
value list item.
 Content (object): An object containing the localized text string variants.
 <Language code> (string): A localized variant of the text string.

3.5.5 Rule Behavior Definitions for Defining Custom Placeholders for Set Values

You can define a custom placeholder that is populated with a property value based on the search conditions defined for the
placeholder. The custom placeholder can be used for defining a set value.

 CustomPlaceholders (object): The internal name of the custom placeholder.

o <Internal name of the custom placeholder> (object)
 SearchCondition (object): The search conditions for populating the custom placeholder.
 ObjectType (string): The object type to be used as the search condition.
 Properties (object): The property to be used to populate the custom placeholder.
o <Property> (string): The search condition for defining the property value
that is used for populating the custom placeholder.

Note: The data type of the property for which a set value containing a custom placeholder is to be added must be
of the same data type as the property matching the search condition of the custom placeholder. For instance, if
the search condition of the custom placeholder matches a property of the Date data type, the property
containing the custom placeholder must also be of the Date data type.

Note: If an indirect custom placeholder search condition matches more than one item, and if the placeholder is
used as a set value for a property whose data type is any other than Text or Text (multi-line), the value of the

20
 property will be empty. If, on the other hand, the data type of the property is Text or Text (multi-line), the
placeholder will be included repeatedly in the value field. In general, you should always try to define the search
condition for a custom placeholder in such a way that it matches only one item.

4. Metadata Card Configurations

This section gives concrete examples of how you can modify the behavior of the metadata card with the metadata card
configuration editor. You may combine these examples into a single set of rules as you see fit.

4.1 Adding an Additional Header to the Metadata Card

You can add an additional header that is added to the metadata card based on the condition of your choice. The below
instructions show you how you can add an additional header for a certain object type.

1. Click Add to add a new rule.

2. Enter a suitable name for the rule in the Rule name field.
3. In the Rule condition field, enter one of the JSON structures below.

If you want to add a header for a certain object type, use the following JSON structure:

{
"ObjectType": "<Object type alias or ID>"
}

Enter the object type, for example Document, as the value of the ObjectType definition.

If you, on the other hand, want to add a header for a certain class, enter the following JSON structure in the Rule
condition field:

{
"Class": "<Class alias or ID>"
}

4. In the Rule behavior field, enter one of the JSON structures below.

If you only want to add a textual description to the metadata card for the object type, use the following JSON
structure:

{
"MetadataCard": {
"Description": "<Your object type description text>"
}
}

You may use the following HTML elements in the description:

21
ELEMENT EXAMPLE

Bolded text <b>Bolded text</b>

1st level heading <h1>Heading text</h1>

2nd level heading <h2>Heading text</h2>

3rd level heading <h3>Heading text</h3>

Line break Here's a line.<br>Here's another line.

Link <a href='URL'>Link text</a>

You can add the following types of links using the <a> tag:

LINK TYPE EXAMPLE

Web site (http: or https:) See <a href='https://kb.cloudvault.m-files.com'>M-Files

KnowledgeBase</a> for more information.

E-mail address (mailto:) Contact <a href='mailto:[email protected]'>customer support</a>

for more information.

M-Files URL (m-files:) Please read the <a href=' m-files://show/BTF3FC8Y-8B41-43FD-NOCC-

FDD895516864/0-230711?object=06TY9555-8618-457T-884F-
114TB9966413'>Project Guidelines</a> document before creating a new project.

Note that single quotes must be used for the href attribute when adding a link in the description:

{
"MetadataCard": {
"Description": "See <a href='https://kb.cloudvault.m-files.com'>
M-Files KnowledgeBase</a> for more information."
}
}

If you want to add a textual description and an image, use the JSON structure below:

{
"MetadataCard": {
"Description": {
"Content": "<Your object type description text>",
"Image": {
"Url": "<URL of the image>",
"Width": <Width of the image in pixels>,
"Height": <Height of the image in pixels>
}
}
}
}

The following URI schemes or network paths may be used for the image Url definition:

 The HTTP URI schemes (http://<host>/<path>) is used to refer to an image file stored at a web
location.
 The data URI scheme (data:image/<file format>;base64,<data>) can contain an image encoded
inline as a Base64 string. For more information on data URIs, see data URIs in Reference Documents.

22
 You can encode your image, for instance, by using any online encoding service. The encoded
sequence replaces the <data> part of the data URI syntax. The <file format> part contains the file
extension of the image.

For instance:
data:image/gif;base64,R0lGODlhEAAOALMAAOazToeHh0tLS/7LZv/0jvb29t/f3//Ub
//ge8WSLf/rhf/3kdbW1mxsbP//mf///yH5BAAAAAAALAAAAAAQAA4AAARe8L1Ekyky67QZ
1hLnjM5UUde0ECwLJoExKcppV0aCcGCmTIHEIUEqjgaORCMxIC6e0CcguWw6aFjsVMkkIr7
g77ZKPJjPZqIyd7sJAgVGoEGv2xsBxqNgYPj/gAwXEQA7

 A UNC path (\\\\<host>\\<path>) is used to provide the location of a shared network resource. Note
that UNC paths use backlashes, and since the backlash also serves as a special escape character in JSON,
you need to use quadruple and double backlashes to provide a UNC path, like in the syntax example
enclosed in parentheses.
 The file URI scheme (file:///<path>) references an image file stored on your local computer.

Say, for example, that you have an image file called logo.png stored in the root of your C: drive.
You can add this image to the metadata card by adding the following value for the Url definition:

file:///c:/logo.png

The following image formats are supported: PNG, GIF, SVG, JPG, and BMP.

5. Click Save once you are done.

Expected results

The header you have defined in the rule behavior appears at the top of the metadata card for the objects you delimited in
the rule condition.

Image 4: Metadata card header with text, images and links.

23
4.2 Modifying the Appearance of the Metadata Card Element s

You can modify the metadata card appearance and, for instance, create a personalized theme for certain object types.

The following example describes how you can personalize the appearance of the metadata card:
1. Click Add to add a new rule.
2. Enter a suitable name for the rule in the Rule name field.
3. In the Rule condition field, enter a rule condition of your choice.
4. In the Rule behavior field, enter the following JSON structure:

{
"MetadataCard": {
"Theme": {
"Ribbon": {
"BackgroundColor:Edit": "#00994C",
"BackgroundColor": "#006633"
},
"Groups": {
"Header": {
"Color": "#FFFFFF",
"BackgroundColor": "#004C99"
}
}
}
}
}

5. Click Save once you are done.

Expected results

The objects delimited with your rule condition should now be displaying your personalized settings. The ribbon and the
group headers should be themed according to the color codes defined in your rule behavior.

24
Image 5: Metadata card using a personalized header and grouping behavior for the Customer class.

4.3 Adding Tooltips and Description Fields for Individual Properties

With the metadata card editor, you can add a tooltip text for a property, which appears when you hover your mouse cursor
over a property on the metadata card, or a description text, which appears above the property value field when you click a
property on the metadata card.

Note: Tooltips do not support HTML content.

Follow the steps below to add a tooltip text and a description text for a property:
1. Click Add to add a new rule.
2. Enter a suitable name for the rule in the Rule name field.
3. In the Rule condition field, enter a rule condition of your choice.
4. In the Rule behavior field, enter the following JSON structure:

25
 {
"Properties": {
"<Property alias or ID>": {
"Description": "<Your description for the property>",
"Tooltip": "<Your tooltip text for the property>"
}
}
}

5. Click Save once you are done.

Expected results

The tooltip text, the description text, or both appear on the metadata cards (delimited in the rule condition) for the
properties that you have defined in the rule behavior. The description text appears above the property value field when you
click a property with a description on the metadata card. The tooltip text appears when you hover your mouse cursor over a
property with a set tooltip text.

Image 6: The property Invoice title displaying a tooltip (left) and a description field (right).

4.4 Adding Tooltips for Value List Items

You can add a tooltip text for value list items, which appears when you hover your mouse cursor over an item in the value
list property. Object types (such as Employee, Customer, and Project) are also value lists and tooltips can accordingly be
added to object value list items.

Tooltips are also displayed for Class and Class Group value list items in the New Document dialog when you are creating a
new document from a template. In such a case, however, rule conditions can be based on object types only. Conditions
based on property or class are not applied in the New Document dialog when creating a new document from a template. In
the metadata card normal rule conditions apply.

Class, Workflow, Workflow State, and State transition value list items can also be identified by aliases in addition to IDs and
GUIDs.

Note: Tooltips do not support HTML content.

Follow the steps below to add a tooltip text for a value list items:
1. Click Add to add a new rule.
2. Enter a suitable name for the rule in the Rule name field.
3. In the Rule condition field, enter a rule condition of your choice.
4. In the Rule behavior field, enter the following JSON structure:

26
 {
"ValueLists": {
"<Value list alias or ID>": {
"Items": {
"<Value list item GUID or ID>": {
"Tooltip": "<Your tooltip text for the item>"
}
}
}
}
}

5. Click Save once you are done.

Expected results

The tooltip text is displayed for value list items that you have defined in the rule behavior. The tooltip text appears when you
hover your mouse cursor over an item with a set tooltip text.

Image 7: Tooltip text for a value list item.

4.5 Replacing Property Names with Labels

The Label definition allows you to replace a property name once the rule condition has been met.

To define a label for a property:

1. Click Add to add a new rule.
2. Enter a suitable name for the rule in the Rule name field.
3. In the Rule condition field, enter a rule condition of your choice.
4. In the Rule behavior field, enter the following JSON structure:

{
"Properties": {
"<Property alias or ID>": {
"Label": "<Your label>"
}
}
}

Add a label for all the properties that need to be renamed.

5. Click Save once you are done.

27
Expected results

According to your rule condition, the properties with the property alias or ID defined in your rule behavior should now
display your personalized label instead of the name defined in M-Files Admin.

4.6 Creating Collapsible Property Groups

You can create property groups for properties that you want to group together on the metadata card. The property groups
can be expanded and collapsed by clicking the arrow icon next to the property group title.

Follow the steps below to create a collapsible property group:

1. Click Add to add a new rule.
2. Enter a suitable name for the rule in the Rule name field.
3. In the Rule condition field, enter a rule condition of your choice.
4. In the Rule behavior field, enter the following JSON structure:

{
"Groups": {
"<Internal name for the group>": {
"Title": "<Header title for the group>",
"IsCollapsible": true,
"IsCollapsedByDefault": <true or false>,
"HasHeader": true,
"IsDefault": <true or false>
}
},
"Properties": {
"<Property alias or ID>": {
"Group": "<Internal name of the group the property belongs to>"
},
"<Property alias or ID>": {
"Group": "<Internal name of the group the property belongs to>"
}
}
}

Add the group definition with the internal name of your group for all the properties that you want to add to the
property group.

Note: Groups are collapsible and expanded by default. In other words, if the definitions IsCollapsible and
IsCollapsedByDefault are not set, the group can be collapsed and expanded, and it is in the expanded state
by default.

5. Click Save once you are done.

Expected results

All the properties for which you have added the Group definition should appear under a collapsible property group. This
applies to all the objects that you have delimited with your rule condition.

28
Image 8: A project object with two collapsible property groups, Status and Contact.

4.7 Controlling the Order of Properties and Property Groups on the Metadata Card

With the priority definition, you can control the order in which properties and property groups are displayed on the
metadata card. The lower the priority value a property is given, the higher it will displayed on the metadata card. The
priority value of a property is compared to priority values of other properties to determine the relative priority of the
property. Similarly, the priority values of property groups are compared to the priority values of other property groups to
determine the relative order in which property groups appear on the metadata card.

Follow the steps presented below to modify the order in which the properties are shown on the metadata card:
1. Click Add to add a new rule.
2. Enter a suitable name for the rule in the Rule name field.
3. In the Rule condition field, enter a rule condition of your choice.
4. In the Rule behavior field, enter the following JSON structure:

{
"Properties": {
"<Property alias or ID>": {
"Priority": <Any integer>
}
}
}

Add the Priority definition for all the properties the order of which you want to adjust.
5. Click Save once you are done.

To modify the order of property groups, repeat the steps presented above, but in step 4, use the following structure instead:

29
 {
"Groups": {
"<Internal name for the group>": {
"Title": "<Header title for the group>",
"Priority": <Any integer>,
"HasHeader": true
}
}
}

Expected results

All the objects that you have delimited with your rule condition should now display the properties and property groups in
the order based on your priority definition. The smaller the priority value, the higher the property groups or properties are
positioned on the metadata card.

4.8 Assigning Set Values for Properties

You can use the SetValue definition to add set values for properties that are filled automatically when a user creates a
new object. For a description of the behavior of the SetValue definition, see Appendix B: Behavior of the SetValue
Definition.

Follow these steps to add a set value for a property:

1. Click Add to add a new rule.
2. Enter a suitable name for the rule in the Rule name field.
3. In the Rule condition field, enter a rule condition of your choice.
4. In the Rule behavior field, enter one of the JSON structures below.

If you are defining a set value only for properties without an existing value, use the following JSON structure:

{
"Properties": {
"<Property alias or ID>": {
"SetValue": "<A user-defined value or a value list item GUID>"
}
}
}

If you want to add multiple values for properties of the Select from list (multi-select) type, assign the values in an
array for the SetValue definition, like so:

{
"Properties": {
"<Property alias or ID>": {
"SetValue": [ "<GUID>", "<GUID>", "<GUID>" ]
}
}
}

30
 Note: When you are using the SetValue definition for properties of the Boolean (yes/no) data type, use
the values true, false, or null without quotation marks.

If you want to add a set value for a property that already has a value, you need to force M-Files to overwrite the
existing value by using the IsForced definition and setting it to true:

{
"Properties": {
"<Property alias or ID>": {
"SetValue": {
"Content": "<A user-defined value or a GUID>",
"IsForced": true
}
}
}
}

Add the SetValue definition for all the properties for which you want to add a set value.
5. Click Save once you are done.

Expected results

When creating a new object that is of the type that you have defined in your rule condition, the property value field is filled
automatically with the set value. The same set value is added to any existing object only when you retrigger the condition by
editing metadata of the object.

4.8.1 Determining the Data Types of Properties

You need to also know the data type of the property when assigning set values. You can determine the data types via
M-Files Admin:

1. Open M-Files Admin.

2. In the left-side tree view, expand a desired connection and then expand a desired document vault.
3. Expand Metadata Structure (Flat View).
4. Select Property Definitions.

The data type of each property definition should be visible in the Data Type column of the property definition listing.

Text, Date, and Time Strings

The data types Text, Text (multi-line), Date, and Time accept values in string format. If you are, for instance, defining a set
value for a text-based property, use the following name–value pair format:

"SetValue": "<Value>"

For properties of the data type Text (multi-line), multi-line text can be added by using the newline character \n:

"SetValue": "This is the first line.\nThis is the second line."

For date and time formats, see Assigning Set Dates and Times for Properties.

31
"Choose from List" Properties

If the data type of the property you are referring to is Choose from list, use the following name–value pair format:

"SetValue": "<GUID>"

or

"SetValue": <ID>

If the data type of the property you are referring to is Choose from list (multi-select), and you need to select more than value
list item, insert them as an array, between square brackets:

"SetValue": [<ID>,<ID>,"<GUID>"]

GUIDs in the array need to be placed inside quotation marks.

Note: Using GUIDs is strongly encouraged in environments where content is replicated between two or more
vaults, or when content is imported from an external database. See chapters 3.3.2 and 3.3.3 for instructions on
determining metadata element and object GUIDs.

Boolean Properties

For properties of the Boolean (yes/no) data type, the value can be either true, false, or null without quotation marks:

"SetValue": true

or

"SetValue": false

or

"SetValue": null

Number Properties

If you are assigning a set value for a property of the Number data type, enter the number value without quotes:

"SetValue": <Number>

4.9 Using Placeholders and Custom Placeholders in Set Values

You can also use property placeholders or define custom placeholders to add set values for properties using the SetValue
definition. For a description of the behavior of the SetValue definition, see Appendix B: Behavior of the SetValue
Definition.

Below is an example of how you can employ placeholders for set values. Following this example requires that you have set
the alias "Department" for the Department property definition.
1. Click Add to add a new rule.

32
 2. Enter a suitable name for the rule in the Rule name field.
3. In the Rule condition field, enter the following condition:

{
"Properties": {
"Department": 1
}
}
The condition above is fulfilled when an object contains the Department property with the value Sales (the ID of
which is 1).

4. In the Rule behavior field, enter the following JSON syntax:

{
"Properties": {
"Description": {
"SetValue": {
"Content": "The department is %PROPERTY_{Department}%.",
"IsForced": true
}
}
}
}

Property placeholders within set values must be entered in one of the following formats:

FORMAT EXAMPLE

%PROPERTY_{alias}% %PROPERTY_{Department}%

%PROPERTY_ID% %PROPERTY_1136%

The placeholder is enclosed by "%" symbols and any text can precede or follow the placeholder.

5. Click Save to save the rule.

In order to use a custom placeholder in a set value, you must first specify the name and search condition for the custom
placeholder in the rule behavior. The example below illustrates how you can define and use a custom placeholder.

1. Click Add to add a new rule.

2. Enter a suitable name for the rule in the Rule name field.
3. In the Rule condition field, enter a rule condition of your choice.
4. In the Rule behavior field, first define the custom placeholder:

33
 {
"CustomPlaceholders": {
"Document_Owner": {
"SearchCondition": {
"ObjectType": "Employee",
"Properties": {
"M-Files user": "%CURRENT_USER%"
}
}
}
}
}

The custom placeholder titled "Document_Owner" is based on a search condition that selects the M-Files user
property value on the basis of the current user placeholder. The custom placeholder can now be used for adding
the current user as a set value for properties.

5. In the Rule behavior field, add a set value for a property and use the custom placeholder that you just defined in
the set value:

{
"Properties": {
"<Alias or ID of the Document Owner property>": {
"SetValue": "%Document_Owner%"
}
},
"CustomPlaceholders": {
"Document_Owner": {
"SearchCondition": {
"ObjectType": "Employee",
"Properties": {
"M-Files user": "%CURRENT_USER%"
}
}
}
}
}

Alternatively, you can use the custom placeholder to extract an indirect property value. For example, this is how you
would use the department of the current user as the placeholder to define a set value for the Department property:

34
 {
"Properties": {
"<Alias or ID of the Department property>": {
"SetValue": "%Document_Owner.PROPERTY_{Department}%"
}
},
"CustomPlaceholders": {
"Document_Owner": {
"SearchCondition": {
"ObjectType": "Employee",
"Properties": {
"M-Files user": "%CURRENT_USER%"
}
}
}
}
}

Note: If the indirect custom placeholder search condition matches more than one item, and if the placeholder
is used as a set value for a property whose data type is any other than Text or Text (multi-line), the value of
the property will be empty. If, on the other hand, the data type of the property is Text or Text (multi-line), the
placeholder will be included repeatedly in the value field. In general, you should always try to define the
search condition for a custom placeholder in such a way that it matches only one item.

6. Click Save to save the rule.

Expected results

When creating a new object that is of the type that you have defined in your rule condition, the property value field is filled
automatically with the set value. The placeholders used in the set values are replaced with their corresponding values.

4.10 Assigning Set Dates and Times for Properties

You can use the SetValue definition to define a set date for a date-based property. The steps are highly similar to those
presented in Assigning Set Values for Properties, but the value needs to be set with the following structure:

{
"Properties": {
"<Alias or ID for a date-based property>": {
"SetValue": "YYYY MM DD"
}
}
}

Alternatively, you can use the ISO 8601 standard to define the date:

35
 {
"Properties": {
"<Alias or ID for a date-based property>": {
"SetValue": "YYYY-MM-DD"
}
}
}

If you need to define a set time for a time-based property, use the following structure:

{
"Properties": {
"<Alias or ID for a time-based property>": {
"SetValue": "HH MM SS"
}
}
}

You can also use the ISO 8601 format to define a set time:

{
"Properties": {
"<Alias or ID for a time-based property>": {
"SetValue": "HH:MM:SS"
}
}
}

You may also want to use the current time for the time-based property. In that case, use the following structure:

{
"Properties": {
"<Alias or ID for a time-based property>": {
"SetValue": {
"UseCurrentTime": true
}
}
}
}

The UseCurrentTime definition uses the time of the client computer.

In addition to indicating the current time, you can use the UseCurrentDate definition to indicate the current date:

36
 {
"Properties": {
"<Alias or ID for a date-based property>": {
"SetValue": {
"UseCurrentDate": true,
"Delta": -2
}
}
}
}

The Delta definition can be used for adding to or subtracting from the date. For instance, if the current date is 29
September and Delta is set to "-2", the date 27 September would be displayed.

4.11 Managing Automatically Added Properties

By using the IsAdditional and IsRequired behavior definitions, you can define properties to be automatically added
to objects of a certain object type or class.

1. Click Add to create a new rule.

2. Enter a suitable name for the rule in the Rule name field.
3. In the Rule condition field, enter a rule condition of your choice.
4. In the Rule behavior field, enter the following JSON structure:

{
"Properties": {
"<Property alias 1 or ID1>": {
"IsAdditional": true
},
"<Property alias 2 or ID2>": {
"IsRequired": true
}
}
}

5. Click Save once you are done.

Expected results

All the objects delimited with your rule condition should now contain the properties defined in the rule behavior. In
addition, the property with the <Property alias 2 or ID2> should be displayed as a mandatory property. You can define
as many properties to be added – or to be added as mandatory – as required. Remember to separate the JSON objects for
the different properties with a comma, as shown above.

4.12 Hiding Properties from the Metadata Card

You may want to temporarily hide a property from the metadata card. You can do so by following these steps:
1. Click Add to add a new rule.
2. Enter a suitable name for the rule in the Rule name field.
3. In the Rule condition field, enter a rule condition of your choice.

37
 4. In the Rule behavior field, enter the following JSON structure:

{
"Properties": {
"<Property alias or ID>": {
"IsHidden": true
}
}
}

Set the IsHidden definition to true for all the properties that you want to hide from the metadata card.
5. Click Save once you are done.

Expected results

The metadata card of all the objects delimited with your rule condition should no longer show the property – or properties –
you defined in the rule behavior.

4.13 Using Alternative User Interface Controls for Selecting Property Values

You may use a group of check boxes or radio buttons instead of the default drop-down menu for selecting property values
on the metadata card. The check boxes can be used for properties of the Choose from list (multi-select) or Boolean (yes/no)
data type, and radio buttons for properties of the Choose from list or Boolean (yes/no) data type.

Do the following steps to use a group of check boxes for selecting values for a property of the Choose from list (multi-select)
or Boolean (yes/no) data type:
1. Click Add to add a new rule.
2. Enter a suitable name for the rule in the Rule name field.
3. In the Rule condition field, enter a rule condition of your choice.
4. In the Rule behavior field, enter the following JSON structure:

{
"Properties": {
"<Property alias or ID>": {
"Control": {
"Type": "Checkbox",
"Parameters": {
"Text": "<Optional label>"
}
}
}
}
}

The Text definition can be used for specifying a text label to the right of the check box if the property data type is
Boolean (yes/no). The parameters can be omitted if the default values are to be used.
5. Click Save to save your changes.

If you want to use a group of radio buttons for selecting values for a property of the Choose from list or Boolean (yes/no)
data type, do the following steps:
1. Click Add to add a new rule.

38
 2. Enter a suitable name for the rule in the Rule name field.
3. In the Rule condition field, enter a rule condition of your choice.
4. In the Rule behavior field, enter the following JSON structure:

{
"Properties": {
"<Property alias or ID>": {
"Control": {
"Type": "RadioButton",
"Parameters": {
"NullText": "<Label to be used for the null value>",
"HideNullItem": <true or false>,
"TrueText": "<Label to be used for the true value>",
"FalseText": "<Label to be used for the false value>"
}
}
}
}
}

The NullText definition is used for specifying a label for a null or empty value. Selecting the null value is the same
as selecting no value for a property. If NullText is not specified, the label for the null value is "Not
specified".
If the HideNullItem definition is set to true, the null value is not displayed as a selectable option.
If the selected property is of the Boolean (yes/no) data type, the TrueText and FalseText definitions can be
used for specifying text labels for the true and false value respectively.
These parameters can be omitted altogether if the default values are to be used.
5. Click Save to save your changes.

Expected results

The metadata card of all the objects delimited with your rule condition should now display either check boxes or radio
buttons for selecting values for the properties defined in your rule behavior.

For example, you have the property Country, the data type of which is Choose from list "Countries" (multi-select), and say
you have defined in your rule to use check boxes for the selecting values for the property. You would then see the following
controls on the metadata card when the rule condition is applied:

As another example, if you have a rule for using radio buttons for selecting the value for the Is supervisor? property, the data
type of which is Boolean (yes/no), the following controls would be displayed on the metadata card for selecting a value for
the property:

39
You can also use a check box for a property of the Boolean (yes/no) data type and define a text to be displayed next to the
check box using the Text definition:

If the Text definition is not used, only the check box is displayed.

If you have defined tooltips for the value list items (for instructions, see Adding Tooltips for Value List Items) in your
metadata card configuration rules and the property employs either the check boxes or the radio buttons, the tooltip for the
item is displayed when you move the cursor over one of the check box or radio button options, like so:

If the number of value list items exceeds the default limit of 50 items or the limit set with the MaxNumberOfItems
definition, an error message is displayed in place of the items:

4.14 Adding Localized Strings

Any definition that accepts a string as a value can have nested localizations for the string. You can add a nested JSON object
with localized string variants for definitions such as Tooltip, Description, Label, SetValue, Text, TrueText,
FalseText, NullText or the Title definition of a property group. This way you can manage localized variants of the
vault metadata structure. For the language codes used in M-Files, see Appendix A: M-Files Language Codes.

Note: The selection of the localized variant is based on the following priority:
1. The vault language
2. The software language
3. The topmost localized variant within a specific Content object

The example below shows how you can localization variants for the metadata description.
1. Click Add to add a new rule.

40
 2. Enter a suitable name for the rule in the Rule name field.
3. In the Rule condition field, enter a rule condition of your choice.
4. In the Rule behavior field, enter the following JSON structure:

{
"MetadataCard": {
"Description": {
"Content": {
"eng": "<The description>",
"fra": "<La description>"
}
}
}
}

The localized variants are added inside the Content object.

5. Click Save once you are done.

As another example, if you want to add localizations for a property group title, use the following syntax:
1. Click Add to add a new rule.
2. Enter a suitable name for the rule in the Rule name field.
3. In the Rule condition field, enter a rule condition of your choice.
4. In the Rule behavior field, enter the following JSON structure:

{
"Groups": {
"<Internal name for the group>": {
"Title": {
"Content": {
"eng": "Title of the group",
"fin": "Ryhmän nimi"
}
}
}
}
}

5. Click Save once you are done.

Expected results

All the objects delimited with your rule condition should now contain a description field displaying the content you defined.
Now, if the vault or software language is Finnish, the translated version of the description should be shown. You can add as
many translations as you need. They are displayed in the user interface according to the priority described in the note
further above in the chapter.

5. Troubleshooting

If you encounter any problems with metadata card configurations, disable the configurations by setting the following
registry key and value on client computers:

41
 Key HKEY_LOCAL_MACHINE\SOFTWARE\Motive\M-Files\<version>\Client\Common\NonVaultSpecifics\MetadataCard

Value name EnableConfigurability

Value type REG_DWORD

Description Setting this value disables metadata card configurations.

Value 0

6. Change History

The table below describes the essential changes by document version.

VERSION DATE ESSENTIAL CHANGES

1.0 2015-08-20 Initial published version.

1.1 2015-10-21 Added instructions for adding tooltips for value list items (chapter 4.4) and examples for adding
HTML content to the metadata card description (chapter 4.1).

1.2 2016-01-27 Added instructions for defining set date and time in the ISO 6801 format (chapter 4.10).

1.3 2016-03-24 Updated chapter 3.5 and added chapter 4.9.

1.4 2016-04-18 Added the IsReadOnly definition to chapter 3.5.1.

1.5 2016-04-19 Added Appendix B: Behavior of the SetValue Definition and updated chapters 4.14 and 3.5.

1.6 2016-06-29 Updated Appendix B: Behavior of the SetValue Definition and chapter 3.5.1.

1.7 2016-09-14 Added chapter 4.13. Added the Control definition to chapter 3.5.1. Updated the information about
acceptable set values for Boolean properties in chapters 4.8 and 4.8.1.

1.8 2016-09-26 Added chapter 3.4.1.

1.9 2017-01-03 Added chapter 3.3.3. Also added a note about using GUIDs to "Choose from List" Properties under
chapter 4.8.1.

2.0 2017-01-12 Updated chapter 3.5.3 (Added the Color definition under AddPropertyLink, BackgroundColor and
BackgroundColor:Hover under Footer, and the LocationButton definition).

2.1 2017-01-27 Added information about the %FILENAME% and %FILENAMEWITHEXTENSION% placeholders to
chapter 3.5.1.

7. Reference Documents

See these articles for additional information:

 data URIs

42
Appendix A: M-Files Language Codes

M-Files 2015.3 is available in the following languages.

LANGUAGE LANGUAGE CODE

Albanian sqi

Arabic ara

Bulgarian bgr

Chinese (Simplified) chs

Chinese (Taiwan/Traditional) cht

Croatian hrv

Czech csy

Danish dan

Dutch nld

English eng

Estonian eti

Finnish fin

French fra

German deu

Greek ell

Hebrew heb

Hungarian hun

Italian ita

Japanese jpn

Korean kor

Norwegian nor

Polish plk

Portuguese (Brazil) ptb

Romanian rom

Russian rus

Serbian srm

Slovak sky

Slovenian slv

Spanish esn

Swedish sve

Turkish trk

Vietnamese vit

43
Appendix B: Behavior of the SetValue Definition

The behavior of the SetValue definition is dependent on the circumstances where it is being used. This appendix clarifies
the differences in its behavior.

SetValue Behavior when Creating a New Object

The SetValue definition adds a set value for a property in the metadata of an object. The set value is added once its rule
condition is fulfilled. If the property for which the set value is to be added is not part of the class of the object, the property
and its set value is added to the metadata card only if either the IsRequired flag or the IsAdditional flag is set to true,
or if the user adds the property to the metadata card manually or changes the class of the object to one that contains the
said property.

Say you have a rule that applies to objects of the Order class and adds a set value for the Description property. When you
create a new object and select the Order class, the Description property value is automatically set.

SetValue Behavior for Existing Objects

A set value is added for an existing object only if its related rule condition at some point is no longer fulfilled and later
becomes valid again. That is to say, that even if the SetValue definition is modified, the new value is not applied before
the rule condition has been fulfilled again. A set value is added if the property does not already have a value. A set value
replaces an existing property value only if the SetValue definition has the IsForced flag set to true. If the property for
which the set value is to be added is not part of the class of the object, the property and its set value is added to the
metadata card only if either the IsRequired flag or the IsAdditional flag is set to true, or if the user adds the property
to the metadata card manually or changes the class of the object to one that contains the said property.

For instance, you have created a rule that applies to objects of the Employment Agreement class and adds a set value for the
Department property. Now, for any existing objects of the Employment Agreement class, the set value for the Department
property is not set unless the class is first changed to something else and then back to Employment Agreement. Once this is
done, the set value for the Department property is added or changed accordingly.

SetValue and Placeholders

If a set value contains a placeholder, the set value alongside the placeholder is added once its corresponding rule condition
is fulfilled, as explained in the previous two subchapters. However, placeholders are updated whenever their referenced
property values are modified, whether the metadata card rule condition becomes revalidated or not.

For example, you have created a rule that applies to objects of the Price List class and adds a set value for the Product
property. The set value contains text and a placeholder for the Department property. The set value is added for the Product
property when the rule condition is fulfilled. The set value is updated in its entirety, including both the text and the
placeholder, whenever the rule condition is revalidated. The Department placeholder in the set value, on the other hand, is
updated whenever its referenced property value is modified. However, if the user modifies the value of the Product
property, the Department placeholder is no longer updated when its referenced property value is modified. It is nonetheless
possible to prevent users from modifying properties such as this one by using the IsReadOnly definition and setting it to
true.

44