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 the {major} and {minor} values are two numbers (major release and minor release). For example, the location for version 3.10 of the DTD is http://www.openkm.com/dtd/property-groups-3.10.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.

Basic XML skeleton

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

</property-groups>

• The DOCTYPE is a formal definition of a DTD. In the previous example, the DOCTYPE is property-groups-3.10.dtd.
• The XML begins with tag and ends with . Within 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.10//EN"
                                 "http://www.openkm.com/dtd/property-groups-3.10.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. The name must be unique. The name must start with “okg:”. Please use only letters, numbers, and underscore: “0-9a-zA-Z_”.	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, only from 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

Basic example

Available field types:

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

More information about field type elements is available at Metadata fields

Note

It’s a 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 the base (changing okg to okp). That 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.10//EN"
                                 "http://www.openkm.com/dtd/property-groups-3.10.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, then the DTD file must be accessible in some 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.10//EN"
                                 "file:///home/openkm/property-groups-3.10.dtd">

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

How metadata is stored into OpenKM

When you register a new metadata definition in OpenKM, the metadata values are stored in two separate tables. One table is for current metadata values and the other is for historical metadata values.

Sample:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.10//EN"
                                 "http://www.openkm.com/dtd/property-groups-3.10.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 which 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 which 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 with name RGT_UUID contains the value of the node UUID.

Caution

Be careful with the 32-character limitation for Oracle table and column names.

Default column size by type:

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

If you have larger metadata values, you should increase the value of the column using 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 each time you add a new file. After the column has been created in the database, changing 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 from a database client.

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