Using a path-based URL to open a document

You can use a path-based URL in an HTML document to retrieve content from a CS library. Web content authors can use path-based URLs to link HTML documents together in a CS library to create a web site. This simplifies the process of creating, publishing, and distributing HTML documents and entire web sites stored in a CS library. Before this will work, the FileNet Web Services administrator must first set the preference "Enable Path-based URL retrieval" to Yes. If set to No, its default, FileNet Web Services uses ID-based document retrieval.

A path-based URL can specify either a relative path or an absolute path.

Comparing path-based retrieval with ID-based retrieval

Path-based retrieval

Multiple HTML pages that compose a web site are commonly stored in a single folder or a hierarchy of folders, where links to other HTML pages within the site are specified as relative URLs.

Say for example, that home.htm is located in WebServer/idmws/doccontent.DLL/CSlibraryname^servername/folder1/home.htm, has links to three documents (doc1.htm, doc2.htm, and image5.gif), and that all of these documents reside in the same CS library.

Instead of specifying the entire path (absolute path), the three document links in home.htm can be expressed as relative links:

./doc1.htm
./doc2.htm
./images/image5.gif

By using relative URLs, the web site is location independent, and therefore, portable. It can be moved anywhere in the folder hierarchy of a web server, and the links will still work because they are relative to the web site's home page location rather than absolute paths. These links can be specified during authoring, before the web site's html pages have been checked into the CS library and assigned a document ID.

ID-based retrieval

The alternative to path-based document retrieval is ID-based document retrieval. With ID-based retrieval, you must specify the document's absolute path and document ID.

By using ID-based URLs, all links would be nothing more than placeholders until each html document is checked in and has received a document ID. The links would have to be changed to the actual document IDs that were assigned during checkin. Also, if you were to move the web site to another library, all links would be rendered invalid.

Using the example web site above, where the document ID for doc1.htm is 000001, doc2.htm is 000002, and image5 is 111115, then the links would look like this:

http://WebServer/idmws/doccontent.DLL/CSlibrary^server/folder1/000001
http://WebServer/idmws/doccontent.DLL/CSlibrary^server/folder1/000002
http://WebServer/idmws/doccontent.DLL/CSlibrary^server/folder1/images/111115

Path-based URL syntax

The following are examples of valid syntax for retrieving a document using a path-based URL. An ID-based URL is included here for reference.

URL

Example

Notes

ID-based

http://<server name>/idmws/doccontent.DLL/ <library>^<server>/<folder path>/<document ID>

Shown here for reference. Must specify the document ID.

Path-based

/idmws/doccontent.dll/<library>^<server>/<folder path>/<original filename>

Relative path.

./<folder path>/<original filename>

Relative path.

../<folder path>/<original filename>

Relative path.

/pburl_idmws/<library^server>/<folder path>/<original filename>

Absolute path only.

pburl_idmws automatically expands into "/idmws/doccontent.DLL" when the link is submitted to FileNet Web Services for retrieval.

http://<server name>/idmws/doccontent.DLL/ <library>^<server>/<folder path>/<original filename>

Similar to ID-based, but no document ID required.

where:

library^server is the two-part identifier of the CS library. Library is the name of the CS library where the document is stored. Server is the system name.

idmws is the name of the application used to retrieve the document, named "idmws" by default.

folder path is the path to and name of the folder in which the document is stored.

original filename is the name of the document when it was checked in to a CS library. If the document has been renamed since, specify its original filename instead.

A document stored in multiple folders

If the path-based URL retrieval preference is set to Yes, FileNet Web Services will automatically convert an ID-based URL to a path-based URL whenever the user opens, views, or checks out a document using an ID-based URL. When a document has more than one path because it is filed in more than one folder, where each folder has a unique name, FileNet Web Services will use the first path it  finds, and use that for the path-based URL.   

In cases where two folders are named identically, and the requested document is stored in each folder, an attempt to retrieve such a document via a path-based URL will return the error "object not found".

We recommend that you do not use path-based URLs to call a document stored in multiple folders,  a document stored in identically named folders, or a document stored in multiple folders.