Oracle CRM On Demand Documentation Library: Adding Custom Objects to Oracle CRM On Demand Desktop

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

Before You Begin

Review the chapter on customization in Oracle CRM On Demand Desktop Administration Guide.

NOTE: This procedure adds the Service Request custom object to Microsoft Outlook storage and not DB FACADE storage.

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:

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.

<extra_command_options>
<option Name="UseDefaultViewMode" Value="true" Scopes="Dedup;ONLKP;QBID"/>
</extra_command_options>

<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"/>

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:

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:

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.


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
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 script section 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:

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.
.


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 <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.

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 type="table">
<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

Oracle CRM On Demand Desktop Customization Guide, Version 5.2 Revision A		Copyright © 2018, Oracle and/or its affiliates. All rights reserved. Legal Notices.