Getting Started with IBM FileNet P8 Content Manager — Save 50%
Install, customize, and administer the powerful IBM FileNet Enterprise Content Management platform using this book and eBook
In this article, we'll turn mostly to something else—things that end users would be likely to do. Our primary tool for that will be Workplace XT (XT), though many of the same features are also available in Workplace "classic". Our primary motivation is to show concepts more than it is to present a tutorial for particular applications.
This article by William J. Carpenter, author of Getting Started with IBM FileNet P8 Content Manager, covers the following topics:
- An overview of the XT application
- Browsing and related operations
- XT entry templates
- Workflow interactions
- Document versioning
- Properties and security manipulation
- XT search interfaces
|Read more about this book|
(For more resources on this subject, see here.)
Parts of some of these topics will cover things that are features of the XT application rather than general features of CM and the P8 platform. We'll point those out so there is no confusion.
What is Workplace XT?
IBM provides complete, comprehensive APIs for writing applications to work with the CM product and the P8 platform. They also provide several pre-built, ready to use environments for working with CM. These range from connectors and other integrations, to IBM and third-party applications, to standalone applications provided with CM. Business needs will dictate which of these will be used. It is common for a given enterprise to use a mix of custom coding, product integrations, and standalone CM applications. Even in cases where the standalone CM applications are not widely deployed throughout the enterprise, they can still be used for ad hoc exploration or troubleshooting by administrators or power users.
XT is a complete, standalone application included with CM. It's a good application for human-centered document management, where users in various roles actively participate in the creation and management of individual items. XT exposes most CM features, including the marriage of content management and process management (workflow).
XT is a thin client web application built with modern user interface technologies so that it has something of a Web 2.0 look and feel. To run XT, open its start page with your web browser. The URL is the server name where XT is installed, the appropriate port number, and the default context of WorkplaceXT. In our installation, that's http://wjc-rhel.example.net:9080/WorkplaceXT. We don't show it here, but for cases where XT is in wider use than our all-in-one development system, it's common to configure things so that it shows up on port 80, the default HTTP port. This can be done by reconfiguring the application server to use those ports directly or by interposing a web server (for example, IBM HTTP Server, IHS) as a relay between the browser clients and the application server. It's also common to configure things such that at least the login page is protected by TLS/SSL. Details for both of these configuration items are covered in depth in the product documentation (they vary by application server type).
For some of the examples in this article, we'll log on as the high-privileged user poweruser, and, for others, we'll log on as the low-privileged user unpriv. You can create them now or substitute any pair of non-administrator accounts from your own directory.
Browsing folders and documents
Let's have a look at XT's opening screen. Log onto XT as user poweruser. With the folder icon selected from the top-left group of four icons, as in the figure below, XT shows a tree view that allows browsing through folders for content.
Of course, we don't actually have any content in the Object Store yet, so all we see when we expand the Object Store One node are pseudo-folders (that is, things XT puts into the tree but which are not really folders in the Object Store).
Let's add some content right now. For now, we'll concentrate on the user view of things.
In the icon bar are two icons with small, green "+" signs on them (you can see them in the screenshot above). The left icon, which looks like a piece of paper, is for adding documents to the currently expanded folder. The icon to the right of that, which looks like an office supply folder, is for adding a subfolder to the currently expanded folder.
Select Object Store One in the tree view, and click the icon for adding a folder.
The first panel of a pop-up wizard appears, as shown above, prompting you for a folder name. We have chosen the name literature to continue the example that we started in Administrative Tools and Tasks. Click the Add button, and the folder will be created and will appear in the tree view. Follow the same procedure to add a subfolder to that called shakespeare. That is, create a folder whose path is /literature/shakespeare.
You can modify the security of most objects by right-clicking and selecting More Information | Security. A pop-up panel shows the object's Access Control List (ACL). For now, we just want to allow other users to add items to the shakespeare folder (we'll need that for the illustration of entry templates when we get to that section below). Open that folder's security panel. Click the link for #AUTHENTICATEDUSERS, and check the File In Folder box in the Allow column, highlighted in the following screenshot:
Now let's add some actual documents to our repository. We'll add a few of Shakespeare's famous works as sample documents.
There are many sources for electronic copies of Shakespeare's works readily available on the Internet. One of our favorites for exercises like this is at the Massachusetts Institute of Technology: http://shakespeare.mit.edu. It's handy because it's really just the text without a lot of notes, criticisms, and so on. The first thing you see is a list of all the works categorized by type of work, and you're only a click or two away from the full HTML text of the work. It doesn't hurt that they explicitly state that they have placed the HTML versions in the public domain.
We'll use the full versions in a single HTML page for our sample documents. In some convenient place on your desktop machine, download a few of the full text files. We chose As You Like It (asyoulikeit_full.html), Henry V (henryv_full.html), Othello (othello_full.html), and Venus and Adonis (VenusAndAdonis.html).
Select the /literature/shakespeare folder in the tree view, and click the icon for adding a document. The document add wizard pops up, as shown next:
Browse to the location of the first document file, asyoulikeit_full.html, and click the Next button. Don't click Add Now or you won't get the correct document class for our example.
Initially, the class Document is indicated. Click on Class and select Work of Literature. The list of properties automatically adjusts to reflect the custom properties defined for our custom class. Supply the values indicated (note in particular that you have to adjust the Document Title property because it defaults to the file name). XT uses the usual convention of marking required properties with an asterisk. Click Add.
Repeat the above steps for the other three documents. You'll now have a short list in the shakespeare folder.
XT also provides a "landing zone" for the drag-and-drop of documents. It's located in the upper right-hand corner of the browser window, as shown next. This can save you the trouble of browsing for documents in your filesystem. Even though it can accept multiple documents in a single drag-and-drop, it prompts only for a single set of property values that are applied to all of the documents.
Clicking on a document link in XT will lead to the download of the content and the launching of a suitable application. For most documents, the web browser is used to find and launch an application based on the document content type, although XT does have some configurability in its site preferences for customizing that behavior. The behavior you can normally expect is the same as if you clicked on a link for a document on any typical website.
For graphical image content (JPEG, PNG, and similar formats), XT launches the Image Viewer applet. The Image Viewer applet is especially handy for dealing with Tagged Image Format Files (TIFF) graphics because most browsers do not handle TIFF natively. It is common for fax and scanning applications to generate TIFF images of pages. However, even for common graphics formats that can be rendered by the browser, the Image Viewer applet has more functionality. The most interesting extra features are for adding textual or graphical annotations to the image. Rather than directly manipulating the original image, the annotations are created in an overlay layer and saved as Annotation objects in the repository. For example, in the image below, being displayed in the Image Viewer applet, the stamp tool has been used to mark it as a DRAFT. That annotation can easily be repositioned or even removed without affecting the original image.
The included Image Viewer applet is licensed only for use within the FileNet components where it's already integrated. It is an OEM version of ViewONE from Daeja Image Systems. The ViewONE Pro application, which has additional functionality, is available for license directly from Daeja and can be integrated into FileNet applications as a supported configuration. However, in such cases, support for the viewer itself comes directly from Daeja.
Although each step of document and folder creation is individually straightforward, taken together they can become bewildering to non-technical users, especially if coupled with naming, security, and other conventions. Even when the process is completely understood, there are several details which are purely clerical in nature but which still might suffer from mis-typing and so on.
From these motivations comes an XT feature called Entry Templates. Someone, usually an administrator, creates an entry template as an aid for other users who are creating folders or documents. A great many details can be specified in advance, but the user can still be given choices at appropriate points.
To create an entry template, navigate to Tools | Advanced Tools | Entry Templates | Add. A wizard is launched from which you can define a Document Entry Template or a Folder Entry Template. We won't go through all of the steps here since the user interface is easy to understand. Both types of entry templates are Document subclasses, and XT files created entry templates into folders. When you double-click on an entry template, XT presents a user interface that adheres to the entry template design. For example, in this screen shot which uses an entry template called Shakespearean Document, the document class and target folder are already selected and cannot be changed by the user. Likewise, the author last and full names are pre-populated. Other properties, which genuinely need user input, can be edited as usual.
eBook Price: $38.99
Book Price: $64.99
|Read more about this book|
(For more resources on this subject, see here.)
XT not only communicates with the CE for content management, but it can also communicate with the Process Engine (PE) to manage workflows. Among the choices offered when you are creating an entry template is the launching of an associated workflow. Like many other features discussed in this chapter, there are multiple ways to launch workflows from XT, but using them in entry templates is a common one.
One-time isolated region setup
As user gcd_admin or any other user who you have made an Application Engine Administrator, navigate to Tools Administration | Process Configuration Console|. The Process Configuration Console is implemented as a Java applet. In the tree view, locate the wjc-w2k3-398 isolated region. Right-click and Connect to it. Right-click again and Initialize Isolated Region. The PE database for the isolated region will be populated with various structures, as seen here:
Running workflows can make calls back into the CE to modify documents and other objects. You might, for example, have an approval workflow that updates a document's lifecycle state to reflect approval or rejection. The PE mechanism for allowing running workflows to call out to other systems is called Component Integrator, and the specific implementation for calls to CE is called Content Extended Operations. It is reflected in the CE_Operations component queue seen in the above image.
The Component Integrator is an extremely powerful feature of PE, and you are not limited to the specific things implemented in CE_Operations. You can implement your own components, including making additional types of CE calls.
There are many configuration parameters for tuning Content Extended Operations, but our immediate interest is in the credentials that it will use when calling back into the CE. Right-click the CE_Operations node and select Properties. On the Adaptor tab, as seen here, are fields for the User Name and Password to be used. This user must have sufficient CE access rights to perform the operations that will come through Content Extended Operations. In general, this means the ability to make a very flexible set of changes to many or most objects in the CE. Obviously, that is a very powerful account. Our advice is to make a dedicated directory account for just that purpose, as we have shown here, and take precautions to protect it from compromise.
If you have a full BPM license, you will have a variety of tools for creating and managing workflows. With a CM license, you have a PE server and two workflow definitions provided with XT. Both are offered during the Select Workflow step of entry template creation.
As you can see from the captions in the previous screenshot, the Fixed Approval Workflow consists of a pre-defined two or three step workflow. This satisfies many common use cases for simple document approval. For more complex cases, the Sequential Approval Workflow allows you to create additional steps. The names of the specific steps are merely suggestions and can be renamed to anything you want. Participants in each workflow step can be specified when the workflow is associated with the entry template or can be left to the user to assign at run time.
Tasks in XT
Participants in workflows can see pending items in XT inboxes. In this screenshot, you can see that the user, poweruser, is looking at the Tasks area of XT. Because poweruser is listed as a participant in the Reviewers step of the Fixed Approval Workflow that was launched when someone added the Cymbeline document, that approval step appears in the inbox, ready to be approved or rejected.
If the user clicks on the link, XT's HTML step processor will open. The reviewing user will have a pointer to the document as the primary workflow attachment and can see that the workflow was launched by the user unpriv. For this scenario, that means that unpriv added the document. If poweruser approves the workflow step, the work item will be moved from his/her inbox to the inbox of the participants listed in the Approvers step. On the other hand, while the workflow is in progress, unpriv can check its progress by looking at the My Active Workflows menu item.
Adding and browsing documents is one thing, but documents must often be manipulated in various ways. The most fundamental manipulation is versioning. In an ECM context, versioning means the controlled ability to modify the content of a document. In CM, you can't literally modify the content of a document, but you can create a new version of the document and modify the content of that new version in the process. Let's just see how it works.
While logged onto XT as poweruser, select the /literature/shakespeare folder in the tree view. Let's imagine we've noticed a typographical error in one of the texts. We'll simulate correcting it by making an inconsequential change. Select Venus and Adonis, and perform a checkout operation. You can do that in a couple of different ways in XT. For our purposes, right-click and select Check Out and Download from the context menu. You'll be prompted for a location to save the contents of the file downloaded from the repository. Select any convenient location, but don't overwrite your original. You'll see that a small red check mark appears next to the document in XT to indicate that it's checked out. Nobody else can check out the same document until we check it back in or cancel our checkout.
While we have a document checked out, you might be interested in clicking the Checkout List pseudo-folder in the tree view to see that our document is, indeed, on the list.
Open the downloaded file VenusAndAdonis.html with an editor (not with a web browser). If you happen to have an HTML editor or a word processor that understands HTML, that's fine. Otherwise, just use any text editor. The files we got from MIT have Unix-style line endings, so editors such as Windows Notepad may show them as a hard-to-read jumble, but never mind that for now. Make some small change to the file. For example, you might change the spelling of Shakespeare's name. Anything that you will recognize later is fine. Save the changed file and exit your editor.
Return to XT, select the document again, and this time select Check In from the context menu. You'll be prompted to browse for the modified file on your local machine. Once you've done that, click the Options button (do not click the Check In button yet). You'll see a property sheet like the next figure, which is very similar to the one we originally used to enter the documents into the repository:
Notice that most or all property values are already populated with values from the previous version. We could change some of those property values here if we were so inclined.
Click the Check In button to complete the operation. Notice that the Major Version column is bumped from 1 to 2 in XT to indicate that this is the second version of the document. The modification date is also updated to the current date and time.
What happened to the previous version of the document? It's still in the repository and available. From the context menu, navigate to More Information | Versions.
You'll notice a pop-up window displaying a complete list of the available versions of the document. It's typical to express the major and minor version information in decimal notation, or, in our case, 2.0 and 1.0. You can probably guess that you can create minor versions of documents and that there are other Version Status labels beyond the Released and Superseded values that you see in the screenshot.
From that same pop-up screen, you can directly examine the content or property sheet for any version still available in the repository. If you click the hyperlinked value in the Title column, that version should open in a web browser. For the Released version, you should be able to spot the change you made. Close the pop-up to return to the main XT screen.
Suppose you've come to regret your decision to modify the document. (Who do you think you are, anyway? Shakespeare?) One option would be to do another checkout/checkin cycle and attempt to restore the file's original contents. Of course, you'd still be leaving around a record of your impudent editing, and you may or may not be able to get back to the original contents for a complex document (unless you realize that you can download the content from an earlier version in the repository). What we really want, in this case, is more of an "undo" for the checkout/checkin cycle that is already completed.
Within the CE, each document version is a separate object that can be manipulated individually. The delete action in XT (and most other tools) acts behind the scenes to delete all of the versions of a document because that is the most common use case. XT also offers the option to delete individual versions. Right-click the document again, and from the context menu navigate to More Actions | Delete Versions. You'll see a pop-up listing all available document versions, similar to the previous pop-up. This time, the individual versions have checkboxes next to them, and you can decide which versions you want to delete. Beware that once you delete them, they really will be gone from the repository.
Interestingly enough, it's not just the older versions that you can delete. Notice that you can delete any version, including the current version. Go ahead and do that: check the box for the Released version and click Accept (do not check the box for the older version). When you get back to the main XT window, you'll see that the major version is once again 1. If you look at that document's content, you'll see the original, unmodified text, as expected.
Hey presto! It's content management.
Deleted objects are really, permanently deleted. There is no undo or recycle bin or similar mechanism unless an application implements one.
eBook Price: $38.99
Book Price: $64.99
|Read more about this book|
(For more resources on this subject, see here.)
Properties and security
While we're here in the browsing portion of the XT user interface, let's briefly look at a few items that can be viewed and updated for a document. Although we'll be examining a document, it illustrates a pattern that is also applicable to folders and other objects in the repository, including the Object Store itself.
Click on a document, for example, Venus and Adonis, and select Properties from the context menu. A very familiar-looking property sheet will pop up, as shown next. One difference from the property sheets we saw earlier is that this one has a section at the bottom for System properties. Every object in the repository has system properties, though the actual properties vary by object type. There are some custom and system properties that XT doesn't show, but all properties are visible to administrators in FEM. Many or all custom properties can be updated from this property sheet, depending on security and how the property was defined. XT will not let you change any values that it can't save to the repository.
If you click on a document and navigate to More Information | Security from the context menu, you'll see a pop-up window giving details of the document's access control list (ACL). What we see below is a typical arrangement. The owner, poweruser, and the administrators have many rights to do things with the document. Everyone else, members of the pseudo-group #AUTHENTICATED-USERS, have only limited rights. The fine-grained security in CM is one of its strongest features.
Browsing through folders for documents is nice in many respects. It feels natural to most computer users. Once you get to a large number of documents, it can be tedious or impossible to use this technique to find things you want. If you've ever clicked around fruitlessly among the folders on your computer looking for a recipe that someone gave you or for your resume from five years ago, you probably know that you sometimes need a better way.
CM offers two major kinds of searches, and it's even possible to combine the two types into a single search.
- The first type of search has a long history in the ECM and database worlds. It is structured searching based on property values. This is also sometimes called metadata searching.
- The second type of search is of more recent vintage but is available on most ECM platforms today. It is full-text searching based on the content of documents and annotations. CM also offers full text searching for string-valued properties on documents, folders, custom objects, and annotations.
These days, most non-technical users are more familiar with full-text searching because it is quite similar to the type of searching offered by Internet search engines. Non-technical users are less familiar with metadata search.
XT attempts to present both types of searches to users in a way that is rational and easy to use. If you click on the magnifying glass icon, you will see XT's three search types: Simple, Keyword, and Advanced. We'll look at each in turn.
XT exposes a large percentage of CM search features, but some things are not available. The complete set of search features is available via a Structured Query Language (SQL) dialect specific to the CE. CE SQL can be used directly via the APIs, via FEM, and via a few other tools.
The aim of Simple Search is to provide a straightforward interface that serves the most common searching needs. The options pretty much speak for themselves. A user doesn't have to be too concerned with the names of properties and other technical factors. He or she merely clicks the applicable checkboxes, enters a term or two, and XT does the rest. This image shows the results of a search for documents whose name starts with the word "Venus".
To parody a modern cliché, however: with limited responsibility comes limited power. The simple search does not provide many options for customization or more sophisticated searching capability.
Keyword Search is XT's terminology for full-text searching. Content-based retrieval (CBR) is just another term for full-text searching. The XT keyword search can only find things that someone has chosen to index via the CE administrative tools.
In this screenshot, we show a simple keyword search for the word "dispatch", which happens to occur in three of the four documents we added. Keyword search results contain a Score column, which is a judgment of the text search engine on how well a document matches the search keywords. If you go and browse around in the text, you will find that Othello contains the word "dispatch" four times, Henry V has it three times, and As You Like It has it only twice. The relative scores reflect that more occurrences of a keyword equates to a better match, at least for simple lists of keywords.
The Advanced Search not only combines the metadata search of Simple Search with the full-text search of Keyword Search, but it also provides powerful features for adding sophisticated custom property conditions to the search. In the screenshot, we've shown just a couple of properties and operations, but rather elaborate conditional expressions can be constructed.
Once you have tuned your search to find just what you are looking for, you can click the Save as button to name and save your search. When you come back to XT's search interface, your saved searches are listed on the left-hand side as My searches.
Stored Searches and Search Templates
XT has a feature for pre-defining searches. The usual use case is that an administrator or someone who is technically adept creates the search definition. A more general population can then run the searches with less technical knowledge about the CE and application data models.
The difference between a Stored Search (SS) and a Search Template (ST) is that the template allows some input from the user at run time. The user who designs an SS or an ST has a great deal of flexibility in predefining restrictive conditions which the running user cannot evade, but there is equal flexibility in the input collected from a user. An SS or an ST is created using a Java applet called Search Designer (SD). You launch SD from XT by navigating to Tools | Advanced Tools | Search Designer. The SD interface is relatively straightforward, so we'll instead show what the user interface for a Search Template looks like when a user executes it in XT.
Stored Searches and Search Templates are Document subclasses, and SD files them in folders of the designing user's choice. When browsing in XT, searches are part of folder contents, just like other documents, though they do have a distinctive icon in the user interface. If you double-click on a Stored Search, XT immediately runs the search and displays the results. If you double-click on a Search Template, XT displays an interface for supplying values according to the ST definition. The search is actually performed when the user clicks the Search button.
The following image shows both the search parameters and the search results for an ST that searches for document of class "Work of Literature" and which either have a Document Title that starts with the word "Venus" or have the word "dispatch" within the content. If you have been following the earlier examples, you will not be surprised to see that it returns all four of our sample documents.
This example contains a case of simple pattern matching on a stringvalued property. The same thing is available several other ways in XT searches, and all use the CE SQL LIKE function. You should be aware that matching the beginning of a property ("starts with") is generally reasonably efficient, but matching the middle ("contains") or the end ("ends with") is an inefficient operation at the database level. Unless other conditions are used in the search to refine the potential results set, "contains" or "ends with" can result in database table scans that can gravely impact performance.
XT has many more features than we've shown here. The point of this article was to give a look at a few typical end user features and operations. You can read more about XT, including customization and site and user preferences, in the CM product documentation.
- IBM FileNet P8 Content Manager: Administrative Tools and Tasks [Article]
- IBM FileNet P8 Content Manager: Exploring Object Store-level Items [Article]
- Domino 7 Lotus Notes Application Development [Book]
- IBM Lotus Quickr 8.5 for Domino Administration [Book]
- IBM Cognos 8 Report Studio Cookbook [Book]
- WS-BPEL 2.0 for SOA Composite Applications with IBM WebSphere 7 [Book]
About the Author :
William J. Carpenter is an Enterprise Content Management Architect with IBM in the Seattle, Washington, area. He has experience in the Enterprise Content Management business since 1998, as a developer, development manager, and architect. He is co-author of the books IBM FileNet Content Manager Implementation Best Practices and Recommendations and Developing Applications with IBM FileNet P8 APIs, is a Contributing Author on IBM developerWorks, and is a frequent conference presenter. He has experience in building large software systems at Fortune 50 companies and has also served as the CTO of an Internet startup. He has been a frequent mailing list and patch contributor to several open source projects. He holds degrees in Mathematics and Computer Science from Rensselaer Polytechnic Institute in Troy, New York.