10 Getting Started with Content Management APIs

This chapter introduces some tasks and concepts that you may find useful before you start using the content management APIs provided with Oracle Portal. It contains the following sections:

10.1 Setting the Session Context

All of the content management APIs and the secure views assume that the context has been set for the functions to execute as a specific portal user. If you call an API from within a browser session (for example, a database provider or PL/SQL item), the context is set automatically to the user who is currently logged in to the portal. If you call an API from a Web provider or an external application (for example, SQL*Plus or Portal Services), you must set the context to a specific user by using the wwctx_api.set_context API.

This API allows an application to assert an identity, by providing a user name and password that the portal can verify with the Oracle Application Server Single Sign-On Server before establishing a session for the asserted user. If the assertion fails, due to an invalid password, for example, an exception is raised.

Example 10-1 sets the context to user JOE.BLOGS with the password welcome1.

Example 10-1 Setting the Session Context (set_context API)

declare
  p_user_name varchar2(60) := 'JOE.BLOGGS';
  p_password  varchar2(60) := 'welcome1';
  p_company   varchar2(60) := null;
begin
  wwctx_api.set_context(p_user_name,p_password,p_company);
end;
/

10.2 API Parameters

  • The following parameters refer to the page group ID:

    • p_site_id

    • p_siteid

    • p_caid

    For backward compatibility purposes these parameter names have not been changed, and will not be changed, to use the most recent terminology. For more information, refer to Section 9.2.2, "Terminology".

  • The following parameters refer to the page ID:

    • p_folder_id

    • p_id

    For backward compatibility purposes these parameter names have not been changed, and will not be changed, to use the most recent terminology. For more information, refer to Section 9.2.2, "Terminology".

  • An item has two IDs. All versions of the item have the same master item ID (GUID). However, when you create a new version of an item it is assigned its own ID that uniquely identifies that particular version of the item. Some APIs simply need the master item ID to identify an item (p_master_item_id). However, some APIs (for example, modify_item) also need to know which particular version of the item you want to work with. In this case you need to pass the unique item ID (p_item_id). In some APIs, you will find that the item ID is referred to as p_thing_id.

  • The primary key for most objects contains the ID of the actual object and the ID of the page group to which the object belongs. When referencing an existing object in a parameter, you must reference both the object ID and its page group ID. The referenced object's page group must either be the same as the page group of the referencing object or the Shared Objects page group. For example, when adding an item, you need to specify the item type (for example, file, text, image, and so on). To do this you must pass the item type ID (p_type_id) and the ID of the page group which contains the item type (p_type_caid).

10.3 Finding an Object ID

Many of the content management APIs require you to pass object IDs to their parameters. To do this, you need to know the IDs of the objects with which you want to work. You can obtain these IDs by using the secured content repository views.

10.3.1 Finding a Page Group ID

Many of the content management APIs include the ID of a page group as one of the parameters. For example, when creating a page using the add_folder API, you need to specify the ID of the page group in which you want to create the page using the p_caid parameter. Example 10-2 shows a query that you could use to find out this ID.

Example 10-2 Finding the ID of a page group

select id "Page Group ID"
from wwsbr_all_content_areas
where name = '&pagegroup'
  and language = '&language'
/

Example 10-3 shows how you might use this query in a function.

Example 10-3 Function to Find the ID of a Page Group

create or replace function get_page_group_id (p_name in varchar2) return number is
  l_page_group number;
  l_language   varchar2(30);
begin
  l_language := wwctx_api.get_nls_language;
  select id
  into l_page_group
  from wwsbr_all_content_areas
  where name = p_name
    and language = l_language;
  return l_page_group;
exception
  ...
end;
/

10.3.2 Finding a Page ID

When working with pages and items using the content management APIs, you need to know the ID of the page in which you want to work. For example, if you want to delete a page using the delete_page API, you need to identify the page that you want to delete by its ID. Example 10-4 shows how to find out the ID of a page if you know the ID of the page group to which it belongs.

Example 10-4 Finding the ID of Page in a Known Page Group

select id "Page ID"
from wwsbr_all_folders
where name = '&page'
  and caid = 53
  and language = '&language'
/

Sometimes you may not know the ID of the page group to which a particular page belongs. Example 10-5 shows how to find out the ID of a page and its owning page group.

Example 10-5 Finding the IDs for a Page and Its Page Group Given Page and Page Group Names

column 'Page Group Name' format a25;
column 'Page Name' format a25;
select f.caid "Page Group ID",
       c.name "Page Group Name",
       f.id   "Page ID",
       f.name "Page Name"
from wwsbr_all_content_areas c,
     wwsbr_all_folders f
where f.name = '&page'
  and c.id = f.caid
  and c.name = '&pagegroup'
  and c.language = '&language'
  and c.language = f.language
/

10.3.3 Finding Region IDs

When adding an item to a page using the add_item API, you need to know the ID of the region in which you want to place the item. You can add items only to item regions that have been set up to allow content to be added to them. Example 10-6 shows a query that finds out the IDs and types of the insertable regions on a particular page. Given this information, you can choose the region ID of an appropriate region on the page in which to place your new item.

Example 10-6 Finding the IDs and Types of Insertable Regions on a Given Page

select distinct r.id "Region ID",
                r.type "Type"
from wwsbr_all_content_areas c,
     wwsbr_all_folders f,
     wwsbr_all_folder_regions r
where f.name = '&page'
  and c.name = '&pagegroup'
  and c.id = f.caid
  and f.id = r.folder.id
  and f.caid = r.folder.caid
  and r.allow_content = 1
  and c.language = '&language'
  and c.language = f.language
  and (f.language = r.language
    or r.language is null)
/

10.3.4 Finding an Item ID

Example 10-7 illustrates how to find the ID of an item by querying the WWSBR_ALL_ITEMS view.

Example 10-7 Finding the ID of the Current Version of an Item Given its Master Item ID

select id
from wwsbr_all_items
where masterid = 513
  and caid = 53
  and active = 1
  and is_current_version = 1
  and language = '&language'
/

To avoid duplicate rows when querying for currently published items, always include the LANGUAGE, ACTIVE (active=1), and IS_CURRENT_VERSION (is_current_version=1) columns. Example 10-8 shows how to select all items on a given page (folder_id=1) and a given page group (caid=75).

Example 10-8 Finding Item IDs

select i.display_name title, i.id latestversion
from wwsbr_all_items i
where i.folder_id = 1
  and i.caid = 75
  and i.active = 1
  and i.is_current_version = 1
  and (i.language = '&language' -- The current session language.
      or (    exists -- A row for the item in the page group default language.
              (select pg.id
               from wwsbr_all_content_areas pg
               where pg.id = i.caid
                 and pg.default_language = i.language
              )
           and not exists -- A row for the item in the current language.
              (select i2.id
               from wwsbr_all_items i2
               where i2.id = i.id
                 and i2.language = '&language'
                 and i2.active = i.active
                 and i2.is_current_version = i.is_current_version
              )
         )
      )
order by i.id
/