16 Integrating OracleAS Wireless with Other Components

The chapter includes the following sections:

Section 16.1, "Overview of Integrating OracleAS Wireless with OID and Portal"
Section 16.2, "Integrating OracleAS Wireless with Oracle Application Server Portal"
Section 16.3, "Notification Engine Integration"
Section 16.4, "Implementing Virtual Private Portals on OracleAS Wireless"

16.1 Overview of Integrating OracleAS Wireless with OID and Portal

This chapter describes integrating OracleAS Wireless with the Oracle Application Server components, Oracle Internet Directory (OID) and OracleAS Portal. In this release, user information is stored centrally in OID. The SSO (Single Sign-On) server uses an OID repository to authenticate users. Table 16-1 describes the attribute mapping between PanamaUser (stored in Oracle Application Server Wireless repository) and orclUserV2 user attributes (stored in OID).

Table 16-1 Attribute Mapping between PanamaUser and orclUserV2 user

PanamaUser	OID User
Name	orclcommonnicknameattribute (by default, cn) specified in OID configuration
DisplayName	DisplayName
Enabled	orclIsEnabled
PasswordHint	orclPasswordHint
PasswordHintAnswer	orclPasswordHintAnswer
Language and Country	preferredLanguage
TimeZone	TimeZone
DateofBirth	orclDateOfBirth
Globaluid	orclguid (the orclguid attribute uniquely identifies OID Users)
Password	user password
Password Confirm	Confirms user password.
Gender	orcl header

Administrators use tools such as Delegated Administrative Services (DAS), to create a new user in OID or to modify attributes of an existing user. Alternatively, OracleAS Wireless customers can implement their own user administrator tool to create, modify, or delete users with the OracleAS Wireless model APIs.

The user information is synchronized between OracleAS Wireless and OID repositories using the following mechanisms:

Oracle Application Server Wireless repository synchronization after user authentication
PL/SQL based asynchronous synchronization
Oracle Application Server Wireless model API interface

For information on authenticating users through SSO, see Chapter 11, "Mobile Single Sign-On".

16.1.1 Repository Synchronization after User Authentication

OracleAS Wireless synchronizes user information which is stored in the Wireless repository with OID after SSO authentication.

Figure 16-1 Interactions Between Oracle Application Server Wireless, SSO and OID

Description of "Figure 16-1 Interactions Between Oracle Application Server Wireless, SSO and OID"

The authentication sequence (as depicted in Figure 16-1) is as follows:

A user sends an explicit login request or tries to access a private service, or an external SSO partner application.
The SSO server challenges user credentials and the user is authenticated.
If the authenticated user does not exist in the OracleAS Wireless repository, then OracleAS Wireless retrieves the user information from OID and creates a new user in the OracleAS Wireless repository. Otherwise, the User attributes in the local repository are synchronized with the attributes stored in the OID.

Note:
The user attributes must be synchronized with OID because the PL/SQL notification mechanism does not guarantee real-time notifications.

16.1.1.1 Potential Conflicts in Application Entities Based on OID

The OracleAS Wireless middle tiers installed against the common meta data repository (the Oracle Application Server Wireless schema) share a common application entity in OID. The application entity is created as part of the first OracleAS Wireless middle-tier installation and is owned by the OID user who installs that middle tier. Subsequent OracleAS Wireless middle tiers installed against the same meta data repository use the application entity that was create as part of the first middle tier installation.

Subsequent OracleAS Wireless middle-tier installations against a meta data repository should be done by the same OID user who installed the first OracleAS Wireless middle tier. For a different OID user to add other OracleAS Wireless middle tiers, you must add the OID user as a shared owner of the application entity before stating any subsequent OracleAS Wireless middle-tier installations.

To add a shared owner for an OracleAS Wireless application entity:

Find the name of the OracleAS Wireless application by executing
```
ORACLE_HOME/wireless/bin/getAppEntityName.sh[bat]
```
from the first middle tier. This script prints the name of the OracleAS Wireless application entity.
Use the OID Deployment Console or OID Directory Manager to add the new OID user as a Component Owner for the OracleAS Wireless application entity name returned in the previous step.

16.1.2 PL/SQL-Based Asynchronous Synchronization

The Oracle Application Server Wireless installation registers a PL/SQL procedure with OID. The PL/SQL procedure is invoked when a user is modified or deleted in OID.

Figure 16-2 Interactions between PL/SQL and OID

Description of "Figure 16-2 Interactions between PL/SQL and OID"

Figure 16-2 depicts the events triggered when a user is modified in OID. The sequence is as follows:

A user attribute is modified, or the user is deleted in OID.
The Provisioning Synchronization agent picks up the modifications and calls the registered PL/SQL package.
The PL/SQL package accomplishes appropriate changes in the PanamaUser table (if required).
The trigger on the PanamaUser table broadcasts a RefreshCache message to all running instances of OracleAS Wireless.
If the modified PanamaUser is cached by the running instances, the PanamaUser object is reloaded from the OracleAS Wireless repository.

16.1.3 Oracle Application Server Wireless Programmatic Model API Interface

The ModelFactory.createUser() method creates a corresponding user in the OID repository.

The User.set methods update the corresponding user entry in OID for all of the attributes. The User.delete() method removes the corresponding user from the OID repository. The current semantics of commit is preserved for the user modifications.

16.1.4 OracleAS Wireless User Management Integrated with DAS

In OracleAS Wireless integration mode, when you create a user through the User Manager, the request is first redirected to OID DAS (Delegated Administration Service), for entering Oracle Application Server User Common Attribute Values. After that, the request is redirected back to the User Manager page for entering Wireless-specific attribute values.

The same applies for editing a registered Wireless user. The user is first edited through DAS and then through the User Manager.

16.1.5 Synchronizing Data between Oracle Application Server and Oracle Internet Directory

To synchronize data between Oracle Application Server and OID, run the Oracle Directory Integration Server, odiserv.

16.2 Integrating OracleAS Wireless with Oracle Application Server Portal

Oracle Application Server Portal (Portal) is a Web-based application model for building and deploying e-business portals. It provides an environment for accessing and interacting with enterprise software services and information resources. Portal provides a framework that integrates Web-based resources such as Web pages, applications, business intelligence reports, and syndicated content feeds, within standardized, reusable information components called portlets. For more information, see Oracle Application Server Portal Configuration Guide.

A portlet is an area of HTML/XML located within a defined area of a Web page. Portlets communicate with the portal through an entity called a provider. Portlets form the fundamental building blocks of a Portal page. Each Portal page consists of content presented through one or more portlets and links that enable the user to navigate to another page to take some action.

Portlets summarize, promote, or provide basic access to an information resource. The portlets allow information resources to be personalized and managed as an application of Portal. The portal framework provides additional services including SSO (single sign-on), content classification, enterprise search, directory integration, and access control. Portal supports Desktop PC Web browsers and enables access to Portal pages from wireless devices. Portal, working in conjunction with OracleAS Wireless, automatically transforms the Portal page structure to one that befits the wireless devices. Portlets provide a wireless interface using Portal through OracleAS Wireless, because Portal generates the page structure in OracleAS Wireless XML for all requests from wireless devices that OracleAS Wireless renders to the device.

16.2.1 OracleAS Portal as a Wireless Application

Portal must be deployed as a OracleAS Wireless application in the OracleAS Wireless repository to enable OracleAS Wireless access to Portal. Each Portal installation is deployed as an HTTP Adapter-based application in OracleAS Wireless. Multiple Portals may be deployed on a single OracleAS Wireless instance. The HTTP adapter application, which accepts a URL as a configuration parameter, must be set to the URL of the Portal's home page. To create a OracleAS Wireless application, a master application definition based on an HTTP adapter must be created using the Service Manager. In addition, you must create aPortal application based on the HTTP adapter master application.

Portal redirects requests from a mobile device to an OracleAS Wireless server. The OracleAS Wireless Server accepts the request and invokes the Portal home page over HTTP and accepts the response generated (in OracleAS Wireless XML), from Portal. The Wireless XML response, generated by Portal, is then adapted to the native device markup by the OracleAS Wireless server. All further requests and responses between Wireless device and OracleAS Portal is mediated by the OracleAS Wireless Server.

The mobile devices make the first request to Portal server. Portal redirects the device request to OracleAS Wireless Server. The Portal appends two query parameters to the redirected URL, PAoid and PAhome. Both PAoid and PAhome contain the value of the object id (the service-id in the OracleAS Wireless repository) of the Portal's HTTP adapter service. The syntax of the redirected URL is:

http://9iASWSerrver:port/ptg/rm?PAoid=<OraclePortal object id>&PAhome=<OraclePortal object id>

The PAoid parameter enables the Wireless server to directly launch the Portal Home page, without having to navigate through the Wireless server's folder and service hierarchy. The PAhome parameter sets the Portal's Home page as the home page for the current OracleAS Wireless session.

16.2.2 Developing Wireless Portlets

Portlets are owned by entities called providers. One provider can manage one or many portlets. Providers are the backbone of the portlets displayed on each page. Portal supports a Web Provider framework that is written as a Web application. It is installed and hosted on a Web server and is remote from the Portal. A portlet exposed as a Web Provider can be developed in any Web language. A Web Provider communicates with Oracle Application Server Portal using SOAP(XML).

Portal supports a Java-based Portal Developer Kit (PDK) framework to develop portlets and services. The Java PDK framework is a set of services that enable Java programmers to create portlets from existing Java-based applications (Java, Java Servlets, and JSPs). It provides an abstraction to handle communication with Oracle Application Server Portal, default classes to simplify portlet creation, and exposes APIs for end-user customization, session storage, security, and logging.

For mobile devices, Portal supports portlets that generate OracleAS Wireless XML. To enable wireless access, Portlets must generate OracleAS Wireless XML and indicate this capability using the Java PDK framework. The Java PDK framework uses a Provider.xml file to discover the capabilities of the Portlets supported by a Provider. Refer to Oracle Portal's PDK-Java User's Guide for more information.

16.2.2.1 Provider.xml Tags

This section provides an overview of the tags in the Provider.xml file that indicate the wireless capabilities of a portlet.

Usage: <acceptContentType>text/vnd.oracle.mobilexml</acceptContentType>

The text/vnd.oracle.mobilexml value indicates that the portlet generates the OracleAS Wireless XML required for wireless access. A portlet can be enabled for both HTML (PC Desktop) and wireless access by indicating that it can accept both of these content types as:

<acceptContentType>text/vnd.oracle.mobilexml</acceptContentType>
            <acceptContentType>text/html</acceptContentType>

If the portlet generates only OracleAS Wireless XML (text/vnd.oracle.mobilexml), then the portlet transforms the OracleAS Wireless XML to HTML for PC Desktop clients unless otherwise indicated.

Usage: <mobileFlags>MOBILE_ONLY</mobileFlags>

Portlets set this value to MOBILE_ONLY to indicate that this portlet must be renderedon wireless devices only. This prevents the default behavior of a portal that renders portlet-generated OracleAS Wireless XML to PC Desktop clients.

Usage: <showLink>true</showLink>

Portal renders all of the portlets on mobile devices as links. Portlets must set this value to true to render portlets on a wireless device. The true value enables the portal to generate a link, which points to the portlet content on the wireless device.

Usage:

         <linkPage class="oracle.portal.provider.v2.render.http.ResourceRenderer">
                       <resourcePath>/mypath/mypage.jsp</resourcePath>
                       <contentType>text/vnd.oracle.mobilexml</contentType>
                       </linkPage>

The <linkPage> tag holds the pointer to the resource which generates the required link that is rendered on a wireless device. This resource must generate OracleAS Wireless XML. Example 16-1 illustrates a link page implemented in JSP.

Example 16-1 A Link Page Implemented in JSP

           <%@ page session="false" contentType="text/vnd.oracle.mobilexml" %>
               <SimpleHref target="/mypath/mywireless.jsp" label="Go">
                     Wireless HelloWorld
               </SimpleHref>

The new version JPDK has been updated to understand thee wireless properties of a Portlet. The JPDK also supports Wireless-specific request information such as location and device information, which can be accessed by the Portlets through the JPDK APIs.

16.2.3 Oracle Portal, OracleAS Wireless and Single Sign-On (SSO)

Both Oracle Portal and OracleAS Wireless depend on Oracle's SSO solution for user authentication and login. This integration enables the user to invoke protected applications defined on both systems and eliminates multiple login dialog boxes for users.

OracleAS Wireless Server upgrades the session context of a user to an "authenticated" state when any service or application (HTTPAdapter applications) validates the user credentials with the SSO server. When Portal, a mobile application, validates the credentials of a user with the SSO Server, the session context in OracleAS Wireless is also updated. This allows wireless Portlets deployed on Oracle Portal to use services such as User Location Picker, Routing, Mobile Positioning supported by the OracleAS Wireless Server.

16.2.4 Portlets for Applications Deployed on Wireless Server

Portal's applications provide a PC Desktop view of OracleAS Wireless services. Use the Portal JPDK framework to provide a ÒshowPage" and "editPage", for Web-based customizations.

Since the Portal itself can be accessed from a wireless device, you must also provide a mobile portlet. On a wireless device, the mobile portlets are rendered as links and can be made to point to an application deployed on the OracleAS Wireless server. Use Portal's JPDK framework to provide a ÒlinkPage" that generates the appropriate link to the OracleAS Wireless service. To point to a OracleAS Wireless service from a mobile portlet, use following URL syntax in the OracleAS Wireless XML:

target="___REQUEST_NAME__?___SESSION__&amp;PAoid=<PAoid of Wireless Service>"

The OracleAS Wireless server replaces all "_<Name>_" to the correct values at runtime and invokes the application defined in the OracleAS Wireless repository.

Example 16-2 illustrates a sample link page.

Example 16-2 A Sample Link Page

<%@ page session="false" contentType="text/vnd.oracle.mobilexml" %>
          <SimpleHref target="/___REQUEST_NAME__?PAoid="+PAoid + "&amp;___SESSION__" label="Go">
                My Wireless Service
          </SimpleHref>

Mobile devices make the first request to Portal server. Portal redirects the device request to OracleAS Wireless server, over HTTP, and appends query parameters to the redirected URL, PAoid and PAhome. Both PAoid and PAhome contain the Portal's object and service ID. The typical syntax of the redirected URL is:

http://Oracle Application Server WirelessSerrver:port/ptg/rm?PAoid=<OraclePortalServiceid>&PAhome=<OraclePortalService id>

The PAoid parameter enables the OracleAS Wireless Server to directly launch the Portal Home page without having to navigate through the OracleAS Wireless Server's folder and service hierarchy. The PAhome parameter sets the Portal's Home page as the home page for the current OracleAS Wireless session.

16.2.4.1 OracleAS Wireless Tools and Customization as Portal Providers

The post-installer automatically registers the OracleAS Wireless Tools and Customization as two Portal providers. Thus, if a Portal user selects the two providers, the user then sees two portlets: one for the OracleAS Wireless Tools, and one for Customization. If the URL for Tools or Customization is changed, then the provider can be registered from Wireless System Manager (a node of Oracle Enterprise Manager).

16.3 Notification Engine Integration

The Notification Event Collector Service process uses the OracleAS Wireless Notification Engine to deliver notifications to mobile devices. It adds components that collect application events, process user contact rules, and formats notification contents. Figure 16-3 presents an architectural overview of the various components of the notification process.

Figure 16-3 Integrated Notification Solutions

Description of "Figure 16-3 Integrated Notification Solutions"

Applications outside of OracleAS Wireless can use two different mechanisms to interface with the Notification Engine: the push interface and the pull interface.

Using the push interface, applications send notification events over HTTP to the Notification Event Collector Service which is based on a servlet. The Notification Event Collector Service then passes the notification event data to the Notification Event Feeder, which is a customized data feeder to the Notification Engine.

The pull interface enables the Notification Event Collector process to connect to the application and retrieve the notification events. The notification event data is then passed onto the Notification Event Feeder. The Notification Event Collector process consists of a number of different adapters; each adapter is specific for a particular application. You can enable and disable adapters by configuring the notification collector process. Using the OracleAS Wireless System Manager, you can start or stop a Notification Event Collector process. For more information, see Section 3.6.1.

The notification event handler is a customized system-level notification application that reads data from the notification event feeder. The data indicates the target user for this notification, as well as the type of notification and other notification-specific data.

The notification event handler then looks up the target user's active contact rule to determine the user's preferred notification device type and address. The notification event formatter is then invoked, which generates the content of the notification, customized for the user's device type. The generated notification content is delivered to user's devices by the notification engine.

The notification event handler is a system-level notification application; users do not need to explicitly create a notification subscription on this process to receive notifications. Instead, only the administrator user, ORCLADMIN, is subscribed to this process. Depending on the application, users can specify (either in the OracleAS Wireless Customization Portal, or in the actual application itself), the events for which they want to receive notifications. For each notification processed, the system looks up the contact rule of the target user and make sure that the correct user receives the notification. Use the System Manager to start, stop or configure notification event process. For more information, see Section 3.6.1.

Note:

Only the ORCLADMIN user can subscribe to the notification event handler notification application. If there is more than one subscription, then users will receive multiple copies of each notification (as many copies as there are subscriptions to the notification event handler notification application).

The Notification Event Collector and notification event handler are two separate processes. Both of them must be running at the same time for the system to process application event notifications.

16.3.1 Integrating OracleAS Wireless with Oracle Workflow

Oracle Workflow integration includes two components: a notification service which receives notifications from the Oracle Workflow Notification queues and sends them to the user's mobile device and an Oracle Workflow Notification Worklist service which can be accessed through the OracleAS Wireless portal.

Since Oracle Workflow and OracleAS Wireless are both components of Oracle Application Server, OracleAS Wireless connects to Oracle Workflow through OID. As a result, they share the same user repository.

16.3.1.1 Notification Service

Oracle Workflow provides a queue which contains all of the outgoing notifications for that particular instance. Each message in the queue contains all of the necessary information for the notification and for the user to which it is sent. OracleAS Wireless dequeues these messages and uses XMS to construct a message to be sent to the end user. The user can then respond to this notification. The response is directed to a OracleAS Wireless service which will then update Oracle Workflow according to the user's response.

Note:

If end users cannot receive notifications during the testing of the OracleAS Wireless integration with Oracle Workflow, then you must check the log file for an ORA-4031 error, which indicates that the notification service failed because of insufficient memory pool size in the database. To increase the shared memory pool:

Increase the value for the shared_pool_size parameter in the init.ora file. (Typically, the init.ora file is located on the infrastructure machine in the ORACLE_HOME/dbs directory.)
Restart the database for the change to take effect.

If end users still cannot receive notifications, then you must further increase the size of the shared memory pool.

16.3.1.2 Worklist Service

This is the equivalent of the Oracle Workflow Notification Worklist through the OracleAS Wireless portal. Using OID, the Worklist Service will connect to Workflow to retrieve a list of all the user's open notifications. Each notification can be closed or responded to (depending on the type of notification).

16.4 Implementing Virtual Private Portals on OracleAS Wireless

To implement virtual private portals (VPP), uncomment the ENABLE MULTIPLE REALM SUPPORT section of the OracleAS Wireless loginpage.jsp (Example 16-3).

Example 16-3 The OracleAS Wireless loginpage.jsp

<!--
UNCOMMENT TO ENABLE MULTIPLE REALM SUPPORT
NOTE: Please replace "Company 1", "Company 2" with the real values.
  Add as many SimpleFormOption elements as you need
      <SimpleFormSelect name="subscribername" displaymode="list" multiple="false">
        <SimpleTitle>
        <%=utils.getString("visual.login.subscribername", locale)%>
        <SimpleFormOption value="Company 1"selected="true"Company 1</SimpleFormOption>
        <SimpleFormOption value="Company 2">Company 2</SimpleFormOption>
      </SimpleFormSelect>
-->

For more infomation on VPP, refer to the Oracle Application Server Portal Configuration Guide