Content Model Access Builder

 

The Content Model Access builder allows you to create Web applications that operate on data in WebSphere Portal's Content Model. The builder allows you to specify the type of data to operate on, for example, documents, folders or libraries. Create, retrieve, update, and delete operations are supported.

This builder requires WebSphere Portal V6.0 or later. You should be familiar with the Content Model in WebSphere Portal. Familiarity with the Java Content Repository (JCR) and Service Data Objects (SDO) is also recommended.

The Content Model Access builder allows you to select the Content Model data to work with by specifying a document type and search criteria. We can customize the search criteria used to retrieve data, including the JCR search paths, the search string, data type properties to search on, and the number of results. By default, the search criteria is retrieved from the builder_nameSearchCriteria variable at runtime. This allows you to present a form for users to specify their own search criteria. As an alternative, we can preset the search criteria values in the builder's Search Criteria section.

The builder also allows you to control how the binary data of a document is handled at runtime. This builder acts against the Content Model running on the portal server configured in your project's deployment information. You must have a deployment configuration configured for your project and the project must be initially deployed when using this builder. This allows the builder editor to retrieve metadata (for example, document types or properties) from the Content Model using an internal support model that is deployed with the project.

 

How do I...

Use this builder to create an application that mimics a hierarchical file system?

For instance, given a path to a Document Library, you could use this builder to display the folders. When the user selects a folder, the folder's contents are displayed. A sample model demonstrating this is included with WebSphere Portlet Factory. See the ContentRepositoryExplorer sample model.

Use this builder to stream the binary contents of a document to the browser?

For instance, on a details page that displays the data of the document, you could add a Download Content link which downloads the content to the browser and automatically launches the application registered with the MIME type of the document.

For an example of how to stream the document content back to the browser, see the sample ContentRepositoryExplorer.model.

Use this builder to upload a file to the Content Model?

There are two methods we can use to manipulate the binary data stored in the data property in documents stored in the Content Model.

  • Method 1: Use the file upload builder

    The file upload builder allows the user to copy a file from the client to a configurable directory on the server hosting the web application. The Content Model Access builder then uses the uploaded file as the value for the data property on the document to be saved in the Content Model.

    Follow these steps to enable your application to upload files from the client.

    1. Create a page in your model.
    2. Create a tag on this page where you want the file upload builder to be located.
    3. Add a file upload builder to your model. The builder inputs require you to select the page tag where the builder should be located. We can optionally select a subfolder of the upload directory where the file will be saved.
    4. Add a Content Model Access builder to your model (or edit an existing one). For the File Upload Tag input, use the same tag name you chose in the file upload builder inputs.

    At runtime, the Content Model Access builder checks the request inputs for a key/value pair set by the file upload builder that specifies the file system location of the uploaded file. If found, the file is converted to a Content Model API DataStream object and set as the data property on the document to be saved.

    Notes:

    • The uploaded files are not deleted from the file system hosting the web application. You may want to implement a strategy for periodically deleting these files.
    • To prevent multiple people simultaneously uploading a file with the same file name, you should implement code to generate a unique file name for the uploaded file.
    • Be sure to enable the file upload builder in override.properties. See the help for the file upload builder for more details.

  • Method 2: Embedded XML

    If the File Upload Tag field was not set in the Content Model Access builder, the data embedded in the data field of the XML will be used as the new value of the data property.

 

Specifying inputs

This builder takes the inputs described in the table below. For help on inputs common to many or all builders such as those in the Properties and HTML Attributes input groups, see Using the Builder Call Editor.

Input name Description
Name Enter a name for this builder call. The designer tool displays this name in the builder call list.
Document Type Selection
Search for Document Types When this button is pressed, the Document Type field is populated with document types and document containers registered with the Content Model. Examples of document containers include Folder and DocumentLibrary. Examples of document types include Document and CollaborativeDocument. By default, the button queries the Content Model for all types that descend from Document and Folder. If the Document Type field contains no data after pressing this button, or if you receive an error, here are some things to check:

  • Ensure you have a Deployment Configuration configured for your project. You must have a Deployment Configuration to WebSphere Portal 6 or later.

  • Ensure that your project has been deployed.

  • Check for mistakes in your deployment information for your Portlet Factory Project. For example, check the server name and port.

  • Ensure the portal server is running and that we can log into the portal manually.

  • If you have just restarted the portal server: Try loading the main login page of WebSphere Portal. Content Model service calls may not be initialized until the login page has been requested at least once after the server has been restarted.

Document Type After pressing the "Search for Document Types" button, use this picklist field to select a document type or document container type to work with. For example, choosing CollaborativeDocument allows you to query and operate only on documents of type CollaborativeDocument.
Enable Schema Caching A schema is created during model regeneration that is specific to the content type selected in the Document Type field. This is done by querying the Content Model for a type's properties. If the metadata of this content type is static, then we can enable schema caching to improve regeneration performance for the builder.
Search Criteria
This section allows you refine what data will be retrieved from the Content Model. By default, search criteria values are entered by the user at runtime and retrieved from a variable. However, we can use this section to override all or some of the search criteria.
Search Paths The Content Model and underlying JCR implementation can be thought of as a tree structure. All document containers and documents in the Content Model are addressable by a path. This field allows you to limit the scope of the documents you want to work with to only certain paths in the tree.

For example, if you wanted to search only the default document library that is installed with WebSphere Portal 6, enter /contentRoot/icm:libraries.

If we need to find the paths to all Document Libraries, run the sample model FindAllDocLibs.model.

Search Depth There are two choices available for this field.

  • Search only direct children of a path causes the Content Model to return only the children of the given path. For example, documents in subfolders of a document library are not returned.
  • Search all descendants of a path causes the direct children and all descendants will be returned. For example, documents in subfolders of a document library are also returned.

Search Type Choose one of the following options

Match All Documents

Finds all documents in the specified paths that match the value in Document Type field.

Perform a web-style text search

Enables two additional fields, Search String and Search Property. Web-style allows you to enter a search string for the "Search String" field. The search string can be combined with the following symbols:

  • +   (plus character). The results must contain the term. For example, search results for +foo must contain the term foo.

  • -   (minus character). The results must not contain the term. For example, -foo search results must not contain the term "foo".

  • ^   (caret character). The results must contain the term, but are not sufficient by itself. For example, ^foo search results must contain the term "foo" but not only the term "foo".

  • ""   (double quotes surrounding the term). The results must contain the term within the double quotes. For example, "WebSphere Portal".

For example, the following query means the results must contain spain, must not contain italy, and must contain france, but not only france.

+spain -italy ^france

This choice also allows you optionally limit the search to a single document property. For example, if your Search Type is CollaborativeDocument, you could select the "title" property. This would limit the search to just the title field of CollaborativeDocuments. If you do not enter a value for Search Property, all fields will be searched.

Note that "Search Property" is required for SQL-style search, described below.

Perform a SQL-style text search

Enables two additional fields, Search String and Search Property. This choice allows you to use SQL syntax for the search string in the Search String field.

When using the SQL-style search, the Search Property field is required. The Content Model does not allow you to perform an SQL query across all properties. If you do not enter a search property, you will receive an error when you run the application.

The Content Model supports the % wild card for SQL-style searches. The following are examples of the query syntax:

  • apple - Property selected exactly matches apple
  • %apple% - Property contains apple
  • apple% - Property starts with apple
  • %apple - Property ends with apple

Note that The search term is matched exactly as specified. The search string must be in the format of the underlying content repository. This may mean dates, users, or other types might need to be converted to the proper format before calling.

Refresh Search Properties If Web-Style or SQL-Style was selected for Search Type, this button will query the Content Model for all properties of the type selected in the Document Type field and automatically populate the Search Property picklist field. This allows you to choose a property from the picklist that you want to search on.
Search Property This field is available when Web-style or SQL-style is selected in the Search Type field. After clicking the Refresh Search Properties button (described above), this picklist field allows you to select a single property to search on. This field is optional for web-style searches; if no property is selected, all fields are searched. This field is required for SQL-style searches; if no property is selected, you will receive an error in your application. See the description for the Search Type field above for additional information.
Search String This field is available when Web-style or SQL-style is selected in the Search Type field. It allows you to specify a search string. The syntax for the search string depends on the choice you selected for the Search Type field. See the description for the Search Type field above for additional information.
Max Documents This field allows you to specify the maximum number of search results to retrieve from the Content Model.
Content Handling
Search Results Content Handling Typically search results contain only metadata about documents found from the query; binary data is not retrieved until the user selects a result. Similarly, this field allows you to omit the actual document content - an image, PDF file, etc. - from the search results by selecting Omit from XML.

If the binary content of the document contains data you wish to embed in the search results, such as HTML or XML, select Embed in XML. If you select Embed In XML, use the Character Set Selection field to specify the character set to use in decoding the content.

Select Custom (Fire A Decode Event) to delegate handling of the binary data to a custom method. This allows you to transform the data in a customized fashion.

Detail Content Handling Specify how to handle content when the document detail is retrieved. This input provides the same choices as Search Results Content Handling. If Embed in XML is chosen, use the Character Set Selection field to specify the character set to use in decoding the content.
File Upload Tag If you are using the File Upload Builder to upload a file, the value of this field should be the page tag name used for the File Upload Builder. See Use the file upload builder for more information.
Character Set Selection If Embed in XML is chosen for Search Results Content Handling or Detail Content Handling, use this field to specify the character set used in decoding the actual document content. Choose one of the following options.

  • Use the Mime type declared by the document

    Instructs the builder to get the character set information from the declared mime type of the document. The format expected is xxx/xxx charset=xxx. For example,

    text/plain charset=us-ascii

  • Use an explicit character set

    Selecting this choice enables an additional input field, Character Set for Decoding, which you should use to enter a specific character set, such as UTF-8.

Character Set for Decoding Indicate the character set used to decode content in the search results, for example, UTF-8 or US-ASCII. This field is enabled only if Use an explicit character set was chosen for Character Set Selection.
Advanced
Base Document Types Filters the document types available in the Document Type input to the useable Content Model types and their decendants. Since all document and document container types extend from Document and Folder, this input can generally be ignored and left to the default values.

 

Objects this builder creates

 

Linked Java objects

  • buildername

    Used for create, retrieve, update, delete, and search operations on the Content Model. Also provides methods for downloading the document content.

 

Methods

  • void updateDocument(WebAppAccess webAppAccess)

    Updates a document in the Content Model with data from the buildernameDetail variable.

  • void findDocuments(WebAppAccess webAppAccess)

    Searches the Content Model using the search criteria specified in buildernameSearchCriteria. Search results are stored in the buildernameSearchResults variable.

  • void getDocument (WebAppAccess webAppAccess)

    Retrieves a document from the Content Model using the buildernameGetCriteria variable. The retrieved document is stored in the buildernameDetail variable.

  • void createDocument(WebAppAccess webAppAccess)

    Creates a new document in the Content Model from the buildernameDetail variable. The folder id and containment property must be specified in the buildernameCreateCriteria variable.

  • void deleteDocumentById (WebAppAccess webAppAccess , String id)

    Deletes the document with the given id from the Content Model.

  • void deleteDocument(WebAppAccess webAppAccess)

    Deletes the document specified in the variable buildernameGetCriteria.

 

Schemas

  • buildernameSchema_XSD

    Represents the document type selected in the builder. Also contains XSD schema elements for search results, a search criteria, get criteria, and create criteria.

 

Variables

  • buildernameSearchResults

    Schema-typed variable that contains the search results that match the search criteria.

  • buildernameSearchCriteria

    Schema-typed variable to hold the search criteria. This includes the search paths, search string, names of properties to search on, the maximum number of documents to fetch, and whether or not to search subpaths.

  • buildernamePropertyLookupXmlData

    Holds the properties of a document type. Automatically populated.

  • buildernameDetail

    Schema-typed variable containing the detail of a document or document container. Used to display document details and collect new document inputs.

  • buildernameCreateCriteria

    Schema-typed variable that holds the parent id (folder) of the document to be created. Also contains the parent's collection property name that will hold the new document. For instance, a parent can be a Folder. The collection property of a Folder is "documents".

  • buildernameGetCriteria

    Schema-typed variable which holds the document id of a document or document container to be fetched from the Content Model.

  • CMSearchTypeXmlData

    Variable to hold the available search types that can be performed. Automatically populated.

 

Data services

The builder provides traditional create, retrieve, update, and delete operations on nodes in the Content Model. The services are described in the following table.

Service Description Input parameters Output parameters
findDocuments Find documents or document containers in the Content Model

criteria

Search criteria from the Search Criteria section in the Builder Call Editor.

results

Container to hold results from a search.
getDocument Retrieves a document or document container from the Content Model

criteria

Specifies the document id of the document to fetch.

document

Holds the detail of the document being requested.
createDocument Create a new document or document container in the Content Model

criteria

Parent id (Folder or DocumentLibrary) and the name of the parent collection property

document

Contains the data of the new document
deleteDocument Delete a document or document container in the Content Model

criteria

Unique document id for the document to delete (Variable: builder_nameGetCriteria)
updateDocument Update a document or document container in the Content Model

Note that The Content Model automatically manages some properties (See Special document properties in the Content Model section below). When metadata or document content has changed and updateDocument() has been called, be sure to call getDocument() again. This ensures the buildernameDetail variable is populated with the latest values stored in the repository.

document

Holds the updated data to be stored in the Content Model. (Variable: DocumentLibraryDetail)

 

Special document properties in the Content Model

The node properties in the table below are managed by either the Document Manager application, Content Model, or underlying JCR repository. Changes to these fields using the builder are ignored.

Property Description
id Unique identifier for each node in the JCR tree.
path Hierarchal path to the node in the tree
lastModified Date the node was last modified.
created Date the node was created.
creator Name of person who created the node
lastModifier Name of person who last modified the node
dataLength Size of the data stored in the data field of the node.
dataLastModified Last modified date of the data stored in the data field of the node.
Revision Revision level of the document.

 

The label property

The Content Model uses the label property as the file portion of the hierarchical file path in the Content Model. For example, if the label is status_report.doc, then the JCR path could be /documentRoot/icm:libraries/folder1/status_report.doc. Like a file system, this value must be unique.

The label property must be set to a unique value when creating a new Document or Folder in the Content Model. Therefore, when using the createDocument Data Service of this builder, it is up to the developer to set a unique value for label property. If this property is not set or if a path already exists at this location, you will receive a Content Model error and the new document or folder will not be created. We recommend implementing a field validation in your web app to ensure this field is set for new documents.

Once set, the Content Model does not allow you to change the label property, as it becomes part of the "path" property. Therefore, if you are using the updateDocument Data Service of this builder to update an existing Document, the builder will ignore changes to this field. We recommend that you hide this field (for instance, using a Data Column Modifier) in the update functionality of your web application.

 

The dataMimeType property

It is the responsibility of the application developer to set the dataMimeType field to the appropriate MIME type for the uploaded document.

 

The effectiveDate Property

This property is used by the Document Manager application. Document Manager displays CollaborativeDocuments where the effectiveDate is now or in the past; if the effectiveDate is set to a future date, the CollaborativeDocument will not show in Document Manager until that date. Also, if the effectiveDate is not set, the CollaborativeDocument will not show in Document Manager. Therefore, if you are using the builder to operate on CollaborativeDocuments, the developer should take special care to set this field appropriately.

 

The revision property

Documents of type CollaborativeDocument are used by Document Manger and other WebSphere Portal applications. CollaborativeDocument contains all the common properties of Document, but with additional application-specific properties used and managed by the Document Manager portlet and Manage Document Libraries portlet. One notable example is the CollaborativeDocument property, "revision", which is managed by Document Manager. The revision field is used by the Document Manager portlet to determine which rendition of the document to show.

To ensure that CollaborativeDocuments modified with this builder continue to work correctly in the Document Manager portlet, the builder updates CollaborativeDocument properties using the Content Model API's DMUtility methods. In addition to updating fields on the document, these methods automatically adjust the revision field of the CollaborativeDocument. Direct changes to the revision field using the builder are ignored.

For all other Documents and descendants, the builder simply updates properties at the SDO level.

 

Considerations for standalone Web applications with this builder

This section describes security considerations to keep in mind when developing an application with this builder.

As a background, most Content Model service calls require a LoginContext, an object which contains authentication information about a user. Given a java.security.Principal, the Content Model API LoginService will return a LoginContext for the user represented by this Principal.

The builder will attempt to get the Principal from the HttpServletRequest so that it can use the Principal to obtain the LoginContext from the LoginService. If the Principal in the HttpServletRequest is null, the builder will log into the Content Model anonymously. Since most Content Model content - documents, document libraries, and folders - have access requirements, you typically want to log into the Content Model as the user who is running the web application. The way to do this depends on whether you are developing a standalone application or a Portlet application.

Standalone

If you are developing a standalone application to be run in WebSphere Application Server where the Content Model is installed, but not as a portlet to be deployed to WebSphere Portal, then you will need to configure a J2EE security constraint for your application. This is so that when you run your model you'll be prompted to authenticate and the Principal will be set on the HttpServletRequest.

If you do not do this, you may receive security exceptions from the Content Model and underlying JCR because you are anonymous and the anonymous user may not have access to the content you are trying to work with.

Portlet

If you are developing a Portlet application to be run on WebSphere Portal, you simply need to add a Portlet Adapter to your model. Then, as with other portlet applications, log into WebSphere Portal and add your portlet to a page. Since users will have to be logged into Portal to run your Portlet, the Principal will automatically be set on the ServletRequest and the builder will use this Principal to obtain the LoginContext.

You do not have to configure a J2EE security constraint in this scenario.

 

Related information

Introducing the WebSphere Portal V6.0 Content API