Migrating Custom Fields

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

Custom Fields

Fields refer to all items under the Field Management section in the Oracle CRM On Demand user interface. Each object has its own set of fields that are derived from the functionality of the objects.

The following table describes the Oracle Migration Tool On Demand client commands used with fields. For more information about running these commands, see Migrating Custom Fields.

Table Commands Used with Fields in the Oracle Migration Tool On Demand Client

Command	Description
`[-sortspec "fieldname[ sortorder][,fieldname[ sortorder]][,fieldname[ sortorder]]"] Read FieldManagement SystemNameOfObject`	This command exports all customized and custom fields for a specific record type. SystemNameOfObject is the system name of the record type. The system names for the record types are listed in System Names for Record Types. The optional `sortspec` parameter allows you to sort the output by one or more specified fields, and to specify the sort order (ascending or descending) for each sort field. You can specify up to three sort fields, in any order. The supported fields are: CreatedDate ModifiedDate Name The supported values for the sort order are: Asc or Ascending for sorting in ascending order. Desc or Descending for sorting in descending order. Note: The sort order values are not case-sensitive. If you do not specify a sort field, then the output is sorted by created date, in ascending order. If you specify a sort field but do not specify a sort order for the field, then the default sort order is ascending.
`[-sortspec "fieldname[ sortorder][,fieldname[ sortorder]][,fieldname[ sortorder]]"] ReadAll FieldManagement`	This command exports all customized and custom fields for all objects. For information about the optional `sortspec` parameter, see the description of the `Read` command.
`Upsert FieldManagement FieldManagementXML`	This command updates or inserts a set of fields in a particular object, as required.
`Create FieldManagement FieldManagementXML`	This command creates a new set of fields on a particular object from the contents of an XML file you create manually that contains the new field definitions, rather than extracting the definition from a company.

Note: If you are extracting field management from a source Oracle CRM On Demand environment, then regardless of whether the fields exist in the target Oracle CRM On Demand environment or not, use the Upsert command. If you are manually creating the field definitions and not extracting them from another source Oracle CRM On Demand environment, then use the Create command.

The Read and ReadAll commands extract only the field definitions for fields that have been created by a user or preconfigured fields that have been modified. Unmodified preconfigured fields are bypassed because they exist on all company tenants by default. An object with unmodified preconfigured fields or without any newly created fields contains an empty XML file.

The system names for the record types are listed in System Names for Record Types. You might not have certain objects available depending on how your company is set up, so some of the system names that are listed might not exist for your company.

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

Privileges Required for Migrating Custom Fields

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 and Create commands: 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 Field Management XML Output File

The following table describes the elements and sections in the field management XML output file.

Table Elements and Sections in the Field Management XML File

Description	Element or Section
<IncludeAll> specifies whether the preconfigured configuration information is returned in addition to the customized configuration information (true), or if only the customized configuration information is returned. The default setting is false.	<data:IncludeAll>true</data:IncludeAll>
When the <IncludeAll> element is set to true, the service fetches all controls for the object, including child controls. If the child control fetched is an address field and the address field is part of the default address template, then the <DefaultAddressField> element is set to true, otherwise it is set to false. This element can then be used as a marker to identify the best address field of the set.	<data:DefaultAddressField>true</data:DefaultAddressField>
<ObjectName> contains the system name of the record type (object), which never changes.	<data:ObjectName>Account</data:ObjectName>
The <ListOfFields> section contains all of the customized field definitions for the record type.	<data:ListOfFields> . . . </data:ListOfFields>
The <Field> section contains all of the elements for a single field.	<data:ListOfFields> <data:Field> . . . </data:Field> . . . </data:ListOfFields>
<Name> contains the system name of the field, which never changes.	<data:Field> <data:Name>TEXTSM_001</data:Name> . . . </data:Field>
<DisplayName> contains the name that is used in the user interface, if no translated display names are provided.	<data:Field> . . . <data:DisplayName>My Custom Field </data:DisplayName> . . . </data:Field>
<FieldType> specifies the type of field.	<data:Field> . . . <data:FieldType>Text (Short) </data:FieldType> . . . </data:Field>
<IntegrationTag> contains the custom integration tag name of the field. This tag can be modified by Oracle CRM On Demand users. The default integration tag is of the format: fieldtypeDisplay_Name For example, stMy_Custom_Field is assigned to a custom field of type Text (Short) with the Display Name value of: My Custom Field.	<data:Field> . . . <data:IntegrationTag>stMy_Custom_Field </data:IntegrationTag> . . . </data:Field>
<GenericIntegrationTag> contains the default integration tag assigned to the field by Oracle CRM On Demand. This element cannot be modified by Oracle CRM On Demand users. Note: For non-custom fields, the <GenericIntegrationTag> and the <IntegrationTag> values are the same.	<data:Field> . . . <data:GenericIntegrationTag>CustomText32 </data:GenericIntegrationTag> . . . </data:Field>
<Required> specifies whether the field is a required field (true), or is not a required field (false). If a condition is specified in the <RequiredCondition> element, then the <Required> element must be set to false.	<data:Field> . . . <data:Required>false</data:Required> . . . </data:Field>
<RequiredCondition> can contain an expression that specifies the criteria that make the field required. If an expression is specified, then the field becomes required when the condition specified in the expression is met. In the example shown here, the field becomes required when the Customer value is selected in the Account Type field. If the <Required> element is set to true, then the <RequiredCondition> element must not contain a value.	<data:Field> . . . <data:RequiredCondition> [{Type}]=LookupValue("ACCOUNT_TYPE","Customer") </data:RequiredCondition> . . . </data:Field>
<Optimized> specifies whether this is an optimized field (true) or is not an optimized field (false). Optimized fields are supported for certain record types only. For more information about optimized fields, see Oracle CRM On Demand Online Help.	<data:Field> . . . <data:Optimized>false</data:Optimized> . . . </data:Field>
<ReadOnly> determines if the field is a read-only field (true) or is not a read-only field (false).	<data:Field> . . . <data:ReadOnly>false</data:ReadOnly> . . . </data:Field>
<DefaultValue> contains the default value of the field, if one is defined.	<data:Field> . . . <data:DefaultValue></data:DefaultValue> . . . </data:Field>
<FieldValidation> contains the validation rules for the custom field, if any are defined.	<data:Field> . . . <data:FieldValidation></data:FieldValidation> . . . </data:Field>
<PostDefault> specifies whether the field is prepopulated with the default value when a new record is being created. If the <PostDefault> element is set to true, then the field is not prepopulated with the default value when the record is created, but if a value is not provided for the field before the record is saved, then the default value is assigned to the field when the record is saved.	<data:Field> . . . <data:PostDefault>false</data:PostDefault> . . . </data:Field>
<DenormalizedControl> corresponds to the Related Information check box in field management. For certain record types, you can create custom related information fields. For those record types, the following fields are available on the Field Edit page in the UI: Related Information, Related Record Type, and Related Field. These fields are used only for creating custom related information fields. Most of the other fields on the Field Edit page become read-only fields after you select the Related Information check box. For more information about custom related information fields, see Oracle CRM On Demand Online Help.	<data:Field> . . . <data:DenormalizedControl>false </data:DenormalizedControl> . . . </data:Field>
<DenormalizedAssociateControlName> corresponds to the Related Record Type picklist in field management.	<data:Field> . . . <data:DenormalizedAssociateControlName/> . . . </data:Field>
<DenormalizedControlName> corresponds to the Related Field picklist in field management.	<data:Field> . . . <data:DenormalizedControlName/> . . . </data:Field>
<ValidationErrorMsg> contains the error message that is displayed when a validation rule fails, if a message is defined.	<data:Field> . . . <data:ValidationErrorMsg></data:ValidationErrorMsg> . . . </data:Field>
<ToolTipText> contains the tooltip text that is displayed for the field in the Oracle CRM On Demand UI, if tooltip text is defined.	<data:Field> . . . <data:ToolTipText></data:ToolTipText> . . . </data:Field>
<Description> contains the description of the field.	<data:Field> . . . <data:Description></data:Description> . . . </data:Field>
<TooltipFormat> specifies the format of the tooltip text, which can be HTML or Plain Text.	<data:Field> . . . <data:TooltipFormat>HTML</data:TooltipFormat> . . . </data:Field>
The <ListOfFieldTranslations> section contains the translation values for the field.	<data:Field> . . . <data:ListOfFieldTranslations> . . . </data:ListOfFieldTranslations> . . . </data:Field>
The <FieldTranslation> section contains the translation values for one language. <LanguageCode> contains the three-letter code for a language. For the list of language codes, see Language Codes and Their Corresponding Language and Country. <DisplayName> contains the display name for the field in the language identified by the language code. <ValidationErrorMsg> contains the validation error message for the field in the language identified by the language code. <ToolTipText> contains the tooltip text for the field in the language identified by the language code. <Description> contains the description for the field in the language identified by the language code. The precedence for determining the display name is as follows: The translation definition, if it is defined. The information contained in the <DisplayName> element, if it is defined and if the translation definition is not defined. The system name, if the translation definition and the <DisplayName> element are not defined.	<data:Field> . . . <data:ListOfFieldTranslations> <data:FieldTranslation> <data:LanguageCode>ENU</data:LanguageCode> <data:DisplayName>Roles</data:DisplayName> <data:ValidationErrorMsg></data:ValidationErrorMsg> <data:ToolTipText></data:ToolTipText> <data:Description></data:Description> </data:FieldTranslation> . . . </data:ListOfFieldTranslations> . . . </data:Field>
<SharedPicklistFlag> corresponds to the Enable Shared Picklist Values check box in field management. On certain record types, you can create a custom picklist field that takes its list of values from another picklist field on the same record type or on a different record type. The field from which the values are taken is referred to as the source field, and the field that shares the values from the source field is referred to as the destination field. For these record types, the following fields are available on the Field Edit page in the UI: Enable Shared Picklist Values, Shared Record Type, and Shared Field. For more information, see Oracle CRM On Demand Online Help.	<data:Field> . . . <data:SharedPicklistFlag>true</data:SharedPpicklistFlag> . . . </data:Field>
<SharedPicklistObject> corresponds to the Shared Record Type picklist in field management.	<data:Field> . . . <data:SharedPicklistObject>Action </data:SharedPicklistObject> . . . </data:Field>
<SharedPicklistControl> corresponds to the Shared Field picklist in field management.	<data:Field> . . . <data:SharedPicklistControl>Region </data:SharedPicklistControl> </data:Field>

For more information about field management, see Oracle CRM On Demand Online Help.

Example of a Field Management XML File Containing a Web Link Field Type

This example displays a section of a Field Management XML containing a field of type Web Link.

The Field Management service includes Custom Web Links. When you run a Read or ReadAll command, the resulting XML file will include any customized fields of type Web Link. The Upsert also supports XML files that contain Web Link information.

<data:Field> 
  <data:Name>WEBLINK_002</data:Name>
  <data:DisplayName>My Custom Web Link</data:DisplayName>
  <data:FieldType>Web Link</data:FieldType>
  <data:IntegrationTag>My_Custom_Web_Link</data:IntegrationTag>
  <data:Required>false</data:Required>
  <data:ReadOnly>true</data:ReadOnly>
  <data:DefaultValue></data:DefaultValue>
  <data:ListOfFieldTranslations>
    <data:FieldTranslation>
      <data:LanguageCode>ENU</data:LanguageCode>
      <data:DisplayName>My Custom Link</data:DisplayName>
    </data:FieldTranslation>
  </data:ListOfFieldTranslations>
</data:Field>

For more information about custom Web links, see Migrating Custom Web Link Fields.

Migrating Custom Fields

The following topics provide examples of how to use the Oracle Migration Tool On Demand client to migrate field definitions:

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

Extracting Customized Field Definitions for a Single Object

This topic describes how to extract the set of customized field definitions for a single object from your Oracle CRM On Demand server for your environment (customer test environment or production).

Syntax

The following is the syntax for using the Oracle Migration Tool On Demand client to extract field definitions for a single object:

migrationtool -u UserID -s ServerURL Read FieldManagement 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) whose field definitions you want to extract, for example, Account Contact. 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 Customized Field Definitions for a Single Object

The following is an example of extracting the customized field definitions for the Account Contact object:

migrationtool -u UserID -s ServerURL Read FieldManagement "Account Contact"

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

The following is an example of extracting the customized field definitions for the Account object, sorted by the Name field, in ascending order:

migrationtool -u UserID -s ServerURL -sortspec "Name ASC" Read FieldManagement Account

Extracting Customized Field Definitions for All Objects

This topic describes how to extract all customized field definitions for all objects from your Oracle CRM On Demand environment (customer test environment or production).

Syntax

The following is the syntax for using the Oracle Migration Tool On Demand client to extract all customized field definitions:

migrationtool -u UserID -s ServerURL ReadAll FieldManagement

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 Customized Field Definitions for All Objects

The following is an example of extracting all customized field definitions for all objects from your Oracle CRM On Demand server:

migrationtool -u UserID -s ServerURL ReadAll FieldManagement

Updating or Inserting a Set of Field Definitions (Upsert)

This topic describes how to update a specific set of field definitions (if they exist) or insert those field definitions (if they do not exist) on your Oracle CRM On Demand environment (customer test environment or production).

Syntax

The following is the syntax for using the Oracle Migration Tool On Demand client to update a specific set of field definitions (if they exist), or insert those field definitions (if they do not exist):

migrationtool -u UserID -s ServerURL Upsert FieldManagement FieldManagementXML

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.
FieldManagementXML is the fully qualified path name of the field management XML file, for example:

C:\My Files\AccountContact.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 Set of Field Definitions

The following is an example of updating account contact field definitions (if they exist) or inserting the field definitions (if they do not exist) in your Oracle CRM On Demand server

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

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

Creating a New Field Definition

This topic describes how to create a new field definition for your Oracle CRM On Demand environment. (Typically, the Create operation is used to manually create brand new XML content rather than extracting the definition from a company.)

Note: System names (that is, the value between the <Name> tag) cannot be defined by a user, and it is a required field. A system name is a required field for an Upsert command. Any Field Management XML file extracted from a company tenant always has the system name defined. A net new field is a field that has not been extracted from another tenant but is defined in an XML file. To create a net new field, you must use the Create function. The Create function allows you to insert field definitions without having the system name defined.

The following is an example XML for using the Create method when you want to explicitly create a new field on the target:

<data:CustomField xmlns:data="urn:/crmondemand/xml/fieldmanagement/data">
  <data:ObjectName>Account</data:ObjectName>
  <data:DisplayName>My Customized Field</data:DisplayName>
  <data:CustomFieldType>Text (Long)</data:CustomFieldType>
  <data:IntegrationTag>My_Customized_Field</data:IntegrationTag>
  <data:Required>false</data:Required>
  <data:ReadOnly>false</data:ReadOnly>
  <data:DefaultValue/>
  <data:ListOfCustomFieldTranslations>
    <data:CustomFieldTranslation>
      <data:LanguageCode>ENU</data:LanguageCode>
      <data:DisplayName>My Customized Field</data:DisplayName>
    </data:CustomFieldTranslation>
</data:ListOfCustomFieldTranslations>
</data:CustomField>

Syntax

The following is the syntax for using the Oracle Migration Tool On Demand client to create a new field definition:

migrationtool -u UserID -s ServerURL Create FieldManagement FieldManagementXML

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.
FieldManagementXML is the fully qualified path name of the field management XML file, for example:
```
C:\My Files\MyAccountField.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 Creating a New Field Definition

The following is an example of creating a field definition for the Account object:

migrationtool -u UserID -s ServerURL Create FieldManagement "C:\My Files\MyAccountField.xml"

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