Connection URL

The OpenKM application context is named OpenKM.

OpenKM application context is named openkm ( lowercase ).

Meanwhile connection URL in version 2.x is something like "http://localhost:8080/OpenKM" in version 3.x should be used something like "http://localhost:8080/openkm".

Create new  instance

The new instance is created with host, username, and password parameters.

The new instance is created with the host.

Because of a major change in the authentication architecture, the instance creation is quite different. In version 2.x the REST authentication works with basic authentication, which means each time it is executed an action the SDK authenticates with username and password. In version 3.x REST authentication works with several authentication procedures like basic and token. In version 3.x token authentication is used intensively. The token by default expires in 24 hours ( take a look in the documentation to get more details about the login feature ) and after the login method is executed the token will be reused by SDK in all the actions executed.

Sample for version 2.x:

package com.openkm;

import com.openkm.sdk4j.OKMWebservices;
import com.openkm.sdk4j.OKMWebservicesFactory;

public class Test {
    public static void main(String[] args) {
        String host = "http://localhost:8080/OpenKM";
        String username = "okmAdmin";
        String password = "admin";
        OKMWebservices ws = OKMWebservicesFactory.newInstance(host, username, password);
    }
}

Sample for version 3.x:

package com.openkm;

import com.openkm.sdk4j.OKMWebservicesFactory;
import com.openkm.sdk4j.bean.Folder;
import com.openkm.sdk4j.impl.OKMWebservices;

public class Test {

    public static void main(String[] args) {
        String host = "http://localhost:8080/openkm";
        String user = "okmAdmin";
        String password = "admin";
        OKMWebservices ws = OKMWebservicesFactory.getInstance(host);

        try {
            ws.login(user, password);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Methods

All the methods are the parent of class OKMWebservices.

The methods are a parent of subclass into OKMWebservices.

Because the SDK has more than 400 methods and growing was a little mess have everything in the same parent. That's why in version 3.x decided to split methods based on their goal.

Methods related to document action will be accessible from ws.document, etc.. in this manner when you choose a method can clearly identify its purpose.

The sample below is shown how to create a folder with ws.folder.createFolder method:

package com.openkm;

import com.openkm.sdk4j.OKMWebservicesFactory;
import com.openkm.sdk4j.bean.Folder;
import com.openkm.sdk4j.impl.OKMWebservices;

public class Test {

    public static void main(String[] args) {
        String host = "http://localhost:8080/openkm";
        String user = "okmAdmin";
        String password = "admin";
        OKMWebservices ws = OKMWebservicesFactory.getInstance(host);

        try {
            ws.login(user, password);
            Folder folder = ws.folder.createFolder("1be884f4-5758-4985-94d1-f18bfe004db8", "test");
            System.out.println(folder);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Nodes ID

In almost methods can use the path or the node UUID.

In almost methods only can be used the node UUID.

This is a major improvement in version 3.x API because is not a good practice use path either UUID.

The reason in deep is that when working with the path the OpenKM core must convert internally the path in the UUID and this action consumes hardware time and resources.

You can emulate the same behavior in version 3.x converting the path to UUID and then executing the action. But we encourage using only the UUID in the whole application.

Sample for version 2.x:

package com.openkm;

import com.openkm.sdk4j.OKMWebservices;
import com.openkm.sdk4j.OKMWebservicesFactory;
import com.openkm.sdk4j.bean.form.FormElement;

public class Test {
    public static void main(String[] args) {
        String host = "http://localhost:8080/OpenKM";
        String username = "okmAdmin";
        String password = "admin";
        OKMWebservices ws = OKMWebservicesFactory.newInstance(host, username, password);
        
        try {
            for (FormElement fElement : ws.getPropertyGroupProperties("/okm:root/logo.pdf", "okg:consulting")) {
                System.out.println(fElement);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

How to simulate the behavior of version 2.x in version 3.x:

package com.openkm;

import com.openkm.sdk4j.OKMWebservicesFactory;
import com.openkm.sdk4j.impl.OKMWebservices;

public class Test {

    public static void main(String[] args) {
        String host = "http://localhost:8080/openkm";
        String user = "okmAdmin";
        String password = "admin";
        OKMWebservices ws = OKMWebservicesFactory.getInstance(host);

        try {
            ws.login(user, password);
            // Exists folder /okm:root/test
            String uuid = ws.repository.getNodeUuid("/okm:root/test");
            ws.folder.renameFolder(uuid, "renamedFolder");
            // Folder has renamed to /okm:root/renamedFolder
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Create metadata

In version 2.x is required to execute two methods to add a metadata group. In version 3.x with a single method execution are added metadata groups and fields.

In version 2.x the values of the fields are set in a list of FormElement objects meanwhile in version 3.x the values go into a map of pairs of type (key, value).

Sample for version 2.x

package com.openkm;

import com.openkm.sdk4j.OKMWebservices;
import com.openkm.sdk4j.OKMWebservicesFactory;

public class Test {
    public static void main(String[] args) {
        String host = "http://localhost:8080/OpenKM";
        String username = "okmAdmin";
        String password = "admin";
        OKMWebservices ws = OKMWebservicesFactory.newInstance(host, username, password);
        
        try {
            ws.addGroup("/okm:root/logo.pdf", "okg:consulting");

            // Modify with a full FormElement list
            List<FormElement> fElements =  ws.getPropertyGroupProperties("/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");
                }
            }
            
            ws.setPropertyGroupProperties("/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);
            ws.setPropertyGroupProperties("/okm:root/logo.pdf","okg:consulting", fElements);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Sample for version 3.x

package com.openkm;

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

import com.openkm.sdk4j.OKMWebservicesFactory;
import com.openkm.sdk4j.impl.OKMWebservices;
import com.openkm.sdk4j.util.ISO8601;

public class Test {

    public static void main(String[] args) {
        String host = "http://localhost:8080/openkm";
        String user = "okmAdmin";
        String password = "admin";
        OKMWebservices ws = OKMWebservicesFactory.getInstance(host);

        try {
            ws.login(user, password);
            Map<String, String> propertiesMap = new HashMap<>();
            propertiesMap.put("okp:consulting.name", "new name");
            // Date fields must be saved with basic ISO 8601 format
            propertiesMap.put("okp:consulting.date", ISO8601.formatBasic(Calendar.getInstance()));
            propertiesMap.put("okp:consulting.comment", "new comment");

            ws.propertyGroup.addPropertyGroup("8cd1e072-8595-4dd3-b121-41d622c43f08", "okg:consulting", propertiesMap);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Get metadata

In version 2.x the metadata values are returned in a list of FormElement. In case you build a user interface with metadata fields, the main advantage of version 2.x values, and field information goes in the same call. In version 3.x the values are returned in a map of pairs of type (key, value). The main advantage of version 3.x is that returns only the information you need, the values, not additional information like field type, etc... which is only required for rendering in the user interface. In case you need rendering information there's another specific method for it purpose that retrieves the FormElement list that must be used in combination with metadata values. In terms of performance version 3.x is faster than 2.x

Sample for version 2.x:

package com.openkm;

import com.openkm.sdk4j.OKMWebservices;
import com.openkm.sdk4j.OKMWebservicesFactory;
import com.openkm.sdk4j.bean.form.FormElement;

public class Test {
    public static void main(String[] args) {
        String host = "http://localhost:8080/OpenKM";
        String username = "okmAdmin";
        String password = "admin";
        OKMWebservices ws = OKMWebservicesFactory.newInstance(host, username, password);
        
        try {
            for (FormElement fElement : ws.getPropertyGroupProperties("/okm:root/logo.pdf", "okg:consulting")) {
                System.out.println(fElement);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Sample for version 3.x:

package com.openkm;

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

import com.openkm.sdk4j.OKMWebservicesFactory;
import com.openkm.sdk4j.impl.OKMWebservices;

public class Test {

    public static void main(String[] args) {
        String host = "http://localhost:8080/openkm";
        String user = "okmAdmin";
        String password = "admin";
        OKMWebservices ws = OKMWebservicesFactory.getInstance(host);

        try {
            ws.login(user, password);
            Map<String, String> properties = new HashMap<>();
            properties = ws.propertyGroup.getPropertyGroupProperties("8cd1e072-8595-4dd3-b121-41d622c43f08", "okg:technology");

            for (String key : properties.keySet()) {
                System.out.println(key + " > " + properties.get(key));
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}