15Migrating Related Information Layouts

Migrating Related Information Layouts

This chapter describes how to migrate related information layouts using the Oracle Migration Tool On Demand client. It contains the following topics:

• Related Information Layouts

• Privileges Required for Migrating Related Information Layouts

• Elements and Sections in the Related Information Layout XML Output File

• Migrating Related Information Layouts

Related Information Layouts

A related information layout defines how related information sections appear in an Oracle CRM On Demand page layout. Typically, you create related information layouts when customizing Oracle CRM On Demand by using the Page Layout wizard. For more information, see the topics describing the customization of related item layouts and customization of static page layouts in Oracle CRM On Demand Online Help.

The following table describes the Oracle Migration Tool On Demand client commands used with related information layouts. For more information about running these commands, see Migrating Related Information Layouts.

Table Commands Used with Related Information Layouts in Oracle Migration Tool On Demand

Command	Description
Read RelatedInformationLayout SystemNameOfObject	This command exports a set of related information layouts from Oracle CRM On Demand. SystemNameOfObject is the system name of the record type. The system names for the record types are listed in System Names for Record Types.
ReadAll RelatedInformationLayout	This command exports all related information layouts in the Oracle CRM On Demand tenant.
Upsert RelatedInformationLayout MyRelatedInfoLayoutXML	This command updates or inserts a related information layout.

Note: Nonadministrative Oracle CRM On Demand users can run the Read and ReadAll commands.

Privileges Required for Migrating Related Information 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.

• 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 Related Information Layout XML Output File

The following table describes the elements and sections in the related information layout XML output file.

Table Elements and Sections in the Related Information Layout XML File

Description	Element or Section
<IncludeAll> specifies whether the preconfigured related information layouts are returned in addition to the customized layouts (true), or if only the customized layouts are returned. The default setting is false.	<data:IncludeAll>false</data:IncludeAll>
<CurrentUserOnly> specifies whether the output must contain only the related information layouts that are associated with the current user's role. If it is set to true, then only the layouts that are associated with the current user’s role are included. If it is set to false or null, then the output is not restricted to the layouts that are associated with the current user’s role. The default setting is false.	<data:CurrentUserOnly>false </data:CurrentUserOnly>
<ObjectName> contains the system name of the parent record type (object), which never changes.	<data:ObjectName>Account</data:ObjectName>
<RelatedInformationName> contains the child applet ID of the related information section. For information about child applet IDs and their mappings to the names of the related information sections as they appear in the UI, see Child Applet IDs and Their Corresponding Names.	<data:RelatedInformationName> OptyChildList </data:RelatedInformationName>
<Name> contains the name given to the related information layout.	<data:Name>Opportunities</data:Name>
<Description> contains the description of the layout.	<data:Description>Test Related Opportunities </data:Description>
For certain record types only, you can specify how the related records are sorted in the related information section when a user opens the parent record detail page, as follows: <SortField> corresponds to the Sort By field in the Page Layout wizard. It displays the name of the field that is used to sort the related records in the related information section when the parent record detail page opens. <SortDir> corresponds to the Sort Order field in the Page Layout wizard. It specifies the sort order for the records in the related information section. The <SortField> and <SortDir> elements are applicable for the Opportunities related record type only, and only for the following parent record types: Account Campaign Contact Custom Object 01 Custom Object 02 Custom Object 03 Dealer Objective Opportunity (the Sub-Opportunities related record type) Partner Program The valid values for the <SortField> element are: Primary Revenue Close Date. Corresponds to the Close Date field. Created. Corresponds to the Created: Date field. Name. Corresponds to the Opportunity Name field. Updated. Corresponds to the Modified: Date field. The valid values for the <SortDir> element are Ascending and Descending.	<data:RelatedInformationLayout> . . . <data:SortField>Name</data:SortField> <data:SortDir>Ascending</data:SortDir> . . . <data:RelatedInformationLayout>
The <ListOfSelectedField> section contains a <SelectedField> child section for each field that appears in the Selected Fields list in the related information layout.	<data:ListOfSelectedField> . . . </data:ListOfSelectedField>
The <SelectedField> section contains the details of one field in the Selected Fields list in the related information layout: <FieldName> contains the name of the field. <Sequence> specifies the sequence of the field in the Selected Fields list. The valid values are the integers 0 through 19.	<data:ListOfSelectedField> <data:SelectedField> <data:FieldName>Contact Full Name</data:FieldName> <data:Sequence>0</data:Sequence> </data:SelectedField> . . . </data:ListOfSelectedField>

Migrating Related Information Layouts

The following topics provide examples of how to use the Oracle Migration Tool On Demand client to migrate related information layouts:

• Extracting a Set of Related Information Layouts for a Single Object

• Extracting All Related Information Layouts for All Objects

• Updating or Inserting a Specific Related Information Layout (Upsert)

Note: Back up your configuration data and all other relevant data before running the Oracle Migration Tool On Demand client.

Extracting a Set of Related Information Layouts for a Single Object

This topic describes how to extract a set of related information layouts for a single object from the Oracle CRM On Demand server for your environment; that is, a customer test environment or production environment.

Note: Users require the Enable Web Services Access privilege to run the Read command.

Syntax

The following is the syntax for using the Oracle Migration Tool On Demand client to extract a set of related information layouts for a single object:

migrationtool -u UserID -s ServerURL Read RelatedInformationLayout 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 name of the object (record type) for which you want to read a set of related information 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 a Set of Related Information Layouts for a Single Object

The following is an example of extracting a set of related information layouts for the Account record type:

migrationtool -u UserID -s ServerURL Read RelatedInformationLayout Account

Extracting All Related Information Layouts for All Objects

This topic describes how to extract all related information layouts for all objects from your Oracle CRM On Demand 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 all related information layouts for all objects:

migrationtool -u UserID -s ServerURL ReadAll RelatedInformationLayout

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.

The output from the Oracle Migration Tool On Demand client is located at:

migration tool install/repository/RelatedInformationLayout/Object/RelatedInformationObject/LayoutName.xml

For example, when you extract related information list layouts for child account competitor lists, the output is located at the following location:

.../repository/RelatedInformationLayout/Account/AccountCompetitorChildList/My Custom Layout.xml

As another example, when you extract related information list layouts for child account partner lists, the output is located at the following location:

.../repository/RelatedInformationLayout/Account/AccountPartnerChildList/My Custom Layout.xml

Example of Extracting All Related Information Layouts for All Objects

The following is an example of extracting all related information layouts for all objects from your Oracle CRM On Demand server:

migrationtool -u UserID -s ServerURL ReadAll RelatedInformationLayout

Updating or Inserting a Specific Related Information Layout (Upsert)

This topic describes how to update a specific related information layout (if it exists) or to insert the related information layout (if it does not exist) in your Oracle CRM On Demand environment; that is, a customer test environment or production environment.

Note: The Enable Web Services Access and Customize Application privileges are required to run the Upsert operation.

The configuration data is updated when the System Layout Name exists in the target company for the specified object and related object. The following table lists the results of an Upsert operation in different situations.

Table Results of an Upsert Operation on a Related Information Layout XML File

If the XML file definition contains...	If the target company contains...	Then the result is...
Object: Account Related Object: Account Competitors Layout Name: My Custom Layout	Object: Account Related Object: Account Competitors Layout: Standard Related Information Layout	A new My Custom Layout is inserted
Object: Account Related Object: Account Competitors Layout Name: My Custom Layout	Object: Account Related Object: Account Competitors Layouts: Standard Related Information Layout My Custom Layout	My Custom Layout is updated.
Object: Account Related Object: Account Competitors Layout Name: Standard Related Information Layout	Object: Account Related Object: Account Competitors Layouts: Standard Related Information Layout My Custom Layout	An error is generated because Standard Related Information Layout cannot be updated.

The Upsert operation has the same limitations as the Oracle CRM On Demand user interface (UI), and it fails if the following conditions occur:

• The XML file contains a layout name that exceeds the length supported in the UI.

• The XML contains a description that exceeds the length supported in the UI.

• The XML content references fields that do not exist in the target environment.

Syntax

The following is the syntax for using the Oracle Migration Tool On Demand client to update a specific related information layout (if it exists) or insert the related information layout (if it does not exist):

migrationtool -u UserID -s ServerURL Upsert RelatedInformationLayout MyRelatedInfoLayoutXML

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.

• MyRelatedInfoLayoutXML is the fully qualified path name of the related information layout XML file, for example:

  C:\My Files\MyRelatedInfoLayout.xml
  

Note: The Oracle Migration Tool On Demand client requests your Oracle CRM On Demand password, which can be redirected (by 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 Related Information Layout

The following is an example of updating a related information layout (if it exists) or inserting the related information layout (if it does not exist) in your Oracle CRM On Demand server:

migrationtool -u UserID -s ServerURL Upsert RelatedInformationLayout "C:\My Files\MyRelatedInfoLayout.xml"

Note: Quotation marks are required only if the file name or path contains spaces.