4How Oracle CRM On Demand Desktop Works
How Oracle CRM On Demand Desktop Works
This chapter describes how Oracle CRM On Demand Desktop works. It includes the following topics:
Extensions to the Microsoft Outlook User Interface
Oracle CRM On Demand Desktop extends Microsoft Outlook to store and display Oracle CRM On Demand sales data within Microsoft Outlook. The following are some examples of these extensions:
Custom toolbar buttons
Custom menu items
Custom forms that display Oracle CRM On Demand data
Custom controls that are embedded in Microsoft Outlook forms that display Oracle CRM On Demand data
Personalization options dialog box
Predefined Oracle CRM On Demand views in Microsoft Outlook folders, for example, the Oracle CRM On Demand Opportunities for Account view.
To allow the user to perform a variety of tasks, Microsoft Outlook uses these extensions. The following are some examples of work that the user can perform:
Creating new Oracle CRM On Demand data in Microsoft Outlook
Marking a Microsoft Outlook item to be shared with Oracle CRM On Demand data and associated sales data
Viewing and editing sales data
Starting a standard Microsoft Outlook action, such as sending an email or scheduling a meeting in the context of a sales item
Oracle CRM On Demand Desktop performs a variety of validations on data entry. The following are some examples of validation that Oracle CRM On Demand Desktop performs:
Confirming that the data type is valid for a given field
Making sure each required field includes information
Making sure certain fields are disallowed, depending on the access rules for conditional data
Overview of Oracle CRM On Demand Desktop Architectural Components
The following figure illustrates the major architectural components that Oracle CRM On Demand Desktop uses.

Explanation of Callouts
Oracle CRM On Demand Desktop uses the following components:
Oracle CRM On Demand Desktop . Oracle CRM On Demand Desktop is an extension of Microsoft Outlook, which uses a synchronization engine to determine the data changes between Microsoft Outlook and Oracle CRM On Demand. Oracle CRM On Demand data is saved locally in Microsoft Outlook, allowing for offline access of Oracle CRM On Demand data through Microsoft Outlook. For more information on using Oracle CRM On Demand Desktop with Microsoft Outlook, see Extensions to the Microsoft Outlook User Interface
Web Services. Oracle CRM On Demand Desktop communicates with Oracle CRM On Demand, using Web services SOAP protocol. Oracle CRM On Demand Desktop submits requests and receives replies through Oracle CRM On Demand Web services to synchronize data between Microsoft Outlook and Oracle CRM On Demand. For more information on Oracle CRM On Demand Web services, see About the Web Service API Used by Oracle CRM On Demand Desktop.
Oracle CRM On Demand. This is Oracle’s customer relationship management (CRM) solution, which hosts CRM data and provides CRM functionality in a hosted Oracle CRM On Demand environment.
How Oracle CRM On Demand Desktop Synchronizes Data
To synchronize data between Microsoft Outlook and the Oracle CRM On Demand server, Oracle CRM On Demand Desktop uses a process that Oracle CRM On Demand Desktop controls. After Oracle CRM On Demand Desktop is installed, it initializes the Oracle CRM On Demand data that is available in Microsoft Outlook through the initial synchronization. An incremental synchronization synchronizes subsequent changes that occur in Microsoft Outlook or on the Oracle CRM On Demand server.
To make Oracle CRM On Demand data available in Microsoft Outlook, the Oracle CRM On Demand Desktop user must perform an initial synchronization with the Oracle CRM On Demand server. CRM On Demand Desktop Assistant guides the user through the setup of the Oracle CRM On Demand Desktop application in Microsoft Outlook. After you install Oracle CRM On Demand Desktop, it displays when the user starts Microsoft Outlook for the first time.
While using the CRM On Demand Desktop Assistant, the user can choose several installation preferences and then start the initial synchronization. Oracle CRM On Demand Desktop does the following:
Connects Microsoft Outlook to the Oracle CRM On Demand server and authenticates the user.
Checks the user's role to determine which customization package to retrieve from the Oracle CRM On Demand server.
Customization packages are specific to a role in Oracle CRM On Demand. For more information customization packages, see Files in the Customization Package.
Performs a version check on the customization package, which verifies if a specific customization package already exists on the user's computer.
For more information, see Overview of Relationships Between Metadata Objects.
Downloads and applies the configuration, as saved on the customization package.
Synchronizes the appropriate data. The connector configuration, synchronization mappings, visibility rules, default internal filters, and default user filters determine this synchronization.
For more information, see How Oracle CRM On Demand Desktop Synchronizes Data with Oracle CRM On Demand.
About Web Service Usage During Synchronization
Microsoft Outlook and Oracle CRM On Demand use Web services to communicate with each other. Web service requests from Oracle CRM On Demand Desktop go through the normal Oracle CRM On Demand Web service infrastructure. Oracle CRM On Demand Desktop does the following:
Sends Web service requests to verify the Oracle CRM On Demand Desktop version
Queries Oracle CRM On Demand data
Modifies Oracle CRM On Demand data by synchronizing changes made by the user in Microsoft Outlook to the Oracle CRM On Demand server
Web service responses are from Oracle CRM On Demand through the normal Oracle CRM On Demand Web service infrastructure. For more information, see About the Web Service API Used by Oracle CRM On Demand Desktop.
How Oracle CRM On Demand Desktop Displays Data in Microsoft Outlook
Oracle CRM On Demand Desktop stores Oracle CRM On Demand data in files that are native to Microsoft Outlook. It stores this data in one of the following files, depending on the data file that a user sets as the default mail delivery location in the Microsoft Outlook profile:
A Microsoft Exchange folder file (.ost file) that is offline and cached
A personal folders file (.pst file)
Microsoft Outlook data is created in the native Microsoft Outlook application. Examples include an appointment or calendar item.
Oracle CRM On Demand data can include the following items:
Business data that the user creates in Oracle CRM On Demand Desktop
Data that a user creates in Oracle CRM On Demand
Data that resides in the Oracle CRM On Demand database on the Oracle CRM On Demand server
Examples of Oracle CRM On Demand data include an opportunity, account, or activity. Because Oracle CRM On Demand Desktop uses native Microsoft Outlook data files, Microsoft Outlook displays Oracle CRM On Demand data in native Microsoft Outlook UI elements, for example, lists and forms. Microsoft Outlook can display Oracle CRM On Demand data simultaneously with other Microsoft Outlook data while using the same UI element, such as a mailbox folder. The Oracle CRM On Demand Desktop user can specify a folder that displays Oracle CRM On Demand data and can also view Microsoft Outlook data in a Microsoft Outlook list view.
Oracle CRM On Demand Desktop displays Oracle CRM On Demand data in the following contexts:
Microsoft Outlook forms, which are extensions to Microsoft Outlook calendar, contact, email, and tasks.
Microsoft Outlook items, such as the details of an account or opportunity that is associated with a Microsoft Outlook appointment that is shared with Oracle CRM On Demand Desktop.
The data that Oracle CRM On Demand Desktop stores in cached Microsoft Exchange mode in OST file format or in personal folders in PST format is accessible to the user while disconnected. The user interacts with data that is accessible to Microsoft Outlook in the local or in the Exchange Server files. The user does not interact directly with data that resides on the Oracle CRM On Demand server.
How Oracle CRM On Demand Desktop Uses Oracle CRM On Demand
This topic describes some of the major components in Oracle CRM On Demand that Oracle CRM On Demand Desktop uses. It includes the following information:
About the Web Service API Used by Oracle CRM On Demand Desktop
Oracle CRM On Demand Desktop uses Oracle CRM On Demand Web services as well as Web service APIs specific to Oracle CRM On Demand Desktop.
A Client Sync Service Web service provides access to data and checks that the client versions are correct. It has one method,ClientSyncService_Execute. This method is a wrapper for the existing Oracle CRM On Demand Web Services v2.0 API. ClientSyncService_Execute calls the Web Services v2.0 QueryPage and Execute methods on Oracle CRM On Demand objects to synchronize data.
For more information about the Web Services v2.0 API, see Oracle Web Services On Demand Guide.
The Client Sync Service Web service is available through privilege checks and authorization only to Oracle CRM On Demand Desktop. A Web Services Description Language (WSDL) file is not published or available to customers. However, usage information for the Web service is visible in the Web Service Utilization page in Oracle CRM On Demand. Entries appear with a Web Service Name value of ClientSyncService and an Operation value of VersionCheck or Execute.
Oracle CRM On Demand Desktop always uses the Sales Rep value for the ViewMode argument in Web services calls. The Sales Rep view mode takes precedence over the Can Read All Records? setting in Oracle CRM On Demand. This setting means that a user can have the Can Read All Records? flag enabled for a record type, but the visibility to that record is blocked by the Sales Rep View mode unless the user is from the team that owns that record.
Visibility is also defined by the access settings defined for the role. For more information on roles and profiles, see Oracle CRM On Demand Online Help. For more information on the ViewMode argument, see Oracle Web Services On Demand Guide.
About Book-Based Visibility
In addition to visibility through record ownership and team membership settings, there is also a book visibility of records. For book visibility, you must set the ViewMode argument to Context in Web services API calls. For access to a specific book, the BookQueryPage method uses the BookId and BookName arguments. If the book has a parent book, then you must also set the ParentBookName argument through the same method. You can associate records with the book if you have the CanContainDataFlag setting enabled for that book. This setting corresponds to the Can Contain Data check box on a Book Detail page in the UI.
For more information on book functionality and configuration see Oracle CRM On Demand Online Help. For more information on Web services, see Oracle Web Services On Demand Guide.
About User Default Books
For access to a user default book, the UserQueryPage method uses the DefaultBookId and DefaultBookName arguments. You can also set default books for each record type. To obtain the default books for each record type, the UserDefaultBookPerType argument returns the default BookId, BookName, IncludeSubBooks, and AccessObjectName for each record type. If the default book for record type contains subbooks, then set the IncludeSubBooks flag to true.
About Authentication and License Allotment
To establish an authenticated session with Oracle CRM On Demand, users must have valid login credentials to Oracle CRM On Demand, with the following Web services privileges enabled:
Enable Web Services Access
Enable CRM Desktop Access
For more information on session management, see Oracle Web Services On Demand Guide.
The number of users that can be granted the Enable CRM Desktop privilege is limited to the number of Oracle CRM On Demand Desktop licenses that have been provisioned for the company.
You can view license allocation and usage in the Service Allotment Administration section of the Company Administration page of Oracle CRM On Demand. To adjust your license allotment for Oracle CRM On Demand Desktop, contact Oracle Customer Care.
How Oracle CRM On Demand Desktop Handles Allotment Errors
Multiple allotment errors can occur during the deployment phase and also during the synchronization process. The disrupted synchronization might be aborted or might restart when the allotment becomes available.
It is recommended that you use an accurate filter to limit the amount of data synchronized to the user. It is recommended that you purge unnecessary records and attachments to free space for Oracle CRM On Demand Desktop.
The following error is a license allotment error that the company administrator can receive when trying to assign a privilege to a role, or a role to a user:
You have exceeded the number of licenses for your company. Please contact your Oracle CRM On Demand Sales Representative to discuss licensing options.
This error occurs when you are trying to assign the Enable CRM Desktop privilege to too many users in your company. It is recommended that you either purchase additional licenses or that you move users to a new role to control the license assignment.
Checking the License Allotment in Oracle CRM On Demand
This topic describes how to check the license allotment in Oracle CRM On Demand.
To check the license allotment in Oracle CRM On Demand
Go to the global Admin link, then Company Administration, and then Service Allotment Administration.
If you have to purchase license allotment for your company, then contact Oracle Customer Care.
Metadata That Describes the Oracle CRM On Demand Desktop Application
Oracle CRM On Demand Desktop is defined in metadata so that you can customize it to meet your business requirements. This topic describes the structure of the metadata that Oracle CRM On Demand Desktop uses and how you can modify the metadata to support a customization. It includes the following information:
For more information on customizing an implementation of Oracle CRM On Demand Desktop, see Customizing Oracle CRM On Demand Desktop.
Overview of Relationships Between Metadata Objects
An Oracle CRM On Demand Desktop user is associated with a given Oracle CRM On Demand Desktop configuration through a role that a customization package references. When the package is activated and published, a user who is associated with the role can download the configuration that is defined in the package. This configuration is a collection of metadata files that Oracle CRM On Demand Desktop stores on the Oracle CRM On Demand server and downloads to Microsoft Outlook during synchronization. The following figure illustrates the relationships between users, roles, customization packages, and metadata files.

The following relationships exist between users, roles, customization packages, and metadata files:
Oracle CRM On Demand Desktop user. The user of an implementation of Oracle CRM On Demand Desktop.
Role. An Oracle CRM On Demand role, such as sales representative. It corresponds to the job role that the user performs.
Customization package. A collection of metadata files that Oracle CRM On Demand Desktop associates with a particular role. This package is delivered to the user in a ZIP file. For more information, see About the Customization Package.
Metadata file. A description of Oracle CRM On Demand Desktop that Oracle CRM On Demand Desktop sends to Microsoft Outlook as XML code or JavaScript files. Metadata files are contained in the customization package. For more information, see About Metadata Files.
How Oracle CRM On Demand Desktop Users Access Oracle CRM On Demand Data
Oracle CRM On Demand Desktop allows the user to access Oracle CRM On Demand data in Microsoft Outlook in the following ways:
Through roles. In Oracle CRM On Demand, a customization package is associated with a role. This association determines which customization package Oracle CRM On Demand Desktop sends to the user. The metadata defines which objects Oracle CRM On Demand Desktop synchronizes with Microsoft Outlook.
Through synchronization filters. The customization package includes metadata files that specify which data access control and which filters to apply when Oracle CRM On Demand Desktop synchronizes data with the Oracle CRM On Demand server. For example, the default configuration specifies that the user can synchronize accounts, contacts, leads and opportunities. These records are associated with the sales team to which the user is assigned.
Depending on your business requirements, you can define different customization packages and assign them to different users through the user’s roles. To meet individual user requirements, you can define different access control and synchronization filters for each customization package.
About the Customization Package
A customization package is a collection of XML metadata files and JavaScript files that Oracle CRM On Demand Desktop associates with a particular role. In Oracle CRM On Demand, the customization package is saved and used as a ZIP file containing the metadata files. If you want to modify the customization package, then you must unzip the customization package and make changes to the appropriate metadata files. When you are finished, you must rezip the entire customization package, and upload the modified customization package to the Oracle CRM On Demand server. For more information, see Overview of Customizing Oracle CRM On Demand Desktop. You can make the following customizations:
Add or remove fields that Oracle CRM On Demand Desktop synchronizes.
Change the layout of a custom form in the client.
Change a control that Oracle CRM On Demand Desktop uses with Microsoft Outlook.
Change a security rule.
The customization package describes the following information:
The extensions to the Oracle CRM On Demand Desktop UI, which includes Microsoft Outlook views, forms, lookup controls, and toolbars
Translated text strings that Oracle CRM On Demand Desktop uses to create prompts and labels in Microsoft Outlook
Data validation and security logic
Descriptions of synchronization preset filters and view modes that Oracle CRM On Demand Desktop uses during synchronization
Criteria that Oracle CRM On Demand Desktop uses to detect duplicate objects that occur in Oracle CRM On Demand Desktop
Business logic that JavaScript provides
Data mapping between Oracle CRM On Demand fields and Microsoft Outlook fields
If you change the data model in the customization package, then Oracle CRM On Demand Desktop performs a complete resynchronization. For more information on customizing the customization package, see Customizing Oracle CRM On Demand Desktop.
Guidelines for Assigning a Role to a Customization Package
When you develop a customization package you must follow these guidelines:
You can associate only one customization package with a role. A user can be assigned to only one role. However, a role can have many users.
You can assign the same customization package to multiple roles. However when you do this assignment you must create a separate package record for each role. You manage roles in the Company Administration section of Oracle CRM On Demand.
Only one customization package can be published for a specific role at any time.
About Metadata Files
A metadata file is an XML or JavaScript file that describes the Oracle CRM On Demand Desktop application. Oracle CRM On Demand Desktop uses these files in the following ways:
XML files. Describes the default synchronization objects, synchronization mapping, custom views and forms in Microsoft Outlook, and so on.
JavaScript files. Describes the business logic that Oracle CRM On Demand Desktop uses for data validation, custom actions that Oracle CRM On Demand Desktop provides access to in toolbars, and other custom processing that Oracle CRM On Demand Desktop performs in Microsoft Outlook.
The following items describe how Oracle CRM On Demand Desktop uses metadata files with a customization package:
A customization package contains a collection of metadata files. These files describe the entire Oracle CRM On Demand Desktop application that you use with Microsoft Outlook.
A customization package consists of a set of metadata files.
Oracle CRM On Demand Desktop requires that a customization package include a minimum number of files. These files are described in Files in the Customization Package.
You can use a single metadata file with more than one customization package. These metadata files can be part of another customization package. The figure in the topic Overview of Relationships Between Metadata Objects illustrates this relationship where the same metadata file occurs in different packages, for example, packages 1 and 3 include metadata file 2.
Oracle CRM On Demand Desktop associates a customization package with a single Oracle CRM On Demand role. It associates a user with the role as a way to acquire access to the customization package and the Oracle CRM On Demand Desktop configuration that you use with Microsoft Outlook. For more information, see Files in the Customization Package.
How Oracle CRM On Demand Desktop Reuses, Modifies, and Updates Metadata Files
Oracle CRM On Demand Desktop stores the metadata files in a customization package. This customization package is stored on Oracle CRM On Demand as a ZIP file. In Oracle CRM On Demand, metadata files are not tracked or stored individually.
Although you can use an existing role and associate it with a customization package, it is recommended that you create a new role. For example, the Oracle CRM On Demand sales representative role is different and separate from the Oracle CRM On Demand sales and marketing manager role. Creating a new role provides you with more control over which users Oracle CRM On Demand Desktop associates with which customization package. For more information, see Creating and Publishing the Customization Package.