Oracle® Fusion Middleware

Administering User Communication Preferences

12c (12.2.1.3.0)

E87097-01

August 2017

Documentation for administrators that describes how to administer Oracle User Communication Preferences (Oracle UCP). This includes how to manage communication channels and filters using the UCP UI, how to manage and configure messaging profiles using Oracle Enterprise Manager, and how to integrate UCP with your web application using an ADF task flow library.

Oracle Fusion Middleware Administering User Communication Preferences 12c (12.2.1.3.0)

E87097-01

Copyright © 2015, 2017 Oracle and/or its affiliates. All rights reserved.

Primary Author:  Megha Sharma

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.

The information contained in this document is for informational sharing purposes only and should be considered in your capacity as a customer advisory board member or pursuant to your pre-General Availability trial agreement only. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described in this document remains at the sole discretion of Oracle.

This document in any form, software or printed matter, contains proprietary information that is the exclusive property of Oracle. Your access to and use of this confidential material is subject to the terms and conditions of your Oracle Master Agreement, Oracle License and Services Agreement, Oracle PartnerNetwork Agreement, Oracle distribution agreement, or other license agreement which has been executed by you and Oracle and with which you agree to comply. This document and information contained herein may not be disclosed, copied, reproduced, or distributed to anyone outside Oracle without prior written consent of Oracle. This document is not part of your license agreement nor can it be incorporated into any contractual agreement with Oracle or its subsidiaries or affiliates.

Contents

Preface

- Audience

- Documentation Accessibility

- Related Documents

- Conventions

1 Introducing User Communication Preferences

- 1.1 Introduction to User Communication Preferences

- 1.2 User Communication Preferences Terminology

2 Managing User Communication Preferences

- 2.1 Managing Communication Channels

- 2.1.1 Creating a Channel

- 2.1.2 Modifying a Channel

- 2.1.3 Deleting a Channel

- 2.1.4 Setting a Default Channel

- 2.1.5 Unsupported Channels

- 2.2 Managing Filters

- 2.2.1 Creating a Filter

- 2.2.2 Modifying a Filter

- 2.2.3 Deleting a Filter

- 2.2.4 Enabling or Disabling a Filter

- 2.2.5 Organizing Filters

- 2.3 Configuring Preference Settings

3 Administering User Communication Preferences

- 3.1 Managing Business Terms by using Oracle Enterprise Manager

- 3.1.1 Adding or Removing Business Terms

- 3.1.1.1 Adding Business Terms

- 3.1.1.2 Modifying a Business Term

- 3.1.1.3 Removing Business Terms

- 3.2 Configuring Profiles by using Oracle Enterprise Manager

- 3.3 Managing User Data using WLST Commands

4 Integrating User Communication Preferences with your Web Application

- 4.1 Introduction to UCP Web User Interface

- 4.2 Integrating ADF Web Application with UCP

- 4.2.1 Creating a New ADF Application

- 4.2.2 Creating an ADF Web Page

- 4.2.3 Connecting UCP Task Flow Library

- 4.2.4 Adding a Region in the New Page

- 4.2.5 Referencing UCP Libraries

- 4.2.6 Managing Project Deployment Profile

- 4.2.7 Creating Application Deployment Profile

- 4.3 Deploying Your Application

- 4.3.1 Deploy Application

- 4.3.2 Configuring Application Server Connection

- 4.4 Verifying Your Application

5 Using User Communication Preferences Java API

- 5.1 Introduction to UCP Java API

- 5.2 Obtaining Delivery Preferences

- 5.3 Managing Channels

- 5.4 Managing Filters

Preface

This document describes how to use User Communication Preferences services in your web applications.

Audience

This guide is intended for process developers who use User Communication Preferences services to send and receive messages from their applications.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

Related Documents

For more information, see the following documents:

- Release Notes

- Administering Oracle User Messaging Service

- Developing SOA Applications with Oracle SOA Suite

- WLST Command Reference for Infrastructure Components

Conventions

The following text conventions are used in this document:

Convention

Meaning

boldface

Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary.

italic

Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.

monospace

Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

1 Introducing User Communication Preferences

This chapter describes the User Communication Preferences (UCP). It describes how to work with communication channels and to create contact preference rules using messaging filters. This chapter also discusses how to manage communication preferences from a web interface by managing channels and filters. It also provides information for system administrators about configuring UCP; and for developers about integrating their applications with UCP.

Note:
To learn about the architecture and components of Oracle User Messaging Service, see Administering Oracle User Messaging Service.

This chapter includes the following sections:

- Introduction to User Communication Preferences

- User Communication Preferences Terminology

1.1 Introduction to User Communication Preferences

User Communication Preferences allows users who have access to multiple channels to control how, when, and where they receive messages. Users define filters, or delivery preferences, that specify which channel a message should be delivered to, and under what circumstances. Information about a user's channels and filters are stored in any database supported for use with Oracle Fusion Middleware. Since preferences are stored in a database, this information is shared across all instances of UCP in a domain.

UCP does not provide services for message delivery, rather provides user interface and APIs to access and manage a user's channels and delivery preferences. User Messaging Services (UMS) uses UCP services for message delivery. When a message is addressed to a user, UMS acquires the user's delivery preferences from UCP services and sends the message according to the user's preferences. For an application developer, User Communication Preferences provide increased flexibility. By sending messages through UMS, an application is indirectly using UCP service. Applications can also directly access UCP services by calling UCP APIs to access and manage a user's preferences and by integrating with UCP using task flow library to provide web user interface.

1.2 User Communication Preferences Terminology

User Communication Preferences defines the following terminology:

- Channel: a combination of delivery type and address. For instance, email bob@example.com and SMS:650333444 are two channels, where Email and SMS are delivery types and, bob@example.com and 6503334444 are the delivery addresses.

- Channel address: one of the addresses that a channel can communicate with.

- Filter: a message delivery preference rule that controls how, when, and where a user receives messages.

- Business term: a named attribute for messages, such as a subject. The fact for a business term can be extracted from messages or supplied by applications and used to compare with a specified value in a filter condition to select the filter.

- Fact: actual value for a business term extracted from messages or supplied by applications.

- Condition: a combination of a business term, an operator and a specified value. The fact about a message is used to compare against the value to evaluate the truth of the condition.

- Action: the action to be taken if the specified conditions in a filter are true, such as do not send message, send to first available channel, or send to all selected channels.

- System term: a pre-defined business term where the fact for the term is automatically supplied by UCP service.

Note:
User Communication Preferences Condition match is not case-sensitive by default. To make it case-sensitive, you must set the JVM system property oracle.ums.userprefs.filter.match-case to true. For more information about this property, refer to User Messaging Service Java API Reference.

2 Managing User Communication Preferences

This chapter describes the User Communication Preferences (UCP). It describes how to work with communication channels and to create contact preference rules using messaging filters. This chapter also discusses how to manage communication preferences from a web interface by managing channels and filters.

Note:
To learn about the architecture and components of Oracle User Messaging Service, see Administering Oracle User Messaging Service.

This chapter includes the following sections:

- Section 2.1, "Managing Communication Channels"

- Section 2.2, "Managing Filters"

- Section 2.3, "Configuring Preference Settings"

2.1 Managing Communication Channels

A communication channel defines an address (such as a phone number) and a type (such as a short message service or SMS) for message delivery.

User Communication Preferences (UCP) creates a few channels automatically for a user based on the user profile settings in the Identity Store. These channels, called as IDM channels, can be used for message delivery. A POPUP channel is automatically created if the corresponding driver is deployed. This channel will be not available when the driver is undeployed. The address value for this channel is the user's login ID. Users cannot modify these channels through the UCP web UI.

Note:
For messaging drivers you cannot specify a channel address with spaces. As the channel address value is the login ID, do not use spaces when you create the login ID for the user.

Alternately, users can create, modify, and delete user-defined channels. These are called USER channels. Any channel that a user creates is associated with that user's system ID. In Oracle User Communication Preferences, channels represent both physical channels, such as mobile phones, and also email client applications running on desktops, and are configurable in the UCP UI.

2.1.1 Creating a Channel

To create a USER channel, perform the following tasks:

1. Click the Create icon as shown in Figure 2-1, located in the toolbar under Available Channels.

Figure 2-1 The Create Icon

The Create Channel dialog box appears as shown in Figure 2-2.

Figure 2-2 Creating a Channel

2. Enter a name for the channel in the Name field.

3. Select the delivery type from the Type drop-down list.

4. Enter the address appropriate to the delivery type you selected.

5. Select the Default check box if you want to set this channel as a default channel. You can have multiple default channels.

6. Click OK to create the channel. The new channel appears in the Available Channels section. The Available Channels page enables you to modify or delete the channel.

2.1.2 Modifying a Channel

To modify a USER channel, select it from the list of Channels in the Available Channels section, and click the Modify icon as shown in Figure 2-3.

Figure 2-3 The Modify Icon

The Modify Channel page appears as shown in Figure 2-4. This page enables you to change the channel properties described in Section 2.1.1, "Creating a Channel".

Figure 2-4 Modifying a Channel

2.1.3 Deleting a Channel

To delete a USER channel, select the channel from the list of channels in the Available Channels section, and click the Delete icon as shown in Figure 2-5.

Figure 2-5 The Delete Icon

Certain channels are based on information retrieved from your user profile in the identity store. These are called IDM channels. Users are not allowed to modify or delete such channels through this interface. The only operation that can be performed on such a channel is to make it the default channel. IDM channel addresses are managed through Identity Management System.

Note:
You must not delete a channel if it is being used in any filter, as this will cause errors. Before deleting the channel, ensure that the channel is released from all filters.

2.1.4 Setting a Default Channel

You can configure one or more channels as default channels. You can set a channel as default messaging channel either during channel creation or after channel creation directly from the list of channels.

To set a channel as default, select that channel from the list of channels, and click the default icon as shown in Figure 2-6. A checkmark appears next to the selected channel, designating it as a default means of receiving messages. Repeat this procedure to add additional default channels, if required.

Figure 2-6 The Default Icon

To remove the default setting of a channel already set as default, select that channel from the list of channels, and click the Remove icon shown in Figure 2-7.

Figure 2-7 The Remove Default Icon

Note:
The Business Email channel that is automatically created from the Identity Store attribute is set as a default channel. You cannot remove the default setting for the Business Email channel.
For more information about configuring LDAP settings, see Configuring User Messaging Service Access to LDAP User Profile in Administering Oracle User Messaging Service.

2.1.5 Unsupported Channels

A channel may not be supported when the service for the particular channel delivery type is not available, for instance, when the driver for the delivery type is disabled. An unsupported channel is indicated by a warning exclamation mark icon at the end of the channel name as shown in Figure 2-8. When the service for the delivery type becomes available later, the warning mark will disappear and the channel can be used again.

Figure 2-8 The Unsupported Channel

2.2 Managing Filters

A filter is composed of two primary sections, condition (or the If section) and action (or the Then section). For each incoming message, the filters are evaluated to determine the appropriate filter that must be selected for handling the message. The condition section determines the circumstances under which a filter is selected; while the action section specifies how the message is handled if the filter is selected.

Figure 2-9 Messaging Filters

2.2.1 Creating a Filter

To create a filter, perform the following tasks:

1. Click the Create icon as shown in Figure 2-9, located in the toolbar under Messaging Filters. The Create Filter page appears as shown in the following figure.

Figure 2-10 Creating a Filter

2. Enter a name for the filter in the Name field.

3. If needed, enter a description of the filter in the Description field.
The checkbox allows you to temporarily enable or disable a filter.

4. Select whether messages must meet all of the conditions or any of the conditions by selecting either the match all of the following conditions or match any of the following conditions options.

5. Create a filter condition in the If section as follows:

1. Click the Create icon located in the toolbar. The Create Condition dialog box appears.

2. Select the message's attribute from the Attribute drop-down list that lists the available Business terms. Refer to Section 3.1, "Managing Business Terms by using Oracle Enterprise Manager" for a list of these attributes.

3. Combine the selected attribute with one of the comparison operators from the Operator drop-down list.

4. Enter an appropriate value in the Operand field. This is the value that the fact for the selected attribute is used to compare with, using the selected operator.
For instance, if you select the Date attribute, select one of the comparison operators and then select the appropriate date from the date chooser. If you choose a range operation such as is between, then two operand fields will appear for entering lower and upper limit values.

5. Click OK to add the condition to the table.

6. Repeat the above mentioned steps to add more filter conditions. To delete a filter condition, select the condition from the list of conditions in the table, and click the Delete icon as shown in Figure 2-5.

7. When a message is addressed to a user, the If section of the user's filters are evaluated against the facts in the message. After a filter is selected in the If section, the Then section determines how the message will be handled. The Then section consists of an action type and a list of channels. Select one of the following actions:

- do not send message -- Select this option to block all messages, that meet the filter conditions, from being sent.

- send to first available channel (Failover in the order) -- Select this option to send messages matching the filter criteria to a preferred channel (set using the up arrow and down arrow) or to the next available channel.

- send to all selected channels -- Select this option to send messages to every listed channel.

8. If you have selected the action type to send messages, then you must select channels from the drop-down list in the toolbar to add to the action channel list for this filter. After selecting a channel, click Add as shown in Figure 2-11. To delete a channel, select the channel from the channel list in the action table and click Delete as shown in Figure 2-5.

Figure 2-11 The Add Icon

9. If required, use the up arrow and the down arrow to prioritize channels. If you select send to first available channel, then the top-most channel that is available will receive messages meeting the filter criteria.

10. Click OK to create the filter, or Cancel to discard the filter.

2.2.2 Modifying a Filter

To modify a filter, select the filter from the list of messaging filters, and click Modify as shown in Figure 2-3. The Modify Filter page appears. Except the filter name, this page enables you to add or change the filter properties described in Section 2.2.1, "Creating a Filter".

2.2.3 Deleting a Filter

To delete a filter, select the filter from the list of messaging filters, and click Delete as shown in Figure 2-5.

2.2.4 Enabling or Disabling a Filter

You can temporarily enable or disable a filter. A filter that is disabled will be skipped during the message processing. You can disable or enable a filter in either of the following ways:

- Select the filter from the list of messaging filters. If the selected filter is enabled, the disable filter icon appears in the toolbar as shown in Figure 2-12. Click this icon to disable the filter.

Figure 2-12 The Disable Filter Icon

If the selected filter is disabled, the enable filter icon appears in the toolbar as shown in Figure 2-13. Click this icon to enable the filter.

Figure 2-13 The Enable Filter Icon

- You can also enable or disable a filter from the filter creation or modification dialog box.

2.2.5 Organizing Filters

You can prioritize the order of the filters in the list by selecting the filter and moving them up or down in the list, using the up or down arrow icons in the toolbar. During message processing, filters are evaluated in the order from top to bottom in the list until a filter matching the condition is found. If a matching filter is not found, the default channel is used for message delivery with the send to all selected channels action type.

Note:
An unsupported channel in a filter will not be used as if there is no such a channel in the filter. See Section 2.1.5, "Unsupported Channels".

2.3 Configuring Preference Settings

You can configure your preference settings by accessing the Settings tab located in the upper right area of the UCP UI. You can set the following parameters:

- Locale Source: Select From Identity Store or From Your Browser.

- Accessibility Mode: Select Standard or Screen Reader.

- Select the Highlight Text checkbox if you want the text to be displayed in high contrast.

- Select the Larger Text checkbox if you want the text to be displayed in large fonts.

- Profile Name: Select a profile from the drop-down list.

- Click Save Your Changes in order to save the changes you made, or click Reset to Default to restore default settings.

Figure 2-14 Configuring Settings

3 Administering User Communication Preferences

This chapter provides information for system administrators about configuring User Communication Preferences (UCP); and for developers about integrating their applications with UCP. It also provides information about business terms that are used during profile configuration.

You can configure profiles and manage user data using WebLogic Scripting Tool (WLST). This chapter discusses the following topics:

- Section 3.1, "Managing Business Terms by using Oracle Enterprise Manager"

- Section 3.2, "Configuring Profiles by using Oracle Enterprise Manager"

- Section 3.3, "Managing User Data using WLST Commands"

3.1 Managing Business Terms by using Oracle Enterprise Manager

As mentioned earlier in this document, each filter condition is defined against a Business Term. UCP supports the business terms as listed in the table below. A business term consists of a name, a data type, and an optional description.

Table 3-1 lists the pre-defined business terms supported by User Communication Preferences.

Table 3-1 Pre-defined Business Terms for User Communication Preferences

Business Term

Data Type

Organization

String

Priority

String

Application

String

Application Type

String

Expiration Date

Date

From

String

To

String

Customer Name

String

Customer Type

String

Status

String

Amount

Number (Decimal)

Due Date

Date

Process Type

String

Expense Type

String

Total Cost

Number (Decimal)

Processing Time

Number (Decimal)

Order Type

String

Service Request Type

String

Group Name

String

Source

String

Classification

String

Duration

Number (Decimal)

User

String

Role

String

Subject

String

Service Name

String

Process Name

String

System Code

String

Error Code

String

Occurrence Count

Number (Decimal)

UCP supports two System terms listed in Table 3-2. System terms are pre-defined business terms. Administrators cannot extend the system terms. System terms are available for defining conditions though they are not managed here. The facts for System terms are automatically obtained based on the current time and user's time zone. Thus, unlike other business terms, during message processing, applications do not need to supply facts for System terms.

Table 3-2 System Terms Supported by User Communication Preferences

System Term

Data Type

Supported Values

Date

Date

Date is accepted as a java.util.Date object or string representing the number of milliseconds.

Time

Time

A 4-digit integer to represent time of the day in HHMM format. First 2-digit is the hour in 24-hour format. Last 2-digit is minutes.

3.1.1 Adding or Removing Business Terms

Oracle Enterprise Manager enables you to add or remove the business terms used to construct message filters in User Communication Preferences.

To add, modify, or remove business terms, you must open the User Messaging Server home page in Oracle Enterprise Manager and select Server Properties from the drop down menu as shown in the following figure.

The Server Properties page appears as shown in the following figure. This page lists the existing business terms, and allows the user to add, modify, or remove business terms. All existing business terms are listed in the Messaging Preference Business Terms section.

3.1.1.1 Adding Business Terms

To add a business term to User Communication Preferences, perform the following tasks:

1. On the Server Properties page, click Add in the Messaging Preference Business Terms section. The Add Business Term page appears as shown in the following figure.

2. Enter a descriptive name for the business term.

3. Select a data type (string, decimal, or date).

4. Click OK. This will add a business term to User Communication Preferences.

3.1.1.2 Modifying a Business Term

To modify an existing business term, select the business term from the list and click Edit. After modifying the details, click OK to confirm.

3.1.1.3 Removing Business Terms

To remove a business term in User Communication Preferences, perform the following tasks:

1. Select the business term from the list.

2. Click Remove.

3. Click OK in the confirmation screen to remove the selected business term.

Note:
You must not remove a business term if it is being used in any filter, as this will cause errors.

3.2 Configuring Profiles by using Oracle Enterprise Manager

Multiple applications may consume a single instance of UCP services. However, not all applications might consume the same set of UCP features. To meet various requirements of different applications, UCP features are virtualized into profiles. This enables each application to target a specific profile that contains a subset of UCP features.

Each profile is identified by a profile ID. Oracle UCP service provides APIs for a client application to target to a profile, by specifying a profile ID. After upgrading, legacy applications consuming old UCP APIs, without profile ID, will target to a default profile sharing with other applications that targets to the default profile. It is recommended to migrate legacy applications to use latest APIs so that each application can target to a specific profile without sharing with other applications. For more information about UCP API, refer to User Messaging Service Java API Reference.

You can manage messaging preferences profiles using Oracle Enterprise Manager. This interface lists the existing configured profiles, and allows the user to add, modify, or remove profiles. To configure preference profiles, perform the following tasks:

1. Open the User Messaging Server home page in Oracle Enterprise Manager and select Server Properties from the drop down menu.
The Server Properties page appears as shown in the following figure. All existing profiles are listed in the Messaging Preference Profiles section.

2. To add a new profile, click the Add icon in the Messaging Preference Profiles section. A dialog box appears as shown in the following figure. You must specify the configuration details to add a new profile.
Click OK to save the new profile.

You can define the profile features by selecting a Locale Source, availability of IDM and/or User Channels and a subset of Business Terms. UCP renders the web user interface based on the locale from three different locale sources, namely Client Browser, Identity Store and System Default. The Locale Source field provides a choice from two sources - Locale from Client Browser and, Locale from Identity Store. This determines the locale lookup sequence for the UI rendering. If Locale from Client Browser is selected, then the lookup sequence will be (1) Locale from Client Browser, (2) Locale from Identity Store and (3) System Default Locale. Otherwise, the sequence will be (1) Locale from Identity Store, (2) Locale from Client Browser and (3) System Default Locale. In each sequence, UCP renders the UI using the first supported locale.

In the above figure, the check box for User Channel defines the availability of user defined channels for that particular profile. If the check box is selected, then the users are allowed to create User Channels from the UCP web user interface. The check box for IDM Channel determines the availability of auto-synced channels from Identity Store. Channels are the properties of users. These check boxes determine the visibility of channels for each profile.

Each Profile encapsulates a subset of Business Terms listed under Selected Business Terms as shown in the above figure. In this example, only three terms - From, To, and Subject, are selected. To add more terms, select them from the Available Business Terms list on the left and click the right arrow (>) to move them to the Selected Business Terms list. Only selected Business Terms are available for users to define conditions for filters in a particular profile. This means that, on defining filter conditions only the selected Business Terms will be seen in the Attribute drop-down list in UCP web user interface.

3. To modify an existing profile, click the Edit icon in the Messaging Preference Profiles section. A dialog box appears as shown in the following figure. You must specify the configuration details to edit the profile.
Click OK to save the profile.

4. To remove the messaging preference profile, select the profile from the list of profiles and click Remove.

5. Click Apply to apply changes in the User Messaging Server instance. Restart the server for the changes to take effect.

3.3 Managing User Data using WLST Commands

UCP provides a command line scripting tool, Oracle WebLogic Scripting Tool (WLST), for downloading user preferences data from the UCP repository to the specified XML file, for uploading user preferences data from an XML file into the UCP repository, or for deleting user preferences from the UCP repository.

For information about how to use WLST for uploading or downloading user preferences data, see "manageUserCommunicationPrefs" in Oracle Fusion Middleware Core Components WLST Command Reference. For information about how to get started with WLST, refer to section Getting Started Using the Oracle WebLogic Scripting Tool (WLST) in the Oracle Fusion Middleware Administering Oracle Fusion Middleware.

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:

- Introduction to UCP Web User Interface

- Integrating ADF Web Application with UCP

- Deploying Your Application

- 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:

1. Open the Oracle JDeveloper 12c wizard. Select New Application from the Application Navigator on the left pane. A New Gallery window appears.

2. 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.

3. 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:

1. In the left window pane, right-click ViewController to display the context menu.

2. In the ViewController context menu, from the New menu, select Page. The Create JSF Page window appears as shown in the following figure.

3. In this wizard, enter the file name, for example, MyPage.jspx. From the Document Type menu, select JSP XML.

4. From the Page Layout menu, select Create Blank Page. Click OK. The new MyPage.jspx is created.

5. 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.

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:

1. 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.

2. 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.

3. Enter the connection name, for example, UCP Task Flow.

4. 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.

5. 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:

1. Click the Source tab of the newly created page, MyPage.jspx.

2. 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.

3. Select Region from the context menu. A confirmation window appears.

4. Click Add Library. The Edit Task Flow Binding wizard appears.

5. 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:

1. Right-click the ViewController node located in the navigation pane. A context menu appears.

2. From the context menu, select New, and click From Gallery. The New Gallery wizard appears.

3. 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.

4. 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

5. 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.

6. 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>

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:

1. You must first create a project deployment profile. Right-click the ViewController node from the navigation pane. A context menu appears.

2. From the context menu, click Deploy, and select New Deployment Profile. The Create Deployment Profile wizard appears.

3. 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.

4. 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.

5. 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.

4.2.7 Creating Application Deployment Profile

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

1. 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.

2. 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.

3. From the navigation tree, select Application Assembly.

4. In the right pane, expand the ViewController.jpr node and select webapp1. to include it in the application as shown in the following figure.

5. 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:

1. From the Applications drop-down list, select Deploy and click MyApp from the context menu. The Deploy MyApp wizard appears.

2. In the Deployment Action screen, select Deploy to Application Server and click Next.

3. 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:

1. From the Applications drop-down list, select Deploy and click MyApp from the context menu. The Deploy MyApp wizard appears.

2. In the Deployment Action screen, select Deploy to Application Server and click Next.

3. In the Select Server screen, click the plus icon located at the top right corner.
The Create Application Server Connection wizard appears.

4. In the Connection Name field, enter your server connection name, for example, MyServer. Click Next.

5. In the Authentication screen, enter your application server's admin Username and Password. Click Next.

6. In the Configuration screen, specify the host name, port numbers and, domain name as shown in the following figure.
Click Next.

7. 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.

8. 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

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.

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.

5 Using User Communication Preferences Java API

This chapter describes how to consume the User Communication Preferences (UCP) services in your application by using the UCP Java APIs.

For more information about APIs and interfaces for UCP services, refer to User Messaging Service Java API Reference.

This chapter includes the following sections:

- Introduction to UCP Java API

- Obtaining Delivery Preferences

- Managing Channels

- Managing Filters

5.1 Introduction to UCP Java API

User Communication Preferences (UCP) services can be consumed directly or indirectly from your application. To consume UCP services indirectly, you must call UMS API by sending messages addressed to USERs. UMS will use UCP services to find the best channels according to the users' preferences for message delivery. For more information, see Oracle® Fusion Middleware Developing Applications with Oracle User Messaging Service. When using UMS API, by default, your application is targeting the default UCP profile. To target a specific profile, you must use oracle.sdp.messaging MessageInfo.setProfileId(String profileId) to set the profile when sending a message to a user.

If you want to consume UCP services directly, then you must call UCP Java API. For instance, if you want to control the message format depending on the delivery type of the channel that a user prefers, then you are required to consume the UCP services directly. Or for instance, if you want to build a new application to send messages to the users of your application on certain events, then you can programmatically create a default email channel for each user using the UCP API to ensure that each user receives the message initially upon the deployment of your application. A user may change his preferences later if he does not want the email as his default channel.

UCP Java APIs provide program interface for implementing applications to consume UCP services. UCP also provides Java APIs for managing channels and filters. The Java interface, oracle.ucs.userprefs.UserCommunicationPreference is the primary interface for clients to access UCP services. The oracle.ucs.userprefs package contains the User Communication Preferences API classes. For more information, refer to User Messaging Service Java API Reference. This is the root interface for managing user's preference objects such as addresses, filtersets, etc. For more information about APIs and interfaces for UCP services, refer to User Messaging Service Java API Reference.

5.2 Obtaining Delivery Preferences

A user's delivery preferences can be obtained by invoking the Java method getDeliveryPreference(String guid, String profileID, Map>String,Object> facts), where guid is case-sensitive. The profileID parameter, introduced in 12c, is used to target user preferences for a specific profile. It is recommended that each application targets a specific profile. There is a default profile ID that can be acquired by applications by calling the getDefaultProfileId method. For applications that invoke the 11g APIs (without a Profile ID), the default profile is automatically used. Finally, applications calling this API must provide all the necessary facts so that UCP can select a matched filter in the target profile. The facts are in a Map<String,Object> of name/value pair where the name is the business term and the key in the map. For more information about using this API, refer to User Messaging Service Java API Reference.

The following code snippet demonstrates how to obtain the delivery preferences for testUser1:

// Obtain a UserCommunicationPreference object
UserCommunicationPreference ucp = UserPrefsServicesFactory.createUserCommunicationPreference();

// Set target user ID
String userId = ”testUser1”;

// Specify the Profile ID, or default id from ucp.getDefaultProfileId()
String profileId = ”soa”;

// Add all facts into Hashtable facts. Facts for Date and Time are not needed.
Map <String, String> facts = new HashMap<String, Object>();
facts.put(”Application”, ”BPEL”);                   // Add application name
facts.put(”Due Date”, new Date());                        // Use current date
facts.put(”Amount”, new Double(”678.00”));          // Set number for 678

// Invoke getDeliveryPreference() function with userId, profileId and and facts.
DeliveryPreference dp = ucp.getDeliveryPreference(userId, profileId, facts);

// Retrieve Action Type and delivery Channels from the returned DeliveryPreference object.
ActionType at = dp.getActionType();              //Get Action Type
Vector <DeviceAddress>  channels = dp.getDevices();   //Get delivery Channels

5.3 Managing Channels

UCP provides an automatic channel management feature to sync UCP repository with the Identity Store (usually, LDAP). When an email address is added to the Identity Store, an EMAIL channel corresponding to that email address is automatically created in the UCP repository. This channel is removed from the repository when the corresponding email address is deleted from the Identity Store. UCP automatically creates channels for email, IM, business, home and mobile phones. These channels are called IDM Channels.

Since these channels are automatically managed by UCP, applications must not attempt to create or remove them. Applications are allowed only to set or unset these channels as default channels. However, applications can create, modify, or remove USER channels using APIs such as, createDeviceAddress, getDeviceAddresses, etc. A channel can be flagged as a default channel using the setDefaultChannel API.

The following code snippet demonstrates how to create a communication channel for a user, testUser1 with a particular email address:

// Create an email channel for testUser1
DeviceAddress channel = ucp.createDeviceAddress(”testUser1”,               // User ID
”myEmail”,                        // Channel name
DeliveryType.EMAIL,             // Delivery Type for email
”myemail@somecompany.com”);        // Email address
ucp.save(channel);      // without this line, the Channel will not be persisted in UCP repository

The channel name must be unique for each user. The combination of Delivery Type and Delivery Address must also be unique for each user. Following are some sample code snippets that demonstrate how to manage a channel:

// Set the Channel as a default Channel
ucp.setDefaultAddress(”testUser1”,                // User ID
”soa”,                  // Profile ID
channel);                     // Channel to be flagged

// Unset a default Channel
ucp.removeDefaultAddress(”testUser1”,             // User ID
”soa”,                   // Profile ID
channel);              // Channel to be unset

// Modify the Channel's address
channel.setAddress(newemail@somecompany.com);
ucp.save(channel);      // without this line, the change will not be persisted in UCP repository

// Remove the Channel
ucp.delete(channel);

5.4 Managing Filters

Filters are managed in a set for each profile. The following code snippet demonstrates how to create a messaging filter for a user, testUser1 for the soa profile.

// Get, or create if not exist, user's Filter Set for Profile ”soa”
FilterSet  filterSet = ucp.getFilterSet(”testUser1”        // User ID
”soa”);               // Profile ID

// Create a new Filter
Filter  filter = filterSet.createFilter(”Test Email Filter”);      // Create a new Filter named ”Test Email Filter”
filter.setConditionType(ConditionType.MATCH_ANY).        // Set the Condition Type to logical OR

// Create a new Condition
Condition  condition = filter.createCondition();         // Create a new Condition first
Map<String, BusinessRuleTerm> terms = ucp.getBusinessterms();
BusinessRuleTerm term = terms.get(”Subject”);      // Business Term for ”Subject”
condition.setFilterTerm(term);
condition.setTermOperation(TermOperationType.Contains);
condition.setOperandOne(”approved”);              // Set value ”approved”
ArrayList<Condition> conditions = new ArrayList<Condition>();
conditions.add(condition);
filter.setConditions(conditions);                       // Add the Condition list to the Filter

// Set Action Type
filter.setActionType(ActionType.SERIAL);                // Set Action Type for SERIAL

// Get all the Channels for ”soa” Profile
Set<DeviceAddress> allAddresses = ucp.getDeviceAddresses(”testUser1”,   // User ID
”soa”);             // Profile ID
ArrayList<DeviceAddress> channels = new ArrayList(allAddresses);      // Convert to a List
filter.setDeviceAddressList(channels);                  // Add to the Filter as target Channels

// Add the Filter to the Filter Set
filterSet.addFilter(filter);

// Finally persist the FilterSet object
ucp.save(filterSet);                            // Required to persist the Filter

To deploy your application, you must reference the shared library oracle.sdp.client from your application's development descriptor. The application must be deployed in the same domain with the UCP service.

Though UCP provides Java APIs for applications to manage channels and filters, it is recommended that users manage their preferences through UCP web interface integrated in their web application using the UCP task flow library.

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2018, Oracle and/or its affiliates. All rights reserved.

License Restrictions Warranty/Consequential Damages Disclaimer

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Warranty Disclaimer

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

Restricted Rights Notice

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

Hazardous Applications Notice

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Trademark Notice

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

Third-Party Content, Products, and Services Disclaimer

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.

Pre-General Availability Draft Documentation Notice

If this document is in public or private pre-General Availability status:

This documentation is in pre-General Availability status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.

Private Pre-General Availability Draft Documentation Notice

If this document is in private pre-General Availability status:

The information contained in this document is for informational sharing purposes only and should be considered in your capacity as a customer advisory board member or pursuant to your pre-General Availability trial agreement only. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described in this document remains at the sole discretion of Oracle.

This document in any form, software or printed matter, contains proprietary information that is the exclusive property of Oracle. Your access to and use of this confidential material is subject to the terms and conditions of your Oracle Master Agreement, Oracle License and Services Agreement, Oracle PartnerNetwork Agreement, Oracle distribution agreement, or other license agreement which has been executed by you and Oracle and with which you agree to comply. This document and information contained herein may not be disclosed, copied, reproduced, or distributed to anyone outside Oracle without prior written consent of Oracle. This document is not part of your license agreement nor can it be incorporated into any contractual agreement with Oracle or its subsidiaries or affiliates.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.