4Adding Custom Objects to Oracle CRM On Demand Desktop
Adding Custom Objects to Oracle CRM On Demand Desktop
This chapter describes how to add a custom object to Oracle CRM On Demand Desktop, using an example. It shows you how to add a Service Request custom object. Although Service Request is actually a default type, it is used as an example to better show the customization process using a default object using existing code in the default package. Use this example as a reference for adding other custom objects for your specific requirements. This chapter includes the following topics:
Adding Custom Objects to Oracle CRM On Demand Desktop
This procedure describes how to add the Service Request custom object to Oracle CRM On Demand Desktop. In this procedure, you make sure the custom object is available through Oracle CRM On Demand Web services, and then you update the following metadata files:
od_meta_info.xml
od_basic_mapping.xml
connector_configuration.xml
forms_12.xml
business_logic.js
forms.js
package_res.xml
views.xml
For information on the contents of these files, see About the Metadata Files Updated During Customization.
Before You Begin
Review the chapter on customization in Oracle CRM On Demand Desktop Administration Guide.
For more information on Microsoft Outlook and DB FACADE storage, see About Microsoft Outlook and DB FACADE Storage.
To add a custom object to Oracle CRM On Demand Desktop
Make sure that the custom object is available through Oracle CRM On Demand Web services.
For information on using Web services, see Oracle Web Services On Demand Guide.
To add a custom object to Oracle CRM On Demand Desktop, you must update at least three files, od_meta_info.xml, od_basic_mapping.xml and connector_configuration.xml, as described in the following steps:
Update the od_meta_info.xml file.
Add the custom object definitions to the od_meta_info.xml file. This file provides information about the user's environment to Oracle CRM On Demand Desktop, such as the objects available for Oracle CRM On Demand Desktop, the fields for the objects, and so on.
To add a custom object definition you must add an <object> element with a set of <field> elements that together define a set of fields that are available for Oracle CRM On Demand Desktop, as in the following sample outline:
<object ... > <field ... /> <field ... /> <field ... /> </object>The <object> element can contain many different attributes, but the minimum required attributes are described in the following table.
Attribute Name Attribute Value Attribute Description TypeId
Service Request
The unique identifier of this object type in Oracle CRM On Demand Desktop.
This attribute can be any value that identifies this object in the Oracle CRM On Demand Desktop configuration. For child objects, use the following naming convention:
Parent_Name.Child_Name
Label
Service Request
The label that Oracle CRM On Demand Desktop uses for this type of object in the user interface, in particular, for a filter view on a control panel.
LabelPlural
Service Requests
The plural label that Oracle CRM On Demand Desktop uses for this type of object in the user interface, in particular, for a filter view on a control panel.
ViewMode
Sales Rep
The view mode for this type of object.
The view mode controls the object's visibility and data volume synchronized with Microsoft Outlook.
This attribute can be set to any applicable view mode.
IntObjName
Service Request
The name of the integration object that provides access to the object you want to add to Microsoft Outlook.
XmlElemName
ServiceRequest
The name of the XML element that Oracle CRM On Demand Desktop uses in requests to the Oracle CRM On Demand server.
XmlCollectionElemName
ListOfServiceRequest
The name of the XML collection element that Oracle CRM On Demand Desktop uses in requests to the Oracle CRM On Demand server.
To obtain the values for the object's IntObjName, XmlElemName and XmlCollectionElemName attributes, see Oracle Web Services On Demand Guide.
The Service Request object in Oracle CRM On Demand contains many fields, but this example uses only a few, as shown in the following sample XML for the Service Request custom object.
Note: The following example contains lines with inadvertent breaks due to their width. If you directly copy and paste this example, ensure that you fix any errors that result from these line breaks.<object TypeId="Service Request" Label="Service Request" LabelPlural="Service Requests" ViewMode="Sales Rep" IntObjName="Service Request" XmlElemName="ServiceRequest" XmlCollectionElemName="ListOfServiceRequest"> <open_with_url_tmpl> <![CDATA[ :[:(protocol):]://:[:(hostname):]::[:(port):]/OnDemand/user/ AccountDetail?ServiceRequestDetailForm.Id=:[:(own_id):] ]]> </open_with_url_tmpl> <extra_command_options> <option Name="UseDefaultViewMode" Value="true" Scopes="Dedup;ONLKP;QBID"/> </extra_command_options> <viewmodes> <viewmode Name="None" Scopes="Dedup;ONLKP;QBID" /> </viewmodes> <access_mode_config BooksSupported="true" TypeOrderNumber="6"> <involved_fields> <field Name="Owner" /> <field Name="BookName" /> </involved_fields> <scopes> <scope Id="Dedup" BookId="" /> <scope Id="ONLKP" BookId="" /> <scope Id="QBID" BookId="" /> </scopes> </access_mode_config> <field Name="SRNumber" Label="SRNumber" DataType="DTYPE_TEXT" CRMName="SRNumber" BackUpd="all"> <suppress_on Upstream="true"/> </field> <field Name="Subject" Label="Subject" DataType="DTYPE_TEXT" CRMName="Subject"/> <field Name="Description" Label="Description" DataType="DTYPE_TEXT" CRMName="Description"/> <field Name="Id" Label="Id" DataType="DTYPE_ID" IsPrimaryKey="yes" IsFilterable='no'/> <field Name="ModId" Label="ModId" DataType="DTYPE_INTEGER" IsTimestamp="yes" IsFilterable='no' IsHidden="yes"/> <field Name="OwnerId" Label="OwnerId" DataType="DTYPE_ID" IsRefObjId="yes" RefObjTypeId="User" IsFilterable='no'/> </object>You must also add the
BackUpd="all"attribute on the SRNumber field because its value should be generated by server and must be synchronized from the Oracle CRM On Demand server side while adding an object on the server. For example:<field Name="SRNumber" Label="SRNumber" DataType="DTYPE_TEXT" CRMName="SRNumber" BackUpd="all">
Update the od_basic_mapping.xml file.
Add Service Request type to the od_basic_mapping.xml file, which describes the data structure that must be created in Microsoft Outlook by Oracle CRM On Demand Desktop. There are two types of storage that exist in Oracle CRM On Demand Desktop:
Microsoft Outlook
DB FACADE
For more information on Microsoft Outlook and DB FACADE storage, see About Microsoft Outlook and DB FACADE Storage.
Note: If an object does not have to be displayed on the Microsoft Outlook folder list view, then you must add this type of object to DB FACADE storage. Objects added to DB FACADE storage cannot be displayed on Outlook forms. Instead, dialog boxes are used to represent the data for those objects.The syntax for adding an object to storage depends on what the type of storage to which you are adding the object. For adding an object to Outlook storage, the syntax is as follows:
<type ... > <form ... /> <field ... /> <field ... /> <field ... /> </type>Make the following updates to the od_basic_mapping.xml file that results in the final XML code for the Service Request type in XML Code for Service Request Types:
You must define the attributes of the <type> element described in the following table in the od_basic_mapping.xml file.
Attribute Name Attribute Value Description id
Service Request
This attribute defines the unique ID of this object type in Oracle CRM On Demand Desktop.
This value must be the same as the value specified for the TypeId attribute of the <object> element in od_meta_info.xml in Step 1.
display_name
Service Requests
This attribute defines the label that Oracle CRM On Demand Desktop uses for this type of object in the user interface. In this example, the label defines the name of a folder in Microsoft Outlook storage, where objects of this type are stored. This value must be unique among all types in the od_basic_mapping.xml file.
folder_type
10
This attribute specifies that objects of this type are stored in a folder of the same type as Microsoft Outlook Contacts.
Add the <form> element which is required in the definition of the new object type. This element defines some important UI attributes, such as form definition used to display records of this type, the icon for this type, the display name for the form, and other attributes. In the example, define the attributes described in the following table. The <form> element must also contain the name of the custom form definition as defined in the forms_12.xml file. For this example, leave it as OnDemand ServiceRequest, see the following sample XML:
Attribute Name Attribute Value Attribute Description message_class
IPM.Contact.SBL. ServiceRequest
This attribute defines the type for new objects by using a subclass of the Microsoft Outlook message class.
The new object is based on the Contact object, but you can extend the set of fields for this type.
Use the following recommended naming convention for this attribute value:
IPM.Contact.SBL.Object_type
icon
type_image: Service_Request:16
This attribute defines the icon that is displayed for this type of object, for example, on a form caption in Microsoft Outlook views, and so on.
The value of this attribute is the resource key of an image file, for example, a PNG file, 16 x 16 pixels, to be used and defined in any Oracle CRM On Demand Desktop resource file.
large_icon
type_image: Service_Request:32
This attribute defines the icon to be displayed for this type of object on a specific Microsoft Outlook view (icon type).
The value of this attribute is the resource key of an image file, for example, a PNG file, 32 x 32 pixels, to be used and defined in any Oracle CRM On Demand Desktop resource file.
display_name
Service Request
This attribute defines the caption of the Microsoft Outlook form if the object is displayed on the Microsoft Outlook form.
The <form> element must also contain the name of the custom form definition as defined in the forms_12.xml file. For this example, leave it as OnDemand ServiceRequest, see the following sample XML:
<form message_class="IPM.Contact.SBL.ServiceRequest" display_name="#obj_service_request" icon="type_image:Service_Request:16" large_icon="type_image:Service_Request:32">OnDemand ServiceRequest</form>
Define the fields of the new object. The field mapping definitions depend on the field type and, in some cases, the decision to map the field to either a custom field or to one of Microsoft Outlook fields. For more information, see Adding Custom Fields to Oracle CRM On Demand Desktop In this example, you map the following fields of Service Request object: SRNumber OwnerId Subject Description You also map the following Service Request fields that you might decide to use later: ObjectState SuppressFileAs
In this example, you map the following fields of Service Request object:
SRNumber
OwnerId
Subject
Description
You also map the following Service Request fields that you might decide to use later:
ObjectState
SuppressFileAs
The final XML code for the Service Request type in the example is provided in XML Code for the Service Request Type Example.
Update the forms_12.xml file.
To be able to see custom object fields values, views, linked objects, and so on, you must define the custom object form layout in the forms_12.xml file. The outline of the the custom object form layout is in the example provided in XML Code for the Custom Objects Form Layout Example.
Update the business_logic.js file.
To avoid receiving a Microsoft Outlook dialog with the message that field File As was not filled, you need to add the following code in function
create_ondemand_meta_scheme2, before// Activity processing and related set:scheme.objects.get_object("Service Request").get_field("SuppressFileAs")["initial_value_res"] = "lang_general_initial_fileas";Update the forms.js file.
Customer objects requires their own handler. This handler should be specified in the forms.js file by adding in the following function:
function od_sr_form(ctx)
{ if (!od_helpers.check_first_sync(ctx)) { od_helpers.lock_form_before_first_sync(ctx) return; } ctx.form_links_manager.init_new(); var form = ctx.form; form.SRNumber.enabled = false; }For the Service Request custom object, the following line disables the SRNumber field because its value is generated by the server:
"form.SRNumber.enabled = false;"
Consequently, you must specify the following handler in object form in the
scriptsection in the forms_12.xml file:var current_form = new include.forms.od_sr_form(include.forms.create_form_ctx(ctx));
Update the connector_configuration.xml file.
The changes made in the od_meta_info.xml and od_basic_mapping.xml describe only the new object in a data structure, either in Microsoft Outlook or on Oracle CRM On Demand. However, to synchronize items of this object type between Oracle CRM On Demand and Microsoft Outlook, you must add the new object definition to a connection_configuration.xml file.
To add the object definition, you add the following structure to the <types> element in the connection_configuration.xml file:
<type ... > <view ... /> <synchronizer ... /> <links> <link ... /> ... </links> <natural_keys> <natural_key> <field ... /> ... </natural_key> ... </natural_keys> </synchronizer> </type>After completing adding the object definition for this example, the resulting XML code is as follows:
<type id="Service Request" state_field="ObjectState"> <view label="Service Request" label_plural="Service Requests" small_icon="type_image:Service_Request:16" normal_icon="type_image:Service_Request:24" large_icon="type_image:Service_Request:48"></view> <synchronizer name_format=":[:(SRNumber):]" threshold="3"> <links> <link>AccountId</link> <link>ContactId</link> <link>OwnerId</link> </links> <natural_keys> <natural_key> <field>Subject</field> </natural_key> </natural_keys> </synchronizer> </type>Define the attribute on the <type> element as described in the following table.
Attribute Name Attribute Value Description id
Service Request
The unique ID of this object type in Oracle CRM On Demand Desktop.
Set this value to the same value specified for the TypeId attribute of the <object> element in od_meta_info.xml and for the id attribute of the <type> element in the od_basic_mapping.xml file.
Define the attributes on the <view> element as described in the following table. The view element defines some of the user interface settings.
Attribute Name Attribute Value Attribute Description label
Service Request
This attribute defines the label that Oracle CRM On Demand Desktop uses for this type of object in the user interface. In particular, Oracle CRM On Demand Desktop uses this label for synchronization issues to resolve duplicates, resolve conflicts, and synchronize the confirmation tabs of the Control Panel.
label_plural
Service Requests
This attribute defines the plural label that Oracle CRM On Demand Desktop uses for this type of object in the user interface. In particular, Oracle CRM On Demand Desktop uses this label for synchronization issues to resolve duplicates, resolve conflicts, and synchronize the confirmation tabs of the Control Panel.
small_icon
type_image:Service_Request:16
This attribute defines the icon to be displayed for this type of object on a Control Panel as a child element icon on a filter tree in various lists of the Control Panel. The value of this attribute is a resource key of an image file, for example, a PNG file, 16 x 16 pixels, to be used and defined in any Oracle CRM On Demand Desktop resource file.
normal_icon
type_image:Service_Request:24
This attribute defines the icon that is displayed for this type of object on a Control Panel, as the top-level element icon on a filter tree.
Set the value of this attribute as a resource key of an image file, for example, a PNG file, 24 x 24 pixels, to use and define in any Oracle CRM On Demand Desktop resource file.
large_icon
type_image:Service_Request:48
This attribute defines the icon that is displayed for this type of object, The icon is on a synchronization dialog box.
Set the value of this attribute as a resource key of an image file, for example, a PNG file, 48 x 48 pixels, to use and define in any Oracle CRM On Demand Desktop resource file.
Define the attributes on the <synchronizer> element as described in the following table. The <synchronizer> element defines the synchronization settings for the object, such as the link fields, natural keys, how the object is displayed if it appears in any Microsoft Windows Control Panel list, and so on. . The <synchronizer> element also contains the <links> and <natural_keys> elements. The <links> element defines a set of link fields for the object. Oracle CRM On Demand Desktop requires these fields to build an object’s dependency tree during synchronization. Oracle CRM On Demand Desktop must also determine which fields contain Ids of other objects, so that their values can be converted from Oracle CRM On Demand Id format to Oracle CRM On Demand Desktop Id format and from Oracle CRM On Demand Desktop Id format to Oracle CRM On Demand format.
Attribute Name Attribute Value Attribute Description name_format
:[:(SRNumber):]
This attribute's value defines a mask that is used to build the object identifier in any list of the Microsoft Windows Control Panel (synchronization issues, duplicates, and so on). In this example, the Control Panel displays the value of the Name field.
The <natural_keys> element contains a set of field sets denoted by <natural_key>, which is used to identify duplicated records during synchronization. Records are identified as a duplicate if there are two matching records in Oracle CRM On Demand and Oracle CRM On Demand Desktop, and if the match is defined by the fields that are specified in natural keys. In the example, the field is: Subject.
Update the package_res.xml file.
The package_res.xml file contains descriptions of every resource in package, for example, labels, images, and so on. Any customer object also requires resources to be defined, as follows:
For the Service Request object, add the following label of list view to resources:
<str key="view_for_service_requests">CRM On Demand Service Requests</str>
Define the Service Request object icon:
<img key="type_image:ServiceRequest:16">IMAGE_IN_BASE64</img> <img key="type_image:ServiceRequest:24">IMAGE_IN_BASE64</img> <img key="type_image:ServiceRequest:32">IMAGE_IN_BASE64</img> <img key="type_image:ServiceRequest:48">IMAGE_IN_BASE64</img>
Note: Replace IMAGE_IN_BASE64 text with valid image in Base64 encoding.
Update the views.xml file.
To expose object field values on a list view, you must define the object custom view with the corresponding columns. You can apply the custom view to the folder by adding its reference to the custom_views tag in the basic mapping.
The following is an example of a custom view.
Note: The following example contains lines with inadvertent breaks due to their width. If you directly copy and paste this example, ensure that you fix any errors that result from these line breaks.<str key="all_sr"> <![CDATA[<?xml version="1.0"?> <view> <viewname>$view_for_service_requests$</viewname> <viewstyle>table-layout:fixed;width:100%;font-family:Segoe UI;font- style:normal;font-weight:normal;font-size:8pt;color:Black;font-charset:0</ viewstyle> <viewtime>214524766</viewtime> <linecolor>8421504</linecolor> <linestyle>3</linestyle> <gridlines>1</gridlines> <autosizing>0</autosizing> <newitemrow>0</newitemrow> <incelledit>0</incelledit> <usequickflags>0</usequickflags> <collapsestate/> <rowstyle>background-color:window;color:windowtext</rowstyle> <headerstyle>background-color:#D3D3D3</headerstyle> <previewstyle>color:Blue</previewstyle> <filter>"http://schemas.microsoft.com/exchange/extensionattribute1" <> 'true'</filter> <arrangement> <autogroup>0</autogroup> <collapseclient/> </arrangement> <column> <name>HREF</name> <prop>DAV:href</prop> <checkbox>1</checkbox> </column> <column> <maxrows>1701576704</maxrows> <editable>0</editable> <heading>Icon</heading> <prop>http://schemas.microsoft.com/mapi/proptag/0x0fff0102</prop> <bitmap>1</bitmap> <width>50</width> <style>padding-left:3px;;text-align:center</style> </column> <column> <heading>Service Request Number</heading> <prop>http://schemas.microsoft.com/mapi/string/{00020329-0000-0000-C000- 000000000046}/od%20SRNumber</prop> <type>string</type> <width>200</width> <style>padding-left:3px;;text-align:left</style> <editable>1</editable> <userheading>Service Request Number</userheading> </column> <column> <heading>Service Request Subject</heading> <prop>http://schemas.microsoft.com/mapi/string/{00020329-0000-0000-C000- 000000000046}/od%20Subject</prop> <type>string</type> <width>200</width> <style>padding-left:3px;;text-align:left</style> <editable>1</editable> <userheading>Service Request Subject</userheading> </column> <column> <heading>Service Request Description</heading> <prop>http://schemas.microsoft.com/mapi/string/{00020329-0000-0000-C000- 000000000046}/od%20Description</prop> <type>string</type> <width>200</width> <style>padding-left:3px;;text-align:left</style> <editable>1</editable> <userheading>Service Request Description</userheading> </column> </view>]]> </str
In the preceding custom view:
<str key="all_sr">is the view Id defined in the basic_mapping.xml file.<prop>http://schemas.microsoft.com/mapi/string/{00020329-0000-0000-C000-000000000046}/od%20SRNumber</prop>is the custom object field "od SRNumber" property value
Adding Custom Objects to DB FACADE Storage
If you are adding an object to DB FACADE storage, then the syntax to add the object is simpler than the syntax for Microsoft Outlook storage because you do not require the <form> element, and the number of <field> child elements is less as shown in the following template.
For more information on Microsoft Outlook and DB FACADE storage, see About Microsoft Outlook and DB FACADE Storage.
Before You Begin
Review the chapter on customization in Oracle CRM On Demand Desktop Administration Guide.
Example Template for Adding an Object to DB FACADE Storage
See the following template:
<type ... >
<field ... />
<field ... />
<field ... />
</type>
Completing this procedure results in the following XML code in the od_basic_mapping.xml file:
<type id="Internal_Product" icon="type_image:Service Request:16">
<field id ="SRNumber">
<type>
<simple type="string"/>
</type>
</field>
<field id="AccountId">
<type>
<simple type="binary"/>
</type>
</field>
<field id="AccountName">
<type>
<simple type="string"/>
</type>
</field>
<field id="ContactId">
<type>
<simple type="binary"/>
</type>
</field>
<field id="Area">
<type>
<simple type="string"/>
</type>
</field>
<field id="Cause">
<type>
<simple type="string"/>
</type>
</field>
<field id="Type">
<type>
<simple type="string"/>
</type>
</field>
<field id="Source">
<type>
<simple type="string"/>
</type>
</field>
<field id="CurrencyCode">
<type>
<simple type="string"/>
</type>
</field>
<field id="Priority">
<type>
<simple type="string"/>
</type>
</field>
<field id="Status">
<type>
<simple type="string"/>
</type>
</field>
<field id="OwnerId">
<type>
<simple type="binary"/>
</type>
</field>
<field id="Subject">
<type>
<simple type="string"/>
</type> </field>
<field id="StatusContact">
<type>
<simple type="string"/>
</type>
</field>
<field id="StatusAccount">
<type>
<simple type="string"/>
</type>
</field>
</type>
To add a custom object to DB FACADE storage
Define the attributes of the <type> element in the od_basic_mapping.xml file as described in the following table.
Attribute Name Attribute Value Attribute Description id
Service Request
The unique ID of this object type in Oracle CRM On Demand Desktop. Set this attribute to the same value specified for the TypeId attribute of the <object> element in od_meta_info.xml.
Note: The name you assign to an object in od_meta_info.xml must be used for the object's name in the od_basic_mapping.xml file.icon
type_image:Service Request:16
This attribute defines the icon that is displayed for this type of object, for example, on a form caption, in Microsoft Outlook views, and so on. Set the value of this attribute to a resource key of an image file, for example, a PNG file, 16 x 16 pixels, to be used and defined in any Oracle CRM On Demand Desktop resource file.
Define the attribute of the <field> element in od_basic_mapping.xml as described in the following table.
Attribute Name Attribute Value Attribute Description id
Service Request
The unique ID of this field within an object type.
Define the attribute of the <simple> element in the od_basic_mapping.xml file as described in the following table.
Attribute Name Attribute Value Attribute Description type
string
binary
integer
double
foreign_key
boolean
The unique ID of this field within an object type.