3Adding Custom Fields to Oracle CRM On Demand Desktop
Adding Custom Fields to Oracle CRM On Demand Desktop
To customize and extend Oracle CRM On Demand Desktop for your requirements you can add new fields on existing objects. This chapter describes the procedures to add new fields through examples. Before you begin this chapter, review the chapter on customization in Oracle CRM On Demand Desktop Administration Guide. This chapter contains the following topics:
About the Metadata Files Updated During Customization
You typically update the following metadata files available in the customization package, depending on the type of customization you are performing:
business_logic.js. Defines the business logic for product behavior and the basic data model for object relations.
connector_configuration.xml. Contains the definitions of objects that are synchronized, the criteria that Oracle CRM On Demand Desktop uses to detect duplicate objects in the Oracle CRM On Demand database, and defines the preset filters for a custom synchronization.
data_sources.xml. Describes the data sources that are used for joining fields between objects that are used in online lookups.
forms.js. Contains the JavaScript code to set up the multiselect picklist layout controls.
forms_12.xml. Contains the UI layouts that define the form layout for each object, the field validation rules on a form, the business logic in JavaScript, and the controls that Oracle CRM On Demand Desktop uses on a form. This file also defines the fields that Oracle CRM On Demand Desktop uses to store references between objects.
od_basic_mapping.xml. Contains the mapping data that defines the field mapping between Oracle CRM On Demand Desktop and Microsoft Outlook, and between Oracle CRM On Demand Desktop and Oracle CRM On Demand. This file describes objects to add to Microsoft Outlook, defines the form that Oracle CRM On Demand Desktop uses to display an object in Microsoft Outlook, and defines a set of custom Microsoft Outlook views that Oracle CRM On Demand Desktop applies to an object.
od_meta_info.xml. Contains the data definitions for the object types that Oracle CRM On Demand Desktop supports, the object fields and their types, and the XML element names that Oracle CRM On Demand Desktop uses to build an Oracle CRM On Demand message.
package_res.xml. Contains the symbolic string definitions that define various resources for the customization package.
views.xml. Defines the views that Oracle CRM On Demand Desktop uses in Oracle CRM On Demand Desktop forms and Microsoft Outlook windows.
For more information on these files, see the chapter on customization in Oracle CRM On Demand Desktop Administration Guide.
Adding Custom Fields to Oracle CRM On Demand Desktop
This procedure shows how you customize Oracle CRM On Demand Desktop so that a new field can be synchronized with Oracle CRM On Demand in addition to the default fields. In this customization procedure, you add a new text field called Membership to the Contact page in Oracle CRM On Demand Desktop. This field is displayed under an existing field called Lead Source.
In this example, the contact object has a new field called Membership in Oracle CRM On Demand.
Before You Begin
To complete this customization procedure, you require the following:
An XML editor of your choice to modify XML files.
A file comparison (diff) tool to compare the changes you have made to the customized files with the default customization package and to verify that the changes are free of errors. Even a minor error such as adding or removing an extra space unintentionally is problematic. The comparison tool can be useful when trying to detect such problems. A tool similar to Windiff is recommended. Windiff is available from the following Web site:
http://www.grigsoft.com/download-windiff.htm
To add a custom field to Oracle CRM On Demand Desktop
In Oracle CRM On Demand, create a new short text field called Membership for the Contact object.
Before customizing Oracle CRM On Demand Desktop, save a copy of the default customization package.
After you begin customizing, you can compare the changed files with the default files to verify your changes.
To add a custom field, you must modify the following XML files in the customization package:
od_meta_info.xml
For more information, see Changing the XML Code in the od_meta_info.xml File.
od_basic_mapping.xml
For more information, see Changing the XML Code in the od_basic_mapping.xml File.
forms_12.xml
For more information, see Changing the XML Code in the forms_12.xml File.
package_res.xml
For more information, see Changing the XML Code in the package_res.xml File.
For information on the contents of these files, see About the Metadata Files Updated During Customization.
After making the changes, package all the files using a ZIP utility, and upload the package to Oracle CRM On Demand.
Unpublish any previously published package, and publish this new customization package for the role associated with the user doing the customization.
The next time you attempt to synchronize using Oracle CRM On Demand Desktop, the new customization package is automatically downloaded so that the contact page in Oracle CRM On Demand Desktop includes the new field, Membership.
Changing the XML Code in the od_meta_info.xml File
In this procedure, you add the field definition for the new Membership field in the od_meta_info.xml file that contains the data definitions. The field definition must be included in all metadata objects that are being exposed in the example:
Contact
Account.Contact
Opportunity.Contact
The convention used for WSDL names is as follows:
For default Oracle CRM On Demand fields that have not been exposed to Oracle CRM On Demand Desktop, the naming convention is the name of the field without spaces. For example, Account Name, becomes AccountName in the WSDL.
For custom fields that you have created in Oracle CRM On Demand, for the WSDL representation of these fields, spaces are replaced with underscores, and a prefix is added to the field name. The prefixes that are used for the field types are listed in the following table. For example, if you create a field called JVD Text of type Text (Short) on an object, then in the WSDL, this field is called stJVD_Text.
Table Prefixes and Data Types for Oracle CRM On Demand Field Types
Field Type Prefix Data Type Checkbox
b
DTYPE_BOOL
Currency
c
DTYPE_NUMBER
Date
d
DTYPE_DATE
Date/Time
dt
DTYPE_UTCDATETIME
Integer
i
DTYPE_INTEGER
Multi-Select Picklist
mspl
DTYPE_CSVLIST
Number
n
DTYPE_NUMBER
Percent
pc
DTYPE_NUMBER
Phone
ph
DTYPE_TEXT
Picklist
pl
DTYPE_TEXT
Text (Long)
lt
DTYPE_TEXT
Text (Short)
st
DTYPE_TEXT
To change the XML code in the od_meta_info.xml file
Edit the od_meta_info.xml file, and locate the
<object>element.For the Contact object, the <object> element looks similar to the following:
<object TypeId = "Contact"… >
For the Account.Contact object, the <object> element looks similar to the following:
<object TypeId='Account.Contact' …>
For the Opportunity.Contact object, the <object> element looks similar to the following:
<object TypeId='Opportunity.Contact' …>
Add a new <field> element to define the new Membership field in each object:
<field Name="stMembership" Label="stMembership" DataType="DTYPE_TEXT" />
The following XML shows the <object> element and the new <field> element:
<object TypeId='Account.Contact' Label='Contact' LabelPlural='Contact' ViewMode='Sales Rep' IntObjName='Account' SiebMsgXmlElemName='Contact' SiebMsgXmlCollectionElemName='ListOfContact'> <field Name='AccountId' Label='AccountId' DataType='DTYPE_ID' IsRefObjId="yes" RefObjTypeId="Account" RefObjIsParent="yes"/> <field Name='AccountLocation' Label='AccountLocation' DataType='DTYPE_TEXT' /> <field Name='AccountMainPhone' Label='AccountMainPhone' DataType='DTYPE_TEXT' /> <field Name='AccountName' Label='AccountName' DataType='DTYPE_TEXT' /> … … <field Name='PrimaryContact' Label='PrimaryContact' DataType='DTYPE_BOOL' /> <field Name='Role' Label='Role' DataType='DTYPE_TEXT' /> <field Name='RoleList' Label='RoleList' DataType='DTYPE_TEXT' /> <field Name="stMembership" Label="stMembership" DataType="DTYPE_TEXT" /> </object>
- In this sample XML code, the st prefix has been added for the new <field> element, stMembership. Add a prefix to a field only in the od_meta_info.xml file.
Verify your changes, and save the od_meta_info.xml file.
About Microsoft Outlook and DB FACADE Storage
Oracle CRM On Demand Desktop supports two types of storage:
Microsoft Outlook storage.
Microsoft Outlook storage is the original legacy storage supported by Oracle CRM On Demand Desktop available through Microsoft Outlook. In prior releases of Oracle CRM On Demand Desktop, all objects participating in synchronization were stored in Microsoft Outlook storage. Microsoft Outlook storage is still used for top level object types such as Account, Contact, and so on, that must be displayed in a Microsoft Outlook folders list.
DB FACADE storage.
DB FACADE storage is an additional storage type supported by Oracle CRM On Demand Desktop Object types that are not visible in a Microsoft Outlook folders list and that do not have a UI form. Place types such as picklists, associations, and child objects into this storage, because DB FACADE storage is optimized for these types.
Changing the XML Code in the od_basic_mapping.xml File
The od_basic_mapping.xml file provides the data mapping between Oracle CRM On Demand and Oracle CRM On Demand Desktop. In this procedure, you add the Membership field mapping to the object <type> element.
If you are adding a field to the object stored in DB FACADE storage in Oracle CRM On Demand Desktop, then the syntax for adding the <field> element is as follows:
<field id ="Membership">
<type>
<simple type="string"/>
</type>
</field>
For more information on DB FACADE storage, see About Microsoft Outlook and DB FACADE Storage.
To change the XML Code in the od_basic_mapping.xml file
In the od_basic_mapping.xml file, locate the Contact <type > element, which looks similar to the following:
<type id="Contact"…>
Add the following <field> mapping element after any existing <field> mapping elements:
<field id="stMembership"> <reader> <mapi_user> <user_field id="od Membership" ol_field_type="1"></user_field> <convertor><string/></convertor> </mapi_user> </reader> <writer> <outlook_user> <user_field id="od Membership" ol_field_type="1"></user_field> <convertor> <string/></convertor> </outlook_user> </writer> </field>A field map has a reader and a writer definition for a custom field as shown in this example. You choose your own name for the custom field, and you must use the right converter for converting the field type. For example, to convert an incoming value of integer type to string, you must use the following structure:
<converter> <string/> </converter>The following XML code shows the Contact <type> element and the <field> mapping element:
<type id="Contact" predefined_folder="10" ver="7"> <form message_class="IPM.Contact.OnDemand.Contact" icon="type_image:Contact:16" large_icon="type_image:Contact:32" display_name="#obj_contact">OnDemand Contact</form> <alt_messageclasses> <alt_messageclass ext="Private" display_name="#obj_private_contact" icon="type_image:Contact.Private:16" large_icon="type_image:Contact.Private:32">OnDemand Contact</alt_messageclass> </alt_messageclasses> <upgrade> <from message_class="IPM.Contact" target_message_class="IPM.Contact.OnDemand.Contact.Private"></from> </upgrade> <custom_views default_name="#view_crm_and_personal_contacts"> <view id="all_contacts" name="#view_crm_and_personal_contacts"></view> </custom_views> <field id="CellularPhone"> <reader> <mapi_std> <mapi_tag id="0x3A1C0000"></mapi_tag> <convertor> <string/> </convertor> </mapi_std> </reader> <writer> <outlook_std> <outlook_field id="MobileTelephoneNumber"></outlook_field> <convertor> <string/> </convertor> </outlook_std> </writer> </field> <field id="stMembership"> <reader> <mapi_user> <user_field id="od Membership" ol_field_type="1"></user_field> <convertor><string/></convertor> </mapi_user> </reader> <writer> <outlook_user> <user_field id="od Membership" ol_field_type="1"></user_field> <convertor> <string/></convertor> </outlook_user> </writer> </field> … … </type>
Verify your changes, and save the forms_12.xml file.
Changing the XML Code in the forms_12.xml File
The new custom field must be displayed on the UI layout. The forms_nn.xml file is used to define the physical UI layout. Use Forms_12.xml for Microsoft Outlook 2007 and above.
In this example, you add the new Membership field under the existing Lead Source field in the Contact page.
To change the XML Code in the forms_12.xml File
Edit the forms_12.xml file.
Place the new field in a cell.
A label or a field must always be placed in a cell in the XML structure. Cells are aligned vertically or horizontally by enclosing them in stacks. Complete stacks are placed in cells, allowing them to be placed either vertically or horizontally again. The size of the cell is also specified on the cell. If the cell is part of a horizontal stack, then the size specification determines the width of the cell. If the cell is part of a horizontal stack, then the size specification determines the height of the cell. When you add your cell to a stack, you must increase the size of the cell that contains that stack. Otherwise, your field might be hidden in the UI.
The cell for the field label of the Membership field is as follows:
<cell size="22"> <static id="lbl_stmembership" tab_order="14"> <text>#lbl_membership</text> </static> </cell>The
#lbl_membershipdata is a reference to the string displayed in the UI that is set up in the package_res.xml file.The cell with the field is similar to the following example:
<cell size="22"> <edit id="stMembership" tab_order="14"> <field value="string">stMembership</field> </edit> </cell>This XML section specifies a text box that is linked to the new field. The field name must match the field created in the od_meta_info.xml file in Changing the XML Code in the od_meta_info.xml File.
Note: In the above cell examples, the values of the id and tab_order parameters must be unique. However, the tab_order parameter is optional, so you can remove it when testing the changes.Add the new Membership field under the existing Lead Source field in the Contact page, and increase the size of the horizontal stack so that the new field is visible between the existing Lead Source field and the Description text box.
The XML changes to the forms_12.xml file include:
Increasing the size of the cell from 210 to 250 to accommodate the new custom field, Membership. The element for the cell that holds the horizontal stack is as follows:
<cell size="250">
Inserting the field label for Membership under the existing label for Lead Source.
Inserting the text box for Membership under the field for Lead Source.
These changes are shown in the following example XML:
<cell size="250"> <stack layout="horz"> <cell size="7"> <stack layout="vert" spacing="1"> <cell size="1"/> <cell> <static id="lbl_required_sign"> <text>#lbl_required_sign</text> </static> </cell> </stack> </cell> <cell> <stack layout="horz" spacing="5"> <!-- left side captions --> <cell size="140"> <stack spacing="5" layout="vert"> … … <cell size="22"> <static id="0x20016" tab_order="15"><text>#lbl_lead_source</ text> </static> </cell> <cell size="22"> <static id="lbl_membership"> <text>#lbl_membership</text> </static> </cell> </stack> </cell> <!-- left side fields --> <cell> <stack layout="vert" spacing="5"> … … <cell size="22"> <combobox id="LeadSource" tab_order="16"> <field>LeadSource</field> <source type="ContactLeadSourcePicklist" field="Value"format=":[:(Label):]"> </source> </combobox> </cell> <cell size="22"> <edit id="stMembership" max_chars="100"> <field value="string">stMembership</field> </edit> </cell> … … </stack> </cell> </stack> </cell> </stack> </cell>
Verify your changes and save the forms_12.xml file.
Changing the XML Code in the package_res.xml File
The package_res.xml file contains the string translations for the string references that are used by the fields, which makes translating the UI easier because all the labels are in one place. You must add a new reference to this file for the new field label as described in this procedure.
The text that you enter for the <str> element is visible in the UI as the field name.
The value of the key attribute of the <str> element must be correctly referenced in the forms_12.xml file to display the field name, as shown in this example.
To change the XML code in the package_res.xml file
Edit the package_res.xml file.
Add the string reference for the Membership field as shown in the following example XML code:
<res_root> … … <!-- Contact form --> <str key="head_contact_details">Contact Details</str> <str key="lbl_job_title">Job title:</str> <str key="lbl_contact_team">Contact Team:</str> <str key="lbl_save_correspondence_to_crm">Automatically save contact emails to CRM</str> <str key="lbl_never_email">Never Email</str> <str key="head_comments">Comments</str> <str key="head_business_addresses">Business Addresses</str> <str key="head_private_addresses">Personal Addresses</str> <str key="btn_account_address_caption">Account Address...</str> <str key="btn_contact_address_caption">Contact Address...</str> <str key="lbl_membership">Membership: </str> … … </res_root>Verify your changes and save the package_res.xml file.
Adding Text Fields to Oracle CRM On Demand Desktop
This procedure shows how to add a text field called Department to an Oracle CRM On Demand Desktop form. Use this example as a reference to add other text fields and adjust the fields to your specific requirements. Before you begin this chapter, review the chapter on customization in Oracle CRM On Demand Desktop Administration Guide.
The following procedure adds a field called Department to the Contact form in the UI.
In this procedure, you make sure the field 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
forms_12.xml
package_res.xml
For information on the contents of these files, see About the Metadata Files Updated During Customization.
To add a text field to Oracle CRM On Demand Desktop
Make sure that the field, Department, is available through Oracle CRM On Demand Web services.
For information on using Web services, see Oracle Web Services On Demand Guide.
Update the metadata files for the new Department field:
Update od_meta_info.xml by adding Department to the metadata objects where making the objects available is necessary, in this example, the Contact object.
Locate the <object> element by TypeId attribute set to Contact. For example:
<object TypeId="Contact"…>
Add the new <field> element (Department) to define the field:
<field Name='Department' Label='Department' DataType='DTYPE_TEXT'/>
where:
Name is the name of new field. You can define any value, which is used to access this field value.
Label is the label that is used to reference this field in the UI, for example, on the Oracle CRM On Demand Desktop Control Panel.
DataType is the type of the field. For text fields, set its value to DTYPE_TEXT. For check boxes or other Boolean fields, set its value to DTYPE_BOOL. For more information on data types, see Changing the XML Code in the od_meta_info.xml File.
Update the od_basic_mapping.xml file:
Locate the <type> element by the id attribute set to Contact. For example:
<type id="Contact"…>
Add the new <field> element for Department to define the mapping:
<field id="Department"> <reader> <mapi_user> <user_field id="od Department" ol_field_type="1"></user_field> <convertor> <string/> </convertor> </mapi_user> </reader> <writer> <outlook_user> <user_field id="od Department" ol_field_type="1"></user_field> <convertor> <string/> </convertor> </outlook_user> </writer> </field>If you are adding a field to an object located in the DB FACADE storage, then the syntax for the field definition differs as in the following XML code:
<field id=" Department "> <type> <simple type="string"/> </type> </field>For more information on DB FACADE storage, see About Microsoft Outlook and DB FACADE Storage.
Update the forms_12.xml file:
Use this file to customize the Microsoft Outlook forms. The syntax to manipulate these files is similar to the syntax of the HTML tables. You can modify the forms_12.xml file in much the same way.
Add a new label control and a text field control for the Department field below the Job Title field on the Contact form.
To do this, insert a label, and a text field and add the XML code for the label to the section denoted by the comment "left side captions" inside the form with id = "OnDemand Contact". Insert the following XML code just after the cell containing the #lbl_job_title label control to add the new Department label. The text #lbl_department is used to specify a key that is used in the package_res.xml file to determine the localized value for the label, which is covered in the next step:
<cell size="22"> <static id="lbl_department"> <text>#lbl_department</text> </static> </cell>After adding the label, add the text field control, using the following XML code:
<cell size="22"> <edit id="department"> <field value="string">Department</field> </edit> </cell>You must add this XML under the section labeled by the comment: left side fields. In this case, you want to add the field just above the cell stack containing the ContactToAccount and btn_mvgAccount controls and just below the cell stack containing the status_image.
You must increase the size of the cell that houses all of these child objects to make more room for this new field on the UI by changing the size value from 210 to 235, for this example:
<cell size="235">
Update the package_res.xml file by adding the following element to the package_res.xml file to have the Contact form render the Department label through the associated key value:
<str key="lbl_department">Department</str>
The package_res.xml file is used to provide localized values and images to Oracle CRM On Demand Desktop. Because you have added the new Department field to the Contact form, you must provide the text for the label. In the modification of the forms_12.xml file in Step 4, you created a label control with the text value #lbl_department. The text value identifies the key to use in the package_res.xml file.
Adding Check Boxes to a Form
This topic describes how to display a check box on an Oracle CRM On Demand Desktop form. In this example, you add a Never Email check box to the UI form.
In this procedure, you update the following metadata files:
od_meta_info.xml
od_basic_mapping.xml
forms_12.xml
package_res.xml
For information on the contents of these files, see About the Metadata Files Updated During Customization.
To add a check box to a form
Update the od_meta_info.xml file:
Locate the <object> element by TypeId, for example, for a contact it is similar to the following:
<object TypeId='Contact' Label='#obj_contact' LabelPlural='#obj_contact_plural'>
Add a new <field> element to define the field, as follows:
<field Name='NeverEmail' Label='NeverEmail' DataType='DTYPE_BOOL' />
In this code, DataType is the type of the field. For check boxes or other Boolean fields, set DataType toDTYPE_BOOL. TypeID is the unique identifier of a type in the od_meta_info.xml file. When a type is defined, then the name is specified by the TypeId attribute.
Update the od_basic_mapping.xml file:
Locate the <object> element by the id attribute, for example, for a contact it is similar to the following:
<type id="Contact" predefined_folder="10" ver="2">
Add a new <field> element to define the mapping as follows:
<field id="NeverEmail"> <reader> <mapi_user> <user_field id="od NeverEmail" ol_field_type="6"></user_field> <convertor> <bool/> </convertor> </mapi_user> </reader> <writer> <outlook_user> <user_field id="od NeverEmail" ol_field_type="6"></user_field> <convertor> <bool/> </convertor> </outlook_user> </writer> </field>- The id attribute is the unique identifier of a type in the od_basic_mapping.xml file. When a type is defined, then the name is specified by the id attribute.
Update the forms_12.xml file by locating the object form, using the id attribute, and adding the code for check box control as follows:
<cell size="22"> <checkbox id="NeverEmail" tab_order="33"> <field>NeverEmail</field> <text>#lbl_never_email</text> </checkbox> </cell>where:
<field> is the field name from the od_basic_mapping.xml file.
<text> is the label resource id attribute from the package_res.xml file.
The id attribute is the unique identifier of a UI form of a type in the forms_XX.xml file. For example, a contact form definition is as follows:
<form id="OD Contact">
Update package_res.xml as follows:
<str key="lbl_never_email">Never Email</str>
Adding Currency Fields to a Form
This topic describes how to display a currency field, using a currency control on an Oracle CRM On Demand Desktop form. Although the currency control has field text in its name, it is a currency control.
<currency_field>CurrencyCode</currency_field>
In this example, you add an Annual Revenues currency field to the UI form. In this procedure, you update the following metadata files:
od_meta_info.xml
od_basic_mapping.xml
forms_12.xml
package_res.xml
For information on the contents of these files, see About the Metadata Files Updated During Customization.
To add a currency control field to a form
Update the od_meta_info.xml file as follows:
Add the following two field definitions for the proper type where the currency code and the currency amount are stored:
<field Name="CurrencyCode" Label="CurrencyCode" DataType="DTYPE_TEXT" HasPicklist="yes" PicklistTypeId='CurrencyPL' IsFilterable='yes'/> <field Name="AnnualRevenues" Label="AnnualRevenues" DataType="DTYPE_NUMBER" IsFilterable='yes'/>
Add the type definition that requires these fields, for example, for Opportunity:
<object TypeId='Opportunity' Label='#obj_opportunity'...> <field Name="CurrencyCode".../> <field Name="AnnualRevenues".../> ... </object>
Update the od_basic_mapping.xml file by adding the following XML section to the type definition that requires these fields:
<field id="CurrencyCode"> <reader> <mapi_user> <user_field id="od CurrencyCode" ol_field_type="1"></user_field> <convertor> <string/> </convertor> </mapi_user> </reader> <writer> <outlook_user> <user_field id="od CurrencyCode" ol_field_type="1"></user_field> <convertor> <string/> </convertor> </outlook_user> </writer> </field> <field id="AnnualRevenues"> <reader> <mapi_user> <user_field id="od AnnualRevenues" ol_field_type="3"></user_field> <convertor> <double/> </convertor> </mapi_user> </reader> <writer> <outlook_user> <user_field id="od AnnualRevenues" ol_field_type="3"></user_field> <convertor> <double/> </convertor> </outlook_user> </writer> </field>For example, for Opportunity, the structure is similar to the following:
<type id="Opportunity" display_name="#obj_opportunity_plural"...> <field id="CurrencyCode".../> <field id="AnnualRevenues".../> ... </type>Update the forms_12.xml file by adding the following XML sample code to update the UI layout by adding the label for the currency field:
<cell size="22"> <multi_currency id="AnnualRevenues" tab_order="46"> <currency_field>CurrencyCode</currency_field> <value_field>AnnualRevenues</value_field> </multi_currency> </cell>In this example,
<currency_field>and<value_field>are the field names from the od_basic_mapping.xml file.Add this code to the appropriate object type form, for example:
<form id="SBL Opportunity"> ... <cell size="22"> <multi_currency id="AnnualRevenues" tab_order="46"> ... </form>The steps for adding labels are provided in Changing the XML Code in the forms_12.xml File and are the same as for a text field.
Update the package_res.xml file by adding the resources for the label text.
The steps for adding the resources are provided in Changing the XML Code in the package_res.xml File and are the same as for a text field.
Adding Date Fields to a Form
This topic describes how to display a date field on an Oracle CRM On Demand Desktop form. In this example, you add Due Date and End Time date and datetime fields to the UI form. In this procedure, you update the following metadata files:
od_meta_info.xml
od_basic_mapping.xml
forms_12.xml
package_res.xml
For information on the contents of these files, see About the Metadata Files Updated During Customization.
To add a date field to a form
Update the od_meta_info.xml file by adding the following XML elements to define the fields, to the corresponding object type structure:
For a date only field type, add:
<field Name="DueDate" Label="DueDate" DataType="DTYPE_DATE" />
For a datetime field type, add:
<field Name="EndTime" Label="EndTime" DataType="DTYPE_UTCDATETIME" />
Update the od_basic_mapping.xml file by adding the following XML code to the corresponding object type structure:
<field id="DueDate"> <reader> <mapi_user> <user_field id="od DueDate" ol_field_type="5"></user_field> <convertor> <datetime/> </convertor> </mapi_user> </reader> <writer> <outlook_user> <user_field id="od DueDate" ol_field_type="5"></user_field> <convertor> <datetime/> </convertor> </outlook_user> </writer> </field>Note: For both the date and datetime field types, the mappings are equivalent, so only the XML for DueDate is shown.Update the forms_12.xml file to change the layout by adding the label for the following fields:
To add the date field, use the following XML sample code to the corresponding object type structure:
<cell> <datetime id="due" tab_order="13" type="date" store_time="false"> <field>DueDate</field> </datetime> </cell>To add the datetime field, use the following XML sample code to the corresponding object type structure:
<cell> <datetime id="end_time" tab_order="18" type="datetime"> <field>EndTime</field> </datetime> </cell>In the sample XML code, the content of the <field> element is the field name from the od_basic_mapping.xml file.
The steps for adding labels are provided in Changing the XML Code in the forms_12.xml File and are the same as for a text field.
Update the package_res.xml file by adding the resources for the label text.
The steps for adding the resources are provided in Changing the XML Code in the package_res.xml File and are the same as for a text field.
Adding Description Fields to a Form
This topic describes how to display a description field, using the Microsoft Outlook control for description fields on an Oracle CRM On Demand Desktop form. In this example, you add a field called Description to the UI form. In this procedure, you update the following metadata files:
od_meta_info.xml
od_basic_mapping.xml
forms_12.xml
package_res.xml
For information on the contents of these files, see About the Metadata Files Updated During Customization.
To add a description control field to a form
Update the od_meta_info.xml file by adding the following XML element to define the field to the corresponding object type structure:
<field Name="Description" Label="Description" DataType="DTYPE_TEXT" />
Update the od_basic_mapping.xml file by adding the following XML code to the corresponding object type structure:
<field id="Description"> <reader> <mapi_std> <mapi_tag id="0x10000000"></mapi_tag> <convertor> <multiline_string/> </convertor> </mapi_std> </reader> <writer> <outlook_std> <outlook_field id="Body"></outlook_field> <convertor> <multiline_string/> </convertor> </outlook_std> </writer> </field>Update the forms_12.xml file by adding the label for the description control field to update the UI layout.
To add the description control field, add the following XML to the corresponding object type structure:
<cell> <control id="description" tab_order="37" window_id="0x103f"></control> </cell>The steps for adding labels are provided in Changing the XML Code in the forms_12.xml File and are the same as for a text field.
Update the package_res.xml file by adding the resources for the label text.
The steps for adding the resources are provided in Changing the XML Code in the package_res.xml File and are the same as for a text field.
Adding Numeric Fields to a Form
This topic describes how to add a numeric field, using the edit control on an Oracle CRM On Demand Desktop form. In this example, you add two fields, Revenue and Number of Employees, to the UI form. In this procedure, you update the following metadata files:
od_meta_info.xml
od_basic_mapping.xml
forms_12.xml
package_res.xml
For information on the contents of these files, see About the Metadata Files Updated During Customization.
To add a numeric field to a form
Update the od_meta_info.xml file by adding the following XML elements to define the fields in the corresponding object type structure:
For a fraction, use
DataType="DTYPE_NUMBER":<field Name="Revenue" Label="Revenue" DataType="DTYPE_NUMBER" />
For an integer, use
DataType="DTYPE_INTEGER":<field Name="NumberEmployees" Label="NumberEmployees" DataType="DTYPE_INTEGER" IsFilterable='no'/>
Update the od_basic_mapping.xml file by adding the following XML sections to the corresponding object type structure:
For fractions, use the convertor,
<double/>:<field id="Revenue" ver="3"> <reader> <mapi_user> <user_field id="od Revenue" ol_field_type="3"></user_field> <convertor> <double/> </convertor> </mapi_user> </reader> <writer> <outlook_user> <user_field id="od Revenue" ol_field_type="3"></user_field> <convertor> <double/> </convertor> </outlook_user> </writer> </field>For integers, use the convertor,
<integer/>:<field id="NumberEmployees"> <reader> <mapi_user> <user_field id="od NumberEmployees" ol_field_type="3"></user_field> <convertor> <integer/> </convertor> </mapi_user> </reader> <writer> <outlook_user> <user_field id="od NumberEmployees" ol_field_type="3"></user_field> <convertor> <integer/> </convertor> </outlook_user> </writer> </field>
Note: If you are adding a field to the DB FACADE storage, then use the following syntax:<field id="NumberEmployees"> <type> <simple type="integer"/> </type> </field>Update the forms_12.xml file by adding the label for the numeric field to update the UI layout:
For a fraction, use
<field value="double">:<edit id="Revenue" max_chars="15" tab_order="50"> <field value="double" precision ="2">Revenue </field> </edit>In this example, precision is the precision value; that is, the number of decimal places that is allowed after a comma.
For an integer, use
<field value="integer">:<edit id="NumberEmployees" max_chars="15" tab_order="50"> <field value="integer">NumberEmployees</field> </edit>In this example, the content of the <field> element is the field name from the od_basic_mapping.xml file.
The steps for adding labels are provided in Changing the XML Code in the forms_12.xml File and are the same as for a text field.
Update the package_res.xml file by adding the resources for the label text.
The steps for adding the resources are provided in Changing the XML Code in the package_res.xml File and are the same as for a text field.
Adding a Picklist Field in Oracle CRM On Demand Desktop
This topic shows how to add a picklist field to the Contact object type.
Before You Begin
Review the chapter on customization in Oracle CRM On Demand Desktop Administration Guide.
In this procedure, you update the following metadata files:
od_meta_info.xml
od_basic_mapping.xml
forms_12.xml
For information on the contents of these files, see About the Metadata Files Updated During Customization.
To add a picklist to the Contact object type
Define the objects and fields to synchronize with Oracle CRM On Demand as follows:
Use an XML editor to open the od_meta_info.xml file.
In the od_meta_info.xml file, locate the following element:
<object TypeId='Contact' ...>
The <object> element contains several child <field> elements. These child elements define the fields in the Contact object.
Add the following <field> element as a child of the <object TypeId='Contact' ...> element:
<field Name="ContactType" Label="Contact Type" DataType="DTYPE_TEXT" HasPicklist="yes" CRMName="Contact Type" />
In this example, ContactType is the exact field name that is used in SOAP queries.
Save and close the od_meta_info.xml file.
Map the picklist field from the Contact object in the Oracle CRM On Demand database to a field in Oracle CRM On Demand Desktop as follows:
Use an XML editor to open the od_basic_mapping.xml file.
In the od_basic_mapping.xml file, locate the following element:
<type id="Contact" ...>
The <object> element contains several child <field> elements. These child elements define the fields in the Contact object.
Add the following <field> element as a child element of the <object TypeId='Contact' ...> element:
<field id="ContactType"> <reader> <mapi_user> <user_field id="od ContactType" ol_field_type="1"></user_field> <convertor> <string/> </convertor> </mapi_user> </reader> <writer> <outlook_user> <user_field id="od ContactType" ol_field_type="1"></user_field> <convertor> <string/> </convertor> </outlook_user> </writer> </field>Create a new object type for the picklist.
To create a new object type for the picklist, you must use the following format for the value of the id attribute of the <type> element:
<type id="object_namefield_namePicklist">
where:
object_name is the name of the object type in the od_meta_info.xml file.
field_name is the name of the field in the object that you define in object_name.
In this example for the Contact Type field, add the following XML code inside the
<database><types>…</types></database>elements:<type id = "ContactContactTypePicklist" icon = "type_image:Generic:16"> <field id = "Label"> <type> <simple type = "string"/> </type> </field> <field id = "Value"> <type> <simple type = "string"/> </type> </field> <field id = "SortOrder"> <type> <simple type = "integer"/> </type> </field> <field id = "IsDefault"> <type> <simple type = "boolean"/> </type> </field> <field id = "ParentCode"> <type> <simple type = "string"/> </type> </field> </type>Customize the picklist control on the form layout by adding the following code in forms_12.xml in the vertical stack, as an example:
<cell size="22"> <combobox id="ContactType" tab_order="16"> <items format=":[:(Label):]" value_column="Value" has_null_item="false"> <source type="auto" name="ContactContactTypePicklist"/> <order_by> <order ascend="true">SortOrder</order> </order_by> </items> <field>ContactType</field> </combobox> </cell>where:
The attribute name of <source> is equal to the object type for the for the picklist form in Step d.
<field> contains the name of the picklist field.
The has_null_item attribute of <items> is set to false to prevent picking an empty value from the picklist.
For more information on a vertical stack, see Adding Multiselect Picklists to an Oracle CRM On Demand Desktop Form.
Adding a Cascading Picklist to Oracle CRM On Demand Desktop
Cascading picklists restrict the values of one picklist, the related picklist, based on the value selected in another picklist, the parent picklist. In this example, a parent picklist for opportunities presents a picklist called Status, and drives the value of a related picklist called ReasonWonLost.
Before You Begin
Ensure you have added both picklists to the od_meta_info.xml, od_basic_mapping.xml, and forms_12.xml metadata files. For more information, see Adding a Picklist Field in Oracle CRM On Demand Desktop. Also ensure that the forms_12.xml metadata file contains the following code:
<cell size="22">
<combobox id="cbx_Status" tab_order="26
<items format=":[:(Label):]" value_column="Value" has_null_item="true">
<source type="auto" name="OpportunityStatusPicklist"/>
<order_by>
<order ascend="true">SortOrder</order>
</order_by>
</items>
<field>Status</field>
</combobox>
</cell>
<cell size="22">
<combobox id="cbx_ReasonWonLost" tab_order="32">
<items format=":[:(Label):]" value_column="Value" has_null_item="true">
<source type="auto" name="OpportunityReasonWonLostPicklist"/>
<order_by>
<order ascend="true">SortOrder</order>
</order_by>
</items>
<field>ReasonWonLost</field>
</combobox>
</cell>
For information on the contents of the form_12.xml metadate file, see About the Metadata Files Updated During Customization.
To add a cascading picklist to Oracle CRM On Demand Desktop
In the forms.js metadata file, locate the Opportunity form handler function:
function od_opportunity_form(ctx)
Add the following code to the Opportunity form handler:
function Status_control_changed() { var status = (form.cbx_Status.value != null) ? form.cbx_Status.value : form.item.Status; update_picklistReasonWonLost_control(status); }The Opportunity form handler calls this function when the value of the parent picklist is changed. This function obtains the new value of the parent picklist and passes this value to the related picklist.
Add the following code to the Opportunity form handler:
function update_picklistReasonWonLost_control(parent_value) { if (parent_value == null || parent_valueparent_value = "{C22EE487-1B92-4ba0-BC8D- E1368E110FFE}";// this line is just to make sure that we created unique value for the parent value and filtered current picklist correctly { parent_value = "{C22EE487-1B92-4ba0-BC8D-E1368E110FFE}";// this line is just to make sure that we created unique value for the parent value and filtered current picklist correctly form.cbx_ReasonWonLost.items.filter = session.create_expression("ParentCode", "ne", parent_value); return; } var pl_filter = ctx.session.create_criteria("or"); pl_filter.add(ctx.session.create_expression("ParentCode", "eq", parent_value)); pl_filter.add(ctx.session.create_expression("ParentCode", "eq", "")); pl_filter.add(od_helpers.create_expression_or_null_value_filter(ctx.session, "ParentCode", "eq", null)); form.cbx_ReasonWonLost.items.filter = pl_filter; }This function checks the value of the parent picklist. If the value of the parent picklist is empty, then all values in the related picklist are visible. If the parent picklist is populated, then the values in the related picklist are filtered, depending on the value in the parent picklist.
In the Opportunity form handler function, add the following code to the picklist you want to change:
ctx.events.connect(form.cbx_Status, "changed", Status_control_changed);
In the Opportunity form handler function, add the following code:
Status_control_changed();
This code enables the filtering of the parent picklist.
Save the forms.js metadata file.
Adding Multiselect Picklists to an Oracle CRM On Demand Desktop Form
This topic shows how to add multiselect picklists using an example. It shows you how to add the picklist into the Contact form in the UI. Use this example as a reference to add other multiselect picklist fields, and adjust them for your specific requirements.
Before You Begin
Review the chapter on customization in Oracle CRM On Demand Desktop Administration Guide.
The following procedure adds a multiselect picklist to the Contact form. Clicking the ... button in the multiselect picklist launches a dialog box to select field values.
In this procedure, you update the following metadata files:
od_meta_info.xml
od_basic_mapping.xml
forms_12.xml
forms.js
For information on the contents of these files, see About the Metadata Files Updated During Customization.
To add a multiselect picklist to an Oracle CRM On Demand Desktop form
Define the objects and fields to synchronize with Oracle CRM On Demand as follows:
Use an XML editor to open the od_meta_info.xml file.
In the od_meta_info.xml file, locate the following element:
<object TypeId='Contact' ...>
The <object> element contains several child <field> elements. These child elements define the fields in the Contact object.
Add the following <field> element as a child of the <object TypeId='Contact' ...> element:
<field Name="msplTest_MSP" Label="msplTest_MSP" DataType="DTYPE_CSVLIST" HasPicklist="yes" IsFilterable='no'/>
In this example, msplTest_MSP is the field name that is used in SOAP queries.
Save and close the od_meta_info.xml file.
Map the multiselect picklist field from the Contact object in the Oracle CRM On Demand database to a field in Oracle CRM On Demand Desktop as follows:
Use an XML editor to open the od_basic_mapping.xml file.
In the od_basic_mapping.xml file, locate the following element:
<type id="Contact" ...>
The <object> element contains several child <field> elements. These children define the fields in the Contact object.
Add the following <field> element as a child element of the <object TypeId='Contact' ...> element:
<field id="msplTest_MSP"> <reader> <mapi_user> <user_field id="od msplTestMSP" ol_field_type="1"> </user_field> <convertor> <multivalue_string/> </convertor> </mapi_user> </reader> <writer> <outlook_user> <user_field id="od msplTestMSP" ol_field_type="1"> </user_field> <convertor> <multivalue_string/> </convertor> </outlook_user> </writer> </field>Create a new object type for the picklist.
To create a new object type for the picklist, you must use the following format for the value of the id attribute of the <type> element:
<type id="object_namefield_namePicklist" predefined_folder="1">
where:
object_name is the name of the object type in the od_meta_info.xml file.
field_name is the name of the field that resides in the object that you define in object_name.
In this example, add the following XML code inside the
<database><types>…</types></database>elements:<type id="ContactmsplTest_MSPPicklist" icon="type_image:ContactmsplTest_MSPPicklist:16"> <field id ="Label"> <type> <simple type="string"/> </type> </field> <field id ="Value"> <type> <simple type="string"/> </type> </field> <field id ="SortOrder"> <type> <simple type="integer"/> </type> </field> <field id ="IsDefault"> <type> <simple type="boolean"/> </type> </field> </type>
Customize the multiselect picklist control on the form layout for the multiselect picklist by adding the following code in forms_12.xml in the vertical stack, as an example:
<cell size="21"> <stack layout="horz"> <cell> <scriptable_edit id="msp_edit" multiline="true"> <field value="string"></field> </scriptable_edit> </cell> <cell size="5"></cell> <cell size="22"> <button id="btn_msp_edit"><text>...</text> </button> </cell> </stack> </cell>where:
<scriptable_edit> is a text box with values.
<button> is the multiselect picklist button that displays the multiselect picklist dialog box.
The number of items displayed in the multiselect picklist control is determined by the value of the size attribute of the containing <cell> element.
For more information on a vertical stack, see About Vertical and Horizontal Stacks.
Customize a form handler in the forms.js file to set up a multiselect picklist layout control by adding the following JavaScript code to the Contact form handler:
var t_msp = new msp_ctrl(ctx, ctx.form.msp_edit, ctx.form.btn_msp_edit, {"source_type": " ContactmsplTest_MSPPicklist ", "dest_field_name": "msplTest_MSP"});The msp_ctrl function accepts the following parameters, where:
ctx is a global object that includes many other objects used to display the UI form and to control events, links, and so on.
ctx.form.msp_edit is the <scriptable_edit> control object. The msp_edit portion must be an appropriate scriptable edit form control ID from the forms_XX.xml file. This control is defined using the <scriptable_edit id="…"> element that is specific to an example. This control object contains the reference to the scriptable edit control with the msp_edit identifier, defined in Step 3. The ctx.form portion is a generic string that is left unchanged.
ctx.form.btn_msp_edit is the <button> control object. The btn_msp_edit portion must be an appropriate button form control ID from the forms_XX.xml file; this control is defined using the
<button id="…">element that is specific to an example. This control object contains the reference to the button control with the btn_msp_edit identifier defined in Step 3. The ctx.form portion is a generic string that is left unchanged.{"source_type": "ContactmsplTest_MSPPicklist", "dest_field_name": "msplTest_MSP"}This options object has the following properties, where:
source_type is the name of the type where picklist items are stored. This property is required.
dest_field_name is the name of the MSP field. This property is required.
ui_delimiter is the delimiter for selected items that is used on the form. The delimiter is a comma (,) by default. (Optional)
max_selected is the number of allowed items that can be selected. The default is 10. (Optional)
About Vertical and Horizontal Stacks
A stack is a group of controls that are placed inside the <stack> element vertically or horizontally depending on the type of stack. The structure for a vertical stack is as follows:
<stack layout="vertical"> <cell><button...></button></cell> <cell><button...></button></cell> </stack>
In this example, two buttons are placed vertically on the UI form. If you use a horizontal stack, then the buttons are placed horizontally on the UI form.
Setting Up Books for Oracle CRM On Demand Desktop Objects
Oracle CRM On Demand Desktop supports the book record visibility model. With this feature, you can configure Oracle CRM On Demand Desktop to allow users to synchronize records based on either a book, owner, or team visibility. The list of object types for which users can set up visibility modes is available through the Record Set tab of Oracle CRM On Demand Desktop Control Panel. By default, users can see the Record Set tab in the First Run Assistant wizard.
The following topics describe how to configure the various book-related features in the Oracle CRM On Demand Desktop customization package:
For additional book-related setup information, see Process of Adding Book Support to a New Top-Level Object.
Setting Up Books for an Object Type
After you set up book support for a particular object type, that type becomes visible in the Record Set tab of the Oracle CRM On Demand Desktop Control Panel. This visibility allows users to choose and configure the visibility model that they want to use. If book support is not set, then the object type disappears from the Record Set tab, and the visibility for the type is set to the default visibility. The default visibility is owner and team visibility. If the following setting inside a type definition is set to true, then book visibility is set up. Otherwise, book visibility is not set up.
<access_mode_config BooksSupported="true" >...</access_mode_config>
To set up books for an object type, for example, Opportunity, complete the steps in the following procedure:
To set up books for an object type
Open the od_meta_info.xml file, and find the type definition by TypeId, in this example, Opportunity:
<object TypeId="Opportunity" ...>
Inside the <object> element, locate the <access_mode_config> element.
Update the BooksSupported attribute of the <access_mode_config> element to
TRUE.If you have set up the object element correctly, then the Opportunity type appears in the Record Set tab in the Synchronization Control Panel window.
Disabling Book Visibility for an Object Type
Complete the following procedure if you want to disable book visibility for an object type.
To disable book visibility for an object type
Set the BooksSupported attribute of the <access_mode_config> element to
FALSEfor that object type.The object type disappears from the Record Set tab in the Synchronization Control Panel window.
Configuring the Include Sub-Items Option
Complete this procedure to configure an Include Sub-Items option for users in the Select Book window for object types that support books. Users can select this option when they are configuring a book in the Record Set tab in the Synchronization Control Panel window. By default, the Include Sub-Items option is not set up.
To configure the Include Sub-Items option
Edit the od_helpers.js file, available in the Oracle CRM On Demand Desktop customization package.
At the top of the file, locate the following definition of the
allow_includesubbooksvariable:var allow_includesubbooks = { // "Account": true }Add type names within the braces with the value set to true or false, depending on whether you want to allow or disallow the option for the user.
For example, if you uncomment the line in Step 2 for Account, the Include Sub-Items check box is displayed in the Select Book window for Account on the Record Set tab in the Synchronization Control Panel window.
Record Types That Support Books
The following table lists the Oracle CRM On Demand record types that support book functionality:
Table Record Types That Support Books
Account |
Exam |
Opportunity |
Accreditation |
Financial Account |
Partner |
Allocation |
Financial Plan |
Policy |
Application |
Fund |
Portfolio |
Appointment |
HCP Contact Allocation |
Program |
Business Plan |
Household |
Sample Lot |
Campaign |
Inventory Audit Report |
Sample Transaction |
Certification |
Inventory Period |
Service Request |
Contact |
Lead |
Smart Call |
Course |
MDF Request |
Solution |
Custom Objects |
MedEd Event |
Special Pricing Request |
Deal Registration |
Messaging Plan |
Task |
Dealer |
Objective |
Vehicle |
For more information on Oracle CRM On Demand book support, see Oracle CRM On Demand Online Help
Process of Adding Book Support to a New Top-Level Object
When you add a new top-level object to Oracle CRM On Demand Desktop, perform the following procedures to set up book support for that object:
Configuring the Access Mode for the Object Type
If you have added a new top-level object that supports books to the customization package, then you must configure book support in the od_meta_info.xml file. To view a list of top-level objects that support books refer to Record Types That Support Books.
This task is a step in Process of Adding Book Support to a New Top-Level Object.
To configure the access mode for the object type
Edit the od_meta_info.xml file, available in the Oracle CRM On Demand Desktop customization package.
Locate the type definition; that is, the <object> element, and add the following <access_mode_config> element, within the <object> element:
<object TypeId="TypeName"> <access_mode_config BooksSupported="true" > <involved_fields> <field Name="Owner" /> <field Name="BookName" /> </involved_fields> <scopes> <scope Id="Dedup" BookId="" /> <scope Id="ONLKP" BookId="" /> </scopes> </access_mode_config> ... </object>You can update the BooksSupported attribute of the <access_mode_config> element to turn off book support at any time. For more information, see Setting Up Books for an Object Type.
Save the od_meta_info.xml file.
Adding a Book Id Field to an Object Type
After you add a new object type that supports books, you must add a BookId field to the type definition in od_meta_info.xml and od_basic_mapping.xml. The type of field is string.
For guidelines on how to add a new field to an object, see Adding Custom Fields to Oracle CRM On Demand Desktop. To view a list of top-level objects that support books refer to Record Types That Support Books.
This task is a step in Process of Adding Book Support to a New Top-Level Object.
Adding Book Selector Controls to Form UI
The following topics describe how to add book selector controls to forms:
To view a list of top-level objects that support books refer to Record Types That Support Books.
This task is a step in Process of Adding Book Support to a New Top-Level Object.
Adding UI Controls for Books
This procedure shows you how to add the UI controls to display a record's book on a form UI scriptable autocomplete control, which shows the books tree dialog that is used. This procedure shows how the control is set up on an Opportunity form.
The tree view of a book is displayed on the UI with a scriptable autocomplete control and a button control. These controls display a dialog box, showing the book’s tree. The scriptable autocomplete control is an expanded version of an autocomplete control. Both autocomplete and scriptable autocomplete controls are used to display associated records, but scriptable autocomplete control can be implemented with additional logic for the value that the control displays. For more information on control elements used in the forms_XX.xml file, see Changing the XML Code in the forms_12.xml File.
To add a UI control for a book
Edit the forms_12.xml file, available in the Oracle CRM On Demand Desktop customization package.
Locate the record's Team control in forms_12.xml, add the Book UI control on the form UI underneath this control, and update head_opportunity_book_info for your new type label.
In the following XML code:
The first cell, <cell size="13">...</cell>, contains two controls:
<static id="head_opportunity_book_info">, which is a label acting as a header.
<edge id="book_separator"/>, which is a horizontal ruler that underlines the header.
The second cell, <cell size="22">...</cell>, contains a static control label under the
<!-- right side captions -->text and a scriptable autocomplete control under<!-- right side fields -->.
Each control has a unique identifier (ID), which is used to refer to the control within the script. For example, for the button control <button id="btn_book_select">, the ID is btn_book_select. The value for all names that are prefixed with the number sign (#) as in the name #btn_book_select are specified in the package_res.xml file.
The Book UI control XML code is as follows:
<cell size="13"> <stack layout="horz"> <cell size="110"> <static id="head_opportunity_book_info"> <text>#head_opportunity_book_info</text> </static> </cell> <cell> <stack layout="vert"> <cell size="7"></cell> <cell size="1"> <edge id="book_separator"/></cell> </stack> </cell> </stack> </cell> <cell size="22"> <stack layout="horz" spacing="5" padding="5"> <!-- right side captions --> <cell size="122"> <stack spacing="5" layout="vert"> <cell size="22"> <static id="lbl_book_of_business"> <text>#lbl_book_of_business</text> </static> </cell> </stack> </cell> <!-- right side fields --> <cell> <stack spacing="5" layout="vert"> <cell size="22"> <stack layout="horz"> <cell> <scriptable_edit id="book_of_business" tab_order="39"> <field value="string"></field> </scriptable_edit> </cell> <cell size="5"></cell> <cell size="22"> <button id="btn_book_select" tab_order="40"> <text>#btn_book_select</text> </button> </cell> </stack> </cell> </stack> </cell> </stack> </cell>Note: You must set the scriptable edit control Id and the book selector button control Id to btn_book_select. Otherwise, the UI controls will not function.Save the forms_12.xml file.
Registering the UI Controls in the Form Handler
After the UI controls have been added to the forms_12.xml file, register the controls in the form handler by completing the following procedure.
To register the UI controls in the form handler
Edit the forms.js file, and locate the form handler function.
For example, for an Opportunity record, the function is od_opportunity_form().
Add the following function call inside the form handler function:
register_book_control(ctx, team_control_id);
In this function call, team_control_id is the Id of Team autocomplete_list control on a form. For example,:
Locate the Id of the autocomplete_list control that displays the record's team, for example:
<autocomplete_list id="TeamToOpportunity" tab_order="36">
For the above autocomplete_list control example Id, define the function register_book_control() as follows:
register_book_control(ctx, "TeamToOpportunity");
The team_control_id argument is not required if no team is associated with the object. For example, for an Opportunity object, the function looks like the following:
register_book_control(ctx, "TeamToOpportunity");
Note: Add the register_book_control() function call anywhere after the ctx.form_links_manager.init_new(); line. Otherwise, book prefilling will not work properly when a new record is created. For more information on book prefilling, see Prefilling the Default Book on New Records.Save the forms.js file.
The form is populated with a control for the selected book name, and the button that brings up a dialog box displaying a book tree. Using this dialog box, a user can select different book.
About Book Prefilling
Prefilling is the process of automatically assigning predefined values to certain fields when a new record is created. Default values or functions that calculate default values must be linked to the fields that users want to have prefilled when they create a new record. This linking is specified in the business_logic.js file. In this example, the Book Name field is automatically prefilled with the value Book_12... after an Opportunity form is opened. For instructions to configure Oracle CRM On Demand Desktop so that when a user creates a new record, the default book is automatically added to the book for the field displaying the record, see Setting Up Books for Oracle CRM On Demand Desktop Objects.
The following line links the BookId field with the prefill_book function that returns the ID of the book to prefill the field.
scheme.objects.get_object("TypeName").get_field("BookId")["initial_value_fn"] =
prefill_book;
The algorithm implemented in the function is as follows:
Get the book that a user has selected on the Record Set tab on the Synchronization Control Panel.
If the user did not select a book, then get the book that is set as the default for the object type from the ::DefaultsTypeDefaultBookPicklist picklist. This picklist sets the default books for object types.
If the book is not available; that is, there is no default book for the record, then get the book that is set as the default for the current user regardless of the object type from the ::DefaultsBookPicklist picklist. This picklist sets the default book for users.
If the default book for the user is not available, then do not return a value, and the Book Name field is not prefilled.
If the book ID is obtained from any of the preceding steps, then check whether the book can contain values or whether the book is only a container for other books. Return the book's ID if the book can contain values, or do not return any ID if the book is a container.
To set up default book prefilling, see Prefilling the Default Book on New Records.
Prefilling the Default Book on New Records
To set up default book prefilling on the form when a user creates a new record, complete the following procedure. For more information on book prefilling, see About Book Prefilling. To view a list of top-level objects that support books refer to Record Types That Support Books.
After you complete this procedure, a default book for the object type is populated on the form when a user creates a new item.
This task is a step in Process of Adding Book Support to a New Top-Level Object.
To prefill the default book on new records
Edit the business_logic.js file, and locate the create_ondemand_meta_scheme2() function.
Insert the following code anywhere inside that function:
scheme.objects.get_object("TypeName").get_field("BookId")["initial_value_fn"] = prefill_book;In this code, TypeName is the name of the object type for which you are setting up book prefilling, for example, Opportunity. After you add this code, a default book for the object type is populated on the form when a user creates a new item.
You can specify any top-level type name, such as Account, Contact, or Opportunity for TypeName. However, if you are defining book prefilling for an Activity type, then you must link the prefill_activity_book function and not the prefill_book function as follows:
scheme.objects.get_object("Activity").get_field("BookId")["initial_value_fn"] = prefill_activity_book;Add the prefill_book function and prefill_activity_owner functions inside the create_ondemand_meta_scheme2() function under the
//Defaultingcomment:function prefill_book(ctx, type_id) { type_id = type_id || ctx.item_ex.get_type(); var ownership_mode = od_helpers.get_ownership_mode(ctx, type_id); switch (ownership_mode) { case "book": var user_selected_book = od_helpers.get_ol_storage_rs_book(ctx, type_id); var book_id = user_selected_book != null ? user_selected_book.BookId : ""; if (!book_id) { var default_book = ctx.session.find_item("::DefaultsTypeDefaultBookPicklist", ctx.session.create_expression("Value", "eq", type_id)); book_id = default_book != null ? default_book.BookId : ""; } if(!book_id) { var defaults = helpers.get_defaults(ctx.session), user_default_book_name = defaults != null ? defaults.DefaultBookName : "", user_default_book = ctx.session.find_item("::DefaultsBookPicklist", ctx.session.create_expression("Label", "eq", user_default_book_name)); book_id = user_default_book != null ? user_default_book.Value : book_id; } if(od_helpers.book_can_contain_data(ctx, book_id)) return book_id; break; default: return ""; break; } } function prefill_activity_owner(ctx) { return prefill_owner(ctx, "Activity"); }Save the updated business_logic.js file.