Creating a new document through the Hippo Repository Workflow API

It's already a couple of months ago that I wrote about using the Hippo Repository Workflow API. Back then, I explained how to modify an existing document, and request publication. Ever since that blog post I have been getting the same question over and over again: how to create a new document through the repository API?

If you read the previous blog post, and looked at the worklfow API, it might not be directly obvious how to create a new document through the workflow. Think about how a document is created though: it is always created as a child node of an existing node: the parent folder. Creating a new document is actually part of the Folder Workflow!

Knowing this, it all becomes very easy. Let's step through the code:

Let's hardcode some values for simplicity's sake:

String folderPath = "/content/documents/news";
String newDocumentName = "Hippo CMS 7.1 released!";
String newDocumentType = "defaultcontent:news";

We will be creating a new document inside the folder /content/documents/news. This is actually a node of type hippostd:folder, which means a FolderWorkflow applies to this node. We will be creating a new document of type "defaultcontent:news", as provided with the Hippo CMS Quickstart WAR. We will call the new document "Hippo CMS 7.1 released!".

Next, we get the folder node from the repository session:

// get the folder node
HippoNode folderNode = (HippoNode) session.getItem(folderPath);

We also need the workflow manager:

// get the workflow manager
HippoWorkspace workspace = (HippoWorkspace) folderNode.getSession().getWorkspace();
WorkflowManager workflowMgr = workspace.getWorkflowManager();

Using the workflow manager, get the folder node's workflow:

// get the folder node's workflow
Workflow workflow = workflowMgr.getWorkflow("internal", folderNode);

Check if the workflow is a folder workflow, and cast it to a FolderWorkflow object:

if (workflow instanceof FolderWorkflow) {
    FolderWorkflow fw = (FolderWorkflow) workflow;

Now that we have the folder workflow, we can simply call the add method. It takes three String parameters: the category ("new-document"), the node type, and the node name:

// create the new document
fw.add("new-document", newDocumentType, newDocumentName);

That's it! Run the program, and check your CMS. There should be a new document "Hippo CMS 7.1 Released!" visible under the "news" folder. You can edit and publish this document just like any other. To modify the document through the API, see my previous post on this subject.

For your convenience, here is the complete class:

package org.example;

import java.rmi.RemoteException;

import javax.jcr.RepositoryException;
import javax.jcr.Session;

import org.hippoecm.repository.HippoRepository;
import org.hippoecm.repository.HippoRepositoryFactory;
import org.hippoecm.repository.api.HippoNode;
import org.hippoecm.repository.api.HippoWorkspace;
import org.hippoecm.repository.api.Workflow;
import org.hippoecm.repository.api.WorkflowException;
import org.hippoecm.repository.api.WorkflowManager;
import org.hippoecm.repository.standardworkflow.FolderWorkflow;

public class CreateDocument {

    public static void main(String[] args) {
        Session session;
        HippoRepository repository;
        try {
            repository = HippoRepositoryFactory.getHippoRepository("rmi://localhost:1099/hipporepository");
            session = repository.login("author", "author".toCharArray());
            
            String folderPath = "/content/documents/news";
            String newDocumentName = "Hippo CMS 7.1 released!";
            String newDocumentType = "defaultcontent:news";

            // get the folder node
            HippoNode folderNode = (HippoNode) session.getItem(folderPath);
            
            // get the workflow manager
            HippoWorkspace workspace = (HippoWorkspace) folderNode.getSession().getWorkspace();
            WorkflowManager workflowMgr = workspace.getWorkflowManager();
            
            // get the folder node's workflow
            Workflow workflow = workflowMgr.getWorkflow("internal", folderNode);
            
            if (workflow instanceof FolderWorkflow) {
                FolderWorkflow fw = (FolderWorkflow) workflow;
                
                // create the new document
                fw.add("new-document", newDocumentType, newDocumentName);
                
                System.out.println("New document '" + newDocumentName + "' of type '" + newDocumentType + "' created");
            }
            else {
                System.out.println("Workflow is not an instance of FolderWorkflow");
                return;
            }
            
        } catch (RepositoryException e) {
            System.out.println(e.getMessage());
        } catch (RemoteException e) {
            System.out.println(e.getMessage());
        } catch (WorkflowException e) {
            System.out.println(e.getMessage());
        }
    }
}

HST Components at Hippo Forge

In the past couple of days I slapped together two simple components for use with the Hippo Site Toolkit 2: RSS Feed Creator and List Builder. At this moment, their names are more fancy than their actual functionalities ;-) but the idea is to provide some basic building blocks that people can take and extend. Both components are hosted at Hippo Forge, so the source code is available and you can do with them whatever you want. Go ahead and take them for a test drive. If you think you can improve them (not that hard), feel free to contribute your work. I am happy to apply your patches. I might even consider giving you commit rights! ;-)

The Forge is actually starting to become a well stocked library of CMS and HST components. Check out the Related Items Plugin; It helps you creating a list of documents related to the one you are editing, by making suggestions. Just one example of reusable functionality that you can add to your CMS project. Doesn't match your exact requirements? Adapt it, it's open source! Made a component for your project that is useful for others? Add it to the Forge!

Coming soon to a computer near you: Hippo Site Toolkit 2!

It's almost finished! Hippo Site Toolkit 2 will be released really soon now. I am working on the documentation right now and I have to say I am impressed by the work of our development team.

Hippo Site Toolkit 2 is a very versatile and lightweight component based framework for building websites on the Hippo CMS stack. Very much in Hippo tradition, we do not enforce you to use any particular technology or framework, but rather give you freedom of choice and the building blocks you need.

Some highlights among the many features of Hippo Site Toolkit 2 are:

Component based
HST2 lets you create reusable components and assemble webpages from those components.

Transparent support for portlets
HST2 components can be used out of the box as portlets in a portal environment.

Framework independent
Although our primary focus is JSP, any Java web framework can make use of HST2 functionalities. A Spring MVC example is included.

Plain Java
HST2 does not enforce any "dominating technology" that has been built on top of Java, such as Cocoon or Sling. It's all plain old Java.

Rapid website development
HST2 includes a web based configuration GUI embedded in Hippo CMS, and many reusable out of the box components.

There is no official release yet, and it's still a little rough around the edges here and there (you need to use the CMS Console for some configuration), but it is already usable. If you want to live on the edge, check out the trunk and give it a go (see the README). If not, stay tuned while we finish up the release and the documentation!