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
The previous article dealt with Exploring Domain-level items. Let's turn our attention now to the Object Store and things inside it. Since an Object Store is a repository, things that reside inside an Object Store are called repository objects. It's a slightly technical point, but the Object Store itself is not a repository object.
In this article by William J. Carpenter, author of Getting Started with IBM FileNet P8 Content Manager, we'll cover:
- A discussion of an Object Store and what's in it
- An example of creating a custom class and adding custom properties to it
|Read more about this book|
(For more resources on this subject, see here.)
As with the Domain, there are two basic paths in FEM to accessing things in an Object Store. The tree-view in the left-hand panel can be expanded to show Object Stores and many repository objects within them, as illustrated in the screenshot below.
Each individual Object Store has a right-click context menu. Selecting Properties from that menu will bring up a multi-tabbed pop-up panel. We'll look first at the General tab of that panel.
Content Access Recording Level
Ordinarily, the Content Engine (CE) server does not keep track of when a particular document's content was last retrieved because it requires an expensive database update that is often uninteresting. The ContentAccessRecordingLevel property on the Object Store can be used to enable the recording of this optional information in a document or annotation's DateContentLastAccessed property. It is off by default.
It is sometimes interesting to know, for example, that document content was accessed within the last week as opposed to three years ago. Once a particular document has had its content read, there is a good chance that there will be a few additional accesses in the same neighborhood of time (not for a technical reason; rather, it's just statistically likely). Rather than record the last access time for each access, an installation can choose, via this property's value, to have access times recorded only with a granularity of hourly or daily. This can greatly reduce the number of database updates while still giving a suitable approximation of the last access time. There is also an option to update the DateContentLastAccessed property on every access.
The CE server can record when clients retrieve or update selected objects. Enabling that involves setting up subscriptions to object instances or classes. This is quite similar to the event subsystem in the CE server. Because it can be quite elaborate to set up the necessary auditing configuration, it can also be enabled or disabled completely at the Object Store level.
The CE server offers two document checkout types, Collaborative and Exclusive. The difference lies in who is allowed to perform the subsequent checkin. An exclusive checkout will only allow the same user to do the checkin. Via an API, an application can make the explicit choice for one type or the other, or it can use the Object Store default value. Using the default value is often handy since a given application may not have any context for deciding one form over another.
Even with a collaborative checkout, the subsequent checkin is still subject to access checks, so you can still have fine-grained control over that. In fact, because you can use fine-grained security to limit who can do a checkin, you might as well make the Object Store default be Collaborative unless you have some specific use case that demands Exclusive.
Text Index Date Partitioning
Most of the values on the CBR tab, as shown in the figure next, are read-only because they are established when the Content Search Engine (CSE) is first set up.
One item that can be changed on a per-Object Store basis is the date-based partitioning of text index collections. Partitioning of the text index collections allows for more efficient searching of large collections because the CE can narrow its search to a specific partition or partitions rather than searching the entirety of the text index.
By default, there is no partitioning. If you check the box to change the partition settings, the Date Property drop-down presents a list of date-valued custom properties. In the screenshot above, you see the custom properties Received On and Sent On, which are from email-related documents. Once you select one of those properties, you're offered a choice of partitioning granularity, ranging from one month up to one year.
Additional text index configuration properties are available if you select the Index Areas node in the FEM tree-view, then right-click an index area entry and select Properties. Although we are showing the screenshot here for reference, your environment may not yet have a CSE or any index areas if the needed installation procedures are not complete.
Just as we saw at the Domain level, the Cache tab allows the configuration of various cache tuning parameters for each Object Store. As we've said before, you don't want to change these values without a good reason. The default values are suitable for most situations.
One of the key features of CM is that it has an extensible metadata structure. You don't have to work within a fixed framework of pre-defined document properties. You can add additional properties to the Document class, and you can even make subclasses of Document for specific purposes. For example, you might have a subclass called CustomerProfile, another subclass called DesignDocument, yet another subclass called ProductDescription, and so on. Creating subclasses lets you define just the properties you need to specialize the class to your particular business purpose. There is no need to have informal rules about where properties should be ignored because they're not applicable. There is also generally no need to have a property that marks a document as a CustomerProfile versus something else. The class provides that distinction.
CM comes with a set of pre-defined system classes, and each class has a number of pre-defined system properties (many of which are shared across most system classes). There are pre-defined system classes for Document, Folder, Annotation, CustomObject, and many others. The classes just mentioned are often described as the business object classes because they are used to directly implement common business application concepts.
System properties are properties for which the CE server has some specifically-coded behavior. Some system properties are used to control server behavior, and others provide reports of some kind of system state. We've seen several examples already in the Domain and Object Store objects.
It's common for applications to create their own subclasses and custom properties as part of their installation procedures, but it is equally common to do similar things manually via FEM. FEM contains several wizards to make the process simpler for the administrator, but, behind the scenes, various pieces are always in play.
The foundation for any custom property is a property template. If you select the Property Templates node in the tree view, you will see a long list of existing property templates. Double-clicking on any item in the list will reveal that property template's properties. A property template is an independently persistable object, so it has its own identity and security.
Most system properties do not have explicit property templates. Their characteristics come about from a different mechanism internal to the CE server.
Property templates have that name because the characteristics they define act as a pattern for properties added to classes, where the property is embodied in a property definition for a particular class. Some of the property template properties can be overridden in a property definition, but some cannot. For example, the basic data type and cardinality cannot be changed once a property template is created. On the other hand, things like settability and a value being required can be modified in the property definition.
When creating a new property with no existing property template, you can either create the property template independently, ahead of time, or you can follow the FEM wizard steps for adding a property to a class. FEM will prompt you with additional panels if you need to create a property template for the property being added.
Most property types allow for a few simple validity checks to be enforced by the CE server. For example, an integer-valued property has an optional minimum and maximum value based on its intended use (in addition to the expected absolute constraints imposed by the integer data type). For some use cases, it is desirable to limit the allowed values to a specific list of items. The mechanism for that in the CE server is the choice list, and it's available for stringvalued and integer-valued properties.
If you select the Choice Lists node in the FEM tree view, you will see a list of existing top-level choice lists. The example choice lists in the screenshot below all happen to come from AddOns installed in the Object Store. Double-clicking on any item in the list will reveal that choice list's properties. A choice list is an independently persistable object, so it has its own identity and security.
We've mentioned independent objects a couple of times, and more mentions are coming. For now, it is enough to think of them as objects that can be stored or retrieved in their own right. Most independent objects have their own access security. Contrast independent objects with dependent objects that only exist within the context of some independent object.
A choice list is a collection of choice objects, although a choice list may be nested hiearchically. That is, at any position in a choice list there can be another choice list rather than a simple choice. A choice object consists of a localizable display name and a choice value (a string or an integer, depending on the type of choice list). Nested choice lists can only be referenced within some top-level choice list.
Within the FEM tree view are two nodes describing classes: Document Class and Other Classes. Documents are listed separately only for user convenience (since Document subclasses occur most frequently). You can think of these two nodes as one big list. In any case, expanding the node in the tree reveals hierarchically nested subclasses. Selecting a class from the tree reveals any subclasses and any custom properties. The screenshot shows the custom class EntryTemplate, which comes from a Workplace AddOn. You can see that it has two subclasses, RecordsTemplate and WebContentTemplate, and four custom properties.
When we mention a specific class or property name, like EntryTemplate, we try to use the symbolic name, which has a restricted character set and never contains spaces. The FEM screenshots tend to show display names. Display names are localizable and can contain any Unicode character.
Although the subclassing mechanism in CM generally mimics the subclassing concept in modern object-oriented programming languages, it does have some differences.
- You can add custom properties to an existing class, including many system classes.
- Although you can change some characteristics of properties on a subclass, there are restrictions on what you can do. For example, a particular string property on a subclass must have a maximum length equal to or less than that property's maximum length on the superclass.
eBook Price: $38.99
Book Price: $64.99
|Read more about this book|
(For more resources on this subject, see here.)
The right-click context menu for individual classes in the tree-view has selections to launch wizards for creating a new subclass (New Class) and for adding properties to the given class (Add Properties to Class). We'll finish up this section with a quick example of creating a new Document subclass called WjcWorkOfLiterature with a small number of custom properties. This class is used in the article on End User Tools and Tasks.
Right-click the Document Class node in the FEM tree view and select New Class. The Create a Class Wizard is launched.
The first panel asks for the Name (which actually means the display name) and the Symbolic Name. As you type the display name, FEM automatically constructs a default symbolic name by removing spaces and other unacceptable characters. You can modify the symbolic name to something else; we added the prefix Wjc because symbolic names must be unique, and using a short prefix reduces the chances of collision with something else. The description is optional, but you can supply whatever descriptive text you'd like.
The next panel shows the inherited properties on the class and invites you to add more. Since we have not previously created the property templates, click the New button to launch the Create a Property Template wizard.
As in the class wizard, the first panel asks for names and a description. Enter the same values shown in the screenshot for the WjcFormat property and click the Next button. We'll use a choice list for this property, so select that option and click the New button to launch the Create a Choice List wizard.
Choice lists don't have a symbolic name, but the display name is required to be unique. We called the choice list Literature Formats. What really matters here for referential integrity is the Id of the choice list, but FEM is automatically creating the necessary linkages and doesn't bother us with it. Click the Next button and select String as the Choice List Data Type. Click Next again to be brought to the Add Choice List Elements panel.
If we were making a hierarchical choice list, we'd use the New Groups button. We're making only a simple list, so click the New Items button.
Use the Add Item panel to add the three values shown. An application using a choice list will usually show the Name to the user, but the Value will actually be used as the property value. When you have completed the Create a Choice List wizard, you will be returned to the Create a Property wizard already in progress.
Select Single (this is the property cardinality) and click the More button to define additional characteristics of the WjcFormat property.
The most important things to notice in this panel are that we have selected the Value Required checkbox, that we have made the property Read/Write, and that we have specified a Maximum String Length of 10 characters.
When you have completed the Create a Property wizard, you will be returned to the Create a Class Wizard already in progress at the Select Properties panel. Before moving on, let's create three more new properties which will show up in some examples in the article on End User Tools and Tasks.
- Genre (WjcGenre), a multi-valued string property (unique and unordered). It should have Value Required, be Read/Write, and have a Maximum String Length of 25. Use a choice list called Literature Genre with values Drama, Comedy, Farce, Science Fiction, Western, Romance, Sonnet, Epic, Unknown, and History.
- AuthorLastName (WjcAuthorLastName), a simple string property. It should have Value Required, be Read/Write, and have a Maximum String Length of 64. It does not have a choice list.
- AuthorFullName (WjcAuthorFullName), a simple string property. It should not have Value Required, be Read/Write, and have a Maximum String Length of 64. It does not have a choice list.
Your Create a Class Wizard should look like this:
Finally, the last panel of the Create a Class Wizard will show a summary of the things you defined along the way. Click the Finish button to create the class.
Although the final step in the Create a Class Wizard will still let you cancel the creation of the class, any property templates and choice lists you created along the way will already have been created in the Object Store. If you wish to completely undo your work, you will have to delete them manually.
Object Browse and Query
The highest level folder in an Object Store is called the root folder, and its path name is simply /. It is represented by the Root Folder node in the FEM tree view. Every folder and every contained document or custom object appears somewhere hierarchically under the root folder.
FEM contains another node called Unfiled Documents. FEM goes to a lot of trouble to make this look like a folder in the user interface. It is not, although it is common to hear people experienced with CM call it "the unfiled documents folder". If you select that "folder", FEM issues a query to find documents which do not appear in any actual folder.
We'll have more to say about browsing and navigating in the next article on End User Tools and Tasks where we'll illustrate it using XT.
For now, we'll just point out the query interface in FEM. If you right-click on an Object Store and select Search from the context menu, you'll see a dialog box that lets you define a query step by step.
We won't go through the details of this dialog box because it's more about FEM user interface than about CM. It is worth noting that you can do queries against the CE server using a SQL-like query language. In fact, we call it CE SQL; it is a SQL-92 variant. Using these queries is very common in applications, and you can do it manually from this dialog box in FEM. Behind the scenes, FEM is composing a CE SQL query.
Another mode for that dialog will let you simply paste in a query that you have constructed on your own. From the Content Engine Query Builder, select View > SQL View.
The resulting view is prepopulated with a rather elaborate CE SQL query string. You can delete that and type or paste in your own query string.
When you click OK, the query will be executed and FEM will display the results. There is also an option to save a local copy of a query so that you can load and re-execute it later. (This feature is unrelated to the Workplace and XT feature called Stored Search.)
A historical quirk of the FEM query interface is that the SELECT list must begin with the This property. That is not a general requirement of CE SQL.
In this article, we took a brief tour of some common administrative features of CM. Most people experience these through the FEM tool. However, everything FEM does is done through the CE APIs, so it is also possible to write custom applications which do some or all of these things.
- IBM FileNet P8 Content Manager: Administrative Tools and Tasks [Article]
- IBM FileNet P8 Content Manager: End User Tools and Tasks [Articles]
- 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]
eBook Price: $38.99
Book Price: $64.99
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.