5Customer Portal

Getting Started with the Customer Portal

Customer portal: Overview

The Oracle RightNow Customer Portal Cloud Service (Customer Portal) is your customer support interface.

Your customers can search for information, review the contents of your knowledge base, ask questions of your support staff and your user community, request a chat session, and manage their account information. Because the Customer Portal is integrated with your Oracle Service Cloud application, customers have access to your knowledge base and community discussions for immediate self-service. Likewise, any information they enter by submitting an incident, updating account information, or providing feedback on an answer is immediately available to your support staff on the Oracle Service Cloud administration interface.

You’ll configure your customer portal by editing the template, pages, and widgets that make up the customer interface. Additional configuration work occurs on the administration interface, so it’s important to have an understanding about Oracle Service Cloud and understand the structure of the Customer Portal and how to work with the code it uses.

Here are a few basic points to keep in mind as you begin working with your customer portal.

  • The reference implementation is the set of default pages and files that make up the Customer Portal as it exists before you configure and customize it for your specific needs. You’ll edit the default files so they meet your organization’s support goals and maintain the appearance of the rest of your organization’s website. After working with the default pages, you should understand the concepts well enough to create custom pages for your site.

  • You’ll use a text editor such as TextPad, NotePad, WordPad, or Adobe Dreamweaver to build and modify your customer portal pages. You’ll also need a WebDAV client for downloading and uploading files.
    Note:  We recommend using Cyberduck version 4.4. Other versions of Cyberduck may not work as expected, or with mixed results.
  • You use configuration settings on the Oracle Service Cloud administration interface to set up certain functionality for your customer portal, such as SmartAssistant and search options. But you’ll use the Customer Portal Administration site, your text editor, WebDAV, and widgets to configure the actual customer portal pages.

View your customer portal

You can view customer portal pages in the development area as you’re working on changes. You can also open the pages that your customers see on your production site.

When you open your customer portal, you might be looking at the development pages you’re working on but haven’t yet staged and promoted. Or you may be viewing the same production pages your customers see. The set of pages that opens depends on which area you’ve selected to view on the Customer Portal Administration site: production, staging, development, or the reference implementation.

Procedure

  1. Open your customer portal by doing one of the following:

    • Launch a web browser and type the URL for your site: https://<your_site>/app
    • From the file menu on the Service Console of your Oracle Service Cloud application, select Link > <your_site> > End-user

  2. To view development pages:

    1. Go to https://<your_site>/ci/admin.

    2. Select View Development Area on the dashboard.

WebDAV for customer portal

The customer portal uses WebDAV to help you manage your website files.

WebDAV offers a familiar file structure, easy uploading and downloading of multiple files, and file security through login access. After you set up a WebDAV connection to upload and download files, you can use any text editor you want to create and edit files for your customer portal, or you can use Adobe Dreamweaver, which uses its own WebDAV protocol for site management and configuration.

Note: If you use special characters in any PHP file, you must use a text editor that lets you save the file with UTF-8 encoding without the leading Byte Order Mark (BOM) character.

View Customer Portal files from a URL

Administrators can view customer portal files from the Customer Portal Administration site.

We recommend downloading files to your local workstation for editing and then uploading them back to the server.

Procedure

  1. In a web browser, type http://<your_site>/dav.

  2. Click the cp link to display the folders.

  3. Click the folder you want to display files for and continue drilling down through subfolders to display the file you want.

Customer Portal page sets: Overview

The Customer Portal contains sets of pages viewable from the Customer Portal Administration site.

Note: Best practice dictates removing any pages that your site does not use. The reference implementation contains pages that you might not use. Even if you do not use these features, the pages remain available on your customer portal and it is possible that your customers may stumble upon them.

The following page sets are included in your Customer Portal:

  • Development files—These are files you work with when you want to make changes to your customer portal. They cannot be seen by your customers. The page and template files are in the /cp/customer/development/views folder, and your custom widgets are in /cp/customer/development/widgets/custom.

  • Staging files—After editing your development pages, you can stage them, which means they are compiled and optimized to look and perform as they will on the production site. These files, located in /cp/generated/staging, are not editable, nor are they visible to your customers.

  • Production files—The production files, located in /cp/generated/production, have been promoted from the staging site and are visible to your customers.

  • Reference implementation files—These are the default, read-only files that make up the original customer portal reference implementation before you modify them. They are located in /cp/core/framework/views and /cp/core/widgets. You can revert to the original file by copying the original from its reference implementation folder and pasting it to the appropriate subfolder in /cp/customer/development.

Editing Customer Portal files: Overview

With the right permissions, users can edit customer portal files to customize their site.

You must enable MOD_CP_DEVELOPMENT_ENABLED before you can make changes to your development site, which means it must be enabled in order to make changes to the customer portal. If you do not enable this setting, your customer portal will use the out-of-the-box reference implementation, and it cannot be edited.

Whenever you follow a procedure in this guide for editing a file, the procedure is really just one part—step 2—of the following overview for all file-editing procedures.

Procedure

  1. Download the file to a local network location where you can access and open the file.

  2. Edit the file as described in the procedure and save it. We’re assuming that you’re working with the templates and pages in your development folder.

  3. Upload the file to the server.

  4. View and verify your changes on your development site.

  5. Stage the pages from the administration interface or the Customer Portal Administration site.

  6. Promote the staged pages into production.

Query string parameters

The Customer Portal does not use query string parameters within URLs.

When question marks are encountered in a URL, the content in the query string is ignored and the page is rendered as if the content is not in the URL. Product and category values in the search URL use sub-product and sub-category IDs.

For example, when product 130 is the parent of 138 and 138 is the parent of 131 (130 > 138 > 131), if all the products are visible by the end-user, the value is reduced to 131.

Although they are not used in the URLs, you can still access the values stored in the query string. The PHP superglobal $_GET array is populated with any query string key/value pairs that are found.

Customer Portal framework versions: Overview

The Customer Portal uses versions that apply a varying degree of change to the framework.

The Customer Portal version is independent of the Oracle Service Cloud release version, allowing you to upgrade to newer versions of Oracle Service Cloud while leaving your customer portal site untouched. This gives you control to migrate to a new Customer Portal framework when it’s convenient for your schedule. Each area of your customer portal can use a different version of framework.

The Customer Portal uses three levels of versions: major, minor, and nano. Each version level implies a varying degree of change to the framework. The version numbering scheme follows a pattern such as 3.1.4.

  • major—A major version change usually involves a fundamental change in a core component of the Customer Portal and will require work on your part to migrate from one version to the next. Major version changes are indicated by a change to the first digit of the version number (for example, the “3” in 3.1.4). You have complete freedom to decide whether you want to migrate to the new major version or remain on your current version.

  • minor—A minor change is not backward compatible. These changes may or may not affect you, depending on the area and extent of the change and how it impacts your customizations. You have the choice of opting in to the change rather than risking the possibility of breaking any of your custom code through an automatic update. Minor version changes are indicated by the second digit in the version number, for example, the “1” in 3.1.4.

  • nano—Nano changes are fully backward compatible. Theses changes will be applied automatically to your customer portal code with no impact to your site. Your site will always have the most current nano version of the framework being used by your customer portal, giving you the benefit of enhancements and bug fixes without having to do any work to consume them. Nano changes are indicated by the third digit of the version number, that is, the “4” in 3.1.4.

Note: Although widget versions are not tied to framework versions (there is not a specific set of widgets that must be used with a specific framework), widgets do have framework dependencies. So it’s possible that some of the widgets you used when your customer portal was on Framework Version 2 will not work with Framework Version 3.3. If any of your existing widgets are not compatible with the new framework version you are migrating to, you will see a warning message on the Customer Portal Administration site during the migration process.

Dependency checks are run when you select a version update to ensure that your Oracle Service Cloud application supports the selected customer portal framework. Dependency checks also let you know if any of your current widgets must be migrated in order to function on the newer framework.

Oracle Service Cloud elements and your customer portal: Overview

Your customer portal relies on Oracle Service Cloud elements to function.

The knowledge base is the term we use to describe how information in the database is presented. This is information staff members see on the agent desktop and customers see on your customer portal. Some of the information in the knowledge base includes the following.

  • Contacts—Each of your customers has a contact record in the knowledge base that includes basic information, such as name, email address, and phone number. Contact records also include information about any support issues or questions the customer has submitted as well as any other information your organization asks customers to provide.

  • Answers—Answers are the heart of your knowledge base. Whether your organization calls them FAQs, help topics, or something else, an answer is the information in the knowledge base that provides a solution to a common customer support question. Your customers can search for answers to their questions, and you can create new answers from questions your customers commonly submit.

  • Incidents—Incidents are created automatically when your customers submit a request for help through the Ask a Question page of your customer portal or when they provide feedback on your site or a specific answer.

  • Reports—A report is simply a list of records. The application offers a full range of standard reports, and you can also create custom reports. The list of answers that is returned when a customer conducts a search is simply a report that has been filtered on the search terms. Customer Portal reports are listed on the administration interface and can be accessed by clicking the Analytics button and then opening the Reports explorer to find Public Reports/Service/Views–Service/Customer Portal.

  • Configuration settings—You can accomplish most of the configuration of your customer portal by editing code for the templates, pages, and widgets that make up your site. There are, however, certain properties that are configured through the administration interface using configuration settings that define behavior on your customer portal.

  • Message bases—A message base is an editable text string that lets you customize headings, labels, buttons, and other text on your customer portal. When you reference a message base by its standard name in a line of code, the page automatically displays the text of the message base.

  • Data dictionary—The data dictionary lists the available database tables and fields that can be used for many input and output widgets. You can also use the Business Objects link on the Customer Portal Administration site (Framework > Business Objects) to look up field and table names for contacts, answers, and incidents.

Message bases in the customer portal: Overview

Many widgets and page headings use message bases, which are unique text strings that support internationalization.

You can identify message bases in Customer Portal code because they use an rn:msg#...# tag. The label between the # symbols points to the specific message base to be used. When you reference a message base in the code, the page automatically displays whatever text is associated with the message base. Message base labels appear in uppercase text with the words separated by an underscore character.

For example, the code that generates the label on the Support Home tab is #rn:msg:SUPPORT_HOME_TAB_HDG#. You can change the default label in one of three ways.

  • Change the value of the message base—Every place that calls or uses the message base will use the value you defined.

  • Reference a different message base—If another message base uses the language you want, reference that message base instead of the one that appears in the default code.

  • Type whatever message you want—If you want the change to appear only once and internationalization is not a concern, you can simply type whatever message you want into the page or widget code.

Example: Change the value of the SUPPORT_HOME_TAB_HDG message base

With the appropriate permissions, users can modify the value of a message base to change labels that appear in the customer portal.

Procedure

  1. Double-click Message Bases in Configuration > Site Configuration.

  2. In the Search window Key field, type SUPPORT_HOME_TAB_HDG.

  3. Click Search.

  4. Type the new label in the Text field.

  5. Click Save.

Example: Reference a different message base in customer portal

In your customer portal pages, you can reference different message bases to change page attributes.

Procedure

  1. Double-click Message Bases in Configuration > Site Configuration.

  2. Locate the message base you want to use as a replacement.

  3. Open /views/templates/standard.php.

  4. Locate the following line of code:

    <li><rn:widget path="navigation/NavigationTab" label_tab="#rn:msg:SUPPORT_HOME_TAB_HDG#" link="/app/#rn:config:CP_HOME_URL#" pages="home"/></li>

  5. Edit the code to reflect the name of the message base you want to use. Your code will resemble the following:

    <li><rn:widget path="navigation/NavigationTab" label_tab="#rn:msg:SUPPORT_HELP_HDG#" link="/app/#rn:config:CP_HOME_URL#" pages="home"/></li>

  6. Save standard.php.

Example: Use custom text instead of a message base

You can change the default message base label to a custom value within the customer portal pages.

Procedure

  1. Open /views/templates/standard.php.

  2. Locate the following line of code.

    <li><rn:widget path="navigation/NavigationTab" label_tab="#rn:msg:SUPPORT_HOME_TAB_HDG#" link="/app/#rn:config:CP_HOME_URL#" pages="home"/></li>

  3. Replace #rn:msg:SUPPORT_HOME_TAB_HDG# with whatever text you want to appear. Your code will resemble the following:

    <li><rn:widget path="navigation/NavigationTab" label_tab="Customer Care" link="/app/#rn:config:CP_HOME_URL#" pages="home"/></li>
    Note: If you’re typing an original message, you don’t need to use quotation marks or type #rn:msg: in the code.

  4. Save the file.

Customer Portal visit information

Many reports use visit information to help you define the success of your customer portal.

A visit is defined as the time a customer spends on your support site, beginning when a customer who does not already have an open visit navigates to a page on your site through a browser. A visit ends under any of the following circumstances.

  • The customer is inactive for a time longer than that specified by the VISIT_INACTIVITY_TIMEOUT configuration setting. The default value for the setting is 30 minutes.

  • The length of the customer’s visit has exceeded the time specified in VISIT_MAX_TIME. The default value for the setting is four hours.

  • The customer closes the browser.

  • The customer’s browser does not have cookies and the customer navigates away from your customer portal and then returns.

Note: Customer visits that result from clicking the PollingSyndication widget are tracked as Oracle RightNow Feedback Cloud Service visits, not as Customer Portal visits.

Passing visit information in custom customer portal pages

Visit information is automatically appended to cookies for all links on the standard pages and widgets.

Within all links on the standard pages and widgets, visit information from cookies is automatically appended. If cookies are disabled, a URL is used to pass visit and profile information through the application.

When you generate new links to custom pages, pass this visit information by adding #rn:session# at the end of each page URL. If you do not add the tag to a link and cookies are disabled, customers generate a new visit ID every time they click a link. Additionally, if the customer is logged in, they are logged out each time they click a link that does not pass the visit information. To prevent this from occurring, you must make changes to maintain the visit data in links.

Turn off cookie use for customer browsers

With the correct permissions, users can modify configuration settings to turn off cookies.

If you disable cookies, visit data is determined by URL parameters, which you must define in individual lines of code to prevent new visits from being initiated each time the customer navigates away from a page. Cookies are set by default.

Procedure

  1. Open Configuration Settings in Configuration > Site Configuration.

  2. Locate the CP_COOKIES_ENABLED key in RightNow User Interface/Customer Portal/Login.

  3. Set the Value field to No.

  4. Click Save.

Maintain customer portal visit data in JavaScript links

If a customer’s browser does not have cookies enabled and the customer clicks a link on a page, visit data can be lost. Use javascript pages, templates, and widgets to modify cookie header information in both the development and production pages.

Procedure

  1. Send the result of the $CI>session>setSessionData($data) function to the JavaScript and append it to the link.

  2. If you are using a widget, you can create a variable for the result.

    1. Create a variable.
      $data['js']['session'] = /RightNow/Utils/Url::sessionParameter()
    2. Reference the variable in the logic file.
      link + data.js.session

Maintain customer portal visit data in PHP links

If a customer’s browser does not have cookies enabled and the customer clicks a link on a page, visit data can be lost. Use php pages, templates, and widgets to modify cookie header information in both the development and production pages.

Procedure

  1. Add /RightNow/Utils/Url::sessionParameter() to the end of the link.

link .= /RightNow/Utils/Url::sessionParameter()

Accessibility in your customer portal

Several customer portal pages include a tag that is made visible to screen readers to meet accessibility requirements.

Several customer portal pages include an off-screen <h1> tag that is made visible to screen readers using the rn_ScreenReaderOnly CSS class. This tag provides accessible navigation using shortcut keys for customers who use screen readers to access your customer portal pages. The content is not visible to sighted users unless styles are disabled.

For information about creating content that is hidden to all users except screen readers, refer to the WebAIM article CSS in Action: Invisible Content Just for Screen Reader Users.

Customer portal widgets are designed to comply with Oracle’s Accessibility Program. When you create custom widgets, you are responsible for ensuring that your changes do not impact accessibility. Labels require particular attention. Input labels support accessibility by providing content for screen readers, and they should be used. However, if you choose to use an empty string for a label, some widgets will not include the asterisk that indicates the input field is required. even if you set the required attribute to true.

Customer portal file naming conventions

Customer portal files follow a standard naming convention.

File naming conventions

  • Use upper or lowercase alphanumeric characters and the underscore symbol.

  • Must begin with a letter or an underscore.

  • Paths are not case-sensitive. A mix of upper and lowercase characters is allowed but ignored.

Note: The native WebDAV client in an English version of Windows does not handle file names that contain multi-byte characters.

CSS and JavaScript files

To avoid naming conflicts with any custom files you create, these files are namespaced with an rn_ prefix.

Customer portal reports

You can find customer portal reports in the Reports explorer, often found in the Analytics navigation list.

Site reports

These reports are located in Public Reports/Service/Site Reports/Customer Portal:

  • Referring sites—provides a list of sites that referred customers to your customer portal and includes a percentage of customers referred from each site.

  • Visits by browser—shows the percentage of visits to your customer portal by browser type.

  • Visits by browser and operating system—a table of browser and operating system combinations and the percentage of visits by each combination.

  • Visits by operating system—the percentage of visits to your customer portal by operating system.

  • Visits by page set—customer portal page set mapping usage by percentage of sessions that accessed each page set.

  • Visits by time—the number of visits that occurred during each defined unit of time as well as a percentage of visits per time unit.

Community Self Service reports

These reports are located in Public Reports/Service/Community Self Service:

  • Activity reports

    • Aging discussions—a list of discussions that do not have comments or best answers.

    • Discussion comment details—a list of comments with their question and comment IDs, associated product or category, title, and date created. It also identifies comments marked as best answers as well as ratings and flags.

    • Discussion question details—a list of discussion questions with their IDs, associated product or category, title, date created, and author. It also includes number of comments, best answers, ratings, and flags.

    • Discussion responsiveness—a list of discussions sorted by the number of comments and response time.

  • Subscription reports

    • Community category subscriptions—a list of subscribers to community content for each category.

    • Community product subscriptions—a list of subscribers to community content for each product.

    • Community subscribers by question—a list of discussion questions and community members who are subscribed to each.

    • Community subscriptions by user—a list of individual users and the discussion content they are subscribed to.

    • Discussion question subscriptions—a list of community discussions, the product or category they are associated with, and the number of subscribers to each discussion.

  • Top reports

    • Top categories by comments—the categories that have the highest number of new comments.

    • Top categories by questions—the categories that have the highest number of new questions.

    • Top comments by rating—the comments with the highest ratings.

    • Top products by comments—the products that have the highest number of new comments.

    • Top products by questions—the products that have the highest number of new questions.

    • Top questions by rating—the questions with the highest ratings.

    • Top users by comments—users who have contributed the highest number of comments.

    • Top users by questions—users who have contributed the highest number of questions.

  • Users reports

    • Registration trend—the trend of new community user registrations.

    • User details—a list of community users that includes their display name, email address, full name, organization, date the account was created, their status, and the number of questions, comments, question and comment ratings, and best answers.

Two administration reports exist for Community Self Service. Both reports are available in Common/Site Administration/Community Self Service:

  • Discussion comments with no author

  • Discussion questions with an author

Customer portal folder structure

The Customer Portal incorporates an intuitive, easy-to-navigate file structure that lets you clearly identify the files you can edit.

The core folder

You cannot add or remove files in the core folder, nor can you edit any of the folder names or files.
  • assets—The core/assets folder contains all web assets used by the Customer Portal Administration site, organized in the following subfolder:

    • debug-js

    • default—contains the CSS, images, and themes for the pages, templates, and widgets in the reference implementation. You can use these files to view and revert to the reference implementation.

    • ejs

    • images

    • thirdParty

  • framework—This folder is the core of the Customer Portal code base and contains all view files for the standard pages, templates, and view partials. It also contains files and information about version changes, controllers, libraries, models, and utilities.

  • widgets—The widgets folder contains the files for all standard widgets, including controllers, views, CSS, images, logic, and YAML information files. You can use these files to view the code for the standard widgets.

The customer folder

The customer folder contains all the Customer Portal files you can modify. The customer folder is organized in the following subfolder structure:
  • assets—This folder contains the assets you can add, edit, and delete. Assets include all files for your customer portal that are not pages, templates, or widgets, including CSS, JavaScript, images, video, and other rich web media. You can add, remove, edit, and execute files and add subfolders to the assets folder.

    The folder is organizes in the following subfolders:
    • css

    • images

    • themes—only files not shared by the development and production files. These files are used strictly by the development files. When you stage the development pages, these files are copied to a time-stamped folder in the staging directory and called from that folder. The themes you develop are kept in this isolated sandbox that cannot be accessed by production files. The themes are applied to your production site only when you promote the staged files into production.

    • feedback

    • other—contains text files

    • default–contains default versions of the asset files provided in the reference implementation

    Note: Even if you don’t stage and promote your development pages, changes you make may affect the look and function of your production pages.
  • development—The development folder is your working folder. It contains all templates and pages to create and update your customer portal. The development folder contains the following subfolders:
    • config—Contains files to define model extensions, hooks that extend functionality, mappings to convert page names from previous frameworks to the current one, and search source model extensions.

      You can edit these files, but you cannot delete them.

      The file hook.php lets you define a PHP array of functions that is executed before and after the API calls of your choice.

      The file mapping.php redirects page requests and defines parameter mapping when you are migrating from Customer Portal Framework Version 1 (Classic or November 07 end-user interface).

    • controllers—Contains a customer controller file, AjaxCustom.php, which provides sample code that you can edit. You cannot delete or rename this file.

      You can create or add other controller files to the controllers folder.

    • errors—Contains two PHP scripts (error_general.php and error_php.php) used to display customized error pages. Besides customizing the appearance of these pages, you can also use information provided by the customer portal to provide more specific information to customer than the standard 404 error page. You can edit these files, but you cannot add any files to this folder.

    • helpers—Contains the sample_helper.php file and can be used for storing PHP utility function files.

    • javascript—Contains a single javascript file, autoload.js, which you can edit. You cannot delete or rename this file.

      In the reference implementation, the file contains no code. When you add content to it, it will automatically load on every page. This lets you make common changes without having to manually load them on individual pages.

    • libraries—Contains sample.php file and can be used for storing singleton PHP class files.

    • models—Contains three sample model files: /custom/extendedsample.php, /custom/mysocialsearch.php, and /custom/sample.php

    • views—Includes all display files that do not contain logic.
      • The admin pages are used to display answer previews on the Service Console.

      • The pages folder contains all customer portal pages.

      • The templates folder includes thestandard.php—used for the reference implementation pages—and the agent.php—for previewing a guide on the Oracle Service Cloud administration interface.

      • The partials folder contains custom view partials.

    • widgets—Contains a folder for custom widgets.

  • error—These pages can contain only the following pages:
    • splash.php—Displayed when your site is being upgraded.

    • error404.html—static HTML page displayed when an HTTP 404 Not found error code is returned.

    • error413.html—static HTML page displayed when an HTTP 413 Request entity too large error code is returned.

    • error500.html—static HTML page displayed when an HTTP 500 Internal server error code is returned.

The generated folder

The generated folder mirrors the structure of the development folder. You cannot add, edit, or delete the files in this folder. The folder is organized in the following subfolder structure:
  • production—Contains the staged files that have been promoted into production. These files are visible to your customers.
    • backup—Contains the original source code from the previous promoting activity.

  • staging—Contains the development files that you have staged through the Service Console or the Customer Portal Administration site. Your customers cannot see these files.
    • backup—Contains the original source code from the previous staging activity.

    • themes—Copied from your development site when you stage the development pages.

The logs folder

The logs folder contains logs for every stage, promote, and rollback operation performed on your site. It also contains a log of who changed Customer Portal files and when.

Configuring Oracle Service Cloud for the Customer Portal

Configuring Oracle Service Cloud for the customer portal

Administrators should do some basic configuration before working with pages and widgets.

Before you get started working with pages and widgets, you’ll want to do some basic configuration for the Oracle RightNow Customer Portal Cloud Service (Customer Portal) on the administration interface. You’ll need to assign appropriate permissions to staff members who will be working with your customer portal. You’ll also want to review the configuration settings to be sure you don’t need to change any of the defaults. Additionally, there are configuration options you’ll want to set up for features that are accessed through your customer portal, such as search options, SmartAssistant, and related answers. Finally, if you want to let your customers search for external documents in addition to the answers that are in your knowledge base when they search on your site, you can set up web indexing.

Assign permissions for your customer portal

Access to edit your customer portal is given through profile settings.

Procedure

  1. Log in to Oracle Service Cloud.

  2. Double-click Profiles under Configuration > Staff Management.

  3. Double-click the profile you want to assign permissions to.

  4. Click Permissions.

  5. Select the appropriate permission:

    • CP Edit—permission to edit customer portal pages using WebDAV, but not to stage or promote them. Staff members with this permission can also access the Customer Portal Administration site.
    • CP Stage—allows profile members to copy the development files to the staging area. The CP Edit check box is selected automatically.
    • CP Promote—allows profile members to promote customer portal pages from the staging area to the production area. This permission level automatically selects CP Stage and CP Edit.

  6. Click Save.

Locate and edit configuration settings

Administrators can edit configuration settings to define custom features and page functionality for your customer portal.

Procedure

  1. Double-click Configuration Settings in Configuration > Site Configuration.

  2. Type a configuration setting name in the Key field.

  3. Click Search.

  4. In the Value field for the Configuration Base (interface name), type or select the new value.

  5. Click Save.

The new value is underlined or it displays a small triangle in the upper left corner of the field to indicate a change from the default value.

Enable MOD_CP_DEVELOPMENT_ENABLED configuration setting

You must enable MOD_CP_DEVELOPMENT_ENABLED before you can make changes to your customer portal development site.

Procedure

  1. Double-click Configuration Settings in Configuration > Site Configuration.

  2. Type MOD_CP_DEVELOPMENT_ENABLED in the Key field.

  3. Click Search.

  4. Select Yes, in the Value field.

  5. Click Save.

Register Customer Portal open login with Facebook

Registering your open login provides you values for the configuration settings below. These configuration settings provide the application IDs and secret keys for requesting customer credentials for authentication. By default, all of these values are blank.

Procedure

  1. Go to the Facebook for Developers Add a New App page.

  2. Create a Facebook Login account, following the requirements until you see the ID and secret values.

  3. In Oracle Service Cloud, locate the FACEBOOK_OAUTH_APP_ID configuration setting.

  4. In the Value field, enter the App ID from the Facebook registration page.

  5. Locate the FACEBOOK_OAUTH_APP_SECRET configuration settings.

  6. In the Value field, enter the App secret key from the Facebook registration page.

  7. Click Save.

  8. On the Facebook page, enter your site’s valid domain in the App Domain field.

    Note: 

    If the domain is not valid, authentication will fail.

  9. Type your site’s URL in the Website With Facebook Login.

  10. Click Save Changes.

Register Customer Portal open login with Google

Registering your open login provides you values for the configuration settings below. These configuration settings provide the application IDs and secret keys for requesting customer credentials for authentication. By default, all of these values are blank.

Procedure

  1. Go to the Google Developers Console.

  2. Create a new application, following the Google requirements until you see the ID and secret values.

  3. In Oracle Service Cloud, locate the GOOGLE_OAUTH_APP_ID configuration setting.

  4. In the Value field, enter the App ID from the Google page.

  5. Locate the GOOGLE_OAUTH_APP_SECRET configuration setting.

  6. In the Value field, enter the App secret key from the Google page.

  7. Click Save.

Register Customer Portal open login with Twitter

Registering your open login provides you values for the configuration settings below. These configuration settings provide the application IDs and secret keys for requesting customer credentials for authentication. By default, all of these values are blank.

Procedure

  1. Go to the Twitter Create an Application page.

  2. Create a new application, following the Twitter requirements until you see the ID and secret values.

  3. In Oracle Service Cloud, locate the TWITTER_OAUTH_APP_ID configuration setting.

  4. In the Value field, enter the App ID from the Twitter Application details page.

  5. Locate the TWITTER_OAUTH_APP_SECRET configuration settings.

  6. In the Value field, enter the App secret key from the Twitter Application details page.

  7. Click Save.

Configuring the results pages

Configuration options include answer solved count, search results, search-field weighting, the aliases word list, search priority words, and stopwords.

By default, the results pages list the answers having the highest solved count and discussions that have best answers selected. The list, which is controlled by a report, includes the summary for each answer, the beginning of the answer text, and the date the answer was last updated. Customers can use the search field, including the Advanced Search option that lets them select products and categories, to find answers to their specific question. Clicking an answer in the list takes customers to the answer details page for that answer.

You can configure several aspects of searching for answers by using configuration settings.

Note: The search functionality of the Customer Portal has been set by default to the settings that have the broadest usefulness. You may not find it necessary to adjust any of the search options, although it will probably be helpful to customize your aliases word list, search priority words, and stopwords.

Configuring search results

Configuration options include setting answer filtering thresholds and limits on answers that are returned from a search.

There are several ways to configure how answers are returned in a search. One way is to specify a threshold, which is a filtering criteria for what answers are returned. A high threshold restricts returned answers to those that have a strong fit, while a low threshold allows more returned answers. You can also determine how match weights are configured to return only the best search results.

Additionally, you can truncate search results if too many matches are returned. The following factors affect the number of returned results.

  • Number of words in the query—If more words are used, fewer results are generally returned.

  • Number of words matched—For a search query containing four words, enough results may match three or four words, so answers that match only one or two words can be dropped.

  • Match weight distribution—If a significant drop occurs in match weight of the answers returned, the results can be truncated.

  • Type of search performed—For example, similar phrases searching and exact searching have different numbers of expected results.

Add and remove answer stopwords

Incidents and answers are analyzed for suggested stopwords. Administrators can modify the list of stopwords.

Procedure

  1. Open Answer Stopwords in Configuration > Service > Knowledge Base.

  2. Do one or more of the following:

    • Add words from the Suggested Additions list to the Active stopword list—Select the stopwords you want and click >>.
    • Add a stopword that is not in the Suggested Additions field—Type the word in the field at the top of the Active list on the right and click Add New.
    • Remove a stopword—Click the word in the Active list and click <<.

  3. Click Save.

Run the Agedatabase utility to activate your changes to the stopwords list.

Edit the aliases word list

You can use aliases (synonyms) to enhance searching. Adding aliases lets you link terms that are specific to your industry or organization to similar terms your customers may search for.

Procedure

  1. Double-click File Manager in Configuration > Site Configuration.

  2. In the Switch To drop-down menu, select wordlist files.

  3. Click Download.

  4. Click Save.

  5. Select a location for the file.

  6. Open the saved file.

  7. Enter each alias on a separate line using comma-delimited terms in uppercase text. The search terms in the line can contain spaces, so you can use phrases as synonyms for the search word. GPS,GLOBAL POSITIONING SYSTEM,NAVIGATIONAL SYSTEM

  8. Save the edited file.

  9. On the File Manager, click Browse.

  10. Locate the edited file.

  11. Click Open.

  12. Click Go.

  13. Click OK.

Configuring the answer details page

You can configure access for the answer details page, giving access to information based on a specific set of criteria.

When customers click the summary of an answer on the Support Home or a results page, the answer details page opens. From this page, your customers not only can view the answer, but they can also provide feedback on the answer and open any related and previously viewed answers. Additionally, they can share the answer on social networking sites, print it, email to another person, and request notification when the answer is updated.

Privileged access lets you give certain customers access to information that is not available to all customers. For example, you might want to give customers who have purchased a premium support contract access to a greater level of information.

An answer’s Access Level field controls who can view it, but all answers that you want to appear on your customer portal must have a Public answer status.

The following steps are required to configure privileged access.

  • Enable privileged access.

  • Add privileged answer access levels.

  • Add privileged answers.

  • Assign access levels to SLAs.

  • Assign SLAs to your customers.

Add a custom answer access level

Administrators can create custom answer access levels to restrict customer access to identified information.

Procedure

  1. Double-click Customizable Menus in Configuration > Application Appearance.

  2. Expand the System Menus folder.

  3. Click Answer Access Levels.

  4. Click New.

  5. Type the name of the answer access level in the Label field.

  6. If you do not want the answer access level to be visible on the interface, clear the Visible check box.

  7. Click Save.

After you create custom access levels, you must assign the access levels to SLAs and assign SLAs to your customers. By assigning an SLA to a group of customers (either organizations or contacts without an organization association), your customers can view privileged answers from your customer portal pages.

Allowing duplicate email addresses

The email address sharing feature allows the creation of individual accounts for multiple people who share one email address.

If you want to allow your customers to create multiple accounts using a single email address, you can enable email address sharing. This can be useful for multiple staff members (for example, support@example.com) or family members (hendersons@example.net).

Caution: Email sharing is disabled by default, and you should consider the implications carefully before you enable it. When email address sharing is disabled, safeguards prevent the creation of duplicate contacts to protect your organization’s reputation when sending mailings and surveys. Enabling email sharing removes these safeguards. Additionally, if you enable the feature and then later disable it, the application can develop conflicts in the database when duplicate email addresses are encountered.

If email address sharing is enabled and a customer creates an account using an email address that is already in the knowledge base, they see a message referring them to the Account Assistance page.

When the customer enters the email address on the Account Assistance page, a message is sent to the email address. It lists the known users of the email address and contains a link for creating a new account using the same email. Clicking the link takes the customer to the Finish Account Creation page, which asks for a user name and password. After submitting that information, the customer is directed to the Account Settings page, where additional contact information can be entered.

Enable email address sharing on your customer portal

Administrators can enable address sharing by modifying a configuration setting.

Procedure

  1. Open Email Adddress Sharing in Configuration > Database.

  2. Select Enabled.

  3. Click Save.

Define customer password requirements

You can set password requirements that can strengthen customer passwords entered on the Log In, Create an Account, and Change Password pages.

Procedure

  1. Double-click Contact Password Configuration inConfiguration.

  2. Edit the password requirements.

    The Contact Password Configuration table lists the password requirements you define on the administration interface appear to your customers on your customer portal when they are creating or changing their password.

    Table Contact Password Configuration

    Field Description
    Login Requirements Establishes a limit on invalid login attempts.
    Number of Invalid Logins The number of invalid login attempts a customer can make before the account is locked. If you don’t want to lock customer accounts, leave the value at its default of 0.
    Password Expiration Defines how and when passwords expire.
    Expiration Interval The number of days until the password expires.
    Grace Period The time period in days after password expiration during which customers can enter a new password and still log in.
    Warning Period The number of days prior to expiration that the customer is notified of the impending expiration. Customers can still log in during the warning period.
    Password Requirements Contains options for defining password requirements and limiting their frequency of use.
    Password Length The minimum number of characters a password must contain. The maximum is 20. If the customer exceeds the maximum number of characters, they will see a message on the customer portal informing them that their password is too long.
    Character Repetitions The maximum number of consecutive repeated characters the password can contain.
    Character Occurrences The maximum number of times a character can be repeated anywhere within the password.
    Lowercase Characters The minimum number of lowercase characters a password must contain.
    Uppercase Characters The minimum number of uppercase characters a password must contain.
    Special Characters

    The minimum number of special characters a password must contain. Special characters include !, @, ^, $, %, and spaces.

    Best practice recommends defining the Special Characters or the Numbers and Special Characters field, but not both.

    Numbers and Special Characters

    The minimum number of special characters, including numbers, a password must contain. Any combination of special characters and numbers will meet this requirement.

    If you are willing to let numbers count as special characters, set this field. If you do not want to let numbers count as special characters, use the Special Characters field instead of the Numbers and Special Characters field.

    Number of Previous Passwords The number of previous passwords that are stored so they cannot be reused for the new password.

  3. Click Save.

Using Sitemap

Search engines use web crawlers (spiders) to explore your website and index the pages that will be available when searches are conducted.

Search engines usually find the pages from links within your site and from other sites. But you may have pages that are not accessible by browsing on the interface (for example, pages that are accessed only when customers complete a form). The spider will not be able to index those pages because it cannot access them. Content in iFrames is not searched and indexed either.

Sitemap lets you inform search engines about all the pages that are available on your site, including those that are not accessible through links. Sitemap is an XML-based protocol used by the major search engines, including Yahoo! and Google. By using the Sitemap protocol, you can identify all the web pages on your customer portal instead of waiting for the search engine spiders to find them.

A Sitemap page is simply a document on a web server that lists all the URLs for a site along with metadata for each URL, including the priority of each page and when it was last updated. Spiders use the page to crawl your customer portal pages more intelligently rather than relying solely on links within the site.

By default, Sitemap is enabled and social discussion URLs are included in the Sitemap. A Sitemap page is created and registered with Yahoo and Google.

The output URLs for your customer portal sitemap are:
  • XML—https://<your_site>/ci/sitemap

  • HTML—https://<your_site>/ci/sitemap/html

Indexing web pages

Indexing lets your customers find indexed documents as well as answers when they search from your customer portal or from an external site using the KnowledgeSyndication widget.

You may want documents that are not part of your knowledge base, such as web pages, PDFs, and Microsoft Word documents, to be indexed.

Indexing and searching of external documents are possible if you store the documents on a web server so they are available through a URL. Typically, this limits files to those within the document root, CGI root, or FTP root directories.

In addition to using Sitemap to provide better spidering of your customer portal pages, Web Indexer can index sites that use a Sitemap page. Because the Web Indexer engine provides support for the Sitemap protocol, it can be pointed to a page that uses Sitemap to better index web pages outside of Oracle Service Cloud. When a Sitemap-formatted page is the starting point for the Web Indexer, all pages identified by the Sitemap page are indexed, not just those available through links. To have the Web Indexer index a site using Sitemap, simply use the Sitemap URL as the root URL in the Web Indexer wizard.

Web Indexer: Overview

When customers access Web Indexer documents by searching on your customer portal, an initial list of answers is displayed on the Answers page. The Web Indexer feature displays the answers in the same way as the standard answers search.

After you configure a root URL to be indexed and searchable, a web spider is used to follow the hyperlinks contained within the web page, indexing each consecutive page. If any of the consecutive web pages contain hyperlinks, those hyperlinks are followed and those web pages are indexed as well. By using filters, the web spider can be set up to follow only those hyperlinks that are within specified domains, but are not among the excluded domains, sub-domains, or URLs. Specified and excluded domains are configurable.

It is possible to have multiple URLs directed to the same document through URL masking and redirection, or the use of query parameters in a URL. During indexing, URLs are normalized to prevent a document from being indexed more than once. For example, the following two URLs can point to the same document in the same location on the web server:
  • http://WWW.EXAMPLE.org/pubs/docs1.txt

  • http://www3.example.org/pubs/docs1.txt?_user=321&_pass=@Qs!Xa

Both of these URLs would be normalized to: http://www.example.org/pubs/docs1.txt

This normalization allows the spider to index the document a single time, which saves drive space on the server, increases search performance, and prevents customers from getting the same document returned twice during a search.

You can also create SED (stream editor) statements that rewrite URLs to find and replace strings within the URL or remove portions of a URL before the URL is stored in the index. This function lets you automatically remove query parameters or further normalize URLs. (SED is a stream editor commonly used to find and replace or find and remove patterns in text strings.)

External documents are not re-indexed if they are edited. They will be re-indexed the next time the Keywordindexer utility runs. The keyword indexes for external documents are stored in a file on the web server rather than in a database table.

View external search logs

You can view a list of external searches on your site using the External Search log.

Procedure

  1. Open Logs in Configuration > Site Configuration.

  2. Click External Search Logs.

  3. Click Details for the log you want to view.

Configure the Web Indexer

External document searching is enabled through the Configuration Wizard which lets you set a variety of filters to help restrict the Web Indexer to the selected areas of your website.

Procedure

  1. Double-click External Search Configuration in Configuration > Service > Knowledge Base.

  2. Follow the prompts in the Configuration Wizard to configure the Web Indexer.

  3. Click Save.

Customer Portal configuration setting keys

Customer Portal configuration setting keys have a default value. Their location and description are listed here.

Configuration Setting Key Description Default Value
ANS_NEW_INC_DURATION

RightNow User Interface/End-User Interface/Answers/

Number of days that the solved count of new answers will not be aged (reduced). 30
ANS_NOTIF_DURATION

RightNow User Interface/Contact Services/Answer Notification/

The number of days that an answer update notification request by an end-user will last before being deleted. 0
ANS_PRV_ENABLED

RightNow User Interface/End-User Interface/Answers/

Enables the Privileged Access feature, which allows contacts and organizations to access privileged access levels of answers when searching the knowledge base. No
ANS_SRCH_SUB_THRESHOLD

RightNow User Interface/End-User Interface/Answers/

Specifies whether there should be an exception to limiting answer results with a threshold on matching. No
ANS_SRCH_THRESHOLD

RightNow User Interface/End-User Interface/Answers/

A threshold for returning answers. Only answers that match at or above this threshold are returned. 0
ANS_UPD_INC_DURATION

RightNow User Interface/End-User Interface/Answers/

Number of days that the solved count of updated answers will not be aged (reduced). 30
CP_404_URL

RightNow User Interface/Customer Portal/Pages/

The page that is loaded when customers navigate to a non-existent page where a 404 error occurs.  
CP_ACCOUNT_ASSIST_URL

RightNow User Interface/Customer Portal/Pages/

The page where customers retrieve their user name and password. utils/account_assistance
CP_ANS_NOTIF_UNSUB_URL

RightNow User Interface/Customer Portal/Pages/

The page where customers unsubscribe from an answer update notification. account/notif/unsubscribe
CP_ANSWERS_DETAIL_URL

RightNow User Interface/Customer Portal/Pages/

The page that displays answer details. answers/details
CP_CHANGE_PASSWORD_URL

RightNow User Interface/Customer Portal/Pages/

The page where customers can change their password. account/change_password
CP_CHAT_URL

RightNow User Interface/Customer Portal/Pages/

The page where customers can submit a request for a chat session. chat/chat_launch
CP_SOCIAL_QUESTIONS_DETAIL_URL

RightNow User Interface/Customer Portal/Pages/

The location and file for generating social questions URLs. social/questions/detail
CP_PUBLIC_PROFILE_URL

RightNow User Interface/Customer Portal/Pages/

The location and file for generating public profile URLs. public_profile
CP_PRODUCTS_DETAIL_URL

RightNow User Interface/Customer Portal/Pages/

The location and file for generating product detail URLs. products/detail
CP_REDIRECT_HOSTS

Common/General/Security

Defines which outside hosts are allowed when redirecting from Customer Portal pages.  
CP_CONTACT_LOGIN_REQUIRED

RightNow User Interface/Customer Portal/Login/

When enabled, requires contacts to be logged in when access most pages or controls.
Tip: If your answer pages or entire site are password-protected, you should enable this setting.
No
CP_COOKIES_ENABLED

RightNow User Interface/Customer Portal/Login/

Defines whether the Customer Portal tries to set cookies on a customer’s browser. Yes
CP_FORCE_PASSWORDS_OVER_HTTPS

RightNow User Interface/Customer Portal/Login/

This setting requires all logged in activity to occur over HTTPS to provide protection from password theft, phishing, and other security threats. Yes
CP_LOGIN_COOKIE_EXP

RightNow User Interface/Customer Portal/Login/

The number of minutes before the Customer Portal login cookie expires. 60
CP_HOME_URL

RightNow User Interface/Customer Portal/Pages/

The home page for your customer portal home
CP_INCIDENT_RESPONSE_URL

RightNow User Interface/Customer Portal/Pages/

The page that displays individual questions submitted by customers when they select one from a list of all their questions. account/questions/detail
CP_LOGIN_URL

RightNow User Interface/Customer Portal/Pages/

The page used to log in to your customer portal. utils/login_form
CP_MAX_LOGINS

RightNow User Interface/Customer Portal/Login/

The total number of customers that can be logged in to your Customer Portal site. 0
CP_MAX_LOGINS_PER_CONTACT

RightNow User Interface/Customer Portal/Login/

The total number of active, concurrent logins a contact can have. 0
CP_WEBSEARCH_DETAIL_URL

RightNow User Interface/Customer Portal/Pages/

The answer details page used to display results from the External Search page. answers/detail
EU_CUST_PASSWD_ENABLED

RightNow User Interface/General/End-User/

Enables the display of the Password field on the Customer Portal. Yes
EU_SLA_VISIBLE

RightNow User Interface/General/

Allows SLA information to be visible in email responses. No
MOD_CP_DEVELOPMENT_ENABLED

Common/Oracle Products/Modules/

Allows users to modify files through WebDAV, deploy changes, and reach the administrative pages. No
MYQ_ENABLED

RightNow User Interface/Contact Services/Questions/

Includes a link in end-user emails that allows end-users to link to the web page for their incident and update their incident from the Your Account Questions page. Yes
MYQ_VIEW_ORG_INCIDENTS

RightNow User Interfaxe/Contact Services/Questions/

Specifies which incidents a logged in user can view. 0
SA_AGE_FREQ

Agedatabase/Batch Processing/SmartAssistant/

The approximate number of days before an unused Answer solved count and link strengths reduce to zero. 200
SA_RESULTS_COUNT_RATIO

Common/Knowledge Base/SmartAssistant/

Specifies the ratio of results distribution by document types. 60A:40S
SA_SOLVED_WEIGH_PREF

Common/Knowledge Base/Answer Search/

The display preference of calculated solved counts. 2
SA_USE_SOCIAL_PROD_CAT_FILTER

Common/Knowledge Base/SmartAssistant/

Specifies the filter to be used in the SmartAssistant GetSmartSuggestion query. 0
SEARCH_RELEVANCE_FOCUS

RightNow User Interface/End-User Interface/Answers/

The degree of conceptual matching between the search query and results using the learned topics from within the knowledge base. 0
SRCH_ATTACH_WEIGHT

Common/Knowledge Base/Answer Search/

The value used in calculating the search score for words used in file attachments of answers. 4
SRCH_BODY_WEIGHT

Common/Knowledge Base/Answer Search/

The value used in calculating the search score for words used in the Answer field of answers and the thread entries of incidents. 4
SRCH_CAT_WEIGHT

Common/Knowledge Base/Answer Search/

The value used in calculating the search score for words used in the Category field of answers. 50
SRCH_DESC_WEIGHT

Common/Knowledge Base/Answer Search/

The value used in calculating the search score for words used in the Question field of answers. 30
SRCH_KEY_WEIGHT

Common/Knowledge Base/Answer Search/

The value used in calculating the search score for words used in the Keywords field of answers. 50
SRCH_PROD_WEIGHT

Common/Knowledge Base/Answer Search/

The value used in calculating the search score for words used in the Product field of answers. 50
SRCH_SUBJ_WEIGHT

Common/Knowledge Base/Answer Search/

The value used in calculating the search score for words used in the subject of both answers and incidents. 45
SSS_DISCUSSION_SITEMAP_ENABLE

RightNow Common/Social Self Service/Genera/

Enables community content, end-user questions and discussions, to be included in the interface’s Sitemap XML. Yes
VISIT_INACTIVITY_TIMEOUT

RightNow User Interface/General/Security/

The number of minutes a customer can be inactive on the Customer Portal without needing to log in again. 30
VISIT_MAX_TIME

RightNow User Interface/General/Security/

The maximum number of minutes a customer web visit can last before and new visit and new session ID are generated. 240
WIDGET_INSTALLATION_HOSTS

RightNow User Interface/Customer Portal/Syndicated Widgets/

The external hosts allowed to install syndicated widgets.  

Customer Portal Template and Page Set

Configuring the template

The reference implementation includes a standard template on which all the default pages of the standard Customer Portal are built. You have complete flexibility to customize these files for your organization’s needs and business practices.

The template for the reference implementation of the Customer Portal includes a set of widgets that are contained in the header and footer to control navigation, search, login, product or category selection, and page set selection functionality and the Oracle logo.

Caution: Any changes you make to configuration settings may affect the reference implementation pages. As a result, the behavior of the reference implementation may not correspond to the descriptions in this section if you have changed the default configuration settings.

The following widgets are not rendered on a page, but provide the following functionality.

  • BrowserSearchPlugin—This widget outputs a link to a browser search engine plug-in. The link is automatically detected by web browsers, and the widget tells the browser what information to send to the search engine so the site can be searched directly from the browser’s search bar.

  • ClickjackPrevention—This widget prevents pages from loading in an iFrame or frameset, which prevents your customers from clicking a concealed link.

  • CapabilityDetector—This widget detects capabilities of your customers’ browsers. When a customer with no or limited JavaScript capabilities tries to access a standard or mobile page, a link to the basic page set appears, advising them to switch to the basic format for a better experience. When a customer with JavaScript capabilities accesses the basic page set, a notice appears to encourage them to switch to the standard page set.

Preventing iFrame security issues

If you run your customer portal in an iFrame on your organization’s website, best practice recommends against using iFrames, so the reference implementation includes a removable widget that prevents your customer portal from being presented in an iFrame.

The use of iFrames can pose several issues. Search engine optimization (SEO) is problematic because content in iFrames is not indexed by web crawlers. As a result, search engines will not display your knowledge base content to customers who are searching for specific information. Security is also a concern in iFrames because clickjacking—that is, misleading your customers into clicking a concealed link—is possible.

An additional consideration against the use of iFrames is the inability to set cookies in Internet Explorer 11. Although your customers can unblock third-party cookies, requiring them to do so is not an optimal customer experience.

Change navigation tab labels

The standard.php template file for the reference implementation includes two navigation tabs: Support Home and Ask a Question. You can change the labels for these tabs and add new tabs.

Procedure

  1. Open /views/templates/standard.php.

  2. To change the Support Home tab label, locate this line of code, and type the new label name over the content between the quotation marks for the label_tab attribute.

    <li><rn:widget path="navigation/NavigationTab" label_tab="#rn:msg:SUPPORT_HOME_TAB_HDG#" link="/app/#rn:config:CP_HOME_URL#" pages="home"/></li>

  3. To change the Ask a Question tab label, locate this line of code, and type the new label name over the content between the quotation marks for the label_tab attribute.

    <li><rn:widget path="navigation/NavigationTab" label_tab="#rn:msg:ASK_QUESTION_HDG#" link="/app/ask" pages="ask, ask_confirm"/></li>

  4. To add a tab, complete these steps.

    1. Copy one of the navigation tab code lines and paste it where you want it to be displayed in the tab navigation. For example, to have it be the far right tab, paste it after the Ask a Question code.

    2. Edit the label_tab attribute to name the tab.

    3. Edit the link attribute to specify the page you want to open when the tab is clicked. Your code will resemble the following.

      <li><rn:widget path="navigation/NavigationTab" label_tab="Chat" link="/app/chat/chat_launch/></li>

  5. To add a drop-down menu to a navigation tab, add the subpages attribute to the NavigationTab widget you want to modify. The code in this example creates a new Answers tab with a sub-menu.

    <rn:widget path="navigation/NavigationTab" label_tab="#rn:msg:ANSWERS_HDG#" link="/app/answers/list" pages="answers/list, answers/detail" subpages="#rn:msg:ANSWERS_HDG# > /app/answers/list, WebSearch Indexing > /app/answers/web_list" />
    Note: If you do not get the results you expect, you may need to copy the NavigationTab widget’s CSS from cp/core/assets/default/themes/standard/widgetCss/NavigationTab.css and use it to replace the NavigationTab.css file in cp/customer/assets/default/themes/standard/widgetCss.

  6. Save the file.

Configure the SimpleSearch widget

The SimpleSearch widget is displayed conditionally. It does not appear on pages that already contain a search field, such as Support Home, any of the search results pages, and the public profile page.

Procedure

  1. Open one of the following files and locate the block of code:

    • /views/templates/standard.php
      <rn:condition hide_on_pages="home, public_profile, results, answers/list, social/questions/list">
          <div class="rn_SearchBar">
              <rn:widget path="search/SimpleSearch" icon_path="" report_page_url="/app/results"/>
          </div>
      </rn:condition>
    • /views/templates/mobile.php
      <rn:condition hide_on_pages="home, results, answers/list, social/questions/list, account/profile, utils/create_account, utils/account_assistance, utils/login_form">
          <div class="rn_SearchBar">
             <rn:widget path="search/SimpleSearch" report_page_url="/app/results"/>
          </div>
      </rn:condition>

  2. To display the SimpleSearch widget on every page, remove the opening condition statement and the closing condition lines.

  3. To remove the SimpleSearch widget from every page, remove the code you located.

  4. To change the widget’s labels, add the label attribute using the form label="New Label Name".

  5. To set the focus to the search field when a page opens, add the initial_focus attribute to the widget and set the value to true.

        <rn:widget path="search/SimpleSearch" icon_path="" report_page_url="/app/results" initial_focus="true"/>

  6. To open a page other than the default results page, which lists both published answers and community results, change the report_page_url to a different page.

        <rn:widget path="search/SimpleSearch" icon_path="" report_page_url="/app/social/questions/list"/>

  7. Save the file.

Configuring login functionality

Configuring the AccountDropdown widget allows your customers to access their user login and account information.

Customers who already have an account with your organization can log in to their account by clicking the Log In or Sign up button, which is generated with the AccountDropdown widget. The login window opens and customers who have an account can enter their user name and log in. They can also log in using the open login options available through social media accounts, such as Facebook, Twitter, Yahoo, and Google. Customers who do not have an account can click the Create an Account link to enter information and set up an account.

Note: Customers must have their browsers set to accept cookies or they will not be able to log in to the customer portal.

Configuring the AccountDropdown widget

When customers are logged in, the AccountDropdown widget displays various account and login options.

The AccountDropdown widget contains the following three widgets.

  • LogoutLink—Creates the Logout option on the drop-down menu.

  • UserInfoDialog—Opens the dialog that asks customers who have a user name but not a community display name to enter a display name.

  • LoginDialog—Opens the login window.

When a widget contains other widgets, you can use the attributes of the contained widgets in the widget definition. So, for example, although the AccountDropdown widget does not include a redirect_url attribute to indicate the page users should be redirected to when they log out, the LogoutLink widget does include that attribute. As a result, you can assign the attribute to the AccountDropdown widget too.

There are four instances of the AccountDropdown widget on the standard template page.

  • For users who are not logged in
    <rn:widget path="login/AccountDropdown" subpages="#rn:msg:ACCOUNT_OVERVIEW_LBL# > account/overview"
  • For logged-in users who do not have a community profile
    <rn:widget path="login/AccountDropdown" subpages="#rn:msg:ACCOUNT_OVERVIEW_LBL# > account/overview, #rn:msg:SUPPORT_HISTORY_LBL# > account/questions/list, #rn:msg:ACCOUNT_SETTINGS_LBL# > account/profile"/>
  • For logged-in users with a community profile
    <rn:widget path="login/AccountDropdown" subpages="#rn:msg:ACCOUNT_OVERVIEW_LBL# > account/overview, #rn:msg:SUPPORT_HISTORY_LBL# > account/questions/list, #rn:msg:ACCOUNT_SETTINGS_LBL# > account/profile, #rn:msg:PUBLIC_PROFILE_LBL# > #rn:config:CP_PUBLIC_PROFILE_URL#/user/#rn:profile:socialUserID#"/>
  • For logged-in users with a community profile who have moderator permissions
    <rn:widget path="login/AccountDropdown" subpages="#rn:msg:ACCOUNT_OVERVIEW_LBL# > account/overview, #rn:msg:SUPPORT_HISTORY_LBL# > account/questions/list, #rn:msg:ACCOUNT_SETTINGS_LBL# > account/profile, #rn:msg:PUBLIC_PROFILE_LBL# > #rn:config:CP_PUBLIC_PROFILE_URL#/user/#rn:profile:socialUserID#, #rn:msg:MODERATION_LBL# > social/moderate/overview"/>

Configure the Account Dropdown widget

Configure the Account Dropdown widget to modify what account details users can access.

Procedure

  1. Open one of the following files:

    • /views/templates/standard.php
    • /views/templates/mobile.php

  2. To change the widget’s labels, add the label attribute using the form label="New Label Name".

  3. To automatically open a request for a community user display name for users who do not have one, add the display_on_page_load attribute to the last instance of the AccountDropdown widget and set it to true.

  4. To set the focus to the search field when a page opens, add the initial_focus attribute to the widget and set the value to true.

        <rn:widget path="search/SimpleSearch" icon_path="" report_page_url="/app/results" initial_focus="true"/>

  5. To open a page other than the default results page, which lists both published answers and community results, change the report_page_url to a different page. The page path must begin with /app/. The following example opens a list of community results only.

        <rn:widget path="search/SimpleSearch" icon_path="" report_page_url="/app/social/questions/list"/>

  6. To remove the open login providers from the LoginDialog widget that opens when the Log In or Sign Up button is selected, add the open_login_providers attribute to the AccountDropdown menu and set it to a null value.

        <rn:widget path="login/AccountDropdown" subpages="#rn:msg:ACCOUNT_OVERVIEW_LBL# > account/overview" open_login_providers=""

  7. To display only a select number of open login providers, add the open_login_providers attribute to the AccountDropdown menu and specify the providers you want.

        <rn:widget path="login/AccountDropdown" subpages="#rn:msg:ACCOUNT_OVERVIEW_LBL# > account/overview" open_login_providers="facebook,google"

  8. To remove the password field, add the disable_password attribute to the AccountDropdown widget and set its value to true.

        <rn:widget path="login/AccountDropdown" subpages="#rn:msg:ACCOUNT_OVERVIEW_LBL# > account/overview" disable_password="true"

  9. Save the file.

Configure the footer

By customizing the code for the footer in the reference implementation template, you can add site navigation links, a copyright statement, contact information, and other elements you want to appear in the footer of every page that uses the template.

Procedure

  1. Open /views/templates/standard.php.

  2. To change any of the widget labels, refer to Editing widget labels.

  3. To display a list of categories instead of the default list of products, add the data_type attribute to the ProductCategoryList widget and set it to “categories,” and change the label_title attribute to “Categories.”

        <rn:widget path="search/ProductCategoryList" report_page_url="/app/products/detail" data_type="categories" label_title="Categories"/>

  4. To change the default number of products or categories that are displayed, add the maximum_top_levels attribute to the ProductCategoryList widget and set it to the number you want.

        <rn:widget path="search/ProductCategoryList" report_page_url="/app/products/detail" maximum_top_levels="10"/>

  5. To display a specific list of products or categories, add the only_display attribute to the ProductCategoryList widget and use the ID numbers, separated by commas, of the products or categories you want to list.

        <rn:widget path="search/ProductCategoryList" report_page_url="/app/products/detail" />

  6. To display an additional level of the product or category hierarchy, add the levels attribute to the ProductCategoryList widget and set it to 2.

        <rn:widget path="search/ProductCategoryList" report_page_url="/app/products/detail" levels="2"/>

  7. To add a copyright statement to the footer, add the following code immediately after the line for the OracleLogo widget.

        <p>&copy Copyright 2015 Global Wireless </p>

  8. Save the file.

Editing the page set from the template

You can configure the standard page set included in the reference implementation.

The standard page set contains a set of standard pages that lets your customers:

  • Search for information in your knowledge base and from your community.

  • View answers and community discussions.

  • Submit questions to your support staff and community.

  • Comment, rate, and flag community discussion content.

  • Update their contact and community profile information

  • Moderate community discussions and users (for those with moderation permissions).

Note: The reference implementation contains pages that you might not use, such as the mobile page set, basic page set, community pages, and chat pages. Even if you do not use these features, the pages remain available on your customer portal and it is possible that your customers may stumble upon them. Best practice dictates removing any pages that your site does not use.

Defining themes

A theme is a collection of files that change the appearance of your customer portal without impacting its functionality. Themes are created from CSS (cascading style sheet) files, which can affect typeface, color, and borders. Themes may also include graphics, JavaScript, flash animations, and other types of files.

All the reference implementation theme files are called from the /euf/assets/themes/standard folder. The /cp/customer/assets/themes/standard and /cp/customer/assets/themes/mobile also contain copies of the reference implementation theme files.

Note: The root /euf/ folder is correct even though you cannot see the /euf/ folder in your WebDAV file structure.

When you create custom themes, you must place them in the /cp/customer/assets/themes subfolder. If you try to stage development files containing theme paths that are not fully qualified with /cp/customer/assets/themes, you will see a warning in the deployment log.

Although all other files in the /cp/customer/assets/ folder are shared between the production and development sites, the files in the /themes/ subfolder of /cp/customer/assets/ are used strictly by the development files. When you stage the development pages, these files are copied to a time-stamped folder in the staging directory and called from that folder. This keeps the themes you develop in an isolated sandbox that cannot be accessed by production files. The themes are applied to your production site only when you promote the staged files into production. Any CSS files that are referenced by a theme but which are not located in the /themes/ folder will be copied into a special directory in the production copy of the theme when the staged files are promoted into production.

Read-only copies of the reference implementation asset files are available in the /cp/core/assets/default/themes/standard folder. By selecting Reference Implementation on the View Site menu at the upper right of the Customer Portal Administration site, you can see exactly how the customer portal appears using the default CSS files. You can also copy the files in this folder if you want to overwrite the changes you’ve made and restore the reference implementation CSS.

RN Theme tag

You can define multiple themes and write logic to select a theme at run time based on any combination of database variables, web visit variables, URL attributes, or other elements.

The RN Theme tag is used on a page or template to define what theme should be used. If a page that defines a theme uses a template that defines a different theme, the page theme takes precedence. Pages can specify more than one theme. If this is the case, the page uses the first theme unless the page code indicates otherwise.

Theme tags have two attributes: the location of the theme directory and one or more CSS files to be included on the page. The reference implementation template, standard.php, uses the default theme, site.css, located in the /euf/assets/themes/standard folder, as shown in this code.

<rn:theme path="/euf/assets/themes/standard" css="site.css"/>
Note: The root /euf/ folder specified in this code is correct even though you cannot see the /euf/ folder in your WebDAV file structure.

The reference implementation uses a single main CSS file to define basic layout, structural and style rules, fonts, borders, and colors. You can copy this file and modify it to create a variety of themes that can be applied to pages using the RN Theme tag, letting you change the appearance of the template or a page by changing only the theme that is applied to it.

Note: Rather than specifying a specific YUI version number, you can substitute the value {YUI} at the beginning of the file name to use the current YUI version, as shown in the preceding reference implementation template code.

Widgets have their own CSS files. The base CSS file for a widget controls its functionality, while the presentation for the widget is contained in its own file. This lets you control the appearance of a single widget without impacting any other widgets.

Create a theme

By copying the reference implementation css files, you can create your own theme.

Procedure

  1. Create a folder in /cp/customer/assets/themes.

  2. Copy the files in /cp/customer/assets/themes/standard and paste them into the folder you created in.

  3. Open site.css in your new custom subfolder.

  4. Make whatever edits you want to modify the CSS file.

  5. If you want to add images, place them in /cp/customer/assets/themes/[your_custom_folder]/images.

  6. If you want to modify widget presentation CSS to match the changes you made to the site.css, make your changes to the corresponding CSS file in /cp/customer/assets/themes/[your_custom_folder]/widgetCss.

Apply a theme to a page or template

You can apply your own theme to a page or template.

Procedure

  1. Open the page or template file you want to apply a custom theme to.

  2. Locate the following line of code.

        <rn:theme path="/euf/assets/themes/standard" css="site.css,

  3. Edit the path attribute for the RN Theme tag to specify the new theme. If you want to specify a different CSS file for the theme to use, change the css attribute as well. Your code will resemble the following.

        <rn:theme path="/euf/assets/themes/custom_01" css="site_01.css,

  4. Save the file.

Page meta tags

The Customer Portal offers page tags and page meta tags that let you control functionality through tags instead of writing PHP code. Page meta tags control page options, whether SLAs are required to view the page, and if customers need to be logged in to access the page. Page tags control specific sections of the page, with one particularly useful tag that lets you display or hide page content based on specific conditions.

The following page meta tags are available. To use them, add the attributes to the <rn:meta…> code for the page. The following is an example of a page that uses the standard template, includes a chat application, and displays an error message to customers who do not have a chat SLA.

<rn:meta title="Gold Service Chat Customers" template="standard.php" clickstream="chat_request" include_chat="true" sla_required_type="chat" sla_failed_page="/app/error/error_id/2" />

Table Page Meta Tag

Page Meta Tag/Attribute Name Description
Account Session ID Required/ account_session_required

Allows the page to be accessed only by logged-in staff accounts. This meta tag is used on the Guided Assistant page so guides can be previewed by staff members who are designing guides on the administration interface.

This tag can also be used to create a custom tab with a browser on an agent desktop workspace. When the browser points to a customer portal page, the page requires a valid ID to ensure that only logged-in staff members can access the page.

Answer Details/ answer_details Defines the page as an answer details page, displaying it only if customers have the required permissions.
Clickstream Tag/ clickstream Defines the type of page for clickstream and page statistics collection.
Force HTTPS/ force_https Forces the page to use HTTPS when CP_FORCE_PASSWORDS_OVER_HTTPS is enabled.
Include Chat/ include_chat Denotes whether the page contains a Chat application, which defines whether the page includes all required Chat JavaScript files.
JavaScript Module/ javascript_module Defines the JavaScript module that should be loaded on the page.
Login Required/ login_required Specifies whether customers must be logged in to view the page.
Page Title/title Defines the title that appears on the page.
Redirect If Logged In/ redirect_if_logged_in Specifies the page where customers will be redirected if they are already logged in.
SLA Failed Page/ sla_failed_page Indicates where customers are redirected if they do not have the kind of SLA specified in the SLA Required Type page meta tag.
SLA Required Type/ sla_required_type Defines the type of SLA a customer must have to view the page.
Social Moderator Required/ social_moderator_required Indicates a page that can be accessed only by a social user with discussion moderation permissions.
Social User Moderator Required/ social_user_moderator_required Indicates a page that can be accessed only by a social user with discussion moderation and social user moderation permissions.
Template/ template Identifies the template the page uses.

Require login on all customer portal pages

You can require your customers to log in before they can access any or all of your customer portal pages.

By setting the login_required attribute on the template to true, all pages that use the template will also require login. However, you don’t want to require customers to log in before they click the Log In or Sign Up link. To prevent requiring login when it doesn’t make sense, the default pages for logging in, resetting passwords, and creating accounts, as well as the error pages have the login_required page meta tag set to false, which overrides the template setting.

By default, the Account Overview page, accessed by clicking the Your Account tab, requires login, but you may also want to require customers to log in before they can view answers in your knowledge base. Or you may decide to require login for your entire customer portal page set.

Note: If you want to keep the answers in your knowledge base from being available to the general public, you must require login on both the answers list and answer details pages. If both pages do not have the same login requirement, a warning will appear when you stage and promote your customer portal. The most secure way to do this is to require login on all pages of your customer portal by requiring login on the template.

Procedure

  1. Open /views/templates/standard.php.

  2. Locate the <rn:page_content/> line and add the following line of code immediately above it.

        <rn:meta login_required="true"/>

  3. Save the file.

Require an SLA on the Ask a Question page

You can require that your customers have an SLA (service level agreement) before they can access any or all of your customer portal pages.

Procedure

  1. Open one of the following pages and locate the line of code:

    • /views/pages/ask.php
      <rn:meta title="#rn:msg:ASK_QUESTION_HDG#" template="standard.php" clickstream="incident_create"/>
    • /views/pages/mobile/ask.php
          <rn:meta title="#rn:msg:ASK_QUESTION_HDG#" template="mobile.php" clickstream="incident_create"/>

  2. Edit the code to change the login_required page meta tag to "true" and add the sla_required_type and sla_failed_page meta tags.

    login_required="true" sla_required_type="incident" sla_failed_page="/app/error/error_id/2" />

  3. Save the file.

Page tags

You’ll use page tags to position information on a page, output information from the database, define themes for a page, and hide or display page content conditionally.

Pound tags (#rn:) are also included in page tags and let you display or output language codes, message base labels, visit parameters, configuration setting values, session parameters, community tokens, URL parameters and parameter values, and widget attribute PHP code.

Note: When you use page tags, do not try to comment them out with HTML commands. Comments do not stop widgets from rendering and may cause rendering problems. They may also stop other tags from being converted. If you want to test a page without a page tag, remove it instead of commenting it out.

Positioning information on a page

There are custom tags you can use to position information on a page.

The following page tags let you position information on a page.

  • Page Title—Place this tag where you want the page’s title to be inserted when the page and template are merged. Use this format:

<title>
       <rn:page_title/>
</title>
  • Head Content—Place this tag between the opening and closing head tags where the page’s head content will be inserted. This content is a combination of widget CSS files, page CSS files, no-cache meta tags, and any other content added to the head by widgets (using the $this->addHeadContent function). When the page is rendered, global CSS is loaded first, followed by any other page/widget level CSS. As a result, the correct CSS hierarchy is preserved. Use this format:

<head>
       <rn:head_content/>
</head>
  • Page Content—Place this tag where you want the page’s content to be inserted when the page and template are merged. Use this format:

<div>
       <rn:page_content/>
</div>

Outputting database fields

When you want a page to display information from the database, you can use the Field page tag to output the value.

The Field tag has two attributes: Highlight for highlighting content that matches the keyword parameter in the URL and Name to identify the business object type and field to be displayed. Click Business Objects on the Customer Portal Administration site to find the names of the fields you can use and how to label them in the code.

For example, the answer details page, /views/pages/answer/detail.php, uses the following code to display information about the answer being viewed. (The Field tags are highlighted. They display the answer summary, the created and updated dates, and the answer description.)

<div class="rn_PageTitle rn_RecordDetail">
    <rn:widget path="navigation/ProductCategoryBreadcrumb"/>
    <h1 class="rn_Summary" itemprop="name"><rn:field name="Answer.Summary" highlight="true"/></h1>
    <div class="rn_RecordInfo rn_AnswerInfo">
        #rn:msg:PUBLISHED_LBL# <span itemprop="dateCreated"><rn:field name="Answer.CreatedTime" /></span>&nbsp;&nbsp;|&nbsp;&nbsp;&nbsp;#rn:msg:UPDATED_LBL# <span itemprop="dateModified"><rn:field name="Answer.UpdatedTime" /></span>
    </div>
    <rn:field name="Answer.Question" highlight="true"/>
</div>

Applying common attributes to multiple widgets

The RN Container page tag lets you create a set of widget attributes that can be referenced by multiple widgets.

You can use this tag in one of two ways. The first way is to use the container tags as a wrapper around a group of widgets. The tag defines the values for one or more widget attributes that all of the enclosed widgets share. Here’s an example of its use on the Answers page. Each one of the widgets that require a report use report ID 176 because they are all enclosed within the <rn:container report_id="176"> tags.

<rn:container report_id="176">
  <div class="rn_Hero">
    <div class="rn_HeroInner">
        <div class="rn_SearchControls">
            <h1 class="rn_ScreenReaderOnly">#rn:msg:SEARCH_CMD#</h1>
            <form onsubmit="return false;">
                <div class="rn_SearchInput">
                    <rn:widget path="search/KeywordText" label_text="#rn:msg:FIND_THE_ANSWER_TO_YOUR_QUESTION_CMD#" initial_focus="true"/>
                </div>
                <rn:widget path="search/SearchButton" force_page_flip="true"/>
            </form>
            <div class="rn_SearchFilters">
                <rn:widget path="search/ProductCategorySearchFilter"/>
                <rn:widget path="search/ProductCategorySearchFilter" filter_type="Category"/>
            </div>
        </div>
    </div>
  </div>
</rn:container>
<div class="rn_Container">
    <div class="rn_PageContent rn_KBAnswerList">
        <div class="rn_HeaderContainer">
            <h2>#rn:msg:PUBLISHED_ANSWERS_LBL#</h2>
            <rn:widget path="knowledgebase/RssIcon" />
        </div>
        <rn:condition flashdata_value_for="info">
            <div class="rn_MessageBox rn_InfoMessage">
                #rn:flashdata:info#
            </div>
        </rn:condition>
        <div>
            <rn:widget path="reports/ResultInfo"/>
            <rn:widget path="reports/Multiline"/>
            <rn:widget path="reports/Paginator"/>
        </div>
    </div>
    <aside class="rn_SideRail" role="complementary">
        <rn:widget path="utils/ContactUs"/>
    </aside>
</div>
</rn:container>

The second way you can use the RN Container tag is as a widget attribute that references the attribute-value definitions of the container. That is, you assign the container an ID value and then define attributes within the container. All widgets that reference the container ID then inherit the other attributes defined in the container.

For example, you could use this code to define the container.

<rn:container rn_container_id="1" report_id="196" per_page=2"/>

Although the value for the rn_container_id is an integer in this example, it does not have to be an integer. Instead, it can be any string except those that begin with rnc_ because that prefix is used by the Customer Portal.

When a container is defined this way, any widget on the page can then use the rn_container_id attribute as a shortcut for assigning all the attributes defined in the container to the widget that calls the container in its code.

For example, each of these widgets uses a report_id value of 196 and a per_page value of 2 because those are the values assigned to the attributes in the container definition:

<rn:widget path="reports/Multiline" label_text="" initial_focus="true" rn_container_id="1"/>
<rn:widget path="reports/Paginator" icon_path="images/icons/search.png" rn_container_id="1"/>
Note: If the widget code specifically defines an attribute that is defined in the container, the value for the attribute in the widget code overrides the value in the container.

Applying page conditions

Page condition tags allow you to hide or display content based on whether set conditions are met.

You may want to hide or display content on the template or on an individual page based on whether certain conditions apply. For example, you might want to hide the Ask a Question tab on the template until the customer has viewed a certain number of answers or conducted a certain number of searches. Or maybe you want to prevent part of a page from being displayed unless the customer is logged in or has an SLA (service level agreement).

Note: You should consider the usability issues of conditionally hiding and exposing page navigation before implementing page conditions. Particularly for customers using screen readers, the presence of a new navigation tab may not be evident when the conditions that trigger its appearance have occurred.

The code structure for the RN Condition page tags looks like this.

<rn:condition attribute="value">
     [Content is displayed when condition attribute is met]
</rn:condition>

The content between the condition tags is displayed only if the specified condition is met. Otherwise it is hidden. The following situations can control whether information is displayed or not.

The conditional page tag also includes an RN Condition Else tag to provide if/then logic for displaying or hiding content. Learn how to use the Else condition page tag.

Logged In condition

If the customer is logged in, the content within the condition tags is displayed on the page.

The template uses the Logged In page condition tag to display the Welcome Back message and customer’s name in the upper right corner of the page.

Note: Although you can use the Logged In page condition tag to show or hide the entire contents of a page, it might be more efficient to use the Login Required page meta tag instead.

External Login Used condition

When customers log in to your customer portal using pass-through authentication (PTA), the input fields on the Account Settings page are set to read-only by default.

If you want to let PTA customers change just one or two fields, you can add an attribute to the widget code for the individual input fields.

However, if you have a block of input fields that you want to let customers edit, you can enclose them in condition tags rather than editing each widget’s code separately. Use the following condition code before the first input widget in the block of input fields, and add the closing condition tag (</rn:condition>) after the last widget.

 <rn:condition external_login_used="true">

Hide on Pages/Show on Pages conditions

The Hide on Pages tag lets you specify the pages on which the content between the tags is hidden. The Show on Pages tag lets you specify the pages where the content appears.

The reference implementation template uses these tags to prevent the SimpleSearch widget from appearing on pages that already have a search field, namely the home page, search results pages, and the public profile page.

Answers Viewed, Questions Viewed, and Content Viewed conditions

You might want to use these tags to require your customers to first view existing answers and/or community discussions instead of automatically submitting a question to your support team.

The Answers Viewed tag lets you hide content until the customer has viewed the number of answers you specify. The Questions Viewed tag hides content until the specified number of community discussions has been viewed. The Content Viewed condition allows a value that adds the number of answers and questions viewed.

Searches Done condition

The Searches Done condition tag hides content until the customer meets the search requirements.

This page condition tag works the same way that the Answers Viewed tag does: It hides content until the customer has conducted the specified number of searches. If you want to use this for displaying the Ask a Question tab, however, it’s better to use the Searches Done attribute of the NavigationTab widget.

Note: The RN Condition tag identifies a search only when a page is turned or refreshed. For example, assume a customer conducts one search and reviews the list but does not click an answer or otherwise leave or refresh the answers list page. When the second search is made, the link you are hiding will not be displayed until another page is opened or the current page is refreshed.

Incident Reopen Deadline Hours condition

You can define content visibility based on incident closure.

This page condition tag lets you define how many hours after an incident is closed that the content within the tags remains visible. For example, the default question details page (the page that customers access by clicking one of their questions on the Support History page) hides the section of the page that lets the customer update the question after one week (168 hours). After that time has elapsed, the content is hidden and the Condition Else tag is used to display a message that the question can no longer be updated.

Hide Popular Published Answers for customers without an SLA

Use this page condition tag to hide content on the page unless the customer has the type of SLA specified on the page.

Procedure

  1. Open /views/pages/home.php.

  2. Find the following line of code.

    <div class="rn_PopularKB">

  3. Add the following code on a separate line immediately above the code you found in step 2.

    <rn:condition sla="incident" >

  4. Find the following line of code.

    <div class="rn_PopularSocial">

  5. Add the following code on a separate line immediately above the code you found in step 4.

    </rn:condition>

  6. Save the file.

Language In condition

You can display content based on the language defined in the page’s content-language meta tag.

The default Account Settings page on an English-language page displays the address fields in this order: Street, City, Country, State/Province, and Postal Code. On pages that use Japanese, Korean, and Chinese languages, the order is Postal Code, Country, State/Province, City, and Street. The use of this condition is demonstrated in this code from the profile.php page.

<rn:condition language_in="ja-JP,ko-KR,zh-CN,zh-HK,zh-TW">
    <rn:widget path="input/FormInput" name="Contact.Address.PostalCode" label_input="#rn:msg:POSTAL_CODE_LBL#" />
    <rn:widget path="input/FormInput" name="Contact.Address.Country" />
    <rn:widget path="input/FormInput" name="Contact.Address.StateOrProvince" label_input="#rn:msg:STATE_PROV_LBL#" />
    <rn:widget path="input/FormInput" name="Contact.Address.City" />
    <rn:widget path="input/FormInput" name="Contact.Address.Street" />
<rn:condition_else />
    <rn:widget path="input/FormInput" name="Contact.Address.Street" />
    <rn:widget path="input/FormInput" name="Contact.Address.City" />
    <rn:widget path="input/FormInput" name="Contact.Address.Country" />
    <rn:widget path="input/FormInput" name="Contact.Address.StateOrProvince" label_input="#rn:msg:STATE_PROV_LBL#" />
    <rn:widget path="input/FormInput" name="Contact.Address.PostalCode" label_input="#rn:msg:POSTAL_CODE_LBL#"/>
</rn:condition>

Config Setting Check condition

You may want to display content based on the value of a configuration setting that was defined on the administration interface.

The attribute for the Config Setting Check condition is more complex than most other conditions. The format is:

    {CONFIG_BASE:CONFIG_SLOT} {OPERATOR} {VALUE}

The elements of the attribute include the following.

  • CONFIG_BASE—One of the following configuration bases in Oracle Service Cloud. The CONFIG_BASE element is not case sensitive.
    • Common (which corresponds to the Common folder on the Configuration Settings editor)

  • RNW (RightNow Common folder)

  • RNW_UI (RightNow User Interface folder)

  • RNL (Chat folder)

  • MA (Outreach and Feedback)

  • CONFIG_SLOT—The name of the configuration setting as it appears in the Configuration Settings editor. These names are case sensitive.

  • OPERATOR—The logical operator. Acceptable values are == (equals), != (not equal), > (greater than), < (less than), >= (greater than or equal to), and <= (less than or equal to).

  • VALUE—The value to compare the parameter to. Values include true, false, null, an integer, or a quoted string.

For example, to set a condition that Chat is enabled, the attribute is the following.

<rn:condition config_check="MOD_CHAT_ENABLED == true">

URL Parameter Check condition

The URL Parameter Check condition lets you display or hide content based on the value of a parameter in the page URL.

The standard Ask a Question confirmation page uses this condition to retrieve the incident’s reference number.

The attribute for this condition is more complex than most other conditions. The format is:

{URL_KEY} {OPERATOR} {VALUE}

The elements of the attribute include the following.

  • URL_KEY—The parameter key to be checked in the URL. For example, to check the keyword URL parameter, type kw for this value.

  • OPERATOR—The logical operator. Acceptable values are == (equals), != (not equal), > (greater than), < (less than), >= (greater than or equal to), and <= (less than or equal to).

  • VALUE—The value to compare the parameter to. Values include true, false, null, an integer, or a quoted string.

For example, to set a condition if the keyword parameter is “roaming,” the attribute is the following.

"<rn:condition url_parameter_check="kw == 'roaming'">

Display alternate content when chat is unavailable

The conditional page tag also includes an Chat Available tag that can be used to determine whether the current time is within the chat operating hours and not currently a holiday.

Used primarily on the launch page for displaying the chat session request form, this tag could be used in conjunction with an Else condition tag to display alternate content during hours when chat is unavailable, as described in the following procedure.

Procedure

  1. Open /views/pages/chat/chat_launch.php.

  2. Locate the following code.

    </rn:condition>
    <rn:widget path="chat/ChatStatus"/>
    <rn:widget path="chat/ChatHours"/>

  3. Add the following code directly above the code you found in the previous step.

    <rn:condition_else/>
    [Content to be displayed when chat hours are not available]

  4. To remove the chat availability status text, delete the following line of code.

    <rn:widget path="chat/ChatStatus"/>

  5. Save the file.

Community user statuses

The community user statuses are used on other pages to control the content seen by discussion moderators and user moderators.

You may have content on your template or pages that you want to display to some community users but not others. For example, the AccountDropdown widget’s menu options are conditional. Customers who are not community members do not have the Public Profile option, while community users who are not moderators do not have the Moderation option. Four status conditions exist.

  • is_active_social_user—Community user with active status.

  • is_social_moderator—Content moderator.

  • is_social_user—Community user with archived or deleted status.

  • is_social_user_moderator—Content and user moderator.

Using the Else condition tag

The conditional page tag also includes an RN Condition Else tag to provide if/then logic for displaying or hiding content.

The RN Condition Else tag has no attributes and requires no closing tag. The code will follow this structure.

<rn:condition attribute="value">
[Content to be displayed if condition is met]
<rn:condition_else/>
[Other content to be displayed when condition is not met]
</rn:condition>

Standard page files

Each standard customer portal page has a title that appears in your browser when the page is displayed, and each page is also defined by its page name.

The following table lists each page file name and its corresponding page title and description.

Table Description of Page Files

Page File Name Page Title and Description
account/change_password Change Your Password page—Allows customers to change their password.
account/overview Account Overview page—Provides an overview of account information, where customers can view the questions they have submitted, the notifications they have subscribed to, and their service contracts. The Account Overview page also lets customers link to their account settings.
account/profile Account Settings page—Allows customers to change their user name and enter contact information.
account/profile_picture Update Your Profile Picture page—Lets community users update their profile picture with a default picture or the user’s Gravatar or Facebook profile picture.
account/reset_password Reset Your Password page—Contains a form where customers can reset their password. The page is accessed only through an email link sent to their primary email address when they request account assistance to reset their password. The link expires after a specified period of time (24 hours by default). If customers do not have a complete contact record, they are taken to the Profile page when they are finished on this page so they can finish setting up an account.
account/setup_password Finish Account Creation page—Displays a page with a link to the Account Assistance page. This page is displayed when customers click an email link to reset their password and the link has already expired or when a customer wants to create an account using an email address that is already in the knowledge base.
account/notif/list Notifications page—Displays all answers customers have subscribed to as well as product/category notifications they have subscribed to. The page allows customers to delete and renew notifications and add product/category notifications.
account/notif/unsubscribe Your Notification Requests: Unsubscribe Results page—Displays a message to customers who have clicked an email link to unsubscribe to an answer notification. This page can be accessed only through the email link.
account/questions/detail Question details page—Displays the details of a specific question submitted by a customer and allows the question to be updated. This page also contains a print button.
account/questions/list Support history page—Displays all questions submitted by a customer, including the subject, reference number, status, and date created. Selecting an incident in the list opens the details of the customer’s question.
agent/guided_assistant Guided assistant page—Displays a guide on the guided assistance designer of the administration interface as it will appear on the customer portal.
agent/polling_preview Polling preview page—Displays a preview of the polling widget to the staff member creating a survey to show how it will appear on the customer portal.
answers/detail Answer details page—Displays details about a specific answer and includes options for sharing, printing, emailing, and subscribing to the answer. The default page also lets customers submit answer feedback and view related and previously viewed answers.
answers/list Published Answers page—Displays a list of answers that meet the customer-entered search criteria. The page contains a search field with advanced search options.
ask Ask a Question page—Allows customers to submit a question.
ask_confirm Ask a Question confirmation page—Confirms the submittal of a customer’s question and displays the reference number of the incident that was created.
basic/ask Basic Email Us page—Lets customers submit a question using their basic device.
basic/ask_confirm Basic question confirmation page—Confirms the submittal of a customer’s question and displays the reference number of the incident that was created.
basic/error Basic error page—Displays one of several error messages, depending on the circumstances that caused the error. The error_id parameter is passed in the error page URL.
basic/error404 Basic error 404 page—Displays a Page Not Found error.
basic/home Basic home page—The entry point for customers using basic devices to access the customer portal. It includes the top popular answers and support categories.
basic/account/change_password Basic change password page—Lets customers change their password using a basic device.
basic/account/overview Basic account overview page—Provides an overview of account information, where customers can view the questions they have submitted. The account overview page also lets customers link to their account settings and the change password page.
basic/account/profile Basic account settings page—Lets customers change their account information using a basic device.
basic/account/reset_password Basic reset password page—Contains a form where customers can reset their password. The page is accessed only through an email link sent to their primary email address when they request account assistance to reset their password. The link expires after a specified period of time (24 hours by default). If customers do not have a complete contact record, they are taken to the account settings page when they are finished on this page so they can finish setting up an account.
basic/account/setup_password Basic finish account creation page—Displays a page with a link to the basic account assistance page. This page is displayed when customers click an email link to reset their password and the link has already expired or when a customer wants to create an account using an email address that is already in the knowledge base.
basic/account/questions/detail Basic question details page—Displays the details of a specific question submitted by a customer and allows the question to be updated using a basic device.
basic/account/questions/list Basic questions list page—Displays all questions submitted by a customer, including the subject, reference number, status, and date created. Selecting an incident in the list opens the details of the customer’s question.
basic/answers/detail Basic answer details page—Displays the details of an answer to customers using a basic device.
basic/answers/list Search results page—Includes a multiline report that has been optimized for basic devices and product and category search filters.
basic/answers/submit_feedback Submit feedback page—Lets customers submit feedback regarding specific answers on the basic page set.
basic/utils/account_assistance Basic account assistance page—Displays a page that lets customers using a basic device request an email containing either their user name or a link to a page for resetting their password. If the customer is logged in, the email address field is populated.
basic/utils/create_account Basic create account page—Displays a page that lets customers using a basic device create an account (which creates a contact record in the knowledge base) by entering their email address, user name, password, and first and last names.
basic/utils/login_form Basic login page—Displays the login page where customers using a basic device can enter their user name and password.
basic/utils/submit/password_changed Basic password change confirmation—Displays a message that a customer’s password change was successful.
chat/chat_landing Chat page—When a customer is waiting for an agent, this page displays position in queue and estimated and average wait times, along with a search field. When an agent is available, the Chat window opens.
chat/chat_launch Live Help page—Lets customers request customer support using Chat.
error404 Error 404 page—Displays a Page Not Found error.
error Error page—Displays one of several error messages, depending on the circumstances that caused the error. The error_id parameter is passed in the error page URL.
home Support Home page—Serves as customers’ main entry into the customer portal.
mobile/ask Mobile ask a question page—Lets customers submit a question using their mobile device.
mobile/ask_confirm Mobile ask question confirmation page—Confirms the submittal of a customer’s question and displays the reference number of the incident that was created.
mobile/error404 Mobile error 404 page—Displays a Page Not Found error.
mobile/error Mobile error page—Displays one of several error messages, depending on the circumstances that caused the error. The error_id parameter is passed in the error page URL.
mobile/home Mobile home page—The entry point for customers using mobile devices to access the customer portal. It includes the top six most popular answers and the top-level support categories.
mobile/account/change_password Mobile change password page—Lets customers change their password using a mobile device.
mobile/account/profile Mobile account settings page—Lets customers change their account information using a mobile device.
mobile/account/profile_picture Update profile picture page—Lets community users on a mobile device update their profile picture with a default picture or the user’s Gravatar or Facebook profile picture.
mobile/account/reset_password Mobile reset password page—Contains a form where customers can reset their password. The page is accessed only through an email link sent to their primary email address when they request account assistance to reset their password. The link expires after a specified period of time (24 hours by default). If customers do not have a complete contact record, they are taken to the mobile account settings page when they are finished on this page so they can finish setting up an account.
mobile/account/setup_password Mobile finish account creation page—Displays a page with a link to the mobile account assistance page. This page is displayed when customers click an email link to reset their password and the link has already expired or when a customer wants to create an account using an email address that is already in the knowledge base.
mobile/account/questions/detail Mobile question details page—Displays the details of a specific question submitted by a customer and allows the question to be updated using a mobile device.
mobile/account/questions/list Mobile support history page—Displays all questions submitted by a customer, including the subject, reference number, status, and date created. Selecting an incident in the list opens the details of the customer’s question.
mobile/answers/detail Mobile answer details page—Displays the details of an answer and allows customers to provide answer feedback using a mobile device.
mobile/answers/list Mobile answers list page—Includes a multiline report that has been optimized for mobile devices and product and category search filters.
mobile/chat/chat_landing Mobile chat page—Displays chat wait information and a transcript of the chat on a mobile device.
mobile/chat/chat_launch Mobile chat launch page—Lets customers request customer support using Chat on their mobile device.
mobile/products/detail Mobile product details page—Displays the list of popular published answers and recent community discussions related to the selected product or category on a mobile device.
mobile/social/ask Mobile community ask a question page—Displays a page that lets customers submit a question to the community while using a mobile device.
mobile/social/questions/detail Mobile community discussion detail page—Displays a single discussion, including question and comments, on a mobile device.
mobile/social/questions/list Mobile community results page—Displays a list of community discussions on a mobile device that match the entered search term.
mobile/utils/account_assistance Mobile account assistance page—Displays a page that lets customers using a mobile device request an email containing either their user name or a link to a page for resetting their password. If the customer is logged in, the email address field is populated.
mobile/utils/create_account Mobile create account page—Displays a page that lets customers using a mobile device create an account (which creates a contact record in the knowledge base) by entering their email address, user name, password, and first and last names.
mobile/utils/guided_assistant Mobile guided assistant page—Opens the page containing a guide that asks customers using a mobile device a series of questions designed to lead them to a solution specific to their situation.
mobile/utils/login_form Mobile login page—Displays the login page where customers using a mobile device can enter their user name and password or click a button to create an account.
mobile/utils/submit/password_changed Mobile password change confirmation—Displays a message that a customer’s password change was successful.
mobile/utils/submit/profile_updated Mobile profile update confirmation—Displays a message that the customer’s profile was successfully updated.
products/detail Products detail—Displays a list of published answers and community discussions related to a specific product.
public_profile Public profile page—Displays a list of a user’s recent community activity, including ratings, questions, and comments.
public_profile_update Update Public Profile page—Lets community users change their avatar (profile picture) and display name.
results Search results page—Displays the published answers and community discussions that match the entered search term.
social/ask Community ask a question page—Lets customers submit a question to the community.
social/moderate/comment Comment Moderation Dashboard page—Lets moderators moderate discussions comments from a report.
social/moderate/overview Moderation Overview page—Displays a summary page for moderators that displays recent question, comment, and user activity.
social/moderate/question Question Moderation Dashboard page—Lets moderators moderate discussion questions from a report.
social/moderate/user User Moderation Dashboard page—Lets moderators moderate community users from a report.
social/questions/detail Community discussion detail page—Displays a community question and all of its comments.
social/questions/list Results from the Community page—Displays community discussions that match the entered search terms.
utils/account_assistance Account Assistance page—Displays a page that lets customers request an email containing either their user name or a link to a page for resetting their password. If the customer is logged in, the email address field is populated.
utils/create_account Create an Account page—Displays a page that lets customers create an account (which creates a contact record in the knowledge base) by entering their email address, user name, password, and first and last names.
utils/editing_help Advanced Editing Help—Offers tips for editing content using plain text markdown.
utils/help_search General Search Tips page—Displays a page of search tips to help customers understand the best way to conduct a search. You can create a link to this page if you think your customers will find it helpful.
utils/login_form Log In page—Displays the Log In page where customers can enter their user name and password or click a button to create an account.
utils/submit/password_changed Password Change Succeeded page—Displays a message that a customer’s password change was successful.
utils/submit/profile_updated Profile Update Succeeded page—Displays a message that the customer’s profile was successfully updated.

Error codes and messages

Depending on the parameter passed in the error page URL, various error messages are displayed to the customer.

The following table lists the error codes and their corresponding messages.

Table Error Codes and Messages

Error Code Error Heading and Message
1 Not available—This answer is no longer available.
2 Not available—We’re sorry. Your account doesn’t have the service level agreement required to view this document.
3 File Download Error—Sorry, there was an error downloading the file.
4 Permission Denied—You do not have permission to access this document.
5 Operation Failed—Submission Failed. The page could not be submitted and the operation timed out. Use the Back button to return to the page. Then refresh the page so that you can resubmit the information.
6 Permission Denied—An illegal parameter was received.
7 Cookies are required—You’ll need to enable cookies in your browser before you can continue.
8 Not available—There is nothing here for you, sorry!
9 Not available—This discussion is no longer available.
sso9 Incomplete Account Data—Sorry, to create an account within the community, you must specify an email address. Please update your account.
sso10 Incomplete Account Data—Sorry, to create an account within the community, you must specify a first and last name. Please update your account.
sso11 Duplicate Email—Sorry, the email address you specified already exists within the community. You might already have an account with that email address. Please visit the account assistance page for further help.
sso13

Authentication Failed—The link you clicked contained an authentication parameter that failed to authenticate. This might have happened because:

  1. The link was intended for you, but has expired.

  2. This authentication parameter has already been used by you.

  3. The link you clicked was not intended for you, but was meant for another user and was given to you erroneously.

sso14
sso15
sso16
sso17
404 Not found—Page not found.

Error 404 page

The CP_404_URL configuration setting has a default value of error404, which is the page that opens if customers try to access a non-existent page.

The Error 404 page content is loaded without modifying the URL, so any incorrect characters in the URL can be replaced instead of requiring the entire URL to be re-entered. You can also add conditions, widgets, or other customer portal elements to the page to help the customer.

If the value for CP_404_URL is blank, the browser’s generic error page opens instead.

Customer Portal Widgets

Customer Portal Widgets

A widget is an element of the Oracle RightNow Customer Portal Cloud Service (Customer Portal) that performs a specific function.

The Customer Portal contains more than one hundred widgets in its standard widget collection. A few examples of standard widget functionality include the following.

  • An information field for input of customer information

  • A button that launches a search or submits customer information

  • A report that returns all answers containing a customer’s search terms

  • A dialog for customer feedback

  • A topics tree for browsing specific topics

  • A link to let customers share their desktop with an agent on the phone

  • An offer to chat with an agent

You can configure the functionality of standard widgets by editing their attributes to achieve different results. A standard widget on one page may function differently than the same widget on a different page, depending on the attribute settings.

You can also create custom widgets by extending the functionality of a standard widget, or you can create custom widgets from scratch.

By their nature, widgets are highly diverse elements, and we won’t be going into all the details of each one. For widget-specific information, first type https://<your_site>/ci/admin/docs/widgets/standard in your web browser. (Or select Browse Widgets on the Widgets tab of the Customer Portal Administration site and select Standard Widgets on the page that opens.) Then you can select a folder and widget to see its definition, including a preview, description, default code, attributes, and all other relevant information about configuring it.

Widget accessibility

The Customer Portal widgets have been designed to comply with Oracle Accessibility Guidelines.

When you create custom widgets, you are responsible for ensuring that your changes do not impact accessibility. Labels require particular attention. Input labels support accessibility by providing content for screen readers, and they should be used. However, if you choose to use an empty string for a label, some widgets will not include the asterisk that indicates the input field is required. even if you set the required attribute to true.

Widget files and code

A widget is a collection of files that work together to provide a specific functionality.

Widgets communicate with the Oracle database and the server through AJAX requests. They also communicate with other widgets through events. When you add a widget to a page or a template, you add code that resembles the following example.

 <rn:widget path="input/FormInput" name="Contact.Emails.PRIMARY.Address" required="true" validate_on_blur="true" initial_focus="true" label_input="#rn:msg:EMAIL_ADDR_LBL#"/>

The widget code contains the following elements.

  • rn:widget—Identifies the object as a widget to be rendered on the page. The rn: prefix identifies the widget as a standard Customer Portal element.

  • path—Locates the widget in the file structure by specifying the folder and widget name (input/FormInput in the example).

  • attributes—Defines widget parameters that control appearance and function. The attributes in the example are name, required, validate_on_blur, initial_focus, and label_input.

Widget files are stored in widget group subfolders (/chat/, /discussion/, /feedback/, /input/, etc.) in the /cp/core/widgets/standard folder. Each widget has its own subfolder containing all the files for that widget. A widget may contain some or all of the following files:

  • info.yml—Provides information about a widget’s dependencies, requirements, attributes, and URL parameters. Every widget has a YAML file.

  • controller.php—Constructs the widget and calls the data it needs.

  • view.php—Contains the HTML required to display the widget.

  • *.html.php—Defines a view partial, which is a subset of the widget’s view and is called from the view.php file.

  • logic.js—Contains the display logic and events the widget subscribes to or fires. This file also contains logic for updating the widget’s HTML when new information is received from an event.

    Note: The controller.php, view.php, and logic.js files for each standard widget identify the originating release in the first line of code.
  • *.ejs—Embedded JavaScript template files that combine variables and the template to produce HTML.

  • base.css—Provides the non-editable CSS for a widget.

  • presentation.css— Controls the stylistic elements that determine how the widget displays on a page.

    Note: The presentation CSS files are located in the /cp/core/assets/default/themes/standard/widgetCss or /cp/core/assets/default/themes/mobile/widgetCssfolder and include the widget name, for example, AdvancedSearchDialog.css.
  • preview/preview.png—Displays an example of what the widget will look like when it is added to a page.

YAML file

Every widget has an information file written in YAML format, which contains no executable code.

The following example is the info.yml file for the KeywordText widget.

version: "1.1.1"

requires:

version: "1.1.1"
requires:
    framework: ["3.3"]
    jsModule: [standard, mobile]
    attributes:
        report_id:
            name: rn:msg:REPORT_LBL
            type: STRING
            description: rn:msg:ID_RPT_DISP_DATA_SEARCH_RESULTS_MSG
            default: rn:def:CP_NOV09_ANSWERS_DEFAULT
        source_id:
            name: rn:msg:SOURCE_ID_LBL
            type: STRING
            description: rn:msg:NAMED_SRC_WIDGET_FIRE_SRCH_EVENTS_LBL
        label_text:
            name: rn:msg:LABEL_LBL
            type: STRING
            description: rn:msg:STRING_LABEL_DISP_WARN_MODIFICATION_LBL
            default: rn:msg:SEARCH_BY_KEYWORD_CMD
        initial_focus:
            name: rn:msg:INITIAL_FOCUS_LBL
            type: BOOLEAN
            description: rn:msg:SET_TRUE_FIELD_FOCUSED_PAGE_LOADED_MSG
        label_placeholder:
            name: rn:msg:PLACEHOLDER_LABEL_LBL
            type: STRING
            description: rn:msg:PLACEHOLDER_NOTE_INPUT_SPACERS_SUPP_IE9_LBL
            default: rn:msg:ASK_A_QUESTION_ELLIPSIS_MSG
    info:
        category:
            - Report Search
        description: rn:msg:WIDGET_DISP_INPUT_TXTBOX_ALLOWS_MSG
        urlParameters:
            kw:
                name: rn:msg:KEYWORD_LBL
                description: rn:msg:SETS_TXT_KEYWORD_BOX_URL_PARAM_VAL_LBL
                example: kw/roam

The elements of this file include the following:

  • version—Defines the widget’s version number. Custom widgets must have a major and minor version specified, while standard widgets also include a nano version.

  • requires—Defines the required framework version number, the required JavaScript module, and any YUI modules that need to be loaded for widget functionality. (The Customer Portal Framework Version 3.3 uses the YUI 3.17 library. Several standard YUI modules are available on every page, and any module is available to widgets that declare dependency on that module.

  • attributes—Defines the widget’s attributes and their values. Note that if a custom widget inherits attributes of a standard widget when it is created, only the inherited attributes that have been removed or edited are listed in info.yml. The others are implied because the custom widget was created by extending the standard widget.

  • extends—Identifies the standard widget that was used as the parent widget if this widget was created by extending another.

  • info—Provides a description of the widget’s functionality and an array of URL parameters the widget gets information from, including name, description, an example, and whether the parameter is required.

    Note: The Widget Info page, accessed at https://<your_site>/ci/admin/docs/widgets/info, is an additional source of information about the info.yml file when you’re on the Customer Portal Administration site.

Controller file

The controller.php file renders and previews the widget.

The controller file functions are constructing the widget and getting the data it needs. The get data function of controller.php instantiates the widget. In the KeywordText widget, for example, the get data function loads a report model that gets report data, creates other functions, gets data, and then returns data and passes it to the view file.

Note: The controller files of standard widgets have been intentionally written to omit the closing PHP tag (?>). Additionally, code has been added to automatically remove the closing PHP tag from the end of widget controllers during the staging operation. If you add a closing tag to a widget controller file, the widget will display and work properly on the development site, but parsing errors might occur on the staging site.

View file

The view.php file contains blocks of code that indicate the elements of the code that you can edit.

Every block in a widget has a unique ID that describes its context. Although standard widgets don’t actually use the block tags, the tags identify where the code is editable. They serve as customization hook points where you can add custom code to the standard widget to create a custom widget. (Not every element of every widget is exposed as a block if modifying the element would cause problems with the standard code.)

Only the code within blocks can be edited. If you add code outside of block tags, your code will be ignored. If you don’t specify the ID of a standard block or if the ID you specify doesn’t exist in the standard widget’s view, your code will also be ignored.

When a standard widget undergoes a nano change, that is, a fully backward compatible change, the change is automatically applied to the widget in your customer portal files so that you can take advantage of the bug fix or enhanced functionality. Additionally, any custom widgets that were created by extending that standard widget will also be updated. This benefit of automatic updating of custom code is possible whenever you extend a standard widget’s view instead of overriding it when you create a custom widget.

View partials

In an effort to avoid code duplication within and among widgets, the Customer Portal includes view partials, which are sections of code that can be used multiple places within a widget or shared across multiple widgets.

Many widget view.php files include duplicate sections of code that are used throughout the widget. Other widgets share sections of code, and each widget calls out the same code section.

The cp/core/framework/views/Partials folder contains these view partial files that can minimize code duplication by letting you reuse common view elements, such as the red asterisk and screen reader label to indicate a field is required.

If a widget is within a view partial, the widget is rendered in the view.

Multiple view partials within one widget

Rather than a single large view.php file, some widgets have partial view files that are smaller subsets of the view.

The view.php is the main widget view, but it renders the partial view files, which also appear in the widget’s folder. For example, the AnswerFeedback widget was split into three view partials. These view partials use the *.html.php naming convention.

The view.php file for the AnswerFeedbackWidget contained 79 lines of code in Framework Version 3.2.1, while the same file in Version 3.3.1 contains only 18 lines, including three lines that call the widget’s view partials to render the various feedback options: Yes/No buttons, up to five stars, and a numerical ranking scale.

When you extend a standard widget and choose to extend its view, the extended widget contains the standard widget’s view.php file and all of its view partial files. When you do not change the standard widget’s view (both View questions are answered No) or when you override the view instead of extending it (by answering Yes to “Does this widget modify the parent widget’s view?” and selecting the Override option), the standard widget’s view partials are not included in the view of the extended widget.

The view partials within a single widget have all the functionality of regular views. They can reference other widgets with the $this context, and they can use <rn:block> and #rn:# tags.

Multiple widgets sharing the same partial

The Customer Portal provides view partials that can be used by any widget.

For example, the SiteFeedback widget contains the following code.

<label for="rn_<?=$this->instanceID?>_FeedbackTextarea">
    <?= $this->data['attrs']['label_comment_box'] ?>
    <?= $this->render('Partials.Forms.RequiredLabel') ?>
</label>

This code calls the view partial RequiredLabel.html.php in the /cp/core/framework/views/Partials/Forms folder, which contains the following code:

<span class="rn_Required"><?= $requiredLabel ?:/RightNow/Utils/Config::getMessage(FIELD_REQUIRED_MARK_LBL) ?></span>
<span class="rn_ScreenReaderOnly"> <?= $screenReaderLabel ?:/RightNow/Utils/Config::getMessage(REQUIRED_LBL) ?></span>

Instead of duplicating the same HTML across different widgets to create the red asterisk and screen reader label to indicate a required field, this single shared view partial can be reused by any widget that needs it by simply calling:

$this->render('Partials.Forms.RequiredLabel')

If you want to override contents of a standard view partial, you must register a custom view in /cp/customer/development/config/extensions.yml by adding the following text to the file.

partialViewExtensions: - Partials.Forms.RequiredLabel

Then whenever the Required.Label view partial is called, the custom file located in /cp/customer/development/views/Partials will be used instead of the standard one in the core folder.

Unlike view partials within a single widget, which have the same functionality as regular view files, view partials that are shared among several widgets have limited functionality. They cannot render widgets or use rn: tags. Nor can they use the $this context to access widget properties.

Creating custom view partials

If you want different functionality for a standard view partial (if, for example, you want to use two blue asterisks instead of a single red one to indicate that a field is required or you want to use a different screen reader label for a required field), you can create a custom view partial file with the same name as the standard.

Using the Required.Label view partial as an example, you would create the new view file, name it RequiredLabel.html.php, and place it in /cp/customer/development/views/Partials/.

After creating the custom view and placing it in the /cp/customer/development/views/Partials folder, you must register the view. You do that by adding the following text to the /cp/customer/development/config/extensions.yml file.

viewPartialExtensions:
    - Partials.Forms.RequiredLabel

Now, calling the RequiredLabel view partial will call the custom view from your development site instead of the standard view partial.

To create a new view partial that can be shared among widgets, create the file and add it to /cp/customer/development/views/Partials. If your new file is named mySharedPartial.html.php, for example, you would add the following code to the custom widget’s view.php file.

<?=$this->render('Partials.MySharedPartial') ?>

Because you are not overriding a standard view partial, you do not have to register your custom view partials in the extensions.yml file as you do when you want to replace a standard view partial.

Logic file

The logic.js file contains the display logic and events for the widget.

The widget may subscribe to or fire custom events to and from the event controller. This file also calls any JavaScript templates the widget might use. The logic file is optional.

Embedded JavaScript files

Embedded JavaScript files allow you to perform complex functions in your customer portal files.

The ejs files in a widget folder are embedded JavaScript templates that produce HTML by using the variables that the view expects. It then can loop, perform conditions, or output variable data.

Widget CSS files

Some widgets have a base CSS file, others have a presentation CSS file, and many standard widgets have both.

The base CSS file for a widget controls its functionality, while the presentation CSS controls the appearance of a widget. By having separate presentation files, you can control the appearance of one widget without impacting the appearance of any other widgets.

You cannot edit the base CSS files for standard widgets, which are stored in the folders with the other files that make up each widget, for example, /cp/core/widgets/standard/chat/ChatAttachFileButton.

Widgets that have a corresponding CSS file in the /cp/customer/assets/themes/standard/widgetCss folder use that CSS file to control the presentation, or appearance, of the widget when it is rendered on a page. This file contains the rules for adding stylistic elements to the widget. The file name is [WidgetName].css, for example, AdvancedSearchDialog.css. The changes you make to presentation CSS files are sandboxed in the /themes/ folder, so you can view them on your development site, but you must stage and promote the customer portal before you can see those changes on your production site.

All widget styling must exist in one of the CSS files. Widget code cannot contain any inline CSS rules.

Best practices for widget CSS files include using as few classes as possible, using the top-level widget CSS class attribute to style elements within the widget, and creating styling rules only if a site CSS rule must be overridden.

CSS File Description Location Guidelines
Base controls the widget’s functionality /cp/customer/development/widgets/custom/[customWidget]/base.css
  • should contain rules that structure the widget or make it function correctly, with very few or no styling rules in the file

  • should not include generic functionality rules

  • rules should start with the class name in the top-level <div> element in the view

  • can be omitted

Presentation controls the appearance of a widget /cp/customer/assets/themes/standard/widgetCss/[widgetName.css]
  • must have the same name as the widget

  • rules should start with the class name in the top-level <div> element in the view

  • should contain no generic styling rules

Standard and custom widget folders

All of the standard widgets that are part of the Customer Portal reference implementation are stored in the /cp/core/widgets/standard folder, and all custom widgets that you create should be stored in the /cp/customer/development/widgets/custom folder.

The page code of the standard reference implementation files defines widgets without specifying whether they are in the standard or custom folder. (Because the reference implementation uses only standard widgets, they are all stored in the standard folder.)

When you modify page code to add or edit a widget, you do not have to specify a folder for the widget path. If you explicitly indicate either the standard or custom widget folder, the code will call the widget from that folder. If you do not specify a folder, the custom widget folder is searched first. If no widget with that name exists in the custom folder, the standard folder is searched.

If you want to create a custom widget that replaces a standard widget everywhere on your customer portal where the standard one appears, you have two options for doing so. The hard way is to find every instance of the standard widget in the code for all pages and replace each instance with the name of the new custom widget.

However, there’s an easier way. Because the custom folder is searched before the standard folder, you can replace a standard widget with a custom one that uses the same name without having to find and replace all calls to the new widget in all customer portal pages.

When you give a custom widget the same name as a standard widget, the custom path must be the same as the standard path. For example, if you create a custom AdvancedSearchDialog widget, you must create a subfolder called sear ch under the custom widget folder and place the widget in that subfolder so the relative path for the custom widget is the same as that of the standard widget. In other words, the path for the standard widget is standard/search/AdvancedSearchDialog. Therefore, the path for the custom widget must be custom/search/AdvancedSearchDialog.

When you give a custom widget the same name as a standard widget, you must be aware of controller issues, described in the following section. The standard widgets that are comprised of multiple widgets (such as ChannelAllInput, ContactNameInput, and CustomAllInput) reference the FormInput widget in their view.php files. If two input widgets use different controllers that have the same class name, such as FormInput or DataDisplay, deployment failures will occur.

Custom widget controllers

A deployment failure will occur if two different widgets on the same page use the same widget folder name.

When two different widgets on the same page use the same widget folder name causing a deployment failure, the widgets have the same class name in the controller. If you copy a widget and use the same widget name for the custom widget (for example, you create a custom input widget, name it FormInput, and put it in the widgets/custom/input folder, the custom widget uses the custom controller. However, because it has the same name as the standard widget’s controller, a failure occurs if both widgets are placed on the same page. The error message lists the two widgets using different controllers that have the same class name and identifies the page where they are found. This lets you correct the problem by copying the view.php files of the custom widget to the appropriate folders.

Widget AJAX requests

When widgets require data, they make an AJAX request to the server.

You define where a widget’s request goes by setting a value for a specifically named AJAX endpoint attribute. For example, the ConditionalChatLink widget has an attribute called get_chat_info_ajax that lets you define where the request for chat availability will be sent. The default value is /ci/ajax_Request/getChatQueueAndInformation. All requests are sent to /ci/ajaxRequest/, which loads the ajaxRequest controller so it can execute the specified function, which is getChatQueueAndInformation in this example.

YUI

The Customer Portal uses YUI 3.17.

While the Customer Portal uses YUI 3.17, you can substitute the value {YUI} at the beginning of a file name to use the most current YUI version. The following default YUI modules are included on each page, so you don’t need to call them out specifically in the widget code.

  • anim-base

  • anim-easing

  • escape

  • event-base

  • history

  • node-core

  • node-event-delegate

  • node-screen

  • node-style

You can also use the following YUI requirements in jsModule.

  • yui: [panel, autocomplete, autocomplete-highlighters]
  • yui: standard: [overlay]

Navigating folders and searching for widgets

There are a variety of ways to browse and search for customer portal widgets.

You can open the Widgets page of the Customer Portal Administration site by typing http://<your_site>/ci/admin/docs/widgets. You must log in with your user name and password, so make sure your profile includes the CP Edit permission.

You can also access this page from anywhere on the Customer Portal Administration site (http://<your_site>/ci/admin) by clicking the Widgets tab.

You can quickly navigate among the different widget folders. After you click Browse Widgets, select Standard Widgets, and select a folder, you can click the drop-down menu associated with the folder level and select a different folder.

Or, if you know the widget’s name, you can type the first few letters or any part of the name in the Search Widgets field to display a menu of widgets that match your entry.

Display and manage widget versions

Every customer portal widget has a version number. When a widget is changed, for example, by the addition of a new attribute that increases functionality, you’ll be able to incorporate only that widget without being required to use an entire widget set or a new Customer Portal framework version.

Procedure

  1. Log into your Customer Portal Administration site.

  2. Click Widgets.

  3. Select Widget Versions.

  4. To filter the list of widgets, click View Options.

  5. To display standard widgets only, selectView Options > Widgets > Standard.

  6. To display custom widgets only, select View Options > Widgets > Custom.

  7. To filter the list of widgets by widget status, click View Options and select one of the widget status filters.

    1. To display all widgets that are currently activated on your customer portal, select Active.

    2. To display all widgets that have been deactivated, select Inactive.

    3. To select all widgets being used in their most current version, select Up To Date.

    4. To select all widgets for which newer versions are available, select Out Of Date.

  8. To search for widgets in a specific category, click View Options and select a category.

  9. To search for a specific widget, type the first few letters of the widget name in the Search field.

  10. To update all widgets to their most recent version for the Customer Portal framework being used by your site, click Update All.

  11. To see all recent version changes, click Recent Changes.

If you migrate versions for multiple widgets on your development site and then decide to stage and promote your customer portal, you are required to deploy every migrated widget during the process. In other words, you cannot selectively deploy widget versions during the staging and promoting processes.

Additionally, if you migrate a widget when a newer version is available because you want to use it on a page, the new version will be used for every instance of that widget on your customer portal.

Select a widget

All of the information you need for each widget is defined in detail when you select the widget on the Customer Portal Administration site.

Procedure

  1. Type https://<your_site>/ci/admin to log in to the Customer Portal Administration site.

  2. Click Widgets.

  3. Choose one of the following:

    • Select Browse Widgets, select Standard Widgets or Custom Widgets, select the widget folder, and then select the widget name.
    • Select Widget Versions and select the widget you want to open from the list.
    • Type the widget name in the Search Widgets field.

Three tabs appear on the widget information page: Available Versions, Widget Usage, and Recent Version Changes. The following elements appear on the page regardless of the selected tab.
  • Preview—The preview shows you an example of what the widget looks like on a page. If the widget is larger than the preview window and the display provides only a partial view, you can click the preview window to display an expanded view of the widget.

  • Widget history timeline—A timeline at the top of the page shows the available versions of the widget and the version currently in use. If the widget version is 1.0, the message says, “This is the newest version.”

Available Versions tab

There are a number of attributes on the Available Versions tab.

The following elements appear on the Available Versions tab of the widget information page.

  • Staging/Production/Development—When multiple versions of the widget exist, the areas using each version are noted. In the following figure, the development, staging, and production areas are all using version 1.2 of the widget.

  • Framework requirements (dependency information)—The page includes the framework version that must be installed to support the widget version.

  • Widget version information—Each version of the widget is listed on the page, with the newest listed first. The version section describes the changes that were made from the previous version. The changes are categorized as likely impact, possible impact, or no impact to custom code, determined by hovering over the bullet for each change. Changes are further classified as new features, removal of functionality, API changes that impact the widget, or bug fixes.

  • Documentation—Clicking Documentation opens a page of information specific to the widget, including description, default code, attributes by category (such as labels, image paths, and AJAX endpoints), the controller class, path information, and URL parameters. (If the page describes a custom widget that was extended from another widget, it will also list the parent widget.) Print this page by clicking the Print link.

  • Dependencies—When a standard or custom widget has dependencies, the Dependencies button appears on the widget information page next to the Documentation button. Clicking the Dependencies button opens a window that displays the dependencies to other widgets. Dependencies include the following:

    • A widget contains other widgets (for example, AdvancedSearchDialog contains KeywordText and other widgets)

    • A widget is extended from another widget (for example, ChatAttachFileButton extends from FileAttachmentUpload)

    • A widget is the parent of a widget (FileAttachmentUpload is the parent of ChatAttachFileButton)

  • Deactivate this widget—When you click this button, the widget is no longer available for use on your site. Then, when you filter on only the Active widgets, your list displays only the activated widgets. (Even deactivated widgets will appear in the list of widgets if you do not select the Active filter.) For example, if you do not use Oracle RightNow Chat Cloud Service (Chat), you may want to deactivate each of the chat widgets. When you click the button for a widget that is currently in use on your site, you are asked to verify that you want to deactivate the widget and offered a chance to see where it is being used. (Even though you are not using Chat, the reference implementation includes Chat pages that use the chat widgets so you will see the message.)

    Widgets are not actually removed from the code when you deactivate them, but they are made unavailable for use. After you have deactivated a widget, it does not appear in the list of widgets when you use the Active filter. It does appear in the list when no filter is used, but it is grayed out to indicate that it is deactivated. If you click a deactivated widget, you can reactivate it. An Activate This Version button appears, and you can select the version you want from the drop-down menu.

    After selecting the version and clicking the button, the widget is activated once again.

    Important: When new widgets are added in future releases, they are not automatically activated. Instead, you’ll need to specify which version of the widget you want when you decide to start using it. This prevents the possibility of using a widget that was activated earlier but hadn’t been used yet if a newer version becomes available before you decide to use it on your customer portal.
  • Delete this widget—The Delete This Widget button appears only for custom widgets. When you click the button, a confirmation message appears. If the widget is being used on your customer portal, a Display Containing Views button appears on the confirmation message. Click the button to display a list of pages and/or widgets that use the widget you want to delete.

    When you click Delete in the confirmation message, the widget is deactivated and deleted from the panel that contains a list of all the widgets. All of the widget’s associated files are also deleted from the file structure, so they no longer appear in the WebDAV file structure. The deleted files are listed in the message that tells you the widget was deleted. You cannot reactivate the widget after deleting it.

Widget Usage tab

Selecting the Widget Usage tab displays the widgets, pages, and templates that use the widget.

Click the link to view the code snippet on the selected widget or page where the widget is used. Select a widget or page from the list to view the snippet of page code where the widget appears, highlighted for easy location.

Recent Version Changes tab

Selecting the Recent Version Changes tab displays a list of recent updates to the widget.

Information includes whether a different version is now being used or if the widget was activated or deactivated. It also includes the staff member who made the change and the date and time the change occurred.

Widget attributes

Each widget has properties, or attributes, that are specific to the instance of the widget.

A widget can look or behave one way on one page and differently on another. You might even have two instances of the same widget on one page with different attributes. For example, you could add a second ProductCategoryList widget to the Support Home page to display a list of featured support products in addition to the featured support categories list that appears on the page by default.

When a widget contains other widgets, you can use the attributes of the contained widgets in the widget definition. For example, the DataDisplay widget contains, among other widgets, the FileListDisplay widget. The code for the DataDisplay widget can include attributes of the FileListDisplay widget, even if those attributes are not available on the DataDisplay widget. The attribute value specified in the DataDisplay widget code is passed on to the FileListDisplay widget.

Additionally, you can create an RN Container page tag to define a set of attributes and their values that are common to multiple widgets. Then, instead of having to add every attribute to the code for each of the affected widgets, you can use the container to define the attributes.

If the widget code specifies an attribute that is also defined in the container, the value for the attribute in the widget code overrides its value in the container.

The page for each widget on the administration site lists and explains the attributes of the widget and tells you how to define the attribute in the widget’s code.

Sub-widgets and attributes

Several Customer Portal widgets contain other widgets.

Often a widget that is contained in a parent widget has attributes with the same name as the attributes of another contained widget. The AdvancedSearchDialog widget, for example, contains two instances of the ProductCategorySearchFilter, one for products and one for categories. Because you want to be able to specify unique labels for each, both instances of the ProductCategorySearchFilter widget have their own ID value to let you use the widget’s sub_id attribute to accomplish this. Review the Containing Widgets section of the documentation page for the AdvancedSearchDialog widget at https://<your_site>/ci/admin/versions/manage/#widget=standard%2Fsearch%2FAdvancedSearchDialog&docs=true&version=1.1. Notice that each of the widgets that are part of the AdvancedSearchDialog widget now contains a sub_id attribute.

Setting a sub-widget’s attribute requires the format:

sub:{sub_id}:{widget_attribute}="Value being set"

For example, the following procedure uses this syntax to set the label_input attribute for the Product field:

sub:prod:label_input="Your Product"

See Configure the AdvancedSearchDialog widget with sub-widgets for an example of how you can use sub-widgets for greater flexibility and reduced code duplication. The example assumes you want to change the “Limit by product” and “Limit by category” labels that appear on the AdvancedSearchDialog widget. Those labels and their associated drop-down menus are created using the sub-widgets for ProductCategorySearchFilter.

Configure the AdvancedSearchDialog widget with sub-widgets

Using the AdvancedSearchDialog, this example demonstrates configuring a widget with sub-widget.

Procedure
  1. Open the page containing the AdvancedSearchDialog widget.

  2. Locate the following code.

     <rn:widget path="search/AdvancedSearchDialog" report_page_url="/app/answers/list"/>
    

  3. Edit the code you located in step 2 as follows:

    <rn:widget path="search/AdvancedSearchDialog" report_page_url="/app/answers/list" sub:prod:label_input="Your Product" sub:cat:label_input="Your Category" />

  4. Save the file.

Other sub-widget examples

When several of a widget’s sub-widgets have the same attribute, you can set the attribute for all of them in the widget code, as you could before.

You can make an exception based on a specific sub-widget. In the following example, the default hint value is used for all custom fields except the Priority custom field, which has its own hint.

<rn:widget path="input/CustomAllInput" hint="hint for every field except Priority" sub:input_Incident.CustomFields.c.priority:hint="Priority hint"/>

FormInput examples

The CustomAllInput contains the FormInput widget, and the FormInput widget contains the SelectionInput, DateInput, PasswordInput, DisplayNameInput, and TextInput widgets.

Because there are different types of input widgets in FormInput, each sub-widget has its own ID, which you can use to set attributes for all sub-widgets of that particular type, similar to the example shown here.

<rn:widget path="input/CustomAllInput" hint="hint for every field except date fields" sub:date:hint="hint for all date fields"/>

If the code sets an attribute based on type (text, selection, date) and that attribute is set to a specific value by default, you can explicitly override the attribute using the sub-widget code format:

sub:<id>:<attribute_name>="attribute_value"

This ensures that the value you specify takes precedence over attributes set in the widget’s view. For example:

<rn:widget path="input/CustomAllInput" table="Incident" sub:text:required="true" sub:input_Incident.CustomFields.c.text1:text:required="false" sub:selection:hint="Hint for selection field" sub:input_Incident.CustomFields.c.priority:selection:hint="Hint for Priority field" />

Notice that you must include the type after the field name only if the code also has an attribute with sub:type:<attribute_name>. That is, you can set specific attributes such as the required or hint value for a specific field using the format below.

<rn:widget path="input/CustomAllInput" table="Incident" sub:input_Incident.CustomFields.c.text1:required="true" sub:input_Incident.CustomFields.c.priority:hint="Hint for Priority field" />

ChannelAllDisplay and ChannelAllInput examples

This example uses sub-widgets to define custom labels.

The ChannelAllDisplay and ChannelAllInput widgets work similarly, where you can use sub-widgets to define custom labels for each channel, as shown in this example.

<rn:widget path="output/ChannelAllDisplay" sub:display_FACEBOOK:label="Custom Facebook username"
    sub:display_TWITTER:label="Custom Twitter username" 
    sub:display_YOUTUBE:label="Custom YouTube username" /> 
<rn:widget path="input/ChannelAllInput" 
    sub:input_FACEBOOK:label_input="Custom Facebook input field"
    sub:input_TWITTER:label_input="Custom Twitter username"
    sub:input_YOUTUBE:label_input="Custom YouTube input field" />

Editing widget labels

Most widgets include label attributes that you can edit. Using the RecentlyAnsweredQuestions widget, we’ll demonstrate the procedure for changing widget labels.

Procedure
  1. Open the page containing the widget you want to edit.

  2. Locate the code for the widget.

  3. Determine the attribute names for the labels you want to edit.

  4. Add the attribute using the form label="New Label Name".

  5. Save the file.

Edit labels on the RecentlyAnsweredQuestions widget

This example edits labels on the RecentlyAnsweredQuestions widget.

Procedure
  1. Open /views/pages/home.php.

  2. Locate the following line of code.

    <rn:widget path="discussion/RecentlyAnsweredQuestions" show_excerpt="true" maximum_questions="5"/>

  3. Navigate to the widget’s Documentation page.

  4. Edit the code to add the label attributes you want to change. Your code will resemble the following.

    <rn:widget path="discussion/RecentlyAnsweredQuestions" show_excerpt="true" maximum_questions="5" label_answer_more_link="Expand Discussion" label_moderator_answer="Staff Best Answer" label_user_answer="Original Poster Best Answer"/>

  5. Save the file.

Find report IDs

You might have noticed that several widgets include a report_id attribute. This attribute defines the report to be displayed by the widget. When you reference a report (for example, the Questions report for the Grid widget), you must know the report’s ID number. The following procedure tells you how to find the report ID.

Procedure
  1. Click Analytics.

  2. Double-click Reports Explorer.

  3. Find and select the report you want. You can find Customer Portal and reports under /Public Reports/Service/Views – Service/Customer Portal.

  4. Click Choose Details.

  5. Select the check box for ID.

  6. Click OK.

Editing widgets to change reports

When a page includes search navigation with an answers report, multiple widgets are used to control the functionality.

You can edit the widgets on a page to change the reports used by that page. On the Published Answers page, for example, these widgets include the following.

  • Elements of the search tool:
    • Search field (KeywordText widget)

  • Search button (SearchButton widget)

  • Search filters (ProductCategorySearchFilter widgets)

  • Elements of the returned search results:

    • The report itself (Multiline widget)

    • The display of total number of results (ResultInfo widget)

    • Pagination control (Paginator widget)

In all, six widgets on the Published Answers page make up the search field and report, and each of these widgets must call the same report in order for the page to display meaningful information. The reference implementation uses a container page tag to define this report ID as 176, which is the Answers–Complex Expression Search Default report.

The same thing is true for any other customer portal page that uses the combination of search field and report, whether it is a page of the reference implementation or a custom page that you’ve created. That is, all widgets that make up these elements must call the same report using one of the following methods.

  • Use the RN Container page tag to identify one or more common attribute values and then embed a group of widgets within the container tags or specify the container as a widget attribute.

  • Edit every search and report widget on the page by adding the report_id attribute to the widget code and setting its value to the ID of the report you want to use. The attribute format resembles the following.
    report_id="194"

Hiding reports when no results are returned

Several report widgets include a hide_when_no_results attribute that prevents the widget from displaying if no search results match the entered terms.

The widgets that include the hide_when_no_results attribute are Multiline, Grid, MobileMultiline, and ModerationGrid.

To hide the widget, simply add the attribute and set its value to true. Here’s an example of adding the attribute to the Multiline widget.

<rn:widget path="reports/Multiline" hide_when_no_results="true"/>

Date and time formats in reports

The date_format attribute formats and values can impact the date and time output on certain reports.

The Multiline, MobileMultiline, BasicMultiline, Grid, and ModerationGrid reports let you format the output of date columns in the report. The following table shows the output for each allowable value of the date_format attribute for the reports.

Table Values for the date_format Attribute of Report Widgets

Value Format Example
short (default value) m/d/Y 09/14/2015
date_time m/d/Y h:i A 09/14/2015 11:08 AM
long l, M d, Y Wednesday, Sep. 14, 2015
raw unformatted UNIX time stamp 1442228880

Defining the number of search results

You can define the number of displayed search results.

You can limit report results by adding the per_page attribute, for example, as shown in the following code.

<rn:widget path="reports/Multiline" per_page="5" />

If the report definition on the Service Console includes row limits and the report widget defines the per_page attribute, the widget attribute overrides the report definition.

Building custom widgets

The Customer Portal widget builder can create a new widget by extending the functionality and attributes of an existing widget and generating custom code files for the new widget. The code contains placeholders that you can modify to achieve the behavior you want for the new widget.

Using the Customer Portal’s widget builder, you can create custom widgets to suit your own business needs. Each custom widget can be designed from scratch as a standalone widget, or it can inherit and extend the functionality and attributes of another widget (referred to as the parent widget).

When you create a new widget from scratch, the widget builder creates the files you need based on your responses to the questions it poses. The files may contain placeholders where you’ll need to add content, or they may be blank.

Note: You can also create code for a custom widget and add it to your customer portal through WebDAV without using the widget builder. The widget will appear in the list on the Widget Versions page, but you must manually activate it by selecting it and then clicking Activate This Version in the upper right section of the page.

The widget builder generates custom widget code when you answer a series of questions about the widget you want to create. By creating placeholders for additional code you’ll add to further define the custom widget, it reduces the amount of code you must write and minimizes the possibility of errors because it creates the widget’s basic code structure.

When you create a new widget by extending the functionality of an existing standard or custom widget, you can define whether the new widget will have its own controller, view, CSS, and JavaScript files or whether it will extend the corresponding file from the existing widget that the new widget is being extended from.

To define the behavior of a custom widget, you can include or modify attributes for the following components.

  • Controller—Initializes and processes data required for widget output. Controllers can also contain AJAX-handling functions.

  • View—Displays the PHP output generated by a controller, rendered as HTML. The file contains a top level div to simplify your coding work.

  • CSS—Defines the style and appearance of the view.

  • JavaScript—Produces specific behavior and renders dynamic HTML views.

  • YUI—Defines the YUI modules to be used with the new widget.

  • Additional widget details—Lets you add a widget definition, specify inherited URL parameters, and define JavaScript framework compatibility.

To simplify the process of creating a new widget, the widget builder steps you through a series of basic questions about your widget. Once complete, the utility generates the widget information file along with all of the necessary supporting files based on your responses, which you then edit to meet your needs.

Extending and overriding the view

You can extend or override a parent widget’s view when modifying a new widget.

If you indicate that the new widget will modify the parent widget’s view, you’ll be asked if you want to extend the view or override it. This is an important question, and you should think carefully before selecting the override option.

We highly recommend that you choose to extend the parent’s widget view instead of overriding it. When you extend a standard widget’s view, any future changes to the standard widget will be automatically applied to the custom widget that was created by extending it. If you choose to override the view instead of extending it, your custom code will not be updated.

Note: You can extend widget views past the child level. For example, if you extend widget A’s view to create the view for custom widget B, you can also extend the view of widget B to create widget C’s view. The parent widget’s view can be extended in the child’s view, which can be extended for the grandchild, and then the great-grandchild.

Create a widget from scratch

You can create custom widgets to control many features on your customer portal.

Procedure

  1. Type https://<your_site>/ci/admin to log in to the Customer Portal Administration site.

  2. Click Create a New Widget.

  3. Click Create a Brand New Widget From Scratch.

  4. Type the name of the custom widget in the What Is Its Name field. The name cannot contain spaces.

  5. Type the name of the custom widget’s parent folder in the And Its Parent Folder field.

  6. Click Continue.

  7. To enable specific widget components, select Yes.

    Note: A custom widget must include at least one of the listed components. A widget without any of these components is nonfunctional and invalid.

    Table Components for New Custom Widgets

    Question Description
    Does this widget have a controller? Select Yes if you will create a controller file for the widget.
    Will it be doing any AJAX-handling? Select Yes if the widget’s controller will handle AJAX requests.
    Does this widget have a view? Select Yes if the widget will display HTML from the controller file’s PHP.
    Does this widget have JavaScript? Select Yes if the widget will contain JavaScript. This option is automatically enabled when the AJAX-handling option is enabled.
    YUI Modules

    Click Add Module and begin typing the name of the YUI module you want to have loaded on the page containing the widget and passed to the widget’s constructor. A list of modules that match the text you enter appears so you can select the one you want. To add more YUI modules, click Add Module and type the name.

    By default, several YUI modules are already included on each page.

    JavaScript templates too? Select Yes if the widget will display dynamic HTML content rendered by JavaScript.

  8. Click Continue.

  9. If you answered Yes to the question about AJAX handling, you can define the default_ajax_endpoint attribute by editing the name, selecting AJAX for the type, creating a description, setting a default value, and defining whether the attribute is required.

  10. To add another attribute, click Add an Attribute and enter the following field information:

    Note: Attribute names cannot contain uppercase characters.

    Table Custom Widget Attributes

    Attribute Description
    Attribute name Type the name of the attribute in the header field.
    Type Select the type of attribute you want to define. Available types include string, Boolean, AJAX endpoint, option, multi-option, file path, and integer.
    Description Type a description for the attribute. This text describes the attribute when you click Documentation on the custom widget page.
    Options Click Add Option and type an option value to add one or more values to an option-type attribute. This field is available only when the attribute Type is set to Option or Multi-option.
    Default value Type a default value for the attribute. By default, a Boolean-type attribute is set to true. Select the False check box if you want the value to default to false.
    This attribute is required Select this check box to make the attribute required.

  11. To add more attributes, repeat step 10.

  12. Click Continue.

  13. To add details to the widget, click Add Additional Details and enter the following field information.

    Table Additional Custom Widget Details

    Field Description
    Widget description Type a description for the widget that appears in the info.yml file and on the widget’s definition page.
    URL Parameters To add a URL parameter, click Add a URL Parameter and complete the Name, Description, and Example fields. (The Name field cannot contain spaces or forward or backward slashes.) To remove a parameter you added, click X.
    Compatibility If you want the widget to work with a specific Customer Portal JavaScript framework, select Standard or Mobile or both. Or select No Framework JavaScript is Required. This section does not appear if the widget does not have a JavaScript component.

  14. Click Create Widget.

  15. Edit the files that were generated so that the custom widget looks and performs as you intend it to.

    Note: To use the new widget in the staging environment, you must not only be sure you select Copy to Staging in the first step of the staging process, but you must also push the widget version change in the second step of the staging process, Version Changes.

Create a custom widget by extending the functionality of another widget

You can use an existing widget to create a new custom widget.

Procedure

  1. Type https://<your_site>/ci/admin to log in to the Customer Portal Administration site.

  2. Click Create a New Widget.

  3. Click Extend the Functionality of an Existing Widget.

  4. Start typing the name of the widget you want to extend in the Which Widget Shall It Extend From field.

  5. Select the widget you want to extend.

  6. Type the name of your new custom widget in the What Is Its Name field. The name cannot contain spaces.

  7. Type the name of the custom widget’s parent folder in the And Its Parent Folder field.

    Note: If you’re creating the custom widget to substitute for a standard widget, you’ll want to be sure the name and folder match the widget you want to replace.

  8. Click Continue.

  9. To enable specific widget components, select Yes for each correlating question.

    Table Custom Widget Components

    Question Description
    Does this widget have a controller of its own? Select Yes option if you will include a controller file for the widget. The new widget is not required to have its own controller. However, you can extend the parent widget’s controller so the new widget can inherit and modify the behavior of its parent.
    Will it be doing any of its own AJAX-handling? Select the Yes option if the widget’s controller will handle its own AJAX requests. The widget will automatically inherit any AJAX-handling functionality of its parent. This option allows you to add new AJAX-handling capabilities or modify the functionality inherited from the parent.
    Does this widget modify the parent widget’s view? Select the Yes option if the widget will modify or override blocks of content within the view of its parent.
    Extend the view This is the recommended option. By extending the view of a standard widget, the custom widget you create will be automatically updated when nano changes are made to the standard widget in the future. No effort will be required on your part to consume the new functionality or bug fix.
    Override the view Selecting this option means that you will be required to manually update the custom widget to take advantage of any future changes to the parent widget
    Include the parent widget’s CSS? Select the Yes option if you want the widget to include the CSS style attributes defined for its parent.
    Does this widget have its own JavaScript? Select the Yes option if the widget will extend the JavaScript functions defined for its parent.
    YUI Modules If you have selected Yes for the preceding JavaScript question, the Add Module link is active. Click Add Module and begin typing the name of the YUI module you want to have loaded on the page containing the widget and passed to the widget’s constructor. A list of modules that match the text you enter appears so you can select the one you want. To add more YUI modules, click Add Module and type the name. By default, several YUI modules are already included on each page.
    JavaScript templates too? Select the Yes option if the widget will modify blocks of content within the parent’s JavaScript view.
    Note: A custom widget must include at least one of the listed components to be a valid, functional widget.

  10. Click Continue.

  11. To edit an inherited attribute, modify the attribute type, description, default value, or whether it is required.

  12. To remove an inherited attribute, click the X.

  13. To add an attribute, click Add an Attribute and enter the following field information:

    Note: Attribute names cannot contain uppercase characters.

    Table Custom Widget Attributes

    Attribute Description
    Attribute name Type the name of the attribute in the header field.
    Type Select the type of attribute you want to define. Available types include string, Boolean, AJAX endpoint, option, multi-option, file path, and integer.
    Description Type a description for the attribute. This text describes the attribute when you click Documentation on the custom widget page.
    Options Click Add Option and type an option value to add one or more values to an option-type attribute. This field is available only when the attribute Type is set to Option.
    Default value Type a default value for the attribute. By default, a Boolean-type attribute is set to true. Select the False check box if you want the value to default to false.
    This attribute is required Select this check box to make the attribute required.

  14. To add another attribute, repeat step 13.

  15. Click Continue.

  16. To add details to the widget, click Add Additional Details and enter the following field information.

    Table Additional Custom Widget Details

    Field Description
    Widget description Type a description for the widget that appears in the info.yml file and on the widget’s definition page.
    URL Parameters If the parent widget contains URL parameters, they will be listed in this section as inherited parameters for the new widget.
    Compatibility If you want the widget to work with a specific Customer Portal JavaScript framework, select Standard or Mobile or both. Or select No Framework JavaScript is Required. This section does not appear if the widget does not have a JavaScript component.

  17. Click Create Widget.

  18. If necessary, edit the generated files.

Customizing widget behavior

Each file, in the custom widgets folder, is used to enable certain functionality within the widget and can vary based on whether the widget is a standalone widget or if it extends the functionality of another widget.

When you create a custom widget using the widget builder, some or all of the following files are stored in the parent folder that you defined in the /widgets/custom folder.

Table Widget Builder Output

File Description
info.yml Contains information about the widget, including its version and attribute values. If the widget extends the functionality of another widget, this file also contains the name of that widget and any components that are extended.
controller.php Initializes and processes the data required for the widget output. This file can also contain AJAX-handling functions or modify AJAX functionality inherited from the parent, if any exists.
view.php Receives the PHP output generated by the controller and renders it as HTML. If the widget extends the functionality of another widget, this file modifies or overrides blocks of content within the view of the parent.
logic.js Defines JavaScript functions used by the widget to produce dynamic behavior.
view.ejs Defines JavaScript functions used by the widget to render dynamic views.
<widget_name>.css Defines the style and appearance of the view.
base.css Contains any style information that extends the CSS of the parent widget, if applicable.

Display a preview of a custom widget

The Customer Portal Administration site describes the custom widgets you create as well as the standard widgets. Follow this procedure to include a screen capture of a custom widget in the widget definition.

Procedure

  1. Add a new subfolder called CustomWidget/preview to the /cp/customer/development/widget/custom folder, where CustomWidget is the name of the widget you want to add a preview for.

  2. Add a .png, .jpg, .jpeg, or .gif file to the subfolder you created and name it preview. When you select the widget on your ci/admin/versions/manage page, the associated preview file will be rendered.

Input and output widgets

When you put input widgets on a page, your customers can enter and update information that gets stored in incidents and contact records.

Output widgets are used to display information about incidents, contacts, and answers in read-only form.

You can help your customers enter the information you request by defining field lengths, adding hints to input widgets, and displaying the format that should be used. This section also defines how to input and output custom fields, discusses using widget attributes, URLs, and POST parameters to define default values, and describes a page tag that can also be used for outputting field values.

The fields you can use for input and output widgets and the Field page tag are listed on the Business Objects page of the Customer Portal Administration site. The page lists the names for the answer, asset, contact, incident, service product, service category, social question, social question comment, and social user fields as they are defined in the Connect PHP API.

The following table shows code samples for widgets using the fields.

Table Code Samples for Widgets Using Data Fields

Widget Data Field Code Sample
FormInput Incident.Subject <rn:widget path="input/FormInput" name="Incident.Subject" required="true" />
DataDisplay Answer.Products <rn:widget path="output/DataDisplay" name="Answer.Products" />
Field page tag Contact <rn:field name="Contact.LookupName"/>

You will see an error in development mode if your code for an input widget includes a primary sub-object, that is, if you try to use an input widget on a primary object that is the child of another object. For example, the following code will display an error message in the development area:

<rn:widget path="input/FormInput" name="Incident.PrimaryContact.Name.First" />

The exceptions to this limitation include Incident.Product, Incident.Category, and Contact.Address.Country.

When you create a custom object with custom menu attributes, the attributes can be used with FormInput and DataDisplay widgets and the rn:field tags for Contact and Incident objects. Custom menu attributes can be used with the DataDisplay widgets for Answer objects. All custom menu attributes appear on the Business Objects page of the Customer Portal Administration site.

Input widgets

The input widgets are used to enter information.

The following widgets are used to enter information for contacts or incidents.

  • ChannelAllInput—Adds Twitter, YouTube, and Facebook fields where customers can enter their user names for those channels.
    Note: You can also define input fields for single channels. Type <rn:widget path="input/FormInput" name="Contact.ChannelUsernames.TWITTER.Username" /> to add the Twitter channel. Change the name attribute to Contact.ChannelUsernames.YOUTUBE.Username for YouTube and Contact.ChannelUsernames.FACEBOOK.Username for Facebook.
  • ContactNameInput—Adds First Name and Last Name fields.

  • CustomAllInput—Displays all contact custom fields on customer entry forms. You must specify the data table (Contact or Incident) for the custom fields you want to display. You can also add individual custom fields by deleting this widget and adding only the ones you want using the FormInput widget.

  • DateInput—Displays a date drop-down menu where customers can enter date information you have requested.

  • DisplayNameInput—Displays a field for community users to enter their display name.

  • EmailCheck—Validates a customer’s entered email address against the database and redirects them to the Create an Account page if the entered address is not in the database.

  • FileAttachmentUpload—Displays a field and Browse button where customers can enter or select files to attach to an incident.

  • FormInput—Displays a field that can be used to input system fields listed under Business Objects on the Customer Portal Administration site. You must add the name attribute to this widget.
    Note: The exceptions are Incident.FileAttachments, which is input with the FileAttachmentUpload widget, and Incident.Category and Incident.Product, which are input with the ProductCategoryInput widget.
  • FormSubmit—Generates the button on an input form that submits customer entries. On the reference implementation, labels for this button include Submit, Continue, Save Changes, and Create Account.

  • PasswordInput—Lets customers set a new password.

  • ProductCatalogInput—Displays product menus for customer selection on assets.

  • ProductCategoryInput—Displays product and category menus for customer selection on the ask a question pages.

  • RichTextInput—Displays a text field that allows HTML formatting tags.

  • SelectionInput—Functions like the FormInput widget for menu and yes/no fields.

  • SmartAssistantDialog—Displays a list of suggested answers and includes the Finish Submitting Question button for customers to submit the question they entered on the Ask a Question page.

  • SocialUserAvatar—Lets community users select an avatar to associate with their display name.

  • TextInput—Functions like the FormInput widget for text, text area, and integer fields.

Output widgets

There are widgets to display information on customer portal pages.

The following widgets display read-only fields on the customer portal.

  • ChannelAllDisplay—Displays Twitter, YouTube, and Facebook user names that were entered by customers.
    Note: You can also define output fields for single channels. Type <rn:widget path="output/FieldDisplay" name="Contact.ChannelUsernames.TWITTER.Username" /> to add the Twitter channel. Change the name attribute to Contact.ChannelUsernames.YOUTUBE.Username for YouTube and Contact.ChannelUsernames.FACEBOOK.Username for Facebook.
  • CustomAllDisplay—Displays the data entered into any of the contact or incident custom fields being displayed on the page. You can also add individual custom fields by deleting this widget and adding only the ones you want using the DataDisplay widget.

  • DataDisplay—Displays the label and value of the field defined by the name attribute in the widget code.

  • FieldDisplay—Displays the label and value of the field defined by the name attribute in the widget code. This widget cannot display File Attachment, Hiermenu, or Thread data types.

  • FileListDisplay—Displays file attachments for an incident or answer.

  • IncidentThreadDisplay—Displays all correspondence associated with an incident.

  • ProductCatalogDisplay—Displays the product associated with an asset.

  • ProductCategoryDisplay—Displays the product or category hierarchy associated with the answer, incident, or contact.

  • ProductCategoryImageDisplay—Displays an image for a specified product or category ID.

Defining field lengths

You can use the maximum_length and minimum_length attributes of the TextInput and RichTextInput widgets to restrict the number of characters entered in a text field.

Because the TextInput widget is contained in the FormInput widget, you can also add these attributes to the FormInput widget even though they aren’t listed as attributes of that widget.

Note: Many fields have a maximum field size defined in their database definitions, which you can view by clicking the field name on the Business Object page of the Customer Portal Administration site. If you set the maximum_length attribute of a TextInput or FormInput field to a value larger than the database maximum field size, the attribute value will be ignored. Setting the minimum_length attribute to a value greater than 0 automatically makes the field required.

Edit the widget code to add the maximum_length or minimum_length attribute to the widget, as shown in this example.

<rn:widget path="input/FormInput" name="Incident.Subject" required="true" maximum_length="200" />

Adding hints

You can add a hint to help customers complete a field that is created using the CustomAllInput, DateInput, FormInput, ProductCategoryInput, SelectionInput, or TextInput widget.

By default, field hints appears when the cursor is in the input field. To display the hint regardless of cursor location, set the always_show_hint attribute of the FormInput widget to true. To hide the hint, set the hide_hint attribute to true. If you add the hint attribute to a widget that calls a custom field, the customer portal hint overrides any hint that was defined for the field on the administration interface. The hide_hint attribute can be used with CustomAllInput and CustomAllDisplay widgets.

You can also define and display product and category selection hints by using the hint and always_show_hint attributes for the ProductCategoryInput widget.

Edit the widget code to add the hint attribute to the widget, as shown in this example.

<rn:widget path="input/FormInput" name="Contact.Login" required="true" validate_on_blur="true" label_input="#rn:msg:USERNAME_LBL#" hint="Enter a username or just use your email address" />

Depending on the length of your hints, you may want to consider editing your page to accommodate them. You can also edit the width of the hint box by changing the max-width definition in the CSS files for the DateInput, SelectionInput, and TextInput widgets.

As an example, the default base.css file for the TextInput widget uses this code:

.rn_TextInput .rn_HintBox {
    border:1px solid #DBDBDB;
    max-width:200px;
    padding:4px 16px 2px;
    word-wrap:break-word;
}
.rn_TextInput .rn_HintBox.rn_AlwaysVisibleHint {
     max-width:300px;
     opacity:1.0;
     z-index:0;
}

Displaying mask characters

You can use masks to define custom field formats.

Custom fields may have masks that define their format for correct data entry. For example, you might want to ensure that serial numbers have the correct sequence of letters, numbers, and formatting characters. The system phone number and postal code fields can be defined on the Countries editor of the administration interface to use masks as well.

On the reference implementation, the CustomAllInput, FormInput, and TextInput fields have an always_show_mask attribute that displays the expected (and allowable) input format to help the customer enter the value correctly. By default, the attribute is set to true.

To hide the mask, set the attribute to false as shown in this code.
<rn:widget path="input/CustomAllInput" table="Contact" always_show_mask="false"/>
Note: If you add a phone number or postal code input field to a page and set the always_show_mask attribute to true, you must also include the Country field on the page. Without a customer selection in the Country field, the phone number and postal codes fields have no way to be associated with the correct mask.

Requiring field validation

You can require field validation to verify customer data.

You may want your customers to validate a field entry by re-entering their information. For example, it’s not uncommon to require customers to add their email address a second time as a way of verifying it. Rather than placing a second FormInput widget on the page for the email address confirmation, you can add the require_validation attribute to the first widget. (The require_validation attribute is an attribute of the TextInput widget, which is contained in the FormInput widget. That’s why you can add the attribute to the FormInput widget even though it isn’t listed as one of the FormInput widget’s attributes.)

The following code is an example of its use on the Create an Account page.

<rn:widget path="input/FormInput" name="Contact.Emails.PRIMARY.Address" required="true" validate_on_blur="true" initial_focus="true" label_input="#rn:msg:EMAIL_ADDR_LBL#" require_validation="true" />

Custom fields input and output

Contact, incident, and answer custom fields can be input and displayed on the customer portal.

Custom fields are defined on the administration interface, and they can be defined as read-only (which means they can only be displayed as an output widget) or they can be marked Read/Write, meaning they can be used for both input and output fields. They can also be set to be required on the customer portal, and a hint can be added to the custom field to provide information to customers who are entering data in the field. When the custom field data type is integer, menu, text area, text field, yes/no, or opt-in, you can also set a default value that automatically populates the field.

These four elements of a custom field—hint, default value, customer portal read-only or read/write visibility, and whether it’s required—that are defined on the administration interface can be modified through attributes of the input widget used to display the custom field.

  • Hints—If you define the hint attribute of an input widget for a custom field, the hint attribute definition defined in the widget code will override whatever hint was defined on the administration interface.

  • Default value—If you define the default_value attribute of an input widget for a custom field, that attribute value will override whatever value was defined on the administration interface.

  • Visibility—Custom fields marked Read can be used with output widgets, but you will get a widget error message on the page if you try to use them with an input widget. Custom fields marked Read/Write can be used for both input and output widgets.

  • Required—If you set the required attribute of an input widget for a custom field to false in the widget code when the custom field is marked as required on the administration interface, you cannot override the requirement with Customer Portal code. If the custom field is not defined as required on the administration interface, you can require it on your customer portal if you set the required attribute of the input widget to true. In other words, the required widget attribute can only make a non-required field required, but it cannot make a required field not required.

Defining input field values

When a page containing an input widget opens, the input field is either blank or populated with a value, depending on how you defined it.

Customers can enter data in blank input fields, and they can override default values in fields that are already populated. (If you don’t want customers to change the value of a field, use one of the read-only output widgets instead of an input widget.)

There are multiple ways the value of an input widget can be set.

  • If the input widget is used with a custom field, the field’s default value may be set on the administration interface when the custom field is added.

  • The value can be defined using the default_value attribute of the input widget when you add the widget code to a page. In this case, the input field always contains the defined default value when the page opens. If the field is a custom field with a default value that was defined when it was created, the widget’s default_value attribute overrides the value set on the administration interface.

  • You can pass the input field’s value in the URL that opens the page. You might want to use this option if you have multiple ways to open a page. Here’s a simple example: Assume your organization sells printers and monitors. You have one web page just for printers and another for monitors, each with a link to the Ask a Question page on your customer portal. You want to populate the Product field to identify whether customers accessed the Ask a Question page from the printer page or the monitor page. You can define the product type in the page’s URL so that the Product field is populated correctly based on which link was clicked to open the page.

    If you pass a field’s value through the page URL when the field’s value was already defined with the input widget’s default_value attribute, the URL value overrides the widget attribute.

    You can also pass the default value of the input field through a POST parameter.

  • The customer enters a value for the field. This value overrides any other predefined value.

Populate the Subject field

This example populates the Subject field on the Ask a Question page.

Procedure
  1. Open /views/pages/ask.php.

  2. Locate the following lines of code. These lines are not sequential.

    Note: One FormInput field is defined for the condition when customers are not logged in, and the second is for logged-in customers.
        <rn:widget path="input/FormInput" name="Incident.Subject" required="true" />
        <rn:widget path="input/FormInput" name="Incident.Subject" required="true" initial_focus="true"/>

  3. Add the default_value attribute to the FormInput widget to define the value in the Subject field. Your code will resemble the following.

    <rn:widget path="input/FormInput" name="Incident.Subject" required="true" default_value="Product Registration" />
    <rn:widget path="input/FormInput" name="Incident.Subject" required="true" initial_focus="true" default_value="Product Registration"/>

  4. Save the file.

Populate default product and category values

This example populates the product and category fields on the Submit a Question page.

Procedure
  1. Open /views/pages/ask.php.

  2. Locate the following line of code.

     <rn:widget path="input/ProductCategoryInput" name="Incident.Product"/>

  3. Add the default_value attribute to the ProductCategoryInput widget to define the value for the product drop-down menu. Your code will resemble the following.

    <rn:widget path="input/ProductCategoryInput" name="Incident.Product" default_value="21,47" />

  4. Locate the following line of code.

    <rn:widget path="input/ProductCategoryInput" name="Incident.Category" />

  5. Add the default_value attribute to the widget to define the value for the category drop-down menu. Your code will resemble the following.

    <rn:widget path="input/ProductCategoryInput" name="Incident.Category"  default_value="98"/>

  6. Save the file.

Set a date/time value

You can set a value for a custom date or date/time field. (The standard date/time fields are read-only, so you cannot set values for those.)

The following example assumes you’ve added a custom Answer Needed By field to the Ask a Question page. If you want to set a default value for the field, add code that resembles the following to the Ask a Question page.

<rn:widget path="input/DateInput" name="Incident.CustomFields.c.answer_needed" default_value="1435920435"/>

The value can be generated using a UNIX date/time stamp converter.

You can also enter absolute and relative dates, which will be converted to a UNIX time stamp format using the PHP strtotime( ) function. Absolute dates must be entered using the English date format of dd/mm/yyyy. If, for example, you specify a default value of 3-7-2015, the date is July 3, 2015.

Any of the following values for the default_value attribute of a DateInput widget are valid, and more examples can be found in the PHP strtotime( ) documentation.

  • Now

  • 18-12-2015

  • December 18, 2015

  • Tomorrow

  • Today + 2 months

  • First day of next month

  • Next Wed + 4 days

If you want the value of a custom field to be populated automatically relative to the current date/time, use code that resembles the following when adding the custom field to the page.
<rn:widget path="input/DateInput" name="Incident.CustomFields.c.answer_needed" default_value="tomorrow" />

Set a Yes/No field

The SelectionInput widget is used to display Yes/No radio buttons for a custom field.

The following example assumes you’ve added a custom field to a page that asks if the person submitting the question is a current customer. It also assumes you want to set the default value of the widget to Yes. (To set it to No, set the default_value attribute to 0 or false.) Add code that resembles the following to the page.

<rn:widget path="input/SelectionInput" name="Contact.CustomFields.c.current_cust" default_value="1"/>

Alternately, you could set the value to true.

<rn:widget path="input/SelectionInput" name="Contact.CustomFields.c.current_cust" default_value="true"/>

If default_value is set to anything other than 1, 0, true, or false, neither selection appears.

Change radio buttons to a check box

You can change the default radio buttons to check boxes using the display_as_checkbox attribute.

If you’d prefer to display yes/no fields as a single check box instead of as radio buttons, simply add the display_as_checkbox attribute to the SelectionInput widget. When this attribute is set to true, the customer’s response is saved as Yes if the check box is selected and No if the check box is not selected. Your code will resemble the following.

<rn:widget path="input/SelectionInput" name="Contact.CustomFields.c.current_cust" display_as_checkbox="true" />

Set a menu option

You can populate menu options on a drop-down menu, by modifying the custom field source code.

To set a default option in a drop-down menu, you’ll use the FormInput widget and use the ID of the option. This example includes a menu custom field to define the urgency of the incident, and it sets the urgency to Normal.

To find the ID of a custom field option, open the page in source code view, search for the menu custom field, note the <option> tags, and find the value you want to set.

Add code that resembles the following to the page.

<rn:widget path="input/FormInput" name="Incident.CustomFields.c.urgency" default_value="1"/>

Populate the Subject field using a URL

You can define a default value for an input field in the URL that opens the page containing the field. If you define a field’s value in the URL that calls the page and if that default value is also defined in the code for the input widget, the value in the URL overrides the value specified in the widget code. The following example populates the Subject field on the Ask a Question page, defining the field with a value when the page is opened by clicking the navigation tab to distinguish it from when the page is opened through the sidebar link.

Procedure
  1. Open /views/templates/standard.php.

  2. Edit the navigation tab for the Ask a Question page.

    1. Locate the following line of code.

      <li><rn:widget path="navigation/NavigationTab" label_tab="#rn:msg:ASK_QUESTION_HDG#" link="/app/ask" pages="ask, ask_confirm"/></li>

    2. Edit the link attribute to use the URL to populate the Subject field. Your code will resemble the following.

      <li><rn:widget path="navigation/NavigationTab" label_tab="#rn:msg:ASK_QUESTION_HDG#" link="/app/ask/Incident.Subject/From the Navigation Tab" pages="ask, ask_confirm"/></li>

  3. Save the file.

    Although this example shows you how to populate a field with a URL within your customer portal, you’re more likely to populate an input field value to access the Ask a Question page from an external page.

Setting default values with POST parameters

You can use POST parameters from forms you create to populate those fields.

Similar to using URL parameters to populate contact and incident input fields, you can also use POST parameters to populate fields. As with URL parameters, the POST parameter must use the Table.Field format, for example, Incident.Subject.

Outputting field values with the Field page tag

You can output field values without labels or formatting by using the Field page tag.

When you don’t need a label or any special formatting, you might find it easier to use the Field page tag to output the value of the field. All you need to do is specify the table and field names just as you do when defining an output widget. For example, the following code is used on the ask_confirm.php page to display the customer’s incident number.

<a href="/app/#rn:config:CP_INCIDENT_RESPONSE_URL#/i_id/#rn:url_param_value:i_id##rn:session#">#<rn:field name="Incident.ReferenceNumber" /></a>.

Allow customer edits to input fields after PTA or open login

The allow_external_login_updates attribute lets you change input fields on the Account Settings page so customers can edit them. The following procedure assumes you want to let customers update their email address on the Account Settings page after logging in with PTA or open login.

Procedure
  1. Open /views/pages/account/profile.php.

  2. Locate the following line of code.

    <rn:widget path="input/FormInput" name="Contact.Emails.PRIMARY.Address" required="true" validate_on_blur="true" initial_focus="true" label_input="#rn:msg:EMAIL_ADDR_LBL#"/>

  3. Edit the code to add the allow_external_login_updates attribute. Your code will resemble the following.

    <rn:widget path="input/FormInput" name="Contact.Emails.PRIMARY.Address" required="true" validate_on_blur="true" initial_focus="true" label_input="#rn:msg:EMAIL_ADDR_LBL#" allow_external_login_updates="true" />

  4. Save the file.

Use a system attribute with the FormInput widget

You can add system attributes to standard data objects, such as answers, contacts, and incidents, and display them on your customer portal using the FormInput and DataDisplay widgets as well as the Field page tag.

This example adds a contact system attribute to the Ask a Question page. The system attribute is a yes/no field that asks customers if they have used a previous version of the product. The usedpreviousproducts attribute was defined on the Service Console.
Procedure
  1. Open /views/pages/ask.php.

  2. Locate the following line of code.

    <rn:widget path="input/FileAttachmentUpload"/>

  3. Add the following code just below the line you located in step 2.

    <rn:widget path="input/FormInput" name="Contact.CustomFields.CO.usedpreviousproducts" always_show_hint="true" hint="Have you used a previous version of this product?" />
    Note: It’s always good practice to include a hint when you ask customers to enter data into an object with a system attribute. Likewise, you will want to set the always_show_hint attribute to "true." This is especially true if your system attribute requires a regular expression with a specified format, such as a product registration number or a catalog number.

  4. Save the file.

Use a system attribute with the DataDisplay widget

You can add system attributes to standard data objects, such as answers, contacts, and incidents, and display them on your customer portal using the FormInput and DataDisplay widgets as well as the Field page tag.

This example adds a Product Registration section to the Account Overview page. The product_registration system attribute is a text field, and the date_registered attribute is a date field. Both were defined on the Service Console.
Procedure
  1. Open /views/pages/account/overview.php.

  2. Add the following code where you want it to appear on the page. This example places after the closing div for the Questions section.

    <div class="rn_Overview">
      <h2><a class="rn_Questions" href="/app/account/questions/list#rn:session#">Product Registration</a></h2>
        <div class="rn_Questions">
          <rn:widget path="output/DataDisplay" name="Contact.CustomFields.CO.product_registration" label="Registered Product"/>
          <rn:widget path="output/DataDisplay" name="Contact.CustomFields.c.date_registered" label="Date Registered"/>
        </div>

  3. Save the file.

Use system attributes with regular expressions

You can add system attributes to standard data objects, such as answers, contacts, and incidents, and display them on your customer portal using the FormInput and DataDisplay widgets as well as the Field page tag.

For the sake of this example, we’ll assume that you’ve added an RMA system attribute to incidents so that you can match the incident with your organization’s Return Merchandise Authorization process. We’ll also assume that you’ve defined the format of the RMA system attribute to use the pattern AA-#####, for example, CX-49935.
Procedure
  1. Open the page where you want to add the incident’s system attribute.

  2. Do one of the following:

    • Add the FormInput widget to the code so it appears where you want it to on the page. Your code will resemble the following.
      <rn:widget path="input/FormInput" name="Incident.CustomFields.CO.RMA" always_show_hint="true" hint="Expected Input: AA-##### (for example, CX-49935)" validate_on_blur="true" label_input="Returned Merchandise Authorization" />
      Note: If the regular expression (the AA-##### pattern) is not met, the validate_on_blur attribute indicates an error as soon as customers move to a different field. Without this attribute, the error is not pointed out until customers click the Continue button.
    • Add the hint directly to the field name. In that case, your code would resemble:
      <rn:widget path="input/FormInput" name="Incident.CustomFields.CO.RMA" label_name= validate_on_blur="true" label_input="RMA (expected input: AA-#####)" />

  3. Save the page.

Web form security

The Customer Portal includes web form security on the FormSubmit widget that automatically requires human validation when abuse is suspected.

Validation is accomplished through the use of a CAPTCHA, a dialog containing distorted words that the customer is asked to type. When the words are typed correctly, a human is assumed to be on the client side. Once customers have correctly entered a CAPTCHA, they will not be asked for verification again as long as the visit has not ended or does not exceed an hour.

You may also want to require CAPTCHAs to prevent user name enumeration, that is, the automatic harvesting of user names from your database.

By default, a CAPTCHA opens on the customer portal only when the system detects abuse, but you can configure a form to always require human validation. You can also configure a form to open a CAPTCHA wherever you want on the form instead of in a dialog, where it opens by default.

Note: CAPTCHAs are not used with pass-through authentication. Nor are they used on the basic page set. CAPTCHAs require JavaScript to display and the basic page set does not support JavaScript. Therefore, if an abuse situation is detected on your basic page set, customers will see a generic error message rather than a CAPTCHA.

Require a CAPTCHA validation on every submit

This example demonstrates setting a CAPTCHA validation for all form submittals.

Procedure
  1. Open the page containing the form where you want a CAPTCHA to always appear and locate the code for the FormSubmit widget.

  2. Edit the FormSubmit widget code to add the challenge_required attribute. Your edited code will resemble the following, where the attribute is used on the Create an Account page.

    <rn:widget path="input/FormSubmit" label_button="#rn:msg:CREATE_ACCT_CMD#" on_success_url="/app/account/overview" error_location="rn_ErrorLocation" challenge_required="true" />

  3. Save the page.

If you want to test a CAPTCHA on a page, you can temporarily set the challenge_required attribute to true, as shown in this example. When your testing is complete, you can remove the attribute from the widget code so that a CAPTCHA appears only when abuse is detected.

Open the CAPTCHA within a form instead of a dialog

This example code allows you to open the CAPTCHA within a form.

Procedure
  1. Open the page containing the form where you want the CAPTCHA to appear and locate the code for the FormSubmit widget.

  2. Edit the widget code to add the challenge_location attribute and set the attribute equal to the div ID for CaptchaArea.

    <rn:widget path="input/FormSubmit" label_button="#rn:msg:CONTINUE_ELLIPSIS_CMD#" on_success_url="/app/ask_confirm" challenge_required = "true" challenge_location = "captchaArea" error_location="rn_ErrorLocation"/>

  3. Add the following code below the line you edited in the previous step.

    <div id="captchaArea" class="rn_CaptchaDialog">

  4. Save the page.

Set the abuse detection cookie

An abuse scenario is hard to create deliberately for testing purposes, so the Customer Portal includes a cookie that makes your site behave as if it is under abuse when the cookie is set. It works only in development mode for testing purposes, so it does not affect customers on your production site.

Procedure
  1. To set the abuse detection cookie, do one of the following:

    • On your Customer Portal Administration site, click Set Environment > Trigger Abuse Detection.
    • On your development site, click the development header > Links and Resources > Toggle Abuse Detection.

Remove the ClickjackPrevention widget from the template

Clickjacking is an attack on browser security that can mislead your customers into clicking a concealed link. To prevent clickjacking, you must not allow your site to be put into an iFrame or frameset on another site. The new ClickjackPrevention widget, included by default on the standard, mobile, and basic templates, ensures that your customer portal cannot be viewed inside a frame. If your site must run in frames, remove the ClickJackPrevention widget.

Procedure
  1. Open customer/development/view/template/standard.php.

  2. Delete the following line of code.

    <rn:widget path="utils/ClickjackPrevention"/>

  3. Save the page.

Syndicated widgets

A syndicated widget lets you access the Oracle knowledge base using a customer portal widget that you add to a web page that is not part of your customer portal.

Syndicated widgets include the following.

  • ConditionalChatLink

  • KnowledgeSyndication

  • PollingSyndication

  • ProactiveChat

  • ProactiveSurveyLink

The syndicated widgets are generated with JavaScript code that can be placed within another web page. You can configure the widgets by modifying the JavaScript or by using the widget definition page to define the configuration options and settings.

The widgets can be completely styled with their CSS files, which are found in the /cp/customer/assets/css/syndicated_widgets/standard folder. You can select one of the syndicated widgets to review and modify its settings at https://<your_site>/ci/tags/syndicated_widgets.

KnowledgeSyndication widget

The KnowledgeSyndication widget functions like the search fields and reports on the Support Home and Published Answers pages of your customer portal, but you can place this widget on any page of your website rather than restricting it to customer portal pages. This lets your customers search the Oracle knowledge base from your organization’s home page, for example, instead of requiring them to go to your support site.

By default, the KnowledgeSyndication widget displays a search field, a list of answers from the knowledge base, and a link to additional results on the customer portal pages. This widget can be configured to display spelling corrections and suggestions, recommended documents, and other suggested searches. It can open an answer in a page overlay or on a new page. You can also edit labels and configure the number of displayed answers, whether to display a description of each answer and, if so, the length of the description.

Note: If you have enabled web indexing, the KnowledgeSyndication widget will also search external documents.

Add the KnowledgeSyndication widget to a web page

The widget information page gives you everything you need to add the KnowledgeSyndication widget to any page on your website. As you modify the attributes of the widget, the page displays a preview of the widget and modifies the widget code to reflect the changes you make. When you’re done, all you have to do is select and copy the code to your page to place the syndicated widget on it.
Procedure
  1. Type https://<your_site>/ci/tags/syndicated_widgets/standard/KnowledgeSyndication to open the page for the KnowledgeSyndication widget.

    Note: Your profile must have the CP Edit permission enabled, and you must log in to the Customer Portal Administration site if you are not already logged in.

  2. In the Configure Widget section, modify the widget attributes.

  3. To preview your changes, click Apply.

  4. Open the source code for the web page you want to add the widget to.

  5. Click the top Select Text button to select the code in the first box and copy the code.

  6. Paste the code into your page file just before the closing </body> tag. Even if you plan to use multiple syndicated widgets on the page, you need to paste this code only once.

  7. Click the second Select Text button and copy the code that defines the widget.

  8. Paste the copied code just below the code you copied in step 6.

  9. Add the following line to the page code wherever you want the widget to appear.

    <div_id="myDiv"></div>

  10. Save your web page.

Configure the KnowledgeSyndication widget

You can configure all attributes of the KnowledgeSyndication widget on the page.

Procedure
  1. To enable external document searching, select the check box for the ext_docs attribute.

    Note: In order to return external documents from a search, web indexing must first be enabled.

  2. To open answers in an overlay instead of a separate window, select the check box for the display_answers_in_overlay attribute.

    Note: If an answer has file attachments, they appear on the overlay, but answers that use guided assistance will not display the guide on the overlay.

  3. To define products for a KnowledgeSyndication widget report, type the product ID in the field for the p attribute.

  4. To define categories for a KnowledgeSyndication widget report, type the category ID in the field for the c attribute.

  5. To retain the product and category search filters, select the check box for the persist_prodcat attribute.

  6. To use context-sensitive information to determine what answers should be returned, type comma-separated HTML tags in the field for the context attribute.

  7. To define the number of characters that will be evaluated for each tag, type the number in the field for the payload_size attribute.

  8. To hide answers until a search is performed, select the check box for the hide_initial_answers attribute.

  9. To set a keyword for a search query, type the search word in the field for the q attribute.

    Note: 

    If you’ve entered HTML tags in the context attribute, any values in the q attribute will be overridden.

  10. To disable spelling corrections and suggestions, clear the check box for the correction attribute.

  11. To disable answer descriptions in the search results, clear the check box for the description attribute.

  12. To disable the More Results link, clear the check box for the navigation attribute.

  13. To disable recommended documents, clear the check box for the recommended attribute.

  14. To disable suggested searches, clear the check box for the related attribute.

  15. To disable the keyword search box to prevent customers from entering search terms, clear the check box for the search_box attribute.

  16. To edit the default spelling suggestion label of “Did You Mean,” type the new label in the field for the label_correction attribute.

    Note:  EU_SEARCH_TERM_FEEDBACK_ENABLE (RightNow User Interface/End-User Interface/General) must be set to Yes to display spelling suggestions. This setting is enabled by default so you shouldn’t have to edit it unless it has been disabled.

  17. To edit the label for recommended documents, type the new label in the field for the label_documents attribute.

  18. To edit the label for the More Results link, type the new label in the field for the label_more_results attribute.

  19. To edit the No Results Found label, type the new label in the field for the label_no_results attribute.

  20. To edit the related searches label, type the new label in the field for the label_related_searches attribute.

    Note: 

    EU_SUGGESTED_SEARCHES_ENABLE (RightNow User Interface/End-User Interface/General) must be set to Yes to display related searches. This setting is enabled by default so you shouldn’t have to edit it unless it has been disabled.

  21. To edit the Search button label, type the new label in the field for the label_search_button attribute.

  22. To edit the Created label, type the new label in the field for the label_created attribute.

  23. To edit the Updated label, type the new label in the field for the label_updated attribute.

  24. To change the target window that defines where linked documents and additional search results open, type one of the following target values for the HTML anchor (<a>) tag in the field for the widget’s target attribute.

    • _blank—Opens the link in a new window.

    • _self—Opens the link in the current window.

    • _parent—Opens the link in the parent frameset.

    • _top—Opens the link in the full window.

  25. To edit the length of answer descriptions from the default of 100 characters, type a numerical value in the field for the truncate_size attribute.

  26. To change the number of displayed answers from the default of ten, type an integer in the field for the number_answers attribute.

  27. To edit the div element, type a new name for the div element in the field for the div_id attribute.

  28. To edit the instance ID, replace the “0” in “skw_0” in the instance_id attribute with another value for each widget you add to the page.

  29. Click Apply to save your changes.

Find a product ID number

The ID numbers for products and categories are defined on the administration interface, so you’ll need to log in to find these values.

Procedure
  1. Open Products/Categories/Dispositions in Configuration > Service.

  2. Expand the products tree to display the product you want to select.

  3. Hover over the product name to display its ID.

    1. If the product is a sub-product, hover over the parent product to also get its ID.

  4. Type the full path of the product hierarchy into the p attribute field of the KnowledgeSyndication widget. The highest level product ID is listed first and the sub-product you selected is last in the comma-separated series.

Determining search results based on page information

The KnowledgeSyndication widget can “read” the content of the page and use context-sensitive information to determine what answers should be returned.

The KnowledgeSyndication widget evaluates a page for context sensitivity when you specify the HTML tags on the page. If you leave the field for this attribute blank, the KnowledgeSyndication widget will not use page content to determine what answers should be returned. You can also define the amount of content you want the widget to evaluate.

When you specify the page tags, the content within those tags is passed to the server for evaluating answers that are relevant to the page content. You might, for example, want to place the KnowledgeSyndication widget on your product pages so the specific product information from each page is used to return product-specific answers to your customers.

If you enter information in the context attribute’s field, the keyword for the search query defined in the q attribute is overridden. If the HTML tags you define are not found on the page, the widget defaults to the empty string, and top answers will be returned.

You can list any div ID, as well as title, document, and meta tags in the field for the context attribute. If you list a meta tag, only meta elements that are named description and keywords will be evaluated. If you use a document tag, the entire contents of the page will be evaluated.

The payload_size attribute of the KnowledgeSyndication widget defines the number of characters for each tag identified in the context attribute that will be sent to the server for evaluation to determine page content and influence context sensitivity of the returned answers. The default value is 150 characters (approximately 25 English words), and the maximum value is 300 characters.

Polling widgets

The polling widgets let you add a single-question poll from surveys that have been created on the agent desktop.

The Polling widget is located in the standard widgets folder in the surveys subfolder. The PollingSyndication widget can be found on the Customer Portal Administration site by clicking the Widgets tab and selecting Syndicated Widgets.

The available question types include choice, text, and matrix, and you can use any of these question types in your poll, although the choice question type probably offers the most usefulness to your organization. When customers answer a choice question by selecting a menu item, option, check box, or list item, they see a chart displaying the responses to date. (This chart can be a horizontal bar chart, vertical bar chart, or pie chart.) When customers respond to text and matrix questions, they see a thank-you message.

If the survey you have associated with the polling widget contains multiple questions, one of the questions will be selected at random to appear to customers for a one-hour time period. Every customer who is offered the poll during that time sees the same question. At the end of an hour, a new question is selected at random.

Polling widget attributes

The following attributes are available for the standard Polling widget and the PollingSyndication widget.

The question, answers, and some styling options are defined on the agent desktop when surveys and associated questions are created. Additional styling and other attributes are defined with customer portal code. If widget styling attributes are different than the styling defined when the survey was created, the widget attributes are used.

  • Chart Style—Sets the styling for the chart using the YUI Charts Control. You can specify backgrounds, borders, colors, fonts, and many other chart attributes. The default is blank.

  • Chart Type—Specifies the chart type. Options include none, horizontal bar, vertical bar, pie chart, and simple. The default is a horizontal bar chart.

  • Cookie Duration—Defines the number of days until the cookie expires. The default is ten days.

  • Instance ID—Defines the ID for the widget instance. You can specify this value, or it will be selected automatically.

  • Frequency—Defines what percentage of visitors are offered the poll. This attribute is used only when modal polls are enabled.

  • Modal—Sets the survey dialog to be modal. This mode requires customer interaction to close the dialog. By default, the modal poll is disabled.

  • Poll Logic—Prevents the survey dialog from opening unless the evt_showPoll event is fired. This attribute is used only when modal polls are enabled. You must add code to define the condition that triggers the event.

  • Seconds—Used only with modal polls to specify the time in seconds until the dialog is opened. The default value is 0.

  • Series Style—Sets the styling for the chart’s bars or pie wedges with the YUI Charts Control.

  • Survey ID—Required to identify the polling survey the widget uses.

  • Test—Puts the widget in test mode so results are not recorded.

Add the Polling widget to a customer portal page

You configure the Polling widget by placing widget code on the customer portal page where you want it to appear and then editing its attributes.

Procedure
  1. Open the file for the page on which you want to place the Polling widget.

  2. Type the code for the Polling widget in the location where you want the widget to appear on the page. The most basic widget code is as follows, where the value of the survey_id attribute is the ID of the survey containing the polling question you want to use.

        <rn:widget path="surveys/Polling" survey_id="8" />
    Every Polling widget must include a value for the survey_id attribute. If it does not, an error message appears on the customer portal page.

  3. Save the file.

Add the PollingSyndication widget to an external page

The following procedure describes the general process for adding a widget to a page.

Procedure
  1. Type https://<your_site>/ci/tags/syndicated_widgets/standard/PollingSyndication to open the page for the PollingSyndication widget.

  2. In the Configure Widget section, edit the widget attributes.

    Caution: Every PollingSyndication widget must include a value for the survey_id attribute. If you do not enter one, code is not generated for the widget.

  3. To preview your changes, click Apply

  4. Continue to configure the widget until you are satisfied with the result.

  5. Open the source code for the web page you want to add the widget to.

  6. Click Select Text and copy the code.

  7. Paste the code into your page file just before the closing </body> tag. Even if you plan to use multiple syndicated widgets on the page, you need to paste this code only once.

  8. Click the second Select Text and copy the code that defines the widget.

  9. Paste the copied code just below the code you pasted in previous steps.

  10. Click the third Select Text, copy the code, and paste it where you want the widget to appear.

  11. Save your web page.

Add the survey ID to a widget

Every polling widget must be associated with a polling survey that was designed on the Service Console. If the survey ID is missing from the Polling widget code, you will see an error on the page where you are trying to place the widget. If it is missing from the PollingSyndication widget, you will not be able to generate code to paste on an external page.

Procedure
  1. Click Surveys.

  2. Double-click Surveys Explorer.

  3. Click Choose Details.

  4. Select the check box for ID.

  5. Click OK.

  6. Add the survey_id attribute to the widget code so it resembles the following.

    <rn:widget path="surveys/Polling" survey_id="5" />
    1. To add the survey ID to a page with the PollingSyndication widget, open the page, scroll to the Configure Widget section of the page, find the attribute called survey_id, and type the ID number of the survey you want to use in the text field.

Define the cookie duration for a widget

You can define the life of the cookie, which is ten days by default, or you can prevent a cookie from being set.

After a customer has answered the poll, a cookie is set to prevent the survey from being offered again when the customer visits the page in the future.

With modal polls (that is, when the poll opens in a separate dialog instead of as an element on the page), the survey is not presented again after the customer has responded once, even if the randomization process now presents a different question to customers. In the non-modal mode after a customer has answered the poll, subsequent visits to the site when the cookie is active will display only the survey results instead of the survey question that appeared on the first visit.

Procedure
  1. Add the cookie_duration attribute to the widget code.

  2. Set the attribute value for the number of days you want the cookie to remain active. Your code will resemble the following.

    <rn:widget path="surveys/Polling" survey_id="5" cookie_duration="5"/>

  3. To define the cookie duration for the PollingSyndication widget, open the page with the PollingSyndication widget, scroll to the Configure Widget section of the page, find the attribute called cookie_duration, and type the number of days you want the cookie to remain active in the text field.

Enabling and configuring modal polls

You can define the poll to be modal so customers must deliberately close the window to reactivate the page they were on.

By default, the poll is not modal, but is instead an element on the page that customers can choose to respond to or ignore. The survey dialog remains in the middle of the page even if scrolling occurs.

Other attributes influence the behavior of the polling widgets when modal polls are enabled. The following attributes apply only to modal polls.

  • Frequency—You can define what percentage of visitors to your site will be offered the poll.

  • Poll logic—If you enable this attribute, the survey dialog does not appear unless the JavaScript event evt_showPoll is triggered. You must add code to define the condition that triggers the event.

  • Seconds—This attribute defines the number of seconds before the survey dialog opens on the page.

Enable and configure modal polls for the Polling widget

This procedure demonstrates enabling and configuring the polling widget for modal polls.

Procedure
  1. Add the modal attribute to the widget code, which will resemble the following.

    <rn:widget path="surveys/Polling" survey_id="5" modal="true" />

  2. To offer the poll to only a percentage of your customers instead of all of them, add the frequency attribute to the widget code. Your code will resemble the following.

    <rn:widget path="surveys/Polling" survey_id="5" modal="true" frequency="50"/>

  3. To trigger the dialog on the event defined in evt_showPoll, add the poll_logic attribute to the widget code. Your code will resemble the following.

    <rn:widget path="surveys/Polling" survey_id="5" modal="true" poll_logic="true"/>

  4. To trigger the dialog after the page has been open a specified number of seconds, add the seconds dialog to the widget code. Your code will resemble the following.

    <rn:widget path="surveys/Polling" survey_id="5" modal="true" seconds="3" />

Enable and configure modal polls for the PollingSyndication widget

This procedure demonstrates enabling and configuring the PollingSyndication widget for modal polls.

Procedure
  1. With the page for the PollingSyndication widget open, scroll to the Configure Widget section of the page, find the attribute called modal, and select the check box.

  2. To offer the poll to only a percentage of your customers instead of all of them, find the attribute called frequency and enter a percentage value in the field.

  3. To trigger the dialog on the event defined in evt_showPoll, find the attribute called poll_logic, and select the check box.

  4. To trigger the dialog after the page has been open a specified number of seconds, find the attribute called seconds and type the number of seconds in the text field.

Use poll logic with widgets

A JavaScript event, evt_showPoll, lets you use logic to display the polling widget when modal polls are enabled. When the poll_logic attribute is set to true, the polling dialog does not display unless the evt_showPoll event is triggered.

Procedure
  1. Add the poll_logic attribute to the widget code. Your code will resemble the following.

    <rn:widget path="surveys/Polling" survey_id="4" modal="true" poll_logic="true" />

  2. Then add code to trigger the evt_showPoll event. If, for example, you want to trigger the poll after customers click a link on the widget, you could add the following code to the page containing the widget. (Notice that the widget code prevents cookies from being set so the link will remain active.)

    <rn:widget path="surveys/Polling" survey_id="4" modal="true" poll_logic="true" cookie_duration="0" />
        <script type="text/javascript">
            function pollLogic() {
                RightNow.Event.fire('evt_showPoll');
            }
        </script>
        <a href="#" onclick="pollLogic()"><h2>Help us serve you better by taking this poll.</h2></a>

  3. To add the poll to the PollingSyndication widget, add the logic code to the external page below the code you added for the PollingSyndication widget. The following example shows the code you might add if you want to display the poll 500 milliseconds after the page opens.

    <script type="text/javascript">
    var rnTimer;
    startCheck();
    
    // check to see when the RightNow javascript is loaded and ready to use
    function startCheck()
    {
         rnTimer = setInterval(checkLoaded, 500); // this is milliseconds
    }
    
    // when loaded fire the poll
    function checkLoaded()
    {
         if (RightNow && RightNow.Client && RightNow.Client.Event && RightNow.Client.Event.evt_showPoll)
         {
           clearInterval(rnTimer);
           RightNow.Client.Event.evt_showPoll.fire();
         }
    }
    </script>

Edit the chart type on polling widgets

When the polling widget uses a survey with a choice type question, the page displays a chart with the results of the poll. By default, a horizontal bar chart is used, but you can change that to a vertical bar chart, pie chart, or simple chart instead. You can also select None if you do not want to display the results in a chart.

The simple chart type is styled with the widget’s CSS file. If you define attributes for the widget in the code on the page where it appears, they are not applied to the widget.
Procedure
  1. To display a vertical bar chart, add the chart_type attribute to the widget code and set its value to vertical_bar. Your code will resemble the following.

    <rn:widget path="surveys/Polling" survey_id="5" chart_type="vertical_bar" />

  2. To display a pie chart, add the chart_type attribute to the widget code and set its value to pie. Your code will resemble the following.

    <rn:widget path="surveys/Polling" survey_id="5" chart_type="pie" />

  3. To edit the chart type on the PollingSyndicated widget:

    1. Open the page for the PollingSyndication widget

    2. Scroll to the Configure Widget section of the page

    3. Find the attribute called chart_type

    4. Select vertical_bar, pie or simple to change the chart from the default horizontal_bar option

Instance ID

The instance_id is used as a unique identifier of the polling widget. Each instance of a polling widget on a customer portal page or an external page must have its own instance ID.

You can enter a value for instance_id in the Polling widget code or type a value in the field for the PollingSyndication widget. If you do not enter a value, one will be assigned automatically.

Set the test mode for polling widgets

When the test mode is enabled, you can test the polling widgets without worrying that your sample poll selections will skew actual customer results. No statistics are collected in test mode.

Procedure
  1. Add the test attribute to the widget code and set it to true. Your code will resemble the following.

    <rn:widget path="surveys/Polling" survey_id="5" test="true" />

  2. To set the test mode for the PollingSyndication widget:

    1. Open the PollingSyndication widget page

    2. Scroll to the Configure Widget section of the page

    3. Find the attribute called test

    4. Select the check box

Add the SurveyLink widget to a page

You can add a link to any customer portal page that opens broadcast and website link types of surveys.

Procedure

  1. Open the customer portal page that you want to add the SurveyLink widget to.

  2. Add the following code in the location on the page where you want the widget to display, defining the survey_id attribute with the ID value of the survey you want to use.

    <rn:widget path="surveys/SurveyLink" survey_id="11"/>

  3. To use a graphic element instead of the text link to the survey, add the icon_path attribute to the widget so that your code resembles the following.

    <rn:widget path="surveys/SurveyLink" survey_id="11" icon_path="images/cp_survey_icon.png" />
    Note: When you use the icon_path attribute, the default label that is read by screen readers is “Follow this link to take a survey.” If you want to change this label, add the label_icon_alt attribute and set the value to whatever you want the screen reader to read.

  4. To open the survey in a separate window instead of on the same page, add the target attribute to the widget code and set it to _blank.

    <rn:widget path="surveys/SurveyLink" survey_id="11" target="_blank" />

  5. To change “Survey Link” to different text, add the link_text attribute to the widget.

    <rn:widget path="surveys/SurveyLink" survey_id="11" link_text="Click here to take our survey" />

  6. Save the file.

Add the ProactiveSurveyLink widget to a page

Place the ProactiveSurveyLink widget on any customer portal page. You can offer a survey when your customers have been on a page for a defined number of seconds or when an event that you have defined occurs.

Procedure
  1. Open the customer portal page that you want to add the ProactiveSurveyLink widget to.

  2. Add the following code to the page.

    <rn:widget path="surveys/ProactiveSurveyLink" survey_id="11"/>

  3. To change the labels on the Accept and Cancel buttons, add the label_accept_button and label_cancel_button attributes. Your code will resemble the following.

    <rn:widget path="surveys/ProactiveSurveyLink" survey_id="11" label_accept_button="Yes please" label_cancel_button="No thanks" />

  4. To open the survey in a separate window instead of on the same page, add the target attribute to the widget code and set it to _blank.

    <rn:widget path="surveys/ProactiveSurveyLink" survey_id="11" target="_blank" />

  5. To set the cookie duration to anything other than the default value of ten days, add the cookie_duration attribute and set it to the number of days you want to avoid presenting the survey offer again. If you set the value to 0, no cookie is set.

    <rn:widget path="surveys/ProactiveSurveyLink" survey_id="11" cookie_duration="0"/>

  6. To change the width of the window that opens when the link is clicked from its default value of 300 pixels, add the dialog_width attribute and set it to the value you want.

    <rn:widget path="surveys/ProactiveSurveyLink" survey_id="11" dialog_width="200" />

  7. To define a percentage of visitors who will be offered the survey (instead of the default value of 100), add the frequency attribute and set it the value you choose.

    <rn:widget path="surveys/ProactiveSurveyLink" survey_id="11" frequency="50" />

  8. To change the default invitation to participate in the survey, add the intro_paragraph attribute with the text of your choice.

    <rn:widget path="surveys/ProactiveSurveyLink" survey_id="11" intro_paragraph="Complete this survey and be entered in a drawing to win an iPad!" />

  9. To open the window after a specified number of seconds, add the seconds attribute.

    <rn:widget path="surveys/ProactiveSurveyLink" survey_id="11" seconds="10" />

  10. To change the survey title from the default “Survey Invitation,” add the title attribute.

    <rn:widget path="surveys/ProactiveSurveyLink" survey_id="11" title="Tell us what you're thinking" />

  11. To open the widget only when an event is fired, add the wait_for_event attribute to the widget and then add the code to fire the event. Your code will resemble the following. (Notice that the widget code prevents cookies from being set so the link will remain active.)

    <rn:widget path="surveys/ProactiveSurveyLink" survey_id="11" wait_for_event="true" cookie_duration="0" /> 
    <script type="text/javascript"> 
    function dialogLogic() 
            { 
                RightNow.Event.fire('evt_showOffer'); 
            } 
            </script> 
            <a href="#" onclick="dialogLogic()"><h2>Help us serve you better by taking this survey.</h2></a>
    Note: A JavaScript event, evt_showOffer, lets you use logic to display the ProactiveSurveyLink widget. You must add code to fire evt_showOffer in order for the widget to open. If you have defined the seconds attribute, the widget opens after the event has fired and the number of seconds has elapsed.

  12. Save the page.

Add the syndicated ProactiveSurveyLink widget to a web page

The syndicated ProactiveSurveyLink widget performs the same function as the standard ProactiveSurveyLink widget but on an external page rather than a customer portal page. The code for the syndicated ProactiveSurveyLink widget is generated on the Customer Portal Administration site, so you must copy the code and then paste it into the code for the external page.

Procedure
  1. Type https://<your_site>/ci/tags/syndicated_widgets/standard/ProactiveSurveyLink to open the page for the syndicated ProactiveSurveyLink widget.

  2. Scroll to the Configure Widget section and edit the widget attributes.

  3. To preview your changes, click Apply.

  4. Open the source code of the external page you want to add the widget to.

  5. To ensure the page renders correctly in Internet Explorer 7, add the following code to the top of the page before your first HTML tag.

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

  6. On the right side of the widget page, click the top Select Text and copy the code.

  7. Paste the code into your page file just before the closing </body> tag. Even if you plan to use multiple syndicated widgets on the page, you need to paste this code only once.

  8. Click the second Select Text and copy the code that defines the widget.

  9. Paste the copied code just below the code you pasted earlier.

  10. Click the third Select Text button, copy the code, and paste it where you want the widget to appear on the page.

  11. Save your web page.

Configure the syndicated ProactiveSurveyLink widget

You can customize the ProactiveSurveyLink widget.

Procedure
  1. With the page for the syndicated ProactiveSurveyLink widget page open, scroll to the Configure Widget section of the page, find the attribute called survey_id, and type the ID number of the survey you want to use in the text field.

  2. To set the cookie duration to anything other than the default value of ten days, type the number of days you want to avoid presenting the survey offer again in the cookie_duration attribute. If you set the value to 0, no cookie is set.

  3. To change the width of the window that opens when the link is clicked from its default value of 300 pixels, type the new value in the dialog_width attribute.

  4. To open the widget only when an event is fired, select the Enabled check box for the display_logic attribute.

    Note: A JavaScript event, evt_showLink, lets you use logic to display the syndicated ProactiveSurveyLink widget. You must add code to fire evt_showLink in order for the widget to open. If you have defined the seconds attribute, the widget opens after the event has fired and the number of seconds has elapsed.

  5. Add the following code just below the widget code on the page where you’re placing the widget.

    <script type="text/javascript"> 
        function dialogLogic() 
        { 
            RightNow.Client.Event.evt_showLink.fire();
        } 
    </script> 
    <a href="#" onclick="dialogLogic()"><h2>Help us serve you better by taking this survey.</h2></a>

  6. To change the div_id attribute from its default of myDiv, type a new name for the div in the field.

  7. To define a percentage of visitors who will be offered the survey (instead of the default value of 100), set the percentage value you want in the frequency attribute.

  8. To rename the instance_id attribute, replace the “0” in “psl_0” with another value.

  9. To change the default invitation to participate in the survey, type text for the new introduction in the intro_paragraph attribute.

  10. To change the labels on the Accept and Cancel buttons, type new values for the label_accept_button and label_cancel_button attributes.

  11. To open the survey link window after a specified number of seconds, type the value in the seconds attribute. The default value of 0 means the window opens immediately.

  12. To open the survey in a separate window instead of on the same page, click the drop-down arrow for the target attribute and select “_blank.”

  13. To change the survey title from the default “Survey Invitation,” type the new title in the title attribute.

Standard widgets

The following table lists all the widgets included in both the standard and mobile customer portal reference implementations, the pages on which they are used, and their functionality on the page.

Click here for a list of standard widgets that are not used in the reference implementation pages or templates.

Table Standard Widgets and Their Functionality on the Reference Implementation

Widget Page Widget functionality on the page
AccountDropdown templates/standard Displays a drop-down menu of account options to logged-in users and a login link to users who are not logged in.
templates/mobile
ActivityCharts social/moderate/overview Displays counts for recent new community discussions and users on the Moderation Overview page.
AnnouncementText social/moderate/overview Displays an announcement to community moderators.
AnswerFeedback answers/detail Displays the Was This Answer Helpful? section of the page, including the Yes/No buttons, and feedback dialog.
mobile/answers/detail
AnswerNotificationIcon answers/detail Displays the Notify Me link on the answer details page.
AnswerNotificationManager account/notif/list Opens the list of answers to which a customer is subscribed and displays the Renew and Delete buttons.
AvatarDisplay account/profile Displays a community user’s avatar.
public_profile
public_profile_update
mobile/account/profile
mobile/public_profile
BasicAnswerFeedback basic/answers/detail Displays the Was This Answer Helpful? section of the page, including the Yes/No buttons, and the Submit Feedback button.
BasicCustomAllInput basic/ask Displays input fields for incident custom fields.
basic/account/profile Displays input fields for contact custom fields.
basic/utils/create_account Displays input fields for contact custom fields.
BasicDisplaySearchFilters basic/account/questions/list Displays the search filters that were used to restrict a search by products, categories, or both.
basic/answers/list
BasicEmailCredentials basic/utils/account_assistance Displays the fields and buttons for customers to enter their email address or user name and request to have their user name emailed to them or have their password reset.
BasicFormInput basic/ask Displays the Email Address, Subject, and Question fields.
basic/account/change_password Displays the Current Password, Password, and Verify Password fields.
basic/account/profile Displays the Username, First Name, Last Name, Email Address, Street, City, Country, State/Province, Postal Code, and phone number fields.
basic/account/questions/detail Displays the field for adding information to a question being updated and the Do You Want a Response? field and menu.
basic/answers/submit_feedback Displays the Email Address and Feedback fields for submitting feedback on an answer.
basic/utils/create_account Displays the Email Address, Username, Password, Verify Password, First Name, and Last Name fields.
BasicFormStatusDisplay basic/ask Displays status and error messages from form submissions on the basic page set.
basic/account/change_password
basic/utils/create_account
basic/account/profile
basic/account/reset_password
basic/account/setup_password
basic/account/questions/detail
basic/answers/detail
basic/answers/submit_feedback
basic/utils/account_assistance
BasicFormSubmit basic/ask Displays the Submit button.
basic/account/change_password
basic/account/profile
basic/account/questions/detail
basic/answers/submit_feedback
basic/utils/create_account Displays the Create Account button.
BasicKeywordSearch basic/home Displays the Search field.
basic/account/questions/list
basic/answers/list
BasicLoginForm basic/utils/login_form Displays the Username and Password fields and the Log In button.
BasicLogoutLink templates/basic Displays the link to log users out.
BasicMultiline basic/account/overview Displays the customer’s incidents in the Questions section.
basic/account/questions/list Displays the customer’s incidents, filtered by product or category if selected.
basic/answers/list Displays the list of answers that meet customer-entered search terms.
BasicPaginator basic/account/questions/list Displays a list of page numbers that customers can select when the length of a report exceeds what can be displayed on a single page.
basic/answers/list
BasicProductCategoryInput basic/ask Lets customers select a product and category when they submit a question.
BasicProductCategorySearchFilter basic/account/questions/list Displays the Limit by Product and Limit by Category search filters.
basic/answers/list
BasicResetPassword basic/reset_password Displays the Password and Verify Password fields and the Submit button. This widget is accessed only through a link in an email sent to the customer.
basic/account/setup_password
BasicResultInfo basic/account/questions/list Displays the number of matching answers displayed in the search results.
basic/answers/list
BestAnswerDisplay social/questions/detail Displays the best answers selected by the original author and a community moderator.
mobile/social/questions/detail
BrowserSearchPlugin templates/standard Provides a link that can be output to a browser search engine plug-in.
ChatAgentStatus chat/chat_landing Displays the status of the chat agent (absent, listening, or responding).
mobile/chataccount/chat_landing
ChatAttachFileButton chat/chat_landing Displays the Attach File button.
ChatCancelButton chat/chat_landing Displays the Leave button.
mobile/chat/chat_landing
ChatDisconnectButton chat/chat_landing Displays the Disconnect button.
mobile/chat/chat_landing
ChatEngagementStatus chat/chat_landing Displays the status of the chat session.
mobile/chat/chat_landing
ChatHours chat/chat_launch Lists the chat hours defined on the administration interface and the current date and time.
mobile/chat/chat_launch
ChatLaunchButton chat/chat_launch Displays the Submit Request button.
mobile/chat/chat_launch
ChatOffTheRecordButton chat/chat_landing Displays the Chat Off the Record button.
mobile/chat/chat_landing
ChatOffTheRecordDialog chat/chat_landing Opens the dialog for sending an off-the-record message when the Chat Off the Record button is clicked.
mobile/chat/chat_landing
ChatPostMessage chat/chat_landing Displays the area where customers enter chat messages.
mobile/chat/chat_landing
ChatPrintButton chat/chat_landing Displays the Print button for printing the chat transcript.
mobile/chat/chat_landing
ChatQueueSearch chat/chat_landing Adds a Search button and field where customers can search for an answer while waiting for a chat session.
mobile/chat/chat_landing
ChatQueueWaitTime chat/chat_landing Displays a message to let customers know their position in the chat session queue, the estimated wait time, the average wait time, or all three.
mobile/chat/chat_landing
ChatRequestEmailResponseButton chat/chat_landing Displays the Request Email Response button that appears when no agents are available.
mobile/chat/chat_landing
ChatSendButton chat/chat_landing Displays the Send button that submits customer chat messages.
mobile/chat/chat_landing
ChatServerConnect chat/chat_landing Displays the message customers see while the chat connection is being established and when other events occur during the chat session.
mobile/chat/chat_landing
ChatSoundButton chat/chat_landing Produces an audible signal to indicate when customers are connected to an agent and when agents post a response. Customers can turn the audio on or off.
mobile/chat/chat_landing
ChatStatus chat/chat_launch Displays a message to let customers know if chat sessions are currently available.
mobile/chat/chat_launch
ChatTranscript chat/chat_landing Contains a record of the customer and agent messages that comprise the chat session.
mobile/chat/chat_landing
ContactUs answers/detail Displays options for contact, including asking a question to support staff and community, chatting with an agent, and providing site feedback.
answers/list
results
social/questions/detail
social/questions/list
CustomAllDisplay account/questions/detail Displays the read-only incident custom fields in the Additional Details section.
basic/account/questions/detail
mobile/account/questions/detail
CustomAllInput chat/chat_launch Displays input fields for incident custom fields with chat visibility.
mobile/chat/chat_launch
utils/create_account Displays input fields for contact custom fields.
mobile/utils/create_account
DataDisplay account/questions/detail Displays the following read-only incident fields: incident thread, customer’s email address, reference number for the incident, incident status, the dates the incident was created and last updated, the product and category associated with the incident, and file attachments.
answers/detail Displays an answer’s file attachments with links to the files.
basic/account/questions/detail Displays the following read-only incident fields: incident thread, customer’s email address, reference number for the incident, incident status, the dates the incident was created and last updated, the product and category associated with the incident, and file attachments.
basic/answers/detail Displays an answer’s file attachments with links to the files.
mobile/account/questions/detail Displays the following read-only incident fields: incident thread, customer’s email address, reference number for the incident, incident status, the dates the incident was created and last updated, the product and category associated with the incident, and file attachments.
mobile/answers/detail Displays an answer’s file attachments with links to the files.
DiscussionAuthorSubscription social/ask Allows authors of questions to subscribe to be notified by email when comments are posted to their questions.
mobile/social/ask
DiscussionSubscriptionIcon products/detail Allows community users to subscribe or unsubscribe to products or categories and social discussions.
social/questions/detail
DiscussionSubscriptionManager account/notif/list Displays discussions a community user is subscribed to.
DisplayNameInput account/profile Displays the field for entering a community user’s display name.
public_profile_update
utils/create_account
mobile/account/profile
mobile/utils/create_account
DisplaySearchSourceFilters social/questions/list Displays the search filters applied to the search results.
EmailAnswerLink answers/detail Displays the Email This Page link.
social/questions/detail
EmailCredentials mobile/utils/account_assistance Displays the fields and buttons for customers to enter their email address or user name and request to have their user name emailed to them or have their password reset.
utils/account_assistance
FileAttachmentUpload account/questions/detail Displays the field and Browse button for attaching additional documents to a question being updated.
ask Displays the field and Browse button for attaching documents to a question being asked.
mobile/account/questions/detail Displays the field and Browse button for attaching additional documents to a question being updated.
mobile/ask Displays the field and Browse button for attaching documents to a question being asked.
FormInput account/profile Displays the user name, email address, street, city, country, state, postal code, and phone number fields.
account/questions/detail Displays the field for adding information to a question being updated and the Do You Want a Response? field and menu.
ask Displays the Email Address, Subject, and Question fields.
chat/chat_launch Displays the Email Address field.
mobile/account/profile Displays the user name, email address, street, city, country, state, postal code, and phone number fields.
mobile/account/questions/detail Displays the field for adding information to a question being updated and the Do You Want a Response? field and menu.
mobile/ask Displays the Email Address, Subject, and Question fields.
mobile/chat/chat_launch Displays the Email Address field.
mobile/social/ask Displays the Email Address, Subject, and Question fields.
mobile/utils/create_account Displays the Email Address, Username, Password, and Verify Password fields.
social/ask Displays the Email Address, Subject, and Question fields.
utils/create_account Displays the Email Address, Username, Password, and Verify Password fields.
FormSubmit account/change_password Displays the Submit button.
account/profile Displays the Save Changes button.
account/profile_picture Displays the Save Changes button.
account/questions/detail Displays the Submit button.
ask Displays the Continue button.
mobile/account/change_password Displays the Submit button.
mobile/account/profile Displays the Save Changes button.
mobile/account/profile_picture Displays the Save Changes button.
mobile/account/questions/detail Displays the Submit button.
mobile/ask Displays the Continue button.
mobile/social/ask Displays the Post Your Question button.
mobile/utils/create_account Displays the Create Account button.
public_profile_update Displays the Save Changes button.
social/ask Displays the Post Your Question button.
utils/create_account Displays the Create Account button.
Grid account/overview Displays reports of recently submitted questions, recent answer notifications, and service contracts.
account/questions/list Displays the Support History report.
GuidedAssistant agent/guided_assistant Opens a preview of the guide on the administration interface.
answers/detail Opens the first question of the guide associated with the answer.
mobile/answers/detail Displays the Launch the Troubleshooter button.
mobile/utils/guided_assistant Opens the first question of the guide associated with the answer.
KeywordText account/questions/list Displays the search field.
answers/list
mobile/account/questions/list
mobile/answers/list
LoginForm mobile/utils/login_form Displays the Username and Password fields and the Log In button.
utils/login_form
MobileMultiline mobile/account/questions/list Displays the list of customer’s incidents.
mobile/answers/list Opens a list of answers when See All Popular Answers is clicked on the home page.
MobileProductCategoryInput mobile/ask Displays the Select a Product or Select a Category button and the associated menus.
mobile/social/ask
MobileProductCategoryList basic/home Displays the list of Featured Support Categories.
MobileProductCategorySearchFilter mobile/account/questions/list Displays the product and category search filters.
mobile/answers/list
MobileSourceProductCategorySearchFilter social/questions/list Displays the search filters applied to the search results.
ModerationAction social/moderate/comment Displays the actions allowed on the moderation report based on the permissions assigned to the moderator.
social/moderate/question
social/moderate/user
ModerationFilterBreadcrumbs social/moderate/comment Displays the filters that have been applied to the moderation report.
social/moderate/question
moderate/user
ModerationFilterDialog social/moderate/comment Displays the available moderation filters options of updated date, status, and product or category.
social/moderate/question
social/moderate/user
ModerationGrid social/moderate/comment Displays moderation data in a grid.
social/moderate/question
social/moderate/user
ModerationInlineAction mobile/public_profile Displays a drop-down menu of moderation actions available for performing inline moderation.
public_profile
ModerationProfile public_profile Allows moderators to view user name and email information on the public profile page.
ModerationSummaryTable social/moderate/overview Displays the report of suspended, active, archived, and total questions, comments, and users on the Moderation Overview page.
Multiline answers/list Displays the list of answers that meet customer-entered search terms.
NavigationTab templates/standard Displays the Support Home and Ask a Question navigation tabs.
templates/mobile
OpenLogin mobile/utils/create_account Displays the third-party sites that can authenticate customers, allowing them to be logged in to the customer portal. The default providers include Facebook, Twitter, Google, Yahoo, and any valid OpenID provider.
mobile/utils/login_form
utils/create_account
utils/login_form
OracleLogo chat/chat_landing Displays the Oracle logo.
mobile/chat/chat_landing
templates/standard
templates/mobile
PageSetSelector templates/basic Displays the option for selecting the desktop, mobile, or basic page set.
templates/mobile
templates/standard
Paginator account/questions/list Displays a list of page numbers that customers can select when the length of a report exceeds what can be displayed on a single page.
answers/list
mobile/account/questions/list
mobile/answers/list
social/moderate/comment
social/moderate/question
social/moderate/user
PasswordInput account/change_password Displays the Current Password, Password, and Verify Password fields.
mobile/account/change_password
PrintPageLink account/questions/detail Displays the Print link.
answers/detail
public_profile
social/questions/detail
ProdCatNotificationManager account/notif/list Opens the list of products and categories to which a customer is subscribed and displays the Renew, Delete, and Add Notifications buttons.
ProductCategoryBreadcrumb answers/detail Displays a breadcrumb of product or category links that indicates the hierarchy of the selected product or category.
products/detail
social/questions/detail
mobile/answers/detail
mobile/products/detail
mobile/social/questions/detail
ProductCategoryImageDisplay products/detail Displays an image of a product or category.
mobile/products/detail
ProductCategoryInput ask Displays the drop-down menus of products and categories that can be selected when submitting a question.
social/ask
ProductCategoryList templates/standard Displays a hierarchical list of products in the template footer.
ProductCategorySearchFilter account/questions/list Allows product or category filter selection when searching on the answers list or questions list page.
answers/list
QuestionComments social/questions/detail Displays a comment form for users to post responses to questions or other comments.
mobile/social/questions/detail
QuestionDetail social/questions/detail Displays a question field with title and body and lets the question’s author make edits.
mobile/social/questions/detail
QuestionStatus social/questions/detail Displays the status of a question if it is anything other than active and not locked.
mobile/social/questions/detail
RecentlyAnsweredQuestions home Displays a list of recent discussions that have best answers associated with them.
products/detail
mobile/home
mobile/products/detail
RecentlyViewedContent answers/detail Displays recently viewed answers and discussions in the sidebar.
answers/list
results
social/questions/detail
social/questions/list
RelatedAnswers answers/detail Displays the Answers Others Found Helpful heading with links to related answers.
basic/answers/detail
RelatedKnowledgebaseAnswers social/questions/detail Displays official (knowledgebase) answers related to the discussion being viewed.
ResetPassword account/reset_password Displays the Password and Verify Password fields and the Submit button. This widget is accessed only through a link in an email sent to the customer.
account/setup_password
mobile/account/reset_password
mobile/account/setup_password
ResultInfo account/notif/list Displays the number of matching answers displayed in the search results.
account/questions/list
answers/list
social/moderate/comment
social/moderate/question
social/moderate/user
mobile/account/questions/list
mobile/answers/list
RichTextInput social/ask Allows basic HTML markdown in the Question field when submitting a question to the community.
RssIcon answers/list Displays the RSS icon that links to the feed of your site’s public answers or social questions.
products/detail
SearchButton account/questions/list Displays the Search icon.
answers/list
mobile/account/questions/list
mobile/answers/list
SimpleSearch public_profile Displays the Search field on all pages except Support Home and the search results pages.
templates/standard
templates/mobile
SmartAssistantDialog ask Displays a list of suggested answers when customers submit a question to support staff or the community.
social/ask
mobile/ask
mobile/social/ask
SocialBookmarkLink answers/detail Displays the Share link that opens a menu of social networking sites.
social/questions/detail
SocialResultListing results Displays a list of results returned from searching community content.
social/questions/list
mobile/results
mobile/social/questions/list
SocialUserAvatar account/profile_picture Allows community users to select their avatar by using an automatically generated one or selecting their Gravatar picture.
mobile/account/profile_picture
SourceFilter social/questions/list Displays the Filter By Age and Filter By Best Answer filters.
mobile/social/questions/list
SummaryResultListing answers/list Displays a list of published answer titles on the questions list page or a list of discussion titles on the answers list page.
social/questions/list
TextInput mobile/social/ask Used to enter the body of a question posed to the community.
TopAnswers home.php Displays a list of suggested top answers that can be filtered by product or category.
basic/home.php
mobile/home.php
products/detail
mobile/products/detail
Unsubscribe account/notif/unsubscribe Lists the notifications a customer is subscribed to. This widget is accessed only through a link in an email sent to the customer.
UserActivity public_profile Displays a community user’s activity within the community.
mobile/public_profile
UserContributions public_profile Displays a summary of totals of a community user’s questions, comments, and best answers.
mobile/public_profile
UserInfoDialog social/ask Displays a request for a customer to submit a display name in order to participate in the community.
mobile/social/ask
UserStatus public_profile Displays a community user’s status if the status is anything other than active.
mobile/public_profile
VirtualAssistantAvatar chat/chat_landing Displays the virtual assistant avatar during the chat engagement.
mobile/chat/chat_landing
VirtualAssistantBanner chat/chat_landing Displays the virtual assistant banner during the chat engagement.
mobile/chat/chat_landing
VirtualAssistantFeedback chat/chat_landing Displays the Was This Response Helpful? section of the page, including the Yes/No buttons, and the Submit Feedback button during the chat engagement.
mobile/chat/chat_landing
VirtualAssistantSimilarMatches chat/chat_landing Displays links to content that is similar to the phrases used in the chat engagement.
mobile/chat/chat_landing
VisualProductCategorySelector home Displays images of products or categories that serve as links for drilling down into sub-products or sub-categories.
products/detail
mobile/home
mobile/products/detail

Widgets not used in reference implementation

The following standard widgets are not used in the reference implementation but are available for you to add to your pages.

  • chat

    • ChatCoBrowseButton (used in prior Customer Portal frameworks)

    • ChatCobrowsePremium

    • ChatLaunchFormOpen (used in prior Customer Portal frameworks)

    • ProactiveChat

    • ConditionalChatLink (used in the ContactUs widget)

  • discussion

    • RecentlyAskedQuestions

  • feedback

    • SiteFeedback (used in ContactUs widget)

    • SocialContentFlagging (used in QuestionComments and QuestionDetail widgets)

    • SocialContentRating (used in QuestionComments and QuestionDetail widgets)

  • input

    • AssetCheck

    • ChannelAllInput

    • ContactNameInput (used in prior Customer Portal frameworks)

    • DateInput (used in FormInput widget)

    • EmailCheck

    • ProductCatalogInput

    • SelectionInput (used in FormInput widget)

  • knowledgebase

    • SearchSuggestions

    • TopicBrowse

    • TopicWords

  • login

    • LoginDialog (used in AccountDropdown and AnswerNotificationIcon widgets)

    • LogoutLink (used in AccountDropdown widget)

  • moderation (These widgets are all used in the ModerationFilterDialog widget)

    • ModerationContentFlagFilter

    • ModerationDateFilter

    • ModerationStatusFilter

  • navigation

    • Accordion

    • MobileNavigationMenu

  • output

    • ChannelAllDisplay

    • FieldDisplay (used in other input widgets)

    • FileListDisplay (used in /views/admin/answer_full_preview.php for displaying the print version of an answer on the agent desktop)

    • IncidentThreadDisplay (used in the DataDisplay widget)

    • ProductCatalogDisplay

    • ProductCategoryDisplay (used in the ProductCategoryInput and DataDisplay widgets)

  • search

    • AdvancedSearchDialog

    • AssetOrgList

    • CombinedSearchResults

    • DisplaySearchFilters

    • FilterDropdown

    • OrgList

    • ProductCatalogSearchFilter

    • SearchTypeList (contained in AdvancedSearchDialog, which is no longer in use on the reference implementation)

      Note: You should add the SearchTypeList widget to any page containing a custom report that uses an integer filter. Without the widget, your customers can search only by answer ID. Adding the widget lets your customers select a different search type so they can enter text search terms.
    • SortList (contained in AdvancedSearchDialog)

    • WebSearchSort (contained in AdvancedSearchDialog)

    • WebSearchType (contained in AdvancedSearchDialog)

  • searchsource

    • SourceSort

  • social

    • AnswerComments

    • CommunityPosts

    • CommunityPostSubmit

    • CommunitySearchResults

    • CommunityUserDisplay

  • surveys

    • SurveyLink

    • ProactiveSurveyLink

  • utils

    • Blank

    • CoBrowseLink

    • CoBrowsePremium

    • ProgressBar

Set the maximum year for date drop-down menus

By default, any drop-down date menus you add to your customer portal will display the current year as the highest year option. If you want to change the latest year listed in the menu, use the following procedure.

Procedure
  1. Locate EU_MAX_YEAR in Common/Knowledge Base/Answer Search.

  2. Set the maximum year.

    1. To set the maximum value to the current year, clear any existing value so the Value field is blank.

    2. To set a specific year, type that year in the Value field.

    3. To set an offset (for example, five years from this year), type the offset value in the Value field. In this example, type +5.

  3. Click Save.

Add an incident custom date field

The following example assumes that you want to add a custom field where customers can tell you how quickly they need an answer to a question they submit on the Ask a Question page. Because that is not a standard incident field, you’ll first need to add it as a custom field. Then you’ll add the custom field to a page.

Procedure
  1. Open Custom Fields in Configuration > Database.

  2. Click Incident.

  3. Click New.

  4. In the Name field, type Answer Needed By.

  5. Click Data Type and select Date Field .

  6. In the Column Name field, type answer_needed.

    Note: The Column Name can include alphanumeric characters and the underscore symbol. It cannot contain spaces.

  7. To require customers to complete the field, select Required for Customer Portal.

  8. If the Visibility check boxes for End-user Display and Edit are not selected, select both of them.

  9. Click Save.

Determine unused custom widgets

Widgets are used throughout the customer portal. You may find, after time, that a custom widget has become obsolete.

Procedure

  1. On the Customer Portal Administration page, select Widgets.

  2. Select Widgets Not In Use. This action reviews every page of your site for any custom widgets used. Depending on the size of your site, this review can take some time.

  3. If the widgets are not actively being worked on, you can remove them from your live site and archive them, in case you need them later.

Logging in to the Customer Portal

Logging in to the Customer Portal

Depending on how you set up the Oracle RightNow Customer Portal Cloud Service (Customer Portal), your customers can log in directly or they can log in through an external site that verifies their identity.

The following list summarizes the various login methods.

  • Standard login—Customers use standard login when they log in to your customer portal using the user name and password assigned to them in Oracle Service Cloud instead of logging in through an external service provider, such as Facebook or PingFederate. Clicking the Log In or Sign Up button (the AccountDropdown widget) in the upper right corner of any customer portal page opens the login window that lets customers log in. Customers who do not yet have an account can click the Create an Account button on the login window to open a form for entering contact information.

  • Open login—Customers can log in to the customer portal through an external service provider where they already have an account. You can accept verified customer logins from Facebook, Twitter, Google, and Yahoo, and any other open login provider you want to add.

  • Pass-through authentication (PTA)—You can integrate the customer portal with your organization’s website so your customers can automatically log in to your support site. Although your organization’s web pages may be external to the customer portal, they can pass login parameters through the URL of the customer portal page. As a result, your customers do not have to complete a second login procedure to access your support site. Information sharing between your external site and the customer portal can be used to create and update contact records. To enable pass-through authentication, contact your Oracle account manager.