9 Content Management API Introduction

9.2.1 Secure Content Repository Views

Held within the portal schema are a number of content repository views. You can use these views to query back data on the documents and items stored in the content repository. For a list of the secure views, refer to Section E.2, "Secure Views".

Many of the content management APIs that are discussed in this manual require you to pass object IDs as parameters. To do this, you need to know the IDs of the objects with which you want to work. You can use the secure content repository views to find the IDs of portal objects. For more information, refer to Section 10.3, "Finding an Object ID".

9.2.2 Terminology

To maintain backward compatibility with the Oracle9iAS Portal Release 1 (3.0.9) content area APIs and views, many of the API procedure and parameter names and the view and column names continue to use Release 1 terminology. You may find the following table useful to map the Release 1 terminology to the current terminology.

9.4.1 Using a Separate Schema

When creating procedures and packages that use the content management APIs, create them in a separate schema of the database in which OracleAS Portal is installed. Do not create them in the portal schema. Creating additional procedures and packages in the portal schema is not supported and they may be lost when upgrading to a new release.

Once you have created the schema for your procedures and packages, you must grant it access to the APIs and secure content repository views. For information about how to do this, refer to Section 9.3, "Providing Access to the APIs and Secure Views".

9.4.2 Using Constants

All the API packages include predefined constants that you can use to easily refer to OracleAS Portal objects and metadata. For example, the WWSBR_API package includes constants for base attributes (such as ATTRIBUTE_AUTHOR and ATTRIBUTE_TEXT), seeded item types (such as ITEM_TYPE_FILE and ITEM_TYPE_URL), and image alignment options (such as ALIGN_BOTTOM and ALIGN RIGHT). To make your code robust, you should use these constants wherever possible for object IDs and attribute values. That way, if the actual ID or values change, your code will still work because the name of the constant will stay the same.

For a full list of the constants available in each API package, refer to the Oracle Application Server Portal PL/SQL API Reference on Portal Center:

http://portalcenter.oracle.com

In the Portal Focus Areas section, click Portlet Development, then in the APIs and References section, click PL/SQL API Reference.

9.4.3 Invalidating the Cache

Many of the APIs automatically generate cache invalidation messages for the pages that are affected by the changes. Therefore, you should always call wwpro_api_invalidation.execute_cache_invalidation at the end of your routine to process these messages (see Example 11-3 for an example of how to do this). If you do not call this procedure, your changes may not be visible until the affected pages are invalidated through other means.

There is no need to call execute_cache_invalidation more than once. For example, if you are adding or updating multiple items in a loop, call execute_cache_invalidation when the loop is complete.

9.4.4 Issuing Commits

The APIs do not issue commits. However, if you are calling the APIs from a browser session through Portal Services, Portal Services will perform an automatic commit before returning control to the browser.

The wwpro_api_invalidation.execute_cache_invalidation API also issues a commit. If you are calling the APIs from an external environment (for example, SQL*Plus or a Web provider), and you need to commit before processing the cache invalidations, you must explicitly issue a commit statement in your code. Similarly, if you need to rollback, do so before calling execute_cache_invalidation.

9.4.5 Resetting CMEF Global Variables

If you are using the content management APIs in conjunction with the Content Management Event Framework (CMEF) you need to make sure that you reset the CMEF global variables before or after each API call.

When a user performs an action using the user interface, OracleAS Portal uses various global variables to determine which CMEF messages get logged. After each action, these global variables are automatically reset ready for the next action. When you use the APIs to perform portal actions, these global variables are not automatically reset. Therefore, to ensure that CMEF messages are logged correctly, you must reset the CMEF variables explicitly by calling the wwsbr_api.clear_cmef_context API before or after each API call.

For example, if you use the APIs to create several items on a page, you need to call the clear_cmef_context API between each of the add_item calls (see Example 9-1).

...
l_new_item_master_id1 := wwsbr_api.add_item(
  p_caid              => l_caid,
  p_folder_id         => l_folder_id,
  ...
  );
wwsbr_api.clear_cmef_context;
l_new_item_master_id2 := wwsbr_api.add_item(
  p_caid              => l_caid,
  p_folder_id         => l_folder_id,
  ...
  );
wwsbr_api.clear_cmef_context;
...

For more information about CMEF, refer to Chapter 16, "Using the Content Management Event Framework".

9.4.6 Using Predefined Exceptions

The API packages contain many predefined exceptions. When coding with the content management APIs, it is good practice to include the appropriate predefined exceptions rather than relying on the WHEN OTHERS exception to pick up all errors. This also has the advantage that any error messages generated by the code can be more specific to the actual problem. Example 9-2 shows some of the exceptions you might include when calling the wwsbr_api.set_attribute API.

begin
 wwsbr_api.set_attribute(
   p_site_id           => 37,
   p_thing_id          => 8056,
   p_attribute_site_id => wwsbr_api.SHARED_OBJECTS,
   p_attribute_id      => wwsbr_api.ATTRIBUTE_TITLE,
   p_attribute_value   => 'New Display Name'
 );
 -- Process cache invalidation messages.
 wwpro_api_invalidation.execute_cache_invalidation;
exception
 when wwsbr_api.ITEM_NOT_FOUND_ERROR then
   dbms_output.put_line('Item does not exist');
 when wwsbr_api.ATTRIBUTE_NOT_FOUND then
   dbms_output.put_line('Attribute does not exist');
 when wwsbr_api.ITEM_NOT_FOR_UPDATE then
   dbms_output.put_line('Cannot update an item with a status of Rejected, Deleted or Marked for Delete');
 when wwsbr_api.NOT_AUTHORIZED_USER then
   dbms_output.put_line('User trying to update the item is not the current user or the user who checked the item out');
 when wwsbr_api.EDIT_CUSTOM_ATTR then
   dbms_output.put_line('Error while trying to update a custom attribute');
 when OTHERS then
   dbms_output.put_line('Error '||to_char(sqlcode)||': '||sqlerrm);
end;
/

For a full list of the exceptions available in each API package, refer to the Oracle Application Server Portal PL/SQL API Reference on Portal Center:

http://portalcenter.oracle.com

In the Portal Focus Areas section, click Portlet Development, then in the APIs and References section, click PL/SQL API Reference.

9.4.7 Naming Objects

When creating page groups and page group objects, you specify a unique internal name for the object (p_name). Internal names must:

• be no more than 60 characters in length.

• not contain spaces or special characters other than the underscore character (_).

9.5.1 Identifying Primary Keys

The primary key for most objects contains the object id, the page group id (caid), and the language. When joining between views, always use these columns in the JOIN clause. Example 9-3 shows the JOIN when joining an item to its page.

select ...
from wwsbr_all_items i,
     wwsbr_all_folders p
where i.folder_id = p.id
  and i.caid = p.caid
  and i.language = p.language

9.5.2 Querying Translatable Objects

If an object is translatable (that is, it resides in a page group for which translations are enabled and it includes languages in its key), you must observe the following rules:

• If the object (or its current version) is translated, a row will exist for the translation. To select the row for the current session language, compare the value of the language column to the function wwctx_api.get_nls_language().

• If the object is not translated, select the row for the page group's default language.

Example 9-4 selects the translated page display name for all pages in a given page group.

select p.display_name title
from wwsbr_all_folders p
where p.caid = 53
and (p.language = wwctx_api.get_nls_language -- The current language.
  or (exists -- A row for the page in the page group default language.
      (select pg.id
       from wwsbr_all_content_areas pg
       where pg.id = p.caid
         and pg.default_language = p.language
      )
      and not exists -- A row for the page in the current language.
       (select p2.id
        from wwsbr_all_folders p2
        where p2.id = p.id
          and p2.language = wwctx_api.get_nls_language
       )
     )
    )
/

9.5.3 Selecting Data for the Current User

To select data for the current user, use the function wwctx_api.get_user. Example 9-5 selects items created by the current user.

declare
  l_user varchar2(60);
  ...
begin
  ...
  l_user := wwctx_api.get_user;
  select ...
  from wwsbr_all_items
  where creator = l_user
  ...
end;
/