Getting Started with the JavaScript API

This chapter provides an overview of how to get started with using the JavaScript API in Oracle CRM On Demand. It contains the following topics:

Overview of Using Custom JavaScript Code

To use custom JavaScript code you must create appropriate custom HTML head additions so that the custom code is executed in the Oracle CRM On Demand pages. You add the custom HTML head additions in the Application Customization section in the Oracle CRM On Demand UI. For more information, see Managing HTML Head Additions.

Your custom HTML head additions can reference JavaScript libraries or external JavaScript files to make their functions available. You upload JavaScript libraries as client-side extensions in the Application Customization section in the Oracle CRM On Demand UI. For more information, see Uploading JavaScript Libraries.

Privileges Required

To upload JavaScript libraries and manage custom HTML head tags, your user role must include the privilege: Upload Client Side Extensions and Manage Custom HTML Head Tag. If you do not have this privilege, then the links for Client Side Extensions and Custom HTML Head Tag are not available on the Application Customization page in the Oracle CRM On Demand UI. Contact Oracle Customer Care if you do not have the privilege.

Uploading JavaScript Libraries

You can upload JavaScript library files as client-side extensions in Oracle CRM On Demand. These files can include custom functions and global variables, as well as other JavaScript libraries that you require.

To upload a JavaScript library

In the upper-right corner of any page, click the Admin global link.
In the Application Customization section, click Application Customization.
In the Application Setup section, click Client Side Extensions.
Click New.
Enter the following details:
- File. Click the paperclip icon to find the file that you want to upload.
- MIME Type. (Optional) This field indicates the Internet media type. If you provide a value, then enter the following:
```
text\javascript
```
  When you refer to the client side extension file from a custom HTML head addition, you use a <script> element as in the following example:
```
<script src="url to the client side extension" type="text/javascript"></script>
```
- Name. A name for the client side extension. This field is required.
- URL Name. A meaningful name used in the URL that points to the client side extension. It is recommended that you keep this field as short as possible. This field changes only when a user edits it. Therefore, if you replace the uploaded file, or if you change the client-side extension name, then the URL Name field value is unchanged. As a result, you can update, maintain and deploy multiple versions of the client-side extension without having to reconfigure the HTML head additions. This field is required.
Click Save.
After you click save, the Relative URL and Full URL fields are generated for the client-side extension and displayed in the Client Side Extension list.

For more information about managing client-side extensions, see Oracle CRM On Demand Online Help.

Guidelines for Uploading Client-Side Extensions

The guidelines for uploading client-side extensions are as follows:

Keep all client-side extensions in as few files as possible. This guideline improves performance. Preferably, refer to only one JavaScript file from custom HTML head additions.
Allow your browser to cache your client-side extensions. If you allow your browser to cache the client-side extensions, then the content does not have to be downloaded from the Oracle CRM On Demand servers each time that a user loads the page. If the client-side extension changes, then you must clear your cache so that Oracle CRM On Demand loads the page containing the extension. By default, client-side extensions are cached for 30 days.

Managing HTML Head Additions

When you add custom HTML head additions, you specify the appropriate code in <script> elements to be included in the HTML <head> element of your pages. The <script> elements can contain your custom JavaScript code and can also reference JavaScript files uploaded through client-side extensions or external JavaScript files. HTML head additions apply to all pages in Oracle CRM On Demand. There is a limit of 50,000 characters to the code that you enter as HTML head additions.

On the Edit Custom HTML Head Tag page, a Preview button enables you to validate any changes that you have made. Depending on your browser settings, errors might be displayed if badly formed HTML or JavaScript is added.

You can disable the custom HTML head additions by appending disableCustomJS=Y as a parameter to the URL for a page. If you navigate away from the page by clicking another link, then the URL parameter is not retained. You must specify the URL parameter each time that you require it. The parameter is used only when the current user’s role includes the Upload Client Side Extensions and Manage Custom HTML Head Tag privilege.

Note: Any custom code is the responsibility of the person or persons who created the code. Oracle Customer Care does not support custom code or the contents of linked-in code. When adding custom code, keep in mind that Oracle supports only calls to published APIs for different versions of Oracle CRM On Demand.

To add a custom HTML head addition

In the upper-right corner of any page, click the Admin global link.
In the Application Customization section, click Application Customization.
In the Application Setup section, click Custom HTML Head Tag.
In the Custom HTML Head Tags Detail page, click Edit.
In the HTML Head Additions text box, enter the <script> elements that you require.
The <script> element can contain JavaScript code or can reference JavaScript files through the src attribute. The following is an example of a reference to a file uploaded as a client side extension:
```
<script type="text/javascript" src="../user/content/Test.js"></script>
```
The following is a reference to an external file:
```
<script type="text/javascript" src="http://www.external.com/js/Test.js"></script>
```
Click Preview to validate any changes you have made.
Click Save.

For more information about managing HTML head additions, see Oracle CRM On Demand Online Help.

Guidelines for Managing HTML Head Additions

To minimize the time taken to load pages, reference JavaScript files, either as client-side extensions or external JavaScript files, to include your business logic. Using referenced JavaScript files also leverages the browser's cache to speed up the loading time for a page.

About Enabling and Disabling Customized Code in Oracle CRM On Demand

Administrators can enable and disable custom JavaScript code and other types of customized code for a user by setting the Customized Code Enablement field in a user's profile. Also, if the administrator adds the Customized Code Enablement field to the User Owner page layout for a user role, then users who have that role can disable and enable customized code for themselves by setting the Customized Code Enablement field in their personal profile.

Disabling all customized code can be helpful in troubleshooting technical issues you experience while working in Oracle CRM On Demand. If the issue no longer occurs when the customized code is disabled, then it is likely that the customized code is the cause of the issue.

The Customized Code Enablement picklist field determines whether all customized code on the pages in Oracle CRM On Demand is enabled or disabled for the user, and whether the customized code indicator is enabled or disabled for the user. The following options are available:

Enabled. This is the default setting in the standard application. When this option is selected, all of the customized code that is available in the pages in Oracle CRM On Demand is enabled, but the customized code indicator is not enabled.
Enabled with indicator. When this option is selected, all of the customized code that is available in the pages in Oracle CRM On Demand is enabled. In addition, the customized code indicator is enabled.
Disabled with indicator. When this option is selected, all of the customized code that is available in the pages in Oracle CRM On Demand is disabled. In addition, the customized code indicator is enabled.

When the customized code indicator is enabled, one of the following messages appears at the bottom of each page that you access in Oracle CRM On Demand:

Customized code active. Customized code is detected and is active in the current page.
Customized code not detected. No customized code is detected in the current page.
Customized code disabled. Customized code is detected in the current page, but the customized code is disabled.

When customized code is active in a page, the customized code is visible in the source code for the page, with comments to mark the start and end of the customized code. When the customized code is disabled, the customized code is not included in the source code for the page. Instead, the source code includes a comment to indicate that the customized code is disabled.

For more information about enabling and disabling customized code see Oracle CRM On Demand Online Help.

Security Considerations

Securing against Web browser-based attacks is a requirement when developing custom code and is the responsibility of the persons creating the custom code. Browser caches are only as secure as the computers or other devices that are browsing Oracle CRM On Demand.

The JavaScript API feature has been disabled for customer service representative (CSR) impersonation.