Skip Headers

Oracle® Communicator User's Guide 10g Release 3 (10.1.3) Part Number E12748-01 |
Home | Contents | Index | Contact Us

Previous | Next
| View PDF

# 5 Configuring Oracle Communicator

This chapter describes how administrators create customized installations of Oracle Communicator. This chapter includes the following sections:

- Setting the Default Values for an Installation of Oracle Communicator

- Customizing the Installer File

- Setting the Oracle Communicator Upgrade Policy

- Configuring Oracle Communicator to Retrieve Resource-Lists Documents

- Enabling File Transfers

## Setting the Default Values for an Installation of Oracle Communicator

You can customize Oracle Communicator installations that populate user accounts with default settings appropriate to the configuration and topology of a particular site. For example, you can distribute installer files to Communicator users that set their accounts to use a SIP proxy with the default address of ourproxy.example.com. You set these defaults by creating an XML file called `customize.xml`. Using a program that supports adding files to a RAR file, you then package this file with the installer file (the self-extracting RAR file called `OracleCommunicatorSetup.exe`) that you distribute to Communicator users.

When a user installs a setup file that includes `customize.xml`, the properties from the customize file are used to overwrite the following two files in the Oracle Communicator install directory:

- Program Files\Oracle\Oracle Communicator\defaults.xml

- Program Files\Oracle\Oracle Communicator\customize\vendor.xml

`defaults.xml` is a template for creating account-specific XML files. These files are updated whenever users modify their configurations through the user interface. As a result, these properties can vary from account to account. For example, one user account-specific XML file may designate the proxy as `beta.testcomany.com`, while another may designate `proxy.example.com`.

`vendor.xml` describes the properties that are the same for all Communicator users.

If you package `customize.xml` with the installer, then the default properties defined in `vendor.xml` and `default.xml` are overwritten by those set in `customize.xml` during installation. For example, if you define an outbound proxy address in `customize.xml`, it will replace the value for the outbound proxy address in `default.xml`. All properties that are not overwritten by `customize.xml` will use default values (that is, either values already present in `defaults.xml` or `vendor.xml`, or values that are generated at runtime).

## Customizing the Installer File

The Oracle Communicator installer includes a template file for `customize.xml` called `customize-sample.xml`. This file documents every property that might require customization. By modifying and renaming this file to `customize.xml` and then packaging it with the installer file as described in "Creating a Customized Installer File", you set the defaults for all of the users in an Oracle Communicator installation.

The `customize-sample.xml` file is divided in two sections: Vendor and Account. In general, Vendor settings apply to every account in a given Communicator installation and cannot be changed by the user. The settings configured in the Account section are used to create an account-specific XML file whenever a user creates a new Communicator account. Some of the properties in a user's account-specific XML file are set using Communicator's Preferences dialog (Figure 5-1).

Figure 5-1 The Oracle Communicator Preferences Dialog

Description of "Figure 5-1 The Oracle Communicator Preferences Dialog"

### Configuring customize.xml

`customize-sample.xml` includes all of the elements needed for creating a custom installer. You can remove any element in the Vendor or Account sections that does not require customization. If you remove an XML element, the system uses a default value documented in `customize-sample.xml`.

Example 5-0 illustrates the structure of `customize-sample.xml`. For the full file, see Appendix A, "The Oracle Communicator Configuration File".

Only include the elements that are appropriate to the topology and configuration of the OCMS installation.

Example 5-1 customize-sample.xml

    <Customize>
    <Vendor>
       <SelfProv>...</SelfProv>
    </Vendor>
    <Account>
       <UseHttps>...</UseHttps>
       <SavePasswordPreference>...</SavePasswordPreference>
       <UseOutboundProxyAddress>...<UseOutboundProxyAddress>
       <OutboundProxyAddress>...<OutbounProxyAddress>
       <Theme>...</Theme>
       <XDMSSettings>...</XDMSSettings>
       <UseRPortForNatTraversal>...</UseRPortForNatTraversal>
       <UseStun>...</UseStun>
       <StunServerAddress>...</StunServerAddress>
       <StunServerPort>...</StunServerPort>
       <LdapServers>...</LdapServers>
       <Provisioning>...</Provisioning>
       <FileTransfer>...</FileTransfer>
       <Notifications>...</Notifications>
       <FileTransferEnabled>...</FileTransferEnabled>
       <UseServerResourceLists>...</UseServerResourceLists>
    </Account>
    </Customize>

#### Enabling User Self-Provisioning

The `<Vendor>` element provides Oracle Communicator users with read-only values. The properties set within this section are the same for all users. Setting the content of the `<SelfProv>` element to 1 enables end users to see the Service Settings menu option. This opens the service provider's Web page URL. See "Setting the Service Provider's Web Page" for more information on configuring this URL.

#### Setting the Outbound Proxy Address

To enable use of the outbound proxy, enter 1 as the content for `<UseOutboundProxy>`. Next, enter the IP address of the outbound proxy server where all requests are sent on the first hop. For example, enter `sip:my.host:5060;transport=tcp`. If you do not specify this value, then a default address of `outbound.<host>` is used instead, where `<host>` is taken from the Oracle Communicator user's SIP address. See also the SIPOutboundProxy attribute of the PresenceSupplierWebService and PresenceConsumerWebService MBeans in Oracle Communication and Mobility Server Administrator's Guide.

#### Setting the Oracle Communicator Skin

The `<Theme>` element sets the default theme for the Oracle Communicator user interface. The current options are Slate, Communicator, and Jazz.

#### Enabling Presence

The `<XDMSSettings>` element and its child elements enable presence for Oracle Communicator users by specifying the address the XDM Server, the presence rules and hard-state settings. The child elements include:

- `<UseHttps>`

  Set to 1 to use HTTPS to connect to the Aggregation Proxy. To enable this secure connection to the server, refer to "Securing the XDMS with the Aggregation Proxy" in Oracle Communication and Mobility Server Administrator's Guide.

- `<Host>`

  The host of the XDMS. For example, enter `your.xdms.domain.com`. For HTTPS, define the host for the Aggregation Proxy.

- `<Port>`

  The port number of the XDMS. For HTTPS, configure the port as the HTTPS port of the Aggregation Proxy host. For example, enter `443`.

- `<RootContext>`

  The root of the XDMS. The default value is `services`. Set `<RootContext>` to `aggregationproxy`, the context root of the Aggregation Proxy, for either HTTP or HTTPS connections to the Aggregation Proxy. If Communicator connects to the Aggregation Proxy using HTTPS (that is, `<UseHttps>1</UseHttps>`), then you must define `<RootContext>` as `aggregationproxy`. If the Aggregation Proxy is not used, then set `<RootContext>` to the default value of `services`.

- `<PresRuleAUID>`

  The ID of the application usage for presrules. The default is `pres-rules`.

- `<PresRuleDocName>`

  The name of the pres-rules document. The default value is `presrules`.

- `<HardStateAUID>`

  The ID of the application usage for PIDF (Presence Information Data Format) manipulation. The default value is `pidf-manipulation`.

- `<HardStateDocName>`

  See also "Presence" and "XCapConfig".

  The document name for pidf manipulation application usage. Unauthenticated users are blocked when no rule is found. The default is `hardstate`.

- `<ResourceListAUID>`

  The application usage id (AUID) of the resource-lists document. The default value is `resource-lists`.

- `<ResourceListsDocName>`

  The name of the resource-lists document The default value is `index`.

  Tip:

  To enable Oracle Communicator to request a user's buddy lists from the XDMS, you must configure the `<ResourceListAUID>` and `<ResourceListsDocName>` elements. You must also set the <UseServerResourceLists> element to 1.

#### Enabling NAT Traversal and Discovery

The `<UseRPortForNatTraversal>`, <UseStun>,`<StunServerAddress>` and `<StunServerPort>` elements are used to enable NAT traversal (that is, to enable a user to connect from behind a router). The latter three properties are used to provide information on the STUN Server, if one is available. Configure these elements as follows:

- `<UseRPortForNatTraversal>`

  Set to 1 to enable use the `rport` parameter specified in RFC 3581. The `rport` parameter, which is in the Via header field, enables the Communicator client to request OCMS to send the response back to the source IP address and port from which the request originated.

  Caution:

  You must set `<UseRPortForNatTraversal>` to 0 for clustered configurations of Oracle Communication and Mobility Server.

- `<UseStun>`

  Set to 1 to enable STUN.

- `<StunServerAddress>`

  The address of the STUN Server.

- `<StunServerPort>`

  The primary STUN port to which to bind for listening for incoming binding requests. The value is UDP port 3478, the default STUN Port as described in RFC 3489.

For more information, see "STUN Service".

#### Enabling Directory Searches

The LDAP server that you define within the `<LdapServers>` element enable Oracle Communicator users to search contact lists through Oracle Communicator's support of LDAPv3. By default, Oracle Communicator does not define an LDAP Server. The child `<LdapServer>` elements have their own children, which specify the LDAP Server accessed by Oracle Communicator users. These include:

- `<Name>`

  The name of the LDAP Server.

- `<Ip>`

  The IP address of the LDAP Server.

- `<Port>`

  The port number of the LDAP Server

- `<BaseObject>`

  The starting point for searches using the DN (Distinguished Name) syntax. For example, enter `dc=oracle,dc=com` to search within oracle.com.

- `<Default>`

  Set this as the default LDAP server if more than one LDAP servers are defined.

- `<useTLS>`

  Set to 1 to use a TLS connection to the LDAP server.

- `<UseAuthentication>`

  Set to 1 to use the DN for authorization.

- `<AuthenticationAttribute>`

  The attribute to use as the DN for authorization. For example, enter `uid`.

- `<SipUriAttribute>`

  Indicates which LDAP schema attribute, if any, should be mapped to the SIP address of a contact.

- `<SipUriProtocolPrefix>`

  If set to 1, this indicates that the LDAP server returns SIP addresses prepended with `sip:`.

- `<SipUriLowercaseTransform>`

  If set to 1, then the SIP address of a contact returned by the LDAP server is put in lower case.

#### Setting the Service Provider's Web Page

Defining the `<Provisioning>` element's child, `<Location>`, defines the service provider's Web page that Oracle Communicator user's to launch from the Service Settings menu item. The value for `<Location>` is a URL.

#### Setting the Upgrade Policy

See "Setting the Oracle Communicator Upgrade Policy".

#### Storing Resource-Lists Documents

To store the resource-lists document on the XMDS, set the `<UseServerResourceLists>` to 1. If the resource-lists document resides on the XDMS:

- The resource-lists document is written to the address specified by the <XDMSSettings> element.

- OCMS performs a full document replacement on the XDMS whenever users change their buddy lists.

- Because OCMS 10.1.3.3 does not support changes to the buddy list document through SUBSCRIBE/NOTIFY, the buddy lists for concurrent sessions of Oracle Communicator may not match. See also "Updating Buddy Lists".

To store the resource-lists document locally as a file, set `<UseServerResourceLists>` to 0.

Caution:

OCMS does not support switching the resource-lists document location from local file to the XDMS. If you change the location from local file to the XDMS during an upgrade, for example, then the resource-lists document is lost.

#### Enabling File Transfers

In order to make File Transfer available to users, you must:

1. Configure File Transfer .ear File

2. Deploy File Transfer .ear File

3. Modify customize.xml

##### Configure File Transfer .ear File

A filetransfer EAR file includes a filetransfer WAR that has a web.xml where all the configurable properties are set namely:

- max-size : indicates the maximum allowed size in bytes of a file transfer; use -1 to indicate no maximum size

- max-connect-time: indicates the maximum length of time each side of the transfer may wait for the other side of the transfer to connect, in seconds

- max-transfer-time: indicates the maximum length of time the transfer may take before timing out, once the other party has connected

One can edit web.xml by opening the EAR and extracting the WAR and re-archiving the WAR with the new web.xml using any of the available archive software. For ex: WinRAR or by using

    jar -xvf and jar -cvf

##### Deploy File Transfer .ear File

Once packaged file transfer EAR can be deployed like any other HTTP servlet on the OC4J container. To deploy follow these instructions:

1. Open EM page. For ex : http://yourip.example.com:<your EM port>/em

2. Click on your ocms node

3. Click on applications tab

4. Click deploy, browse the ear file, select default as the parent application and click next.

5. Give it an application name and a context root. Context root defines the location of the HTTP servlet . For example: the default context root is "/filetransfer". This means that the filetransfer HTTP servlet can be invoked from http://yourip.example.com:<your EM port>/filetransfer . This URL is the location of filetransfer servlet that the admin should point to in Oracle Communicator's customize.xml.

6. Click Next and then click on Deploy.

##### Modify customize.xml

To use file transfer in OC, an admin should make changes to the customize.xml in the installer. He should change the following:

    <!-- enables/disables the file transfer functionality; in order
         to support file transfer you must have the FileTransferServlet
         deployed; the Location should be the full URL of the
         FileTransferServlet (e.g. http://example.com/filetransfer) -->
    <FileTransferEnabled>1</FileTransferEnabled>
    <FileTransfer>
    <Location>http://yourip.example.com:<your EM port>/filetransfer</Location>
    </FileTransfer>

### Creating a Customized Installer File

To create the customized installer file:

1. Download and install an application that supports adding files to a RAR. These instruction use WinRAR (`http://www.rarlab.com/`) as an example.

2. Open the self-extracting RAR file, `OracleCommunicatorSetup.exe`, in WinRAR.

   Figure 5-2 Opening the Oracle Communicator Setup File

   Description of "Figure 5-2 Opening the Oracle Communicator Setup File"

3. Extract `customize-sample.xml` and rename it `customize.xml`.

4. Edit the `customize.xml` file with your specific settings. Typically, you edit all of the server settings to match the deployment. You can comment out or remove the XML elements for those properties for which the default values suffice.

5. Using WinRAR (or another application that manages RAR files), package `customize.xml` with the setup file (`OracleCommunicatorSetup.exe`) using one of the following methods:

   - Open `OracleCommunicatorSetup.exe` in WinRAR (Figure 5-2) and then drag and drop `customize.xml` into `OracleCommunicatorSetup.exe`. In the Archive Name and Parameters dialog (Figure 5-3), select `OracleCommunicatorSetup.exe` as the archive and then click OK.

     Figure 5-3 Adding customize.xml to the Installer

     Description of "Figure 5-3 Adding customize.xml to the Installer"

   - Open `OracleCommunicatorSetup.exe` in WinRAR (Figure 5-2), click Commands and then select Add Files to Archive. In the Select Files to Add dialog, navigate to `customize.xml` using the Browse function and then select `customize.xml`. In the Archive Name and Parameters dialog, select `OracleCommunicatorSetup.exe` as the archive and then click OK. You can either add `customize.xml` back to `OracleCommunicatorSetup.exe` or rename a copy of the setup file and add `customize.xml` to that.

     Note:

     You can also rename the`.exe` file. You can give this file any name.

6. If desired, sign the new self-extracting`.exe` so that users who download it have confidence in the source of the modified installer.

7. Distribute the modified self-extracting`.exe` to end-users.

## Setting the Oracle Communicator Upgrade Policy

This section describes how to configure `upgrade.xml` to specify the upgrade policy for all Oracle Communicator instances installed by end-users.

For upgrading versions 10.1.3.2 or 10.1.3.3 to 10.1.3.4, you must make changes to an existing `upgrade.xml` that you deployed when you made the previous version available to your users.

    <?xml version="1.0" encoding="UTF-8"?>
    <Upgrade>
    <Must>10.1.3.20002</Must>
    <Recommend>10.1.3.40007</Recommend>
    <Interval>86400</Interval>
    <Download>http://example.com/myInstallInstructions.html</Download>
    </Upgrade>

After your users install the 10.1.3.4 version, and you want to upgrade them further to a newer version, you must create another xml file by the name of `notification.xml` and put it in your web browser. Here is a sample:

    <?xml version="1.0" encoding="UTF-8"?>
    <Notification>
    <Upgrade>
    <Must>10.1.3.40007</Must>
    <Recommend>10.1.3.40007</Recommend>
    <Download>http://www.example.com/myInstallInstructions.html</Download>
    </Upgrade>
    <BannerMessage> <MessageID></MessageID> <MessageType></MessageType> <MessageContent></MessageContent>
    </BannerMessage>
    <Interval>86400</Interval>
    </Notification>

You then reference this document within `customize.xml` by defining the `<Notifications>` element that is located in the `<Account>` section. For example, configuring the `<Location>` element to point to upgrade policy results in the retrieval and review of the upgrade policy when a user logs into the newly installed Oracle Communicator. See "customize-sample.xml" for detailed instructions on how to use `notification.xml` for future upgrades.

    <Notifications>
    <!-- 0 disabled, 1 enabled --> <UseNotifications>1</UseNotifications>
    <!-- xml document location --> <Location>http://notification.example.com/notification.xml</Location>
    </Notifications>

If the version of the user's Communicator client is lower than the required version defined in `<Must>` element of the upgrade policy, then Communicator displays a dialog that alerts users to the fact that they must upgrade. (Figure 5-4).

Figure 5-4 The Required Upgrade Dialog

Description of "Figure 5-4 The Required Upgrade Dialog"

Clicking the dialog's More Information button opens the download URL in a default URL. If the user's version is higher than the required version specified in the `<Must>` element, but lower than the version defined in the `<Recommended>` element, then Communicator presents the user with a dialog with that enables the user to open the download URL from the default browser or to ignore this option.

For a Communicator installation that points to the upgrade policy described above, Communicator does not prompt users to upgrade to versions of Communicator greater than, or equal to, both the versions set for the `<Must>` (10.1.3.20002) and `<Recommended>` (10.1.3.0003) elements and will wait the number of seconds specified in `<Interval>` (86400) before retrieving from `upgrade.xml` or `notification.xml` (depending on whether the version installed is the one prior to 10.1.3.4.* or 10.1.3.4+ respectively). The upgrade policy affects users running Versions 10.1.3.20001, 10.1.3.20002, 10.1.3.20003, and 10.1.3.20004 of Communicator as follows:

- 10.1.3.20001: Communicator prompts the user that an upgrade is required. When the user then clicks the button, Communicator is closed and the URL specified in `upgrade.xml` is launched in the default browser.

- 10.1.3.20002: Because the user has the latest required version, but not the latest recommended version, Communicator alerts the user that the recommended version is available (Figure 5-5). The user can then opt to close this dialog or can click a button that launches the upgrade URL in the default browser. Communicator closes when the user clicks this button.

  Figure 5-5 The Recommended Upgrade Dialog

  Description of "Figure 5-5 The Recommended Upgrade Dialog"

- 10.1.3.20003: Communicator does not prompt the user to upgrade.

- 10.1.3.20004: Communicator does not prompt the user to upgrade.

If `upgrade.xml` is not available for some reason (for example, the server is down, the `<VersionControl>` and `<Location>` elements were not specified properly, or a fire wall blocks access to the upgrade document), then the upgrade process will fail silently with no ill effect on the user's experience. The user can login normally.

Note:

It is not possible to ensure that every instance of Communicator running at a site matches the version specified in the `<Must>` element in some situations. For example, a user with a personal fire wall that blocks access to `uprgrade.xml` will never be prompted to upgrade.

## Setting Banners in Oracle Communicator

Administrators can publish a message on the Client by making changes to an .xml file on the server. The .xml file used to make this change is `notification.xml` as described in the version control documentation. Here is a sample `notification.xml`:

    <?xml version="1.0" encoding="UTF-8"?>
    <Notification>
    <Upgrade>
    <Must>10.1.3.40007</Must>
    <Recommend>10.1.3.40007</Recommend>
    <Download>http://www.oracle.com/downloadsample</Download>
    </Upgrade>
    <BannerMessage>
    <MessageID></MessageID>
    <MessageType></MessageType>
    <MessageContent></MessageContent>
    </BannerMessage>
    <Interval>86400</Interval>
    </Notification>

The Administrator must modify the tags within the `BannerMessage` element. Here is a brief description of each tag:

- `MessageID` - every new message the Administrator wants to push out to the Client must have a unique MessageID.

- `MessageContent` - the message text the Administrator wants displayed.

- `Interval` - a time after which the Client gets the message data from server.

- `MessageType` - one of the following:

  - `showforever` - users log on to Oracle Communicator and see the banner message. Users cannot close the banner. Logging on and then on again, or changing themes does not make the message disappear. It persists until a new message (with a new MessageID) is published on the server.

  - `showonce` - users log on to Oracle Communicator and see the banner message. This type of message has a Close button. Clicking the Close button closes the message. If users log out and then log back on, or change themes, the message does not appear again.

  - `normal` - users log on to Oracle Communicator and see the banner message. This type of message has a Close button. Clicking the Close button closes the message. But the next time the user logs on (or upon interval expiration), the new message will still be visible.

## Configuring Oracle Communicator to Retrieve Resource-Lists Documents

The parameters set through the <UseServerResourceLists>, <ResourceListsDocName>, and <ResourceListAUID> attributes enable Oracle Communicator to retrieve a user's buddy list from resource-lists document stored on the XDMS at startup. Oracle Communicator reads the resource-lists document only once, when the user first logs in. Any changes made to the resource-lists document after that initial login (for example, through a different session of Oracle Communicator writing to the server) are not read and may be overwritten.

### Updating Buddy Lists

Oracle Communicator does not support partial updates. Instead, it saves and uploads the entire buddy list document to the XDMS after any modification, such as:

- Adding a buddy.

- Adding a new group.

- Changing a buddy's contact information.

- Changing a group name.

- Moving a buddy to another group.

Because OCMS does not support `NOTIFY` operations (it uses `XCAP PUT` instead), buddy lists from different instances of Oracle Communicator may not be in synchronization. For example, Alice has two running instances of Oracle Communicator: one on her home computer and one on her office computer. If Alice adds Bob as a contact from her home computer, her office computer will not automatically be notified of this change. Without restarting the office instance of Oracle Communicator, Alice adds Charlie as a contact from her office computer. Because the office instance of Oracle Communicator has an older XML document (one that does not include Bob), Charlie is added to Alice's buddy list, but Bob is removed, because OCMS replaces the entire buddy list document whenever a user modifies the contact list in any way.

### Upgrading Buddy Lists

Contacts are stored locally in Communicator 10.1.3.2; buddies are stored as VCARDS in a `.dat` text file that is located in the user's account properties folder (typically located at `Documents and Settings\<username>\Application Data\Oracle Communicator`). Communicator 10.1.3.3 stores buddies and groups in a new XML format which may be stored as a local file or on the XDMS. Because of this change, Communicator 10.1.3.2 buddy lists must be upgraded to the new format.

#### Prompting Users to Upgrade to XDMS-Stored Buddy Lists

Once you configure the `<UseServerResourceLists>`, `<ResourceListAUID>`,and `<ResourceListsDocName>` attributes to support storage of the resource-lists document to the XDMS, Oracle Communicator 10.1.3.3 performs this upgrade as follows:

1. When the user logs into Oracle Communicator 10.1.3.3, Communicator determines if a `.dat` file is still present. A `.dat` file indicates the user has not yet upgraded to the 10.1.3.3 resource-lists document.

2. If a `.dat` file is present, Communicator prompts the user with a message asking if he or she wishes to upgrade their buddy list. This message is needed for users who have multiple Communicator instances, such as separate instances for home and work that store resource-lists documents on the XDMS. Because OCMS does not support partial changes or document merging, users must select a particular buddy lists to be saved. Users with multiple instances of Oracle Communicator must answer "no" to the upgrade message for every instance except for the one that the user selects to upload.

3. If the user chooses to upgrade the buddy list, any existing 10.1.3.3 buddy list is removed. The user's buddies and groups will be migrated to the resource-lists document.

   If there are no problems, the .`dat` file is given the additional `.bak` extension. If there are problems reading the .`dat` file, then Communicator informs the user that problems arose and uses an empty buddy list. Communicator renames the`.dat` file with the .`dat.bak` extension. If Communicator encounters problems when saving this file, it alerts the user that there are problems saving the file and does not rename the`.dat` file with the`.dat.bak` extension. This enables the user to the upgrade in the future. If the user chooses not to upgrade the buddy list, then the existing `.dat` file is renamed with a `.dat.bak` extension.

Note:

This upgrade is only performed after users log into the new version of Oracle Communicator and are authenticated to the XDMS for the first time.

## Enabling File Transfers

The <FileTransfer> and <FileTransferEnabled> elements enable Oracle Communicator users to exchange files by connecting to the FileTransferServlet. This servlet does not reside on the same OC4J container; it is instead hosted on a separate OC4J 10.1.3.4 (or 10.1.3.2) container (illustrated in Figure 5-6). See also "Deploy File Transfer .ear File"

Figure 5-6 File Transfer Topology

Description of "Figure 5-6 File Transfer Topology"

### Transferring Files

Oracle Communicator enables users to send files through the following options:

- Right-clicking a contact and then selecting Send File.

- Entering the SIP address in the Quick Dial box and then selecting Send File.

- Selecting File and then Send File from the Communication dialog.

When the user selects and then sends a file, Oracle Communicator sends a SIP INVITE request to the recipient. To secure the file transfer, the INVITE contains XML that describes the file itself and the URL of the FileTransferServlet (the address designated by the <Location> element) and a randomly generated string.

Note:

This string is unique to every file transfer; it is never re-used.

Upon receiving the INVITE request, the recipient's client alerts its user of the file transfer with the File Offer dialog (Figure 5-7) that indicates the name of the sender as well as the name and size of the file. If the recipient accepts the file, the client returns an OK response to the sender. The user and recipient's clients both make HTTP or HTTPS connections to the URL of the OC4J container hosting the FileTransferServlet. The servlet matches the sender to the receiver and then ushers the file to the receiver. Typically, the server hosting the FileTransferServlet does not store the files; the FileTransferServlet only conveys the files from sender to receiver.

Figure 5-7 The File Offer Dialog

Description of "Figure 5-7 The File Offer Dialog"

After the receiver accepts the file and selects a location to store the file, the file transfer status and any error messages display for both the sender and receiver (Figure 5-8). The recipient receives a notification once the file transfer completes and can open the selected destination folder to view the file.

If the receiver declines the file, or if the receiver's instance of Oracle Communicator is not configured to support file transfer, then a dialog notifies the sender and the file transfer ends.

Figure 5-8 File Transfer Status

Description of "Figure 5-8 File Transfer Status"

See also "Enabling File Transfers" for more information on configuring file transfers.

Note:

The FileTransferServlet will timeout on a sender or receiver if a request has not been made within the period designated in the its `WEB-INF/web.xml`'s `max-connect time` parameter.

#### Setting the File Size

If needed, you can set a limit on the size (in bytes) of files that FileTransferServlet transfers through the `max-size` parameter of its `WEB-INF/web.xml`.

#### HTTP Authentication and HTTPS Certificates

Oracle Communicator 10.1.3.4 does not support authentication for file recipients since the FileTransferServlet is hosted separately from OCMS. Although Oracle Communicator 10.1.3.3 supports HTTPS, users are not prompted to accept certificates.