With the autumn finally having arrived, it is time to end the summer break of this blog. We have a couple of interesting topics to cover. Today we take a look at the Document Viewer coach view in IBM Business Process Manager, one of the coach views that enables end users to work with local documents and with document stored in Enterprise Content Management systems that support the CMIS specification.
The purpose of the Document Viewer coach view is to render the content of a document. It is typically used together with the Document Explorer or Document List to let the end user select one of the displayed documents that the Document Viewer then renders. If you already used the coach view, you might have noticed that it can only render a limited set of file formats. The reason for this is that it does not contain any own rendering capabilities. Instead, it delegates the rendering to the browser. Therefore, every file type that your browser can render, can be rendered by the Document Viewer coach view. This includes some popular image formats like GIF, JPEG and PiNG as well as the PDF format. But other important file types – especially the Office file formats – cannot render. For those, the browser triggers a download of the document.
If you are working with a file type that the browser cannot render, then there is an alternate approach to do the rendering. Three years ago, IBM acquired Daeja Image Systems and its products became part of IBM's portfolio. Interesting for us is IBM Daeja ViewONE, a browser file viewer for a large amount of file formats. Some months after this acquisition, I had been taking a look at the product and implemented a Document Viewer coach view based on it. This coach view can be downloaded since then from the Daeja Document Viewer project location. Let's take a look at how to make use of this coach view.
As a prerequisite, you need to have a license of IBM Daeja ViewONE and you need to install the product. IBM Daeja ViewONE comes in several editions, Standard, Professional and Virtual. You should use the Virtual edition as the other editions use a Java applet for the rendering – a past technology that more and more browser vendors block for security reasons.
To be able to use IBM Daeja ViewONE from within an IBM BPM coach view, you need to prepare and install an application into the application cluster of your IBM BPM deployment environment. You can find instructions on how to do this on this documentation page: Configuring IBM Daeja ViewONE. If you want to play with it, then perform these steps now, otherwise, just continue reading and see the nice things you could be creating. ;-)
Building and running it
With IBM Daeja ViewONE being ready, let's quickly build a human service for our first test. We start with just the IBM BPM coach views first. In the human service we are using the Document List coach view and the Document Viewer coach view. In the variables, create a documentInfos variable of the ECMDocumentInfo type as a list. Bind the Document List to the documentInfos variable and enable the Allow create configuration option. Bind the Document Viewer to documentInfos.listSelected.
With that, we are ready to run it for the first time. Use the Document List to create two documents with files as content: one with a JPEG image and another one using an Office file format. Then use the magnifier icon to show the document in the Document Viewer. You will notice that this works for the image but not for the Office document.
Note: the screenshots show the new Document List and Document Viewer coach views from IBM BPM V8.5.7. You can as well use the older coach views in earlier IBM BPM releases.
Now, let's see how this works with the Daeja Document Viewer. For this, download the TWX file that matches your IBM BPM version from Downloads and import it into Process Center. Back to our sample application, add a Toolkit dependency to the Daeja Document Viewer toolkit. In the human service, use the Daeja Document Viewer coach view instead of the Document Viewer. Its binding works the same way as the product coach view. In addition, it is mandatory to specify a height. In a client-side human service you can do this in the Positioning settings. In a heritage human service you can set the height in the configuration of the Daeja Document Viewer.
Let's run the sample again and try to view the office document again: works now in the Daeja Document Viewer.
Let's take a closer look at the configuration options of the Daeja Document Viewer. In the Behavior section additional functionality like a Print button or paging can be enabled.
You may want to play around with them a little bit.
Having done that, let's take a closer look at the Annotations settings. IBM Daeja ViewONE allows to annotate a document in the viewer, for example to highlight sections or to add comments. Using a custom servlet, these annotations can be persisted. The EAR file skeleton that you downloaded, extended with the files from your IBM Daeja ViewONE product installation and installed at the beginning already contains such a servlet. Therefore let's enable annotations. To persist them, three options are available. We stay with the Temporary file for our tests. This stores the annotations in temporary files which is not designated for production usage. You can check the detailed documentation of these configuration properties in the Coach View Getting Started to learn how to store the annotations in a database table or in document properties.
Let's run the viewer with annotations enabled. Once we open the document again, the annotations toolbar is displayed. We can now add and remove different types of annotations. The disk icon in the toolbar allows to save the annotations. When you open the document again, the annotations are automatically loaded and shown.
Finally, let's just have a quick look at the Advanced section. It allows to provide the value for any Daeja ViewONE configuration option, see Configuring the viewer by using HTML parameters. You will need to look deeper into how IBM Daeja ViewONE works to leverage this functionality. As an example, let's try the following one to show how the viewer can be adjusted to the default IBM BPM Theme of IBM BPM V8.5.7:
If you now run the viewer, it will display in a dark blue layout.
And that's it.
We have seen the limitation of the rendering capabilities of the Document Viewer product coach view and we configured the Daeja Document Viewer based on IBM Daeja ViewONE technology to overcome these limitations.
If you had not already started, then now, it is finally your turn to play with it.