# Installation and Development Guide

# Portlet Development -
WebLogic Portal

WSRP (Web Services for Remote Portlets) is a W3C standard for consuming one or more remote markup "Producers" from a markup "Consumer". The .NET Application Accelerator provides a WSRP Producer for ASP.NET that can be used to produce portlets for the WebLogic Portal's WSRP Consumer.

Note: | In order to produce portlets, the WSRP Producer must be installed and correctly configured with the local IIS instance. A working WSRP Producer provides a WSRP WSDL available at the following URL: http://<iis-website-address>/wsrpproducer/1.0/WSRPService.wsdl

Note: | This URL will be required below when referencing a .NET WSRP Producer from the WebLogic Portal WSRP Consumer. To ensure that the WSRP producer is running, paste this URL into the address bar of a web browser.

The .NET Application Accelerator includes VisualStudio.NET integration for easy authoring of WSRP portlets. The provided WSRP web site project template is pre-configured to include references to required BEA assemblies, including the new Portlet API libraries. These settings are available in the site's Web.config file.

A new WSRP Portlet project also includes a simple WSRP portlet page in the Default.aspx / Default.aspx.cs files. This page extends the WSRPPortletPage base class, which provides access to preference and user information.

Note: | ALI Portlet and Preference Page templates should not be used for WSRP portlets.

This chapter includes the following sections:

- Getting Started with WSRP Portlet Project and File Templates
- Using WSRP Preferences with WSRP Portlets
- Using User Profile Preferences with WSRP Portlets
- Registering a Portlet with the WSRP Producer
- Consuming a .NET WSRP Portlet from WebLogic Portal
- Deploying the WSRP Producer
- Retrieving SAML Tokens from WLP

## Getting Started with WSRP Portlet Project and File Templates

Follow the steps below to create a new portlet using the WSRPPortletPage template.

1. Create a new WSRP Portlet project in VisualStudio.NET:

1. Start VisualStudio.NET.
2. Click File | New | Web Site to create a new project.
3. Select the C# language option.
4. In the My Templates list, select WSRP Portlet Project.
5. Name the project "firstWsrpWeb".

2. Create a new WSRP portlet page:

1. In the Solution Explorer, right-click on the root of the project and select Add New Item...
2. In the My Templates list, select WSRP Portlet Page.
3. Save the file as "HelloWorld.aspx".

The WSRPPortletPage class provides access to functionality described in the sections that follow.

## Using WSRP Preferences with WSRP Portlets

The .NET WSRP Producer supports user scoped preferences that can be declaratively created in a WSRPPortletPage instance and are managed by the WSRPPortletPage itself. For example, a WSRP preference can be declared simply using an attribute as shown in the code below:

    [PortletStateValue()]
    protected String colorSelection;

This will extract a preference named colorSelection from the PortletRequest and set the value in this field. This is supported for fields declared as public, protected, and internal and are of type String, int, float, bool, or DateTime. Preference values will be available after the OnLoad() page event. Any changes to the value of a field marked with the PortletStateValue attribute after the OnLoad() event will be set as a new preference value during the OnUnload() event.

In the absence of the value for a preference in the PortletRequest, the value of the preference will default to the intrinsic default value of the preference type in the language. To provide a default value, use the the attribute's "defaultValue" field. For example:

    [PortletStateValue(DefaultValue="orange")]
    protected String colorSelection;

To decouple the name of the field in the page class and the name of the preference, set the attribute's "Key" attribute. For example,

    [PortletStateValue(Key="colorlSelection", DefaultValue="orange")]
    protected String theColor;

This will extract the preference named "colorSelection" and apply it to the field "theColor".

For a full description of the API, see the complete class documentation for the WSRP part of the Portlet API, which is installed into the VisualStudio.NET 2005 Integrated Help System. Standard NDoc HTML files are also installed in: $PT_HOME/portletapi/1.0/Documentation

Note: | WebLogic Portal supports WSRP Preferences, but in order to use preferences, the .portal file describing a portal in WebLogic Portal must be converted from "file" mode to "streaming" mode. For details, see "Creating a Desktop" on the following page: http://download.oracle.com/docs/cd/E13218_01/wlp/docs92/portals/creating_staging.html

To get started with WSRP portlet preferences in ASP.NET, create a new WSRP portlet page with these steps:

1. Create a new portlet using the WSRPPortletPage template:

1. In Solution Explorer, right-click on the root of the web site project and select Add New Item...
2. In the My Templates list, select WSRP Portlet Page.
3. Name the page "SimplePreference.aspx".

2. Add a preference to the portlet by adding this code to the code-behind file for SimplePreference.aspx: [TODO: code sample. PM.]
3. Register the new SimplePreference portlet with the WSRP Producer as described in Registering a Portlet with the WSRP Producer.
4. Follow the steps to create a new portlet in WebLogic Portal and add the new portlet to the existing streamed portal. In order to make changes to a streamed portal, the new SimplePreference portlet must be added to the portal via the online administration tools for the portal application. Also, in order to modify preferences, a user must be logged into WebLogic Portal. See the WebLogic Portal documentation for additional information for configuring login.
5. Log in to the portal and access the location of the portal in a web browser. Refreshing the page will cause the preference value to change and keep track of the number of times the portlet has been accessed by the user.

Note: | In WSRP portlets, a change in preference state is not reflected until the next request to a WSRP portlet. This is because transmission of the preference and persistence of the new preference value happens in the response at the end of the preference editing request. The new value for the preference will be available in the next portlet request.

## Using User Profile Preferences with WSRP Portlets

ASP.NET 2.0 introduced the Provider model as a design pattern for plugging data providers into the framework. The Portlet API makes use of the ProfileProvider to expose user profile information sent by WebLogic Portal over WSRP to an ASP.NET web application. More information about the ProfileProvider model can be found in the MSDN documentation here: http://windowssdk.msdn.microsoft.com/en-us/library/014bec1k.aspx

The Web.config file for a .NET WSRP Portlet project contains a `<profile>` element that defines a Provider to supporting accessing user profile properties. In order for user profile properties from WebLogic Portal to flow over WSRP into the .NET web application, they must be registered in the Web.config file as follows:

    <properties>

    <add name="CustomPropertiesTitle" type="string" defaultValue="Test Title"/>
    <add name="MyProfileAge" type="Int32" />
    <add name="MyProfileBirthday" type="DateTime" />

    </properties>

Each property must have a "name" and a "type" attribute and can include an optional "defaultValue" attribute. These values can be accessed in a WSRPPortletPage by using the Profile property of the superclass as shown in the code below:

    int age = Profile.MyProfileAge;

Note: | Property names must follow a specific naming format to match the user profile property naming conventions used by WebLogic Portal. User profiles consist of a named property set of named properties. The rule for naming a property in a user profile is to use the capitalized name of the property set concatenated with the capitalized name of the property. In the example above, the property set is named "MyProfile" and has two properties "Age" and "Birthday". For more information, see the WLP documentation: http://download.oracle.com/docs/cd/E13218_01/wlp/docs92/users/developuserprofiles.html

The .NET WSRP Producer must also be configured to send these properties from the WSRP message to the ASP.NET web application. This requires adding a `<user-profile>` element to a `<portlet>` and configuring the property names that should be passed through the WSRP Producer. For example, add the following code to the end of a `<portlet>` element to pass the properties described above:

    <user-profile>

      <item>CustomProperties/Title</item>

      <item>MyProfile/*</item>

    </user-profile>

The properties from a property set can be filtered individually using a string with the format `<propertyset-name>/<propertyname>`. Using "*" for the `<propertyname>` will pass all properties from a property set from the WSRP Producer to the ASP.NET web application.

## Registering a Portlet with the WSRP Producer

Once the portlet content has been created, the URLs of the portlet content and additional metadata must be configured in the WSRP Producer. All the portlets available from the WSRP Producer must be registered in the /portlets.xml file at the root of the WSRP Producer's web site.

To add a portlet, edit the portlets.xml file in a text editor and add the following XML between the enclosing `<portlets>` elements:

    <?xml version="1.0" ?>

    <portlets xmlns:xsd="http://www.w3.org/2001/XMLSchema"

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <!-- Configure the HelloWorld portlet -->

    <portlet>

      <handle>HelloWorldPortlet</handle>

      <portlet-name>Hello World Portlet</portlet-name>

      <view_url>/firstWsrpWeb/HelloWorld.aspx</view_url>

      <expiration-cache>10</expiration-cache>

      <supported-locale>en</supported-locale>

      <description lang="en">HelloWorld WSRP Portlet</description>

      <display-name lang="en">HelloWorld Portlet</display-name>

      <supports>

        <mime-type>text/html</mime-type>

        <portlet-mode>View</portlet-mode>

      </supports>

      <portlet-info>

        <title>Hello World Portlet</title>

        <short-title>View</short-title>

      </portlet-info>

    </portlet>

    </portlets>

This configures the URL for the portlet content in the `<view_url>` element and adds additional information about the default title, supported view mode and mime types, and provides the portlet a WSRP handle name. Once this step is complete, the portlet can be consumed by WLP.

## Consuming a .NET WSRP Portlet from WebLogic Portal

To consume remote portlet resources from WebLogic Portal, a Remote Portlet must be created using either the IDE tools (described here) or using the online administration tools. Once created, Remote Portlets (.portlet files) can be added to a WebLogic Portal portal description (.portal file).

In order to create a Remote Portlet produced by the .NET WSRP Producer, you must know the address of the Producer's WSRPService.wsdl file. The URL will vary depending on how IIS is configured to host the WSRP Producer, but it should be similar to the following: http://192.168.1.1:1234/wsrpproducer/1.0/WSRPService.wsdl

To create the Remote Portlet using the WebLogic Portal IDE tools, follow the steps below:

1. Click File | New | Portlet.
2. Under Portlet Type, select Remote Portlet.
3. Select the Producer from the Select Producer menu. If this is the first time the WSRP Producer is used to provide remote portlets to WebLogic Portal, follow the steps below:

1. Select Find Producer and enter the URL to the WSRPService.wsdl file as `http://<server>:<port>/wsrpproducer/1.0/WSRPService.wsdl`
2. Click Retrieve to obtain the list of available remote portlets from the .NET WSRP Producer. Click Next.
3. The page shows the list of available, remote portlets listed in the WSRP Producer's portlets.xml file. Select one and click Next.
4. In the Producer's Handle field, enter a name that is descriptive of the .NET WSRP Producer. This name will be displayed in the Select Producer menu.

4. Create the portlet and add any necessary functionality.
5. Once the .portlet file is created, add it to the .portal file. (For instructions on creating a .portal file, see http://download.oracle.com/docs/cd/E13218_01/wlp/docs92/portals/develop_portals.html#wp1011957.)

For detailed information on creating remote portlets, see http://download.oracle.com/docs/cd/E13218_01/wlp/docs92/federation/Chap-Build_Simple_Remote.html#wp1016477

The .portal file containing the ASP.NET portlet can be rendered by rebuilding and redeploying the Portal application and accessing the URL of the .portal file. Consult the WebLogic Portal documentation for information on creating and deploying portal and portlet resources.

If problems arise following these steps, see Troubleshooting..

## Deploying the WSRP Producer

This section is applicable only to the WSRP Producer. During installation, the WSRP Producer web site is deployed to IIS based on the configuration settings provided to the installer. This configuration information is used to parameterize the WSRP Producer's WSDL file which describes the locations of various WSRP web services. After installation has completed, any changes to the IP address, port number, or web site deployment path must be made to this file: $DNAA_HOME/wsrpproducer/1.0/webapp/wsrpproducer/1.0/WSRPService.wsdl

Forgetting to make these changes will result in failure of the WSRP Producer to locate required WSRP web services. To make changes, simply edit WSRPService.wsdl in a text editor and change the necessary entries. For example, to update the location of the WSRP Producer, change the following entry:

    <soap:address
    location="http://192.168.1.1:1234/wsrpproducer/1.0/WSRPBaseService.asmx"/>

    to the correct IP address and port, for example:

    <soap:address
    location="http://192.168.123.456:8888/wsrpproducer/1.0/WSRPBaseService.asmx"/>

Additional configuration of the WSRP Producer web site can be made via the IIS administrative tools.

## Retrieving SAML Tokens from WLP

SAML assertions are sent from WLP over WSRP when WLP is configured to send them. SAML configuration are often unique; to learn more about SAML configuration, read Establishing WSRP Security with SAML ( http://download.oracle.com/docs/cd/E13218_01/wlp/docs92/federation/ Chap-Security-SAML.html). You may also want to read Configuring Single Sign-On with Web Browsers and HTTP Clients ( http://download.oracle.com/docs/cd/E13222_01/wls/docs92/secmanage/saml.html).

The SAML token is passed directly to the .NET Portlet API as part of the `User` property of the `WSRPBasePage`, the base class for `WSRPPortletPage`. You can access the SAML token using the `SAMLToken` field in `WSRPPortletUser`.

The following code accesses the `SAMLToken` field from `WSRPPortletPage`:

    XmlElement samlTok = User.SAMLToken;

If no SAML token was sent, this property is set to null.

Below is an example of a SAML token returned from `WSRPPortletUser.SAMLToken`: