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:
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.
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
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);
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.