Metadata XML definition

The application metadata is based on a formal XML definition. The DTD (Document Type Definition) defines the structure and the legal elements and attributes of an XML document.

Note

You can see the latest DTD on our website http://www.openkm.com/dtd/property-groups-{major}.{minor}.dtd where {major} and {minor} are two numbers (major release and minor release). For example, the location for version 3.15 of the DTD is http://www.openkm.com/dtd/property-groups-3.15.dtd

Caution

Each application version supports only a couple of DTD definitions. Read Application version compatibility table to see which are supported by your application.

Caution

Once the metadata is registered, remember to enable it in the user profile at Administration > Profiles, General tab, and Metadata Groups.

Basic XML skeleton

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.15//EN"
                                 "http://www.openkm.com/dtd/property-groups-3.15.dtd">
<property-groups>

</property-groups>

• The DOCTYPE is a formal definition of a DTD. In the previous example, the property-groups-3.15.dtd is used.
• The XML begins with the tag and ends with the . In this hierarchy, the metadata groups are defined.

Metadata group definition

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.15//EN"
                                 "http://www.openkm.com/dtd/property-groups-3.15.dtd">
<property-groups>
  <property-group label="Consulting" name="okg:consulting">

  </property-group>
</property-groups>

• Each …</property-group block identifies the beginning and end of a new metadata group definition.
• Each metadata group has a label - used by the user interface - Consulting.
• Each metadata group has a unique name, okg:consulting.
• The metadata group name must always start with “okg:” (OpenKM Group).
• Do not use special characters in the name.

Attribute	Description	Required
label	The text shown as a label in the user interface.	true
name	Unique field identifier. Two metadata groups cannot have the same name. Name must be unique. The name must start with “okg:”. Please use only letters, numbers, and underscore: “0-9a-zA-Z_”. We recommend “snake_case” rather than “camelCase” for better column names.	true
visible	Show or hide the metadata. Allowed values are: - true. - false. By default, the metadata are visible.	false
readonly	Metadata values cannot be modified from the user interface; they can only be modified via the API. Allowed values are: - true. - false. By default, the metadata are modifiable.	false
defaultValueClassName	Set a custom Java class for setting initial default values.	false
validatorClassName	String. Class name of the FormValidator plugin. If set, the form validator is invoked when the form is saved.	false
autocompleteValueClassName	String. Class name of the AutocompleteFormValues plugin. Provides autocomplete suggestions for the property group fields.	false
interceptorClassName	String. Class name of the FormInterceptor plugin. If set, the interceptor can inspect or modify form data on load and save.	false
defaultAccess	Default security access for the property group. Allowed values: grant, revoke. Defaults to grant.	false

Basic example

Available field types:

• Checkbox
• Input
• Iframe
• Select
• Separator
• Suggestbox
• Text
• TextArea

More information about field type elements can be found at Metadata fields.

Note

It’s good practice to use the metadata group name as the basis for creating metadata field names. For example, okp:consulting.code uses okg:consulting as its base (changing okg to okp). This helps to determine which metadata group is associated with each metadata field.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.15//EN"
                                 "http://www.openkm.com/dtd/property-groups-3.15.dtd">
<property-groups>
  <property-group label="Consulting" name="okg:consulting">
    <input label="Input label" name="okp:consulting.input1" />
    <separator label="Separator label" name="okp:consulting.separator" />
    <input label="Input label" name="okp:consulting.input2" />
  </property-group>
</property-groups>

Using file system DTD

If the server has no access to the Internet, the DTD file must be accessible in some other way; for example, you can store a copy on your application server.

Caution

The XML definition must be changed to refer to the new DTD location; otherwise, you will get an application error while processing the DTD file.

It can be a file system path (example below) or a valid intranet URL.

<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.15//EN"
                                 "file:///home/openkm/property-groups-3.15.dtd">

• In the example, /home/openkm/property-groups-3.15.dtd is the file system path to the file.

How metadata is stored in OpenKM

When you register a new metadata definition in OpenKM, the metadata values are stored in two separate tables: one table for current metadata values and another for historical metadata values.

Sample:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.15//EN"
                                 "http://www.openkm.com/dtd/property-groups-3.15.dtd">
<property-groups>
  <property-group label="Consulting" name="okg:consulting">
    <input label="Input label" name="okp:consulting.input1" />
    <separator label="Separator label" name="okp:consulting.separator" />
    <input label="Input label" name="okp:consulting.input2" />
  </property-group>
</property-groups>

After registering the previous metadata definition, two tables will be created with these columns:

• OKM_PGRP_CUR_CONSULTING (used for current metadata values)
  • RGT_UUID: ID of the node that has this metadata
  • RGT_PRO_INPUT1: Value of property okp:consulting.input1
  • RGT_PRO_INPUT2: Value of property okp:consulting.input2
  • RGT_PRO_SEPARATOR: Value of property okp:consulting.separator
• OKM_PGRP_HIS_CONSULTING (used for historical metadata values)
  • RGT_UUID: ID of the node that has this metadata
  • RGT_VERSION: ID of the related version
  • RGT_PRO_INPUT1: Value of property okp:consulting.input1
  • RGT_PRO_INPUT2: Value of property okp:consulting.input2
  • RGT_PRO_SEPARATOR: Value of property okp:consulting.separator

Note

The prefix used for all the columns will be RGT_.

The column named RGT_UUID contains the value of the node UUID.

Caution

Be careful of Oracle’s 32-character limitation for table and column names.

We recommend “snake_case” rather than “camelCase” for better column names.

For example, this definition would create the table field RGT_PRO_RETURNPLACE:

<input label="Return place" name="okp:sample.returnPlace" />

But this one would create the table field RGT_PRO_RETURN_PLACE, which is more human-readable:

<input label="Return place" name="okp:sample.return_place" />

Default column size by type:

Type	Size
CheckBox	8 characters
Input	128 characters
Select	128 characters
SuggestBox	128 characters
TextArea	256 characters

If you have larger metadata values, you should increase the column size with the attribute “dbColumnSize”. See the sample below:

Caution

The value of the attribute “dbColumnSize” will only be applied the first time you register the metadata group or when you add a new field. After the column has been created in the database, changing the value of the “dbColumnSize” attribute will not update the column size. If you want to update the column size after creation, you should apply the changes directly using a database client.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.15//EN"
                                 "http://www.openkm.com/dtd/property-groups-3.15.dtd">
<property-groups>
  <property-group label="Consulting" name="okg:consulting">
    <input label="Input label" name="okp:consulting.input1" dbColumnSize="256"/>
    <separator label="Separator label" name="okp:consulting.separator" />
    <input label="Input label" name="okp:consulting.input2" dbColumnSize="512"/>
  </property-group>
</property-groups>