# OpenKM 8.2 - API Reference

> This document is intended for LLM consumption. It consolidates the complete API documentation for OpenKM 8.2.
> Source: https://docs.openkm.com/kcenter/view/okm-8.2/
> Compatibility: OpenKM Professional 8.2

---

## Overview

OpenKM is a document management system (DMS) that provides a Java API for building applications integrated with OpenKM. The API is organized into facade classes (e.g. `OKMDocument`, `OKMFolder`, `OKMActivity`) that delegate to the underlying module layer.

### Obtaining an API instance

All API classes are Spring components. Obtain an instance via the Spring application context:

```java
import com.openkm.util.ContextWrapper;

OKMActivity okmActivity = ContextWrapper.getContext().getBean(OKMActivity.class);
```

### Token parameter

Every API method accepts a `String token` as its first parameter. Pass `null` to use the current authenticated user's session.

---

## OKMActivity

`com.openkm.api.OKMActivity`

Provides access to OpenKM's activity log data.

### Methods

| Method | Returns | Description |
|--------|---------|-------------|
| `findByFilter(String token, ActivityFilter filter)` | `List<Activity>` | Returns activity log entries matching the given filter. |
| `countByFilter(String token, ActivityFilter filter)` | `int` | Returns the number of activity log entries matching the given filter. |
| `getActions(String token)` | `List<String>` | Returns the list of all available activity log action names. |

### Exceptions

All methods may throw `DatabaseException` and `AccessDeniedException`.

---

### ActivityFilter

`com.openkm.db.bean.ActivityFilter`

Filter criteria used by `findByFilter` and `countByFilter`.

| Field | Type | Description |
|-------|------|-------------|
| `begin` | `Calendar` | Start date (inclusive). |
| `end` | `Calendar` | End date (inclusive). |
| `user` | `String` | Filter by username. |
| `action` | `String` | Filter by action name. |
| `item` | `String` | Filter by item UUID. |
| `offset` | `Integer` | Pagination offset (zero-based). |
| `limit` | `Integer` | Maximum number of results to return. |

---

### Activity

`com.openkm.db.bean.Activity`

Represents a single activity log entry.

| Field | Type | Description |
|-------|------|-------------|
| `id` | `long` | Unique identifier. |
| `tenant` | `String` | Tenant identifier. |
| `date` | `Calendar` | Date and time of the activity. |
| `user` | `String` | User who performed the action. |
| `action` | `String` | Action performed. |
| `item` | `String` | UUID of the item involved. |
| `path` | `String` | Path of the item at the time of the action. |
| `params` | `String` | Additional parameters. |
| `ip` | `String` | IP address of the client. |

---

### findByFilter

Returns a list of activity log entries matching the given filter.

```java
package com.openkm;

import java.util.Calendar;

import com.openkm.api.OKMActivity;
import com.openkm.db.bean.Activity;
import com.openkm.db.bean.ActivityFilter;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMActivity okmActivity = ContextWrapper.getContext().getBean(OKMActivity.class);

            Calendar beginDate = Calendar.getInstance();
            beginDate.add(Calendar.MONTH, -1);
            Calendar endDate = Calendar.getInstance();

            ActivityFilter filter = new ActivityFilter();
            filter.setBegin(beginDate);
            filter.setEnd(endDate);
            filter.setItem("f84a2e1f-a858-4e53-9c09-36519d903782");
            filter.setUser("okmAdmin");
            filter.setOffset(0);
            filter.setLimit(20);

            for (Activity activity : okmActivity.findByFilter(null, filter)) {
                System.out.println(activity);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### countByFilter

Returns the number of activity log entries matching the given filter.

```java
package com.openkm;

import java.util.Calendar;

import com.openkm.api.OKMActivity;
import com.openkm.db.bean.ActivityFilter;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMActivity okmActivity = ContextWrapper.getContext().getBean(OKMActivity.class);

            Calendar beginDate = Calendar.getInstance();
            beginDate.add(Calendar.MONTH, -1);
            Calendar endDate = Calendar.getInstance();

            ActivityFilter filter = new ActivityFilter();
            filter.setBegin(beginDate);
            filter.setEnd(endDate);
            filter.setItem("f84a2e1f-a858-4e53-9c09-36519d903782");
            filter.setUser("okmAdmin");
            filter.setOffset(0);
            filter.setLimit(20);

            System.out.println(okmActivity.countByFilter(null, filter));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### getActions

Returns the list of all available activity log action names.

```java
package com.openkm;

import com.openkm.api.OKMActivity;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMActivity okmActivity = ContextWrapper.getContext().getBean(OKMActivity.class);

            for (String action : okmActivity.getActions(null)) {
                System.out.println(action);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

## OKMAuth

`com.openkm.api.OKMAuth`

Used for managing security and users. For example, add or remove grants on a node, create or modify users, or get the profiles.

### Basics

The class `com.openkm.bean.Permission` contains permission values. Use it when calling methods that change or read security grants.

```java
// Set READ and WRITE access
int permission = Permission.READ + Permission.WRITE;

// Check if a permission value includes WRITE
if ((permission & Permission.WRITE) == Permission.WRITE) {
    // Has WRITE grants.
}
```

The `nodeId` parameter accepts a node UUID (folder, document, mail, or record):

```
"b153c4b7-3d1c-4589-bd42-0ed0f34fd338"
```

To obtain the administrator token (promotes the call to superuser context):

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

### Methods

| Method | Returns | Description |
|--------|---------|-------------|
| `login()` | `void` | Simulates the user UI login process, creating user-specific nodes (e.g. `/okm:trash/userId`). Must be called before using other API methods if the user has never logged in via UI. |
| `login(String user, String pass)` | `String` | Authenticates a user and returns a token valid for 24 hours. |
| `logout(String token)` | `void` | Executes logout on the OpenKM side. |
| `grantUser(String token, String nodeId, String user, int permissions, boolean recursive)` | `void` | Adds a user grant on a node. |
| `revokeUser(String token, String nodeId, String user, int permissions, boolean recursive)` | `void` | Removes a user grant on a node. |
| `getGrantedUsers(String token, String nodeId)` | `Map<String, Integer>` | Returns the granted users of a node. |
| `setUserPermissions(String token, String nodeId, String user, int permissions, boolean recursive)` | `void` | Replaces (overwrites) user permissions on a node. |
| `grantRole(String token, String nodeId, String role, int permissions, boolean recursive)` | `void` | Adds a role grant on a node. |
| `revokeRole(String token, String nodeId, String role, int permissions, boolean recursive)` | `void` | Removes a role grant on a node. |
| `getGrantedRoles(String token, String nodeId)` | `Map<String, Integer>` | Returns the granted roles of a node. |
| `setRolePermissions(String token, String nodeId, String role, int permissions, boolean recursive)` | `void` | Replaces (overwrites) role permissions on a node. |
| `changeSecurity(String token, String nodeId, Map<String, Integer> grantUsers, Map<String, Integer> revokeUsers, Map<String, Integer> grantRoles, Map<String, Integer> revokeRoles, boolean recursive)` | `void` | Applies incremental security changes on a node. |
| `overwriteSecurity(String token, String nodeId, Map<String, Integer> grantUsers, Map<String, Integer> grantRoles, boolean recursive)` | `void` | Replaces all security grants on a node. |
| `getUsers(String token, boolean filterByActive)` | `List<DbUser>` | Returns all users. When `filterByActive` is `true`, returns only active users. |
| `getUser(String token, String userId)` | `DbUser` | Returns data for a specific user. |
| `userExist(String token, String userId)` | `Boolean` | Returns `true` if the user exists. |
| `getRoles(String token, boolean filterByActive)` | `List<String>` | Returns all roles. When `filterByActive` is `true`, returns only active roles. |
| `getUsersByRole(String token, String role)` | `List<DbUser>` | Returns all users assigned to a role. |
| `getRolesByUser(String token, String user)` | `List<String>` | Returns all roles assigned to a user. |
| `createUser(String token, DbUser user)` | `DbUser` | Creates a new user and returns the created object. |
| `deleteUser(String token, String user)` | `void` | Deletes a user. |
| `updateUser(String token, DbUser user)` | `DbUser` | Updates a user and returns the updated object. |
| `activateUser(String token, String user, boolean active)` | `void` | Activates or deactivates a user. |
| `createRole(String token, Role role)` | `void` | Creates a new role. |
| `deleteRole(String token, String role)` | `void` | Deletes a role. |
| `updateRole(String token, String role, boolean active)` | `void` | Updates a role's active status. |
| `assignRole(String token, String user, String role)` | `void` | Assigns a role to a user. |
| `removeRole(String token, String user, String role)` | `void` | Removes a role from a user. |
| `getProfiles(String token, boolean filterByActive)` | `List<Profile>` | Returns all profiles. When `filterByActive` is `true`, returns only active profiles. |
| `getUserProfile(String token, String userId)` | `Profile` | Returns the profile assigned to a user. |
| `setUserProfile(String token, String userId, long profileId)` | `void` | Changes the profile assigned to a user. |
| `getUserTenants(String token)` | `List<Tenant>` | Returns the tenants to which the current user has access. |
| `setUserTenant(String token, long tenantId)` | `void` | Changes the active tenant for the current user. |
| `isPasswordExpired(String token)` | `Boolean` | Returns `true` if the current user's password has expired. |
| `resetPassword(String userId)` | `void` | Sends a password reset email to the user. |

### Exceptions

Methods may throw `AccessDeniedException`, `DatabaseException`, `RepositoryException`, `PathNotFoundException`, and `AuthException` depending on the operation.

---

### DbUser

`com.openkm.db.bean.DbUser`

Represents an OpenKM user.

| Field | Type | Description |
|-------|------|-------------|
| `id` | `String` | User identifier (login name). |
| `name` | `String` | Display name. |
| `password` | `String` | Password (write-only; not returned in read operations). |
| `email` | `String` | Email address. |
| `active` | `Boolean` | Whether the user is active. |
| `secret` | `String` | Two-factor authentication secret. |
| `passwordChanged` | `Calendar` | Date of last password change. |
| `created` | `Calendar` | Account creation date. |
| `lastLogin` | `Calendar` | Date of last login. |
| `roles` | `Set<DbRole>` | Roles assigned to the user. |

---

### Role

`com.openkm.bean.Role`

Represents an OpenKM role.

| Field | Type | Description |
|-------|------|-------------|
| `id` | `String` | Role identifier (e.g. `ROLE_USER`, `ROLE_ADMIN`). |
| `active` | `Boolean` | Whether the role is active. |

---

### Tenant

`com.openkm.db.bean.Tenant`

Represents a tenant in a multi-tenant deployment.

| Field | Type | Description |
|-------|------|-------------|
| `id` | `Long` | Tenant identifier. |
| `name` | `String` | Tenant name. |

---

### login()

Simulates the user UI login process. Must be called when using the API for the first time with a user who has never logged in via the UI, to ensure user-specific folders (e.g. `/okm:trash/userId`) are created.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            okmAuth.login();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### login(String user, String pass)

Authenticates a user and returns a token valid for 24 hours. Each call replaces the previous token.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            String token = okmAuth.login("userId", "password");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### logout

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            okmAuth.logout(null);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### grantUser

Adds user grants on a node. When `recursive` is `true`, the grant is applied to the node and all its descendants (only meaningful for folder and record nodes).

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.bean.Permission;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);

            // Grant all permissions to sochoa on the node only
            okmAuth.grantUser(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "sochoa", Permission.ALL_GRANTS, false);

            // Grant all permissions to okmAdmin on the node and descendants
            okmAuth.grantUser(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "okmAdmin", Permission.ALL_GRANTS, true);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### revokeUser

Removes user grants on a node. When `recursive` is `true`, the revocation is applied to the node and all its descendants.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.bean.Permission;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);

            // Revoke all grants from sochoa on the node only
            okmAuth.revokeUser(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "sochoa", Permission.ALL_GRANTS, false);

            // Revoke all grants from okmAdmin on the node and descendants
            okmAuth.revokeUser(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "okmAdmin", Permission.ALL_GRANTS, true);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### getGrantedUsers

Returns a map of username → permission bitmask for all users with grants on the node.

```java
package com.openkm;

import java.util.Map;

import com.openkm.api.OKMAuth;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);

            Map<String, Integer> grants = okmAuth.getGrantedUsers(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338");
            for (String user : grants.keySet()) {
                System.out.println(user + " -> " + grants.get(user));
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### grantRole

Adds role grants on a node. When `recursive` is `true`, the grant is applied to the node and all its descendants.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.bean.Permission;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);

            // Grant all permissions to ROLE_USER on the node only
            okmAuth.grantRole(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "ROLE_USER", Permission.ALL_GRANTS, false);

            // Grant all permissions to ROLE_ADMIN on the node and descendants
            okmAuth.grantRole(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "ROLE_ADMIN", Permission.ALL_GRANTS, true);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### revokeRole

Removes role grants on a node.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.bean.Permission;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);

            // Revoke all grants from ROLE_USER on the node only
            okmAuth.revokeRole(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "ROLE_USER", Permission.ALL_GRANTS, false);

            // Revoke all grants from ROLE_ADMIN on the node and descendants
            okmAuth.revokeRole(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "ROLE_ADMIN", Permission.ALL_GRANTS, true);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### getGrantedRoles

Returns a map of role → permission bitmask for all roles with grants on the node.

```java
package com.openkm;

import java.util.Map;

import com.openkm.api.OKMAuth;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);

            Map<String, Integer> grants = okmAuth.getGrantedRoles(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338");
            for (String role : grants.keySet()) {
                System.out.println(role + " -> " + grants.get(role));
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### changeSecurity

Applies incremental security changes on a node in a single call: grants and revocations for users and roles.

```java
package com.openkm;

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

import com.openkm.api.OKMAuth;
import com.openkm.bean.Permission;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            String nodeId = "b153c4b7-3d1c-4589-bd42-0ed0f34fd338";
            Map<String, Integer> grantUsers = new HashMap<>();
            Map<String, Integer> revokeUsers = new HashMap<>();
            Map<String, Integer> grantRoles = new HashMap<>();
            grantRoles.put("ROLE_TEST", Permission.READ | Permission.WRITE);
            Map<String, Integer> revokeRoles = new HashMap<>();
            okmAuth.changeSecurity(null, nodeId, grantUsers, revokeUsers, grantRoles, revokeRoles, false);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### overwriteSecurity

Replaces all existing grants on a node with the specified grants.

```java
package com.openkm;

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

import com.openkm.api.OKMAuth;
import com.openkm.bean.Permission;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            String nodeId = "b153c4b7-3d1c-4589-bd42-0ed0f34fd338";
            Map<String, Integer> grantUsers = new HashMap<>();
            Map<String, Integer> grantRoles = new HashMap<>();
            grantRoles.put("ROLE_TEST", Permission.READ | Permission.WRITE);
            okmAuth.overwriteSecurity(null, nodeId, grantUsers, grantRoles, false);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### getUsers

Returns the list of users. When `filterByActive` is `true`, only active users are returned.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.db.bean.DbUser;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            for (DbUser user : okmAuth.getUsers(null, true)) {
                System.out.println(user.getId());
                System.out.println(user.getName());
                System.out.println(user.getEmail());
                System.out.println(user.getActive());
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### getUser

Returns data for a specific user.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.db.bean.DbUser;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            DbUser user = okmAuth.getUser(null, "okmAdmin");
            System.out.println(user);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### userExist

Returns `true` if a user with the given ID exists.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            System.out.println(okmAuth.userExist(null, "okmAdmin"));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### getRoles

Returns the list of roles. When `filterByActive` is `true`, only active roles are returned.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            for (String role : okmAuth.getRoles(null, true)) {
                System.out.println(role);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### getUsersByRole

Returns all users assigned to a given role.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.db.bean.DbUser;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            for (DbUser user : okmAuth.getUsersByRole(null, "ROLE_ADMIN")) {
                System.out.println(user.getId());
                System.out.println(user.getName());
                System.out.println(user.getEmail());
                System.out.println(user.getActive());
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### getRolesByUser

Returns all roles assigned to a given user.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            for (String role : okmAuth.getRolesByUser(null, "okmAdmin")) {
                System.out.println(role);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### createUser

Creates a new user and returns the created `DbUser` object.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.db.bean.DbUser;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            DbUser user = new DbUser();
            user.setId("test");
            user.setPassword("password.2019");
            user.setEmail("some@mail.com");
            user.setName("User Name");
            user.setActive(true);
            DbUser created = okmAuth.createUser(null, user);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### deleteUser

Deletes a user.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            okmAuth.deleteUser(null, "test");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### updateUser

Updates a user and returns the updated `DbUser` object.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.db.bean.DbUser;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            DbUser user = new DbUser();
            user.setId("test");
            user.setPassword("newpassword");
            user.setEmail("some@mail.com");
            user.setName("Test");
            user.setActive(false);
            DbUser updated = okmAuth.updateUser(null, user);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### activateUser

Activates or deactivates a user.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            okmAuth.activateUser(null, "test", false);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### createRole

Creates a new role.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.bean.Role;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            Role role = new Role();
            role.setId("ROLE_TEST");
            role.setActive(true);
            okmAuth.createRole(null, role);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### deleteRole

Deletes a role.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            okmAuth.deleteRole(null, "ROLE_TEST");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### updateRole

Updates a role's active status.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            okmAuth.updateRole(null, "ROLE_TEST", true);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### assignRole

Assigns a role to a user.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            okmAuth.assignRole(null, "test", "ROLE_USER");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### removeRole

Removes a role from a user.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            okmAuth.removeRole(null, "test", "ROLE_USER");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### getProfiles

Returns the list of profiles. When `filterByActive` is `true`, only active profiles are returned. Each user is assigned one profile that controls which OpenKM UI features are enabled.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.db.bean.Profile;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            for (Profile profile : okmAuth.getProfiles(null, true)) {
                System.out.println(profile);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### getUserProfile

Returns the profile assigned to a user.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            System.out.println(okmAuth.getUserProfile(null, "okmAdmin"));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### setUserProfile

Changes the profile assigned to a user.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.db.bean.Profile;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            for (Profile profile : okmAuth.getProfiles(null, true)) {
                if (profile.getName().equals("default")) {
                    okmAuth.setUserProfile(null, "okmAdmin", profile.getId());
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### getUserTenants

Returns the list of tenants the current user has access to.

```java
package com.openkm;

import java.util.List;

import com.openkm.api.OKMAuth;
import com.openkm.db.bean.Tenant;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            List<Tenant> tenants = okmAuth.getUserTenants(null);
            for (Tenant tenant : tenants) {
                System.out.println(tenant);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### setUserTenant

Changes the active tenant for the current user. A user can have access to multiple tenants but only one is active at a time.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            okmAuth.setUserTenant(null, 1L);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### isPasswordExpired

Returns `true` if the current user's password has expired.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            Boolean isExpired = okmAuth.isPasswordExpired(null);
            System.out.println(isExpired);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### resetPassword

Sends a password reset email to the specified user.

```java
package com.openkm;

import com.openkm.api.OKMAuth;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMAuth okmAuth = ContextWrapper.getContext().getBean(OKMAuth.class);
            okmAuth.resetPassword("okmAdmin");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

## OKMBookmark

`com.openkm.api.OKMBookmark`

Used for managing bookmarks for users. For example, add or remove a bookmark on a node.

### Methods

| Method | Returns | Description |
|--------|---------|-------------|
| `add(String token, String nodeId, String name)` | `Bookmark` | Adds a new bookmark for a node. |
| `get(String token, int bmId)` | `Bookmark` | Returns the bookmark data for the given ID. |
| `remove(String token, int bmId)` | `void` | Deletes a bookmark. |
| `rename(String token, int bmId, String newName)` | `Bookmark` | Renames a bookmark. |
| `getAll(String token)` | `List<Bookmark>` | Returns all bookmarks of the logged-in user. |

### Exceptions

Methods may throw `AccessDeniedException`, `PathNotFoundException`, `RepositoryException`, and `DatabaseException`.

---

### Bookmark

`com.openkm.db.bean.Bookmark`

Represents a user bookmark on a node.

| Field | Type | Description |
|-------|------|-------------|
| `id` | `Long` | Unique bookmark identifier. |
| `user` | `String` | Owner of the bookmark. |
| `name` | `String` | Display name of the bookmark. |
| `node` | `String` | UUID of the bookmarked node. |
| `type` | `String` | Type of the bookmarked node (document, folder, mail, record). |
| `path` | `String` | Path of the bookmarked node. |

---

### add

Adds a new bookmark for a node. The `name` parameter sets the display name of the bookmark.

```java
package com.openkm;

import com.openkm.api.OKMBookmark;
import com.openkm.db.bean.Bookmark;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMBookmark okmBookmark = ContextWrapper.getContext().getBean(OKMBookmark.class);
            Bookmark bookmark = okmBookmark.add(null, "3887ae75-dd67-4019-b4d1-2f6962815403", "document.doc");
            System.out.println(bookmark);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### get

Returns the bookmark data for the given bookmark ID.

```java
package com.openkm;

import com.openkm.api.OKMBookmark;
import com.openkm.db.bean.Bookmark;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMBookmark okmBookmark = ContextWrapper.getContext().getBean(OKMBookmark.class);
            int bmId = 2;
            Bookmark bookmark = okmBookmark.get(null, bmId);
            System.out.println(bookmark);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### remove

Deletes a bookmark by its ID.

```java
package com.openkm;

import com.openkm.api.OKMBookmark;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMBookmark okmBookmark = ContextWrapper.getContext().getBean(OKMBookmark.class);
            int bmId = 23;
            okmBookmark.remove(null, bmId);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### rename

Renames a bookmark.

```java
package com.openkm;

import com.openkm.api.OKMBookmark;
import com.openkm.db.bean.Bookmark;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMBookmark okmBookmark = ContextWrapper.getContext().getBean(OKMBookmark.class);
            int bmId = 2;
            Bookmark bookmark = okmBookmark.rename(null, bmId, "newname.doc");
            System.out.println(bookmark);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### getAll

Returns all bookmarks of the logged-in user.

```java
package com.openkm;

import com.openkm.api.OKMBookmark;
import com.openkm.db.bean.Bookmark;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMBookmark okmBookmark = ContextWrapper.getContext().getBean(OKMBookmark.class);
            for (Bookmark bookmark : okmBookmark.getAll(null)) {
                System.out.println(bookmark);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

## OKMDashboard

`com.openkm.api.OKMDashboard`

Provides access to dashboard data: user activity, subscriptions, locked nodes, and repository-wide statistics.

### Result types

Methods return typed `ResultSet` objects (with `getTotal()` and `getResults()`) or plain `List` depending on the method:

| ResultSet class | Package | Element type |
|---|---|---|
| `DashboardDocumentResultSet` | `com.openkm.ws.rest.util` | `DashboardDocumentResult` |
| `DashboardFolderResultSet` | `com.openkm.bean` | `DashboardFolderResult` |
| `DashboardRecordResultSet` | `com.openkm.bean` | `DashboardRecordResult` |
| `DashboardMailResultSet` | `com.openkm.bean` | `DashboardMailResult` |

Each result element has:

| Field | Type | Description |
|---|---|---|
| `document` / `folder` / `record` / `mail` / `node` | bean | The node object. |
| `visited` | `boolean` | Whether the current user has visited this entry. |
| `date` | `Calendar` | Date of the activity. |

### Pagination

All paginated methods accept `int offset` (zero-based, number of results to skip) and `int limit` (maximum results to return).

### Methods

| Method | Returns | Description |
|--------|---------|-------------|
| `getUserCheckedOutDocuments(String token, int offset, int limit)` | `DashboardDocumentResultSet` | Documents checked out by the current user. |
| `getUserLastModifiedDocuments(String token, int offset, int limit)` | `DashboardDocumentResultSet` | Documents most recently modified by the current user. |
| `getUserLockedDocuments(String token, int offset, int limit)` | `DashboardDocumentResultSet` | Documents locked by the current user. |
| `getUserLockedRecords(String token, int offset, int limit)` | `DashboardRecordResultSet` | Records locked by the current user. |
| `getUserLockedFolders(String token, int offset, int limit)` | `DashboardFolderResultSet` | Folders locked by the current user. |
| `getUserLockedMails(String token, int offset, int limit)` | `DashboardMailResultSet` | Mails locked by the current user. |
| `getUserSubscribedDocuments(String token, int offset, int limit)` | `DashboardDocumentResultSet` | Documents subscribed to by the current user. |
| `getUserSubscribedFolders(String token, int offset, int limit)` | `DashboardFolderResultSet` | Folders subscribed to by the current user. |
| `getUserSubscribedRecords(String token, int offset, int limit)` | `DashboardRecordResultSet` | Records subscribed to by the current user. |
| `getUserLastCreatedDocuments(String token, int offset, int limit)` | `DashboardDocumentResultSet` | Documents most recently created by the current user. |
| `getUserLastCreatedDocumentsNotes(String token, int offset, int limit)` | `DashboardDocumentResultSet` | Documents/notes most recently created by the current user. |
| `getUserLastCreatedFolders(String token, int offset, int limit)` | `DashboardFolderResultSet` | Folders most recently created by the current user. |
| `getUserLastCreatedFoldersNotes(String token, int offset, int limit)` | `DashboardFolderResultSet` | Folders/notes most recently created by the current user. |
| `getUserLastCreatedRecords(String token, int offset, int limit)` | `DashboardRecordResultSet` | Records most recently created by the current user. |
| `getUserLastCreatedRecordsNotes(String token, int offset, int limit)` | `DashboardRecordResultSet` | Records/notes most recently created by the current user. |
| `getUserLastDownloadedDocuments(String token, int offset, int limit)` | `DashboardDocumentResultSet` | Documents most recently downloaded by the current user. |
| `getUserLastImportedMails(String token, int offset, int limit)` | `DashboardMailResultSet` | Mails most recently imported by the current user. |
| `getUserLastCreatedMailsNotes(String token, int offset, int limit)` | `DashboardMailResultSet` | Mails/notes most recently created by the current user. |
| `getUserLastImportedMailAttachments(String token, int offset, int limit)` | `DashboardDocumentResultSet` | Mail attachments most recently imported by the current user. |
| `getUserDocumentsSize(String token)` | `long` | Total size in bytes of all documents owned by the current user (including all versions). |
| `getUserSearches(String token)` | `List<QueryParams>` | Saved searches ("user news") belonging to the current user. |
| `getSharedSearches(String token)` | `List<QueryParams>` | Shared searches visible to the current user. |
| `find(String token, int qpId)` | `List<DashboardNodeResult>` | Executes a saved search by its ID and returns matching nodes. |
| `getLastWeekTopDownloadedDocuments(String token, int offset, int limit)` | `List<DashboardDocumentResult>` | Top downloaded documents across all users in the last week. |
| `getLastMonthTopDownloadedDocuments(String token, int offset, int limit)` | `List<DashboardDocumentResult>` | Top downloaded documents across all users in the last month. |
| `getLastWeekTopModifiedDocuments(String token, int offset, int limit)` | `List<DashboardDocumentResult>` | Top modified documents across all users in the last week. |
| `getLastMonthTopModifiedDocuments(String token, int offset, int limit)` | `List<DashboardDocumentResult>` | Top modified documents across all users in the last month. |
| `getLastModifiedDocuments(String token, int offset, int limit)` | `List<DashboardDocumentResult>` | Most recently modified documents across all users. |
| `getLastCreatedDocuments(String token, int offset, int limit)` | `List<DashboardDocumentResult>` | Most recently created documents across all users. |
| `getLastCheckedOutDocuments(String token, int offset, int limit)` | `List<DashboardDocumentResult>` | Most recently checked-out documents across all users. |
| `getLastCreatedFolders(String token, int offset, int limit)` | `List<DashboardFolderResult>` | Most recently created folders across all users. |
| `getLastCreatedRecords(String token, int offset, int limit)` | `List<DashboardRecordResult>` | Most recently created records across all users. |
| `visitNode(String token, String source, String node, Calendar date)` | `void` | Marks a node as visited by the current user for a given dashboard source. |

### Exceptions

Methods may throw `AccessDeniedException`, `RepositoryException`, `DatabaseException`, `ParseException`, and `IOException`.

---

### getUserCheckedOutDocuments

```java
package com.openkm;

import com.openkm.api.OKMDashboard;
import com.openkm.bean.DashboardDocumentResult;
import com.openkm.util.ContextWrapper;
import com.openkm.ws.rest.util.DashboardDocumentResultSet;

public class Test {

    public static void main(String[] args) {
        try {
            OKMDashboard okmDashboard = ContextWrapper.getContext().getBean(OKMDashboard.class);
            DashboardDocumentResultSet resultSet = okmDashboard.getUserCheckedOutDocuments(null, 0, 5);
            System.out.println("Total: " + resultSet.getTotal());
            for (DashboardDocumentResult result : resultSet.getResults()) {
                System.out.println(result);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### getUserLockedFolders

```java
package com.openkm;

import com.openkm.api.OKMDashboard;
import com.openkm.bean.DashboardFolderResult;
import com.openkm.bean.DashboardFolderResultSet;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMDashboard okmDashboard = ContextWrapper.getContext().getBean(OKMDashboard.class);
            DashboardFolderResultSet resultSet = okmDashboard.getUserLockedFolders(null, 0, 5);
            System.out.println("Total: " + resultSet.getTotal());
            for (DashboardFolderResult result : resultSet.getResults()) {
                System.out.println(result);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### getUserLockedMails

```java
package com.openkm;

import com.openkm.api.OKMDashboard;
import com.openkm.bean.DashboardMailResult;
import com.openkm.bean.DashboardMailResultSet;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMDashboard okmDashboard = ContextWrapper.getContext().getBean(OKMDashboard.class);
            DashboardMailResultSet resultSet = okmDashboard.getUserLockedMails(null, 0, 5);
            System.out.println("Total: " + resultSet.getTotal());
            for (DashboardMailResult result : resultSet.getResults()) {
                System.out.println(result);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### getUserLastImportedMails

```java
package com.openkm;

import com.openkm.api.OKMDashboard;
import com.openkm.bean.DashboardMailResult;
import com.openkm.bean.DashboardMailResultSet;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMDashboard okmDashboard = ContextWrapper.getContext().getBean(OKMDashboard.class);
            DashboardMailResultSet resultSet = okmDashboard.getUserLastImportedMails(null, 0, 5);
            System.out.println("Total: " + resultSet.getTotal());
            for (DashboardMailResult result : resultSet.getResults()) {
                System.out.println(result);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### getUserDocumentsSize

```java
package com.openkm;

import com.openkm.api.OKMDashboard;
import com.openkm.util.ContextWrapper;
import com.openkm.util.FormatUtil;

public class Test {

    public static void main(String[] args) {
        try {
            OKMDashboard okmDashboard = ContextWrapper.getContext().getBean(OKMDashboard.class);
            long sizeInBytes = okmDashboard.getUserDocumentsSize(null);
            System.out.println(FormatUtil.formatSize(sizeInBytes));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### getUserSearches

```java
package com.openkm;

import com.openkm.api.OKMDashboard;
import com.openkm.db.bean.QueryParams;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMDashboard okmDashboard = ContextWrapper.getContext().getBean(OKMDashboard.class);
            for (QueryParams qp : okmDashboard.getUserSearches(null)) {
                System.out.println(qp);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### find

Executes a saved search by its ID. The result node can be cast to `Document`, `Folder`, `Record`, or `Mail`.

```java
package com.openkm;

import com.openkm.api.OKMDashboard;
import com.openkm.bean.DashboardNodeResult;
import com.openkm.bean.Document;
import com.openkm.bean.Folder;
import com.openkm.bean.Mail;
import com.openkm.bean.Record;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMDashboard okmDashboard = ContextWrapper.getContext().getBean(OKMDashboard.class);
            int qpId = 12;
            for (DashboardNodeResult result : okmDashboard.find(null, qpId)) {
                if (result.getNode() instanceof Document doc) {
                    System.out.println(doc);
                } else if (result.getNode() instanceof Folder fld) {
                    System.out.println(fld);
                } else if (result.getNode() instanceof Record rec) {
                    System.out.println(rec);
                } else if (result.getNode() instanceof Mail mail) {
                    System.out.println(mail);
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

### visitNode

Marks a node as visited for a specific dashboard source. Visited nodes stop being displayed in bold in the UI.

Available source values: `LastWeekTopDownloadedDocuments`, `LastMonthTopDownloadedDocuments`, `LastWeekTopModifiedDocuments`, `LastMonthTopModifiedDocuments`, `LastModifiedDocuments`, `LastCreatedDocuments`, `LastCreatedFolders`, `LastCreatedRecords`, `LastCheckoutDocuments`, `UserLockedDocuments`, `UserLockedRecord`, `UserCheckedOutDocuments`, `UserLastModifiedDocuments`, `UserLastDownloadedDocuments`, `UserSubscribedDocuments`, `UserSubscribedFolders`, `UserSubscribedRecords`, `UserLastCreatedDocuments`, `UserLastCreatedFolders`, `UserLastCreatedRecords`, `UserLastImportedMails`, `UserLastImportedMailAttachments`. For user-news saved searches, use the search name as the source.

```java
package com.openkm;

import java.util.Calendar;

import com.openkm.api.OKMDashboard;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMDashboard okmDashboard = ContextWrapper.getContext().getBean(OKMDashboard.class);
            Calendar cal = Calendar.getInstance();
            okmDashboard.visitNode(null, "LastWeekTopDownloadedDocuments", "/okm:root/document.pdf", cal);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

---

## OKMDocument

Used for managing documents in the repository: create, read, update, delete, checkout/checkin, copy, move, versioning, stamping, and more.

### Basics

The `docId` parameter accepts a document **UUID**. Example: `"c41f9ea0-0d6c-45da-bae4-d72b66f42d0f"`.

The `fldId` / `dstId` parameters accept a folder or record **UUID**.

Pass `null` for `token` to use the current user session.

### Bean: Document (`com.openkm.bean.Document`)

| Field | Type | Description |
|-------|------|-------------|
| path | String | Full repository path |
| uuid | String | Unique identifier |
| title | String | Document title |
| language | String | Document language code |
| mimeType | String | MIME type |
| checkedOut | boolean | Whether the document is currently checked out |
| signed | boolean | Whether the document is digitally signed |
| convertibleToPdf | boolean | Whether the document can be converted to PDF |
| textExtracted | boolean | Whether text has been extracted for indexing |
| indexable | boolean | Whether the document is included in search index |
| cipherName | String | Encryption cipher name (if encrypted) |
| keywords | Set\<String\> | Keywords assigned to the document |

### Bean: Version (`com.openkm.bean.Version`)

| Field | Type | Description |
|-------|------|-------------|
| name | String | Version identifier (e.g. "1.0", "1.1") |
| created | Calendar | Creation date |
| size | long | Size in bytes |
| author | String | User who created this version |
| actual | boolean | Whether this is the current version |
| comment | String | Check-in comment |
| checksum | String | MD5 checksum |

### Bean: ExtendedAttributes (`com.openkm.bean.ExtendedAttributes`)

| Field | Type | Description |
|-------|------|-------------|
| categories | boolean | Copy category assignments |
| keywords | boolean | Copy keywords |
| propertyGroups | boolean | Copy metadata groups |
| notes | boolean | Copy notes |
| security | boolean | Copy security grants |

### Bean: WizardNode (`com.openkm.db.bean.WizardNode`)

Returned by `createWizard`. Contains the created node and a list of pending actions to complete the wizard (add keywords, categories, metadata).

---

### Methods

#### create
| Method | Returns | Description |
|--------|---------|-------------|
| `create(String token, Document doc, InputStream is)` | `Document` | Create a new document. Set `doc.setPath(...)` with the repository path. Optionally set title and keywords. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
InputStream is = new FileInputStream("/home/openkm/sample.pdf");
Document doc = new Document();
doc.setPath("/okm:root/sample.pdf");
doc.setTitle("sample document");
doc.getKeywords().add("key1");
doc = okmDocument.create(null, doc, is);
```

#### createSimple
| Method | Returns | Description |
|--------|---------|-------------|
| `createSimple(String token, String docPath, InputStream is)` | `Document` | Create a new document by path. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
InputStream is = new FileInputStream("/home/openkm/sample.pdf");
Document doc = okmDocument.createSimple(null, "/okm:root/sample.pdf", is);
```

#### delete
| Method | Returns | Description |
|--------|---------|-------------|
| `delete(String token, String docId)` | `void` | Move a document to the trash. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
okmDocument.delete(null, "d50133e3-dbfa-4d01-a109-28785cd48f40");
```

#### getProperties
| Method | Returns | Description |
|--------|---------|-------------|
| `getProperties(String token, String docId)` | `Document` | Returns a document's properties. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
Document doc = okmDocument.getProperties(null, "3887ae75-dd67-4019-b4d1-2f6962815403");
```

#### getContent
| Method | Returns | Description |
|--------|---------|-------------|
| `getContent(String token, String docId, boolean checkout)` | `InputStream` | Returns the document binary content. Set `checkout=true` to simultaneously check out the document. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
InputStream is = okmDocument.getContent(null, "3887ae75-dd67-4019-b4d1-2f6962815403", false);
```

#### getContentByVersion
| Method | Returns | Description |
|--------|---------|-------------|
| `getContentByVersion(String token, String docId, String versionId)` | `InputStream` | Returns the binary content of a specific document version. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
InputStream is = okmDocument.getContentByVersion(null, "3887ae75-dd67-4019-b4d1-2f6962815403", "1.0");
```

#### getExtractedText
| Method | Returns | Description |
|--------|---------|-------------|
| `getExtractedText(String token, String docId)` | `String` | Returns the text extracted from the document for full-text search. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
String text = okmDocument.getExtractedText(null, "3887ae75-dd67-4019-b4d1-2f6962815403");
```

#### setExtractedText
| Method | Returns | Description |
|--------|---------|-------------|
| `setExtractedText(String token, String docId, String text)` | `void` | Manually set the extracted text for a document. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
okmDocument.setExtractedText(null, "3887ae75-dd67-4019-b4d1-2f6962815403", "custom extracted text");
```

#### isTextExtracted
| Method | Returns | Description |
|--------|---------|-------------|
| `isTextExtracted(String token, String docId)` | `boolean` | Returns whether text has been extracted from the document. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
boolean extracted = okmDocument.isTextExtracted(null, "3887ae75-dd67-4019-b4d1-2f6962815403");
```

#### forceTextExtraction
| Method | Returns | Description |
|--------|---------|-------------|
| `forceTextExtraction(String token, String docId)` | `void` | Forces re-extraction of text from the document. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
okmDocument.forceTextExtraction(null, "3887ae75-dd67-4019-b4d1-2f6962815403");
```

#### getChildren
| Method | Returns | Description |
|--------|---------|-------------|
| `getChildren(String token, String fldId)` | `List<Document>` | Returns all documents in a folder or record. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
for (Document doc : okmDocument.getChildren(null, "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474")) {
    System.out.println(doc);
}
```

#### rename
| Method | Returns | Description |
|--------|---------|-------------|
| `rename(String token, String docId, String newName)` | `Document` | Rename a document. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
Document doc = okmDocument.rename(null, "3887ae75-dd67-4019-b4d1-2f6962815403", "newname.pdf");
```

#### setProperties
| Method | Returns | Description |
|--------|---------|-------------|
| `setProperties(String token, Document doc)` | `void` | Update document properties (title, language, keywords). |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
Document doc = okmDocument.getProperties(null, "3887ae75-dd67-4019-b4d1-2f6962815403");
doc.setTitle("Updated Title");
okmDocument.setProperties(null, doc);
```

#### setLanguage
| Method | Returns | Description |
|--------|---------|-------------|
| `setLanguage(String token, String docId, String lang)` | `void` | Set the document language (e.g. `"en"`, `"es"`). |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
okmDocument.setLanguage(null, "3887ae75-dd67-4019-b4d1-2f6962815403", "en");
```

#### setTitle
| Method | Returns | Description |
|--------|---------|-------------|
| `setTitle(String token, String docId, String title)` | `void` | Set the document title. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
okmDocument.setTitle(null, "3887ae75-dd67-4019-b4d1-2f6962815403", "My Document Title");
```

#### setDescription
| Method | Returns | Description |
|--------|---------|-------------|
| `setDescription(String token, String docId, String description)` | `void` | Set the document description. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
okmDocument.setDescription(null, "7ce1b4a8-4ade-4dce-8d7d-4e99a6cd368b", "some description");
```

#### setNodeClass
| Method | Returns | Description |
|--------|---------|-------------|
| `setNodeClass(String token, String docId, long ncId)` | `void` | Set the node class (classification) for a document. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
okmDocument.setNodeClass(null, "7ce1b4a8-4ade-4dce-8d7d-4e99a6cd368b", 2L);
```

#### setDispositionStage
| Method | Returns | Description |
|--------|---------|-------------|
| `setDispositionStage(String token, String docId, long stage)` | `void` | Set the disposition stage of a document (records management). |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
okmDocument.setDispositionStage(null, "7ce1b4a8-4ade-4dce-8d7d-4e99a6cd368b", 1L);
```

#### checkout
| Method | Returns | Description |
|--------|---------|-------------|
| `checkout(String token, String docId)` | `void` | Check out a document for editing. Locks the document to the current user. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
okmDocument.checkout(null, "f3a977f7-abfc-4f58-a033-988903b31473");
```

#### cancelCheckout
| Method | Returns | Description |
|--------|---------|-------------|
| `cancelCheckout(String token, String docId)` | `void` | Cancel a checkout. Reverts the document to its previous state. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
okmDocument.cancelCheckout(null, "f3a977f7-abfc-4f58-a033-988903b31473");
```

#### forceCancelCheckout
| Method | Returns | Description |
|--------|---------|-------------|
| `forceCancelCheckout(String token, String docId)` | `void` | Force cancel a checkout. Can be used by administrators regardless of who checked out the document. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
okmDocument.forceCancelCheckout(null, "f3a977f7-abfc-4f58-a033-988903b31473");
```

#### isCheckedOut
| Method | Returns | Description |
|--------|---------|-------------|
| `isCheckedOut(String token, String docId)` | `boolean` | Returns whether the document is currently checked out. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
boolean checkedOut = okmDocument.isCheckedOut(null, "f3a977f7-abfc-4f58-a033-988903b31473");
```

#### checkin
| Method | Returns | Description |
|--------|---------|-------------|
| `checkin(String token, String docId, InputStream is, String comment)` | `Version` | Check in a document, creating a new version. |
| `checkin(String token, String docId, InputStream is, String comment, int increment)` | `Version` | Check in with a specific version increment (e.g. 0=minor, 1=major). |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
InputStream is = new FileInputStream("/home/openkm/updated.pdf");
Version version = okmDocument.checkin(null, "f3a977f7-abfc-4f58-a033-988903b31473", is, "Updated content");
```

#### lock / unlock / forceUnlock
These methods are inherited from `OKMNode`.

| Method | Returns | Description |
|--------|---------|-------------|
| `lock(String token, String docId)` | `LockInfo` | Lock a document. |
| `unlock(String token, String docId)` | `void` | Unlock a document locked by the current user. |
| `forceUnlock(String token, String docId)` | `void` | Force unlock any locked document. Requires ROLE_ADMIN. |

#### isLocked
| Method | Returns | Description |
|--------|---------|-------------|
| `isLocked(String token, String docId)` | `boolean` | Returns whether the document is currently locked. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
boolean locked = okmDocument.isLocked(null, "f3a977f7-abfc-4f58-a033-988903b31473");
```

#### getLockInfo
| Method | Returns | Description |
|--------|---------|-------------|
| `getLockInfo(String token, String docId)` | `LockInfo` | Returns lock information (owner, token, etc.). |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
LockInfo lockInfo = okmDocument.getLockInfo(null, "f3a977f7-abfc-4f58-a033-988903b31473");
```

#### purge
| Method | Returns | Description |
|--------|---------|-------------|
| `purge(String token, String docId)` | `void` | Permanently delete a document. Cannot be undone (no trash). |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
okmDocument.purge(null, "f3a977f7-abfc-4f58-a033-988903b31473");
```

#### move
| Method | Returns | Description |
|--------|---------|-------------|
| `move(String token, String docId, String dstId)` | `void` | Move a document to a different folder or record. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
okmDocument.move(null, "f3a977f7-abfc-4f58-a033-988903b31473", "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474");
```

#### copy
| Method | Returns | Description |
|--------|---------|-------------|
| `copy(String token, String docId, String dstId)` | `Document` | Copy a document to a folder or record. Only binary data and security grants are copied. |
| `copy(String token, String docId, String dstId, String newName)` | `Document` | Copy a document with an optional new name. Pass `null` for `newName` to keep the original name. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
okmDocument.copy(null, "f3a977f7-abfc-4f58-a033-988903b31473", "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474", "copy.pdf");
```

#### extendedCopy
| Method | Returns | Description |
|--------|---------|-------------|
| `extendedCopy(String token, String docId, String dstId, String docName, ExtendedAttributes extAttr)` | `Document` | Copy a document with optional metadata, keywords, categories, notes. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
ExtendedAttributes extAttr = new ExtendedAttributes();
extAttr.setKeywords(true);
extAttr.setCategories(true);
extAttr.setNotes(true);
extAttr.setPropertyGroups(true);
okmDocument.extendedCopy(null, "f3a977f7-abfc-4f58-a033-988903b31473", "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474", "copy.pdf", extAttr);
```

#### getVersionHistorySize
| Method | Returns | Description |
|--------|---------|-------------|
| `getVersionHistorySize(String token, String docId)` | `long` | Returns the total size in bytes of all versions in the document's history. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
long size = okmDocument.getVersionHistorySize(null, "f3a977f7-abfc-4f58-a033-988903b31473");
```

#### isValid
| Method | Returns | Description |
|--------|---------|-------------|
| `isValid(String token, String docId)` | `boolean` | Returns whether the given UUID belongs to a document node. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
boolean valid = okmDocument.isValid(null, "f3a977f7-abfc-4f58-a033-988903b31473");
```

#### getPath
| Method | Returns | Description |
|--------|---------|-------------|
| `getPath(String token, String uuid)` | `String` | Converts a document UUID to its repository path. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
String path = okmDocument.getPath(null, "f3a977f7-abfc-4f58-a033-988903b31473");
```

#### getDetectedLanguages
| Method | Returns | Description |
|--------|---------|-------------|
| `getDetectedLanguages(String token)` | `List<String>` | Returns the list of language codes that OpenKM can detect. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
for (String lang : okmDocument.getDetectedLanguages(null)) {
    System.out.println(lang);
}
```

#### createFromTemplate
| Method | Returns | Description |
|--------|---------|-------------|
| `createFromTemplate(String token, String docId, String dstPath, Map<String, String> properties, ExtendedAttributes attributes)` | `Document` | Create a document from a template, filling in metadata group fields. `dstPath` is a folder or record UUID. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
Map<String, String> properties = new HashMap<>();
properties.put("okp:tpl.name", "Some name");
properties.put("okp:tpl.bird_date", ISO8601.formatBasic(Calendar.getInstance()));
okmDocument.createFromTemplate(null, "86633fe8-1b0d-48ac-a716-7685022adad8", "/okm:root/templates.pdf", properties, new ExtendedAttributes());
```

#### updateFromTemplate
| Method | Returns | Description |
|--------|---------|-------------|
| `updateFromTemplate(String token, String docId, String dstId, Map<String, String> properties)` | `void` | Update a document previously created from a template, re-applying metadata field values. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
Map<String, String> properties = new HashMap<>();
properties.put("okp:tpl.name", "Updated name");
okmDocument.updateFromTemplate(null, "86633fe8-1b0d-48ac-a716-7685022adad8", "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474", properties);
```

#### setAnnotations / getAnnotations
| Method | Returns | Description |
|--------|---------|-------------|
| `setAnnotations(String token, String docId, String verName, String annotation)` | `void` | Set annotations for a specific document version. |
| `getAnnotations(String token, String docId, String verName)` | `String` | Get the annotations for a specific document version. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
okmDocument.setAnnotations(null, "3887ae75-dd67-4019-b4d1-2f6962815403", "1.1", "Annotation text.");
String annotation = okmDocument.getAnnotations(null, "3887ae75-dd67-4019-b4d1-2f6962815403", "1.1");
```

#### getCheckedOut
| Method | Returns | Description |
|--------|---------|-------------|
| `getCheckedOut(String token)` | `List<Document>` | Returns all documents currently checked out in the repository. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
for (Document doc : okmDocument.getCheckedOut(null)) {
    System.out.println(doc);
}
```

#### stamp
| Method | Returns | Description |
|--------|---------|-------------|
| `stamp(String token, String docId, int type, long stId)` | `void` | Apply a stamp to a document. `type`: 0=text stamp, 1=image stamp. `stId` is the stamp definition ID. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
okmDocument.stamp(null, "3887ae75-dd67-4019-b4d1-2f6962815403", 0, 1L);
```

#### stampText
| Method | Returns | Description |
|--------|---------|-------------|
| `stampText(String token, String docId, long stId, String range, String exprX, String exprY, String text)` | `void` | Stamp a document with custom text at specified coordinates. Supports macros: `PAGE_CENTER`, `PAGE_MIDDLE`, `PAGE_WIDTH`, `PAGE_HEIGHT`, `IMAGE_WIDTH`, `IMAGE_HEIGHT`. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
okmDocument.stampText(null, "05b14eee5-2e57-4d1d-925a-c9bc3f526e24", 1L, "", "PAGE_CENTER", "PAGE_MIDDLE", "OpenKM");
```

#### stampImage
| Method | Returns | Description |
|--------|---------|-------------|
| `stampImage(String token, String docId, long stId, String range, String exprX, String exprY, byte[] image)` | `void` | Stamp a document with a custom image at specified coordinates. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
byte[] image = IOUtils.toByteArray(new FileInputStream("/path/to/logo.png"));
okmDocument.stampImage(null, "055b5206-35d0-4351-ba92-c304bbba7ddf", 1L, "", "PAGE_CENTER - IMAGE_WIDTH / 2", "PAGE_MIDDLE - IMAGE_HEIGHT / 2", image);
```

#### createWizard
| Method | Returns | Description |
|--------|---------|-------------|
| `createWizard(String token, String docPath, long nodeClass, InputStream is)` | `WizardNode` | Create a document using a wizard. `docPath` is the full repository path. Returns a `WizardNode` with pending actions (keywords, categories, metadata). |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
InputStream is = new FileInputStream("/home/openkm/logo.png");
WizardNode wn = okmDocument.createWizard(null, "/okm:root/test/logo.png", 0L, is);
```

#### getNumberOfPages
| Method | Returns | Description |
|--------|---------|-------------|
| `getNumberOfPages(String token, String uuid)` | `int` | Returns the number of pages in a document. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
int pages = okmDocument.getNumberOfPages(null, "b2f88679-e3fd-4f97-bf0e-abf76f9ec499");
```

#### getPageAsImage
| Method | Returns | Description |
|--------|---------|-------------|
| `getPageAsImage(String token, String uuid, int pageNumber, int maxWidth, int maxHeight)` | `String` | Returns a specific page rendered as a Base64-encoded image string. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
String base64 = okmDocument.getPageAsImage(null, "3fe350e2-69e8-4681-a97c-6ac4ba6c1524", 1, 150, 150);
```

#### isConvertibleToPdf
| Method | Returns | Description |
|--------|---------|-------------|
| `isConvertibleToPdf(String token, String docId)` | `boolean` | Returns whether the document can be converted to PDF. Returns `false` for documents that are already PDF. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
boolean convertible = okmDocument.isConvertibleToPdf(null, "9ed5c7b1-9314-4479-8f80-fd8e2b47f55e");
```

#### setIndexable
| Method | Returns | Description |
|--------|---------|-------------|
| `setIndexable(String token, String uuid, boolean enabled)` | `void` | Enable or disable full-text indexing for a document. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
okmDocument.setIndexable(null, "19938640-fd34-421c-90c8-6b435e4b7d79", true);
```

#### mergePdf
| Method | Returns | Description |
|--------|---------|-------------|
| `mergePdf(String token, String destinationPath, String docName, List<String> paths)` | `void` | Merge two or more PDF documents into a single file. `destinationPath` is a folder or record PATH. `paths` is a list of document paths to merge. |

```java
OKMDocument okmDocument = ContextWrapper.getContext().getBean(OKMDocument.class);
List<String> paths = new ArrayList<>();
paths.add("/okm:root/test/document.pdf");
paths.add("/okm:root/test/document1.pdf");
okmDocument.mergePdf(null, "/okm:root/merged", "MergePdf.pdf", paths);
```

---

## OKMFolder

Used for managing folders in the repository: create, delete, rename, move, copy, list children, and more.

### Basics

The `fldId` parameter accepts a folder **UUID**. Example: `"b67fe3ae-bcca-4947-b8ea-0cc7aedd4474"`.

The `dstId` parameter accepts a folder or record **UUID** as the destination.

Pass `null` for `token` to use the current user session.

### Bean: Folder (`com.openkm.bean.Folder`)

Extends `Node`. Key fields inherited from `Node`:

| Field | Type | Description |
|-------|------|-------------|
| path | String | Full repository path |
| uuid | String | Unique identifier |
| author | String | Creator username |
| created | Calendar | Creation date |
| lastModified | Calendar | Last modification date |
| description | String | Description |
| keywords | Set\<String\> | Keywords |
| categories | Set\<Folder\> | Category assignments |
| notes | List\<Note\> | Notes |
| locked | boolean | Whether the folder is locked |
| nodeClass | long | Node class (classification) ID |
| hasChildren | boolean | Whether the folder has child nodes |

### Bean: ContentInfo (`com.openkm.bean.ContentInfo`)

| Field | Type | Description |
|-------|------|-------------|
| folders | long | Number of folders |
| documents | long | Number of documents |
| records | long | Number of records |
| mails | long | Number of mails |
| size | long | Total size in bytes |

---

### Methods

#### create
| Method | Returns | Description |
|--------|---------|-------------|
| `create(String token, Folder fld)` | `Folder` | Create a new folder. Set `fld.setPath(...)` with the target repository path. Other properties are ignored at creation time. |

```java
OKMFolder okmFolder = ContextWrapper.getContext().getBean(OKMFolder.class);
Folder fld = new Folder();
fld.setPath("/okm:root/test");
fld = okmFolder.create(null, fld);
```

#### createSimple
| Method | Returns | Description |
|--------|---------|-------------|
| `createSimple(String token, String fldPath)` | `Folder` | Create a new folder by path. |

```java
OKMFolder okmFolder = ContextWrapper.getContext().getBean(OKMFolder.class);
Folder fld = okmFolder.createSimple(null, "/okm:root/test");
```

#### getProperties
| Method | Returns | Description |
|--------|---------|-------------|
| `getProperties(String token, String fldId)` | `Folder` | Returns the folder properties. |

```java
OKMFolder okmFolder = ContextWrapper.getContext().getBean(OKMFolder.class);
Folder fld = okmFolder.getProperties(null, "9f64248c-e049-4706-b89e-6d725842c7f7");
```

#### delete
| Method | Returns | Description |
|--------|---------|-------------|
| `delete(String token, String fldId)` | `void` | Move a folder to the trash. |

```java
OKMFolder okmFolder = ContextWrapper.getContext().getBean(OKMFolder.class);
okmFolder.delete(null, "9f64248c-e049-4706-b89e-6d725842c7f7");
```

#### purge
| Method | Returns | Description |
|--------|---------|-------------|
| `purge(String token, String fldId)` | `void` | Permanently delete a folder. Cannot be undone (no trash). |

```java
OKMFolder okmFolder = ContextWrapper.getContext().getBean(OKMFolder.class);
okmFolder.purge(null, "9f64248c-e049-4706-b89e-6d725842c7f7");
```

#### rename
| Method | Returns | Description |
|--------|---------|-------------|
| `rename(String token, String fldId, String newName)` | `Folder` | Rename a folder. |

```java
OKMFolder okmFolder = ContextWrapper.getContext().getBean(OKMFolder.class);
Folder fld = okmFolder.rename(null, "7aceb86c-1dc8-4551-aebd-b7bd73d01263", "newname");
```

#### move
| Method | Returns | Description |
|--------|---------|-------------|
| `move(String token, String fldId, String dstId)` | `void` | Move a folder to a different folder or record. |

```java
OKMFolder okmFolder = ContextWrapper.getContext().getBean(OKMFolder.class);
okmFolder.move(null, "7aceb86c-1dc8-4551-aebd-b7bd73d01263", "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474");
```

#### copy
| Method | Returns | Description |
|--------|---------|-------------|
| `copy(String token, String fldId, String dstId)` | `Folder` | Copy a folder to another folder or record. Only security grants are copied; metadata, keywords, etc. are not. |
| `copy(String token, String fldId, String dstId, String newName)` | `Folder` | Copy a folder with an optional new name. Pass `null` for `newName` to keep the original name. |

```java
OKMFolder okmFolder = ContextWrapper.getContext().getBean(OKMFolder.class);
okmFolder.copy(null, "7aceb86c-1dc8-4551-aebd-b7bd73d01263", "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474", "newname");
```

#### extendedCopy
| Method | Returns | Description |
|--------|---------|-------------|
| `extendedCopy(String token, String fldId, String dstId, ExtendedAttributes extAttr)` | `Folder` | Copy a folder with optional metadata, keywords, categories, notes. |
| `extendedCopy(String token, String fldId, String dstId, String newName, ExtendedAttributes extAttr)` | `Folder` | Copy a folder with a new name and optional extended attributes. |

```java
OKMFolder okmFolder = ContextWrapper.getContext().getBean(OKMFolder.class);
ExtendedAttributes extAttr = new ExtendedAttributes();
extAttr.setKeywords(true);
extAttr.setCategories(true);
extAttr.setNotes(true);
extAttr.setPropertyGroups(true);
okmFolder.extendedCopy(null, "7aceb86c-1dc8-4551-aebd-b7bd73d01263", "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474", "newname", extAttr);
```

#### getChildren
| Method | Returns | Description |
|--------|---------|-------------|
| `getChildren(String token, String fldId)` | `List<Folder>` | Returns all child folders of a folder or record. |

```java
OKMFolder okmFolder = ContextWrapper.getContext().getBean(OKMFolder.class);
for (Folder fld : okmFolder.getChildren(null, "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474")) {
    System.out.println(fld);
}
```

#### getContentInfo
| Method | Returns | Description |
|--------|---------|-------------|
| `getContentInfo(String token, String fldId)` | `ContentInfo` | Returns statistics about the folder contents: number of folders, documents, records, mails, and total size. |

```java
OKMFolder okmFolder = ContextWrapper.getContext().getBean(OKMFolder.class);
ContentInfo ci = okmFolder.getContentInfo(null, "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474");
System.out.println("Documents: " + ci.getDocuments() + ", Size: " + ci.getSize());
```

#### isValid
| Method | Returns | Description |
|--------|---------|-------------|
| `isValid(String token, String fldId)` | `boolean` | Returns whether the given UUID belongs to a folder node. |

```java
OKMFolder okmFolder = ContextWrapper.getContext().getBean(OKMFolder.class);
boolean valid = okmFolder.isValid(null, "7aceb86c-1dc8-4551-aebd-b7bd73d01263");
```

#### getPath
| Method | Returns | Description |
|--------|---------|-------------|
| `getPath(String token, String uuid)` | `String` | Converts a folder UUID to its repository path. |

```java
OKMFolder okmFolder = ContextWrapper.getContext().getBean(OKMFolder.class);
String path = okmFolder.getPath(null, "7aceb86c-1dc8-4551-aebd-b7bd73d01263");
```

#### createMissingFolders
| Method | Returns | Description |
|--------|---------|-------------|
| `createMissingFolders(String token, String fldPath)` | `String` | Creates all missing intermediate folders in the given path. Returns the UUID of the deepest created folder. |

```java
OKMFolder okmFolder = ContextWrapper.getContext().getBean(OKMFolder.class);
String uuid = okmFolder.createMissingFolders(null, "/okm:root/test/missing/from/here");
```

#### addNodeClassChildren
| Method | Returns | Description |
|--------|---------|-------------|
| `addNodeClassChildren(String token, String fldId, long ncId)` | `void` | Assign a node class to all children of a folder. |

```java
OKMFolder okmFolder = ContextWrapper.getContext().getBean(OKMFolder.class);
okmFolder.addNodeClassChildren(null, "7ce1b4a8-4ade-4dce-8d7d-4e99a6cd368b", 2L);
```

#### createFromTemplate
| Method | Returns | Description |
|--------|---------|-------------|
| `createFromTemplate(String token, String fldId, String dstPath, Map<String, String> properties, ExtendedAttributes extAttr)` | `Folder` | Create a folder from a template, filling in metadata group fields. `dstPath` is a folder or record UUID. |

```java
OKMFolder okmFolder = ContextWrapper.getContext().getBean(OKMFolder.class);
Map<String, String> properties = new HashMap<>();
Folder fld = okmFolder.createFromTemplate(null, "86633fe8-1b0d-48ac-a716-7685022adad8",
        "/okm:root/destination", properties, new ExtendedAttributes());
```

#### setDescription
| Method | Returns | Description |
|--------|---------|-------------|
| `setDescription(String token, String uuid, String description)` | `void` | Set the description of a folder. |

```java
OKMFolder okmFolder = ContextWrapper.getContext().getBean(OKMFolder.class);
okmFolder.setDescription(null, "7ce1b4a8-4ade-4dce-8d7d-4e99a6cd368b", "some description");
```

---

## OKMImport

Used for importing content into the repository at a low level: create documents, folders, records, and mails directly by UUID parent reference. Designed for bulk imports and migrations from external systems.

### Basics

The `parentUuid` parameter must be a valid **folder or record UUID** in the repository.

Pass `null` for `token` to use the current user session.

Return types are `NodeDocument`, `NodeFolder`, `NodeRecord`, `NodeMail` from `com.openkm.db.bean` — these are the internal JPA entities, lower-level than the `Document`/`Folder` beans used in `OKMDocument`/`OKMFolder`.

---

### Methods

#### createDocument
| Method | Returns | Description |
|--------|---------|-------------|
| `createDocument(String token, String parentUuid, String name, File file)` | `NodeDocument` | Create a new document under the given parent. |
| `createDocument(String token, String parentUuid, String name, Calendar created, String author, File file)` | `NodeDocument` | Create a new document preserving the original creation date and author (use for migrations). |

```java
OKMImport okmImport = ContextWrapper.getContext().getBean(OKMImport.class);
File file = new File("/home/openkm/sample.pdf");
NodeDocument nodeDoc = okmImport.createDocument(null, "0a19e616-1d11-4ef7-a7c7-f1e109f8ea3c", "document.pdf", file);
```

```java
// Preserve original metadata during migration
Calendar created = Calendar.getInstance();
NodeDocument nodeDoc = okmImport.createDocument(null, "0a19e616-1d11-4ef7-a7c7-f1e109f8ea3c", "document.pdf", created, "okmAdmin", file);
```

#### createFolder
| Method | Returns | Description |
|--------|---------|-------------|
| `createFolder(String token, String parentUuid, String name)` | `NodeFolder` | Create a new folder under the given parent. |
| `createFolder(String token, String parentUuid, String name, Calendar created, String author)` | `NodeFolder` | Create a new folder preserving the original creation date and author (use for migrations). |

```java
OKMImport okmImport = ContextWrapper.getContext().getBean(OKMImport.class);
NodeFolder nodeFld = okmImport.createFolder(null, "0a19e616-1d11-4ef7-a7c7-f1e109f8ea3c", "newFolderName");
```

#### createRecord
| Method | Returns | Description |
|--------|---------|-------------|
| `createRecord(String token, String parentUuid, String name)` | `NodeRecord` | Create a new record under the given parent. |
| `createRecord(String token, String parentUuid, String name, Calendar created, String author)` | `NodeRecord` | Create a new record preserving the original creation date and author (use for migrations). |

```java
OKMImport okmImport = ContextWrapper.getContext().getBean(OKMImport.class);
NodeRecord nodeRec = okmImport.createRecord(null, "0a19e616-1d11-4ef7-a7c7-f1e109f8ea3c", "newRecordName");
```

#### createMail
| Method | Returns | Description |
|--------|---------|-------------|
| `createMail(String token, String parentUuid, File file)` | `NodeMail` | Import a mail file (`.eml`) into the repository under the given parent. |

```java
OKMImport okmImport = ContextWrapper.getContext().getBean(OKMImport.class);
File file = new File("/home/openkm/message.eml");
NodeMail nodeMail = okmImport.createMail(null, "0a19e616-1d11-4ef7-a7c7-f1e109f8ea3c", file);
```

#### importFolder
| Method | Returns | Description |
|--------|---------|-------------|
| `importFolder(String token, String parentUuid, File folder, int threads)` | `int` | Recursively import a local filesystem folder hierarchy into the repository. Returns the number of errors encountered. |

The `threads` parameter controls the number of concurrent import threads. It should never exceed the number of server CPU cores. A good starting point is half the available cores.

```java
OKMImport okmImport = ContextWrapper.getContext().getBean(OKMImport.class);
File fld = new File("/home/openkm/import/");
int errors = okmImport.importFolder(null, "0a19e616-1d11-4ef7-a7c7-f1e109f8ea3c", fld, 4);
System.out.println("Import errors: " + errors);
```

---

## OKMMail

Used for managing mails in the repository: create, retrieve properties, manage attachments, delete, move, copy, send, import, and more.

### Basics

- **mailId**: UUID of a mail node, e.g. `"0747c0cb-5e4a-4088-92a9-ab97b401af75"`.
- **fldId**: UUID of a folder or record node.
- **token**: `null` to use the current user session; use `DbSessionManager.getInstance().getSystemToken()` for administrator access.
- Obtain an instance via `ContextWrapper.getContext().getBean(OKMMail.class)`.

### Methods

#### create
| Method | Returns | Description |
|--------|---------|-------------|
| `create(String token, Mail mail, InputStream is)` | `Mail` | Create a new mail node from a Mail bean and an input stream. The `mail.path` must point to a valid folder or record path. `is` contains the binary mail content (EML or MSG). |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
InputStream is = new FileInputStream("/home/openkm/message.eml");
Mail mail = new Mail();
mail.setPath("/okm:root/test/message.eml");
Mail newMail = okmMail.create(null, mail, is);
IOUtils.closeQuietly(is);
```

#### getProperties
| Method | Returns | Description |
|--------|---------|-------------|
| `getProperties(String token, String mailId)` | `Mail` | Returns the mail properties. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
Mail mail = okmMail.getProperties(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75");
```

#### createAttachment
| Method | Returns | Description |
|--------|---------|-------------|
| `createAttachment(String token, String mailId, String docName, InputStream is)` | `Document` | Add an attachment to the mail. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
InputStream is = new FileInputStream("/home/openkm/sample.pdf");
Document doc = okmMail.createAttachment(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", "sample.pdf", is);
IOUtils.closeQuietly(is);
```

#### deleteAttachment
| Method | Returns | Description |
|--------|---------|-------------|
| `deleteAttachment(String token, String mailId, String docId)` | `void` | Delete an attachment from the mail. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
okmMail.deleteAttachment(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", "c98d704f-c9f2-4f75-9923-878300b36b52");
```

#### getAttachments
| Method | Returns | Description |
|--------|---------|-------------|
| `getAttachments(String token, String mailId)` | `List<Document>` | Returns a list of all attachments for a mail. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
for (Document doc : okmMail.getAttachments(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75")) {
    System.out.println(doc);
}
```

#### delete
| Method | Returns | Description |
|--------|---------|-------------|
| `delete(String token, String mailId)` | `void` | Delete a mail (moves it to trash). |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
okmMail.delete(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75");
```

#### purge
| Method | Returns | Description |
|--------|---------|-------------|
| `purge(String token, String mailId)` | `void` | Permanently remove a mail from the repository. This action cannot be undone without a backup restore. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
okmMail.purge(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75");
```

#### rename
| Method | Returns | Description |
|--------|---------|-------------|
| `rename(String token, String mailId, String newName)` | `Mail` | Rename a mail. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
okmMail.rename(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", "newname");
```

#### move
| Method | Returns | Description |
|--------|---------|-------------|
| `move(String token, String mailId, String dstId)` | `void` | Move a mail into a folder or record. `dstId` is a folder or record UUID. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
okmMail.move(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", "3636f3bb-779c-4851-b145-0d53e0702b0f");
```

#### copy
| Method | Returns | Description |
|--------|---------|-------------|
| `copy(String token, String mailId, String dstId)` | `Mail` | Copy a mail into a folder or record. Only security grants are copied; metadata and keywords are not. |
| `copy(String token, String mailId, String dstId, String newName)` | `Mail` | Copy a mail with an optional new name. Pass `null` to preserve the original name. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
Mail copy1 = okmMail.copy(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", "3636f3bb-779c-4851-b145-0d53e0702b0f");
Mail copy2 = okmMail.copy(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", "3636f3bb-779c-4851-b145-0d53e0702b0f", "newname");
```

#### extendedCopy
| Method | Returns | Description |
|--------|---------|-------------|
| `extendedCopy(String token, String mailId, String dstId, ExtendedAttributes extAttr)` | `Mail` | Copy a mail with associated data into a folder or record. |
| `extendedCopy(String token, String mailId, String dstId, ExtendedAttributes extAttr, String newName)` | `Mail` | Copy a mail with associated data and an optional new name. |

`ExtendedAttributes` controls what is copied in addition to binary data and security grants: `categories`, `keywords`, `propertyGroups`, `notes`, `wiki`.

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
ExtendedAttributes extAttr = new ExtendedAttributes();
extAttr.setNotes(true);
extAttr.setKeywords(true);
extAttr.setCategories(true);
extAttr.setPropertyGroups(true);
Mail copied = okmMail.extendedCopy(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", "3636f3bb-779c-4851-b145-0d53e0702b0f", extAttr);
```

#### getChildren
| Method | Returns | Description |
|--------|---------|-------------|
| `getChildren(String token, String fldId)` | `List<Mail>` | Returns all mails whose parent is `fldId` (a folder or record UUID). |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
for (Mail mail : okmMail.getChildren(null, "3636f3bb-779c-4851-b145-0d53e0702b0f")) {
    System.out.println(mail);
}
```

#### isValid
| Method | Returns | Description |
|--------|---------|-------------|
| `isValid(String token, String mailId)` | `boolean` | Returns `true` if the node is a mail node. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
boolean valid = okmMail.isValid(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75");
```

#### getPath
| Method | Returns | Description |
|--------|---------|-------------|
| `getPath(String token, String uuid)` | `String` | Converts a mail UUID to its repository path. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
String path = okmMail.getPath(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75");
```

#### sendMail
| Method | Returns | Description |
|--------|---------|-------------|
| `sendMail(String token, List<String> recipients, String subject, String body)` | `void` | **Deprecated.** Send a mail. Use the `from` overload instead. |
| `sendMail(String token, String from, List<String> recipients, String subject, String body)` | `void` | Send a mail specifying the sender address. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
List<String> recipients = new ArrayList<>();
recipients.add("user@example.com");
okmMail.sendMail(null, "sender@example.com", recipients, "Subject", "Body text.");
```

#### setTitle
| Method | Returns | Description |
|--------|---------|-------------|
| `setTitle(String token, String mailId, String title)` | `void` | Set the mail title. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
okmMail.setTitle(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", "new title");
```

#### sendMailWithAttachments
| Method | Returns | Description |
|--------|---------|-------------|
| `sendMailWithAttachments(String token, List<String> toRecipients, List<String> ccRecipients, List<String> bccRecipients, List<String> replyToMails, String subject, String body, List<String> docsId, String dstId)` | `Mail` | Send a mail with attachments. `dstId` is the folder/record UUID where the sent mail is stored in the repository. `docsId` is a list of document UUIDs to attach (optional). |
| `sendMailWithAttachments(String token, String from, List<String> toRecipients, List<String> ccRecipients, List<String> bccRecipients, List<String> replyToMails, String subject, String body, List<String> docsId, String dstId)` | `Mail` | Same as above but with a custom `from` address. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
List<String> toRecipients = Arrays.asList("user@example.com");
List<String> docsId = Arrays.asList("b153c4b7-3d1c-4589-bd42-0ed0f34fd338");
Mail mail = okmMail.sendMailWithAttachments(null, "sender@example.com", toRecipients,
        new ArrayList<>(), new ArrayList<>(), new ArrayList<>(),
        "subject", "body", docsId, "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474");
```

#### importEml
| Method | Returns | Description |
|--------|---------|-------------|
| `importEml(String token, String fldId, String title, InputStream is)` | `Mail` | Import a mail in EML format into the folder or record identified by `fldId`. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
InputStream is = new FileInputStream("/home/openkm/sample1.eml");
Mail mail = okmMail.importEml(null, "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474", "some title", is);
IOUtils.closeQuietly(is);
```

#### importMsg
| Method | Returns | Description |
|--------|---------|-------------|
| `importMsg(String token, String fldId, String title, InputStream is)` | `Mail` | Import a mail in MSG format into the folder or record identified by `fldId`. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
InputStream is = new FileInputStream("/home/openkm/message.msg");
Mail mail = okmMail.importMsg(null, "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474", "some title", is);
IOUtils.closeQuietly(is);
```

#### setNodeClass
| Method | Returns | Description |
|--------|---------|-------------|
| `setNodeClass(String token, String uuid, long ncId)` | `void` | Set the node class for a mail. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
okmMail.setNodeClass(null, "7ce1b4a8-4ade-4dce-8d7d-4e99a6cd368b", 2L);
```

#### setDispositionStage
| Method | Returns | Description |
|--------|---------|-------------|
| `setDispositionStage(String token, String uuid, long stage)` | `void` | Set the disposition stage for a mail. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
okmMail.setDispositionStage(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", 1L);
```

#### setDescription
| Method | Returns | Description |
|--------|---------|-------------|
| `setDescription(String token, String uuid, String description)` | `void` | Set the description of a mail. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
okmMail.setDescription(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", "some description");
```

#### getContent
| Method | Returns | Description |
|--------|---------|-------------|
| `getContent(String token, String mailId)` | `InputStream` | Retrieve the binary content of the mail (EML data). |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
InputStream is = okmMail.getContent(null, "b405a504-d8cb-4166-ac51-22f68acee8c5");
IOUtils.copy(is, new FileOutputStream("/home/openkm/test.eml"));
IOUtils.closeQuietly(is);
```

#### createWizard
| Method | Returns | Description |
|--------|---------|-------------|
| `createWizard(String token, String path, String title, InputStream is, String type)` | `WizardNode` | Create a new mail with a wizard. `path` is a folder or record PATH. `type` is `Mail.ORIGIN_EML` or `Mail.ORIGIN_MSG`. |

The returned `WizardNode` contains a list of pending actions (add keyword, add categories, add metadata) that must be completed to finish the creation process.

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
InputStream is = new FileInputStream("/home/openkm/sample.eml");
WizardNode wn = okmMail.createWizard(null, "/okm:root/test", "test title", is, Mail.ORIGIN_EML);
IOUtils.closeQuietly(is);
```

#### forwardEmail
| Method | Returns | Description |
|--------|---------|-------------|
| `forwardEmail(String token, String uuid, List<String> users, List<String> roles, List<String> mails, String message)` | `Mail` | Forward an email to a list of users, roles, or external email addresses. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
List<String> users = Arrays.asList("userTest");
List<String> roles = Arrays.asList("ROLE_USER");
List<String> mails = Arrays.asList("test@none.com");
Mail forwarded = okmMail.forwardEmail(null, "f123a950-0329-4d62-8328-0ff500fd42db", users, roles, mails, "Any message");
```

#### getExtractedText
| Method | Returns | Description |
|--------|---------|-------------|
| `getExtractedText(String token, String uuid)` | `String` | Returns the text extracted from the mail by the text extraction process. The mail must have been processed by the extraction queue before this returns meaningful content. |

```java
OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
String text = okmMail.getExtractedText(null, "46762f90-82c6-4886-8d21-ad3017dd78a7");
```

---

## OKMNode

Base class that provides node-level operations applicable to any node type (documents, folders, mails, records): version management, locking, subscriptions, ZIP import/export, record promotion, and more.

> **Note:** `OKMNode` is registered with a named bean qualifier. Use `ContextWrapper.getContext().getBean("okmNode", OKMNode.class)` to obtain an instance.

### Basics

- **nodeId**: UUID of any node (document, folder, mail, record).
- **fldId**: UUID of a folder or record node.
- **token**: `null` to use the current user session; use `DbSessionManager.getInstance().getSystemToken()` for administrator access.

### Methods

#### getNodeByUuid
| Method | Returns | Description |
|--------|---------|-------------|
| `getNodeByUuid(String token, String uuid)` | `Node` | Get a node by its UUID. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
Node node = okmNode.getNodeByUuid(null, "78f9c377-e557-48c7-804e-35c0ca284739");
```

#### getVersionHistory
| Method | Returns | Description |
|--------|---------|-------------|
| `getVersionHistory(String token, String nodeId)` | `List<Version>` | Returns the version history of a node. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
List<Version> versions = okmNode.getVersionHistory(null, "78f9c377-e557-48c7-804e-35c0ca284739");
```

#### restoreVersion
| Method | Returns | Description |
|--------|---------|-------------|
| `restoreVersion(String token, String nodeId, String versionId)` | `void` | Restore a node to a specific version. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
okmNode.restoreVersion(null, "78f9c377-e557-48c7-804e-35c0ca284739", "1.2");
```

#### renameVersion
| Method | Returns | Description |
|--------|---------|-------------|
| `renameVersion(String token, String nodeId, String versionId, String newName)` | `void` | Rename a specific version of a node. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
okmNode.renameVersion(null, "78f9c377-e557-48c7-804e-35c0ca284739", "1.2", "newName");
```

#### deleteVersion
| Method | Returns | Description |
|--------|---------|-------------|
| `deleteVersion(String token, String nodeId, String versionId)` | `void` | Delete a specific version of a node. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
okmNode.deleteVersion(null, "78f9c377-e557-48c7-804e-35c0ca284739", "1.2");
```

#### purgeVersionHistory
| Method | Returns | Description |
|--------|---------|-------------|
| `purgeVersionHistory(String token, String nodeId)` | `void` | Permanently delete the entire version history of a node. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
okmNode.purgeVersionHistory(null, "3767deb4-21e7-4272-82be-fece5384fbab");
```

#### mayBePromotedAsRecord
| Method | Returns | Description |
|--------|---------|-------------|
| `mayBePromotedAsRecord(String token, String nodeId, boolean fullEvaluation)` | `PromoteAsRecordEvaluation` | Evaluate whether a node can be promoted to record status. When promotion is not possible, the result contains the reason. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
PromoteAsRecordEvaluation pre = okmNode.mayBePromotedAsRecord(null, "3767deb4-21e7-4272-82be-fece5384fbab", false);
```

#### promoteAsRecord
| Method | Returns | Description |
|--------|---------|-------------|
| `promoteAsRecord(String token, String nodeId)` | `void` | Promote a node to record status. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
okmNode.promoteAsRecord(null, "3767deb4-21e7-4272-82be-fece5384fbab");
```

#### degradeRecord
| Method | Returns | Description |
|--------|---------|-------------|
| `degradeRecord(String token, String nodeId)` | `void` | Remove the record status from a node. Requires administrator privileges. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
okmNode.degradeRecord(null, "3767deb4-21e7-4272-82be-fece5384fbab");
```

#### isElectronicRecordPath
| Method | Returns | Description |
|--------|---------|-------------|
| `isElectronicRecordPath(String token, String nodeId)` | `boolean` | Returns `true` if the node is located inside an electronic record (i.e., one of its ancestors is an electronic record). |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
boolean inRecord = okmNode.isElectronicRecordPath(null, "3767deb4-21e7-4272-82be-fece5384fbab");
```

#### getElectronicRecordInPath
| Method | Returns | Description |
|--------|---------|-------------|
| `getElectronicRecordInPath(String token, String nodeId)` | `Record` | Returns the first electronic record found in the path of the node. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
Record record = okmNode.getElectronicRecordInPath(null, "3767deb4-21e7-4272-82be-fece5384fbab");
```

#### getChildrenPaginated
| Method | Returns | Description |
|--------|---------|-------------|
| `getChildrenPaginated(String token, String nodeId, int offset, int limit, String filter, String orderByField, boolean orderAsc, List<Class<? extends NodeBase>> filteredByNodeTypeList, String pluginName)` | `PageInfo` | Returns a paginated list of child nodes. |

- `offset`/`limit`: control paging (e.g. offset=0, limit=10 for the first page).
- `orderByField`: `"name"` or `"created"`.
- `filteredByNodeTypeList`: restrict to specific node types (`NodeDocument.class`, `NodeFolder.class`, etc.). Pass `null` for all types.
- `pluginName`: optional plugin name filter; pass `null` to disable.

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
List<Class<? extends NodeBase>> types = Arrays.asList(NodeDocument.class, NodeFolder.class);
PageInfo pageInfo = okmNode.getChildrenPaginated(null, "39479efe-de5e-468e-91a7-24d2aa3f8837",
        0, 10, "", "created", true, types, null);
```

#### getChildrenByCategoryPaginated
| Method | Returns | Description |
|--------|---------|-------------|
| `getChildrenByCategoryPaginated(String token, String fldId, int offset, int limit, String filter, String orderByField, boolean orderAsc, List<Class<? extends NodeBase>> filteredByNodeTypeList, String pluginName)` | `PageInfo` | Returns a paginated list of child nodes filtered by category. Same parameters as `getChildrenPaginated`. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
PageInfo pageInfo = okmNode.getChildrenByCategoryPaginated(null, "39479efe-de5e-468e-91a7-24d2aa3f8837",
        0, 10, "", "name", true, null, null);
```

#### getBreadcrumb
| Method | Returns | Description |
|--------|---------|-------------|
| `getBreadcrumb(String token, String fldId)` | `List<BreadCrumbItem>` | Returns the breadcrumb path for a node. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
List<BreadCrumbItem> crumbs = okmNode.getBreadcrumb(null, "39479efe-de5e-468e-91a7-24d2aa3f8837");
```

#### subscribe / unsubscribe
| Method | Returns | Description |
|--------|---------|-------------|
| `subscribe(String token, String nodeId)` | `void` | Subscribe to change notifications for a node. |
| `unsubscribe(String token, String nodeId)` | `void` | Remove a subscription from a node. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
okmNode.subscribe(null, "39479efe-de5e-468e-91a7-24d2aa3f8837");
okmNode.unsubscribe(null, "39479efe-de5e-468e-91a7-24d2aa3f8837");
```

#### importZip
| Method | Returns | Description |
|--------|---------|-------------|
| `importZip(String token, String fldUuid, InputStream inputStream)` | `void` | Import a ZIP file into the folder identified by `fldUuid`. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
InputStream is = new FileInputStream("/home/openkm/import.zip");
okmNode.importZip(null, "212e7c1f-443d-4aac-a12c-0b818ca03419", is);
IOUtils.closeQuietly(is);
```

#### unzip
| Method | Returns | Description |
|--------|---------|-------------|
| `unzip(String token, String uuid, String destinationPath)` | `void` | Unzip a ZIP document already stored in the repository into `destinationPath` (a folder or record PATH). |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
okmNode.unzip(null, "82555dd1-bcc2-4e64-81cb-5f7c2b0d7801", "/okm:root/test");
```

#### exportZip
| Method | Returns | Description |
|--------|---------|-------------|
| `exportZip(List<String> paths, boolean withPath, boolean background, boolean excludeProperties)` | `ByteArrayInputStream` | Export a list of nodes as a ZIP file. `withPath` preserves directory structure; `excludeProperties` omits metadata. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
List<String> paths = Arrays.asList("/okm:root/test/logo.png", "/okm:root/test/invoice.pdf");
InputStream is = okmNode.exportZip(paths, true, false, false);
IOUtils.copy(is, new FileOutputStream("/home/openkm/export.zip"));
IOUtils.closeQuietly(is);
```

#### getNodesFromUuids
| Method | Returns | Description |
|--------|---------|-------------|
| `getNodesFromUuids(String token, String[] uuids)` | `List<Node>` | Returns a list of nodes for the given UUIDs. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
String[] uuids = {"0f6463f3-4d36-4091-b518-4fe7c353ee70", "d386cff8-1d4d-472f-9c6d-f21955ec499a"};
List<Node> nodes = okmNode.getNodesFromUuids(null, uuids);
```

#### evaluateZipDownload
| Method | Returns | Description |
|--------|---------|-------------|
| `evaluateZipDownload(String token, List<String> uuids)` | `ZipDownloadEvaluationResult` | Evaluate whether the selected nodes can be downloaded as a ZIP in real time or must be queued as a background job. Controlled by `download.zip.live.max.file.size` and `download.zip.live.max.files` configuration parameters. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
List<String> uuids = Arrays.asList("0f6463f3-4d36-4091-b518-4fe7c353ee70");
ZipDownloadEvaluationResult result = okmNode.evaluateZipDownload(null, uuids);
```

#### restore
| Method | Returns | Description |
|--------|---------|-------------|
| `restore(String token, String nodeId)` | `Node` | Restore a node from the trash to its original location. If the original location no longer exists the system will attempt the best alternative. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
Node node = okmNode.restore(null, "0f6463f3-4d36-4091-b518-4fe7c353ee70");
```

#### hasNodesLockedByOtherUser
| Method | Returns | Description |
|--------|---------|-------------|
| `hasNodesLockedByOtherUser(String token, String nodeId)` | `boolean` | Returns `true` if the node or any of its descendants are locked by a different user. Useful before attempting a hierarchy lock (e.g. locking a record). |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
boolean blocked = okmNode.hasNodesLockedByOtherUser(null, "0f6463f3-4d36-4091-b518-4fe7c353ee70");
```

#### lock / forceLock
| Method | Returns | Description |
|--------|---------|-------------|
| `lock(String token, String nodeId)` | `LockInfo` | Lock a node. Only the locking user can unlock it. |
| `forceLock(String token, String nodeId)` | `LockInfo` | Lock a node overriding any existing lock. Requires administrator privileges. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
LockInfo lockInfo = okmNode.lock(null, "1ec49da9-1746-4875-ae32-9281d7303a62");
```

#### unlock / forceUnlock
| Method | Returns | Description |
|--------|---------|-------------|
| `unlock(String token, String nodeId)` | `void` | Unlock a node. Only the user who locked it can unlock. |
| `forceUnlock(String token, String nodeId)` | `void` | Unlock any locked node regardless of who locked it. Requires administrator privileges. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
okmNode.unlock(null, "1ec49da9-1746-4875-ae32-9281d7303a62");
```

#### isLocked
| Method | Returns | Description |
|--------|---------|-------------|
| `isLocked(String token, String nodeId)` | `boolean` | Returns `true` if the node is locked. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
boolean locked = okmNode.isLocked(null, "1ec49da9-1746-4875-ae32-9281d7303a62");
```

#### getLockInfo
| Method | Returns | Description |
|--------|---------|-------------|
| `getLockInfo(String token, String nodeId)` | `LockInfo` | Returns the lock information for a locked node. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
LockInfo info = okmNode.getLockInfo(null, "1ec49da9-1746-4875-ae32-9281d7303a62");
```

#### setComment
| Method | Returns | Description |
|--------|---------|-------------|
| `setComment(String token, String uuid, String versionName, String comment)` | `void` | Set the comment for a specific version of a node. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
okmNode.setComment(null, "1ec49da9-1746-4875-ae32-9281d7303a62", "1.14", "Update comment");
```

#### exists
| Method | Returns | Description |
|--------|---------|-------------|
| `exists(String token, String parentUuid, String name)` | `boolean` | Returns `true` if a node with the given name exists as a direct child of `parentUuid`. |

```java
OKMNode okmNode = ContextWrapper.getContext().getBean("okmNode", OKMNode.class);
boolean exists = okmNode.exists(null, "39479efe-de5e-468e-91a7-24d2aa3f8837", "document.pdf");
```

---

## OKMNote

Used for managing notes attached to any node (document, folder, mail, record).

### Basics

- **nodeId**: UUID of any node (document, folder, mail, record).
- **noteId**: UUID of a specific note. The `Note` bean's `path` field contains this UUID.
- **token**: `null` to use the current user session; use `DbSessionManager.getInstance().getSystemToken()` for administrator access.
- Obtain an instance via `ContextWrapper.getContext().getBean(OKMNote.class)`.

### Methods

#### add
| Method | Returns | Description |
|--------|---------|-------------|
| `add(String token, String nodeId, String text)` | `Note` | Add a note to a node. Returns the created Note object. |

```java
OKMNote okmNote = ContextWrapper.getContext().getBean(OKMNote.class);
Note note = okmNote.add(null, "f123a950-0329-4d62-8328-0ff500fd42db", "the note text");
```

#### get
| Method | Returns | Description |
|--------|---------|-------------|
| `get(String token, String noteId)` | `Note` | Retrieve a note by its UUID. The `Note.path` field holds the UUID used as `noteId`. |

```java
OKMNote okmNote = ContextWrapper.getContext().getBean(OKMNote.class);
for (Note note : okmNote.list(null, "f123a950-0329-4d62-8328-0ff500fd42db")) {
    Note data = okmNote.get(null, note.getPath());
    System.out.println(data);
}
```

#### delete
| Method | Returns | Description |
|--------|---------|-------------|
| `delete(String token, String noteId)` | `void` | Delete a note. The `Note.path` field holds the UUID used as `noteId`. |

```java
OKMNote okmNote = ContextWrapper.getContext().getBean(OKMNote.class);
for (Note note : okmNote.list(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338")) {
    okmNote.delete(null, note.getPath());
}
```

#### set
| Method | Returns | Description |
|--------|---------|-------------|
| `set(String token, String noteId, String text)` | `String` | Update the text of a note. Returns the updated text. The `Note.path` field holds the UUID used as `noteId`. |

```java
OKMNote okmNote = ContextWrapper.getContext().getBean(OKMNote.class);
for (Note note : okmNote.list(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338")) {
    String updated = okmNote.set(null, note.getPath(), "new note text");
}
```

#### list
| Method | Returns | Description |
|--------|---------|-------------|
| `list(String token, String nodeId)` | `List<Note>` | Returns all notes attached to a node. |

```java
OKMNote okmNote = ContextWrapper.getContext().getBean(OKMNote.class);
for (Note note : okmNote.list(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338")) {
    System.out.println(note);
}
```

#### getNoteHistories
| Method | Returns | Description |
|--------|---------|-------------|
| `getNoteHistories(String token, String nodeId)` | `List<NoteHistory>` | Returns the historical notes of a node. |

```java
OKMNote okmNote = ContextWrapper.getContext().getBean(OKMNote.class);
for (NoteHistory nh : okmNote.getNoteHistories(null, "3c68b3a1-c65c-4b1e-84b5-9ce2712ca573")) {
    System.out.println(nh);
}
```

---

## OKMNotification

Used for managing node subscriptions and sending mail notifications about nodes.

### Basics

- **nodeId**: UUID of any node (document, folder, mail, record).
- **token**: `null` to use the current user session; use `DbSessionManager.getInstance().getSystemToken()` for administrator access.
- Obtain an instance via `ContextWrapper.getContext().getBean(OKMNotification.class)`.

### Methods

#### subscribe
| Method | Returns | Description |
|--------|---------|-------------|
| `subscribe(String token, String nodeId)` | `void` | Subscribe the current user to change notifications for a node. |

```java
OKMNotification okmNotification = ContextWrapper.getContext().getBean(OKMNotification.class);
okmNotification.subscribe(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338");
```

#### unsubscribe
| Method | Returns | Description |
|--------|---------|-------------|
| `unsubscribe(String token, String nodeId)` | `void` | Remove the current user's subscription from a node. |

```java
OKMNotification okmNotification = ContextWrapper.getContext().getBean(OKMNotification.class);
okmNotification.unsubscribe(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338");
```

#### getSubscriptors
| Method | Returns | Description |
|--------|---------|-------------|
| `getSubscriptors(String token, String nodeId)` | `Set<String>` | Returns the set of usernames subscribed to a node. |

```java
OKMNotification okmNotification = ContextWrapper.getContext().getBean(OKMNotification.class);
for (String user : okmNotification.getSubscriptors(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338")) {
    System.out.println(user);
}
```

#### notify
| Method | Returns | Description |
|--------|---------|-------------|
| `notify(String token, String nodeId, List<String> users, List<String> mails, String message, boolean attachment)` | `void` | Send a mail notification about a node. `users` is a list of OpenKM usernames to notify; `mails` is a list of external email addresses. When `attachment` is `true`, the node is attached to the notification email. |

```java
OKMNotification okmNotification = ContextWrapper.getContext().getBean(OKMNotification.class);
List<String> users = new ArrayList<>();
users.add("sochoa");
List<String> mails = new ArrayList<>();
okmNotification.notify(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", users, mails, "Body of the message", false);
```

---

## OKMProperty

Used for managing node properties: categories, keywords, encryption flags, and digital signature flags.

### Basics

- **nodeId**: UUID of any node (document, folder, mail, record).
- **catId**: UUID of a category folder node.
- **token**: `null` to use the current user session; use `DbSessionManager.getInstance().getSystemToken()` for administrator access.
- Obtain an instance via `ContextWrapper.getContext().getBean(OKMProperty.class)`.

### Methods

#### addCategory / removeCategory
| Method | Returns | Description |
|--------|---------|-------------|
| `addCategory(String token, String nodeId, String catId)` | `void` | Associate a category with a node. `catId` is the UUID of a category folder. |
| `removeCategory(String token, String nodeId, String catId)` | `void` | Remove a category association from a node. |

```java
OKMProperty okmProperty = ContextWrapper.getContext().getBean(OKMProperty.class);
okmProperty.addCategory(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "5cbc35fc-23c0-48f5-a7bc-3cfa1e7be25f");
okmProperty.removeCategory(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "5cbc35fc-23c0-48f5-a7bc-3cfa1e7be25f");
```

#### addKeyword / removeKeyword
| Method | Returns | Description |
|--------|---------|-------------|
| `addKeyword(String token, String nodeId, String keyword)` | `String` | Add a keyword to a node. Returns the added keyword. Keywords should be a single word; use `_` as a word separator (e.g. `two_words`). Case-sensitive — lowercase is recommended. |
| `removeKeyword(String token, String nodeId, String keyword)` | `void` | Remove a keyword from a node. |

```java
OKMProperty okmProperty = ContextWrapper.getContext().getBean(OKMProperty.class);
String kw = okmProperty.addKeyword(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "test");
okmProperty.removeKeyword(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "test");
```

#### setEncryption / unsetEncryption
| Method | Returns | Description |
|--------|---------|-------------|
| `setEncryption(String token, String nodeId, String cipherName)` | `void` | Mark a document node as encrypted. `cipherName` records the encryption mechanism name. Does **not** perform actual encryption — it only sets the flag in the database. |
| `unsetEncryption(String token, String nodeId)` | `void` | Remove the encryption flag from a document node. Does **not** decrypt data. |

```java
OKMProperty okmProperty = ContextWrapper.getContext().getBean(OKMProperty.class);
okmProperty.setEncryption(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "phrase");
okmProperty.unsetEncryption(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338");
```

#### setSigned / isSigned
| Method | Returns | Description |
|--------|---------|-------------|
| `setSigned(String token, String nodeId, boolean signed)` | `void` | Mark a document node as signed or unsigned. Does **not** perform a digital signature — it only sets the flag in the database. |
| `isSigned(String token, String nodeId)` | `boolean` | Returns `true` if the document node is marked as signed. |

```java
OKMProperty okmProperty = ContextWrapper.getContext().getBean(OKMProperty.class);
okmProperty.setSigned(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", true);
boolean signed = okmProperty.isSigned(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338");
```

---

## OKMPropertyGroup

Used for managing metadata groups (formerly "Property Groups") on nodes: adding/removing groups, reading/writing field values, listing available groups, managing the XML group definition, and AI-assisted metadata extraction.

> **Note:** Metadata field values of type `date` must use ISO-8601 basic format.
> Parse: `Calendar cal = ISO8601.parseBasic(value);`
> Format: `String value = ISO8601.formatBasic(Calendar.getInstance());`

### Basics

- **nodeId**: UUID of any node (document, folder, mail, record).
- **grpName**: Metadata group name, e.g. `"okg:technology"`.
- **token**: `null` for current user session; `DbSessionManager.getInstance().getSystemToken()` for administrator access.
- Obtain an instance via `ContextWrapper.getContext().getBean(OKMPropertyGroup.class)`.

### Methods

#### addGroup
| Method | Returns | Description |
|--------|---------|-------------|
| `addGroup(String token, String nodeId, String grpName, Map<String, String> props)` | `void` | Add a metadata group with initial field values to a node. Only the fields you want to set need to be included in `props`. |

For multi-select fields, encode the value as a JSON array string:
```java
properties.put("okp:technology.type", "[\"t1\", \"t2\"]");
// or using Gson:
properties.put("okp:technology.type", new Gson().toJson(Arrays.asList("t1", "t2")));
```

```java
OKMPropertyGroup okmPropertyGroup = ContextWrapper.getContext().getBean(OKMPropertyGroup.class);
Map<String, String> props = new HashMap<>();
props.put("okp:technology.comment", "comment sample");
props.put("okp:technology.date", ISO8601.formatBasic(Calendar.getInstance()));
okmPropertyGroup.addGroup(null, "4a3b1c1b-c880-45a3-a6ff-2c8b7c5adfa5", "okg:technology", props);
```

#### removeGroup
| Method | Returns | Description |
|--------|---------|-------------|
| `removeGroup(String token, String nodeId, String grpName)` | `void` | Remove a metadata group and all its values from a node. |

```java
OKMPropertyGroup okmPropertyGroup = ContextWrapper.getContext().getBean(OKMPropertyGroup.class);
okmPropertyGroup.removeGroup(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "okg:consulting");
```

#### getGroups
| Method | Returns | Description |
|--------|---------|-------------|
| `getGroups(String token, String nodeId)` | `List<PropertyGroup>` | Returns the metadata groups currently assigned to a node. |
| `getGroups(String token, String nodeId, String versionName)` | `List<PropertyGroup>` | Returns the metadata groups assigned to a specific version of a node. |

```java
OKMPropertyGroup okmPropertyGroup = ContextWrapper.getContext().getBean(OKMPropertyGroup.class);
for (PropertyGroup pg : okmPropertyGroup.getGroups(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338")) {
    System.out.println(pg);
}
// With version:
for (PropertyGroup pg : okmPropertyGroup.getGroups(null, "82555dd1-bcc2-4e64-81cb-5f7c2b0d7801", "1.2")) {
    System.out.println(pg);
}
```

#### getAllGroups
| Method | Returns | Description |
|--------|---------|-------------|
| `getAllGroups(String token)` | `List<PropertyGroup>` | Returns all metadata groups defined in the application. |
| `getAllGroups(String token, String nodeId)` | `List<PropertyGroup>` | Returns all metadata groups, filtered for a specific node via automation rules (available since 8.1.19). |

```java
OKMPropertyGroup okmPropertyGroup = ContextWrapper.getContext().getBean(OKMPropertyGroup.class);
for (PropertyGroup pg : okmPropertyGroup.getAllGroups(null)) {
    System.out.println(pg);
}
```

#### getUserGroups
| Method | Returns | Description |
|--------|---------|-------------|
| `getUserGroups(String token)` | `List<PropertyGroup>` | Returns all metadata groups available to the current user. |
| `getUserGroups(String token, String nodeId)` | `List<PropertyGroup>` | Returns all metadata groups available to the current user, filtered for a specific node via automation rules. |

```java
OKMPropertyGroup okmPropertyGroup = ContextWrapper.getContext().getBean(OKMPropertyGroup.class);
for (PropertyGroup pg : okmPropertyGroup.getUserGroups(null)) {
    System.out.println(pg);
}
```

#### getGroupProperties
| Method | Returns | Description |
|--------|---------|-------------|
| `getGroupProperties(String token, Long pgdId)` | `List<PropertyGroup>` | Returns the metadata group properties for a given group definition ID. |

```java
OKMPropertyGroup okmPropertyGroup = ContextWrapper.getContext().getBean(OKMPropertyGroup.class);
for (PropertyGroup pg : okmPropertyGroup.getGroupProperties(null, 1L)) {
    System.out.println(pg);
}
```

#### getProperties
| Method | Returns | Description |
|--------|---------|-------------|
| `getProperties(String token, String nodeId, String grpName)` | `Map<String, String>` | Returns the field values of a metadata group for a node. |
| `getProperties(String token, String nodeId, String grpName, String versionName)` | `Map<String, String>` | Returns the field values for a specific version of a node. |

```java
OKMPropertyGroup okmPropertyGroup = ContextWrapper.getContext().getBean(OKMPropertyGroup.class);
Map<String, String> props = okmPropertyGroup.getProperties(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "okg:consulting");
for (Map.Entry<String, String> e : props.entrySet()) {
    System.out.println(e.getKey() + ": " + e.getValue());
}
```

#### setProperties
| Method | Returns | Description |
|--------|---------|-------------|
| `setProperties(String token, String nodeId, String grpName, Map<String, String> props)` | `void` | Update the field values of a metadata group on a node. Only the fields included in `props` are updated. |

```java
OKMPropertyGroup okmPropertyGroup = ContextWrapper.getContext().getBean(OKMPropertyGroup.class);
Map<String, String> props = new HashMap<>();
props.put("okp:technology.comment", "updated comment");
okmPropertyGroup.setProperties(null, "4a3b1c1b-c880-45a3-a6ff-2c8b7c5adfa5", "okg:technology", props);
```

#### getPropertyGroupForm
| Method | Returns | Description |
|--------|---------|-------------|
| `getPropertyGroupForm(String token, String grpName)` | `List<FormElement>` | Returns the form element definitions for a metadata group (empty values — useful for rendering a blank form). |
| `getPropertyGroupForm(String token, String nodeId, String grpName)` | `List<FormElement>` | Returns the form element definitions for a metadata group in the context of a specific node. |

```java
OKMPropertyGroup okmPropertyGroup = ContextWrapper.getContext().getBean(OKMPropertyGroup.class);
for (FormElement fe : okmPropertyGroup.getPropertyGroupForm(null, "okg:consulting")) {
    System.out.println(fe);
}
```

#### hasGroup
| Method | Returns | Description |
|--------|---------|-------------|
| `hasGroup(String token, String nodeId, String grpName)` | `boolean` | Returns `true` if the node has the specified metadata group assigned. |

```java
OKMPropertyGroup okmPropertyGroup = ContextWrapper.getContext().getBean(OKMPropertyGroup.class);
boolean found = okmPropertyGroup.hasGroup(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "okg:consulting");
```

#### getSuggestions
| Method | Returns | Description |
|--------|---------|-------------|
| `getSuggestions(String token, String nodeId, String grpName, String propName)` | `List<String>` | Returns suggested values for a metadata select field. `propName` must refer to a field of select type. |

```java
OKMPropertyGroup okmPropertyGroup = ContextWrapper.getContext().getBean(OKMPropertyGroup.class);
for (String v : okmPropertyGroup.getSuggestions(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "okg:technology", "okp:technology.language")) {
    System.out.println(v);
}
```

#### registerDefinition / getRegisteredDefinition
| Method | Returns | Description |
|--------|---------|-------------|
| `registerDefinition(String token, String pgDef, String pgName)` | `void` | Upload the XML metadata group definition to the repository. Requires `ROLE_ADMIN`. |
| `getRegisteredDefinition(String token)` | `String` | Returns the current XML metadata group definition. Requires `ROLE_ADMIN`. |

```java
OKMPropertyGroup okmPropertyGroup = ContextWrapper.getContext().getBean(OKMPropertyGroup.class);
InputStream is = new FileInputStream("/home/files/PropertyGroups.xml");
okmPropertyGroup.registerDefinition(null, IOUtils.toString(is), "test");
IOUtils.closeQuietly(is);

String pgDef = okmPropertyGroup.getRegisteredDefinition(null);
```

#### getSuggestBoxKeyValue
| Method | Returns | Description |
|--------|---------|-------------|
| `getSuggestBoxKeyValue(String token, String nodeId, String grpName, String propertyName, String key)` | `KeyValue` | Returns the key-value pair for a specific key in a suggest-box field. |

```java
OKMPropertyGroup okmPropertyGroup = ContextWrapper.getContext().getBean(OKMPropertyGroup.class);
KeyValue kv = okmPropertyGroup.getSuggestBoxKeyValue(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "okg:groupname", "okp:groupname.propertyname", "namekey");
System.out.println(kv.getKey() + ": " + kv.getValue());
```

#### getSuggestBoxKeyValuesFiltered
| Method | Returns | Description |
|--------|---------|-------------|
| `getSuggestBoxKeyValuesFiltered(String token, String nodeId, String grpName, String propertyName, String filter)` | `List<KeyValue>` | Returns key-value pairs from a suggest-box field, filtered by a search string. |

```java
OKMPropertyGroup okmPropertyGroup = ContextWrapper.getContext().getBean(OKMPropertyGroup.class);
List<KeyValue> kvList = okmPropertyGroup.getSuggestBoxKeyValuesFiltered(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "okg:groupname", "okp:groupname.propertyname", "filter");
for (KeyValue kv : kvList) {
    System.out.println(kv.getKey() + ": " + kv.getValue());
}
```

#### addOrSetPropertyGroupWithAI
| Method | Returns | Description |
|--------|---------|-------------|
| `addOrSetPropertyGroupWithAI(String token, String nodeId, String grpName)` | `void` | Use AI to automatically extract and populate metadata group values for a node. Adds the group if not yet assigned; updates it otherwise. Requires AI to be configured. |

```java
OKMPropertyGroup okmPropertyGroup = ContextWrapper.getContext().getBean(OKMPropertyGroup.class);
okmPropertyGroup.addOrSetPropertyGroupWithAI(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "okg:technology");
```

#### getExtractedPropertyGroupWithAI
| Method | Returns | Description |
|--------|---------|-------------|
| `getExtractedPropertyGroupWithAI(String token, String nodeId, String grpName)` | `Map<String, String>` | Use AI to extract metadata group values for a node and return them without saving. Useful for previewing AI-extracted values before committing. Requires AI to be configured. |

```java
OKMPropertyGroup okmPropertyGroup = ContextWrapper.getContext().getBean(OKMPropertyGroup.class);
Map<String, String> props = okmPropertyGroup.getExtractedPropertyGroupWithAI(null, "b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "okg:technology");
for (Map.Entry<String, String> e : props.entrySet()) {
    System.out.println(e.getKey() + ": " + e.getValue());
}
```

---

## OKMReport

Facade for report operations. Obtain via `ContextWrapper.getContext().getBean(OKMReport.class)`.

### Report format constants (defined in `Report` class)

| Constant | Value |
|---|---|
| `Report.FORMAT_TEXT` | `"text/plain"` |
| `Report.FORMAT_HTML` | `"text/html"` |
| `Report.FORMAT_CSV` | `"text/csv"` |
| `Report.FORMAT_PDF` | `"application/pdf"` |
| `Report.FORMAT_RTF` | `"application/rtf"` |
| `Report.FORMAT_ODT` | `"application/vnd.oasis.opendocument.text"` |
| `Report.FORMAT_XLSX` | `"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"` |
| `Report.FORMAT_DOCX` | `"application/vnd.openxmlformats-officedocument.wordprocessingml.document"` |

### list

```
List<Report> list(String token, boolean active)
```

Returns a list of reports. When `active` is `true`, only active reports are returned; otherwise all reports are returned.

```java
OKMReport okmReport = ContextWrapper.getContext().getBean(OKMReport.class);
System.out.println(okmReport.list(null, true));
```

### get

```
Report get(String token, long rpId)
```

Returns a `Report` object identified by `rpId`.

```java
OKMReport okmReport = ContextWrapper.getContext().getBean(OKMReport.class);
System.out.println(okmReport.get(null, 1));
```

### execute (plugin-based)

```
PageInfo execute(String token, String pluginName, Map<String, String> params)
```

Executes a report plugin by name and returns a `PageInfo` object. `pluginName` is the name of a plugin registered in OpenKM.

```java
OKMReport okmReport = ContextWrapper.getContext().getBean(OKMReport.class);

Calendar yesterday = Calendar.getInstance();
yesterday.add(Calendar.DATE, -1);
Calendar today = Calendar.getInstance();

SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd");

Map<String, String> params = new HashMap<>();
params.put("from_date", sdf.format(yesterday.getTime()));
params.put("to_date", sdf.format(today.getTime()));
PageInfo pageInfo = okmReport.execute(null, "pluginName", params);
System.out.println(pageInfo);
```

### execute (JasperReports)

```
InputStream execute(String token, long rpId, Map<String, Object> params, String format)
```

Executes a JasperReports report identified by `rpId` with the given parameters and output format. Returns the report as an `InputStream`.

```java
OKMReport okmReport = ContextWrapper.getContext().getBean(OKMReport.class);

Map<String, Object> params = new HashMap<>();
params.put("from_date", "2024-01-01");
params.put("to_date", "2024-12-31");
InputStream is = okmReport.execute(null, 1, params, Report.FORMAT_PDF);
```

### getSqlReport

```
SqlReport getSqlReport(String token, long rpId)
```

Returns a `SqlReport` object identified by `rpId`.

```java
OKMReport okmReport = ContextWrapper.getContext().getBean(OKMReport.class);
SqlReport sqlReport = okmReport.getSqlReport(null, 1);
System.out.println(sqlReport);
```

### listSqlReports

```
List<SqlReport> listSqlReports(String token, boolean active)
```

Returns a list of SQL reports. When `active` is `true`, only active SQL reports are returned; otherwise all are returned.

```java
OKMReport okmReport = ContextWrapper.getContext().getBean(OKMReport.class);
for (SqlReport sqlReport : okmReport.listSqlReports(null, true)) {
    System.out.println(sqlReport);
}
```

### executeSqlReport

```
InputStream executeSqlReport(String token, long rpId)
```

Executes a SQL report identified by `rpId` and returns the result as an `InputStream`.

```java
OKMReport okmReport = ContextWrapper.getContext().getBean(OKMReport.class);
InputStream is = okmReport.executeSqlReport(null, 1);
```

---

## OKMRecord

Facade for record operations. `OKMRecord` extends `OKMNode` (inherits lock/unlock/forceUnlock etc.). Obtain via `ContextWrapper.getContext().getBean(OKMRecord.class)`.

### create

```
Record create(String token, Record rec)
```

Creates a new record. The `path` field of `rec` must be set to the destination path. Returns the created `Record` object.

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
Record rec = new Record();
rec.setPath("/okm:root/test");
Record newRec = okmRecord.create(null, rec);
System.out.println(newRec);
```

### createSimple

```
Record createSimple(String token, String recPath)
```

Creates a new record at the given path. Returns the created `Record` object.

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
Record newRec = okmRecord.createSimple(null, "/okm:root/PKI-100200");
System.out.println(newRec);
```

### getProperties

```
Record getProperties(String token, String recId)
```

Returns the properties of the record identified by `recId` (UUID).

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
Record rec = okmRecord.getProperties(null, "7f867772-7476-4176-b86f-bdeb8bce1c5f");
System.out.println(rec);
```

### delete

```
void delete(String token, String recId)
```

Moves the record to the trash.

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
okmRecord.delete(null, "7f867772-7476-4176-b86f-bdeb8bce1c5f");
```

### purge

```
void purge(String token, String recId)
```

Permanently removes the record from the repository. This action cannot be undone without restoring from a backup.

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
okmRecord.purge(null, "7f867772-7476-4176-b86f-bdeb8bce1c5f");
```

### rename

```
Record rename(String token, String recId, String newName)
```

Renames a record. Returns the updated `Record` object.

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
Record renamedRec = okmRecord.rename(null, "7f867772-7476-4176-b86f-bdeb8bce1c5f", "newname");
System.out.println(renamedRec);
```

### move

```
void move(String token, String recId, String dstId)
```

Moves a record into a folder or another record. `dstId` is the destination UUID.

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
okmRecord.move(null, "7f867772-7476-4176-b86f-bdeb8bce1c5f", "b6848ac2-345f-454e-964a-eba4dcc020e6");
```

### copy (no rename)

```
Record copy(String token, String recId, String dstId)
```

Copies a record into a folder or record. Only binary data and security grants are copied. Returns the new `Record` object.

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
Record newRec = okmRecord.copy(null, "7f867772-7476-4176-b86f-bdeb8bce1c5f", "b6848ac2-345f-454e-964a-eba4dcc020e6");
System.out.println(newRec);
```

### copy (with rename)

```
Record copy(String token, String recId, String dstId, String newName)
```

Copies a record with a new name. When `newName` is `null`, the original name is preserved. Returns the new `Record` object.

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
Record newRec = okmRecord.copy(null, "7f867772-7476-4176-b86f-bdeb8bce1c5f", "b6848ac2-345f-454e-964a-eba4dcc020e6", "newname");
System.out.println(newRec);
```

### extendedCopy

```
Record extendedCopy(String token, String recId, String dstId, String newName, ExtendedAttributes extAttr)
```

Copies a record with selectable extended attributes. Returns the new `Record` object. Use `ExtendedAttributes` to control what is copied (categories, keywords, property groups, notes, wiki).

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
ExtendedAttributes extAttr = new ExtendedAttributes();
extAttr.setKeywords(true);
extAttr.setCategories(true);
extAttr.setNotes(true);
Record newRec = okmRecord.extendedCopy(null, "7f867772-7476-4176-b86f-bdeb8bce1c5f",
        "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474", "PKI-100201", extAttr);
System.out.println(newRec);
```

### isValid

```
boolean isValid(String token, String recId)
```

Returns `true` if the node identified by `recId` is a record.

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
boolean valid = okmRecord.isValid(null, "7f867772-7476-4176-b86f-bdeb8bce1c5f");
System.out.println(valid);
```

### getPath

```
String getPath(String token, String uuid)
```

Converts a record UUID to its repository path.

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
String path = okmRecord.getPath(null, "7f867772-7476-4176-b86f-bdeb8bce1c5f");
System.out.println(path);
```

### getChildren

```
List<Record> getChildren(String token, String fldId)
```

Returns all records whose parent is `fldId` (folder or record UUID).

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
for (Record rec : okmRecord.getChildren(null, "b6848ac2-345f-454e-964a-eba4dcc020e6")) {
    System.out.println(rec);
}
```

### setTitle

```
void setTitle(String token, String recId, String title)
```

Sets the title of a record.

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
okmRecord.setTitle(null, "7f867772-7476-4176-b86f-bdeb8bce1c5f", "new title");
```

### setNodeClass

```
void setNodeClass(String token, String recId, long ncId)
```

Sets the node class of a record. `ncId` is the node class identifier.

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
okmRecord.setNodeClass(null, "7ce1b4a8-4ade-4dce-8d7d-4e99a6cd368b", 2);
```

### setDispositionStage

```
void setDispositionStage(String token, String recId, long stage)
```

Sets the disposition stage of a record.

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
okmRecord.setDispositionStage(null, "7ce1b4a8-4ade-4dce-8d7d-4e99a6cd368b", 1);
```

### addNodeClassChildren

```
void addNodeClassChildren(String token, String recId, long ncId)
```

Propagates the node class value to parent containers (folders) to indicate they contain a record of this type. Used for navigation.

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
okmRecord.addNodeClassChildren(null, "7ce1b4a8-4ade-4dce-8d7d-4e99a6cd368b", 2);
```

### setDescription

```
void setDescription(String token, String uuid, String description)
```

Sets the description of a record.

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
okmRecord.setDescription(null, "7ce1b4a8-4ade-4dce-8d7d-4e99a6cd368b", "some description");
```

### createMissingRecords

```
void createMissingRecords(String token, String recPath)
```

Creates any missing records under the given path.

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
okmRecord.createMissingRecords(null, "/okm:root/PKI");
```

### createFromTemplate

```
Record createFromTemplate(String token, String fldId, String dstPath, Map<String, String> properties, ExtendedAttributes extAttr)
```

Creates a new record from a template folder. `fldId` is the template folder UUID, `dstPath` is the destination path, `properties` is a map of property group values to apply. Returns the created `Record` object.

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
Map<String, String> properties = new HashMap<>();
properties.put("okp:group.property", "value");
ExtendedAttributes extAttr = new ExtendedAttributes();
extAttr.setKeywords(true);
extAttr.setCategories(true);
Record newRec = okmRecord.createFromTemplate(null, "b6848ac2-345f-454e-964a-eba4dcc020e6",
        "/okm:root/PKI-100300", properties, extAttr);
System.out.println(newRec);
```

### createWizard

```
WizardNode createWizard(String token, String recPath, String title, long nodeClass)
```

Creates a new record using a wizard. `recPath` is any valid folder or record UUID. Returns a `WizardNode` containing a list of pending actions (add keywords, categories, metadata) that must be completed to finish record creation.

```java
OKMRecord okmRecord = ContextWrapper.getContext().getBean(OKMRecord.class);
WizardNode wn = okmRecord.createWizard(null, "1f323e88-64ee-4f57-91e2-9276f8c603f9", "PKI-100200", 0);
System.out.println(wn);
```

---

## OKMRelation

Facade for node relation operations. Obtain via `ContextWrapper.getContext().getBean(OKMRelation.class)`.

### Relation types (constants in `NodeRelationType`)

- `NodeRelationType.BIDIRECTIONAL` — bidirectional relation between two nodes
- `NodeRelationType.PARENT_CHILD` — parent-child relation
- `NodeRelationType.MANY_TO_MANY` — many-to-many relation (used with relation groups)

### getRelationTypes

```
List<RelationType> getRelationTypes(String token, String type)
```

Returns all relation definitions for the given type.

```java
OKMRelation okmRelation = ContextWrapper.getContext().getBean(OKMRelation.class);
for (RelationType rt : okmRelation.getRelationTypes(null, NodeRelationType.BIDIRECTIONAL)) {
    System.out.println(rt);
}
```

### add

```
void add(String token, String nodeAId, String nodeBId, long relationType)
```

Creates a relation between two nodes. `nodeAId` and `nodeBId` are UUIDs. `relationType` is the ID of a `RelationType`.

```java
OKMRelation okmRelation = ContextWrapper.getContext().getBean(OKMRelation.class);
for (RelationType rt : okmRelation.getRelationTypes(null, NodeRelationType.BIDIRECTIONAL)) {
    if (rt.getTitle().equals("invoice")) {
        okmRelation.add(null, "d168924d-e801-426d-a222-00124a1461bd", "1f8ee9b8-0357-447b-95d0-c7b0adf887ec", rt.getId());
    }
}
```

### delete

```
void delete(String token, long relationId)
```

Deletes a relation by its ID. A relation can only be deleted when it is not in use.

```java
OKMRelation okmRelation = ContextWrapper.getContext().getBean(OKMRelation.class);
for (Relation relation : okmRelation.getRelations(null, "d168924d-e801-426d-a222-00124a1461bd")) {
    if (relation.getRelationTitle().equals("invoice")) {
        okmRelation.delete(null, relation.getId());
    }
}
```

### getRelations

```
List<Relation> getRelations(String token, String nodeId)
```

Returns all relations for a node.

```java
OKMRelation okmRelation = ContextWrapper.getContext().getBean(OKMRelation.class);
for (Relation relation : okmRelation.getRelations(null, "d168924d-e801-426d-a222-00124a1461bd")) {
    System.out.println(relation);
}
```

### getRelationGroups (by node)

```
List<RelationGroup> getRelationGroups(String token, String nodeId)
```

Returns all relation groups for a node.

```java
OKMRelation okmRelation = ContextWrapper.getContext().getBean(OKMRelation.class);
for (RelationGroup rg : okmRelation.getRelationGroups(null, "d168924d-e801-426d-a222-00124a1461bd")) {
    System.out.println(rg);
}
```

### getRelationGroups (paginated)

```
RelationGroupResultSet getRelationGroups(String token, long relationTypeId, String filter, int offset, int limit)
```

Returns a paginated list of relation groups filtered by relation type ID and optional name filter.

```java
OKMRelation okmRelation = ContextWrapper.getContext().getBean(OKMRelation.class);
RelationGroupResultSet resultSet = okmRelation.getRelationGroups(null, 1, "", 0, 10);
System.out.println(resultSet);
```

### addGroup

```
void addGroup(String token, String nodeId, String groupName, long type)
```

Adds a new relation group to a node. Only `NodeRelationType.MANY_TO_MANY` is meaningful for groups. `type` is the ID of a `RelationType`.

```java
OKMRelation okmRelation = ContextWrapper.getContext().getBean(OKMRelation.class);
for (RelationType rt : okmRelation.getRelationTypes(null, NodeRelationType.MANY_TO_MANY)) {
    if (rt.getTitle().equals("staple")) {
        okmRelation.addGroup(null, "d168924d-e801-426d-a222-00124a1461bd", "staple group", rt.getId());
    }
}
```

### addNodeToGroup

```
void addNodeToGroup(String token, String nodeId, long groupId)
```

Adds a node to an existing relation group.

```java
OKMRelation okmRelation = ContextWrapper.getContext().getBean(OKMRelation.class);
for (RelationGroup rg : okmRelation.getRelationGroups(null, "d168924d-e801-426d-a222-00124a1461bd")) {
    if (rg.getRelationTitle().equals("staple")) {
        okmRelation.addNodeToGroup(null, "1f8ee9b8-0357-447b-95d0-c7b0adf887ec", rg.getId());
    }
}
```

### deleteGroup

```
void deleteGroup(String token, String nodeId, long groupId)
```

Removes a node from a relation group.

```java
OKMRelation okmRelation = ContextWrapper.getContext().getBean(OKMRelation.class);
for (RelationGroup rg : okmRelation.getRelationGroups(null, "8f101a85-88e7-4abe-8175-c5fea3e17d8b")) {
    if (rg.getName().equals("staple group")) {
        okmRelation.deleteGroup(null, "46762f90-82c6-4886-8d21-ad3017dd78a7", rg.getId());
    }
}
```

### getGroup

```
RelationGroup getGroup(String token, long groupId)
```

Returns a relation group by its ID.

```java
OKMRelation okmRelation = ContextWrapper.getContext().getBean(OKMRelation.class);
RelationGroup rg = okmRelation.getGroup(null, 1);
System.out.println(rg);
```

### setGroupName

```
void setGroupName(String token, long groupId, String groupName)
```

Renames a relation group.

```java
OKMRelation okmRelation = ContextWrapper.getContext().getBean(OKMRelation.class);
okmRelation.setGroupName(null, 1, "new name");
```

---

## OKMRepository

Facade for repository-level operations (root folders, trash, UUID/path conversion, versioning info). Obtain via `ContextWrapper.getContext().getBean(OKMRepository.class)`.

### getRootFolder

```
Folder getRootFolder(String token)
```

Returns the `Folder` object for `/okm:root`.

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
Folder fld = okmRepository.getRootFolder(null);
System.out.println(fld);
```

### getTrashFolder

```
Folder getTrashFolder(String token)
```

Returns the current user's trash folder (`/okm:trash/{userId}`).

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
Folder fld = okmRepository.getTrashFolder(null);
System.out.println(fld);
```

### getTrashFolderBase

```
Folder getTrashFolderBase(String token)
```

Returns the base trash folder `/okm:trash`.

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
Folder fld = okmRepository.getTrashFolderBase(null);
System.out.println(fld);
```

### getTemplatesFolder

```
Folder getTemplatesFolder(String token)
```

Returns the `Folder` object for `/okm:templates`.

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
Folder fld = okmRepository.getTemplatesFolder(null);
System.out.println(fld);
```

### getPersonalFolder

```
Folder getPersonalFolder(String token)
```

Returns the current user's personal folder (`/okm:personal/{userId}`).

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
Folder fld = okmRepository.getPersonalFolder(null);
System.out.println(fld);
```

### getPersonalFolderBase

```
Folder getPersonalFolderBase(String token)
```

Returns the base personal folder `/okm:personal`.

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
Folder fld = okmRepository.getPersonalFolderBase(null);
System.out.println(fld);
```

### getMailFolder

```
Folder getMailFolder(String token)
```

Returns the current user's mail folder (`/okm:mail/{userId}`).

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
Folder fld = okmRepository.getMailFolder(null);
System.out.println(fld);
```

### getMailFolderBase

```
Folder getMailFolderBase(String token)
```

Returns the base mail folder `/okm:mail`.

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
Folder fld = okmRepository.getMailFolderBase(null);
System.out.println(fld);
```

### getCategoriesFolder

```
Folder getCategoriesFolder(String token)
```

Returns the `Folder` object for `/okm:categories`.

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
Folder fld = okmRepository.getCategoriesFolder(null);
System.out.println(fld);
```

### getMetadataFolder

```
Folder getMetadataFolder(String token)
```

Returns the metadata folder.

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
Folder folder = okmRepository.getMetadataFolder(null);
System.out.println(folder);
```

### purgeTrash

```
void purgeTrash(String token)
```

Permanently removes all nodes from the current user's trash (`/okm:trash/{userId}`). This cannot be undone.

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
okmRepository.purgeTrash(null);
```

### getUpdateMessage

```
String getUpdateMessage(String token)
```

Returns a message when a new OpenKM release is available.

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
String msg = okmRepository.getUpdateMessage(null);
System.out.println(msg);
```

### getRepositoryUuid

```
String getRepositoryUuid(String token)
```

Returns the unique identifier of this OpenKM installation.

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
String uuid = okmRepository.getRepositoryUuid(null);
System.out.println(uuid);
```

### hasNode

```
boolean hasNode(String token, String nodeId)
```

Returns `true` if a node with the given UUID exists in the repository.

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
boolean found = okmRepository.hasNode(null, "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474");
System.out.println(found);
```

### getNodePath

```
String getNodePath(String token, String uuid)
```

Converts a node UUID to its repository path.

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
String path = okmRepository.getNodePath(null, "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474");
System.out.println(path);
```

### getNodeUuid

```
String getNodeUuid(String token, String path)
```

Converts a node path to its UUID.

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
String uuid = okmRepository.getNodeUuid(null, "/okm:root/api");
System.out.println(uuid);
```

### getAppVersion

```
AppVersion getAppVersion(String token)
```

Returns information about the current OpenKM version.

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
AppVersion appVersion = okmRepository.getAppVersion(null);
System.out.println(appVersion);
```

### copyAttributes

```
void copyAttributes(String token, String srcId, String dstId, ExtendedAttributes extAttr)
```

Copies selected attributes from one node to another. Use `ExtendedAttributes` to control what is copied (categories, keywords, property groups, notes, wiki).

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
ExtendedAttributes extAttr = new ExtendedAttributes();
extAttr.setKeywords(true);
extAttr.setCategories(true);
extAttr.setNotes(true);
extAttr.setPropertyGroups(true);
extAttr.setWiki(true);
okmRepository.copyAttributes(null, "d168924d-e801-426d-a222-00124a1461bd", "9f64248c-e049-4706-b89e-6d725842c7f7", extAttr);
```

### getChangeLog

```
List<ChangeLogged> getChangeLog(String token, String nodePath, Calendar modifyFrom)
```

Returns all changes under `nodePath` and its subfolders since `modifyFrom`. Used by the desktop synchronization application.

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
Calendar now = Calendar.getInstance();
for (ChangeLogged cl : okmRepository.getChangeLog(null, "/okm:root/synchronized", now)) {
    System.out.println(cl);
}
```

### getAppLicense

```
LicenseInfo getAppLicense(String token)
```

Returns license information for this OpenKM installation.

```java
OKMRepository okmRepository = ContextWrapper.getContext().getBean(OKMRepository.class);
LicenseInfo licenseInfo = okmRepository.getAppLicense(null);
System.out.println(licenseInfo);
```

---

## OKMSearch

Provides full-text and metadata search capabilities. Most methods accept a `QueryParams` object that supports AND-only logic across multiple filter fields.

**Obtain instance:**
```java
OKMSearch okmSearch = ContextWrapper.getContext().getBean(OKMSearch.class);
```

**`token` parameter:** pass `null` to use the current user session, or `DbSessionManager.getInstance().getSystemToken()` for the system/admin user.

**QueryParams fields:**

| Field | Type | Wildcards | Description |
|---|---|---|---|
| domain | long | No | Node type filter: `QueryParams.DOCUMENT`, `QueryParams.FOLDER`, `QueryParams.MAIL`, `QueryParams.RECORD`. Combine with `|`. Default: DOCUMENT. |
| author | String | No | Filter by creator userId. |
| name | String | Yes | Filter by node name. |
| title | String | Yes | Filter by title. |
| keywords | Set\<String\> | Yes | Filter by keywords. |
| categories | Set\<String\> | No | Filter by category UUID (not path). |
| content | String | Yes | Filter by binary content. |
| mimeType | String | No | Filter by MIME type (documents only). |
| language | String | No | Filter by language (documents only). |
| folder | String | No | Filter by folder UUID (not path). Defaults to `/okm:root`. |
| folderRecursive | Boolean | No | Enable recursive folder filtering. |
| lastModifiedFrom | Calendar | No | Filter nodes created after date. |
| lastModifiedTo | Calendar | No | Filter nodes created before date. |
| mailSubject | String | Yes | Filter by mail subject. |
| mailFrom | String | Yes | Filter by mail "from" field. |
| mailTo | String | Yes | Filter by mail "to" field. |
| notes | String | Yes | Filter by notes. |
| properties | Map\<String, String\> | Yes (most) | Filter by metadata group field values: `("okp:group.field", "value")`. For date ranges use ISO8601 format: `ISO8601.formatBasic(from)+","+ISO8601.formatBasic(to)`. For multi-select fields separate values with `;`. |

**Wildcard syntax:** `*` matches multiple characters, `?` matches a single character. Example: `test?.html`, `?test*`.

**Mail type constants:**
- `OKMSearch.TYPE_MAIL_ALL = 0`
- `OKMSearch.TYPE_MAIL_WITH_ATTACHMENT = 1`
- `OKMSearch.TYPE_MAIL_WITHOUT_ATTACHMENT = 2`

---

### find

```
List<QueryResult> find(String token, QueryParams params)
```

Returns all results matching the QueryParams filter.

```java
OKMSearch okmSearch = ContextWrapper.getContext().getBean(OKMSearch.class);
QueryParams qParams = new QueryParams();
qParams.setDomain(QueryParams.DOCUMENT + QueryParams.FOLDER);
qParams.setName("test*");
for (QueryResult qr : okmSearch.find(null, qParams)) {
    System.out.println(qr);
}
```

---

### find (with propertiesPlugin)

```
List<QueryResult> find(String token, QueryParams params, String propertiesPlugin)
```

Returns results with lightweight node properties populated via a `NodeProperties` plugin. `propertiesPlugin` is the canonical class name of the implementing class.

```java
for (QueryResult qr : okmSearch.find(null, qParams, "com.openkm.plugin.properties.SimpleNodeProperties")) {
    System.out.println(qr);
}
```

---

### findPaginated

```
ResultSet findPaginated(String token, QueryParams params, int offset, int limit)
```

Returns a paginated `ResultSet`. Use `rs.getTotal()` for total count and `rs.getResults()` for the page.

```java
ResultSet rs = okmSearch.findPaginated(null, qParams, 0, 10);
System.out.println("Total results:" + rs.getTotal());
for (QueryResult qr : rs.getResults()) {
    System.out.println(qr);
}
```

---

### findWithMetadata

```
List<QueryResult> findWithMetadata(String token, QueryParams params, String propertiesPlugin, List<String> groups)
```

Returns results including metadata group values. `groups` is a list of metadata group names (e.g. `"okg:tpl"`).

```java
List<String> groups = new ArrayList<>();
groups.add("okg:tpl");
for (QueryResult qr : okmSearch.findWithMetadata(null, qParams, "com.openkm.plugin.properties.SimpleNodeProperties", groups)) {
    System.out.println(qr);
}
```

---

### findWithMetadataPaginated

```
ResultSet findWithMetadataPaginated(String token, QueryParams params, int offset, int limit, String propertiesPlugin, List<String> groups)
```

Paginated version of `findWithMetadata`.

```java
ResultSet rs = okmSearch.findWithMetadataPaginated(null, qParams, 0, 10, "com.openkm.plugin.properties.SimpleNodeProperties", groups);
```

---

### findByQuery

```
List<QueryResult> findByQuery(String token, String query)
List<QueryResult> findByQuery(String token, String query, String propertiesPlugin)
List<QueryResult> findByQuery(String token, String query, String sortField, boolean sortReverse, String propertiesPlugin)
```

Searches using Lucene query syntax (`field:value`). Available `sortField` values: `name`, `author`, `lastModified`.

```java
for (QueryResult qr : okmSearch.findByQuery(null, "text:grial AND name:o*.pdf")) {
    System.out.println(qr);
}
// With sort:
for (QueryResult qr : okmSearch.findByQuery(null, "text:grial AND name:o*.pdf", "name", true, "com.openkm.plugin.properties.SimpleNodeProperties")) {
    System.out.println(qr);
}
```

---

### findByQueryPaginated

```
ResultSet findByQueryPaginated(String token, String query, int offset, int limit)
ResultSet findByQueryPaginated(String token, String query, int offset, int limit, String propertiesPlugin)
ResultSet findByQueryPaginated(String token, String query, String sortField, boolean sortReverse, int offset, int limit)
ResultSet findByQueryPaginated(String token, String query, String sortField, boolean sortReverse, int offset, int limit, String propertiesPlugin)
```

Paginated Lucene query search. Available `sortField` values: `name`, `author`, `lastModified`.

```java
ResultSet rs = okmSearch.findByQueryPaginated(null, "text:grial AND name:o*.pdf", "name", true, 0, 10);
System.out.println("Total results:" + rs.getTotal());
for (QueryResult qr : rs.getResults()) {
    System.out.println(qr);
}
```

---

### findSimpleNodeBaseByQueryPaginated

```
SimpleNodeBaseResultSet findSimpleNodeBaseByQueryPaginated(String token, String query, String sortField, boolean sortReverse, int offset, int limit)
```

Returns lightweight `SimpleNodeBase` results (uuid, path, name, type) from a Lucene query. Faster than full object retrieval.

```java
SimpleNodeBaseResultSet resultSet = okmSearch.findSimpleNodeBaseByQueryPaginated(null, "name:test*", "name", true, 0, 10);
for (SimpleNodeBase snb : resultSet.getResults()) {
    System.out.println(snb);
}
```

---

### findSimpleNodeBasePaginated

```
SimpleNodeBaseResultSet findSimpleNodeBasePaginated(String token, QueryParams params, int offset, int limit)
```

Returns lightweight `SimpleNodeBase` results from a `QueryParams` filter.

```java
QueryParams qParams = new QueryParams();
qParams.setDomain(QueryParams.DOCUMENT + QueryParams.FOLDER);
qParams.setName("test*");
SimpleNodeBaseResultSet resultSet = okmSearch.findSimpleNodeBasePaginated(null, qParams, 0, 10);
for (SimpleNodeBase snb : resultSet.getResults()) {
    System.out.println(snb);
}
```

---

### saveSearch

```
Long saveSearch(String token, QueryParams params)
```

Saves search parameters for later reuse. `params.queryName` must be set. Returns the saved search ID.

```java
qParams.setQueryName("sample search");
okmSearch.saveSearch(null, qParams);
```

---

### updateSearch

```
void updateSearch(String token, QueryParams params)
```

Updates a previously saved search. Only the owner can update their own searches.

---

### getSearch

```
QueryParams getSearch(String token, int qpId)
```

Retrieves a saved search by its ID.

---

### getAllSearches

```
List<QueryParams> getAllSearches(String token)
```

Returns all saved searches belonging to the current user.

---

### deleteSearch

```
void deleteSearch(String token, long qpId)
```

Deletes a saved search by ID. Only the owner can delete their own searches.

---

### getCategorizedDocuments / getCategorizedFolders / getCategorizedMails / getCategorizedRecords

```
List<Document> getCategorizedDocuments(String token, String categoryId)
List<Folder>   getCategorizedFolders(String token, String categoryId)
List<Mail>     getCategorizedMails(String token, String categoryId)
List<Record>   getCategorizedRecords(String token, String categoryId)
```

Returns all nodes of the respective type assigned to the given category. `categoryId` can be a UUID or path.

```java
for (Document doc : okmSearch.getCategorizedDocuments(null, "5cbc35fc-23c0-48f5-a7bc-3cfa1e7be25f")) {
    System.out.println(doc);
}
```

---

### getDocumentsByKeyword / getFoldersByKeyword / getMailsByKeyword / getRecordsByKeyword

```
List<Document> getDocumentsByKeyword(String token, String keyword)
List<Folder>   getFoldersByKeyword(String token, String keyword)
List<Mail>     getMailsByKeyword(String token, String keyword)
List<Record>   getRecordsByKeyword(String token, String keyword)
```

Returns all nodes of the respective type that have the specified keyword assigned.

```java
for (Document doc : okmSearch.getDocumentsByKeyword(null, "test")) {
    System.out.println(doc);
}
```

---

### getDocumentsByPropertyValue / getFoldersByPropertyValue / getMailsByPropertyValue / getRecordsByPropertyValue

```
List<Document> getDocumentsByPropertyValue(String token, String group, String property, String value)
List<Folder>   getFoldersByPropertyValue(String token, String group, String property, String value)
List<Mail>     getMailsByPropertyValue(String token, String group, String property, String value)
List<Record>   getRecordsByPropertyValue(String token, String group, String property, String value)
```

Returns all nodes of the respective type where the specified metadata property matches the given value.

```java
for (Document doc : okmSearch.getDocumentsByPropertyValue(null, "okg:consulting", "okp:consulting.name", "value")) {
    System.out.println(doc);
}
```

---

### findMailPaginated

```
ResultSet findMailPaginated(String token, Map<String, String> filter, String sortField, boolean sortReverse, int type, int offset, int limit)
```

Returns paginated mail results. Filter keys: `Mail.SENT_DATE` (ISO8601 range), `Mail.SUBJECT`, `Mail.TO`. Sort field: `"okm:"` (none), `Mail.TYPE`, `Mail.SUBJECT`, `Mail.FROM`, `Mail.SENT_DATE`, `Mail.SIZE`, `Mail.REPLY`, `Mail.TO`, `Mail.CC`, `Mail.BCC`, `Mail.CONTENT`. Type: `OKMSearch.TYPE_MAIL_ALL`, `TYPE_MAIL_WITH_ATTACHMENT`, `TYPE_MAIL_WITHOUT_ATTACHMENT`.

```java
Map<String, String> filter = new HashMap<>();
ResultSet rs = okmSearch.findMailPaginated(null, filter, "okm:", false, OKMSearch.TYPE_MAIL_ALL, 0, 10);
for (QueryResult qr : rs.getResults()) {
    System.out.println(qr);
}
```

---

### csvExport

```
InputStream csvExport(String token, String lang, QueryParams params, List<String> propertyGroups, boolean compact, Ref<String> fileName)
```

Exports search results as a CSV `InputStream`. `lang` must be ISO 639-1 (e.g. `"en"`). `propertyGroups` lists metadata group names to include as extra columns. `compact` enables compact output format. `fileName` is an output `Ref<String>` populated with the suggested file name.

```java
QueryParams params = new QueryParams();
params.setDomain(QueryParams.DOCUMENT + QueryParams.FOLDER);
params.setName("test*");
List<String> propertyGroups = Arrays.asList("okg:consulting");
Ref<String> fileName = new Ref<>();
InputStream is = okmSearch.csvExport(null, "en", params, propertyGroups, false, fileName);
System.out.println("File name: " + fileName.get());
```

---

## OKMStamp

Provides document stamping capabilities: apply predefined or custom text, image, and barcode stamps to PDF documents.

**Obtain instance:**
```java
OKMStamp okmStamp = ContextWrapper.getContext().getBean(OKMStamp.class);
```

**`token` parameter:** pass `null` to use the current user session, or `DbSessionManager.getInstance().getSystemToken()` for the system/admin user.

**Expression macros for exprX / exprY:** `IMAGE_WIDTH`, `IMAGE_HEIGHT`, `PAGE_WIDTH`, `PAGE_HEIGHT`, `PAGE_CENTER`, `PAGE_MIDDLE`.

---

### calculateStampCoordinates

```
StampCoordinates calculateStampCoordinates(String token, long imgToStampWidth, long imgToStampHeight, long floatingDivWidth, long floatingDivHeight, String exprX, String exprY, String stampType, String stampAlign)
```

Calculates the pixel coordinates of a stamp given the page/image dimensions and position expressions. `stampType`: `"text"` or `"image"`. `stampAlign`: `"left"`, `"center"`, or `"right"`.

```java
StampCoordinates stampCoordinates = okmStamp.calculateStampCoordinates(null, 100, 100, 250, 300,
        "PAGE_CENTER - IMAGE_WIDTH / 2", "PAGE_MIDDLE - IMAGE_HEIGHT / 2", "text", "center");
System.out.println("X = " + stampCoordinates.getX() + ", Y = " + stampCoordinates.getY());
```

---

### calculateStampExpressions

```
StampExpressions calculateStampExpressions(String token, long imgToStampWidth, long imgToStampHeight, long posX, long posY)
```

Calculates the expression strings for X and Y coordinates given actual pixel positions.

```java
StampExpressions stampExpressions = okmStamp.calculateStampExpressions(null, 100, 100, 10, 50);
System.out.println("X = " + stampExpressions.getExprX() + ", Y = " + stampExpressions.getExprY());
```

---

### stampDocument

```
void stampDocument(String token, long id, int type, String uuid)
```

Applies a predefined stamp to a document. `id` is the stamp configuration ID. `type`: `0` for text stamp, `1` for image stamp. `uuid` is the target document UUID.

```java
okmStamp.stampDocument(null, 1, 1, "babe24df-c443-49a5-9453-39dfc9b27924");
```

---

### stampTextCustom

```
void stampTextCustom(String token, String uuid, long id, String exprX, String exprY, String range, String text)
```

Applies a custom text stamp to a document. `uuid` is the target document UUID. `id` is the stamp configuration ID created by the administrator. `range` restricts which pages to stamp (empty string for all pages).

```java
okmStamp.stampTextCustom(null, "05b14eee-2e57-4d1d-925a-c9bc3f526e24", 1,
        "PAGE_CENTER", "PAGE_MIDDLE", "", "OpenKM");
```

---

### stampImageCustom (with personalStampUuid)

```
void stampImageCustom(String token, String uuid, long id, String exprX, String exprY, String range, String personalStampUuid)
```

Applies a custom image stamp using an image document stored in the repository. `personalStampUuid` must be a valid document UUID pointing to a jpg or png image.

```java
okmStamp.stampImageCustom(null, "babe24df-c443-49a5-9453-39dfc9b27924", 3,
        "PAGE_CENTER - IMAGE_WIDTH / 2", "PAGE_MIDDLE - IMAGE_HEIGHT / 2", "",
        "928de61e-6ceb-4f94-bf20-9ba2405c5cee");
```

---

### stampImageCustom (with byte[])

```
void stampImageCustom(String token, String uuid, long id, String exprX, String exprY, String range, byte[] image)
```

Applies a custom image stamp from raw bytes. `image` must be a jpg or png image.

```java
InputStream is = new FileInputStream("/home/test/image.png");
byte[] image = IOUtils.toByteArray(is);
okmStamp.stampImageCustom(null, "babe24df-c443-49a5-9453-39dfc9b27924", 3,
        "PAGE_CENTER - IMAGE_WIDTH / 2", "PAGE_MIDDLE - IMAGE_HEIGHT / 2", "", image);
```

---

### getAllStamps

```
List<StampItem> getAllStamps(String token)
```

Returns a list of all configured stamps (both text and image types).

```java
List<StampItem> result = okmStamp.getAllStamps(null);
for (StampItem stampItem : result) {
    System.out.println(stampItem.getName());
}
```

---

### getStampTextByPk

```
StampText getStampTextByPk(String token, long itemId, String docId)
```

Returns the text stamp configuration for the given stamp ID and document UUID.

```java
StampText stampText = okmStamp.getStampTextByPk(null, 1, "928de61e-6ceb-4f94-bf20-9ba2405c5cee");
System.out.println(stampText.getName());
```

---

### getStampImageByPk

```
StampImage getStampImageByPk(String token, long itemId, String docId)
```

Returns the image stamp configuration for the given stamp ID and document UUID.

```java
StampImage stampImage = okmStamp.getStampImageByPk(null, 3, "928de61e-6ceb-4f94-bf20-9ba2405c5cee");
System.out.println(stampImage.getName());
```

---

### getStampBarcodeByPk

```
StampBarcode getStampBarcodeByPk(String token, long itemId, String docId)
```

Returns the barcode stamp configuration for the given stamp ID and document UUID.

```java
StampBarcode stampBarcode = okmStamp.getStampBarcodeByPk(null, 3, "928de61e-6ceb-4f94-bf20-9ba2405c5cee");
System.out.println(stampBarcode.getName());
```

---

### calculateFlyImageDimensions

```
StampImageSize calculateFlyImageDimensions(String token, String uuid, long imgToStampWidth, long imgToStampHeight, long floatingImageWidth, long floatingImageHeight, int pageNumber)
```

Calculates the rendered dimensions of a floating stamp image on the given page. `uuid` is the target document UUID. `pageNumber` is 1-based.

```java
StampImageSize stampImageSize = okmStamp.calculateFlyImageDimensions(null,
        "babe24df-c443-49a5-9453-39dfc9b27924", 100, 100, 300, 300, 2);
System.out.println(stampImageSize);
```

---

### getPersonalStamps

```
List<Document> getPersonalStamps(String token)
```

Returns a list of personal stamp images (jpg/png documents) from `/okm:templates/{userId}/stamps`.

```java
List<Document> result = okmStamp.getPersonalStamps(null);
for (Document doc : result) {
    System.out.println(doc);
}
```

---

### getPersonalStampImage

```
StampPersonalImage getPersonalStampImage(String token, String docId, String imgId, long id)
```

Processes a personal stamp image (applies its text layer if any) and returns the result. `docId` must be one of the UUIDs returned by `getPersonalStamps`.

```java
long stampId = 1;
String imgId = ""; // stamp image id
StampPersonalImage stampPersonalImage = okmStamp.getPersonalStampImage(null,
        "928de61e-6ceb-4f94-bf20-9ba2405c5cee", imgId, stampId);
System.out.println(stampPersonalImage);
```

---

## OKMStats

Provides repository statistics grouped by context (tenant).

**Obtain instance:**
```java
OKMStats okmStats = ContextWrapper.getContext().getBean(OKMStats.class);
```

**`token` parameter:** pass `null` to use the current user session, or `DbSessionManager.getInstance().getSystemToken()` for the system/admin user.

All methods return a `StatsInfo` object containing the aggregated counts or sizes for the requested entity type.

---

### getDocumentsByContext

```
StatsInfo getDocumentsByContext(String token)
```

Returns document count statistics grouped by context.

```java
StatsInfo sInfo = okmStats.getDocumentsByContext(null);
System.out.println(sInfo);
```

---

### getDocumentsSizeByContext

```
StatsInfo getDocumentsSizeByContext(String token)
```

Returns total document size statistics grouped by context.

```java
StatsInfo sInfo = okmStats.getDocumentsSizeByContext(null);
System.out.println(sInfo);
```

---

### getFoldersByContext

```
StatsInfo getFoldersByContext(String token)
```

Returns folder count statistics grouped by context.

```java
StatsInfo sInfo = okmStats.getFoldersByContext(null);
System.out.println(sInfo);
```

---

### getMailsByContext

```
StatsInfo getMailsByContext(String token)
```

Returns mail count statistics grouped by context.

```java
StatsInfo sInfo = okmStats.getMailsByContext(null);
System.out.println(sInfo);
```

---

### getMailsSizeByContext

```
StatsInfo getMailsSizeByContext(String token)
```

Returns total mail size statistics grouped by context.

```java
StatsInfo sInfo = okmStats.getMailsSizeByContext(null);
System.out.println(sInfo);
```

---

### getRecordsByContext

```
StatsInfo getRecordsByContext(String token)
```

Returns record count statistics grouped by context.

```java
StatsInfo sInfo = okmStats.getRecordsByContext(null);
System.out.println(sInfo);
```

---

## OKMTask

Manages tasks, task metadata (projects, types, statuses, notes) and task history. Tasks support assignment to users/roles and linking to repository nodes.

**Obtain instance:**
```java
OKMTask okmTask = ContextWrapper.getContext().getBean(OKMTask.class);
```

**`token` parameter:** pass `null` to use the current user session, or `DbSessionManager.getInstance().getSystemToken()` for the system/admin user.

**Task fields:**

| Field | Type | Mandatory | Description |
|---|---|---|---|
| id | Long | No (auto) | Internal task ID, set by the application. |
| owner | String | No (auto) | OpenKM userId, set by the application. |
| subject | String | Yes | Topic of the task. |
| description | String | No | Description. |
| start | Calendar | Yes | When the task should start. |
| end | Calendar | No | When the task should end. |
| status | TaskStatus | Yes | Task status. Administer via `createStatus`/`getStatuses`. |
| project | TaskProject | Yes | Related project. Administer via `createProject`/`getProjects`. |
| type | TaskType | Yes | Task type. Administer via `createType`/`getTypes`. |
| progress | Integer | Yes | Completion percentage (0–100). |
| repeatGroup | Long | No | Group ID for repeated tasks. |
| reminderStartValue | Integer | No | Reminder X units before start. |
| reminderEndValue | Integer | No | Reminder X units before end. |
| reminderStartUnit | String | Conditional | Unit for reminderStartValue: `"m"`, `"h"`, `"d"`. |
| reminderEndUnit | String | Conditional | Unit for reminderEndValue: `"m"`, `"h"`, `"d"`. |
| users | Set\<String\> | No* | Users assigned to the task. |
| roles | Set\<String\> | No* | Roles assigned to the task. |
| documents | Set\<String\> | No | UUIDs of related documents. |
| folders | Set\<String\> | No | UUIDs of related folders. |
| mails | Set\<String\> | No | UUIDs of related mails. |
| records | Set\<String\> | No | UUIDs of related records. |

*At least one user or role must be assigned.

**Filter parameters for `getAssigned/getActive/getFinished/getNotified`:** Pass `0` for `projectId`, `typeId`, or `statusId` to skip that filter. `orderColumn` is a `TaskManagerTask` field name: `"subject"`, `"start"`, `"end"`, `"progress"`, `"owner"`.

---

### create

```
Task create(String token, Task task)
```

Creates a new task. Returns the created task with its assigned ID.

```java
OKMTask okmTask = ContextWrapper.getContext().getBean(OKMTask.class);
Task task = new Task();
task.setSubject("task subject");
task.setDescription("description");
Calendar start = Calendar.getInstance();
start.add(Calendar.DATE, 15);
task.setStart(start);
TaskStatus status = okmTask.findStatus(null, 1L);
TaskProject project = okmTask.findProject(null, 1L);
TaskType type = okmTask.findType(null, 1L);
task.setStatus(status);
task.setProject(project);
task.setType(type);
task.setProgress(0);
okmTask.create(null, task);
```

---

### update

```
Task update(String token, Task task)
```

Updates an existing task.

```java
Task task = okmTask.find(null, 1L);
task.setSubject("subject modified");
okmTask.update(null, task);
```

---

### find

```
Task find(String token, long taskId)
```

Returns a task by its ID.

```java
Task task = okmTask.find(null, 1L);
System.out.println(task);
```

---

### delete

```
void delete(String token, long taskId)
```

Deletes a task by its ID.

```java
okmTask.delete(null, 1L);
```

---

### getByProject

```
List<Task> getByProject(String token, long projectId)
```

Returns all tasks for the given project.

```java
for (Task task : okmTask.getByProject(null, 1L)) {
    System.out.println(task);
}
```

---

### getByType

```
List<Task> getByType(String token, long typeId)
```

Returns all tasks for the given type.

```java
for (Task task : okmTask.getByType(null, 1L)) {
    System.out.println(task);
}
```

---

### getAssigned

```
List<Task> getAssigned(String token, long projectId, long typeId, long statusId, String orderColumn)
List<Task> getAssigned(String token, long projectId, long typeId, long statusId, String orderColumn, boolean orderAsc, int offset, int limit)
TaskList   getAssigned(String token, String subject, int progress, long projectId, long typeId, long statusId, Calendar lastModified, Calendar start, Calendar end, String orderColumn, boolean orderAsc, int offset, int limit)
TaskList   getAssigned(String token, String subject, int progress, long projectId, long typeId, long statusId, Calendar lastModified, Calendar start, Calendar end, Calendar from, Calendar to, String orderColumn, boolean orderAsc, int offset, int limit)
```

Returns tasks assigned to the current user. Use the `TaskList` variants for full filtering with date ranges. `TaskList.getTasks()` returns the results; `TaskList.getTotal()` returns the total count.

```java
// Simple paginated
for (Task task : okmTask.getAssigned(null, 1L, 1L, 1L, "subject", true, 0, 10)) {
    System.out.println(task);
}

// Full filter
Calendar lastModified = Calendar.getInstance();
Calendar start = Calendar.getInstance();
start.add(Calendar.DATE, -30);
Calendar end = Calendar.getInstance();
TaskList tl = okmTask.getAssigned(null, "test", 10, 1L, 1L, 1L, lastModified, start, end, "subject", true, 0, 10);
for (Task task : tl.getTasks()) { System.out.println(task); }
```

---

### countAssigned

```
long countAssigned(String token, long projectId, long typeId, long statusId)
long countAssigned(String token, String subject, int progress, long projectId, long typeId, long statusId, Calendar lastModified, Calendar start, Calendar end)
```

Returns the count of tasks assigned to the current user.

```java
long total = okmTask.countAssigned(null, 1L, 1L, 1L);
System.out.println(total);
```

---

### getAssignedCount

```
long getAssignedCount(String token, long projectId, long typeId, long statusId)
```

Returns the count of tasks assigned to the current user (alias for `countAssigned` 4-param).

---

### getActive

```
List<Task> getActive(String token, long projectId, long typeId, long statusId, String orderColumn)
List<Task> getActive(String token, long projectId, long typeId, long statusId, String orderColumn, boolean orderAsc, int offset, int limit)
TaskList   getActive(String token, String subject, int progress, long projectId, long typeId, long statusId, Calendar lastModified, Calendar start, Calendar end, String orderColumn, boolean orderAsc, int offset, int limit)
TaskList   getActive(String token, String subject, int progress, long projectId, long typeId, long statusId, Calendar lastModified, Calendar start, Calendar end, Calendar from, Calendar to, String orderColumn, boolean orderAsc, int offset, int limit)
```

Returns active tasks assigned to the current user.

```java
for (Task task : okmTask.getActive(null, 1L, 1L, 1L, "start")) {
    System.out.println(task);
}
```

---

### countActive

```
long countActive(String token, long projectId, long typeId, long statusId)
long countActive(String token, String subject, int progress, long projectId, long typeId, long statusId, Calendar lastModified, Calendar start, Calendar end)
```

Returns the count of active tasks for the current user.

```java
long total = okmTask.countActive(null, 1L, 1L, 1L);
System.out.println(total);
```

---

### getActiveCount

```
long getActiveCount(String token, long projectId, long typeId, long statusId)
```

Returns the count of active tasks for the current user (alias for `countActive` 4-param).

---

### getFinished

```
List<Task> getFinished(String token, long projectId, long typeId, long statusId, String orderColumn)
List<Task> getFinished(String token, long projectId, long typeId, long statusId, String orderColumn, boolean orderAsc, int offset, int limit)
TaskList   getFinished(String token, String subject, int progress, long projectId, long typeId, long statusId, Calendar lastModified, Calendar start, Calendar end, String orderColumn, boolean orderAsc, int offset, int limit)
TaskList   getFinished(String token, String subject, int progress, long projectId, long typeId, long statusId, Calendar lastModified, Calendar start, Calendar end, Calendar from, Calendar to, String orderColumn, boolean orderAsc, int offset, int limit)
```

Returns finished tasks assigned to the current user.

```java
for (Task task : okmTask.getFinished(null, 1L, 1L, 1L, "end")) {
    System.out.println(task);
}
```

---

### countFinished

```
long countFinished(String token, long projectId, long typeId, long statusId)
long countFinished(String token, String subject, int progress, long projectId, long typeId, long statusId, Calendar lastModified, Calendar start, Calendar end)
```

Returns the count of finished tasks for the current user.

```java
long total = okmTask.countFinished(null, 1L, 1L, 1L);
System.out.println(total);
```

---

### getFinishedCount

```
long getFinishedCount(String token, long projectId, long typeId, long statusId)
```

Returns the count of finished tasks for the current user (alias for `countFinished` 4-param).

---

### getNotified

```
List<Task> getNotified(String token, long projectId, long typeId, long statusId, String orderColumn)
List<Task> getNotified(String token, long projectId, long typeId, long statusId, String orderColumn, boolean orderAsc, int offset, int limit)
TaskList   getNotified(String token, String subject, int progress, long projectId, long typeId, long statusId, Calendar lastModified, Calendar start, Calendar end, String orderColumn, boolean orderAsc, int offset, int limit)
TaskList   getNotified(String token, String subject, int progress, long projectId, long typeId, long statusId, Calendar lastModified, Calendar start, Calendar end, Calendar from, Calendar to, String orderColumn, boolean orderAsc, int offset, int limit)
```

Returns tasks the current user is notified about (but not necessarily assigned to).

```java
for (Task task : okmTask.getNotified(null, 1L, 1L, 1L, "subject", true, 0, 10)) {
    System.out.println(task);
}
```

---

### countNotified

```
long countNotified(String token, long projectId, long typeId, long statusId)
long countNotified(String token, String subject, int progress, long projectId, long typeId, long statusId, Calendar lastModified, Calendar start, Calendar end)
```

Returns the count of tasks the current user is notified about.

---

### getNotifiedCount

```
long getNotifiedCount(String token, long projectId, long typeId, long statusId)
```

Returns the count of notified tasks for the current user (alias for `countNotified` 4-param).

---

### findStatus

```
TaskStatus findStatus(String token, long statusId)
```

Returns a `TaskStatus` by ID.

```java
TaskStatus ts = okmTask.findStatus(null, 1L);
System.out.println(ts);
```

---

### findProject

```
TaskProject findProject(String token, long projectId)
```

Returns a `TaskProject` by ID.

---

### findType

```
TaskType findType(String token, long typeId)
```

Returns a `TaskType` by ID.

---

### findNote

```
TaskNote findNote(String token, long noteId)
```

Returns a `TaskNote` by ID.

---

### getStatuses

```
List<TaskStatus> getStatuses(String token)
```

Returns all configured task statuses.

---

### getProjects

```
List<TaskProject> getProjects(String token, boolean filterByActive)
```

Returns all configured task projects. Pass `true` to return only active projects.

---

### getTypes

```
List<TaskType> getTypes(String token, boolean filterByActive)
```

Returns all configured task types. Pass `true` to return only active types.

---

### getNotes

```
List<TaskNote> getNotes(String token, long taskId)
```

Returns all notes for a task.

```java
for (TaskNote tn : okmTask.getNotes(null, 1L)) {
    System.out.println(tn);
}
```

---

### createStatus

```
TaskStatus createStatus(String token, String name, boolean finish)
```

Creates a new task status. `finish` marks it as a terminal status (e.g. "closed", "cancelled").

```java
TaskStatus ts = okmTask.createStatus(null, "cancelled", true);
```

---

### createProject

```
TaskProject createProject(String token, String name, String description, boolean active)
```

Creates a new task project.

```java
TaskProject tp = okmTask.createProject(null, "Project one", "Description", true);
```

---

### createType

```
TaskType createType(String token, String name, String description, boolean active)
```

Creates a new task type.

```java
TaskType tt = okmTask.createType(null, "Type one", "Description", true);
```

---

### createNote

```
TaskNote createNote(String token, long taskId, String text)
```

Adds a note to a task.

```java
TaskNote tn = okmTask.createNote(null, 1L, "New note");
```

---

### updateStatus

```
TaskStatus updateStatus(String token, long id, String name, boolean finish)
```

Updates a task status.

---

### updateProject

```
TaskProject updateProject(String token, long id, String name, String description, boolean active)
```

Updates a task project.

---

### updateType

```
TaskType updateType(String token, long id, String name, String description, boolean active)
```

Updates a task type.

---

### updateNote

```
TaskNote updateNote(String token, long id, String text)
```

Updates the text of a task note.

---

### deleteStatus

```
void deleteStatus(String token, long statusId)
```

Deletes a task status by ID.

---

### deleteProject

```
void deleteProject(String token, long projectId)
```

Deletes a task project by ID.

---

### deleteType

```
void deleteType(String token, long typeId)
```

Deletes a task type by ID.

---

### deleteNote

```
void deleteNote(String token, long noteId)
```

Deletes a task note by ID.

---

### getByNode

```
List<Task> getByNode(String token, String nodeUuid)
```

Returns all tasks linked to the given repository node UUID.

```java
for (Task task : okmTask.getByNode(null, "d168924d-e801-426d-a222-00124a1461bd")) {
    System.out.println(task);
}
```

---

### getHistory

```
List<TaskHistory> getHistory(String token, long taskId)
```

Returns the change history for a task.

```java
for (TaskHistory th : okmTask.getHistory(null, 1L)) {
    System.out.println(th);
}
```

---

## OKMUserConfig

Manages per-user configuration settings such as the home folder.

**Obtain instance:**
```java
OKMUserConfig okmUserConfig = ContextWrapper.getContext().getBean(OKMUserConfig.class);
```

**`token` parameter:** pass `null` to use the current user session, or `DbSessionManager.getInstance().getSystemToken()` for the system/admin user.

---

### getConfig

```
UserConfig getConfig(String token)
```

Returns the current user's configuration. The `UserConfig` object contains: userId, home path, home type (`folder`, `document`, `mail`, or `record`), and home node UUID.

```java
UserConfig uc = okmUserConfig.getConfig(null);
System.out.println(uc);
```

---

### setHome

```
void setHome(String token, String uuid)
```

Sets the user's home node by UUID. Default home is `/okm:root`.

```java
okmUserConfig.setHome(null, "d168924d-e801-426d-a222-00124a1461bd");
```

---

### setConfig

```
void setConfig(String token, UserConfig cfg)
```

Updates the user's full configuration object.

```java
UserConfig uc = okmUserConfig.getConfig(null);
// Modify config fields as needed
okmUserConfig.setConfig(null, uc);
```

---

## OKMWorkflow

Manage workflow process definitions, process instances, and task instances.

**Bean:** `ContextWrapper.getContext().getBean(OKMWorkflow.class)`

**token:** `null` = current user session; `DbSessionManager.getInstance().getSystemToken()` = administrator.

### registerProcessDefinition

```
registerProcessDefinition(String token, InputStream is) → void
```

Registers a new workflow process definition from a `.par` file input stream.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
InputStream is = new FileInputStream("/opt/files/Purchase.par");
okmWorkflow.registerProcessDefinition(null, is);
IOUtils.closeQuietly(is);
```

### deleteProcessDefinition

```
deleteProcessDefinition(String token, long processDefinitionId) → void
```

Deletes a workflow process definition by ID.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
long pdId = 5;
okmWorkflow.deleteProcessDefinition(null, pdId);
```

### getProcessDefinition

```
getProcessDefinition(String token, long processDefinitionId) → ProcessDefinition
```

Returns a workflow process definition by ID.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
long pdId = 5;
ProcessDefinition pd = okmWorkflow.getProcessDefinition(null, pdId);
System.out.println(pd);
```

### getProcessDefinitionImage

```
getProcessDefinitionImage(String token, long processDefinitionId, String node) → byte[]
```

Returns an image of a workflow process definition. `node` is the path of a node that has a workflow in execution.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
long pdId = 5;
byte[] img = okmWorkflow.getProcessDefinitionImage(null, pdId, "/okm:root/sample.pdf");
```

### getProcessDefinitionForms

```
getProcessDefinitionForms(String token, long processDefinitionId) → Map<String, List<FormElement>>
```

Returns a map of all workflow form definitions keyed by task name.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
long pdId = 5;
Map<String, List<FormElement>> map = okmWorkflow.getProcessDefinitionForms(null, pdId);
for (String key : map.keySet()) {
    for (FormElement fe : map.get(key)) {
        System.out.println(fe);
    }
}
```

### runProcessDefinition (with node)

```
runProcessDefinition(String token, long processDefinitionId, String uuid, List<FormElement> variables) → ProcessInstance
```

Starts a workflow process and associates it with a document, folder, mail, or record UUID.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
long pdId = 8041;
List<FormElement> feList = new ArrayList<>();
Input price = new Input();
price.setName("price");
price.setValue("1000");
feList.add(price);
okmWorkflow.runProcessDefinition(null, pdId, "f86cc22d-9b50-434f-a940-b04cea9c0048", feList);
```

### runProcessDefinition (without node association)

```
runProcessDefinition(String token, long processDefinitionId, List<FormElement> variables) → ProcessInstance
```

Starts a standalone workflow process not associated with any node.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
long pdId = 8041;
List<FormElement> feList = new ArrayList<>();
ProcessInstance pi = okmWorkflow.runProcessDefinition(null, pdId, feList);
System.out.println("Process instance: " + pi);
```

### sendProcessInstanceSignal

```
sendProcessInstanceSignal(String token, long processInstanceId, String transitionName) → ProcessInstance
```

Sends a transition signal to a process instance.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
long pId = 1046;
okmWorkflow.sendProcessInstanceSignal(null, pId, "jump2");
```

### endProcessInstance

```
endProcessInstance(String token, long processInstanceId) → void
```

Ends a process instance.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
long pId = 1046;
okmWorkflow.endProcessInstance(null, pId);
```

### deleteProcessInstance

```
deleteProcessInstance(String token, long processInstanceId) → void
```

Deletes a process instance.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
long pId = 1046;
okmWorkflow.deleteProcessInstance(null, pId);
```

### findProcessInstances

```
findProcessInstances(String token, long processDefinitionId) → List<ProcessInstance>
```

Retrieves all process instances for a given process definition.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
for (ProcessDefinition pd : okmWorkflow.findAllProcessDefinitions(null)) {
    for (ProcessInstance pi : okmWorkflow.findProcessInstances(null, pd.getId())) {
        System.out.println(pi);
    }
}
```

### searchAssignedTasks

```
searchAssignedTasks(String token, LocalDate start, LocalDate end, String status, Long procDefId, String taskName, Integer offset, Integer limit) → ProcessInstanceResultSet
```

Searches for workflow task instances assigned to the current user. All filter parameters may be null.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
ProcessInstanceResultSet result = okmWorkflow.searchAssignedTasks(null, null, null, null, null, null, 0, 10);
System.out.println("Total: " + result.getTotal());
```

### searchPooledTasks

```
searchPooledTasks(String token, LocalDate start, LocalDate end, String status, Long procDefId, String taskName, Integer offset, Integer limit) → ProcessInstanceResultSet
```

Searches for pooled workflow task instances available for the current user. All filter parameters may be null.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
ProcessInstanceResultSet result = okmWorkflow.searchPooledTasks(null, null, null, null, null, null, 0, 10);
System.out.println("Total: " + result.getTotal());
```

### searchStartedByMe

```
searchStartedByMe(String token, LocalDate start, LocalDate end, String status, Long procDefId, String taskName, Integer offset, Integer limit) → ProcessInstanceResultSet
```

Searches for workflow process instances started by the current user. All filter parameters may be null.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
ProcessInstanceResultSet result = okmWorkflow.searchStartedByMe(null, null, null, null, null, null, 0, 10);
System.out.println("Total: " + result.getTotal());
```

### searchOverview

```
searchOverview(String token, LocalDate start, LocalDate end, String status, Long procDefId, String taskName, String initiator, String taskUser, Integer offset, Integer limit) → ProcessInstanceResultSet
```

Administrative overview search across all workflow process instances. All filter parameters may be null.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
ProcessInstanceResultSet result = okmWorkflow.searchOverview(null, null, null, null, null, null, null, null, 0, 10);
System.out.println("Total: " + result.getTotal());
```

### findAllProcessDefinitions

```
findAllProcessDefinitions(String token) → List<ProcessDefinition>
```

Retrieves all registered workflow process definitions (all versions).

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
for (ProcessDefinition pd : okmWorkflow.findAllProcessDefinitions(null)) {
    System.out.println(pd);
}
```

### findLatestProcessDefinitions

```
findLatestProcessDefinitions(String token) → List<ProcessDefinition>
```

Retrieves the latest version of each registered workflow process definition.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
for (ProcessDefinition pd : okmWorkflow.findLatestProcessDefinitions(null)) {
    System.out.println(pd);
}
```

### findLastProcessDefinition

```
findLastProcessDefinition(String token, String name) → ProcessDefinition
```

Retrieves the most recent version of a specific workflow process definition by name.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
ProcessDefinition pd = okmWorkflow.findLastProcessDefinition(null, "purchase");
System.out.println(pd);
```

### getProcessInstance

```
getProcessInstance(String token, long processInstanceId) → ProcessInstance
```

Returns a process instance by ID.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
long piId = 8108;
ProcessInstance pi = okmWorkflow.getProcessInstance(null, piId);
System.out.println(pi);
```

### suspendProcessInstance

```
suspendProcessInstance(String token, long processInstanceId) → void
```

Suspends a running process instance.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
long piId = 8108;
okmWorkflow.suspendProcessInstance(null, piId);
```

### resumeProcessInstance

```
resumeProcessInstance(String token, long processInstanceId) → void
```

Resumes a suspended process instance.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
long piId = 8108;
okmWorkflow.resumeProcessInstance(null, piId);
```

### findUserTaskInstances

```
findUserTaskInstances(String token, int offset, int limit) → TaskInstanceResultSet
```

Retrieves task instances assigned to the current user with pagination.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
TaskInstanceResultSet resultSet = okmWorkflow.findUserTaskInstances(null, 0, 10);
System.out.println("Total: " + resultSet.getTotal());
for (TaskInstance ti : resultSet.getResults()) {
    System.out.println(ti);
}
```

### findPooledTaskInstances

```
findPooledTaskInstances(String token, int offset, int limit) → TaskInstanceResultSet
```

Retrieves pooled task instances available for the current user with pagination.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
TaskInstanceResultSet resultSet = okmWorkflow.findPooledTaskInstances(null, 0, 10);
System.out.println("Total: " + resultSet.getTotal());
for (TaskInstance ti : resultSet.getResults()) {
    System.out.println(ti);
}
```

### findTaskInstances

```
findTaskInstances(String token, long processInstanceId) → List<TaskInstance>
```

Retrieves all task instances for a given process instance.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
long piId = 8108;
for (TaskInstance ti : okmWorkflow.findTaskInstances(null, piId)) {
    System.out.println(ti);
}
```

### setTaskInstanceValues

```
setTaskInstanceValues(String token, long taskInstanceId, String transitionName, List<FormElement> values) → void
```

Sets form values on a task instance and advances it through the given transition.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
long tiId = 8110;
List<FormElement> feList = new ArrayList<>();
okmWorkflow.setTaskInstanceValues(null, tiId, "approve", feList);
```

### getTaskInstance

```
getTaskInstance(String token, long taskInstanceId) → TaskInstance
```

Returns a task instance by ID.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
long tiId = 8110;
TaskInstance ti = okmWorkflow.getTaskInstance(null, tiId);
System.out.println(ti);
```

### setTaskInstanceActorId

```
setTaskInstanceActorId(String token, long taskInstanceId, String actorId) → void
```

Assigns a specific user as the actor for a task instance.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
long tiId = 8110;
okmWorkflow.setTaskInstanceActorId(null, tiId, "okmAdmin");
```

### unsetTaskInstanceActor

```
unsetTaskInstanceActor(String token, long taskInstanceId) → void
```

Removes the actor assignment from a task instance, returning it to the pool.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
long tiId = 8110;
okmWorkflow.unsetTaskInstanceActor(null, tiId);
```

### startTaskInstance

```
startTaskInstance(String token, long taskInstanceId) → void
```

Marks a task instance as started.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
long tiId = 8110;
okmWorkflow.startTaskInstance(null, tiId);
```

### endTaskInstance

```
endTaskInstance(String token, long taskInstanceId, String transitionName) → void
```

Ends a task instance and follows the specified transition.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
long tiId = 8110;
okmWorkflow.endTaskInstance(null, tiId, "end");
```

### getSuggestBoxKeyValuesFiltered

```
getSuggestBoxKeyValuesFiltered(String token, String nodeId, long processDefinitionId, String taskName, String propertyName, String filter) → List<KeyValue>
```

Returns filtered key-value pairs for a suggest box field in a workflow form.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
List<KeyValue> values = okmWorkflow.getSuggestBoxKeyValuesFiltered(null, null, 5L, "review", "assignee", "adm");
for (KeyValue kv : values) {
    System.out.println(kv.getKey() + " = " + kv.getValue());
}
```

### getSuggestBoxKeyValue

```
getSuggestBoxKeyValue(String token, String nodeId, long processDefinitionId, String taskName, String propertyName, String key) → KeyValue
```

Returns the key-value pair for a specific key in a workflow suggest box form field.

```java
OKMWorkflow okmWorkflow = ContextWrapper.getContext().getBean(OKMWorkflow.class);
KeyValue kv = okmWorkflow.getSuggestBoxKeyValue(null, null, 5L, "review", "assignee", "okmAdmin");
System.out.println(kv.getKey() + " = " + kv.getValue());
```

---