How to Store and Load a Document

A Document in the Imixs-Workflow systems is represented by the ItemCollection class, which presents a generic value object used by all methods of the Imixs-Workflow engine. The DocumentService provides methods to save and load a document.

The following example shows how an instance of an ItemCollection can be saved using the DocumentService:

  @EJB
  org.imixs.workflow.jee.ejb.DocumentService documentService;
  //...

  ItemCollection myDocument=new ItemCollection;
  myDocument.setItemValue("type","product");
  myDocument.setItemValue("name","coffee");
  myDocument.setItemValue("weight",new Integer(500));
  	
  // save ItemCollection
  myDocument=documentService.save(myDocument);

In this example a new ItemCollection is created and the properties 'type, ‘name’ and ‘weight’ are stored into a ItemCollection. The save() method stores the document into the database. If the document is stored the first time, the method generates an ID which can be used to identify the document for later access. This ID is provided in the property ‘$uniqueid’ which will be added automatically by the DocumentService. If the document was saved before, the method updates only the items of the document in the database.

The next example shows how to use the $uniqueid of a stored ItemCollection to load the document from the database. For this the ID is passed to the load() method:

  @EJB
  org.imixs.workflow.jee.ejb.DocumentService documentService;
  //...
  // save document
  myDocument=documentService.save(myDocument);
  // get ID from ItemCollection 
  String id=myDocument.getUniqueID();
  // load the document from database
  myDocument=documentService.load(id);

Note: The method load() checks if the CallerPrincipal has read access to a document. If not, the method returns null. The method doesn't throw an AccessDeniedException if the user is not allowed to read the document. This is to prevent an aggressor with informations about the existence of that specific document.

  ItemCollection myDocument=new ItemCollection;
  myDocument.settemValue("type","product");
  ....
  // save ItemCollection
  myDocument=documentService.save(myDocument);
  
  // select documents by type...
  List<ItemCollection> products=documentService.getDocumentsByType("product");

  //...
  // save ItemCollection
  myDocument=documentService.save(myDocument);
  Date created=myDocument.getItemValueDate("$Created");
  Date modified=myDocument.getItemValueDate("$Modified");

$immutable=true

Search Documents

The DocumentService provides a Lucene Index to query documents by an individual search query. A document is automatically added into the index when the document is saved. The find() method of the DocumentService can be used to query documents by a Lucene search term.

The following example returns all documents starting with the search term ‘Imixs’:

String serachTerm="(imixs*)";
result=documentService.find(serachTerm);

To query for a specific subset of documents, it is also possible to add individual attributes to the search term. The follwoing example will return all documents with the serach term ‘imixs’ and the Type ‘workitem’:

String serachTerm="(type:'workitem')(imixs*)";
result=documentService.find(serachTerm);

See the section Query Syntax for details about how to search for documents.

String serachTerm="(imixs*)";
// return only the first 10 documents 
result=documentService.find(serachTerm,10,0);

 String serachTerm="(imixs*)";
// return only the first 10 documents 
// sort by $created descending
result=documentService.findStubs(serachTerm,10,0,'$created',true);

result = documentService.findStubs(query, 100, 0, '$created' , true);

Query Documents

All documents are managed by the Java Persistece API (JPA). The Java Persistence Query Language (JPQL) can be used to select documents by the Document entity schema independent from the existence of the Lucene search index. The following example selects all documents from the type=‘workitem’:

SELECT document FROM Document AS document 
WHERE document.type='workitem' 

JPQL can be used to sort documents by one of the attributes ‘id’, ‘type’, ‘modified’ or ‘created’. These are the attributtes of the Document Entity Bean. The following example sorts the result by the creation date:

SELECT document FROM Document AS document 
WHERE document.type='workitem' 
ORDER BY document.created DESC

The Access Control List of a Document

Additional the DocumentService allows to restrict the read- and write access for a document by providing a ACL. The items ‘$readaccess’ and ‘$writeaccess’ can be added into a document to restrict the access. The items can provide a list of UserIds or Roles.

  @EJB
  org.imixs.workflow.jee.ejb.DocumentService documentService;
  //...

  ItemCollection myDocument=new ItemCollection;
  myDocument.setItemValue("type","product");
  myDocument.setItemValue("name","coffee");
  myDocument.setItemValue("weight",new Integer(500));
  
  // restrict read access to 'bob'
  myDocument.setItemValue("$readaccess","bob");
  // restrict write access to 'anna'
  myDocument.setItemValue("$readaccess","anna");
  	
  // save ItemCollection
  myDocument=documentService.save(myDocument);

For further details read the section ACL.

Note: There is no need to set the Read- and Writeaccess programmatic because the ACL of a workitem can be managed model definition in a transparent way.

The UserNameList

The DocumentService provides the method getUserNameList() which returns a list of user names, roles and application groups the current user belongs to.

List<String> userNames = documentService.getUserNameList();

Inject Custom User Groups

Imixs-Workflow supports an mechanism to inject additional user groups into the security layer of the Imxis-Workflow engine.

Based on CDI Events your can inject custom user groups from your own application or library. For example, your application can lookup groups from a LDAP directory or a user-database and inject this groups into the security mechanism.

The typically implementation of this mechanism is done by an CDI observer pattern:

public void onUserGroupEvent(@Observes UserGroupEvent userGroupEvent) {
	List<String> customGroups = new ArrayList<String>();
	customGroups.add("my-group");
	userGroupEvent.setGroups(customGroups);
}

The CDI DocumentEvent

The DocumentService EJB provides an Observer Pattern based on CDI Events. The events are fired when a document is loaded or saved. The Event is defined by the class:

org.imixs.workflow.engine.DocumentEvent

The class DocumentEvent defines the following event types:

• ON_DOCUMENT_SAVE - send immediately before a document will be persisted. The document is already managed by JPA but the transaction is not closed and the lucene index is not updated. So a EJB-Exception can roll back the changes. This event should be handled in the same transaction context.
• ON_DOCUMENT_LOAD - send immediately after a document was loaded. The document may already be managed by JPA (attached) if the document was saved in the same transaction.
• ON_DOCUMENT_DELETE - send immediately before a document will be deleted

This DocumentEvent can be consumed by another Session Bean or managed bean implementing the @Observes annotation:

@Stateless
public class DocumentServiceListener {
    public void onEvent(@Observes DocumentEvent documentEvent){
        ItemCollection document=documentEvent.getDocument();
        System.out.println("Received DocumentEvent Type = " + documentEvent.getType());
	}
}

In both event types, an observer client can change the data of the document.