Migrating Search Layouts

This chapter describes how to migrate custom search layouts using 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

Command	Description
`Read SearchLayout SystemNameOfObject [SearchLayoutName]`	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: SystemNameOfObject is the system name of a record type. The system names for the record types are listed in System Names for Record Types. SearchLayoutName is the name of a search layout. This parameter is optional.
`ReadAll SearchLayout`	This command extracts all of the custom search layouts for all objects.
`Upsert SearchLayout SearchLayoutXML`	This command updates or inserts a custom search layout.

Read SearchLayout SystemNameOfObject [SearchLayoutName]

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:

SystemNameOfObject is the system name of a record type. The system names for the record types are listed in System Names for Record Types.
SearchLayoutName is the name of a search layout. This parameter is optional.

ReadAll SearchLayout

This command extracts all of the custom search layouts for all objects.

Upsert SearchLayout SearchLayoutXML

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 and ReadAll 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: <FieldName> contains the system name of the field, which never changes. <SearchOptimization> indicates whether the field is optimized for fast search and whether it can be case insensitive in a search. For more information about this element, see the About the SearchOptimization Element section of this topic. <Section> indicates which section of the search field layout the field appears in, as follows: A value of 0 indicates that the field is in the Not Available Search Fields section. A value of 1 indicates that the field is in the Targeted Search Fields section. A value of 2 indicates that the field is in the Additional Search Fields section. The <Order> element indicates the position of the field within the section of the search layout. In the Targeted Search Fields section and the Additional Search Fields section, the fields are numbered consecutively within the section. The first field in each section is numbered 0, the second field is numbered 1, and so on. All of the fields in the Not Available Search Fields section have their order number set to -1.	<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: <FieldName> is the name of the field. <SearchOptimization> indicates whether the field is optimized for fast search and whether it can be case insensitive in a search. For more information about this element, see the About the SearchOptimization Element section of this topic. <Section> indicates which section of the search results layout the field appears in, as follows: A value of 0 indicates that the field is in the Not Available Search Results Fields section. A value of 1 indicates that the field is in the Lookup Window Search Results Fields section. A value of 2 indicates that the field is in the Additional Search Results Fields section. <Order> indicates the position of the field within the list of fields. In the Lookup Window Search Results Fields section and the Additional Search Results Fields section, the fields are numbered consecutively within the section. The first field in each section is numbered 0, the second field is numbered 1, and so on. All of the fields in the Not Available Search Results Fields section have their order number set to -1.	<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: <FieldName> is the name of the field. <DefaultSearchValue> is the default value for the field. The condition for a default search value depends on the field type and you cannot specify a different condition for most of the field types. However, for fields of the Check Box type, the value you specify in the <DefaultSearchValue> corresponds to a condition and you can specify either Is Checked, which is the default condition, or Is Not Checked. <DefaultSearchValueAssocId> is the association ID (row ID) for a filter value for association control fields.	<data:SearchLayout> . . . <data:ListOfDefaultSearchValues> <data:DefaultSearchField> <data:FieldName>Indexed Boolean 0 </data:FieldName> <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: If this element is set to true, then a predefined set of fields is displayed in the search results in the Lookup windows for the record type. If this element is set to false, then the fields that are configured as the search fields for the Lookup window are also displayed in the search results in the Lookup window.	<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: If this element is set to true, then the fields that are configured as the search fields for the Lookup window are also displayed in the results of an enhanced keyword search. If this element is set to false, then a predefined set of fields is displayed in the results of an enhanced keyword search.	<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 extract is saved to a file and directory as follow:

migration tool install/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"

Note: If the object name contains spaces, then it must be enclosed with quotation marks. Similarly, if the search layout name contains spaces, then it must be enclosed with quotation marks.

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.

Note: The Oracle Migration Tool On Demand client requests your Oracle CRM On Demand password, which can be redirected (using the pipe command) to the client program from standard input; that is, from a file, from the command line, or from another program.

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

Note: If the object name contains spaces, then it must be enclosed with quotation marks.

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.

Note: The Oracle Migration Tool On Demand client requests your Oracle CRM On Demand password, which can be redirected (using the pipe command) to the client program from standard input; that is, from a file, from the command line, or from another program.

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

Note: The Oracle Migration Tool On Demand client requests your Oracle CRM On Demand password, which can be redirected (using the pipe command) to the client program from standard input; that is, from a file, from the command line, or from another program.

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\repository\SearchLayout\MyAccountSearchLayout.xml"

Note: Quotation marks are required only if the fully qualified path name contains spaces.