20Migrating Search Layouts
Migrating Search Layouts
This chapter describes how to migrate custom search layouts using the command-line interface of the Oracle Migration Tool On Demand client. It contains the following topics:
Search Layouts
A search layout for a record type determines which fields users can search on when searching for records of that type, and also which fields are displayed in the search results page. Search layouts also determine some of the features in Lookup windows and whether smart associations are enabled. A default search layout is provided for each record type. For many record types, you can create multiple custom search layouts and assign them to user roles. For more information about search layouts, see Oracle CRM On Demand Online Help.
The following table describes the Oracle Migration Tool On Demand client commands used with search layouts. These commands are case sensitive.
Table Commands Used with Search Layouts in Oracle Migration Tool On Demand
Command | Description |
---|---|
|
This command extracts all of the custom search layouts for a specific record type (object), or a single custom layout (if the SearchLayoutName parameter is specified). The parameters are as follows:
|
|
This command extracts all of the custom search layouts for all objects. |
|
This command updates or inserts a custom search layout. |
Privileges Required for Migrating Search Layouts
The following privileges are required for the user account running the Oracle Migration Tool On Demand client commands:
For the
Read
andReadAll
commands: Enable Web Services Access and Customize Application.For the
Upsert
command: Enable Web Services Access, Customize Application, and Manage Object Access for custom objects that have been set up in the company tenant, for example, Customize Application - Manage Custom Object 01, and so on.
For information about setting and checking privileges, see Oracle CRM On Demand Online Help.
Elements and Sections in the Search Layout XML Output File
The following table describes the elements and sections in the search layout XML output file.
Table Elements and Sections in the Search Layout XML File
Description | Element or Section |
---|---|
The <SearchLayout> section contains all of the information for a single search layout. |
<data:SearchLayout> . . . </data:SearchLayout> |
<ObjectName> contains the system name of the record type (object), which never changes. |
<data:SearchLayout> <data:ObjectName>Account</data:ObjectName> . . . </data:SearchLayout> |
<LayoutName> contains the name of the layout. |
<data:SearchLayout> . . . <data:LayoutName>TestLayout</data:LayoutName> . . . </data:SearchLayout> |
<LastUpdatedBy> contains the date and time the layout was last updated. |
<data:SearchLayout> . . . <data:LastUpdatedBy>10/17/2012 12:41:05 </data:LastUpdatedBy> . . . </data:SearchLayout> |
<Description> contains the description for the layout. |
<data:SearchLayout> . . . <data:Description>This is a test layout. </data:Description> . . . </data:SearchLayout> |
The <ListOfSpecifySearchFields> section contains the details of the search fields for the layout. |
<data:SearchLayout> . . . <data:ListOfSpecifySearchFields> . . . </data:ListOfSpecifySearchFields> . . . </data:SearchLayout> |
The <SearchLayoutField> section includes the following elements for a single search field:
|
<data:SearchLayout> . . . <data:ListOfSpecifySearchFields> <data:SearchLayoutField> <data:FieldName>Name_Shadow </data:FieldName> <data:SearchOptimization>2 </data:SearchOptimization> <data:Section>1</data:Section> <data:Order>0</data:Order> </data:SearchLayoutField> . . . </data:ListOfSpecifySearchFields> . . . </data:SearchLayout> |
The <ListOfDefineSearchResultsLayout> section contains the details of the search result fields for the layout. |
<data:SearchLayout> . . . <data:ListOfDefineSearchResultsLayout> . . . <data:ListOfDefineSearchResultsLayout> . . . </data:SearchLayout> |
The <SearchLayoutField> section includes the following elements for a single search result field:
|
<data:SearchLayout> . . . <data:ListOfDefineSearchResultsLayout> <data:SearchLayoutField> <data:FieldName>Name_Shadow </data:FieldName> <data:SearchOptimization>2 </data:SearchOptimization> <data:Section>1</data:Section> <data:Order>0</data:Order> </data:SearchLayoutField> </data:ListOfDefineSearchResultsLayout> . . . </data:SearchLayout> |
The <ListOfDefaultSearchValues> section contains all of the default values for the fields in the list of targeted search fields, corresponding to Step 3 in the Search Layout wizard in the UI. |
<data:SearchLayout> . . . <data:ListOfDefaultSearchValues> . . . <data:ListOfDefaultSearchValues> . . . </data:SearchLayout> |
The <DefaultSearchField> section includes the following elements for a single search field:
|
<data:SearchLayout> . . . <data:ListOfDefaultSearchValues> <data:DefaultSearchField> <data:FieldName>Indexed Boolean 0 </data:FieldName> <data:DefaultSearchCondition>Is Checked </data:DefaultSearchCondition> <data:DefaultSearchValue>Is Checked </data:DefaultSearchValue> <data:DefaultSearchValueAssocId/> </data:DefaultSearchField> </data:ListOfDefaultSearchValues> . . . </data:SearchLayout> |
<RestrictSearchToFieldsSelectedInRelatedInformationLayout> corresponds to the Restrict Search to Fields Selected in Related Information Layout check box in the UI. In certain cases where a field is not displayed in a list of related records, the setting in this check box is considered to determine if the field is available as a search field for searches of related records even though the field is not displayed in the list of related records. |
<data:SearchLayout> . . . <data:RestrictSearchToFieldsSelectedInRe latedInformationLayout>false </data:RestrictSearchToFieldsSelectedIn RelatedInformationLayout> . . . </data:SearchLayout> |
<EnableDivisionAsDefaultSearchField> corresponds to the Configure Lookup Window with Division as the Default Search Field check box in the UI. This element is applicable for search layouts for the Product record type only. If this element is set to true, then the Division field is the default search field and it is prepopulated with the user's primary division. If this element is set to false, then the Product Name field is the default search field, unless the <EnableFirstTargetedFieldAsLookupDefault> element is set to true, in which case the first field in the list of targeted search fields in the search layout is used as the default search field. |
<data:SearchLayout> . . . <data:EnableDivisionAsDefaultSearchField> false </data:EnableDivisionAsDefaultSearchField> . . . </data:SearchLayout> |
<EnableDefaultFields> corresponds to the Configure Lookup Window With Default Fields check box in the UI. It determines which fields appear in the search results in the Lookup windows for the record type, as follows:
|
<data:SearchLayout> . . . <data:EnableDefaultFields>true </data:EnableDefaultFields> . . . </data:SearchLayout> |
<EnableDefaultSearchResults> corresponds to the Show Search Results When Lookup Window Opens check box in the UI. It determines whether a list of available records is displayed in the Lookup window when it opens (true), or no records are displayed when the Lookup window opens (false). |
<data:SearchLayout> . . . <data:EnableDefaultSearchResults>true </data:EnableDefaultSearchResults> . . . </data:SearchLayout> |
<EnableAutoResolve> corresponds to the Auto-Resolve Enabled check box in the UI. It determines whether smart associations are enabled (true) or are not enabled (false). Smart associations are automatic searches that make it easier for users to associate records of different record types, such as account, contact, opportunity, activity, and so on with each other. For more information about smart associations, see Oracle CRM On Demand Online Help. |
<data:SearchLayout> . . . <data:EnableAutoResolve>true </data:EnableAutoResolve> . . . </data:SearchLayout> |
<EnableDefaultCtxSensitiveList> corresponds to the Show Context-Sensitive List as Lookup Window Default check box in the UI. It determines whether any available context-sensitive lists appear before the other lists in the record-type List field in the upper-left corner of Lookup windows (true), or appear after the system lists (false).
Note: This check box is effective only if the Show Context-Sensitive List as Lookup Window Default option is set to Enabled on the company profile.
|
<data:SearchLayout> . . . <data:EnableDefaultCtxSensitiveList> false</data:EnableDefaultCtxSensitiveList> . . . </data:SearchLayout> |
<EnableKeywordSearch> corresponds to the Configure Enhanced Keword Search with Selected Search Results Fields check box in the UI. It determines which fields appear in the search results when an ehanced keyword search is performed for the record type, as follows:
|
<data:SearchLayout> . . . <data:EnableKeywordSearch>false </data:EnableKeywordSearch> . . . </data:SearchLayout> |
<EnableFirstTargetedFieldAsLookupDefault> corresponds to the First Targeted Search Field as Default Search in Lookups check box in the UI. It determines whether the first field in the list of targeted search fields in the search layout is used as the default search field in the Quick Filter in the Lookup window (true), or the preconfigured default search field is used (false).
Note: For the Product record type only, the setting in the <EnableDivisionAsDefaultSearchField> element takes precedence over the setting of the <EnableFirstTargetedFieldAsLookupDefault> element.
|
<data:SearchLayout> . . . <data:EnableFirstTargetedFieldAsLookup Default>false </data:EnableFirstTargetedFieldAsLookup Default> . . . </data:SearchLayout> |
<EnableDefaultSort> corresponds to the Auto-Populate Sort Field in New List and Advanced Search check box in the UI. It specifies whether the default sort field is automatically selected (true) or no sort field is automatically selected (false) when a user creates a new list or performs an advanced search for a single record type. |
<data:SearchLayout> . . . <data:EnableDefaultSort>true </data:EnableDefaultSort> . . . </data:SearchLayout> |
About the SearchOptimization Element
The <SearchOptimization> element for a field in a search layout indicates whether the field is optimized for fast search and also whether the field can be made case insensitive by selecting the Case Insensitive check box in an advanced search or in the Refine List page for a list. The possible values are as follows:
A value of -1 indicates that the field is not optimized for fast search and is always case sensitive, regardless of the setting in the Case Insensitive check box in a search. The names of these fields appear in the default text color in the search layout wizard.
A value of 1 indicates that the field is optimized for fast search and is always case sensitive, even when the Case Insensitive check box is selected in a search. The names of these fields appear in green text in the search layout wizard.
A value of 2 indicates that the field is optimized for fast search and becomes case insensitive when the Case Insensitive check box is selected in a search. The names of these fields appear in blue text in the search layout wizard.
A value of 3 indicates that the field is not optimized for fast search and is always case insensitive, regardless of the setting in the Case Insensitive check box in a search. The names of these fields appear in purple text in the search layout wizard.
Migrating Search Layouts
The following topics describe how to use the Oracle Migration Tool On Demand client to migrate search layouts:
Extracting a Single Search Layout
This topic describes how to extract a single custom search layout from the Oracle CRM On Demand server for your environment; that is, a customer test environment or production environment.
The output from the Oracle Migration Tool On Demand client is saved in the following directory:
...\repository\SearchLayout\RecordType\SearchlayoutName.xml
Syntax
The following is the syntax for using the Oracle Migration Tool On Demand client to extract a single search layout:
migrationtool -u UserID -s ServerURL Read Searchlayout SystemNameOfObject SearchLayoutName
where:
UserID is the user sign-in ID that has the appropriate privileges to run the Oracle Migration Tool On Demand client commands.
ServerURL is the URL for the Oracle CRM On Demand server where your company resides.
SystemNameOfObject is the system name of the object (record type) for which you want to extract the search layout, for example, Account. The system names for the record types are listed in System Names for Record Types.
SearchLayoutName is the name of the search layout that you want to extract.
Example of Extracting a Single Search Layout
The following is an example of extracting a single search layout:
migrationtool -u UserID -s ServerURL Read SearchLayout Account "My Account Layout"
Extracting All Search Layouts for a Single Object
This topic describes how to extract all of the custom search layouts for a single object from the Oracle CRM On Demand server for your environment; that is, a customer test environment or production environment.
Syntax
The following is the syntax for using the Oracle Migration Tool On Demand client to extract the search layouts for a single object:
migrationtool -u UserID -s ServerURL Read SearchLayout SystemNameOfObject
where:
UserID is the user sign-in ID that has the appropriate privileges to run the Oracle Migration Tool On Demand client commands.
ServerURL is the URL for the Oracle CRM On Demand server where your company resides.
SystemNameOfObject is the system name of the object (record type) for which you want to extract the search layouts, for example, Account. The system names for the record types are listed in System Names for Record Types.
Example of Extracting All Search Layouts for a Single Object
The following is an example of extracting all search layouts for a single object:
migrationtool -u UserID -s ServerURL Read SearchLayout Account
Extracting All Search Layouts for All Objects
This topic describes how to extract all of the custom search layouts for all objects from the Oracle CRM On Demand server for your environment; that is, a customer test environment or production environment.
Syntax
The following is the syntax for using the Oracle Migration Tool On Demand client to extract the search layouts for all objects:
migrationtool -u UserID -s ServerURL ReadAll SearchLayout
where:
UserID is the user sign-in ID that has the appropriate privileges to run the Oracle Migration Tool On Demand client commands.
ServerURL is the URL for the Oracle CRM On Demand server where your company resides.
Updating or Inserting a Search Layout (Upsert)
This topic describes how to update a search layout (if it exists) or insert a search layout (if it does not exist) on your Oracle CRM On Demand environment (customer test environment or production).
About the Upsert Operation
The Upsert
command inserts or updates search layouts based on the user key: <LayoutName> and <ObjectName>.
Oracle CRM On Demand attempts to locate the search layout specified in the input file based on the user key. If a match is located, then the search layout is updated. If Oracle CRM On Demand cannot locate a search layout based on the user key, then a new search layout is created for the specified record type.
Syntax
The following is the syntax for using the Oracle Migration Tool On Demand client to insert or update a search layout for an object:
migrationtool -u UserID -s ServerURL Upsert SearchLayout SearchLayoutXML
where:
UserID is the user sign-in ID that has the appropriate privileges to run the Oracle Migration Tool On Demand client commands.
ServerURL is the URL for the Oracle CRM On Demand server where your company resides.
SearchLayoutXML is the fully qualified path name of the search layout XML file, for example:
C:\My Files\MyAccountSearchLayout.xml
If the fully qualified path name contains any spaces, then it must be enclosed with quotation marks, for example:
migrationtool -u UserID -s ServerURL Upsert SearchLayout "C:\My Files\My Account Search Layout.xml"
Example of Updating or Inserting a Search Layout
The following is an example of updating a search layout (if it exists) or inserting the search layout (if it does not exist) in your Oracle CRM On Demand server:
migrationtool -u UserID -s ServerURL Upsert SearchLayout "C:\Oracle Migration Tool On Demand\windows\repository\SearchLayout\MyAccountSearchLayout.xml"