Migrating Homepage Layouts

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

Homepage Layouts

A homepage layout for a record type provides the most relevant information to different users for that record type. Most homepage layouts display the tasks related to the types of records that correspond to that page, for example, account-related tasks for the Accounts homepage. Generally, they also display filtered lists that have been defined by your administrator, and an analytic chart relevant to your work. Homepage layouts can also contain Web widgets, RSS feeds, and other Web content, depending on what your company administrator has set up. From the homepage for a record type, you can drill down to other pages to manage the various types of information as required.

The following table describes the Oracle Migration Tool On Demand client commands used with homepage layouts. For more information about running these commands, see Extracting All Homepage Layouts.

Table Commands Used with Homepage Layouts in Oracle Migration Tool On Demand

Command	Description
`ReadAll HomepageLayout`	This command exports all homepage layouts for all objects.
`Upsert HomepageLayout HomepageLayoutXML`	This command updates or inserts a homepage layout, as required.

Privileges Required for Migrating Homepage Layouts

The following privileges are required for the user account running the Oracle Migration Tool On Demand client commands:

For Read and ReadAll commands: Enable Web Services Access and Customize Application.
For the Upsert command: Enable Web Services Access, Customize Application, and Customize Application - Manage Homepage Customizations. 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 Homepage Layout XML Output File

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

Table Elements and Sections in the Homepage Layout XML File

Description	Element or Section
<ObjectName> contains the system name of the record type (object), which never changes.	<data:ObjectName>Account</data:ObjectName>
<LayoutName> contains the name of the homepage layout.	<data:LayoutName>Account Default Layout </data:LayoutName>
<Description> contains a description of the homepage layout.	<data:Description>My Account Homepage Layout </data:Description>
The <ListOfAvailableSection> section contains the details of the sections that are included in the Available Sections list in the homepage layout.	<data:ListOfAvailableSection> . . . </data:ListOfAvailableSection>
The <AvailableSection> section contains the details of one section that is in the Available Sections list in the homepage layout: <SectionName> contains an internal applet name that is associated with the SectionLayoutName. Do not modify this element. <SectionLayoutName> contains the section layout name. Note: The section layout name is the name of a homepage section in the layout. This name is not the same as the display name of the section as it appears in the Homepage Layout wizard. For reference information about the mapping of section layout names to the corresponding UI names, see Homepage Section Layout Mapping.	<data:ListOfAvailableSection> <data:AvailableSection> <data:SectionName>AccountRecentlyApplet </data:SectionName> <data:SectionLayoutName> MyRecentlyModifiedAccounts </data:SectionLayoutName> </data:AvailableSection> . . . </data:ListOfAvailableSection>
The <ListOfSelectedSection> section contains the details of the sections that are included in the Left Side and Right Side lists in the homepage layout.	<data:ListOfSelectedSection> . . . </data:ListOfSelectedSection>
The <SelectedSection> section contains details of one section that is in either the Left Side list or the Right Side list in the homepage layout: <SectionName> contains an internal applet name that is associated with the SectionLayoutName. Do not modify this element. <SectionLayoutName> contains the section layout name. Note: The section layout name is the name of a homepage section in the layout. This name is not the same as the display name of the section as it appears in the Homepage Layout wizard. For reference information about the mapping of section layout names to the corresponding UI names, see Homepage Section Layout Mapping. <Sequence> determines the column in which the section is displayed: An even number, including 0 (zero), indicates that the section is in the Left Side list, where 0 (zero) is the first section. An odd number indicates that the section is in the Right Side list, where a value of 1 is the top (or first) section.	<data:ListOfSelectedSection> <data:SelectedSection> <data:SectionName>PdqList </data:SectionName> <data:SectionLayoutName> HomepageAccountList </data:SectionLayoutName> <data:Sequence>0</data:Sequence> </data:SelectedSection> . . . </data:ListOfSelectedSection>

For more information about the mapping of the section layout name to the corresponding UI section name for homepage layouts, see Homepage Section Layout Mapping.

About the PdqList Section Name

In the <ListOfSelectedSection> section in Elements and Sections in the Homepage Layout XML Output File, the section name, PdqList, is an applet name. The applet name specified in the corresponding object homepage XML file (for example, in AccountHomepage.xml or ContactHomepage.xml) is the same, but the layout name is different.

For example, for the Account homepage object, the applet name, layout name, and display name might be as follows:

Applet Name: PdqList
Layout Name: HomepageAccountList
Display Name: Account Lists

For example, for the Contact homepage object, the applet name, layout name, and display name might be as follows:

Applet Name: PdqList
Layout Name: HomepageContactList
Display Name: Contact Lists

Example of Sequence Values in the Section: ListOfSelectedSection

The following image represents the left and right side of the Accounts homepage UI. Exporting this homepage layout generates the <ListOfSelectedSection> section in the XML code displayed in the following code example. The sequence numbers for the left-side column and right-side column displayed in the following image are contained in the <Sequence> elements in the XML code.

Example XML Code for the Sequence Values in the <ListOfSelectedSection> Section

Example of Generated XML Code for the Sequence Values

The following example displays the generated XML code for sequence values:

<data:ListOfSelectedSection>
  <data:SelectedSection>
    <data:SectionName>AccountRelatedTasks</data:SectionName>
    <data:SectionLayoutName>AllOpenAccountTasks</data:SectionLayoutName>
    <data:Sequence>0</data:Sequence>
  </data:SelectedSection>
  <data:SelectedSection>
    <data:SectionName>AccountRecentlyApplet</data:SectionName>
    <data:SectionLayoutName>All Recently Modified Accounts</data:SectionLayoutName>
    <data:Sequence>1</data:Sequence>
  </data:SelectedSection>
  <data:SelectedSection>
    <data:SectionName>PdqList</data:SectionName>
    <data:SectionLayoutName>HomepageAccountList</data:SectionLayoutName>
    <data:Sequence>2</data:Sequence>
  </data:SelectedSection>
  <data:SelectedSection>
    <data:SectionName>HomePageListAnalyticsRevenue</data:SectionName>
    <data:SectionLayoutName>Account Analysis Report</data:SectionLayoutName>
    <data:Sequence>3</data:Sequence>
  </data:SelectedSection>
  <data:SelectedSection>
    <data:SectionName>AccountRecentlyApplet</data:SectionName>
    <data:SectionLayoutName>All Recently Created Accounts</data:SectionLayoutName>
    <data:Sequence>5</data:Sequence>
  </data:SelectedSection>
</data:ListOfSelectedSection>

Migrating Homepage Layouts

The following topics provide examples of how to use the Oracle Migration Tool On Demand client with homepage layouts:

Extracting All Homepage Layouts

The following topic describes how to extract all homepage layouts from your Oracle CRM On Demand environment (customer test environment or production).

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

Syntax

The following is the syntax for using the Oracle Migration Tool On Demand client to extract all homepage layouts:

migrationtool -u UserID -s ServerURL ReadAll HomepageLayout

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.

Example of Extracting All Homepage Layouts

The following is an example of extracting all homepage Layouts from your Oracle CRM On Demand server:

migrationtool -u UserID -s ServerURL ReadAll HomepageLayout

Updating or Inserting a Homepage Layout (Upsert)

This topic describes how to update a specific homepage layout (if it exists), or insert that homepage layout (if it does not exist) on your Oracle CRM On Demand environment (customer test environment or production). For the purposes of the Oracle Migration Tool On Demand client, this is known as an Upsert operation. It is specified using the Upsert command.

About the Upsert Operation

The Upsert command inserts or updates a homepage layout based on the <LayoutName> value. If a homepage layout already exists with the same <LayoutName> value, then the homepage layout is updated, otherwise, a new homepage layout is created. The matching of the homepage layout names is case sensitive.

The Enable Web Services Access and Customize Application privileges are required for an Upsert operation on a homepage layout.

Note: The homepage layout cannot reference section names that are not set up on the target system in an Upsert operation.

Sequence Tags

The <Sequence> tag in the homepage layout XML must contain all the sequence values for the layout.

For example, the following are acceptable sequence values for the Upsert operation:

0, 1, 2
0, 1, 3
0, 2, 4
0

1
1, 3
0, 1, 3

The following sequence values are not acceptable for an Upsert operation:

-1 is not acceptable because only positive integers are acceptable
0, 0, 1, 2 is not acceptable because duplicates must not exist
2 is not acceptable because the first left side value (that is, 0) is missing
3 is not acceptable, because the first right side value (that is, 1) is missing
1, 2 is not acceptable because the first left side value (that is, 0) is missing
0, 3 is not acceptable because the first right side value (that is, 1) is missing
0,1,2,5 is not acceptable, because the second right side value (that is, 3) is missing
0, 2, 3 is not acceptable, because the first right side value (that is, 1) is missing

Syntax

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

migrationtool -u UserID -s ServerURL Upsert HomepageLayout HomepageLayoutXML

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.
HomepageLayoutXML is the fully qualified path name of the homepage layout XML file, for example:
```
C:\My Files\My HomepageLayout.xml
```

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 Homepage Layout

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

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

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