Skip Headers

Oracle® Application Server Portal Developer's Guide 10g Release 3 (10.1.3) B25601-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 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 OracleAS Portal. It contains the following sections:

- Setting the Session Context

- API Parameters

- Finding an Object ID

## 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 all 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 both 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
    /