4
Administering Unified Messaging

This chapter discusses how to administer your Unified Messaging system. The following topics are included:

The Administrator's Inbox

An administrator account, named Helpdesk, provides the administrator with a separate inbox for receiving, responding to, and storing support requests. This inbox is created as part of the Unified Messaging installation process.

Creating New Accounts for Users

Before a user can log in, the administrator must create and activate the user's account using an instance of the Session class. Use the createUser() method to create a new customer account. Here is a snippet of code from the admin_con_newUser.jsp template. This form gathers various attributes and sends them to the admin_createUser.jsp template:

...
<form name=newUserForm action="<%= 
response.encodeUrl("admin_createUser.jsp") %>"
    target=Result method=post>
<table border=0 cellspacing=0 cellpadding=0 width=100%>
...
<td class=fieldData nowrap><input type=text 
name=CUSTOMER_NAME value=""
    size=13><span class=reqField>*</span></td>
...
<td class=fieldData nowrap><input type=text name=PHONE value="" 
size=13><span
    class=reqField>*</span></td>
...
<td class=fieldData nowrap><input type=text name=FAX value="" 
size=13><span
    class=reqField>*</span></td>
...
<td class=fieldData nowrap><input type=text name=USER_NAME 
value="" size=13><span
    class=reqField>*</span></td>
...
<td class=fieldData nowrap><input type=text name=PIN value="" 
size=13><span
    class=reqField>*</span></td>
...
<td class=fieldHeader nowrap>Protocol</td>
<td class=fieldData nowrap><input type=text name=EML_PROTOCOL 
value="" size=4><span
    class=reqField>*</span></td>
<td class=fieldData nowrap><input type=text name=VML_PROTOCOL 
value="" size=4></td>
<td class=fieldData nowrap><input type=text name=FAX_PROTOCOL 
value="" size=4></td>
...
<td class=fieldHeader nowrap>Address</td>
<td class=fieldData nowrap><input type=text name=EML_ADDRESS 
value="" size=13><span
    class=reqField>*</span></td>
<td class=fieldData nowrap><input type=text name=VML_ADDRESS 
value="" size=13></td>
<td class=fieldData nowrap><input type=text name=FAX_ADDRESS 
value="" size=13></td>
...
<td class=fieldData nowrap><input type=text name=EML_USERID 
value="" size=13><span
    class=reqField>*</span></td>
<td class=fieldData nowrap><input type=text name=VML_USERID 
value="" size=13></td>
<td class=fieldData nowrap><input type=text name=FAX_USERID 
value="" size=13></td>
...
<td class=fieldHeader nowrap>Password</td>
<td class=fieldData nowrap><input type=text name=EML_PASSWORD 
value=""
    size=13><span class=reqField>*</span></td>
<td class=fieldData nowrap><input type=text name=VML_PASSWORD 
value="" 
     size=13></td>
<td class=fieldData nowrap><input type=text name=FAX_PASSWORD 
value="" 
     size=13></td>
...
</table>
</form>
...

This is the simple call to createUser() in admin_createUser.jsp:

umSession.createUser(att, val);

Updating Existing Accounts

When the administrator needs to update an account, the first step is to search through the list of customers to access the correct customer record. For this task, use the getAdministratorList method in the Session class.

The results of this search may be multiple Unified Messaging accounts, so to find the correct account, you must iterate through the AdministratorList object. The AdministratorList object is a list of Settings objects. Most of the attributes in the Settings class may be changed by either the user of the account or the administrator. For a list of Settings attributes and HTML samples, refer to the Javadoc for oracle.um.sdk.Settings.

This example includes two parts. The first example shows how to search for a Unified Messaging customer.

<%
String searchID = request.getParameter ("searchID")
String searchOp = request.getParameter ("searchOp")
String searchVal = request.getParameter ("searchVal")
Session umSession = (Session) session.getValue (""umSession")
AdministratorList admList = umSession.getAdministratorList (searchID, searchVal, 
searchOp);
%>

The second HTML page shows how to update that customer's password:

<%
Settings userSettings = admList.getElement (0);
String[]att = newString [1];
String[]val = newString [1];
att[0] = "password";
val[o] = "new_password";
userSettings.set (att, val);
userSettings.update ();
%>

Note that when constructing the search, you may also search on EMAIL_ID, PHONE_ID, or any other column in the UM_ PERSONAL_PROFILE table. For the Operation value, you may use START, EQUAL, or CONTAINS.

Deleting Accounts

To delete a Unified Messaging customer, call the deleteUser method.

<%
Session umSession = (Session)

session.getValue ("umSession");

String phone_id = request.getParameter ("phone_id");
String customer_id = request.getParameter ("phone_id");
umSession.deleteUser (phone_id, customer_id);
%>

The deletion is successful if a record exists that matches the specified PHONE_ID and CUSTOMER_ID. Otherwise, an exception is thrown.

Working with SMS

In addition to receiving e-mail, voice mail, and facsimiles, customers who use pagers will want to be notified of the arrival of important messages. The Short Messaging Service (SMS) provides a connection to the SMS message store that allows customers to send and receive these short pager messages, which are limited to about 150 characters in length.

There are four ways an SMS message could be initiated from UM:

Scenario 1: During account activation, UM sends a registration code to the subscriber's pager.

Scenario 2: UM users with the notification feature activated are notified of the arrival of new messages.

Scenario 3: UM users can send SMS messages from the UM Internet client running on a Web browser.

Scenario 4: UM users can request that the next portion of e-mail text be displayed on the pager. (UM users can also originate an e-mail message from a pager, when the pager system includes this function.)

To send an SMS message, first create an SMS connection:

<%
SMS smsconn = umSession.getSMSConnection ();
%>

Then, make the following call to smsconn.send:

<%
String receiver = request.getParameter ("receiver");
String message = request.getParameter ("message");
smsconn = send (receiver, message);
%>

There is an outbound SMS process that handles SMS messages originating from UM. In Scenario 1 and Scenario 3, the SMS process passes the request from its input queue to the SMS gateway process for delivery. In Scenario 2, the SMS process checks to see if the notification rule is active and if the arrived message passes the user's notification rule. If the message passes both checks, SMS passes the contents of the e-mail (or the initial portion of e-mail, if it exceeds the SMSC buffer limitation) to the SMS gateway for delivery. In Scenario 4, SMS receives the request from an inbound SMS process and passes the next portion of the e-mail content to the SMS gateway process.

For inbound SMS delivery, the SMS inbound process checks to see whether the request is a new e-mail message or a request for the next portion of a current e-mail message. If the request is for a new e-mail message, SMS passes the request to the SMTP processor; otherwise, SMS passes the request to the outbound SMS process.

Customers may want to filter their messages based on time, sender, or other categories. The UM notification rules provide this functionality. UM provides API classes you can use to create, modify, and delete notification rules based on filtering options. A sample of creating, modifying, and deleting notification rules can be found in the $ORACLE_HOME/um/templates/um directory, called pref_con_rules.jsp.

Sample code for the scenario where a UM user sends an SMS message from the UM Internet client can be found in $ORACLE_HOME/um/templates/um directory called msg_comp_sms_send.jsp.

Working with LDAP

Your company may already have an LDAP server containing a corporate directory listing both UM users and non-UM users; that is, users who are not part of your UM system. A UM user can search this server to obtain the e-mail address or phone number of both UM users and non-UM users.

You can expose this directory from within Unified Messaging by connecting the LDAP server to your UM application.

Use the GSMDir and GSMAddress classes in the oracle.um.sdk package to work with UM's own directory, as well as external LDAP servers.

An external LDAP server is likely to contain information about users who are not known to the UM system. When displaying information about these users, you will not be able to use the normal methods in GSMAddress class to display the various user properties. To display properties defined by the external LDAP server, you must first know the name of the properties as defined within that LDAP server. Then you can use the generic method to retrieve the values for these properties.

The following example shows how this is done in an HTML template file.

GSMAddress person = dir.getElement (1);

Where dir is of the GSM Dir and is the result of the umsession.getDirectory method.

Set person to the second element returned from searching through the external LDAP server:

person.get("FIRST_NAME");
person.get("ST");
person.get("STREET");

Note that you may need to test your code using all capital letters for the property name.

Using this technique, you can customize your UM application to display data stored on any LDAP server. The only requirement is that you need to know the names of the properties defined for the directory items on the LDAP server.

The default installation of UM will set up the UM system to use the same LDAP server for both the UM directory and a generic directory. See the Unified Messaging installation documentation for information about how to change this server name to point to your own LDAP server.

4 Administering Unified Messaging