4 Integrating User Communication Preferences with your Web Application

This chapter describes how to implement the web user interface using an ADF task flow library and targeting a specific profile. The ADF task flow library makes it easy to integrate the web interface with a new application or an existing application.

For more information about ADF task flows, refer to Creating ADF Task Flows in Developing Fusion Web Applications with Oracle Application Development Framework. To provide the UCP web user interface in your application, perform the tasks described in this chapter.

This chapter includes the following sections:

Section 4.1, "Introduction to UCP Web User Interface"
Section 4.2, "Integrating ADF Web Application with UCP"
Section 4.3, "Deploying Your Application"
Section 4.4, "Verifying Your Application"

4.1 Introduction to UCP Web User Interface

With UCP services, an end user can manage his communication preferences from a web interface by managing his channels and filters. To ensure that the end users are provided control over their communication preferences, the application developers must ensure the integration of UCP web user interface to their application. UCP provides an ADF task flow library which makes it easy to add a region in your web application so that end users can access their preferences directly from your application.

4.2 Integrating ADF Web Application with UCP

This section describes how to create an ADF web application, and how to add a page or a region to an existing web application using the ADF task flow library in Oracle JDeveloper.

4.2.1 Creating a New ADF Application

You can integrate UCP UI with a new application or an existing application. The following instruction describes how to add the UCP UI in a new application through Oracle Jdeveloper. You can add the UI in an existing application by adding a region in an existing page or a new page in the application similarly. To create a new ADF web application in Oracle Jdeveloper, perform the following tasks:

Open the Oracle JDeveloper 12c wizard. Select New Application from the Application Navigator on the left pane. A New Gallery window appears.
In the New Gallery window, select ADF Fusion Web Application from the list of items, and click OK. The Create ADF Fusion Web Application window appears as shown in the following figure.

Description of the illustration ucp_create_app.gif
In this window, enter an application name, for example, MyApp. Also, enter the application package prefix, for example, oracle.ucp. Click Finish to create a new ADF application.

4.2.2 Creating an ADF Web Page

The bounded task flow in the UCP library can be added in any region to provide seamless integration to your application. In this section, we will create a demo ADF web page to host a region for the UCP task flow. To create a new ADF web page, perform the following tasks:

In the left window pane, right-click ViewController to display the context menu.
In the ViewController context menu, from the New menu, select Page. The Create JSF Page window appears as shown in the following figure.

Description of the illustration ucp_create_page.gif
In this wizard, enter the file name, for example, MyPage.jspx. From the Document Type menu, select JSP XML.
From the Page Layout menu, select Create Blank Page. Click OK. The new MyPage.jspx is created.
Open the newly created page by double-clicking MyPage.jspx under the ViewController node in the navigation pane. In the MyPage.jspx window, select Source from toolbar at the bottom to view the source code of the page as shown in the following figure.

Description of the illustration ucp_page_sourcecode.gif

4.2.3 Connecting UCP Task Flow Library

If you have deployed UMS to Oracle WebLogic Server, then the UCP task flow library is already deployed to the server. However, the UCP task flow library may not be accessible from your JDeveloper instance. Therefore, it is important to connect the task flow library to you application. You must first create a file system connection from your JDeveloper instance to the library. To achieve this, perform the following steps:

Click the Window tab located in the toolbar on the top pane to display a drop-down list. From the list, select Resources to add the Resources tab to the right pane of the Jdeveloper window.
Under the Resources tab, click the folder icon to display a drop-down list. In the list, navigate to IDE Connections, and select File System. The Create File System Connection wizard appears as shown in the following figure.

Description of the illustration ucp_create_filesys.gif
Enter the connection name, for example, UCP Task Flow.
Click Browse to select the folder that contains the UCP task flow library. This folder is located in the oracle_common directory and the path would look like the following:
```
oracle_common/communications/modules/oracle.ucs.userprefs.webapp_x.x
```
where x.x is the version number, for example, 2.0.

Navigate to this folder and click Select.
Click Ok. The File System Connection is created. To verify, expand the File System navigation tree in the right pane. On expanding the ADF Task Flows folder, you will see UserCommunicationPreferences as shown in the following figure.

4.2.4 Adding a Region in the New Page

With the support of an ADF task flow library, you can add a region in your web application so that the end users can access their preference directly from your application. To achieve this, perform the following tasks:

Click the Source tab of the newly created page, MyPage.jspx.
From the File System navigation tree in the right pane, drag the UserCommunicationPreferences task flow and drop it inside the <af:form> </af:form> tag in the page source to create a region in this tag.

A context menu appears as shown in the following figure.
Select Region from the context menu. A confirmation window appears.
Click Add Library. The Edit Task Flow Binding wizard appears.
In the Input Parameters table, enter a value for profield, for example, soa. The value for the Profile ID determines that the created user interface accesses only user filters and channels in this profile. This should be the same profile that your application is targeting. Click OK. A region has been added to the page.

If you have an existing ADF web application that you want to integrate with UCP by including a user preference page, then you can add a region to your existing or new ADF page, in the same manner as mentioned in this section.

4.2.5 Referencing UCP Libraries

Since UMS and UCP task flow libraries are deployed on Oracle WebLogic Server, you do not need these libraries in your application. You must reference these libraries from the weblogic.xml file. To achieve this, perform the following tasks:

Right-click the ViewController node located in the navigation pane. A context menu appears.
From the context menu, select New, and click From Gallery. The New Gallery wizard appears.
In the navigation pane, expand the General node and select Deployment Descriptors. From the list of items on the right pane, select Weblogic Deployment Descriptor. Click OK. See the following figure.

The Create WebLogic Deployment Descriptor wizard appears.
From the list of deployment descriptors, select weblogic.xml, and click Next. In the next screen, select 12.1.1 or the newer version as the deployment descriptor version, and click Next. In the Summary page, click Finish
Open the newly created file by double-clicking weblogic.xml under the ViewController node in the navigation pane. In the weblogic.xml window, select Source from toolbar at the bottom to view the source code of the page.
In the weblogic.xml file, you will reference two libraries, that is, the UMS library (oracle.sdp.client) and the UCP library (oracle.ucs.userprefs.webapp). Add the following library references as shown in the following figure:
```
<library-ref><library-name>oracle.sdp.client</library-name></library-ref>
<library-ref><library-name>oracle.ucs.userprefs.webapp</library-name></library-ref>
```
Description of the illustration ucp_library_prefs.gif

4.2.6 Managing Project Deployment Profile

Since you have already referenced the two libraries in the weblogic.xml file, you do not need to package these libraries in your application. This can be managed through the project deployment profile. To achieve this, perform the following tasks:

You must first create a project deployment profile. Right-click the ViewController node from the navigation pane. A context menu appears.
From the context menu, click Deploy, and select New Deployment Profile. The Create Deployment Profile wizard appears.
From the Profile Type drop-down list, select WAR File, and click OK.

The project deployment profile has been created. You must, now, ensure that the libraries are not packaged in your application.
Under the General tab, select the Specify Java EE Web Context Root option, and enter your application context root, for example, myapp as shown in the following figure.

Description of the illustration ucp_deploy_profile.gif
From the navigation tree, select Filters listed under WEB-INF/lib. Deselect all the .jar files listed in the right pane as shown in the following figure. Click OK to save changes to your deployment profile.

This ensures that the libraries are not packaged in your application, as you have already referenced the important libraries in the weblogic.xml file in the previous section.

Description of the illustration ucp_filters.gif

4.2.7 Creating Application Deployment Profile

To create a new application deployment profile, perform the following tasks:

From the Applications drop-down list in the left pane, select Deploy and click New Deployment Profile from the context menu.

The Create Deployment Profile wizard appears.
From the Profile Type drop-down list, select EAR File, and enter a name for your application deployment profile, for example, MyApp.

Click OK to create the application deployment profile. The Edit EAR Deployment Profile Properties wizard appears.
From the navigation tree, select Application Assembly.
In the right pane, expand the ViewController.jpr node and select webapp1. to include it in the application as shown in the following figure.

Description of the illustration ucp_app_profile.gif
In the toolbar, click Save All to save your application.

4.3 Deploying Your Application

You must, now, deploy your application to the WebLogic application server. If your application server has not been configured already, then you must first configure your application server connection.

4.3.1 Deploy Application

To deploy your application, perform the following tasks:

From the Applications drop-down list, select Deploy and click MyApp from the context menu. The Deploy MyApp wizard appears.
In the Deployment Action screen, select Deploy to Application Server and click Next.
In the Select Server screen, select the server from the list of Application servers, and click Finish to deploy your application.

If the server is not in the list of application servers, then follow instructions in Section 4.3.2, "Configuring Application Server Connection" to configure your server connection.

4.3.2 Configuring Application Server Connection

If you have not configured your application server connection, then you must first configure it by performing the following tasks:

From the Applications drop-down list, select Deploy and click MyApp from the context menu. The Deploy MyApp wizard appears.
In the Deployment Action screen, select Deploy to Application Server and click Next.
In the Select Server screen, click the plus icon located at the top right corner.

The Create Application Server Connection wizard appears.
In the Connection Name field, enter your server connection name, for example, MyServer. Click Next.
In the Authentication screen, enter your application server's admin Username and Password. Click Next.
In the Configuration screen, specify the host name, port numbers and, domain name as shown in the following figure.

Click Next.

Description of the illustration ucp_configuring_server.gif
On the Test screen, verify your connection by clicking Test Connection. If the test is successful, then click Finish. You should be able to see your application server in the list of application servers as shown in the following figure.

Description of the illustration ucp_configure_appserver.gif
To deploy your application to the newly configured application server, select the server from the list and click Finish. You will receive a confirmation for the successful deployment of your application.

4.4 Verifying Your Application

Your can access your application to manage user preferences. To verify your application, open a browser and point the URL to your newly created page, for example, http://localhost:7001/myapp/faces/MyPage.jspx. You should see your communication preference web interface as shown in the following figure.

Surrounding text describes ucp_app_verify.gif.

Note:

When you access your application for the first time on your browser, you might see a blank page. This is expected behavior if your application does not include authentication. For the simplicity of this demo, we have not included authentication. But it is recommended that you protect your web application with proper authentication.

To test your demo application without authentication, you can try the following workaround. If there is another Oracle SSO protected web application, you can first log in to that application, and then access your application from the same browser. As a result, you will see the channels and filters of the authenticated user, instead of seeing a blank page.