OKMMail

Basics

In almost all methods you'll see a parameter named "mailId". The value of this parameter can be a valid mail UUID.

Example of mailId:

  • Using UUID -> "0747c0cb-5e4a-4088-92a9-ab97b401af75";

About the parameter named "fldId",  the value of this parameter can be a valid folder UUID or a record node.

Example of fldId:

  • Using UUID -> "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474";

Also in all methods you'll see a parameter named "token". Because cron tasks are executed in the background without authentication, the methods used in this scenario might use the token parameter. From the default application execution context you must use the value "null", which indicates the application must use the "user session".

In special cases you might be "promoted to Administrator" using the "administrator token".

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

Methods

getProperties

Description:

MethodReturn valuesDescription

getProperties(String token, String mailId)

Mail

Returns the mail properties.

Example:

package com.openkm;

import com.openkm.api.OKMMail;
import com.openkm.bean.Mail;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            Mail mail = okmMail.getProperties(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75");
            System.out.println(mail);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

createAttachment

Description:

MethodReturn valuesDescription

createAttachment(String token, String mailId, String docName, InputStream is)

Document

Add an attachment to the mail.

Example:

package com.openkm;

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

import org.apache.poi.util.IOUtils;

import com.openkm.api.OKMMail;
import com.openkm.bean.Document;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        InputStream is = null;
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            is = new FileInputStream("/home/openkm/sample.pdf");
            Document doc = okmMail.createAttachment(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", "sample.pdf", is);
            System.out.println(doc);
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            IOUtils.closeQuietly(is);
        }
    }
}

deleteAttachment

Description:

MethodReturn valuesDescription

deleteAttachment(String token, String mailId, String docId)

void

Delete an attachment from the mail.

Example:

package com.openkm;

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

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            okmMail.deleteAttachment(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", "c98d704f-c9f2-4f75-9923-878300b36b52");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getAttachments

Description:

MethodReturn valuesDescription

getAttachments(String token, String mailId)

List<Document>

Returns a list of all attachments for a mail.

Example:

package com.openkm;

import com.openkm.api.OKMMail;
import com.openkm.bean.Document;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            for (Document doc : okmMail.getAttachments(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75")) {
                System.out.println(doc);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

delete

Description:

MethodReturn valuesDescription

delete(String token, String mailId)

void

Delete a mail.

Example:

package com.openkm;

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

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            okmMail.delete(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

purge

Description:

MethodReturn valuesDescription

purge(String token, String mailId)

void

The mail is permanently removed from the repository.

Usually you will purge mails into /okm:trash/userId - the personal trash user location - but it is possible to directly purge any mail from the repository.

When a mail is purged, it can only be restored from a previous repository backup. The purge action removes the mail permanently from the repository.

Example:

package com.openkm;

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

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            okmMail.purge(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

rename

Description:

MethodReturn valuesDescription

rename(String token, String mailId, String newName)

Mail

Rename a mail.

Example:

package com.openkm;

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

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            okmMail.rename(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", "newname");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

move

Description:

MethodReturn valuesDescription

move(String token, String mailId, String dstId)

void

Moves the mail into a folder or record.

The values of the dstId parameter should be a folder or record UUID.

Example:

package com.openkm;

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

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            okmMail.move(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", "3636f3bb-779c-4851-b145-0d53e0702b0f");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

copy

Description:

MethodReturn valuesDescription

copy(String token, String mailId, String dstId)

void

Copies a mail into a folder or record.

The values of the dstId parameter should be a folder or record UUID.

Only the security grants are copied to the destination; the metadata, keywords, etc. of the mail are not copied.

See "extendedCopy" method for this feature.

Example:

package com.openkm;

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

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            okmMail.copy(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", "3636f3bb-779c-4851-b145-0d53e0702b0f");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

copy

Description:

MethodReturn valuesDescription

copy(String token, String mailId, String dstId, String newName)

void

Copies a mail into a folder or record.

The values of the dstId parameter should be a folder or record UUID.

When the newName parameter value is null, the mail will preserve the same name.

Only the security grants are copied to destination, the metadata, keywords, etc. of the mail are not copied.

See "extendedCopy" method for this feature.

Example:

package com.openkm;

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

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            okmMail.copy(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", "3636f3bb-779c-4851-b145-0d53e0702b0f", "newname");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

extendedCopy

Description:

MethodReturn valuesDescription

extendedCopy(String token, String mailId, String dstId, ExtendedAttributes extAttr)

void

Copies a mail with the associated data into some folder or record.

The values of the dstId parameter should be a folder or record UUID.

By default only the binary data and the security grants are copied; the metadata, keywords, etc. of the mail are not copied.

Additional extended attributes parameters:

  • When the category parameter is true, the original values of the categories will be copied.
  • When the keywords parameter is true, the original values of the keywords will be copied.
  • When the propertyGroups parameter is true, the original values of the metadata groups will be copied.
  • When the notes parameter is true, the original values of the notes will be copied.
  • When the wiki parameter is true, the original values of the wiki will be copied.

Example:

package com.openkm;

import com.openkm.api.OKMMail;
import com.openkm.bean.ExtendedAttributes;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            ExtendedAttributes extAttr = new ExtendedAttributes();
            extAttr.setNotes(true);
            extAttr.setKeywords(true);
            extAttr.setCategories(true);
            extAttr.setPropertyGroups(true);
            okmMail.extendedCopy(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", "3636f3bb-779c-4851-b145-0d53e0702b0f", extAttr);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

extendedCopy

Description:

MethodReturn valuesDescription

extendedCopy(String token, String mailId, String dstId, ExtendedAttributes extAttr, String newName)

void

Copies a mail with the associated data into some folder or record.

The values of the dstId parameter should be a folder or record UUID.

When the newName parameter value is null, the mail will preserve the same name.

By default only the binary data and the security grants are copied; the metadata, keywords, etc. of the mail are not copied.

Additional extended attributes parameters:

  • When the category parameter is true, the original values of the categories will be copied.
  • When the keywords parameter is true, the original values of the keywords will be copied.
  • When the propertyGroups parameter is true, the original values of the metadata groups will be copied.
  • When the notes parameter is true, the original values of the notes will be copied.
  • When the wiki parameter is true, the original values of the wiki will be copied.

Example:

package com.openkm;

import com.openkm.api.OKMMail;
import com.openkm.bean.ExtendedAttributes;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            ExtendedAttributes extAttr = new ExtendedAttributes();
            extAttr.setNotes(true);
            extAttr.setKeywords(true);
            extAttr.setCategories(true);
            extAttr.setPropertyGroups(true);
            okmMail.extendedCopy(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", "3636f3bb-779c-4851-b145-0d53e0702b0f", extAttr, "new_name");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getChildren

Description:

MethodReturn valuesDescription

getChildren(String token, String fldId)

List<Mail>

Returns a list of all mails whose parent is fldId.

The parameter fldId can be a folder or a record node.

Example:

package com.openkm;

import com.openkm.api.OKMMail;
import com.openkm.bean.Mail;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            for (Mail mail : okmMail.getChildren(null, "3636f3bb-779c-4851-b145-0d53e0702b0f")) {
                System.out.println(mail);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

isValid

Description:

MethodReturn valuesDescription

isValid(String token, String mailId)

boolean

Returns a boolean that indicates if the node is a mail or not.

Example:

package com.openkm;

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

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            boolean valid = okmMail.isValid(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75");
            System.out.println(valid);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getPath

Description:

MethodReturn valuesDescription

getPath(String token, String uuid)

String

Converts a folder UUID to a mail path.

Example:

package com.openkm;

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

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            String path = okmMail.getPath(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75");
            System.out.println(path);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

sendMail

Description:

MethodReturn valuesDescription

sendMail(String token, List<String> recipients, String subject, String body)

void

Sends a mail.

Example:

package com.openkm;

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

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

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            StringBuffer body = new StringBuffer();
            body.append("Test message body.");
            List<String> recipients = new ArrayList<>();
            recipients.add("gnu.java.sergio@gmail.com");
            okmMail.sendMail(null, recipients, "Testing sending mail from OpenKM", body.toString());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

setTitle

Description:

MethodReturn valuesDescription

setTitle(String token, String mailId, String title)

void

Sets the mail title.

Example:

package com.openkm;

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

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            okmMail.setTitle(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", "new title");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

sendMailWithAttachments

Description:

MethodReturn valuesDescription

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

Sends a mail message with attachment.

The value of the dstId parameter should be a folder or record UUID. The dstId parameter indicates where the mail will be stored in the repository after it is sent.

Other parameters:

  • toRecipients is a list of destination mail accounts.
  • subject is the mail subject.
  • ccRecipients and bccRecipients are lists of destination mail accounts (optional)
  • replyToMails is a list of mail accounts for replying (optional)
  • docsId is a list of valid document UUIDs already in OpenKM that will be sent as attachments in the mail (optional).

Example:

package com.openkm;

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

import com.openkm.api.OKMMail;
import com.openkm.bean.Mail;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            List<String> toRecipients = Arrays.asList("gnujavasergio@mail.com");
            List<String> ccRecipients = new ArrayList<>();
            List<String> bccRecipients = new ArrayList<>();
            List<String> replyToMails = new ArrayList<>();
            List<String> docsId = Arrays.asList("b153c4b7-3d1c-4589-bd42-0ed0f34fd338", "d168924d-e801-426d-a222-00124a1461bd");

            Mail mail = okmMail.sendMailWithAttachments(null, toRecipients, ccRecipients, bccRecipients, replyToMails,
                    "some subject", "some body", docsId, "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474");
            System.out.println(mail);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

importEml

Description:

MethodReturn valuesDescription

importEml(String fldId, String title, InputStream is)

Mail

Imports a mail in EML format.

The value of the fldId parameter should be a folder or record UUID. The fldId parameter indicates where the mail will be stored in the repository after it is imported.

Example:

package com.openkm;

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

import org.apache.commons.io.IOUtils;

import com.openkm.api.OKMMail;
import com.openkm.bean.Mail;
import com.openkm.util.ContextWrapper;

public class Test {

	public static void main(String[] args) {		
		InputStream is = null;
        try {       
        	OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            is = new FileInputStream("/home/openkm/sample1.eml");
            Mail mail = okmMail.importEml(null, "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474", "some title", is);
            System.out.println(mail);
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            IOUtils.closeQuietly(is);
        }
	}
}

importMsg

Description:

MethodReturn valuesDescription

importMsg(String fldId, String title, InputStream is)

Mail

Imports a mail in MSG format.

The value of the fldId parameter should be a folder or record UUID. The fldId parameter indicates where the mail will be stored in the repository after it is imported.

Example:

package com.openkm;

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

import org.apache.commons.io.IOUtils;

import com.openkm.api.OKMMail;
import com.openkm.bean.Mail;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        InputStream is = null;
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            is = new FileInputStream("/home/openkm/test subject.msg");
            Mail mail = okmMail.importMsg(null, "b67fe3ae-bcca-4947-b8ea-0cc7aedd4474", "some title", is);
            System.out.println(mail);
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            IOUtils.closeQuietly(is);
        }
    }
}

setNodeClass

Description:

MethodReturn valuesDescription

setNodeClass(String token, String uuid, long ncId)

void

Set the NodeClass.

Example:

package com.openkm;

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

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            long ncId = 2;
            okmMail.setNodeClass(null, "7ce1b4a8-4ade-4dce-8d7d-4e99a6cd368b", ncId);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

setDispositionStage

Description:

MethodReturn valuesDescription

setDispositionStage(String token, String uuid, long stage)

void

Set the disposition stage

Example:

package com.openkm;

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

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            long stage = 1;
            okmMail.setDispositionStage(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", stage);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

setDescription

Description:

MethodReturn valuesDescription

setDescription(String token, String uuid, String description)

void

Set the description.

Example:

package com.openkm;

import com.openkm.api.OKMMail;
import com.openkm.bean.Mail;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            okmMail.setDescription(null, "0747c0cb-5e4a-4088-92a9-ab97b401af75", "some description");
            Mail mail = okmMail.getProperties(null, "b0747c0cb-5e4a-4088-92a9-ab97b401af75");
            System.out.println(mail);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getContent

Description:

MethodReturn valuesDescription

getContent(String token, String mailId)

InputStream

Retrieves the mail content (binary data).

Example:

package com.openkm;

import java.io.FileOutputStream;
import java.io.InputStream;
import java.io.OutputStream;

import org.apache.commons.io.IOUtils;

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

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            OutputStream fos = new FileOutputStream("/home/openkm/test.eml");
            InputStream is = okmMail.getContent(null, "b405a504-d8cb-4166-ac51-22f68acee8c5");
            IOUtils.copy(is, fos);
            IOUtils.closeQuietly(is);
            IOUtils.closeQuietly(fos);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

createWizard

Description:

MethodReturn valuesDescription

createWizard(String token, String path, String title, InputStream is, String type)

WizardNode

Create a new email with a wizard.

The parameters path should be any valid folder or record PATH.

Available types:

  • Mail.ORIGIN_MSG
  • Mail.ORIGIN_EML

The WizardNode contains a list of pending actions that should be done to complete the process of document creation. These might be:

  • Add keyword
  • Add Categories
  • Add Metadata

Example:

package com.openkm;

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

import org.apache.commons.io.IOUtils;

import com.openkm.api.OKMMail;
import com.openkm.bean.Mail;
import com.openkm.bean.WizardNode;
import com.openkm.util.ContextWrapper;

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);
            InputStream is = new FileInputStream("/home/openkm/sample2.eml");
            WizardNode wn = okmMail.createWizard(null, "/okm:root/test", "test title", is, Mail.ORIGIN_EML);
            System.out.print(wn);
            IOUtils.closeQuietly(is);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

getExtractedText

Description:

MethodReturn valuesDescription

getExtractedText(String token, String uuid)

String

Returns a string with the text extracted by the text extraction process.

When a document is uploaded to OpenKM, it goes into the text extraction queue. There's a crontab that periodically processes this queue and extracts document contents.

 

Unfortunately there is no direct way to know if a document has been processed or not from the API, because this information is only stored at the database level.

Despite this restriction, from the API only administrator users can run database queries to retrieve this information. Check Repository samples for accessing database level.

 

More information at Statistics.

 

Example:

package com.openkm;

import com.openkm.api.OKMMail;
import com.openkm.util.ContextWrapper; public class Test { public static void main(String[] args) { try { OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class); String text = okmMail.getExtractedText(null, "46762f90-82c6-4886-8d21-ad3017dd78a7"); System.out.println(text); } catch (Exception e) { e.printStackTrace(); } } }

forwardEmail

Description:

MethodReturn valuesDescription

forwardEmail(String token, String uuid, List<String> users, List<String> roles, List<String> mails, String message)

void

Forwards an email to a list of users, roles, or external email addresses.

Example:

package com.openkm;

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

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

public class Test {

    public static void main(String[] args) {
        try {
            OKMMail okmMail = ContextWrapper.getContext().getBean(OKMMail.class);            
            String mailUuid = "f123a950-0329-4d62-8328-0ff500fd42db";
            List<String> users = new ArrayList<>();
            users.add("userTest");
            List<String> roles = new ArrayList<>();
            roles.add("ROLE_USER");
            List<String> mails = new ArrayList<>();
            mails.add("test@none.com");

            okmMail.forwardEmail(null, mailUuid, users, roles, mails, "Any message");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}