1. Home
  2. OpenKM 6.3 - CE
  3. Development
  4. API description
  5. OKMPropertyGroup
  1.  

OKMPropertyGroup

Basics

From the older OpenKM version we named "Metadata Groups" as "Property Groups".

Although we understand this name does not help a lot to identify these methods with metadata ones, for historical reason, we continue maintaining the nomenclature.

For more information about Metadata.

On most methods you'll see a parameter named "nodeId". The value of this parameter can be a valid document, folder, mail or record UUID or path.

Example of nodeId:

  • Using UUID -> "f123a950-0329-4d62-8328-0ff500fd42db";
  • Using path -> "/okm:root/logo.png"

The class com.openkm.util.ISO8601 should be used to set and parse metadata date fields. The metadata field of type date values is stored in the application in ISO-8601 basic format.

To convert the retrieved metada field of type date to a valid date use:

Calendar cal = ISO8601.parseBasic(metadataFieldValue);

To save the date value in the metadata field of type date use:

Calendar cal = Calendar.getInstance(); // Present date 
String metadataFieldValue = ISO8601.formatBasic(cal);
// metadataFieldValue can be saved into repository metadata field of type date

Also on all methods you'll see parameter named "token". When accessing application across SOAP the login process returns a token, what is used to identify the user on all the exposed methods. From default application execution context you must use "null" value what indicates to the application must use the "user session".

On special cases you might be "promoted as Administrator" using the "administrator token".

String systemToken = DbSessionManager.getInstance().getSystemToken();

Methods

addGroup

Description:

MethodReturn valuesDescription

addGroup(String token, String nodeId, String grpName)

void

Adds an empty metadata group to a node.

The grpName should be a valid Metadata group name.

Example:

package com.openkm;

import com.openkm.api.OKMPropertyGroup;

public class Test {
    public static void main(String[] args) {
        try {           
            OKMPropertyGroup.getInstance().addGroup(null, "/okm:root/logo.png", "okg:consulting");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

removeGroup

Description:

MethodReturn valuesDescription

removeGroup(String token, String nodeId, String grpName)

void

Removes a metadata group of a node.

The grpName should be a valid Metadata group name.

Example:

package com.openkm;

import com.openkm.api.OKMPropertyGroup;

public class Test {
    public static void main(String[] args) {
        try {           
            OKMPropertyGroup.getInstance().removeGroup(null, "/okm:root/logo.png", "okg:consulting");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getGroups

Description:

MethodReturn valuesDescription

getGroups(String token, String nodeId)

List<PropertyGroup>

Retrieves a list of metadata groups assigned to a node.

Example:

package com.openkm;

import com.openkm.api.OKMPropertyGroup;
import com.openkm.bean.PropertyGroup;

public class Test {
    public static void main(String[] args) {
        try {           
            for (PropertyGroup pg : OKMPropertyGroup.getInstance().getGroups(null, "/okm:root/logo.png")) {
                System.out.println(pg);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getAllGroups

Description:

MethodReturn valuesDescription

getAllGroups(String token)

List<PropertyGroup>

Retrieves a list of all metadata groups set into the application.

Example:

package com.openkm;

import com.openkm.api.OKMPropertyGroup;
import com.openkm.bean.PropertyGroup;

public class Test {
    public static void main(String[] args) {
        try {           
            for (PropertyGroup pg : OKMPropertyGroup.getInstance().getAllGroups(null)) {
                System.out.println(pg);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getProperties

Description:

MethodReturn valuesDescription

getProperties(String token, String nodeId, String grpName)

List<FormElement>

Retrieves a list of all metadata group elements and its node values.

The grpName should be a valid Metadata group name.

The method is usually used to display form elements with its values to be shown or changed by used.

Example:

package com.openkm;

import com.openkm.api.OKMPropertyGroup;
import com.openkm.bean.form.FormElement;

public class Test {
    public static void main(String[] args) {
        try {           
            for (FormElement fe : OKMPropertyGroup.getInstance().getProperties(null,"/okm:root/logo.png", "okg:consulting")) {
                System.out.println(fe);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

setProperties

Description:

MethodReturn valuesDescription

setProperties(String token, String nodeId, String grpName, List<FormElement> properties)

void

Changes the metadata group values of a node.

The grpName should be a valid Metadata group name.

It is not mandatory to set in the parameter ofeList all FormElement, it is enought with the formElements you wish to change its values.

The sample below is based on this Metadata group definition:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 2.0//EN"
                                 "http://www.openkm.com/dtd/property-groups-2.0.dtd">
<property-groups>
  <property-group label="Consulting" name="okg:consulting">
    <input label="Name" type="text" name="okp:consulting.name"/>
    <input label="Date" type="date" name="okp:consulting.date" />
    <checkbox label="Important" name="okp:consulting.important"/>
    <textarea label="Comment" name="okp:consulting.comment"/>
  </property-group>
</property-groups>

Example:

package com.openkm;

import java.util.ArrayList;
import java.util.List;

import com.openkm.api.OKMPropertyGroup;
import com.openkm.bean.form.FormElement;
import com.openkm.bean.form.Input;

public class Test {
    public static void main(String[] args) {
        try {                       
            List<FormElement> fElements = OKMPropertyGroup.getInstance().getProperties(null, "/okm:root/logo.pdf","okg:consulting");
            for (FormElement fElement : fElements) {
                if (fElement.getName().equals("okp:consulting.name")) {
                    Input name = (Input) fElement;
                    name.setValue("new value");
                }
            }
            
            OKMPropertyGroup.getInstance().setProperties(null, "/okm:root/logo.pdf", "okg:consulting", fElements);
            
            // Same modification with only affected FormElement
            fElements = new ArrayList<>();
            Input name = new Input();
            name.setName("okp:consulting.name");
            name.setValue("new value");
            fElements.add(name);
            OKMPropertyGroup.getInstance().setProperties(null, "/okm:root/logo.pdf","okg:consulting", fElements);
            
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

setPropertySimple

Description:

MethodReturn valuesDescription

setPropertySimple(String token, String nodeId, String propGroup, String propName, String propValue)

void

Changes the metadata group field value of a node.

The grpName should be a valid Metadata group name.

It is not mandatory to set in the properties parameter all fields values, is enough with the fields you wish to change its values.

The sample below is based on this Metadata group definition:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 2.0//EN"
                                 "http://www.openkm.com/dtd/property-groups-2.0.dtd">
<property-groups>
  <property-group label="Consulting" name="okg:consulting">
    <input label="Name" type="text" name="okp:consulting.name"/>
    <input label="Date" type="date" name="okp:consulting.date" />
    <checkbox label="Important" name="okp:consulting.important"/>
    <textarea label="Comment" name="okp:consulting.comment"/>
  </property-group>
</property-groups>

To add several values on a metadata field of type multiple like this:

<select label="Multiple" name="okp:consulting.multiple" type="multiple">
  <option label="One" value="one"/>
  <option label="Two" value="two"/>
  <option label="Three" value="three" />
</select>

You should do:

"one;two";

Where "one" and "two" are valid values and character ";" is used as separator.

Example:

package com.openkm;

import com.openkm.api.OKMPropertyGroup;

public class Test {
    public static void main(String[] args) {
        try {                       
            OKMPropertyGroup.getInstance().setPropertySimple(null, "/okm:root/logo.pdf","okg:consulting", "okp:consulting.name", "new name");           
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

setPropertiesSimple

Description:

MethodReturn valuesDescription

setPropertiesSimple(String token, String nodeId, String grpName, Map<String, String> properties)

void

Changes the metadata group valuea of a node.

The grpName should be a valid Metadata group name.

It is not mandatory to set in the properties parameter all fields values, is enough with the fields you wish to change its values.

The sample below is based on this Metadata group definition:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 2.0//EN"
                                 "http://www.openkm.com/dtd/property-groups-2.0.dtd">
<property-groups>
  <property-group label="Consulting" name="okg:consulting">
    <input label="Name" type="text" name="okp:consulting.name"/>
    <input label="Date" type="date" name="okp:consulting.date" />
    <checkbox label="Important" name="okp:consulting.important"/>
    <textarea label="Comment" name="okp:consulting.comment"/>
  </property-group>
</property-groups>

To add several values on a metadata field of type multiple like this:

<select label="Multiple" name="okp:consulting.multiple" type="multiple">
  <option label="One" value="one"/>
  <option label="Two" value="two"/>
  <option label="Three" value="three" />
</select>

You should do:

properties.put("okp:consulting.multiple", "one;two");

Where "one" and "two" are valid values and character ";" is used as separator.

Example:

package com.openkm;

import java.util.Calendar;
import java.util.HashMap;
import java.util.Map;

import com.openkm.api.OKMPropertyGroup;
import com.openkm.util.ISO8601;

public class Test {
    public static void main(String[] args) {
        try {                       
            Map<String, String> properties = new HashMap<>();
            properties.put("okp:consulting.name", "new name");
            
            // Date fields must be saved with basic ISO 8601 format
            properties.put("okp:consulting.date", ISO8601.formatBasic(Calendar.getInstance()));
            OKMPropertyGroup.getInstance().setPropertiesSimple(null, "/okm:root/logo.pdf","okg:consulting", properties);           
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getPropertyGroupForm

Description:

MethodReturn valuesDescription

getPropertyGroupForm(String token, String grpName)

List<FormElement>

Retrieves a list of all metadata group elements definition.

The grpName should be a valid Metadata group name.

The method is usually used to display empty form elements for creating new metadata values.

Example:

package com.openkm;

import com.openkm.api.OKMPropertyGroup;
import com.openkm.bean.form.FormElement;

public class Test {
    public static void main(String[] args) {
        try {                       
            for (FormElement fe : OKMPropertyGroup.getInstance().getPropertyGroupForm(null, "okg:consulting")) {
                System.out.println(fe);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

hasGroup

Description:

MethodReturn valuesDescription

hasGroup(String token, String nodeId, String grpName)

boolean

Returns a boolean that indicate if the node has or not a metadata group.

Example:

package com.openkm;

import com.openkm.api.OKMPropertyGroup;

public class Test {
    public static void main(String[] args) {
        try {                       
            boolean found = OKMPropertyGroup.getInstance().hasGroup(null, "/okm:root/logo.pdf", "okg:consulting");
            System.out.println(found);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getSuggestions

Description:

MethodReturn valuesDescription

getSuggestions(String token, String nodeId, String grpName, String propName)

List<String>

Retrieves a list of a suggested metadata field values.

The propName parameter should be a Metadata Select field type.

More information at cCreating your own Suggestion Analyzer and Metadata Select field .

The sample below is based on this Metadata group definition:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 2.0//EN"
                                 "http://www.openkm.com/dtd/property-groups-2.0.dtd">
<property-groups>
  <property-group label="Technology" name="okg:technology">
    <select label="Type" name="okp:technology.type" type="multiple">
      <option label="Alfa" value="t1"/>
      <option label="Beta" value="t2" />
      <option label="Omega" value="t3" />
    </select>
    <select label="Language" name="okp:technology.language" type="simple">
      <option label="Java" value="java"/>
      <option label="Python" value="python"/>
      <option label="PHP" value="php" />
    </select>
    <input label="Comment" name="okp:technology.comment"/>
    <textarea label="Description" name="okp:technology.description"/>
    <input label="Link" type="link" name="okp:technology.link"/>
  </property-group>
</property-groups>

 

Example:

package com.openkm;

import com.openkm.api.OKMPropertyGroup;

public class Test {
    public static void main(String[] args) {
        try {                       
            for (String value : OKMPropertyGroup.getInstance().getSuggestions(null, "/okm:root/logo.pdf","okg:technology", "okp:technology.language")) {
                System.out.println(value);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

registerDefinition

Description:

MethodReturn valuesDescription

registerDefinition(String token, String pgDef)

void

Set the XML Metada groups definition into the $TOMCAT_HOME/PropertyGroups.xml file.

The method only can be executed by super user granted ( ROLE_ADMIN member user).

Take in mind chaging metadata is done in two steps, first modifiying PropertyGroups.xml file and then registering the changing. For the second step take a loot at registerPropertyGroups method in OKMRepository class for it.

Example:

package com.openkm;

import java.io.FileInputStream;
import java.io.InputStream;

import org.apache.commons.io.IOUtils;

import com.openkm.api.OKMPropertyGroup;

public class Test {
    public static void main(String[] args) {
        InputStream is = null;
        try {
            is = new FileInputStream("/home/files/PropertyGroups.xml");
            String pgDef = IOUtils.toString(is);
            OKMPropertyGroup.getInstance().registerDefinition(null, pgDef);
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            IOUtils.closeQuietly(is);
        }
    }
}