PrepPak API

The PrepPak API helps the user to create and manipulate PrepPaks and associated documents via the XML-RPC service.

CALO Express (CE) must be installed prior to using the PrepPak API. Please configure CE to scan the email and file folders that you want accessible for PrepPaks. Let CE run overnight to fully complete its scan.

Accessing the Service

External applications written in Java can access PrepPak by using XmlRpcUtilities.callServiceMethod() with the service name “RemotePreppak.”  For applications written in other languages:

1.       Determine the port where the RemotePrepPak service is running by reading the file “C:\Documents and Settings\<YOUR-USERNAME>\caloExpressPersistence\<ver-XX>\preferences\RemotePreppak_Port.pref”.

2.       Make an XML-RPC call to http://localhost:<PORT>/xmlrpc/<METHOD> where <PORT> is the port number and <METHOD> is one of the methods described under “API Methods” below.

Accessing the Database

The PrepPak API refers to item ids in the CALO Express Database. See CALO Express Desktop Harvesting for instructions on accessing the database.

API Data Structures

PrepPak – Array of three elements:

[

    string preppakItemId - Id of item originally used to make the PrepPak.

    string name – Human readable name of the PrepPak.

    PrepPakEntry[] – Entries in the PrepPak.

]

 

PrepPakEntry – Array of three elements:

[

    string id – Id of item in CALO Express database.

    boolean isPersistentlyIncluded – true for required “keep-in-preppak” items, false for suggested items.

    double preppakScore – Relevance of the item in the PrepPak, between 0.0 and 1.0.

]

 

API Methods

// Description: Construct a new PrepPak or retrieve the existing PrepPak for an

// item.

//

// Input: Id of an item in the CALO Express database.

//

// Output: PrepPak structure

//

GetPreppak(string itemId);

 

 

// Description: Explicitly keep a list of items persistently in a PrepPak in response

// to user request.

//

// Input:

//     preppakItemId – Id of item originally used to make the PrepPak.

//     items – Array of the ids of the items to keep in the PrepPak.

//

// Output: The updated PrepPak structure.

//

KeepInPreppak(string preppakItemId, string[] items)

 

 

// Description: Explicitly remove a list of items from a PrepPak in response

// to user request.

//

// Input:

//     preppakItemId – Id of item originally used to make the PrepPak.

//     items – Array of the ids of the items to remove from the PrepPak.

//

// Output: The updated PrepPak structure.

//

RemoveFromPreppak(string preppakItemId, string[] items)

 

 

// Description: Notify PrepPak when the user opens or otherwise accesses items

// in a PrepPak. Needed for learning from implicit feedback.

//

// Input:

//     preppakItemId – Id of item originally used to make the PrepPak.

//     items – Array of the ids of the items that were accessed.

//

// Output: none

ItemsAccessed(string preppakItemId, string[] items)

 

PreppakClient Sample Program

The PreppakClient is a simple Java Swing program for creating and manipulating PrepPaks for Outlook calendar events.

Install CALO Express and harvest at least one Outlook calendar event. In CE, you can do a natural language search like “all events” or “events this month about project-x” to find some events. Download the zip file and unzip it, then follow the instructions in readme.txt to build and run the sample program.

The program will prompt you for information to find a specific Outlook calendar event and then will display a PrepPak window with suggested relevant items. You can explicitly promote suggested items to be required items by first selecting those items and then clicking “Keep in PrepPak.” Similarly, you can explicitly remove items by first selecting the items and then clicking on “Remove from PrepPak.”  You can provide implicit feedback that the item is relevant simply by double clicking the item to open it. Unlike the full CALO Express interface, this simple program does not allow you to add new items to a PrepPak.

A PrepPak in the Java Sample Program

javaPrepPak.png

The same PrepPak in the full CALO Express User Interface

cePrepPak.png

 

Preppak.java from the sample program, a simple wrapper on XML-RPC calls.

package preppakClient;

 

import org.apache.xmlrpc.XmlRpcException;

 

import java.util.*;

import java.io.IOException;

 

import com.sri.calo.caloCommon.NoPortException;

import com.sri.calo.caloCommon.XmlRpcUtilities;

 

// Demonstrates a PrepPak implementation to get PrepPak entries,

// keeping the entries in the PrepPak, removing the entries from PrepPak and

// refreshing the PrepPak list via XML-RPC calls

public class Preppak implements IPreppak {

    private final static String REMOTE_PREPPAK_SERVICE_NAME = "RemotePreppak";

 

    private String itemId;

    private String name;

    private List<IPreppakEntry> entries = new ArrayList<IPreppakEntry>();

 

    // Constructor passes unique identifier to CALO Express item

    public Preppak(String itemId) throws XmlRpcException, NoPortException, SerializationException {

        this.itemId = itemId;

        refresh();

    }

 

    // Refreshes the contents of the PrepPak by calling GetPreppak XML-RPC method

    public void refresh() throws XmlRpcException, NoPortException, SerializationException {

        Object[] params = new Object[]{itemId};

        Object result = XmlRpcUtilities.callServiceMethod(REMOTE_PREPPAK_SERVICE_NAME,"GetPreppak",params);

        try {

            Deserialize(result);

        }

        catch (Exception e) {

            throw new SerializationException();

        }

    }

 

    // Gets the unique name of the PrepPak

    public String getName() {

        return name;

    }

 

    // Returns PrepPak entries

    public List<IPreppakEntry> getEntries() {

        return entries;

    }

 

    // Deserializes the results of the XML-RPC call and constructs a list of PrepPak entries

    private void Deserialize(Object serialized) throws IOException, MissingItemException {

        entries.clear();

        Object[] array = (Object[])serialized;

        this.itemId = (String)array[0];

        this.name = (String)array[1];

        for (int n = 2; n < array.length; n++) {

            entries.add(DeserializeEntry(array[n]));

        }

    }

 

    // Deserializes a PrepPak entry

    private IPreppakEntry DeserializeEntry(Object serialized) throws IOException, MissingItemException {

        Object[] array = (Object[])serialized;

        return new PreppakEntry((String)array[0],((Boolean)array[1]).booleanValue(),((Double)array[2]).floatValue());

    }

 

    // Marks a list of entries as keep in PrepPak

    public void keepInPreppak(List<IPreppakEntry> entries) throws NoPortException, XmlRpcException, SerializationException {

        Object[] params = new Object[]{

            itemId,

            Utilities.entryListToArray(entries),

        };

        Object result = XmlRpcUtilities.callServiceMethod(REMOTE_PREPPAK_SERVICE_NAME,"KeepInPreppak",params);

        try {

            Deserialize(result);

        }

        catch (Exception e) {

            throw new SerializationException();

        }

    }

 

    // Removes a list of entries from PrepPak

    public void removeFromPreppak(List<IPreppakEntry> entries) throws NoPortException, XmlRpcException, SerializationException {

        Object[] params = new Object[]{

            itemId,

            Utilities.entryListToArray(entries),

        };

        Object result = XmlRpcUtilities.callServiceMethod(REMOTE_PREPPAK_SERVICE_NAME,"RemoveFromPreppak",params);

        try {

            Deserialize(result);

        }

        catch (Exception e) {

            throw new SerializationException();

        }

    }

 

    // Activates an entry in the PrepPak

    public void entryActivated(IPreppakEntry entry) throws NoPortException, XmlRpcException, SerializationException {

        Object[] params = new Object[]{

            itemId,

            new Object[]{entry.getItem().getId()},

        };

        XmlRpcUtilities.callServiceMethod(REMOTE_PREPPAK_SERVICE_NAME,"ItemsAccessed",params);

    }

}