18.4 General Rules for Using a WebDAV Client

Oracle Portal supports a number of WebDAV client actions. Since not all WebDAV clients behave the same way, only a subset of these actions may be allowed for a particular client. For example, you can check items in and out through WebDAV if the WebDAV client supports the WebDAV LOCK method. (Web Folders does not currently support locking operations. Office 2000 clients support implicit locking operations. Cadaver and Dreamweaver support explicit locking operations.)

Performing actions on your portal through WebDAV clients has the same effect as performing them in the portal itself. If you make a change to your portal from a WebDAV client, it is instantly visible in Oracle Portal, provided the change is not subject to an approval process. You may need to refresh the portal page through your browser to see your changes.

This section describes the actions you can perform on Oracle Portal through a WebDAV client. It includes the following subsections:

18.4.1 Listing Portal Content in a WebDAV Client

Once you are connected to Oracle Portal through WebDAV, all the page groups you have the privilege to see are visible as folders on your local machine's file system. The top-level folders represent the root pages of your portal's page groups.

To see a page group, you must have sufficient portal privileges to view the page group's root page. Additionally, if you have a personal page in the Shared Objects page group, you should see the Shared Objects page group and be able to access your personal page through the WebDAV client.

Only Standard pages are exposed in WebDAV. No other page types are listed, nor are custom pages that are based on the Standard page, type.

When you open a page group folder, you see a list of the next level of sub-pages inside the page group. These display as sub-folders. Similarly, when you open a sub-page folder, you see a list of the sub-page's sub-pages and all items (and sub-items) of the following types:

Referenced image items do not display in the WebDAV list of pages and items. Referenced image items are those images you add by referring to the image's internal name, such as 1614.gif. Items with a status of Pending or Draft display to their approvers as 0 KB files.

To see items in a WebDAV client, you must have at least the page privilege View on the page where the item is placed. You will see the current version of the item in the page group's default language only (that is, the language in which the page group was created). Translations of items are not visible in WebDAV clients.

You see only the primary file associated with each item or sub-item. Any other files (that is, secondary files or images) associated with the item (for example, an item's representative image or icon), do not display in the WebDAV client. If you want to delete or change these files, you must do so in Oracle Portal.

In WebDAV clients, no distinction is made between items and sub-items.

Most unpublished items (that is, expired items, hidden items, and items with a future publish date) are visible in WebDAV clients only to users with at least the page privilege Manage Content on the page that contains the item, and only when the page group setting Display Unpublished Items In Edit Mode is enabled. Expired items display in the WebDAV client until they are permanently removed (that is, purged) from the database. Items marked for deletion do not display in WebDAV clients, even when the marked items display in one of the portal's Edit mode views.

Whether an item is visible through WebDAV is also influenced by what state the item is in, such as Pending, Draft, and so on. For information on which items are accessible in what states, see Section 17.9.3, "Item URL Security".

Oracle Portal is case-sensitive for folder and file-based item names (for example, aaa.htm and AAA.htm are treated as different items). If your WebDAV client is not case-sensitive (as is the case with Web Folders), aaa.htm or AAA.htm may not be accessible, or the client may confuse one for the other. Therefore, when using such clients, do not use a naming convention that relies on case.

Renaming a file with a WebDAV client affects the Display Name of the corresponding item only if the Display Name was previously the same (including the same case) as the file Name. For example, if, in the Oracle Portal user interface, the item's Name is sample.txt, and its Display Name is also sample.txt, when you rename this file through a WebDAV client to realfile.txt, both the Name and Display Name are updated to realfile.txt. Conversely, if the item's Name is sample.txt and its Display Name is Benefits Information, when you rename this file through a WebDAV client to benefits.txt, only the Name is updated in the portal; the Display Name continues to read Benefits Information. This holds true if the Name and Display Name are in different cases. For example, if the Name is sample.txt and the Display Name is Sample.txt, when you change the Name to benefits.txt in a WebDAV client, the Display Name remains Sample.txt.

Templates, regions, and tabs are not currently represented in Web folders. This means that when you look at a portal page through a Web folder, you can see the portal page's items and sub-pages, but you cannot see any objects representing a region, a tab, or a template. Further, any items and portlets that are part of a template or that are placed in a tab region are not represented. For this reason, avoid using tabs on pages that are intended for use with WebDAV clients.

Note, however, that if a template is detached from a page, any items from the template are copied to the page itself and therefore become visible in your WebDAV client.

18.4.2 Viewing Content Through a WebDAV Client

Most WebDAV clients allow you to view the content of an item by clicking its file name. In Windows 2000 or NT, the behavior is very similar to clicking a file on the local machine: the operating system opens it in the application associated with the file type.

If you are using a Microsoft Office application to browse portal content, be aware that when you open a file, that file is locked in the WebDAV client and checked out in the portal. Therefore other users will not be able to edit the file until you have closed it. When you close the file, it is unlocked and checked back in. If versioning is enabled, a new version is created.

Some desktop applications may have difficulty opening files that use special characters in the file name. To avoid such problems, consider limiting the names to alphanumeric characters (A to Z, a to z, 0 to 9), spaces, and underscore (_).

18.4.3 Moving, Copying, and Editing Content Through WebDAV

To move, copy, or edit files, you must have at least the page privilege Manage Content (or Manage Items With Approval if approvals are enabled).

With WebDAV-enabled desktop applications, such as Microsoft Office 2000, you can open a file, edit it directly, and then save it to the same location, using the same name. With other applications, you can save the file to the local file system and drag and drop the new file to Oracle Portal. The next time the file is opened from Oracle Portal, the edited version is displayed.

When a file is moved or copied, the entire item associated with that file is moved or copied, including associated files (for example, the item's icon) and any sub-items. But note that if a sub-item is copied, the copy is created as a top-level item.

When you select multiple files for moving, and these include items and sub-items, you may encounter error messages, and all the files may not be moved. This is because, in a multiple move, the WebDAV client will attempt to move each item in turn. If the parent item is moved first, all of its sub-items are moved with it. Then the client attempts to move the sub-items (one at a time). Because they no longer exist in the source folder, an error message is displayed. Similarly, if the sub-item is moved first, when the client attempts to move the parent item, it displays an error message because it cannot find the parent's associated sub-item.

When you drag a file from one folder to another within Web Folders, and the file already exists in the target folder, then the file being moved will replace the existing file in the target folder. Within your portal, this means the dragged item replaces the existing item on the target page. This will happen irrespective of any versioning setting on that page. That is, even if item versioning is enabled in your portal, all versions will be replaced. To preserve versioning in WebDAV, copy (rather than drag) the file to your local system, then copy it from there to the target folder.

Note:

You cannot use a WebDAV client to add an item that has the same name as an item of the status Pending. This is because it is seen as trying to edit the pending item. You can use the portal user interface to add an item that has the same name as a pending item. This is because it is seen as adding a different item. The new item is created with a unique Name.

18.4.4 How WebDAV Handles Item Types and Attributes

Your page designer can specify what item types to use for new files published to Oracle Portal through WebDAV. For example, the page designer might want any Zip files published to Oracle Portal to be uploaded as Zip File item types, so that their content can be extracted into the page group.

If the default item type specified for files uploaded through WebDAV includes the Category attribute, new items added through WebDAV clients are assigned to the General category. See Section 18.2, "Setting Up Oracle Portal for WebDAV" for more information.

When you edit or move an existing item using WebDAV, that item retains its original item type and attribute values. Similarly, when you copy an item using WebDAV, the copy uses the item type and attribute values of the original item.

With most WebDAV clients, you cannot edit an item's attributes in Oracle Portal's WebDAV server. To edit attribute values, you must edit the item in Oracle Portal. One exception is Oracle Drive. Oracle Drive provides a right-click menu option, Set Properties, that provides access to the Edit Item screen where you can edit item attribute values. For more information about Oracle Drive, see Section 18.5, "Using Oracle Drive as a WebDAV Client".

Renaming a file with a WebDAV client affects the Display Name of the corresponding item, only when the Display Name was previously the same (including the same case) as the file Name. For example, if the item's Name is sample.txt and its Display Name is also sample.txt, when you rename this file through a WebDAV client to realfile.txt, both the Name and Display Name are updated to realfile.txt.

Conversely, if the item's Name is sample.txt and its Display Name is Benefits Information, when you rename this file through a WebDAV client to benefits.txt, only the Name is changed. The Display Name continues to be Benefits Information.

This holds true if the Name and Display Name are in different cases. For example, if the Name is sample.txt and the Display Name is Sample.txt, when you change the Name to benefits.txt in a WebDAV client, the Display Name remains Sample.txt.

18.4.5 Versioning Support in WebDAV

Oracle Portal's WebDAV server supports a slightly varied model of the Simple and Audit versioning available in the main portal application. For example, when Audit versioning is enabled, all versions are retained as specified, but you cannot see or select a different version to display through a Web folder.

If your page is set up to use Audit Versioning and you use a WebDAV client to edit an item on the page, a new version of the item is created. The new version is always set to the current version. WebDAV folders always display the current item version. If you do not want the new version to be the current version, you must log in to Oracle Portal, and edit the item's version setting.

If Simple Versioning is enabled on a page and you edit an item on that page through a WebDAV client, a new version of the item is created and set to the current version. When you edit items through a WebDAV client, you cannot choose the overwrite versioning option. If you want your versioning model to remove the previous version when you save the file, you must edit the item then upload it through Oracle Portal, rather than through a WebDAV client.

In some clients, for example, Windows 2000, the message you receive when you add a new version of an item may imply that you are overwriting the file rather than adding a new version. This is a limitation of the client's messaging. When Simple or Audit versioning is enabled for a page, saving a file to your portal through the WebDAV client always creates a new version.

When you drag a file from one folder to another within Web Folders, and the file already exists in the target folder, then the file being moved will replace the existing file in the target folder. Within your portal, this means the dragged item replaces the existing item on the target page. This will happen irrespective of any versioning setting on that page. That is, even if item versioning is enabled in your portal, all versions will be replaced. In this scenario, to preserve versioning in WebDAV, copy (rather than drag) the file from the first WebDAV folder to your local system, then copy it from your local system to the target WebDAV folder.

18.4.6 Approvals and Drafts Support in WebDAV

Oracle Portal's WebDAV server also supports approvals and Drafts. With approvals enabled, when you add an item to a page using a WebDAV client, the approval process that was defined for the page or page group is triggered. The content of the item does not display to other users until it has been approved. Users, including approvers, may be able to see the item listed (as a zero-byte file) in the WebDAV client, but they will not be able to see the actual content of the pending item until it has been approved. The item cannot be updated in the WebDAV client until it has been approved or rejected.

How a pending item displays in a WebDAV client depends on whether the item is a new item or an edited item. If the item is a new item, in a pending state it displays in WebDAV as a zero-byte file. If the item is a revision of an existing item, the older-unedited version of the item displays in the WebDAV client until the revised version is approved.

If approvals are enabled, when a user updates an item using a WebDAV client, other users, including approvers, continue to see the non-updated item until such time as the update is approved. Conversely, the user who updated the item sees the updated item in its WebDAV folder, even before it is approved.

This works a little differently when the file is updated through the Oracle Portal user interface. In such a case, all users (including the user who updated the item) will see the non-updated item in WebDAV clients until the updated item is approved.

The point at which the approval process is triggered depends upon the WebDAV client being used. For example, in Microsoft Word, when a file is opened it is automatically locked. The approval process will not be triggered until the file is unlocked (that is, when the file is closed). Therefore, simply saving the file does not trigger the approval process. You must perform the action that causes the client to unlock the file (such as, closing it) to trigger the approval process.

18.4.7 Deleting Content Through WebDAV

When you delete a file in a WebDAV client, the whole item associated with that file is deleted from Oracle Portal. This means that any other files that are associated with the item (for example, the item's representative image) are also deleted, as well as all sub-items, versions, and translations of the item. When you delete an item using a WebDAV client, the item is permanently deleted even if the page group is set to retain and display deleted items.

When you mark an item for deletion in Oracle Portal but it is not yet deleted from the database, the item is nonetheless no longer visible in WebDAV clients.

18.4.8 Checking Content Out and In through WebDAV

If the WebDAV client supports locking and unlocking (as do Dreamweaver and Microsoft Office 2000), you can lock a file, which in turn will check out the portal item associated with the file (the Oracle Portal equivalent of the WebDAV LOCK method).

Some clients (for example Microsoft Office) implicitly lock files when you open them. Other clients (for example, Dreamweaver) require explicit (manual) file locking if you want to prevent other users from making changes to files while you work on them.

Once a file is locked from a WebDAV client, no one else can make changes to it until it is checked back in by the same WebDAV client. Even the user who locked the item cannot make changes to the file using a different WebDAV client or the portal itself. The unlock token is owned by the client that locked the file, so the file must be unlocked by the same WebDAV client (on the same machine) that locked the file.

Note:

Some clients, for example, Cadaver, provide the ability to explicitly or implicitly steal a lock token and unlock a file that has been locked by another user or client. We strongly advise users never to steal locks. It can lead to confusing behavior in the locked files, particularly when users steal locks created by other users.

Locking is useful for more than preventing the overwrite of an active file. For example, you can use it to reserve a particular file name by locking a non-existent file. When you do this, a file with the specified file name is created and locked. This prevents other users from creating a file with the same name. You must remember, however, to unlock this file when you are ready to let other users work on it.

After you have made the required changes to the file, you can unlock it, which in turn checks in the portal item associated to the file (the Oracle Portal equivalent of the WebDAV UNLOCK method). Other users are then able to make their own changes to the file.

Here are some additional tips for checking content out and in through WebDAV:

You cannot check folders in or out, or recursively check out the content of a folder.

You cannot move, copy, or delete a page if a WebDAV-supported item in that page, or in one of the page's sub-pages, is locked through another WebDAV client or by another user. WebDAV supported items include files, Zip files, images, and custom item types that are based on these item types.

If you lock a file with an associated sub-item, other users can use a WebDAV client to delete the parent item (and thus the sub-item) even though they do not own the unlock token for the sub-item. This is because WebDAV clients do not support the Oracle Portal item hierarchy.

If you check an item out in Oracle Portal, you cannot update the item in a WebDAV client. This is because Oracle Portal uses a different locking model from WebDAV. Oracle Portal locks items based on user names, whereas WebDAV locks resources based on specific lock-keys. When you check an item out in Oracle Portal, it is locked in the WebDAV domain with a specific key. Only Oracle Portal (not the individual user) has the key to unlock the item. Even the user who checked the item out must check the item in again before he or she can operate on it using a WebDAV client.

For example, when Scott checks out File1 in Oracle Portal, the portal keeps a record that Scott has checked out File1.The Oracle Portal WebDAV server locks File1 and holds the related lock token. Scott can log on to Oracle Portal using any Web browser and check File1 back in, but he cannot use a WebDAV client to unlock the item because the Oracle Portal WebDAV server (not Scott's WebDAV client) has the lock token.

Items can be locked through a WebDAV client even though item check-out is not enabled for the item in the portal user interface. This is because some WebDAV clients, such as Microsoft Word, automatically lock an item once it has been opened for editing within the client. When the client is closed, it automatically unlocks the item. If such locking was prevented because the Enable Item Check-Out option was not selected, Oracle Portal would not properly support WebDAV file locking standards. Consequently, the portal ignores its own item check-out property setting when an item is locked through a WebDAV client.

18.4.9 Creating Oracle Portal Pages and Sub-Pages Through WebDAV

Using a WebDAV client, you can create and delete pages within existing page groups, provided you have the appropriate privileges. For example, to create a sub-page in Web Folders, right click inside the folder in which to create the sub-page and choose New then Folder. All the pages you create using WebDAV clients are Standard pages and contain an item region.

Here are some additional tips on creating pages and sub-pages through a WebDAV client:

Page names can contain any character except the following:

, & # % \ / : * ? < > | "

Consequently, to paste a folder from the file system into Oracle Portal, it and all sub-folders that it contains must be named according to these parameters.

Although you can create pages through WebDAV, you cannot create, edit, or delete page groups through WebDAV. These actions must be performed in the portal.

You cannot create tabs through WebDAV.

18.4.10 Viewing WebDAV Errors

When performing actions using WebDAV clients, you may encounter error messages that do not seem to be appropriate for the action. For example, in Web Folders when you create a new version of an item you may get an error message that implies the item will be overwritten rather than a new version created. Also in Web Folders, when you move an item you may get an error message asking you to verify that you want to delete the file. This is due to the underlying behavior of the client. It does not affect the actual action that is being performed.

Any errors that occur while you are using a WebDAV client with Oracle Portal are recorded in an error log. The error log is created the first time an Oracle Portal related WebDAV error occurs. It is placed on your personal page as an item titled My Error Log. This can be helpful with interpreting the error messages reported in WebDAV clients, such as the message "An error has occurred while trying to complete this operation" that is often displayed in Web Folders, or HTTP error numbers reported in Cadaver.

Note:

The error log is truncated after 32K.

All errors are also recorded in the Oracle HTTP Server error log file, so if you do not have a personal page, or are a public user, the errors can still be examined by the portal administrator.

For more verbose error reporting in the Oracle HTTP Server error log file (ORACLE_HOME/diagnostics/logs/OHS/ohs1/error_log), ask your administrator to add the following parameter to theoradav.conf file:

DAVParam ORATraceLevel 1

Additionally, the following parameter will log more information in the Oracle HTTP Server error log file about WebDAV usage, such as the user, operation, and client:

18.4.11 Authentication and WebDAV

With some WebDAV clients, you might experience multiple authentication requests. To avoid this, your portal administrator can enable the cookie option by adding the following line to theoradav.conf file:

Some WebDAV clients, for example, Dreamweaver, do not support cookies, so even if the cookie option is enabled, you may still be prompted for your password multiple times. In some of the clients that do not support cookies, you may be able to save your user name and password, preventing the need to enter the information each time you are prompted. Note, however, this may cause performance issues with large volume transactions.

Scripting on this page enhances content navigation, but does not change the content in any way.