Migrating Client Side Extensions

This chapter describes how to migrate client side extensions using the command-line interface of the Oracle Migration Tool On Demand client. It contains the following topics:

Client Side Extensions

Client side extensions are files that you can upload to and host on Oracle Migration Tool On Demand client instead of hosting them on other servers. The following table describes the Oracle Migration Tool On Demand client commands used with client side extensions. These commands are case sensitive.

Table Commands Used with Client Side Extensions in Oracle Migration Tool On Demand

Command Description

Command	Description
`Read ClientSideExtension ClientSideExtensionName`	This command exports a single client side extension. ClientSideExtensionName is the name of the client side extension.
`ReadAll ClientSideExtension`	This command exports all of the client side extensions in the Oracle CRM On Demand tenant.
`Upsert ClientSideExtension ClientSideExtensionXML`	This command updates or inserts the client side extension specified in the XML file. Oracle CRM On Demand supports the following file types for client side extensions: HTML JPG GIF SWF JavaScript CSS

Read ClientSideExtension ClientSideExtensionName

This command exports a single client side extension. ClientSideExtensionName is the name of the client side extension.

ReadAll ClientSideExtension

This command exports all of the client side extensions in the Oracle CRM On Demand tenant.

Upsert ClientSideExtension ClientSideExtensionXML

This command updates or inserts the client side extension specified in the XML file.

Oracle CRM On Demand supports the following file types for client side extensions:

HTML
JPG
GIF
SWF
JavaScript
CSS

Privileges Required for Migrating Client Side Extensions

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

For the Upsert command: Enable Web Services Access and Upload Client Side Extensions and Manage Custom HTML Head Tag.

Users can use the Read and ReadAll commands to extract client side extensions even if they do not have the Enable Web Services Access privilege.

Elements and Sections in the Client Side Extensions XML Output File

The following table describes the elements and sections in the client side extensions XML output file.

Table Elements and Sections in the Client Side Extensions XML File

Description	Element or Section
The <ClientSideExtension> section contains all of the information for a single client side extension.	<data:ClientSideExtension> . . . </data:ClientSideExtension>
<Name> is the name of the client side extension.	<data:ClientSideExtension> <data:Name>Corporate<data:Name> . . . </data:ClientSideExtension>
<UrlName> is a meaningful name for the URL that points to the client side extension. The following characters are accepted in the UrlName element: A-Z, a-z, 0-9, underscore (_), and period (.). Double periods (..) are not permitted, and a period (.) must not be the last character in the string. Examples of URL names are: Logo_Image and Map376. It is recommended that you keep this name as short as possible. Note: If you change the URL name on an existing client side extension, then the relative URL and full URL will be changed. If the client side extension has already been deployed, then you must update custom Web tabs, custom Web applets, global Web tabs, or custom HTML head additions that reference this client side extension to use the newly generated URL.	<data:ClientSideExtension> . . . <data:UrlName>Company_Logo</data:UrlName> . . . </data:ClientSideExtension>
<RelativeURL> is the relative URL that navigates to the client side extension from within Oracle CRM On Demand. The value in this element is generated by Oracle CRM On Demand, and the element is read-only.	<data:ClientSideExtension> . . . <data:RelativeURL>/user/content/Company_Logo</data:RelativeURL> . . . </data:ClientSideExtension>
<FullURL> is the full URL that points to the URL in the Oracle CRM On Demand application. The value in this element is generated by Oracle CRM On Demand, and the element is read-only.	<data:ClientSideExtension> . . . <data:FullURL>https://example.com/user/content/Company_Logo</data:FullURL> . . . </data:ClientSideExtension>
<Description> is the description of the client side extension.	<data:ClientSideExtension> . . . <data:Description>Company logo</data:Description> . . . </data:ClientSideExtension>
<FileName> is the name of the file, including the file extension.	<data:ClientSideExtension> . . . <data:FileName>logo.jpg</data:FileName> . . . </data:ClientSideExtension>
<MIMEType> is the Internet media (MIME) type of the file. The following are some examples of MIME types: text/html image/jpeg image/gif application/x-shockwave-flash text/css	<data:ClientSideExtension> . . . <data:MIMEType>image/jpeg</data:MIMEType> </data:ClientSideExtension>
<Extension> is the file extension of the file. The value in this element is generated by Oracle CRM On Demand, and the element is read-only.	<data:ClientSideExtension> . . . <data:Extension>.jpg</data:Extension> . . . </data:ClientSideExtension>
<FileSize> is the size of the file in bytes. The value in this element is generated by Oracle CRM On Demand, and the element is read-only.	<data:ClientSideExtension> . . . <data:FileSize>106590</data:FileSize> . . . </data:ClientSideExtension>
<FileData> contains the reference to the identifier (the Content-ID) for the attachment file. The Oracle Migration Tool On Demand client uses the Message Transmission Optimized Mechanism (MTOM) specification with the XML-binary Optimized Packaging (XOP) convention and the Multipurpose Internet Mail Extensions (MIME) standard to extract and return the client side extension configuration data and the file attached to the client side extension. Therefore, the content of the <FileData> element in the SOAP request is packaged as an MTOM/XOP request.	<data:ClientSideExtension> . . . <data:FileData><xop:Include xmlns:xop='http://www.w3.org/2004/08/xop/include'href='cid:Logo2021'/></data:FileData> </data:ClientSideExtension>

Migrating Client Side Extensions

The following topics describe how to use the Oracle Migration Tool On Demand client to migrate client side extensions:

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

Extracting a Single Client Side Extension

This topic describes how to extract a single client side extension from your Oracle CRM On Demand environment.

Syntax

The following is the syntax for using the Oracle Migration Tool On Demand client to extract a client side extension:

migrationtool -u UserID -s ServerURL Read ClientSideExtension ClientSideExtensionName

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.
ClientSideExtensionName is the name of a client side extension.

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 XML file is named with the name of the client side extension, and it is saved in the following directory:

...\repository\ClientSideExtension

A subdirectory with the same name as the client side extension is also created, and a metadata file and the attachment file are placed within the subdirectory.

Example of Extracting a Single Client Side Extension

The following is an example of extracting a client side extension named Company Logo:

migrationtool -u UserID -s ServerURL Read ClientSideExtension "Company Logo"

Note: If the name of the client side extension contains spaces or special characters, then it must be enclosed with quotation marks.

Extracting All Client Side Extensions

This topic describes how to extract all of the client side extensions from your Oracle CRM On Demand environment.

Syntax

The following is the syntax for using the Oracle Migration Tool On Demand client to extract all of the client side extensions:

migrationtool -u UserID -s ServerURL ReadAll ClientSideExtension

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 XML files are named with the names of the client side extensions, and they are saved in the following directory:

...\repository\ClientSideExtension

A subdirectory with the same name as the client side extension is also created for each client side extension. A metadata file and the attachment file for the client side extension are placed within the subdirectory.

Updating or Inserting a Client Side Extension

This topic describes how to update a client side extension (if it exists) or insert a client side extension (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 a client side extension based on the user key: Name.

Oracle CRM On Demand attempts to locate the client side extension specified in the input file based on the user key. If a match is located, then the client side extension is updated. If Oracle CRM On Demand cannot locate a client side extension based on the user key, then a new client side extension is created.

For an upsert operation, the attachment to be uploaded must be saved in a subdirectory of the directory where the client side extension XML file is saved, and the subdirectory must have the same name as the client side extension. The subdirectory must also contain a metadata text file that has the same name as the client side extension and is saved with the .metadata file extension. In the metadata file, the information for the file must be specified in the following format:

FileName: filename.fileextension
Content-Id: content-id
Content-Type: MIMEtype

where:

filename must match the value in the <FileName> element in the XML file that contains the configuration data for the client side extension.
fileextension must match the value in the <Extension> element in the XML file that contains the configuration data for the client side extension.
content-id must match the content-id value in the <FileData> element in the XML file that contains the configuration data for the client side extension.
MIMEtype must match the value in the <MIMEType> element in the XML file that contains the configuration data for the client side extension.

For example:

FileName: logo.jpg
Content-Id: Logo2021
Content-Type: image/jpeg

Note: When you extract client side extensions, the metadata file is generated automatically and is saved together with the attachment file in the subdirectory for the client side extension.

Syntax

The following is the syntax for using the Oracle Migration Tool On Demand client to insert or update a client side extension:

migrationtool -u UserID -s ServerURL Upsert ClientSideExtension ClientSideExtensionXML

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.
ClientSideExtensionXML is the fully qualified path name of the client side extension XML file, for example:
```
C:\My Files\logo.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 ClientSideExtension "C:\My Files\logo2021.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 Client Side Extension

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

migrationtool -u UserID -s ServerURL Upsert ClientSideExtension "C:\Oracle Migration Tool On Demand\windows\repository\Client Side Extension\logo2021.xml"

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