Metadata XML definition

The application metada 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.

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

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.7//EN"
                                 "http://www.openkm.com/dtd/property-groups-3.7.dtd">
<property-groups>
  
</property-groups>
  • The DOCTYPE is a formal definition of some DTD. In the previous example the property-groups-3.7.dtd.
  • The XML begins with <property-groups> tag and ends with </property-groups>. Into this hicheracy are defined the metada groups.

Metadata group definition

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.7//EN"
                                 "http://www.openkm.com/dtd/property-groups-3.7.dtd">
<property-groups>
  <property-group label="Consulting" name="okg:consulting">
    
  </property-group>
</property-groups>
  • Each  <property-group>...</property-group  block identify the begining and end of new metadata group definition.
  • Each metadata group has a label - used by user interface - Consulting.
  • Each metadata group has a unique name, okg:consulting.
  • The metadata group name always must starts with "okg:" ( OpenKGroup ).
  • Must not use special characters for name.
AttributeDescriptionRequired

label

The text shown as a label in the user interface.

true

name

Unique field identifier.

Two metadata groups can't 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_".

true

visible

Show or hide the metadata.

Allowed values are:

  • true.
  • false.

By default the metadata are visible.

false

readonly

Metadata values can not be modified from user interface only from API.

Allowed values are:

  • true.
  • false.

By default the metadata are modificable.

false

defaultValueClassName

Set 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 at Metadata fields

It's a good practice to use the metadata group name as the basis to create metadata field name. For example okp:consulting.code use okg:consulting as base ( changing okg to okp ). That helps to find out which is the metada group asociated to each metadata field.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.7//EN"
                                 "http://www.openkm.com/dtd/property-groups-3.7.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 can store a copy in your application server.

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

Can be a file system ( example below ) or a valid intranet URL.

<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.7//EN"
                                 "file:///home/openkm/property-groups-3.7.dtd">
  • In the example, /home/openkm/property-groups-3.7.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 separated tables. One table for current metadata values and the other for history metadata values.

Sample:

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

The prefix used for all the columns will be RGT_.

The column with name RGT_UUID contains the value of the node UUID. 

Be careful with the Oracle table name and column name 32 characters limitation. 

Default column size by type

TypeSize

Input

128 characters

Select

128 characters

SuggestBox

128 characters

TextArea

256 characters

In case you have metadata values larger should increase the value of the column with the attribute "dbColumnSize". See the sample below:

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, although you change the value "dbColumnSize" of the attribute, the column size will not be updated. In case you want to update the column size after creation, should apply changes from database client directly.

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