6Customer Portal

Configuring B2C Service for the Customer Portal

Overview of Customer Portal

Your customers use this interface to interact with your customer support.

Your customers can use your customer portal to access a variety of self-help tools, including:
  • Searching for product and support information

  • Reviewing the contents of your knowledge base

  • Asking questions of your support staff and your user community

  • Chatting with staff

  • Managing their account information

Because the Customer Portal is integrated with your B2C Service application, any information customers enter by submitting an incident, updating account information, or providing feedback on an answer is immediately available to your support staff on the B2C Service administration interface.

Some configuration occurs in the B2C Service administration interface, while editing the templates, pages, widgets, and inlays is completed using third-party tools and software.

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 make modification for your specific needs. Edit the default files so they meet your organization’s support goals. You can match 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 any custom pages you may need.

  • You’ll use a text editor such as TextPad, NotePad, 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 B2C Service 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, widgets, and inlays to configure the customer portal pages.

B2C Service Elements Used in Customer Portal

Your Customer Portal relies on B2C Service 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. This is some of the information in the knowledge base.

  • 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.

View Your Customer Portal

As you’re working on changes to your customer portal pages, you can use the development area to view them. You can set your site to open the pages that your customers see on your production site or your development pages.

When you open your customer portal, 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. 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.

  1. Open your customer portal by doing one of these:

    • Launch a web browser and enter the URL for your site: https://<your_site>/app.
    • From the file menu on the Service Console of your B2C Service 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.

Overview of WebDAV

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

Administrators can view files stored on the customer portal server from the Customer Portal Administration site or from their local workstation.

  1. To view files on your local workstation:

    1. Browse to the local location you specified in your WebDAV setup.

      Note: We recommend editing downloaded files and then uploading them back to the server.
    2. Click folders to navigate through the site files.

    3. Double-click the filename to open the file for editing.

  2. To view files on the customer portal server:

    1. In a web browser, enter https://<your_site>/dav.

    2. Click cp to display the subfolders.

    3. Click the folders to open them and navigate through the site files.

    4. Double-click the filename to open the file for editing.

Configuring B2C Service for Customer Portal

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

Before you get started working with pages, widgets, and inlays, you’ll want to do some basic configuration for the Customer Portal on the administration interface.
  • Assign appropriate permissions to staff members who will be working with your customer portal.

  • Review the configuration settings to be sure you don’t need to change any of the defaults.

  • Set up additional configuration options for features that are accessed through your customer portal, such as search options, SmartAssistant, related answers and web indexing.

Assign Permissions for Customer Portal

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

  1. Log in to B2C Service.

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

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

  4. Click Permissions.

  5. Select the appropriate permission:

    • CP Edit—Lets staff members with this profile edit customer portal pages using WebDAV, but not to stage or promote them. They can also access the Customer Portal Administration site.
    • CP Stage—Lets staff members with this profile copy the development files to the staging area.
    • CP Promote—Lets staff members with this profile promote customer portal pages from the staging area to the production area.
  6. Click Save.

Enable MOD_CP_DEVELOPMENT_ENABLED

Before you can make changes to your customer portal development site, you must enable the MOD_CP_DEVELOPMENT_ENABLED configuration setting.

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

  2. Enter 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 with Facebook provides the application IDs and secret keys for requesting customer credentials for authentication.

  1. Go to Facebook for Developers Quick Starts.

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

  3. From the Service Console, 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. Enter 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 with Google provides values for the GOOGLE_OAUTH configuration settings.

  1. Go to the Google API Dashboard.

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

  3. From the Service Console, 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 with Twitter provides the application IDs and secret keys for requesting customer credentials for authentication.

  1. Go to Twitter Developer.

  2. Create a new application using the Twitter requirements.

    1. Set the website URL to point to your B2C Service site.

    2. Select Enable Sign in with Twitter.

    3. Set a Callback URL. The format for the Callback URL is <site_url>/ci/openlogin/oauth/callback/twitter/app/home/onfail/app/home/.

    4. Set the Terms of Service URL. The format for the URL is <site_url>/app/home.

    5. Set the Privacy policy URL. The format for the URL is <site_url>/app/home.

    6. Select the Allow this application to be used to sign in with Twitter checkbox.

    7. On the Permissions tab, select Request email address from users.

    You should see a unique App ID and App secret value.
  3. From the Service Console, 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.

Add Search Priority Words

You can associate answers and documents with specific search terms ensuring the customer sees the information you want them to.

Search priority words let you associate a specific answer or document with specific search terms to ensure that the answer (or document) will always be returned when a customer enters the search term. When you’ve assigned a search priority word to an answer and the customer enters the search priority word, the answer is displayed in the Recommended Links section on the Answers page.
  1. Double-click Search Priority Words in Configuration > Service > Knowledge Base.

  2. Click New.

  3. Type a name in Search Priority Word Name. This is not the search term itself, merely the identifier for it.

  4. In Keywords, type search terms, separating each one with a comma, semicolon, or line break.

  5. Select Always Show, if you want the answer to appear in the Recommended Links section of the Answers page.

  6. Choose how you want to associate the search priority word.

    • Public Answer
    • WWW Document
  7. Enter the answer or document information you want to associate with the search priority words.

    • To associate to an answer, enter the Answer ID for the answer.
    • To associate to a document, enter the title and URL of the document.
  8. Click Save and Close.

Add and Remove Answer Stopwords

Incidents and answers are analyzed for suggested words you have indicated should not be searchable. Administrators can modify this list of stopwords.

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

  2. Do one or more of these actions:

    • Add words from the Suggested Additions list to the Active stopword list.
      1. Select the stopwords you want to add to the list.
      2. Click >>.
    • Add a stopword that is not in the Suggested Additions field.
      1. Enter the word in the field at the top of the Active list on the right.
      2. Click Add New.
    • Remove a stopword.
      1. Click the word in the Active list.
      2. Click <<.
  3. Click Save.

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

Edit the Aliases Word List

You can add aliases, or synonyms, to link terms that are specific to your industry or organization to similar search terms your customers use.

  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, for example:
    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.

Add an Answer Access Level

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

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

  2. Expand the System Menus folder.

  3. Click Answer Access Levels.

  4. Click New.

  5. Enter 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.

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.

  1. Double-click Contact Password Configuration in Configuration.

  2. Edit the password requirements.

  3. Click Save.

Overview of Finding Content on the Customer Portal

You can use Customer Portal standard searching or indexing to return search results to customers.

Search engines find the pages of your website from links from other sites and from links within your site. With the help of sitemaps, search engines can also find and index pages that are not part of your knowledge base, such as web pages, PDFs, and Microsoft Word documents.
Note: Content in iFrames is not searched and 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.

By default, Sitemap is enabled 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

In addition to using Sitemap to provide better spidering of your customer portal pages, Web Indexer can be pointed to a page that uses Sitemap to better index web pages outside of B2C Service. Filters can guide the web spider to follow only those hyperlinks that are within specified domains. During indexing, URLs are normalized to prevent a document from being indexed more than once.

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.

Configure the Web Indexer

You can enable external document searching in the Configuration Wizard.

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

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

    Note: To index a site using Sitemap, use the Sitemap URL as the root URL.
  3. Click Save.

View External Search Logs

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

  1. Open Logs in Configuration > Site Configuration.

  2. Click External Search Logs.

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

Turn Off Customer Browser Cookie Use

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

If you disable cookies, visit data is determined by URL parameters. You must define in individual lines of code to prevent new visits from being initiated each time the customer navigates away from a page.
  1. Open Configuration Settings in Configuration > Site Configuration.

  2. On the Search window, enter CP_COOKIES_ENABLED in Key and click Search.

    The configuration setting is located in the RightNow User Interface/Customer Portal/Login folder.
  3. Set the Value field to No.

  4. Click Save.

Pass Visit Information in Custom Pages

When your site has disabled cookies, you can pass visit information by modifying the page links.

  1. Open the custom web site page.

  2. Locate the link and add #rn:session# to the end of the page URL.

    https://<your_site>.custhelp.com/<custom_page>.html#rn:session#
  3. Save and publish the page.

Accessibility in Customer Portal

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

An off-screen <h1> tag is visible to screen readers using the rn_ScreenReaderOnly CSS class. This tag provides accessible navigation using shortcut keys for customers who use screen readers. The content is not visible to sighted users unless styles are disabled.

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.

Note: 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 Configuration Setting Keys

Customer Portal configuration settings are located in folders on the Configuration Settings editor. Folder paths, descriptions, and default values are listed here.

Table Configuration Settings

Configuration Setting and Path 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. 365
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. Null
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_CONTACT_LOGIN_REQUIRED

RightNow User Interface/Customer Portal/Login/

When enabled, requires contacts to be logged in when access most pages or controls. No
CP_COOKIES_ENABLED

RightNow User Interface/Customer Portal/Login/

Defines whether the Customer Portal tries to set cookies on a customer’s browser.
Note: When enabled, a session parameter is added on the initial page load until the end user accepts the create cookie request and is retained until the cookie expires or is removed from the end user’s system.
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_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_LOGIN_COOKIE_EXP

RightNow User Interface/Customer Portal/Login/

The number of minutes before the Customer Portal login cookie expires. 60
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_PRODUCTS_DETAIL_URL

RightNow User Interface/Customer Portal/Pages/

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

RightNow User Interface/Customer Portal/Pages/

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

Common/General/Security

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

RightNow User Interface/Customer Portal/Pages/

The location and file for generating social questions URLs. social/questions/detail
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 Interface/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. Null

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 Folder Structure

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

Table Folder Structure

Folder and file location Description
/core/ You cannot add or remove files in this folder. You cannot edit the names of the folders or files.
/core/assets/ Contains all web assets used by the Customer Portal Administration site.
/core/assets/debug-js/ Contains all JavaScript debug assets used by the Customer Portal Administration site.
/core/assets/default Contains the CSS, images, and themes for the pages, templates, and widgets in the reference implementation.
/core/assets/ejs/ Contains the CSS, images, and themes for the pages, templates, and widgets in the reference implementation.
/core/assets/images/ Contains the CSS, images, and themes for the pages, templates, and widgets in the reference implementation.
/core/assets/thirdParty/ Contains the CSS, images, and themes for the pages, templates, and widgets in the reference implementation.
/core/framework/ The core of the Customer Portal code base. 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.
/core/widgets/ 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.
/customer/ Contains all the Customer Portal files you can modify. Even if you don’t stage and promote these pages, changes you make may affect the look and function of your production pages.
/customer/assets/ 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 this folder.
/customer/assets/css/ Contains the assets you can add, edit, and delete.
/customer/assets/images/ Contains the image you can add, edit, and delete.
/customer/assets/themes/ 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. The themes are applied to your production site only when you promote the staged files into production.
/customer/assets/feedback/ These files are used strictly by the development files.
/customer/assets/other/ Contains text files.
/customer/assets/default/ Contains default versions of the asset files provided in the reference implementation.
/customer/development/ This is your working folder. It contains all templates and pages to create and update your customer portal.
/customer/development/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.
/customer/development/hook.php Lets you define a PHP array of functions that is executed before and after the API calls of your choice.
/customer/development/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).
/customer/development/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 and add additional controller files to this folder.
/customer/development/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.
/customer/development/helpers Contains the sample_helper.php file and can be used for storing PHP utility function files.
/customer/development/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.
/customer/development/libraries/ Contains sample.php file and can be used for storing singleton PHP class files.
/customer/development/models/ Contains three sample model files: /custom/extendedsample.php, /custom/mysocialsearch.php, and /custom/sample.php.
/customer/development/views/ Includes all display files that do not contain logic.
/customer/development/views/admin/ Pages are used to display answer previews on the Service Console.
/customer/development/views/pages/ Contains all customer portal pages.
/customer/development/views/templates/ Includes thestandard.php—used for the reference implementation pages—and the agent.php—for previewing a guide on the B2C Service administration interface.
/customer/development/views/partials/ Contains custom view partials.
/customer/development/widgets/ A folder for your custom widgets.
/customer/error/ This folder can contain only the reference implementation error pages listed in this table.
/customer/error/splash.php You can display this page when your site is being upgraded.
/customer/error/error404.html Static HTML page displayed when an HTTP 404 Not found error code is returned.
/customer/error/error413.html Static HTML page displayed when an HTTP 413 Request entity too large error code is returned.
/customer/error/error500.html Static HTML page displayed when an HTTP 500 Internal server error code is returned.
/generated/ Mirrors the structure of the development folder. You cannot add, edit, or delete the files in this folder.
/generated/production/ Contains the staged files that have been promoted into production. These files are visible to your customers.
/generated/backup/ Contains the original source code from the previous promoting activity.
/generated/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.
/generated/backup/ Contains the original source code from the previous staging activity.
/generated/themes/ Copied from your development site when you stage the development pages.
/logs/ 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.

Customer Portal Reports

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

Report Name Location Description
Referring Sites Public Reports/Service/Site Reports/Customer Portal/ The percentage of visits by sites that referred customers to your site.
Visits by Browser Public Reports/Service/Site Reports/Customer Portal/ The percentage of visits by browser type.
Visits by Browser and Operating System Public Reports/Service/Site Reports/Customer Portal/ The percentage of visits by browser and operating system.
Visits by Operating System Public Reports/Service/Site Reports/Customer Portal/ The percentage of visits by operating system.
Visits by Page Set Public Reports/Service/Site Reports/Customer Portal/ The percentage of sessions that accessed each page set.
Visits by Time Public Reports/Service/Site Reports/Customer Portal/ The number of visits that occurred during each defined unit of time as well as a percentage of visits per time unit.
Aging Discussions Public Reports/Service/Community Self Service/Activity/ A list of discussions that do not have comments or best answers.
Discussion Comment Details Public Reports/Service/Community Self Service/Activity/ 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 Public Reports/Service/Community Self Service/Activity/ 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 Public Reports/Service/Community Self Service/Activity/ A list of discussions sorted by the number of comments and response time.
Community Category Subscriptions Public Reports/Service/Community Self Service/Subscription/ A list of subscribers to community content for each category.
Community Product Subscriptions Public Reports/Service/Community Self Service/Subscription/ A list of subscribers to community content for each product.
Community Subscribers by Question Public Reports/Service/Community Self Service/Subscription/ A list of discussion questions and community members who are subscribed to each.
Community Subscribers by User Public Reports/Service/Community Self Service/Subscription/ A list of individual users and the discussion content they are subscribed to.
Discussion Question Subscriptions Public Reports/Service/Community Self Service/Subscription/ A list of community discussions, the product or category they are associated with, and the number of subscribers to each discussion.
Top Categories by Comments Public Reports/Service/Community Self Service/Top/ The categories that have the highest number of new comments.
Top Categories by Questions Public Reports/Service/Community Self Service/Top/ The categories that have the highest number of new questions.
Top Comments by Rating Public Reports/Service/Community Self Service/Top/ The comments with the highest ratings.
Top Products by Comments Public Reports/Service/Community Self Service/Top/ The products that have the highest number of new comments.
Top Products by Questions Public Reports/Service/Community Self Service/Top/ The products that have the highest number of new questions.
Top Questions by Rating Public Reports/Service/Community Self Service/Top/ The questions with the highest ratings.
Top Users by Comments Public Reports/Service/Community Self Service/Top/ Users who have contributed the highest number of comments.
Top Users by Questions Public Reports/Service/Community Self Service/Top/ Users who have contributed the highest number of questions.
Registrations Trend Public Reports/Service/Community Self Service/Users/ The trend of new community user registrations.
User Details Public Reports/Service/Community Self Service/Users/ A list of community users. Includes 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.
Discussion Comments with No Author Common/Site Administration/Community Self Service/ A list of discussion comments with no authors assigned to them.
Discussion Questions with No Author Common/Site Administration/Community Self Service/ A list of discussion questions with no authors assigned to them.

Customer Portal Page Sets

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

File location Type of file Description
/cp/customer/development/views Development Files you work with when you want to make changes to your customer portal. These files are not visible to your customers.
/cp/customer/development/widgets/custom Development Files you add or edit to change custom widget functionality. These files are not visible to your customers.
/cp/generated/staging Staging Files you’ve compiled and optimized to look and perform as they will on the production site. These files are not editable. These files are not visible to your customers.
/cp/generated/production Production Files you have promoted from staging. These files are visible to your customers.
/cp/core/framework/views Reference implementation Default, read-only files that make up the original customer portal reference implementation. You should remove pages that your site does not use.
/cp/core/widgets Reference implementation Default, read-only files that make up the original customer portal reference implementation.

Customer Portal Template and Page Set

Overview of the Standard Page Set

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. You should remove any pages that you do not use in your site.

Overview of the Customer Portal Standard Template

The reference implementation standard Customer Portal pages are built on a standard template. You can 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: The behavior of the reference implementation may not correspond to the descriptions in this section if you have changed the default configuration settings.

These widgets are not rendered on a page, but provide specific 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.

Edit Customer Portal Files

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

You must enable the MOD_CP_DEVELOPMENT_ENABLED configuration setting 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.
  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 for that file, and then save the file.

    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.

  1. Stage Customer Portal Pages.
  2. Promote Customer Portal Pages.

How Customer Portal Handles Question Marks in a URL

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 subproduct and subcategory 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.

iFrame Security Issues

Because using iFrames is not a best practice, 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.

Customer Portal Framework Versioning

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

The Customer Portal version is independent of the B2C Service release version, allowing you to upgrade to newer versions of B2C Service 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.

Dependency checks are run when you select a version update to ensure that your B2C Service 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.

Overview of Message Bases in Customer Portal

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.

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

Change a Message Base Value

This example shows how a user with the appropriate permissions can modify the value of SUPPORT_HOME_TAB_HDG.

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

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

  3. Click Search.

  4. Enter the new label in the Text field.

  5. Click Save.

Reference a Different Message Base

This example shows how you can reference the SUPPORT_HELP_HDG message base.

Locate the message base you want to use as a replacement. Message bases are listed in Configuration > Site Configuration > Message Bases. For this example we are using SUPPORT_HELP_HDG.
  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. Edit the code to reflect the name of the message base you want to use.

    This code replaces the SUPPORT_HOME_TAB_HDG message base with the SUPPORT_HELP_HDG message base:
    <li><rn:widget path="navigation/NavigationTab" label_tab="#rn:msg:SUPPORT_HELP_HDG#" link="/app/#rn:config:CP_HOME_URL#" pages="home"/></li>
  4. Save the file.

Use Custom Text Instead of Message Bases

This example shows how to change the default message base label to a custom value.

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

  2. Locate this 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 the text you want to appear.

    Your custom value doesn't need to include #rn:msg:.
    <li><rn:widget path="navigation/NavigationTab" label_tab="Customer Care"
         link="/app/#rn:config:CP_HOME_URL#" pages="home"/></li>
  4. Save the file.

Add Navigation Tabs

You can add new navigation tabs to the standard.php template file.

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

    1. Copy the code lines for an existing navigation tab and paste it where you want the tab to appear in the navigation.

      <li><rn:widget path="navigation/NavigationTab" label_tab="#rn:msg:SUPPORT_HOME_TAB_HDG#" link="/app/#rn:config:CP_HOME_URL#" pages="home"/></li>
    2. Edit the label_tab attribute to name the tab and the link attribute to specify the page you want to open when the tab is clicked.

      <li><rn:widget path="navigation/NavigationTab" label_tab="Chat" link="/app/chat/chat_launch/></li>
  2. Save the file.

Change Navigation Tab Labels

You can change the labels for the two existing tabs, Support Home and Ask a Question, on the standard template.

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

    • To change the Support Home tab label, enter 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>
    • To change the Ask a Question tab label, enter 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>
  2. Save the file.

Add a Drop-down Menu to a Navigation Tab

This example creates a new Answers tab with a submenu to demonstrate how you can create a drop-down menu for navigation tabs on the standard.php template file.

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

    1. Add the subpages attribute, subpages="#rn:msg:ANSWERS_HDG#, to the NavigationTab widget you want to modify. List the page titles and paths in the attribute, WebSearch Indexing > /app/answers/web_list.

      <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" />
  2. Save the file.

    If you do not get the results you expect, try replacing the NavigationTab.css file in cp/customer/assets/default/themes/standard/widgetCss with the NavigationTab widget’s CSS from cp/core/assets/default/themes/standard/widgetCss/NavigationTab.css.

Configure the SimpleSearch Widget

You can add simple search functionality to any Customer Portal page.

The SimpleSearch widget is displayed conditionally and 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.
  1. Open one of these files and locate the SimpleSearch widget 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. Edit the code to configure the SimpleSearch widget:

    • To remove the SimpleSearch widget from every page, remove the code you located.
    • To display the SimpleSearch widget on every page, remove the opening condition statement <rn:condition ...> and the closing condition statement </rn:condition> lines.
    • To change the widget’s labels, add the label attribute using the form label="Your Custom Label Name".
    • 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"/>
    • To open a page other than the default results page, change the report_page_url to a different page.
      <rn:widget path="search/SimpleSearch" icon_path="" report_page_url="/app/social/questions/list"/>
  3. Save the file.

Overview of the AccountDropdown Widget

The AccountDropdown widget displays various account and login options, depending on the customer's status.

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. 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.

The AccountDropdown widget contains these 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.

Configure the AccountDropdown Widget

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

  1. Open one of these files and locate the AccountDropdown widget code.

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

      There are four instances of the AccountDropdown widget on the 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"/>
  2. Edit the code to configure the AccountDropdown Widget.

    • To change the widget’s labels, add the label attribute using the form label="Your Custom Label Name".
    • 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.
    • 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.
    • 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.
    • To display only a select number of open login providers, add the open_login_providers attribute to the AccountDropdown widget and specify the providers you want.
    • To remove the password field, add the disable_password attribute to the AccountDropdown widget and set its value to true.
  3. Save the file.

Defining Themes

Themes are created from CSS files. Themes may also include graphics, JavaScript, flash animations, and other types of files.

All reference implementation theme files are called from the /euf/assets/themes/standard and /euf/assets/themes/mobile folders. Copies of theme files used in the reference implementation are also stored in /cp/customer/assets/themes/standard and /cp/customer/assets/themes/mobile.

When you create custom themes, you must place them in the /cp/customer/assets/themes subfolder. The CSS used for the theme must also be placed in the custom theme folder. If you try to stage development files containing theme paths not associated 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 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 and /cp/core/assets/default/themes/mobile folders. 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 runtime 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 uses a template and also defines a 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"/>

You can copy the reference implementation CSS file and modify it to create a variety of themes that can be applied to pages using the RN Theme tag.

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.

Create a Theme

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

  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. In a text editor, open site.css from your new custom folder.

  4. To customize your new theme, edit the CSS file .

    1. Make edits to modify the text, colors, or other aspect of your custom theme.

    2. To add images, place the image files in /cp/customer/assets/themes/[your_custom_folder]/images.

  5. Save the file.

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

Apply a Theme

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

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

  2. Locate <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.

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

Customer Portal Page Meta Tags

You can control Customer Portal functionality through page tags and page meta tags instead of writing PHP code.

You can use page meta tags on any Customer Portal page by adding the attribute name to the <rn:meta> tag.

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 tag can also be used to create a custom tab with a browser on an agent desktop workspace.

This meta tag is used on the guided assistance page so guides can be previewed by staff members who are designing guides on the administration interface.

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

Indicates whether the page contains a Chat application.

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 community user with discussion moderation permissions.
Social User Moderator Required social_user_moderator_required Indicates a page that can be accessed only by a community user with discussion moderation and social user moderation permissions.
Template template Identifies the template the page uses.

Add Page Meta Tags

This example demonstrates using a page tag on the standard template with a chat application to display an error message to customers who do not have a chat SLA.

  1. Open a template file and locate the <rn:meta> tag.

    • /views/templates/standard.php
    • /views/templates/mobile.php
  2. Edit the <rn:meta> tag to include the sla_failed_page attribute.

    <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" />
  3. Save the file.

Require Login on 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.
  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 before they can access any or all of your customer portal pages.

  1. Open one of the Ask a Question page files and locate the <rn:meta> tag:

    • /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.

    <rn:meta title="#rn:msg:ASK_QUESTION_HDG#" template="standard.php" clickstream="incident_create"
    login_required="true" sla_required_type="incident" sla_failed_page="/app/error/error_id/2" />
  3. Save the file.

Content Placement on Customer Portal Pages

You’ll use page tags to position information on a page.

These tags control the placement of content on Customer Portal pages.
  • Page Title—Place this tag where you want the page title to appear when the page and template are merged.
    <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.
    <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.
    <div>
         <rn:page_content/>
    </div>

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.

Display Database Content on Customer Portal Pages

This example uses the Answer Details page to demonstrate how to use page tags to output answer information from the database.

Locate the names of the fields you wish to use in Business Objects on the Customer Portal Administration site. Make note of how to label them in the code.

The <rn:field> tag has two attributes.

  • highlight—Highlights content that matches the keyword parameter in the URL.
  • name—Identifies the business object type and field to be displayed.
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.
  1. Open the Answer Details page (/views/pages/answer/detail.php).

  2. Locate this code:

    <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>
  3. Notice the <rn:field> tags used to display the answer summary, the created and updated dates, and the answer description.

  4. Add other database fields using the same format.

  5. Save the file.

How You Apply Common Attributes to Multiple Widgets

Page tags let you create a set of widget attributes that can be referenced by multiple widgets.

You can use the <rn:container> tag in one of two ways.

  • 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.
  • As a widget attribute that references the attribute-value definitions of the container—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.

Use the rn:container Tag as a Wrapper

This example uses the Answers page to demonstrate using the container tag as a wrapper around a group of widgets to applying common attributes to multiple widgets.

Each of the widgets that requires a report use report ID 176 because they are all enclosed within the <rn:container report_id="176"> tag.

  1. Open the Answers page (/views/pages/answers/list.php).

  2. Locate the rn_SearchControls tag.

    <div class="rn_SearchControls>...</div>
  3. Replace that tag with this code:

    <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>
  4. Note the code identifying the report: <rn:container report_id="176">. You can change the report id to require all widgets in the tag to use a different report.

  5. Save the file.

Use the rn:container Tag as a Widget Attribute

This example demonstrates how you could use code to define the container.

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. 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.

  1. Open the page you want to add the widget attribute to.

  2. Add this code to the page: <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 can be any string.
    Note: The prefix rnc_ is reserved by Customer Portal and cannot be used in string values.
  3. Add this code to the page.

    <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"/>
    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.
  4. Save the file.

The Page Condition Tag

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

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

<rn:condition attribute="value">
     [Content here is displayed only if the specified condition is met]
</rn:condition>

These situations can control whether information is displayed or not.

  • The customer’s login status
  • The customer is logged in with pass-through authentication
  • The specific page where content is placed
  • The number of answers viewed by a customer
  • The number of searches performed by a customer
  • The amount of time that has elapsed since an incident was solved
  • The customer’s SLA
  • The language of the interface
  • The value of a configuration setting
  • The value of a URL parameter
  • Chat availability
  • The customer’s community user status

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

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.

Logged In Condition

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

The standard 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 <rn:condition external_login_used="true"> before the first input widget in the block of input fields, and add the closing condition tag (</rn:condition>) after the last widget.

Hide or 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, Questions, and Content Viewed Conditions

You might want to use these tags to require your customers to first view existing answers 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 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, it’s better to Display the Ask a Question Page Based on User Actions.

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.

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 attribute includes these elements.

  • CONFIG_BASE—One of these configuration settings found on the Configuration Settings editor.
    • Common

    • RNW (RightNow Common folder)

    • RNW_UI (RightNow User Interface folder)

    • RNL (Chat folder)

    • MA (Outreach and Feedback)

    Note: The CONFIG_BASE element is not case sensitive.
  • 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 looks like this.

<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}

These are the elements of the attribute.

  • URL_KEY—The parameter key to be checked in the URL. For example, to check the keyword URL parameter, enter 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, use this attribute to set a condition if the keyword parameter is “roaming.”

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

Display Alternate Content when Chat is Unavailable

Use the Chat Available tag to determine whether the current time is within the chat operating hours and not a holiday.

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

  2. Locate this code.

    </rn:condition>
    <rn:widget path="chat/ChatStatus"/>
    <rn:widget path="chat/ChatHours"/>
  3. Add this 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. Remove the chat availability status text by deleting <rn:widget path="chat/ChatStatus"/>.

  5. Save the file.

<rn:condition_else/>
    [Content to be displayed when chat hours are not available]
</rn:condition>
<rn:widget path="chat/ChatHours"/>

Community User Statuses

The community user statuses are used 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

The conditional page tag includes an RN Condition Else 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.

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 page—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 page—Displays a message that a customer’s password change was successful.
mobile/utils/submit/profile_updated Mobile Profile Update Confirmation page—Displays a message that the customer’s profile was successfully updated.
products/detail Products Detail page—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 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—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—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 page—Offers tips for editing content using plain text markdown.
utils/help_search General Search Tips page—Displays 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 a 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 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 nonexistent 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.

Error Codes and Messages

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

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.

Customer Portal Widgets

Customer Portal Widgets

A widget is an element of the Customer Portal that performs a specific function.

The Customer Portal contains more than one hundred widgets in its standard widget collection. Here are a few examples of standard widget functionality.

  • 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 don't go into all the details of each one. For widget-specific information, visit https://<your_site>/ci/admin/docs/widgets/standard. You can select a folder and widget to see its definition, preview, description, default code, attributes, and other configuration information.

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 resembling this 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 these 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.

  • attributes—Defines widget parameters that control appearance and function.

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 these 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. The originating release is identified in the first line of code.

  • view.php—Contains the HTML required to display the widget. The originating release is identified in the first line of code.

  • *.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.

  • *.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. The presentation CSS files are located in the /cp/core/assets/default/themes/standard/widgetCss or /cp/core/assets/default/themes/mobile/widgetCss folder and include the widget name.

  • preview/preview.png—Displays an example of what the widget will look like when it is added to a page.

Overview of the YAML File

This topic uses the info.yml file for the KeywordText widget to describe the parts of an YAML file.

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

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

This file includes these elements:

  • 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. 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.

Overview of the Controller File

The controller file renders and previews the widget.

The functions within the file construct the widget and get the data the widget needs. The get data function of controller.php instantiates the widget.

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.

Overview of the View File

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

In the view.php file, every block has a unique ID that describes its context. Although standard widgets don’t actually use the block tags, the tags identify where you can edit the code. 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, 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 and the View File

View partials 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

Rather than a single large view 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 View Partials

This topic uses the SiteFeedback widget to demonstrate how you can use view partials across multiple widgets.

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.

For example, the SiteFeedback widget contains this code.

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

It calls the view partial RequiredLabel.html.php in the /cp/core/framework/views/Partials/Forms folder, which contains this 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 this 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.

Custom View Partials

A custom view partial lets you set different functionality in standard view partials.

For example, if you want to use two blue asterisks instead of a single red one to indicate a required field, you can create a custom view partial file with the same name as the standard.

Using the RequiredLabel 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 this 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 this 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.

Overview of the Logic File

The logic 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.js file is optional.

Overview of 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. These CSS files are stored in folders with other files that make up each widget.

Widgets with a corresponding CSS file in the /cp/customer/assets/themes/standard/widgetCss folder use that CSS file to control the presentation 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. You must stage and promote your 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.

You should follow these best practices when editing widget CSS files:
  • Use as few classes as possible
  • Use the top-level widget CSS class attribute to style elements within the widget
  • Create styling rules only if a site CSS rule must be overridden
Follow these guidelines when editing the base CSS files found in /cp/customer/development/widgets/custom/[customWidget]/base.css:
  • Add rules that structure the widget or make it function correctly
  • Start rules with the class name in the top-level <div> element in the view
  • Avoid generic functionality rules
  • Avoid styling rules
Follow these guidelines when creating and editing presentation CSS files found in /cp/customer/assets/themes/standard/widgetCss/[widgetName.css]:
  • Name the CSS file the same as the widget
  • Start rules with the class name in the top-level <div> element in the view
  • Avoid generic styling rules

Standard and Custom Widget Folders

All standard and custom widgets that are part of the Customer Portal reference implementation are stored together.

All of the standard widgets 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.

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.

Overview of 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 and cause 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.

Overview of YUI Usage

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. These 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 these YUI requirements in jsModule.

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

How You Find 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 entering 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 enter 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 Widget Versions

Widget versions are displayed in the widget information found on the administration site.

Every customer portal widget has a version number, letting you incorporate only that widget without requiring you to use an entire widget set or a new framework version.
  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, select View 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.

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

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

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

    • 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, enter 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

Widget information is defined in detail when you select the widget on the Customer Portal Administration site.

  1. In a web browser, enter https://<your_site>/ci/admin.

  2. Click Widgets.

  3. Find and select a widget.

    • 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.
    • Enter the widget name in Search Widgets.
Three tabs appear on the widget information page: Available Versions, Widget Usage, and Recent Version Changes. These 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.”

Overview of the Available Versions Tab

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

These elements appear on the Available Versions tab.

  • Staging/Production/Development—When multiple versions of the widget exist, the areas using each version are noted.

  • 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 also 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.)

  • 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.

    • 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 B2C 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.

    Note: When new widgets are added in future releases, they are not automatically activated. You’ll need to specify which version of the widget you want when you 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—This 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 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.

Overview of the 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.

Overview of the Recent Version Changes Tab

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 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.

Subwidgets 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 subwidget’s attribute requires the format:

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

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

sub:prod:label_input="Your Product"

Configure a Widget With a Subwidget

This example uses the AdvancedSearchDialog widget to demonstrate configuring a widget with a subwidget.

  1. Open the page containing the AdvancedSearchDialog widget.

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

  3. Edit the code to include the subwidget labels.

    <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.

Overview of the FormInput Widget

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

Because there are different types of input widgets in FormInput, each subwidget has its own ID, which you can use to set attributes for all subwidgets 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 subwidget 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 Widgets

This example uses subwidgets to define custom labels.

The ChannelAllDisplay and ChannelAllInput widgets work similarly, where you can use subwidgets to define custom labels for each channel.

<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

This example uses the RecentlyAnsweredQuestions widget to demonstrate changing widget labels.

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

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

  3. Navigate to the widget’s Documentation page and determine the attribute names for the labels you want to edit.

  4. Edit the code to add the label attributes you want to change.

    <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.

How You Change Reports in Widgets

You can edit the widgets on a page to change the reports used by that page.

When a page includes search navigation with an answers report, multiple widgets are used to control the functionality. For example, the Published Answers page includes these widgets:

  • 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)

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. All widgets that make up these elements must call the same report using one of these 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. This is the attribute format: report_id="194"

The hide_when_no_results Attribute

The hide_when_no_results attribute prevents a 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"/>

How You Define the Number of Search Results

You can define the number of displayed search results.

The per_page attribute controls how many results are shown on a page. This example code limits them to 5.

<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.

How You Build Widgets

You can create a new widget using the Customer Portal 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).

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 based on your answers to a series of questions about the widget you want to create. The generated code includes placeholders for additional code you’ll add to define the new custom widget. This reduces the amount of code you must write and minimizes the possibility of errors.

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 these 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.

Considerations for Extending or Overriding the View

You can extend or override a view from the parent widget when modifying a new widget.

If you indicate that the new widget will modify the view of the parent widget, 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 widget view instead of overriding it. When you extend a standard widget 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 the view for widget A to create the view for custom widget B, you can also extend the view of widget B to create the view for widget C. The parent view can be extended in the child view, which can be extended for the grandchild, and then the great-grandchild.

Create a Widget

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

  1. Enter 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. Enter the name (without spaces) of the custom widget in the What Is Its Name field.

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

  6. Click Continue.

  7. Answer the widget components questions.

    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 field information:

    Table Custom Widget Attributes

    Attribute Description
    Attribute name Enter 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 Enter a description for the attribute. This text describes the attribute when you click Documentation on the custom widget page.
    Options Click Add Option and enter 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 Enter 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 field information.

    Table Additional Custom Widget Details

    Field Description
    Widget description Enter 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.

To use the new widget in the staging environment, you must select Copy to Staging in the first step and push the widget version change in the second step of Stage Customer Portal Pages.

Create a Widget by Extending the Functionality of a Widget

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

  1. Enter 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. Enter 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. Enter the name (without spaces) of your new custom widget in the What Is Its Name field.

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

  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 if you will create a controller file for the widget.
    Will it be doing any of its own AJAX-handling? Select Yes if the widget’s controller will handle AJAX requests.
    Does this widget modify the parent widget’s view? Select Yes 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 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 Yes if the widget will include the CSS style attributes defined for its parent.
    Does this widget have its own JavaScript? Select Yes if the widget will extend the JavaScript functions defined for its parent.
    YUI Modules The Add Module link is active if you enable JavaScript functions. By default, several YUI modules are already included on each page.
    JavaScript templates too? Select Yes if the widget will modify blocks of content within the parent’s JavaScript view.
  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 X.

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

    Table Custom Widget Attributes

    Attribute Description
    Attribute name Enter 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 Enter a description for the attribute. This text describes the attribute when you click Documentation on the custom widget page.
    Options Click Add Option and enter 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 Enter 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 field information.

    Table Additional Custom Widget Details

    Field Description
    Widget description Enter 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.

Widget Builder Files

The Widget Builder generates a number of files.

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 these 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.

Preview a Custom Widget

This procedure demonstrates including a screen capture of a custom widget in the widget definition.

  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 render.

Input and Output Widgets

Input widgets let customers enter information and output widgets let you display database content.

When you place 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, community question, community question comment, and community user fields as they are defined in the Connect PHP API.

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, this 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

Input widgets allow customers to enter information.

These 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. Enter <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.

These 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. Enter <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.

Text Input Field Lengths

Use the maximum_length and minimum_length attributes to restrict the number of characters entered in a text field.

You can add these attributes to the TextInput and RichTextInput widgets. Many fields have a maximum field size defined in their database definitions. You can view these 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" />

Field Hints

You can add a hint to help customers complete a field.

If the field is created using the CustomAllInput, DateInput, FormInput, ProductCategoryInput, SelectionInput, or TextInput widget, you can use the hint attribute. 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;
}

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.

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.

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.)

This example uses field validation 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 Field Options

Contact, incident, and answer custom fields can be input and displayed on the customer portal.

Custom fields are defined on the administration interface and have these options.
  • Read-only—meaning they can only be displayed as an output widget.

  • Read/Write—meaning they can be used for both input and output fields.

  • Required—the field is mandatory on the customer portal.

  • Hint—providing additional information to customers who are entering data in the field.

  • Default value—automatically populating the field if the data type is integer, menu, text area, text field, yes/no, or opt-in.

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.

Input Field Values

Input fields are either blank or populated with a value, depending on how you define the field.

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.

  1. Open /views/pages/ask.php.

  2. Locate this code. These lines are not sequential.

    <rn:widget path="input/FormInput" name="Incident.Subject" required="true" />
    ...
    <rn:widget path="input/FormInput" name="Incident.Subject" required="true" initial_focus="true"/>
    One FormInput field is defined for the condition when customers are not logged in, and the second is for logged-in customers.
  3. Add the default_value attribute to the FormInput widget to define the value in the Subject field.

    <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 with preset values.

  1. Open /views/pages/ask.php.

  2. Locate this code.

    <rn:widget path="input/ProductCategoryInput" name="Incident.Product"/>
  3. Add the default_value attribute to the ProductCategoryInput widget.

    <rn:widget path="input/ProductCategoryInput" name="Incident.Product" default_value="21,47" />
  4. Locate this code.

    <rn:widget path="input/ProductCategoryInput" name="Incident.Category" />
  5. Add the default_value attribute to the widget.

    <rn:widget path="input/ProductCategoryInput" name="Incident.Category" default_value="98"/>
  6. Save the file.

Set a Custom Date/Time Value

You can set a value for a custom date or date/time field.

This 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 this code to the Ask a Question page.

<rn:widget path="input/DateInput" name="Incident.CustomFields.c.answer_needed" default_value="1435920435"/>

You can use a UNIX date/time stamp converter to generate the value.

You can also enter absolute and relative dates, which the PHP strtotime( ) function will convert to a UNIX time stamp format. Absolute dates must be entered using the English date format of dd/mm/yyyy.

These values for the default_value attribute of a DateInput widget are valid, and more examples can be found at Date/Time Function strtotime.

  • Now

  • 18-12-2015

  • December 18, 2015

  • Tomorrow

  • Today + 2 months

  • First day of next month

  • Next Wed + 4 days

When adding the custom field to the page, use this code if you want the value of the field to be populated automatically, relative to the current date/time.
<rn:widget path="input/DateInput" name="Incident.CustomFields.c.answer_needed" default_value="tomorrow" />
Note: The standard date/time fields are read-only, so you cannot set values for those.

Set a Yes/No Field

The SelectionInput widget is used to display Yes/No radio buttons for a custom field.

This 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 this code 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.

<rn:widget path="input/SelectionInput" name="Contact.CustomFields.c.current_cust"
display_as_checkbox="true" />

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.

Set a Menu Option

You can populate menu options on a drop-down menu by modifying the custom field 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 this code to the page.

<rn:widget path="input/FormInput" name="Incident.CustomFields.c.urgency" default_value="1"/>

Populate the Subject Field Using a URL

This example defines a default value for an input field in the URL that opens the page containing the field.

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. 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.
  1. Open /views/templates/standard.php.

  2. Edit the navigation tab for the Ask a Question page.

    1. Locate this 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.

      <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.

POST Parameters and Populating Fields

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.

How You Display Values without Labels

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 can use the rn: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, you can use this code 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 Edits to Fields After Login

You can change input fields on the Account Settings page so customers can edit them.

  1. Open /views/pages/account/profile.php.

  2. Locate this 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.

    <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.

Add a System Attribute Using the FormInput Widget

This example uses the FormInput widget to add a contact system attribute to the Ask a Question page asking customers if they have used a previous version of the product.

  1. Open /views/pages/ask.php.

  2. Locate <rn:widget path="input/FileAttachmentUpload"/>.

  3. Add this code after <rn:widget path="input/FileAttachmentUpload"/>.

    <rn:widget path="input/FormInput" name="Contact.CustomFields.CO.usedpreviousproducts"
    always_show_hint="true" hint="Have you used a previous version of this product?" />
    <rn:widget path="input/FileAttachmentUpload"/>
    <rn:widget path="input/FormInput" name="Contact.CustomFields.CO.usedpreviousproducts"
    always_show_hint="true" hint="Have you used a previous version of this product?" />
  4. Save the file.

Add a System Attribute Using the DataDisplay Widget

This example adds a Product Registration section to the Account Overview page.

  1. Open /views/pages/account/overview.php.

  2. Add this code where you want it to appear on the page.

    <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.

Add a System Attribute Using Regular Expressions

This example adds an RMA system attribute to incidents.

For 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.
  1. Open the page where you want to add the system attribute.

  2. Add the FormInput widget to the code so it appears where you want it to on the page.

    <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.
  3. Add the hint directly to the field name.

    <rn:widget path="input/FormInput" name="Incident.CustomFields.CO.RMA" label_name=
    validate_on_blur="true" label_input="RMA (expected input: AA-#####)" />
  4. 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. Customers who have correctly entered a CAPTCHA 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.

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 CAPTCHA Validation on Submit

This example demonstrates setting a CAPTCHA validation for all form submittals.

  1. Open the page containing the form where you want a CAPTCHA to always appear.

  2. Locate the code for the FormSubmit widget, <rn:widget path="input/FormSubmit".

  3. Edit the FormSubmit widget code to add the challenge_required attribute.

    <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" />
  4. 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 CAPTCHA Within a Form

This example code lets you open the CAPTCHA within a form.

  1. Open the page containing the form where you want the CAPTCHA to appear.

  2. Locate the code for the FormSubmit widget, <rn:widget path="input/FormSubmit".

  3. 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"/>
  4. Add <div id="captchaArea" class="rn_CaptchaDialog"> to the page.

    <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"/>
    
    <div id="captchaArea" class="rn_CaptchaDialog">
  5. Save the page.

Remove ClickjackPrevention from the Template

If your site runs in frames, you should remove the ClickJackPrevention widget.

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.
  1. Open customer/development/view/template/standard.php.

  2. Delete this line of code.

    <rn:widget path="utils/ClickjackPrevention"/>
  3. Save the page.

Syndicated Widgets

You can use a syndicated widget to access the Oracle knowledge base from another web page outside of your customer portal.

These are the syndicated widgets.

  • 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 review and modify the settings for a syndicated widget at https://<your_site>/ci/tags/syndicated_widgets.

The KnowledgeSyndication Widget

The KnowledgeSyndication widget provides search access to your knowledge base.

This widget acts like the search fields and reports on the Support Home and Published Answers pages of your customer portal, but you can place it on any page of your website, letting your customers search the Oracle knowledge base from any of your organization’s website pages.

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.

If you have enabled web indexing, the KnowledgeSyndication widget will also search external documents.

Add the KnowledgeSyndication Widget to a Page

The widget information page gives you everything you need to add the KnowledgeSyndication widget to any page on your website.

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.
  1. Enter https://<your_site>/ci/tags/syndicated_widgets/standard/KnowledgeSyndication to open the page for the KnowledgeSyndication widget.

  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. On the widget page, click the top Select Text button to select the code in the first box and copy the code.

  6. Paste the code into your web 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. On the widget page, click the second Select Text button and copy the code that defines the widget.

  8. Paste the copied code just below the code you pasted in step 6.

  9. Add <div_id="myDiv"></div> to the page code where you want the widget to appear.

  10. Save the page.

Configure the KnowledgeSyndication Widget

You can configure all attributes of the KnowledgeSyndication widget.

In order to return external documents from a search, you must enable web indexing.
  1. To enable external document searching, select the check box for the ext_docs attribute.

  2. To open answers in an overlay instead of a separate window, select the check box for the display_answers_in_overlay attribute.

  3. To define products for a KnowledgeSyndication widget report, enter the product ID in the field for the p attribute.

  4. To define categories for a KnowledgeSyndication widget report, enter 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, enter 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, enter 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, enter 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,” enter the new label in the field for the label_correction attribute.

  17. To edit the label for recommended documents, enter the new label in the field for the label_documents attribute.

  18. To edit the label for the More Results link, enter the new label in the field for the label_more_results attribute.

  19. To edit the No Results Found label, enter the new label in the field for the label_no_results attribute.

  20. To edit the related searches label, enter the new label in the field for the label_related_searches attribute.

  21. To edit the Search button label, enter the new label in the field for the label_search_button attribute.

  22. To edit the Created label, enter the new label in the field for the label_created attribute.

  23. To edit the Updated label, enter 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, enter 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, enter a numerical value in the field for the truncate_size attribute.

  26. To change the number of displayed answers from the default of ten, enter an integer in the field for the number_answers attribute.

  27. To edit the div element, enter 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.

How the KnowledgeSyndication Widget Determines Search Results

The KnowledgeSyndication widget can use context-sensitive information on a page to determine what answers to return.

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.

Inlays and Customer Portal

Inlays are the next generation of syndicated widgets.

These are objects that you can place on any web page to invoke specific customer service interactions. They are packaged units of functionality, such as chat interactions, viewing knowledge articles and service request creation. The name Inlays refers to the design of these components and that you can inlay them into any web page, including your external web site, seamlessly.

Inlays are single version, so there is no need to migrate or update your current Inlay implementation. The release cycle for Inlays is typically every 2-4 weeks.

For more information, see the inlay documentation at Oracle OIT Registry.

Polling Widgets

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.

Customer visits that result from clicking the PollingSyndication widget are tracked as B2C Service Feedback visits, not as Customer Portal visits.

Polling Widget Attributes

These 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 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.

  1. Open the file for the page where you want to place the Polling widget.

  2. Enter the code for the Polling widget in the location where you want the widget to appear on the page.

    This is an example of the most basic widget code. 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

This example describes the process for adding the PollingSyndication widget to an external page.

  1. Enter 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.

  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. On the widget page, 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. On the widget page, 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. On the widget page, click the third Select Text, copy the code, and paste it where you want the widget to appear.

  11. Save the page.

Add the Survey ID to the Polling Widget

You can specify the survey used by the polling 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.
  1. Click Surveys.

  2. Double-click Surveys Explorer.

  3. Click Choose Details.

  4. Select ID.

  5. Click OK.

  6. Add the survey_id attribute to the widget code.

    <rn:widget path="surveys/Polling" survey_id="5" />

Configure Modal Polls for the Polling Widget

This procedure demonstrates enabling and configuring the polling widget for modal polls.

  1. Add the modal attribute to the widget code and set it to true.

    <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.

    <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.

    <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 attribute to the widget code.

    <rn:widget path="surveys/Polling" survey_id="5" modal="true" seconds="3" />

Configure Modal Polls for the PollingSyndication Widget

This procedure demonstrates enabling and configuring the PollingSyndication widget for modal polls.

  1. With the page for the PollingSyndication widget open, scroll to the Configure Widget section.

  2. Select the modal attribute check box.

  3. To offer the poll to only a percentage of your customers, find the frequency attribute and enter a percentage value in the field.

  4. To trigger the dialog on the event defined in evt_showPoll, select the poll_logic attribute check box.

  5. To trigger the dialog after the page has been open a specified number of seconds, find the seconds attribute and enter the number of seconds in the text field.

Use Poll Logic with Widgets

You can use a JavaScript event to display the polling widget when modal polls are enabled.

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.
  1. Add the poll_logic attribute to the widget code.

    <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

You can change the type of chart the page uses to display the poll results of a choice type question.

  1. To display a vertical bar chart, add the chart_type attribute to the widget code and set its value to vertical_bar.

    <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.

    <rn:widget path="surveys/Polling" survey_id="5" chart_type="pie" />
  3. To remove the display, add the chart_type attribute to the widget code and set its value to none.

    <rn:widget path="surveys/Polling" survey_id="5" chart_type="none" />
  4. 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 chart_type attribute.

    4. Select vertical_bar, pie, or simple.

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 Test Mode for Polling Widgets

You can test the polling widgets without contaminating your poll results. No statistics are collected in test mode.

  1. Add the test attribute to the widget code and set it to true.

    <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.

Standard Widgets

There are widgets included in both the standard and mobile customer portal reference implementations.

Widgets Not Used in Reference Implementation

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 these 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 these 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 these 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 subproducts or subcategories.
products/detail
mobile/home
mobile/products/detail

Widgets Not Used in Reference Implementation

A number of widgets are available for you to use in your Customer Portal site.

These 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

You can set date drop-down menu values.

By default, drop-down date menus display the current year as the highest year option.
  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, enter that year in the Value field.

    3. To set an offset (for example, five years from this year), enter the offset value in the Value field. In this example, type +5.

  3. Click Save.

Add an Incident Date Field

This example demonstrates adding a custom field, on the Ask a Question page, letting customers tell you how quickly they need an answer to their submitted question.

  1. Open Custom Fields in Configuration > Database.

  2. Click Incident.

  3. Click New.

  4. In the Name field, enter Answer Needed By.

  5. Click Data Type and select Date Field.

  6. In the Column Name field, enter answer_needed.

    Note: The Column Name 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 Widgets

You can view a list of obsolete custom widgets.

  1. On the Customer Portal Administration page, select Widgets.

  2. Select Widgets Not In Use.

    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.

Logging in to the Customer Portal

How Customers Log in to the Customer Portal

Your customers can log in directly or they can log in through an external site that verifies their identity.

These are 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 B2C Service 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.

    • Encrypted pass-through authentication—Data encryption transmits customer information even more securely through the customer portal page URL using one of several encryption options. You can configure encrypted PTA so your customers can log in directly to the customer portal as well as log in with pass-through authentication from your external site. You also have the option of requiring customers to log out through the external site or allowing them to log out from the customer portal. Your Oracle account manager can provide information about encrypted PTA.

  • SAML 2.0 open login (single sign-on)—Instead of logging in to the customer portal with their B2C Service user name and password, customers can log in to a third-party identity provider, such as PingFederate or Windows ADFS, which authenticates their identity. Then they select a connection to the customer portal. The identity provider verifies their login, sends an assertion to the customer portal, which verifies the signature and (if successful) logs the customer in.

Remove the Password Field Using the Configuration Setting

You can turn off the password requirement.

If you remove the Password field using this procedure, customers who already have passwords will still be able to log in with only their user name.
  1. Locate EU_CUST_PASSWD_ENABLED under RightNow User Interface/General.

  2. Click the Value drop-down menu and set the value to No.

  3. Click Save.

Remove the Password Field by Editing Code

You can remove the password requirement from your Customer Portal pages.

If you remove the Password field using this procedure, you will override the value of the EU_CUST_PASSWD_ENABLED configuration setting. Customers who do not have a value in the password field in the database will still be able to log in with only their user name, but customers who have a value in the password field in the database will not be able to log in.
  1. Open one of the following files:

    • /views/templates/standard.php
    • /views/templates/mobile.php
  2. Locate this text, which should be in the last lines of code for the first AccountDropdown widget.

    sub:input_Contact.NewPassword:label_input="#rn:msg:PASSWORD_LBL#" />
  3. Add the disable_password attribute to the widget and set the value to true.

    The last line of code will be:
    disable_password="true"/>
  4. Save the file.

Edit Message Bases on the Login Window

Use this process to edit read-only messages set in the system message bases.

  1. Open one of these template files:

    • /views/templates/standard.php
    • /views/templates/mobile.php
  2. To edit the “Please log in to continue” heading, add the label_dialog_title attribute to the first instance of the AccountDropdown widget and set the value to the new message.

    label_dialog_title="Log in to access product information"/>
  3. To edit the “Quickly log in or create an account…” message, add the label_open_login attribute to the first AccountDropdown widget and set the value to the new message.

    label_open_login_intro="Speed up your login by using one of these accounts"/>
  4. To edit the “Create an Account” message on the button, add the label_create_account_button attribute to the first AccountDropdown widget and set the value to the new message.

  5. To edit the “Forgot your username or password?” message, add the label_assistance attribute to the first AccountDropdown widget and set the value to the new message.

  6. To edit any other label on the page, find its corresponding attribute on the widget information page for the LoginDialog widget, add the attribute to the AccountDropdown widget, and set its value to the new message.

  7. Save the file.

Edit the Create an Account Form

You cannot add or remove fields on the Create an Account form, but you can change their labels and whether the field is required.

  1. Open one of the template files:

    • /views/templates/standard.php
    • /views/templates/mobile.php
  2. To edit any of the field labels, edit the label attribute of the associated field on the first instance of the AccountDropdown widget and set the value to the new message.

    sub:input_Contact.Login:label_input="Account Name"
  3. To not require an email address or first name, remove the line of code from the first AccountDropdown widget that contains the required attribute.

    sub:input_Contact.Name.First:required="true"
    Note: If you do not require a user name, the customer will see a message that they do not have permission to create a user, so you should not remove the requirement for that field. The Display Name and Last Name fields are required by default. Even if you remove the requirement for the last name or add the required attribute to the display name code and set it to false, those fields will still be required.
  4. Save the file.

Edit the Password Label on the Create an Account Form

You can edit the label on the Create an Account form.

If you set a minimum password length that customers must enter, passwords are automatically required.
  1. Open /views/templates/standard.php.

  2. Locate sub:input_Contact.NewPassword:label_input="#rn:msg:PASSWORD_LBL#" in the first AccountDropdown widget.

  3. Edit the label_input attribute to define password length information.

    sub:input_Contact.NewPassword:label_input="Password (8 characters minimum)"
  4. Save the file.

Edit the Create an Account Page

You can edit the Create an Account page to meet the needs of your organization.

  1. Open one of the following files:

    • /views/pages/utils/create_account.php
    • /views/pages/mobile/utils/create_account.php
  2. To add a global opt-in field on the Create an Account page, follow these steps.

    1. Locate the following line of code.

      <rn:widget path="input/CustomAllInput" table="Contact"/>
    2. Add a FormInput widget after the line you located in step A to ask customers if they want to be on your mailing list.

      The following sample code adds the widget and also changes the label from the default value of Global Opt-In.
      <rn:widget path="input/FormInput" name="Contact.MarketingSettings.MarketingOptIn"
       label_input="Can we add you to our mailing list?" />
  3. To enable an email confirmation loop, modify the CP.EmailConfirmationLoop.Enable setting.

    1. Open the cp/customer/development/config/siteConfig.json file.

    2. Set the CP.EmailConfirmationLoop.Enable to 1.

  4. Save the file.

Add Fields on the Create an Account Page

You might want to add alternate email address fields and the customer’s mailing address to the page.

  1. Open one of these files:

    • /views/pages/utils/create_account.php
    • /views/pages/mobile/utils/create_account.php
  2. To add a contact field, add a line of code that calls the FormInput widget.

    To find the names of all the contact fields you can use for the FormInput widget, click Framework > Business Objects on the Customer Portal Administration site.

    <rn:widget path="input/FormInput" name="Contact.Emails.ALT1.Address"
     label_input="Alternate Email 1" />
    <rn:widget path="input/FormInput" name="Contact.Emails.ALT2.Address"
     label_input="Alternate Email 2" />
    <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.StateOrProvince"
     label_input="State or Province" />
    <rn:widget path="input/FormInput" name="Contact.Address.PostalCode" />
  3. To allow the entry and display of multiple lines in the Street field, add the textarea attribute to the FormInput widget.

    <rn:widget path="input/FormInput" name="Contact.Address.Street" textarea="true" />
  4. To add an organization login and password so your customers can be associated with an organization, add this code.

    <rn:widget path="input/FormInput" name="Contact.Organization.Login"
     label_input="Organization Login" />
    <rn:widget path="input/FormInput" name="Contact.Organization.NewPassword"
     label_input="Organization Password" />
  5. To make the organization login and password required fields, replace the code in the previous step with this code.

    <rn:widget path="input/FormInput" name="Contact.Organization.Login"
     required="true" label_input="Organization Login" />
    <rn:widget path="input/FormInput" name="Contact.Organization.NewPassword"
     required="true" label_input="Organization Password" />
  6. Save the file.

Remove Fields on the Create an Account Page

Removing the associated widget will remove the field from the page.

  1. Open one of the following files:

    • /views/pages/utils/create_account.php
    • /views/pages/mobile/utils/create_account.php
  2. To remove the Email Address field, delete 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. To remove the Username field, delete the following line of code.

    <rn:widget path="input/FormInput" name="Contact.Login" required="true" validate_on_blur="true"
     label_input="#rn:msg:USERNAME_LBL#" hint="#rn:msg:TH_PRIVATE_S_LOG_IN_SITE_JUST_WANT_MSG#"/>
  4. To remove the Display Name field, delete the following line of code.

    <rn:widget path="input/DisplayNameInput" label_input="#rn:msg:DISPLAY_NAME_LBL#"
     hint="#rn:msg:TH_PUBLIC_THATS_DISP_ALONG_COMMENTS_MSG#"/>
  5. To remove the Password and Verify Password fields, delete the following lines of code.

    <rn:condition config_check="EU_CUST_PASSWD_ENABLED == true">
         <rn:widget path="input/FormInput" name="Contact.NewPassword" require_validation="true"
     label_input="#rn:msg:PASSWORD_LBL#" label_validation="#rn:msg:VERIFY_PASSWD_LBL#"/>
    </rn:condition>
  6. To remove the First Name and Last Name fields, delete the following lines of code.

    <rn:condition config_check="intl_nameorder == 1">
        <rn:widget path="input/FormInput" name="Contact.Name.Last"
     label_input="#rn:msg:LAST_NAME_LBL#" required="true"/>
        <rn:widget path="input/FormInput" name="Contact.Name.First"
     label_input="#rn:msg:FIRST_NAME_LBL#" required="true"/>
        <rn:condition_else/>
            <rn:widget path="input/FormInput" name="Contact.Name.First"
     label_input="#rn:msg:FIRST_NAME_LBL#" required="true"/>
            <rn:widget path="input/FormInput" name="Contact.Name.Last"
     label_input="#rn:msg:LAST_NAME_LBL#" required="true"/>
    </rn:condition>
  7. To remove all contact custom fields with end-user visibility, delete the following line of code.

    <rn:widget path="input/CustomAllInput" table="Contact"/>
  8. Save the file.

Edit the Password Label on the Create an Account Page

You can edit the password label on the Create an Account page.

  1. Open one of the Create an Account page files:

    • /views/pages/utils/create_account.php
    • /views/pages/mobile/utils/create_account.php
  2. Locate <rn:widget path="input/FormInput" name="Contact.NewPassword" require_validation="true" label_input="#rn:msg:PASSWORD_LBL#" label_validation="#rn:msg:VERIFY_PASSWD_LBL#"/>.

  3. Edit the label_input attribute of the FormInput widget to define password length information.

    <rn:widget path="input/FormInput" name="Contact.NewPassword" require_validation="true"
     label_input="Password (8 characters minimum)" label_validation="#rn:msg:VERIFY_PASSWD_LBL#"/>
  4. Save the file.

Edit the Password Label on the Change Your Password Page

You can edit the label on the Change Your Password page.

  1. Open one of the change password files:

    • /views/pages/account/change_password.php
    • /views/pages/mobile/account/change_password.php
  2. Locate <rn:widget path="input/PasswordInput" name="Contact.NewPassword" require_validation="true" require_current_password="true" label_input="#rn:msg:PASSWORD_LBL#" label_validation="#rn:msg:VERIFY_PASSWD_LBL#" initial_focus="true"/>.

  3. Edit the label_input attribute of the PasswordInput widget to define password length information.

    <rn:widget path="input/PasswordInput" name="Contact.NewPassword" require_validation="true"
     require_current_password="true" label_input="Password (8 characters minimum)"
     label_validation="#rn:msg:VERIFY_PASSWD_LBL#" initial_focus="true"/>
    Note: Even if you leave the required attribute set to false, setting a minimum password length on the administration interface causes the configuration setting to override the attribute.
  4. Save the file.

Prevent User Name Enumeration

This process adds barriers to the Create an Account page, preventing the automated harvesting of user names.

User name enumeration is an automated attempt to retrieve user names in your database for malicious purposes.
  1. Open /views/pages/utils/create_account.php.

  2. Locate these lines 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#"/>
        <rn:widget path="input/FormInput" name="Contact.Login" required="true"
         validate_on_blur="true" 
         label_input="#rn:msg:USERNAME_LBL#"hint="#rn:msg:TH_PRIVATE_S_LOG_IN_SITE_JUST_WANT_MSG#"/>
  3. Remove the validate_on_blur attribute for both widgets.

  4. Locate this line of code.

    <rn:widget path="input/FormSubmit" label_button="#rn:msg:CREATE_ACCT_CMD#"
     on_success_url="/app/account/overview" error_location="rn_ErrorLocation"/>
  5. Edit the code for the Create Account button (the FormSubmit widget) to add the challenge_required attribute.

    <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" />
  6. Save the file.

Overview of Open Login

Open login lets your customers log in to the customer portal by logging in through an external service provider where they already have an account.

By using an external service to authenticate customers instead of requiring them to create a separate customer portal account, you offer your customers a faster, more convenient experience. The default login and Create an Account form contain four OpenLogin widgets, each associated with an external service provider: Facebook, Twitter, Google, and Yahoo. When customers click the Create an Account button, the form opens. Instead of completing the contact information fields on the page to create their account, they can click a widget associated with an external provider where they already have an account. After logging in to the external account, an account is created for them automatically in B2C Service.

Note: If you are opening your customer portal pages in iFrames, you should not use open login. Open login directs customers to a third-party site that then redirects them to the customer portal after verification. Because iFrames do not display a URL, customers cannot verify that the third-party login site is legitimate, and security issues are possible. Additionally, some open login providers do not allow their login page to be opened in an iFrame.

Customers who click the Facebook, Twitter, Google, or Yahoo OpenLogin widgets see a message that tells them to log in to the external service and explains that they will then be redirected to your customer portal and logged in. When they click the button above the message, they are taken to the external site to log in (if they are not already logged in). The site asks for permission to send their email address and possibly their name, depending on the site, back to the customer portal. Customers who allow the transfer of information to B2C Service are redirected to the customer portal and logged in automatically.

How Open Login Works

The Customer Portal uses the web industry protocols OAuth and OpenID to let customers log in from their existing accounts on external services.

To allow customers to log in using Facebook, Twitter, and Google, you must define public IDs and private keys for the applications. Additionally, to use Facebook as an open login provider, you must migrate to OAuth 2.0, process a signed_request parameter, and obtain an SSL certificate. The Customer Portal supports OAuth 1.0 – 2.0.

OAuth lets customers grant authorization for your customer portal to access their information from external sites where they have existing accounts.

OpenID lets customers log in to the site, which then confirms their identity to your customer portal, and also lets them specify what customer information can be shared.

Note: Customer information includes, at a minimum, an email address, but may contain other information, such as the customer’s full name. The specific information that is shared depends on which external service is providing the customer information.

Open Login Account Creation

When customers log in to the customer portal using open login, these events occur the first time they log in from the selected service provider.

  1. The customer attempts to access a password-protected customer portal page and is directed to the login window. Or, the customer clicks the Sign Up link, opening the Create an Account page.
  2. The customer selects one of the open login options.
  3. If the customer is not logged in to the external service provider, the third-party login page opens to allow login, and the provider verifies the customer’s identity.
  4. The external service lets the customer know that the customer portal is requesting specific account information and asks the customer for permission to share that information.
  5. When the customer grants permission for the external site to share information with the customer portal, the site gives the customer’s information to B2C Service.
  6. A contact record for the customer is created in the database using the email address and, if available, the customer’s name. The contact record uses the customer’s email address as the login/username with a null password.
  7. The customer is logged in to the customer portal.

Open Login Process

The following events occur when a customers has logged in to the customer portal using one of their external service accounts but try to use open login again.

  1. The customer tries to access the customer portal by logging in through an external site.
  2. The external site verifies the customer and sends the customer’s information to the customer portal. If the customer previously gave permission for more than one-time use, this step occurs automatically and the customer does not see the provider page, but is logged in to the customer portal and directed to the Support Home page.
  3. The customer portal looks up the customer using the account’s user ID (provided by Twitter and Facebook and stored as contact2channel_type.userid) or the OpenID URL (used by Google, Yahoo, and other OpenID providers, stored as openid_account.openid_url).
  4. The customer portal then checks the customer’s login, which should still be the email address, as it was when the contact record was created. If the login is blank for any reason (for example, a staff member deleted it), the login field is repopulated with the customer’s email address.
  5. The customer’s email address, as received from the external site, is checked against the email address in the database. If the two addresses do not match, the contact record is updated with the email address from the external site. However, the customer’s login, which is the original email address, is not updated.
  6. If the customer does not have a first or last name in the database but that information is received from the external service, the first name and last name fields are updated in the database.

The process is slightly different when customers use an open login from a different external site than the one used to create the contact record in B2C Service. If the open login account the customer is using on this visit does not match other open logins associated with the contact record, the account’s OpenID URL is added to the contact record. By default, customers who use external login to access your customer portal, whether through open login or pass-through authentication, cannot edit their account information on the Account Settings (profile.php) page. If you remove the external login condition on the FormSubmit button—which we recommend against doing—you must also add the allow_external_login_updates attribute before the Save Changes button is available to customers.

Change the Open Login Options

You can change the open login options or remove them entirely.

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

  2. Locate sub:input_Contact.NewPassword:label_input="#rn:msg:PASSWORD_LBL#" />, which should be in the last lines of code for the first instance of the AccountDropdown widget.

  3. Add the open_login_providers attribute to the widget and set the value to the providers you want to list.

     open_login_providers="facebook,google"/>
  4. Save the file.

Remove the Open Login Options

Remove the open login options to restrict customers from using another provider to login to your customer portal.

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

  2. Locate this text, which should be in the last lines of code for the first instance of the AccountDropdown widget.

    sub:input_Contact.NewPassword:label_input="#rn:msg:PASSWORD_LBL#" />
  3. Add the open_login_providers attribute to the widget and set the value to null.

  4. Add the label_open_login_intro attribute and set its value to null.

    open_login_providers="" label_open_login_intro=""/>
  5. Save the file.

Remove All OpenLogin Widgets

This example removes all OpenLogin widgets from the default Create an Account page requiring customers to create a new user account.

  1. Open a Create an Account page file:

    • /views/pages/utils/create_account.php
    • /views/pages/mobile/utils/create_account.php
  2. Delete the following lines of code.

    <div class="rn_ThirdPartyLogin">
       <p class="rn_ServicesMessage">#rn:msg:SERVICES_MSG#</p>
       <p class="rn_LoginUsingMessage">#rn:msg:LOG_IN_OR_REGISTER_USING_ELLIPSIS_MSG#</p>
          <div class="rn_OpenLogins">
             <rn:widget path="login/OpenLogin"/>
             <rn:widget path="login/OpenLogin"
              controller_endpoint="/ci/openlogin/oauth/authorize/twitter"
              label_service_button="Twitter"
              label_process_explanation="#rn:msg:CLICK_BTN_TWITTER_LOG_TWITTER_MSG#"
              label_login_button="#rn:msg:LOG_IN_USING_TWITTER_LBL#"/>
             <rn:widget path="login/OpenLogin"
              controller_endpoint="/ci/openlogin/openid/authorize/google"
              label_service_button="Google"
              label_process_explanation="#rn:msg:CLICK_BTN_GOOGLE_LOG_GOOGLE_VERIFY_MSG#"
              label_login_button="#rn:msg:LOG_IN_USING_GOOGLE_LBL#"/>
             <rn:widget path="login/OpenLogin"
              controller_endpoint="/ci/openlogin/openid/authorize/yahoo"
              label_service_button="Yahoo"
              label_process_explanation="#rn:msg:CLICK_BTN_YAHOO_LOG_YAHOO_VERIFY_MSG#"
              label_login_button="#rn:msg:LOG_IN_USING_YAHOO_LBL#"/>
             <rn:widget path="login/OpenLogin"
              controller_endpoint="/ci/openlogin/openid/authorize"
              label_service_button="Wordpress" openid="true"
              preset_openid_url="http://[username].wordpress.com"
              openid_placeholder="[#rn:msg:YOUR_WORDPRESS_USERNAME_LBL#]"
              label_process_explanation="#rn:msg:YOULL_LOG_ACCT_WORDPRESS_TAB_ENTER_MSG#"
              label_login_button="#rn:msg:LOG_USING_YOUR_WORDPRESS_ACCOUNT_LBL#"/>
             <rn:widget path="login/OpenLogin"
              controller_endpoint="/ci/openlogin/openid/authorize"
              label_service_button="OpenID" openid="true"
              openid_placeholder="http://[provider]"
              label_process_explanation="#rn:msg:YOULL_OPENID_PROVIDER_LOG_PROVIDER_MSG#"
              label_login_button="#rn:msg:LOG_IN_USING_THIS_OPENID_PROVIDER_LBL#"/>
          </div>
    </div>
    <p class="rn_CreateAccountMessage">#rn:msg:CONTINUE_CREATING_ACCOUNT_ELLIPSIS_CMD#</p>
  3. Save the file.

Remove an OpenLogin Widget

You can remove the OpenLogin widget associated with specific external providers.

  1. Open a Create an Account page file:

    • /views/pages/utils/create_account.php
    • /views/pages/mobile/utils/create_account.php
  2. Identify the widgets you want to remove.

    The code <rn:widget path="login/OpenLogin"/> is for the Facebook widget. All other widgets include the provider’s name in the controller_endpoint, label_service_button, label_process_explanation, and label_login_button attributes.
    For example, here is the widget to log in with a Google account as it appears on the Create an Account page.
    <rn:widget path="login/OpenLogin"
     controller_endpoint="/ci/openlogin/openid/authorize/google"
     label_service_button="Google"
     label_process_explanation="#rn:msg:CLICK_BTN_GOOGLE_LOG_GOOGLE_VERIFY_MSG#"
     label_login_button="#rn:msg:LOG_IN_USING_GOOGLE_LBL#"/>
  3. Delete the lines of code associated with open login providers you want to remove from the page.

  4. Save the page.

Change Labels on OpenLogin Widgets

This example demonstrates editing the labels on the Google OpenLogin widget.

  1. Open one of these files:

    • /views/templates/standard.php
    • /views/templates/mobile.php
  2. Locate sub:input_Contact.NewPassword:label_input="#rn:msg:PASSWORD_LBL#" />, which should be in the last lines of code for the first instance of the AccountDropdown widget.

    1. To change the label on the login button, add the label_login_button attribute to the widget and set the value to the new message.

      sub:openlogin_google:label_login_button="Use Google to log in now"/>
    2. To change the label that explains the process to customers, add the label_process_explanation attribute and set the value to the new message.

      sub:openlogin_google:label_process_explanation="Google will verify you and log you in instantly."
    3. To change the “What will happen:” label in the explanation area, add the label_process_header attribute and set the value to the new message.

      sub:openlogin_google:label_process_header="Why it is okay to do this" />
    4. To edit the email labels that appear when the service provider authenticates the customer but does not provide the customer’s email address, add any of the following widget attributes to the code: label_email_address, label_email_prompt, label_email_prompt_cancel_button, label_email_prompt_submit_button, and label_email_prompt_title.

      sub:openlogin_google:label_email_prompt="We’ll get you started just as soon as you enter your email address." />
    5. To change the text label, add the label_service_button attribute and set the value to the new message.

      sub:openlogin_google:label_service_button="Google Login" />
  3. Save the file.

How Contacts are Created in the Database

B2C Service creates contact records with information passed from the external service.

When the customer portal receives the customer’s email address from the external provider, it creates a contact record in the Oracle database. (If the email address is not received, a contact cannot be created and customers see a message that asks them for their email address or lets them know an account was not created.) If the customer’s name has been transferred from the external provider, that information is also added to the contact record. The Login field of the record on the agent desktop (which is the Username field on the customer portal) is populated with the customer’s email address, and the password is null. Customers whose contact records have been disabled on the agent desktop cannot log in through open login.

Customers can continue to log in through open login with a null password, but they cannot log in to the customer portal directly until they set a password using the standard customer portal protocol. Customers who log in through open login can create a password on the customer portal by clicking the Change Your Password link on the Account Settings page. They can then log in to the customer portal using their login and password, or they can continue to log in through open login.

B2C Service keeps track of all open login accounts a customer uses to prevent duplicate contact records. When a customer’s email address is provided from the external service and it matches an email address in the database, the application finds the existing contact and adds a new channel or OpenId for the customer. The database table openid_accounts keeps track of the different OpenID accounts customers use to log in by mapping OpenIDs to contact IDs.

OpenID URLs

Using the openid_placeholder attribute of the OpenLogin widget, you can preset the URL that displays and include the user name.

By default, the WordPress and OpenID widgets use the OpenID protocol and have the openid attribute set to true.

For the WordPress OpenLogin widget, you would edit the widget code to remove the preset_openid_url attribute and include:
openid_placeholder="https://openid.wordpress.com/[username]"
However, you might want the increased security by hiding the URL so the customer sees only a user name field to complete. The preset_openid_url attribute defines the URL but does not expose it on the page. The reference implementation uses these attributes to hide the URL and name the default placeholder “Your WordPress username.”
preset_openid_url="https://openid.wordpress.com/[username]"
openid_placeholder="[#rn:msg:YOUR_WORDPRESS_USERNAME_LBL#]"

Support Home Page

Remove the Search Field from Home Pages

You can remove the search field from your Customer Portal home pages.

  1. Open one of the following files:

    • /views/pages/home.php
    • /views/pages/mobile/home.php
    • /views/pages/social/home.php
  2. Delete the following code from the page.

    <div class="rn_SearchControls">
        <h1 class="rn_ScreenReaderOnly">#rn:msg:SEARCH_CMD#</h1>
        <form method="get" action="/app/results">
            <rn:container source_id="KFSearch">
                <div class="rn_SearchInput">
                    <rn:widget path="searchsource/SourceSearchField" initial_focus="true"/>
                </div>
                <rn:widget path="searchsource/SourceSearchButton" search_results_url="/app/results"/>
            </rn:container>
        </form>
    </div>
  3. Save the file.

Configure the VisualProductCategorySelector Widget

The VisualProductCategorySelector widget displays products (by default) or categories on the Support Home page.

  1. Open one of the Home page files:

    • /views/pages/home.php
    • /views/pages/mobile/home.php
  2. Locate <rn:widget path="navigation/VisualProductCategorySelector"/>.

  3. To display categories instead of products, add the type attribute.

    <rn:widget path="navigation/VisualProductCategorySelector" type="category"/>
  4. To change the default number of products or categories that are displayed, add the maximum_items attribute.

    <rn:widget path="navigation/VisualProductCategorySelector" maximum_items="12"/>
  5. To display a specific list of products or categories, add the top_level_items attribute and use the ID numbers, separated by commas, of the products or categories you want to list.

    <rn:widget path="navigation/VisualProductCategorySelector" top_level_items="12,13,6"/>
  6. Save the file.

Edit the Recent Community Discussions Section

The Support Home page displays a list of recent community discussions, generated by the RecentlyAnsweredQuestions widget, that have a best answer selection.

  1. Open one of the home page files:

    • /views/pages/home.php
    • /views/pages/mobile/home.php
  2. To customize the heading, select all code between the <h2> and </h2> tags and enter a title.

    <h2>#rn:msg:RECENT_COMMUNITY_DISCUSSIONS_LBL#</h2>
  3. To display only questions that have a best answer designated by the original author of the question, add the answer_type attribute to the widget and set its value to “author.”

    <rn:widget path="discussion/RecentlyAnsweredQuestions" show_excerpt="true" maximum_questions="5" answer_type="author"/>
  4. To display only questions that have a best answer designated by a moderator of the question, add the answer_type attribute to the widget and set its value to “moderator.”

    <rn:widget path="discussion/RecentlyAnsweredQuestions" show_excerpt="true" maximum_questions="5" answer_type="moderator"/>
  5. To change the number of displayed questions, edit the maximum_questions attribute of the widget to replace 5 with the number of questions you want to display.

    <rn:widget path="discussion/RecentlyAnsweredQuestions" show_excerpt="true" maximum_questions="5"/>
  6. To shorten the length of the displayed question excerpt from the default (and maximum) value of 256 characters, add the excerpt_max_length attribute and set the value to the length you want.

    <rn:widget path="discussion/RecentlyAnsweredQuestions" show_excerpt="true" maximum_questions="5" excerpt_max_length="100"/>
  7. To shorten the length of the displayed best answer excerpt from the default value of 150 characters, add the answer_text_length attribute and set the value to the length you want.

    <rn:widget path="discussion/RecentlyAnsweredQuestions" show_excerpt="true" maximum_questions="5" answer_text_length="100"/>
  8. To remove excerpts of questions, remove the show_excerpt attribute from the RecentlyAnsweredQuestions widget.

    <rn:widget path="discussion/RecentlyAnsweredQuestions" maximum_questions="5"/>
  9. To change the size of avatars from the default value of medium, add the avatar_size attribute to the widget and select one of the following values: none, small, large, or xlarge.

    <rn:widget path="discussion/RecentlyAnsweredQuestions" show_excerpt="true" maximum_questions="5" avatar_size="small"/>
  10. Save the file.

Add an Unanswered Questions Section

You can display a list of recent community discussions on your Support Home page.

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

  2. Add this code where you want the section to appear.

    <div class="rn_PopularSocial">
    <div class="rn_Container">
      <h2>Unanswered Questions</h2>
      <rn:widget path="discussion/RecentlyAskedQuestions" show_excerpt="true" maximum_questions="4" questions_with_comments="no_comments"/>
      <span class="rn_DiscussionsLink">
        <a href="/app/social/questions/lists/kw/*#rn:sessions#">#rn:msg:SHOW_MORE_COMMUNITY_DISCUSSIONS_LBL#</a>
      </span>
    </div>
    </div>
  3. Save the file.

Search Results Pages

Edit the Search Results Page

You can change what information displays related to published answers from the knowledge base and community discussions.

  1. Open one of the Search Results page files:

    • /views/pages/results.php
    • /views/pages/mobile/results.php
  2. Find the container that includes the SourceResultListing widget.

  3. To change the number of displayed answers from the default of five, edit the per_page attribute and set the value to the number of answers you want to display.

    <rn:container source_id="KFSearch" per_page="3">
  4. To hide the Published Answers section if no search results match, add the hide_when_no_results attribute and set it to true.

    <rn:widget path="searchsource/SourceResultListing"
     label_heading="#rn:msg:PUBLISHED_ANSWERS_LBL#" hide_when_no_results="true" />
  5. To disable search term highlighting in the Published Answers section, add the highlight attribute and set it to false.

    <rn:widget path="searchsource/SourceResultListing"
     label_heading="#rn:msg:PUBLISHED_ANSWERS_LBL#" highlight="false" />
  6. To truncate the length of published answers to something other than the default value of 200 characters, add the truncate_size attribute and set it to the value you want.

    <rn:widget path="searchsource/SourceResultListing"
     label_heading="#rn:msg:PUBLISHED_ANSWERS_LBL#" truncate_size="100" />
  7. To change the number of community discussions from the default of five, change the per_page attribute and set the value to the number of discussions you want to display.

    <rn:container source_id="SocialSearch" per_page="8">
  8. To remove dates from community discussions, add the show_dates attribute and set its value to false.

    <rn:widget path="searchsource/SocialResultListing"
     label_heading="#rn:msg:RESULTS_FROM_THE_COMMUNITY_LBL#"
     more_link_url="/app/social/questions/list" show_dates="false"/>
  9. To hide the Results from the Community section if no search results match, add the hide_when_no_results attribute and set it to true.

    <rn:widget path="searchsource/SocialResultListing"
     label_heading="#rn:msg:RESULTS_FROM_THE_COMMUNITY_LBL#"
     more_link_url="/app/social/questions/list" hide_when_no_results="true" />
  10. To disable search term highlighting in the Results from the Community section, add the highlight attribute and set it to false.

    <rn:widget path="searchsource/SocialResultListing"
     label_heading="#rn:msg:RESULTS_FROM_THE_COMMUNITY_LBL#"
     more_link_url="/app/social/questions/list" highlight="false" />
  11. To truncate the length of community questions to something other than the default value of 200 characters, add the truncate_size attribute and set it to the value you want.

    <rn:widget path="searchsource/SocialResultListing"
     label_heading="#rn:msg:RESULTS_FROM_THE_COMMUNITY_LBL#"
     more_link_url="/app/social/questions/list" truncate_size="100" />
  12. To hide selected metadata, add the show_metadata attribute and remove the comment_count or best_answers options.

    <rn:widget path=”searchsource/SocialResultListing” show_metadata=”comment_count” />
  13. Save the file.

Edit the Published Answers Page

You can modify what displays on the Published Answer page.

Your customers access the Published Answers page by clicking the Show More Published Answers link on the Support Home page or on the Results page. They can enter search terms and filter published answers by product and category.
  1. Open one of the Answer List page files:

    • /views/pages/answers/list.php
    • /views/pages/mobile/answers/list.php
  2. To change the number of displayed answers from the reference implementation’s default value of five answers, follow these steps.

    1. Change the per_page attribute of the container that includes the SourceResultListing widget and set the value to the number of answers you want to display.

      <rn:container source_id="KFSearch" per_page="8" history_source_id="KFSearch">
    2. Add the per_page attribute to the Multiline widget and set the same value as you defined in the SourceResultListing widget.

      <rn:widget path="reports/Multiline" show_answer_update_date_field="false" per_page="8"/>
  3. To truncate the length of published answers to something other than the default value of 200 characters, follow these steps.

    1. Add the truncate_size attribute to the SourceResultListing widget and set it to the value you want.

      <rn:widget path="searchsource/SourceResultListing" more_link_url="" truncate_size="100" />
    2. Add the truncate_size attribute to the Multiline widget and set it the same value as you defined in the SourceResultListing widget.

      <rn:widget path="reports/Multiline" show_answer_update_date_field="false" truncate_size="100"/>
  4. To remove the icon for the RSS feed, delete <rn:widget path="knowledgebase/RssIcon" />.

  5. Save the file.

Change the Search Report

You can use any report on the Answers page, as long as it contains the answers.special_settings filter.

The default search report on the Published Answers page is Answers–Complex Expressions Search Default.
  1. Open one of these files:

    • /views/pages/answers/list.php
    • /views/pages/mobile/answers/list.php
  2. Locate <rn:container report_id="176">.

  3. Replace 176 with the report ID of the answers report you want to open when the customer conducts a search.

  4. Save the file.

Check for the answers.special_settings Filter

Answers reports used on the customer portal must contain the answers.special_settings filter.

If you are using a custom answers report, make sure it includes the answers.special_settings filter.
All standard answers reports for the customer portal already include the filter.
  1. Double-click Reports Explorer in Analytics.

  2. Locate the custom answers report you want to use on the customer portal, right-click it, and select Edit.

  3. Click Filters.

  4. Locate special settings is null in the list of filters on the window.

  5. If the special settings filter is not present in the list, add it.

    1. Click Add Filter.

    2. Enter special settings is null in the Name field.

    3. Enter answers.special_settings in the Expression field.

    4. Select is null in the Operator drop-down menu.

      Note: If the “is null” option is not available in the Operator menu, be sure the check box for Make this filter selectable at runtime is cleared.
    5. Click OK.

  6. Click OK.

  7. Click Save.

Use a Grid Report on the Published Answers Page

You can use a grid report to display search results in tabular form.

By default, the Published Answers page displays search results in a multiline format.
  1. Open /views/pages/answers/list.php.

  2. Locate this code.

    <rn:widget path="reports/Multiline" show_answer_update_date_field="false" />
  3. Replace the Multiline widget with the Grid widget.

    <rn:widget path="reports/Grid" show_answer_update_date_field="false" />
  4. Save the file.

Copy the Standard Answers Report

Users with report editing permissions can use the Standard Answers report to create a custom report and replaces the standard report.

  1. Double-click Reports Explorer in Analytics.

  2. Click Find.

  3. Select ID in Find Using.

  4. Select Equal To.

  5. Enter 176 in the field.

  6. Click Find.

  7. Right-click the report and select Copy.

  8. Enter a name for the custom report you are going to create in the Name field.

  9. Click OK.

Edit a Custom Report

This example edits a custom report to open answers in a separate window.

Users must have report edit permissions.
  1. With the Reports explorer open, locate the custom report you want to edit.

  2. Right-click the report and select Edit.

  3. Right-click the Summary column and select Insert New Column Before.

  4. Enter Link Target in the Heading field.

  5. Place the cursor in the Expression field to the right of the Available Columns/Functions.

  6. Enter if((answers.type = 2 | answers.type = 3), '_blank') in the Expressions field.

  7. Click OK.

  8. Right-click the Link Target column and select Hide Column.

  9. Right-click the Summary column and select Edit Format.

  10. Click URL > Advanced URL Definition.

  11. Click Target and select Link Target.

  12. Click OK.

  13. Click Home.

    1. Click Definition.

    2. Select View.

    3. Note the AcId number.

  14. Close the Report Definition window.

  15. Click Save.

Replace the Standard Report

This example replaces the standard report with a custom report that opens URL and file attachment answers in a separate browser window.

  1. Open /views/pages/answers/list.php.

  2. Locate <rn:container report_id="176">.

  3. Replace 176 with the ID number for the custom report you created.

  4. Save the file.

Edit the Results from the Community Page

Community discussions can be filtered by product, age, and questions that have a best answer.

  1. Open /views/pages/social/questions/list.php.

  2. To remove the Filter by Product filter, delete this code.

    <rn:widget path="searchsource/SourceProductCategorySearchFilter"
     verify_permissions="true"/>
  3. To remove the Filter by Age filter, delete this code.

    <rn:widget path="searchsource/SourceFilter" filter_type="updatedTime"
     label_default="--" labels="#rn:php:/RightNow/Utils/Config::getMessage(LAST_DAY_LBL)
     . ',' . /RightNow/Utils/Config::getMessage(LAST_WEEK_LBL) . ','
     . /RightNow/Utils/Config::getMessage(LAST_MONTH_LBL) . ','
     . /RightNow/Utils/Config::getMessage(LAST_YEAR_LBL)#"
     label_input="#rn:msg:FILTER_BY_AGE_LBL#"/>
  4. To remove the Filter by Best Answer filter, delete this code.

    <rn:widget path="searchsource/SourceFilter" filter_type="numberOfBestAnswers"
     label_default="--" labels="#rn:php:/RightNow/Utils/Config::getMessage(YES_LBL)
     . ',' . /RightNow/Utils/Config::getMessage(NO_LBL)#"
     label_input="#rn:msg:FILTER_BY_BEST_ANSWER_LBL#"/>
  5. To change the number of displayed questions from the default of 10, edit the per_page attribute in the container that includes the SocialResultListing widget and change its value to the number of questions you want to display.

    <rn:container source_id="SocialSearch" per_page="5" history_source_id="SocialSearch">
  6. To truncate the length of published questions to something other than the default value of 200 characters, add the truncate_size attribute to the SocialResultListing widget and set it to the value you want.

    <rn:widget path="searchsource/SocialResultListing" more_link_url="" truncate_size="100" />
  7. To hide selected metadata, add the show_metadata attribute and remove the comment_count or best_answers options.

    <rn:widget path=”searchsource/SocialResultListing” show_metadata=”comment_count” />
  8. Save the file.

Configure the Contact Us Section

You can configure the contact us section of the Search Results page.

  1. Open the Search Results page to configure the sidebar.

  2. To remove the Ask a Question link, add the channels attribute to the ContactUs widget and set the value to community, chat, feedback.

    <rn:widget path="utils/ContactUs" channels="community,chat,feedback" />
  3. To remove the Ask the Community link, add the channels attribute to the ContactUs widget and set the value to question, chat, feedback.

    <rn:widget path="utils/ContactUs" channels="question,chat,feedback" />
  4. To remove the Live Chat link, add the channels attribute to the ContactUs widget and set the value to question, community, feedback.

    <rn:widget path="utils/ContactUs" channels="question,community,feedback" />
  5. To remove the Give Feedback link, add the channels attribute to the ContactUs widget and set the value to question, community, chat.

    <rn:widget path="utils/ContactUs" channels="question,community,chat" />
  6. Save the page.

Configure the Recently Viewed Section

You can configure the recently viewed items available on various pages including the Search Results, the Answer Details, and the Community Results pages.

  1. Open the file for the page you want to configure the sidebar.

  2. To change the Recently Viewed heading, add the label_heading attribute to the RecentlyViewedContent widget and set the value to the new heading.

    <rn:widget path="discussion/RecentlyViewedContent" label_heading="New Label" />
  3. To change the number of recently viewed answers and discussions from the default of 5, add the content_count attribute to the widget and set the new value. (If you do not want to set a limit, set the attribute to 0.)

    <rn:widget path="discussion/RecentlyViewedContent" content_count="3" />
  4. To change the number of characters that are displayed for each answer or discussion from the default value of 50 characters, add the truncate_size attribute and set the new value.

    <rn:widget path="discussion/RecentlyViewedContent" truncate_size="100" />
  5. To display only discussions, add the content_type attribute and set the value to questions.

    <rn:widget path="discussion/RecentlyViewedContent" content_type="questions" />
  6. To display only published answers, add the content_type attribute and set the value to answers.

    <rn:widget path="discussion/RecentlyViewedContent" content_type="answers" />
  7. To remove the Recently Viewed section, delete <rn:widget path="discussion/RecentlyViewedContent"/>.

  8. Save the page.

Configure SummaryResultListing on the Published Answers Page

The SummaryResultListing widget displays the Community Results section in the sidebar of the Published Answers page to show community discussions related to the search term.

  1. Open one of these files and locate the associated code.

    • /views/pages/answers/list.php
      <rn:widget path="searchsource/SummaryResultListing"
       label_heading="#rn:msg:COMMUNITY_RESULTS_LBL#" results_type="SocialQuestions"
       more_link_url="/app/social/questions/list" per_page="10"/>
    • /views/pages/social/questions/list.php
      <rn:widget path="searchsource/SummaryResultListing" hide_when_no_results="true"
       label_heading="#rn:msg:PUBLISHED_ANSWERS_LBL#" per_page="10"/>
  2. To change the number of displayed results from the default of 10, change the value of the per_page attribute to the value you want.

  3. To disable search term highlighting, add the highlight attribute and set it to false.

  4. To change the length of the question title from the default of 35 characters, add the truncate_size attribute and set it to the length you want.

  5. To hide the heading when there are no related community discussions, add the hide_when_no_results attribute and set it to true.

  6. Save the file.

Configure the Provide Feedback Dialog

The Provide Feedback dialog opens when customers click the Give Feedback sidebar link.

If the customer is not logged in, the dialog contains two required fields: the email address and a feedback field. If the customer is logged in, the incident created by the feedback is automatically associated with the customer and only the Your Feedback field appears on the dialog.
  1. Open the Search Results page.

  2. To change the Provide Feedback header, add the label_dialog_title attribute to the ContactUs widget and set its value to the new header.

    <rn:widget path="utils/ContactUs" label_dialog_title="New Provide Feedback Header Label" />
  3. To change the confirmation message, add label_feedback_confirmation="New Confirmation Message" to the widget code.

  4. To point your customers to a different feedback page instead of the Provide Feedback window, follow these steps:

    1. Create the page you want to open, name it, and place it in /cp/customer/development/views/pages folder or a subfolder.

    2. Add the feedback_page_url attribute to the Contact Us widget and set its value to the new page you have created.

      <rn:widget path="utils/ContactUs" feedback_page_url="/app/utils/your_custom_feedback_page" />
  5. Save the page.

Answer and Question Details Pages

Overview of the Answer and Question Details Pages

When customers select an answer on an Answers report, the Answer Details page opens. When customers select a Recent Community discussion on the Support Home page, the Question Details page opens.

The Answer Details and Question Details pages (views/pages/answers/detail.php or views/pages/social/questions/detail.php) display:
  • a summary of the answer or question

  • the question and answer text

  • the dates when the question or answer were published and updated

  • any files that are attached to the answer or question

  • a feedback section

  • links for sharing, printing, emailing, and subscribing

The page sidebar has a section for channels that customers can use to contact your organization, a section for recently viewed content, and a section for related answers from your knowledge base.

The Details pages also contain the GuidedAssistant widget, which walks customers through a series of questions to help them locate information that may provide additional information to answer their questions.

Depending on how an answer was configured, it may or may not be visible to all customers on the Answer Details page. Many factors control answer visibility, including:
  • the answer status

  • the answer access level

  • the answer language

  • the associated products and categories

  • conditional sections

  • the customers’ SLAs

This is also true of answers that have been reached through a guide on your customer portal. For example, if an answer or section of an answer is available only to customers whose SLAs give them permission to view certain answer access levels, that answer will not be visible to customers without that SLA even if they click an answer in a guide.

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 and the Answer Details page. If both pages do not have the same login requirement, a warning will appear when you stage and promote your customer portal.

For search engine optimization, the source code for the Answer Details page includes a tag that contains the title of the answer. The title is all lowercase and the words are separated by hyphens. Punctuation in a title is escaped and the title uses a maximum of 80 characters.

The link tag is automatically added to the <head> section of the answer and uses this form.
<link rel="canonical" href="http://www.example.com/app/answers/detail/a_id/<answerID>
 /~/<answer-title>" />
To view this tag, view the source code for an answer page in your web browser. Here is an example.
<link rel='canonical' href='http://yoursiteurl.com/app/answers/detail/a_id/47/
 ~/how-do-i-use-my-cell-phone-as-a-mobile-hotspot%3F'/>

Edit Date Labels on the Answer Details Page

This example shows how to edit the labels associated with the publication date of the answer and the date it was last updated.

  1. Open /views/pages/answers/detail.php.

  2. Locate this code.

    #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>
  3. Edit the code to reflect your label changes.

    This answer was first published on <span itemprop="dateCreated"><rn:field 
    name="Answer.CreatedTime" /></span> &nbsp;&nbsp;|&nbsp;&nbsp;&nbsp; 
    This answer was last updated on <span itemprop="dateModified">
    <rn:field name="Answer.UpdatedTime" /></span>
  4. To remove the dates, delete the code you previously located.

    #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>
  5. Save the file.

Disable Search Term Highlighting

You can turn off the default highlighting of search terms on the Answer Details page.

  1. Open one of the answer details files:

    • /views/pages/answers/detail.php
    • /views/pages/mobile/answers/detail.php
  2. Locate this code.

    <h1 id="rn_Summary"><rn:field name="Answer.Summary" highlight="true"/></h1>
    ...
    <rn:field name="Answer.Question" highlight="true"/>
    ...
    <rn:field name="Answer.Solution" highlight="true"/>
  3. Remove highlight="true" from each line.

  4. Save the file.

Modify the File Attachments Display

You can configure the display to sort the attachments, remove file size information, remove thumbnails, and prevent the display of file attachments.

  1. Open /views/pages/answers/detail.php.

  2. Locate <rn:widget path="output/DataDisplay" name="Answer.FileAttachments" label="#rn:msg:ATTACHMENTS_LBL#"/>.

  3. To sort the file attachment list numerically and alphabetically, edit the DataDisplay widget to add the sort_by_filename attribute and set its value to true.

    <rn:widget path="output/DataDisplay" name="Answer.FileAttachments"
     label="#rn:msg:ATTACHMENTS_LBL#" sort_by_filename="true" />
  4. To remove the file attachment size information, add the display_file_size attribute and set it to false.

    <rn:widget path="output/DataDisplay" name="Answer.FileAttachments"
     label="#rn:msg:ATTACHMENTS_LBL#" display_file_size="false" />
  5. To remove file attachment thumbnail, add the display_thumbnail attribute and set it to false.

    <rn:widget path="output/DataDisplay" name="Answer.FileAttachments"
     label="#rn:msg:ATTACHMENTS_LBL#" display_thumbnail="false"/>
  6. To prevent displaying answer file attachments on the answer details page, delete this code.

    <div id="rn_FileAttach">
        <rn:widget path="output/DataDisplay" name="Answer.FileAttachments"
         label="#rn:msg:ATTACHMENTS_LBL#" />
    </div>
  7. Save the file.

GuidedAssistant Guides

The sets of branching questions used by the GuidedAssistant widget are called guides, and they are created on the administration interface.

The default Answer Details page includes the GuidedAssistant widget, which helps your customers locate solutions to their problems when they answer questions presented to them on the customer portal. Guides can be associated with individual answers so that when your customers select an answer, the GuidedAssistant widget appears on the Answer Details page. (If the selected answer is not associated with a guide, the widget will not appear.) Or you can select one guide you want to always appear on the page regardless of which answer is opened.

If you define a guide ID in the widget code, that guide will be displayed even if another guide is already associated with the selected answer. If the widget code does not specify a guide, the page displays the guide associated with the answer that is selected, if it has one.

You can configure guides to pass parameters to the Ask a Question page. If, for instance, your customer reaches the end of a guide and still doesn’t have the answer to a question, you can ask for product and category information that will be passed in the URL to the Ask a Question page to populate those fields automatically.

Be sure to check your guides as they appear on the Customer Portal. Image type questions can benefit from additional configuration to display effectively. It’s a good idea to leave additional space to the left of the image and include the caption as part of the image rather than separately. Images that are roughly 350 pixels by 200 pixels display optimally.

Open the Same Guide on Every Answer

By defining the guide ID in the widget code, you can override the answer-guide association and specify one guide open on the Answer Details page regardless of the answer.

  1. Open one of the following files:

    • /views/pages/answers/detail.php
    • /views/pages/mobile/answers/detail.php
  2. Locate the following code.

    <rn:widget path="knowledgebase/GuidedAssistant" />
  3. Edit the GuidedAssistant widget to add the static_guide_id attribute and specify the ID of the guide.

    <rn:widget path="knowledgebase/GuidedAssistant" static_guide_id="21" />
  4. Save the page.

Open Guides in a Separate Window

You can open guides from the Answer Details page in a separate window.

  1. Create a PHP page that contains the GuidedAssistant widget and place it in a development folder.

    In this example, we’ll call the page guide.php and place it in the /development/views/pages folder.
    <rn:meta title="Guides" template="standard.php" />
        <div id="rn_PageContent">
            <div class="rn_AnswerDetail">
                <dl class="rn_Overview">
                    <rn:widget path="knowledgebase/GuidedAssistant"/>
                </dl>
            </div>
        </div>
  2. Open /views/pages/answers/detail.php.

  3. Locate this code.

    <rn:widget path="knowledgebase/GuidedAssistant"/>
  4. Edit the GuidedAssistant widget.

    • To add the popup_window_url attribute to specify the guide page you just created.
      <rn:widget path="knowledgebase/GuidedAssistant" popup_window_url="/app/guide" />
    • To add the call_url_new_window attribute.
      <rn:widget path="knowledgebase/GuidedAssistant" call_url_new_window="true" />
  5. Save the file.

Open Answers Inline

You can open answers inline instead of a separate window, which is the default.

  1. Open /views/pages/answers/detail.php.

  2. Locate this code.

    <rn:widget path="knowledgebase/GuidedAssistant"/>
  3. Edit the GuidedAssistant widget to add the target attribute.

    <rn:widget path="knowledgebase/GuidedAssistant" target="_self" />
  4. Save the file.

Display Only the Current Question

You can configure the GuidedAssistant widget to display only the current question.

  1. Open /views/pages/answers/detail.php.

  2. Locate <rn:widget path="knowledgebase/GuidedAssistant"/>.

  3. Add the single_question_display attribute and set it to true.

    <rn:widget path="knowledgebase/GuidedAssistant" single_question_display="true" />
  4. Save the file.

Edit Labels on the GuidedAssistant Widget

These attributes can change the labels displayed in your GuidedAssistant widget.

  1. Open /views/pages/answers/detail.php.

  2. Locate <rn:widget path="knowledgebase/GuidedAssistant"/>.

  3. Edit the GuidedAssistant widget labels.

    • To change the default label "Please consult the following information", edit the label_answer_result attribute.
    • To change the default label "Launch the Troubleshooter", edit the label_popup_launch_button attribute.
      <rn:widget
           path="knowledgebase/GuidedAssistant" popup_window_url="/app/guide"
           label_popup_launch_button="Open Help System" />
    • To change the default label "Go back to previous question", edit the label_question_back attribute.
    • To change the default label "Start over", edit the label_start_over attribute.
    • To change the default label "OK", edit the label_text_response_button attribute.
    • To change the default label "(Null)", edit the label_text_result attribute.
  4. Save the file.

Remove the GuidedAssistant Widget

You can remove the GuidedAssistance widget from your site.

  1. Open /views/pages/answers/detail.php.

  2. Delete <rn:widget path="knowledgebase/GuidedAssistant"/>.

  3. Save the file.

Add Fields on the Answer Details Page

You might want to provide additional information about the answer being viewed on the Answer Details page.

  1. Open one of the listed files and find the line of code:

    • /views/pages/answers/detail.php
      <rn:field name="Answer.Question" highlight="true"/>
    • /views/pages/mobile/answers/detail.php
      <rn:field name="Answer.Solution" highlight="true"/>
  2. Add the appropriate code below the previously located code.

    • To add the answer’s ID, add <p>Answer ID <rn:field name="Answer.ID" /></p>.
    • To add product information for the answer, add <rn:widget path="output/DataDisplay" name="Answer.Products" />.
    • To add category information for the answer, add <rn:widget path="output/DataDisplay" name="Answer.Categories" />.
  3. Save the file.

Change the Answer Feedback Page

You can create an Answer Feedback page where your customers will be redirected when they submit feedback that is below the specified threshold.

For this example, let’s assume that your page name is new_answer_feedback_page.php and that you have stored it in views/pages/answers.
  1. Open /views/pages/answers/detail.php.

  2. Add the feedback_page_url attribute to the AnswerFeedback widget and set its value to the new feedback page.

    <rn:widget path="feedback/AnswerFeedback"
     label_title="#rn:msg:IS_THIS_ANSWER_HELPFUL_LBL#"
     feedback_page_url="/app/answers/new_answer_feedback_page" />
  3. Save the file.

Offer Alternate Feedback Options

You can offer your customers more than the default Yes and No options as a response to the answer feedback question.

You can define up to five options, which appear as stars by default, but can also appear as percentage ratings.
  1. Open /views/pages/answers/detail.php.

  2. Add the options_count attribute to the AnswerFeedback widget.

    <rn:widget path="feedback/AnswerFeedback"
     label_title="#rn:msg:IS_THIS_ANSWER_HELPFUL_LBL#" options_count="5" />
  3. If you want the options to appear in descending order rather than the default ascending order, add the options_descending attribute to the code.

    <rn:widget path="feedback/AnswerFeedback" 
     label_title="#rn:msg:IS_THIS_ANSWER_HELPFUL_LBL#" options_count="5"
     options_descending="true" />
  4. If you want to explain the rating scale, you can edit the label_title attribute as well.

    <rn:widget path="feedback/AnswerFeedback"
     label_title="#rn:msg:IS_THIS_ANSWER_HELPFUL_LBL#" options_count="5"
     label_title="Rate this answer for helpfulness by selecting between 1 (low) and 5 
     (high) stars" />
  5. If you want to display a numerical percentage rating instead of the default stars that are used when more than two responses are offered, add the use_rank_labels attribute.

    <rn:widget path="feedback/AnswerFeedback"
     label_title="#rn:msg:IS_THIS_ANSWER_HELPFUL_LBL#" options_count="5"
     label_title="How useful is this answer?" use_rank_labels="true" />
  6. Save the file.

Remove Answer Feedback

You can remove the answer feedback from the Answer Details page.

  1. Open /views/pages/answers/detail.php.

  2. Delete this code.

    <rn:widget path="feedback/AnswerFeedback" label_title="#rn:msg:IS_THIS_ANSWER_HELPFUL_LBL#"/>
  3. Save the file.

Change the Rating Threshold

You can let customers provide more detailed feedback.

  1. Open /views/pages/answers/detail.php.

  2. Locate <rn:widget path="feedback/AnswerFeedback" label_title="#rn:msg:IS_THIS_ANSWER_HELPFUL_LBL#" />.

  3. Edit the code to add the dialog_threshold attribute to the widget.

    1. Let customers provide feedback on the answer, set the threshold to 0.

    2. Offer every customer the ability to provide feedback, regardless of the answer rating, set the threshold to the total number of feedback options (2 for the default Yes/No buttons, 5 for the default multiple feedback options).

      <rn:widget path="feedback/AnswerFeedback"
       label_title="#rn:msg:IS_THIS_ANSWER_HELPFUL_LBL#" options_count="5"
       dialog_threshold="3" />
  4. Save the file.

Configure the ContactUs Widget

The ContactUs widget appears on the Answer and Question Details pages and also on the Search Result pages.

This procedure uses the answers/detail page, but the steps are the same for the social/questions/detail page.
  1. Open /views/pages/answers/detail.php.

  2. To remove the Ask a Question link, add the channels attribute to the ContactUs widget and set the value to community, chat, feedback.

    <rn:widget path="utils/ContactUs" channels="community,chat,feedback" />
  3. To remove the Ask the Community link, add the channels attribute to the ContactUs widget and set the value to question, chat, feedback.

    <rn:widget path="utils/ContactUs" channels="question,chat,feedback"/>
  4. To remove the Live Chat link, add the channels attribute to the ContactUs widget and set the value to question, community, feedback.

    <rn:widget path="utils/ContactUs" channels="question, community,feedback" />
  5. To remove the Give Feedback link, add the channels attribute to the ContactUs widget and set the value to question, community, chat.

    <rn:widget path="utils/ContactUs" channels="question, community,chat" />
  6. Save the page.

Configure the SiteFeedback Widget

The Provide Feedback dialog is generated by the SiteFeedback widget contained in the ContactUs widget.

If a customer is not logged in, the dialog contains two required fields: the email address and a feedback field. If a customer is logged in, the incident created by the feedback is automatically associated with the customer and only the Your Feedback field appears on the dialog. This procedure uses the answers/detail page, but the steps are the same for the social/questions/detail page.
  1. Open /views/pages/answers/detail.php.

  2. To open a different customer portal page instead of the Provide Feedback window, follow these steps.

    1. Create the page you want to open, name it, and place it in /cp/customer/development/views/pages folder or a subfolder.

    2. Add the feedback_page_url attribute to the ContactUs widget, making sure the path begins with/app.

      <rn:widget path="feedback/SiteFeedback" />
    3. Edit the code to add a value for the feedback_page_url attribute. The value must begin with /app.

      <rn:widget path="utils/ContactUs" feedback_page_url="/app/utils/your_custom_feedback_page" />
    4. Save detail.php.

  3. To edit labels on the Provide Feedback dialog, add the appropriate label attribute to the ContactUs widget and change its value to the new label.

    • To change the label on the Give Feedback link, add label_link="New Give Feedback Link Label".
    • To change the Provide Feedback header of the window, add label_dialog_title="New Provide Feedback Header Label".
    • To change the Email label, add label_email_address="New Email Address Label".
    • To change the Your Feedback label, add label_comment_box="New Your Feedback Label".
    • To change the Submit button label, add label_send_button="New Submit Button Label".
    • To change the Cancel button label, add label_cancel_button="New Cancel Button Label".
    • To change the confirmation message, add label_feedback_confirmation="New Confirmation Message".
  4. Save the page.

Configure the Published Answers Section

The related answers feature suggests answers based on the answer relationships generated when staff members manually relate answers or when customers use your site.

  1. Open /views/pages/answers/detail.php.

  2. To change the Published Answers heading, add the label_title attribute to the RelatedAnswers widget and set the value to the new heading.

    <rn:widget path="knowledgebase/RelatedAnswers" label_title="New Label" />
  3. To change the number of published answers from the default of 5, add the limit attribute to the RelatedAnswers widget and set the new value.

    If you do not want to set a limit, set the attribute to 0.
    <rn:widget path="knowledgebase/RelatedAnswers" limit="3" />
  4. To change the number of characters that are displayed for each answer from the default value of 0 characters (which prevents truncation), add the truncate_size attribute and set the new value.

    <rn:widget path="knowledgebase/RelatedAnswers" truncate_size="50" />
  5. To remove the Published Answers section, delete <rn:widget path="knowledgebase/RelatedAnswers" />.

  6. Save the file.

Submit a Question Pages

Submit a Question Pages

Your customer portal contains a page that lets customers ask questions to your support staff and another that lets them ask questions to the community.

When the Ask a Question tab is clicked, the first page that opens (/views/pages/ask.php) lets your customers submit questions to your support staff, which automatically creates an incident in your database. This page contains a link to another page (/views/pages/social/ask.php) that lets customers pose their question to the community, instead of submitting it to your organization.

The standard workflow for submitting a question to your support staff on the Customer Portal reference implementation was designed for an optimal customer experience. It asks for only an email address, without requiring account creation or login. When customers are already logged in, the email field is hidden and they need only enter information about their question. When customers submit a question, an incident is created in your database so that your support staff can resolve the issue. The created incident is linked automatically to the customer if a contact record exists in the database. If a contact does not already exist, a new contact record is created. The new contact record contains only the email address, so customers will be required to use account assistance if they want to log in to the customer portal in the future. Customers are not logged in to the customer portal after submitting a question, whether their contact record already exists or is created through the question submission.

When customers who are not logged in click the Ask our Community link after clicking the Ask a Question tab, they are taken to the login window to either log in or create an account. Customers who are logged in but who do not have a community display name will be asked to create a display name before submitting questions to the community.

Display the Ask a Question Page Based on User Actions

The RN Condition page tag lets you hide part of the page if the condition specified in the tag is not met.

Before you implement this requirement, you should consider the usability issues of conditionally hiding and exposing page navigation. 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.
Among the attributes of the RN Condition page tag are answers_viewed, questions_viewed, content_viewed (combination of answers and questions/discussions), and searches_done.
  1. Open /views/templates/standard.php.

  2. Locate this code.

    <li><rn:widget path="navigation/NavigationTab" label_tab="#rn:msg:ASK_QUESTION_HDG#"
         link="/app/ask" pages="ask, ask_confirm"/></li>
  3. To hide the tab based on the number of answers customers view, add the answers_viewed condition above the code for the Ask a Question tab.

    In this example, customers must view three answers before the tab is displayed.
    <rn:condition answers_viewed="3">
  4. To hide the tab based on the number of community discussions (questions) customers view, add the questions_viewed condition above the code for the Ask a Question tab.

    <rn:condition questions_viewed="2">
  5. To hide the tab based on the combination of answers and community discussions customers view, add the content_viewed condition above the code for the Ask a Question tab.

    <rn:condition content_viewed="4">
  6. To hide the tab based on the number of searches customers perform, add the searches_done attribute to the NavigationTab widget.

    <li><rn:widget path="navigation/NavigationTab" label_tab="#rn:msg:ASK_QUESTION_HDG#"
         link="/app/ask" pages="ask, ask_confirm" searches_done="2" /></li>
    1. If your only criteria for displaying the Ask a Question page is the number of searches your customers perform, you should use the searches_done attribute of the NavigationTab widget instead of the RN Condition searches_done attribute.

      Because the RN Condition tag identifies a search only when a page is turned or refreshed, this is a less ideal option for displaying the Ask a Question page. Assume you set the searches_done attribute for RN Condition to 2. Now assume a customer conducts one search, reviews the list but does not click an answer or otherwise leave or refresh the answers list page, and then conducts a second search. In this case, the Ask a Question tab will not be displayed until another page is opened or the current page is refreshed.
    2. To count searches performed by the customer regardless of whether page turns occur (that is, regardless of whether an answer resulting from a search is viewed), use the searches_done attribute of the NavigationTab widget rather than the searches_done attribute of the RN Condition tag.

  7. To use a combination of options for hiding the navigation tab, use the else condition as shown in this example, which hides the tab until either three answers have been viewed or two searches have been conducted.

    <rn:condition answers_viewed="3">
        <li><rn:widget path="navigation/NavigationTab" label_tab="#rn:msg:ASK_QUESTION_HDG#"
             link="/app/ask" pages="ask, ask_confirm"/></li>
    <rn:condition_else/>
        <li><rn:widget path="navigation/NavigationTab" label_tab="#rn:msg:ASK_QUESTION_HDG#"
             searches_done="2" link="/app/ask" pages="ask, ask_confirm"/></li>
    </rn:condition>
  8. Add the following code on a separate line below the code for the Ask a Question tab.

    </rn:condition>
  9. Save the file.

Remove the Subject Field

The Subject field on the Ask a Question page populates the Subject field of the created incident.

If you remove the Subject field from the Ask A Question page, the incident Subject field contains the first 80 characters of the customer’s question.
  1. Open /views/pages/ask.php.

  2. Delete the following line of code from the file to remove the Subject field when the customer is not logged in.

    <rn:widget path="input/FormInput" name="Incident.Subject" required="true"
     label_input="#rn:msg:SUBJECT_LBL#"/>
  3. Delete the following lines of code from the file to remove the Subject field when the customer is logged in.

    <rn:condition logged_in="true">
        <rn:widget path="input/FormInput" name="Incident.Subject" required="true"
         initial_focus="true" label_input="#rn:msg:SUBJECT_LBL#"/>
    </rn:condition>
  4. Save the file.

Populate the Product Field

You can automatically populate the product field on the Ask a Question page to a default value.

Although the default_value attribute takes precedence over any other method of populating the products and categories for the ProductCategoryInput widget, you can also populate the product and category fields by passing the ID numbers in the URL used to open the page. This lets you populate different products and categories when customers access the Ask a Question page from different external pages. You can also use POST parameters, but the URL parameters will override the POST parameter if both are used.
  1. Open /views/pages/ask.php.

  2. Locate <rn:widget path="input/ProductCategoryInput" name="Incident.Product" />.

  3. Add the default_value attribute to the ProductCategoryInput widget to specify the product you identified the ID number for.

    <rn:widget path="input/ProductCategoryInput" name="Incident.Product" 
     default_value="421,47" />
  4. Save the file.

Configure File Attachments

The standard Ask a Question page lets your customers attach an unlimited number of files to the question they submit, but you can restrict the number or type of file attachments or prevent them from adding attachments.

  1. Open /views/pages/ask.php.

  2. Locate <rn:widget path="input/FileAttachmentUpload"/>.

  3. To restrict the type of attachments, add the valid_file_extensions attribute to the FileAttachmentUpload widget.

    <rn:widget path="input/FileAttachmentUpload" valid_file_extensions="doc,docx,xls,xlsx" />
  4. To change the default label that displays if customers try to attach a file type that is not valid, add the label_invalid_extension attribute and define the label.

    <rn:widget path="input/FileAttachmentUpload" valid_file_extensions="doc,docx,xls,xlsx"
     label_invalid_extension="You may attach only the following file types:%s" />
  5. To restrict the number of file attachments, add the max_attachments attribute to the widget.

    <rn:widget path="input/FileAttachmentUpload" max_attachments="5" />
  6. To change the default label that displays if customers exceed the allowable number of attachments, add the label_max_attachment_limit attribute and define the label.

    <rn:widget path="input/FileAttachmentUpload" max_attachments="5"
     label_max_attachment_limit="You may upload only 5 files to your question."/>
  7. To remove the ability to attach files to a question, delete <rn:widget path="input/FileAttachmentUpload"/>.

  8. To require a minimum number of file attachments, add the min_required_attachments attribute to the FileAttachmentUpload widget.

    <rn:widget path="input/FileAttachmentUpload" min_required_attachments="2" />
  9. To change the default label that displays if customers do not attach the minimum number of attachments, add the label_min_required attribute and define the label.

    <rn:widget path="input/FileAttachmentUpload" min_required_attachments="2"
     label_min_required="You must attach at least 2 files before submitting your question."/>
  10. Save the file.

Define Form Completion Time

By default, a customer’s partially completed form remains valid for 30 minutes, but you can change that value.

  1. Locate SUBMIT_TOKEN_EXP configuration setting in RightNow User Interface/General/Security.

  2. Click Value and enter the number of minutes at which you want the form to expire.

  3. Click Save.

Edit the Standard Confirmation Page

You can edit the standard confirmation page that opens when a customer submits a question on the Ask a Question page, or you can display a different confirmation page.

  1. Open /views/pages/ask_confirm.php.

  2. To change the “Your question has been submitted!” heading, locate the following line of code and edit the content between the <h1> tags with your new heading.

    <h1>#rn:msg:YOUR_QUESTION_HAS_BEEN_SUBMITTED_LBL#</h1>
  3. Save the file.

  4. To display a different confirmation page, follow these steps.

    1. Open /views/pages/ask.php.

    2. Locate <rn:widget path="input/FormSubmit" label_button="#rn:msg:CONTINUE_ELLIPSIS_CMD#" on_success_url="/app/ask_confirm" error_location="rn_ErrorLocation" />.

    3. Edit the code to replace "/app/ask_confirm" with the page of your choice.

  5. Save the file.

Create an Incident Rule for Incident Receipts

You can set up an incident rule to send an email receipt to your customers when they submit a question on the Ask a Question page.

  1. Open Rules in Configuration > Site Configuration.

  2. Click Incident.

  3. Click Edit.

  4. If an initial state does not already exist for the incident rule base, create one.

    1. Right-click States and select New State.

    2. Enter a name, such as Initial State.

    3. Select Initial State.

    4. Click Save.

  5. Right-click the initial state and select New Rule.

  6. Enter a name for the incident rule in the Rule Name field.

  7. Click Add IF Condition Based On.

  8. Select Incident > Source.

  9. Click the arrow in the Select Operator field and select Equals.

  10. Expand the End-User Pages heading in the incident source menu and select Ask a Question.

  11. Click Add Action–Then.

  12. Select Email > Send Receipt Email.

  13. Click Save.

  14. Expand the initial state again and determine the location of the incident receipt rule.

  15. If the incident receipt rule is not at the top of the list, drag it to the top position.

  16. Click Activate.

  17. Click OK.

  18. Click OK.

  19. If incidents are in the Null state or a state that has been removed, you should move them into an active state in the rule base.

  20. Click the drop-down arrow to select a state where the incidents should be moved.

  21. Click Save.

Configure the Social Ask Page

On the Community Ask a Question page, customers who are logged in but who do not have a community user profile are asked to enter a display name before continuing.

  1. Open /views/pages/social/ask.php.

  2. To change the “Submit a question to the support community” heading, locate the following line of code and edit the content between the <h1> tags with your new heading.

    <h1>#rn:msg:SUBMIT_A_QUESTION_TO_SUPPORT_COMMUNITY_MSG#</h1>
  3. To remove the product selector, delete <rn:widget path="input/ProductCategoryInput" name="SocialQuestion.Product" verify_permissions="Create"/>.

  4. To clear the check box for “Email me when a new comment is posted,” add the subscribe_me_default attribute to the DiscussionAuthorSubscription widget and set its value to false.

    <rn:widget path="notifications/DiscussionAuthorSubscription"
     subscribe_me_default="false"/>
  5. To remove the “Email me when a new comment is posted” check box, delete <rn:widget path="notifications/DiscussionAuthorSubscription"/>.

  6. Save the file.

How SmartAssistant Works

When your customers can’t find an answer to their question in your knowledge base, they can submit a question to your support staff.

If you have an incident business rule defined to do so, the SmartAssistant suggested answers feature uses natural language processing to display a list of answers from your knowledge base that may contain the information your customers are seeking. The list of suggested answers and community discussions is presented to customers before they finish submitting their questions. If one of the suggested answers addresses the customer’s concern, they can avoid submitting an incident. Besides displaying a list of proposed answers to customer questions, SmartAssistant can also display standard text or a single, specific answer.

Customers also see SmartAssistant suggested answers and community discussions when they submit a question to the community. However, incident rules do not apply to community content.

Create an Incident Rule for SmartAssistant

You need to create an incident rule to use SmartAssistant.

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

  2. Click Incident.

  3. Click Edit.

  4. If an initial state does not already exist for the incident rule base, create one.

    1. Right-click States > New State.

    2. Enter a name in the State Name field.

    3. Select Initial State.

    4. Click Save.

  5. Right-click the state you want to add the rule to and select New Rule.

  6. Enter a name for the incident rule in the Rule Name field.

  7. Click Add IF Condition Based On.

  8. Select Incident > Source.

  9. Click the arrow in the Select Operator field and select Equals.

  10. Expand the End-User Pages heading in the incident source menu and select SmartAssistant on Ask a Question.

  11. Click Add Action–Then.

  12. You can display a list of suggested answers, append standard text, or append the text of a specific answer.

    • To display a list of suggested answers, select Append Thread > Append SmartAssistant Response to Response Field.
    • To display standard text, select Append Thread > Append Response Template to Response Field and add the standard text response in the Then action.
    • To display an answer, select Append Thread > Append Existing Solution (by Answer ID) to Response Field and enter the ID of the answer you want to display.
  13. Click Save.

  14. Click Activate > OK > OK.

  15. If incidents are in the Null state or a state that has been removed, you should move them into an active state in the rule base.

    1. Click the drop-down arrow to select a state where the incidents should be moved.

    2. Click Save.

Configure SmartAssistant

A variety of options exist for configuring SmartAssistant on the administration interface.

You can enable optimization so that the parameters that control SmartAssistant accuracy are analyzed to determine their optimum values.
  1. To enable SmartAssistant optimization (which determines the optimum values for the parameters that control accuracy), follow these steps.

    1. Locate KF_SA_OPTIMIZATION_ENABLE in Common/Knowledge Base/Knowledge Foundation.

    2. Click the Value field and select Yes.

    3. Click Save.

  2. To configure the number of days optimization data is valid, follow these steps.

    1. Locate KF_SA_OPTIMIZATION_DATA_PURGE_DAYS in Common/Knowledge Base/Knowledge Foundation.

    2. Click the Value field and enter the number of days after which the optimization data is removed.

    3. Click Save.

  3. To change the ratio of suggested published answers to community discussions from the default of 60 percent answers to 40 percent community results, follow these steps.

    1. Locate SA_RESULTS_COUNT_RATIO in Common/Knowledge Base/SmartAssistant.

    2. Click the Value field and enter the ratio of answers to community results using the format 60A:40S.

    3. Click Save.

  4. To define whether product and category filters should be used for SmartAssistant community results, follow these steps.

    1. Locate SA_USE_SOCIAL_PROD_CAT_FILTER in Common/Knowledge Base/SmartAssistant.

    2. Click the Value field and enter 1 for product filter only, 2 for category filter only, and 3 for both product and category filters.

    3. Click Save.

  5. To define the number of answers to display as solutions instead of links, follow these steps.

    1. Locate SA_WF_SOLNS_EXPAND_CNT in RightNow User Interface/Support/SmartAssistant.

    2. Click the Value field and enter the number of expanded suggested answers you want to appear on the customer portal.

    3. Click Save.

  6. To change the number of answers suggested from the default value of 5, follow these steps.

    1. Locate SA_NL_MAX_SUGGESTIONS under RightNow User Interface/Support/SmartAssistant.

    2. Click the Value field and enter the number of suggested answers you want to appear on the customer portal.

    3. Click Save.

  7. To limit suggested answers by category or product, follow these steps.

    1. Navigate to the RightNow User Interface/Support/SmartAssistant configuration settings.

    2. To limit by categories, click the Value field for SA_SUGGEST_LIMIT_CAT_LVL and enter a value to indicate how you want to restrict suggested answers by category sub-levels.

    3. To limit by products, click the Value field for SA_SUGGEST_LIMIT_PROD_LVL and enter a value to indicate how you want to restrict suggested answers by products sub-levels.

    4. Click Save.

Modify SmartAssistant Relevancy

Two configuration settings let you control how an incident’s subject and body influence the way answers are returned in SmartAssistant.

The SA_DISPATCH_RATIO configuration setting includes two values to define whether the answers are returned based on the hybrid mode used by the SA_SUBJ_BODY_WEIGHTS configuration setting or on the standard SmartAssistant mode. The default value “100 0” means that they will always be returned by the first mode, while “0 100” means they will always be returned by the standard mode. The two values do not have to add up to 100. Instead they represent the odds that the first or second mode will be chosen. These configuration settings are also used to identify similar answers for the Smart Merge feature in Service.
  1. Locate the configuration settings in Common/Knowledge Base/Answer Search.

  2. In the SA_SUBJ_BODY_WEIGHTS value field, enter three values, separated by a single space, to indicate how you want to weight an incident’s subject, body, and bonus value for the hybrid SmartAssistant mode.

  3. In the SA_DISPATCH_RATIO value field, enter two values, separated by a single space, to define the ratio for returning SmartAssistant answers using the mode from SA_SUBJ_BODY_WEIGHTS.

  4. Click Save.

Configure the SmartAssistantDialog Widget

You can modify what is displayed when customers submit their question.

  1. Open the appropriate ask.php file.

    • Open /views/pages/ask.php.
    • Open /views/pages/social/ask.php.
  2. To remove conditions for the SmartAssistant Dialog widget so that it will always propose suggested answers, locate this code and delete all but the <rn:widget path="input/SmartAssistantDialog"/> line.

    <rn:condition content_viewed="2" searches_done="1">
        <rn:condition_else/>
            <rn:widget path="input/SmartAssistantDialog"/>
    </rn:condition>
  3. To change the content viewed or searches done condition, change the code values to the numbers you want.

    <rn:condition content_viewed="2" searches_done="1">
  4. To open the answers that customers click in a separate window, add the display_inline attribute to the SmartAssistantDialog widget and set it to false.

    <rn:widget path="input/SmartAssistantDialog" display_inline="false" />
  5. To redirect customers to a page other than the default Support Home page when their questions are answered, add the solved_url attribute to the SmartAssistantDialog widget.

    <rn:widget path="input/SmartAssistantDialog" solved_url="/app/answers/list" />
  6. To remove the SmartAssistantDialog widget and never suggest answers to your customers, delete this code.

    <rn:condition content_viewed="2" searches_done="1">
        <rn:condition_else/>
            <rn:widget path="input/SmartAssistantDialog"/>
    </rn:condition>
  7. Save the file.

Using the Do Not Create Incident Action with SmartAssistant

You might use the business rule action called Do Not Create Incident if your organization has stopped supporting an older product.

Instead of creating an incident for an unsupported product, you might want to direct customers to the Answers page, where they can search the knowledge base for an answer to their question. In this case, the SmartAssistantDialog widget notifies them that their question hasn’t been submitted and then directs them to the Answers page.

Another time you might want to combine a Do Not Create Incident rule with a SmartAssistant rule is when your organization requires additional information before a customer’s question can be submitted. In this case, the rule base performs a basic form validation. It checks to see if the information is complete and, if it isn’t, directs the customer back to the Ask a Question page without creating an incident from the partial question. You might use this when you have a field on the page that you need customers to answer only under certain conditions. For example, assume you have an Urgency field that is not required except when customers select the Troubleshooting category. When customers select Troubleshooting without selecting an Urgency option, you can automatically direct them back to the submit a question form to complete the field before submitting the question.

Prevent Incident Creation Using the SmartAssistant

This example demonstrates how to prevent an incident creation because your organization no longer supports the selected product.

Create the SmartAssistant rule. See Configure the SmartAssistantDialog Widget .
When the question meets the conditions specified in the Do Not Create Incident rule and the customer clicks the Continue button, the SmartAssistantDialog widget appears. Instead of displaying the suggested answers and standard message bases, the widget displays the labels you have designed specifically for this situation. For example, you can tell customers an incident cannot be submitted because your organization no longer offers the selected product. You can then direct them to the Answers page, where they can search the knowledge base for the answer to their question.
  1. Create the standard text message you want to display when the SmartAssistant window opens to tell customers their question has not been submitted.

    In this example, you might create standard text for a product end-of-life.
    “Because this product has reached end-of-life for customer support, we can no longer accept
    questions about it. For help, please see our knowledge base of existing answers, 
    which will open when you click the Close button.”
  2. Create the Do Not Create Incident rule by following the example in Create an Incident Rule for SmartAssistant.

    IF Incident.Source equals End-User Pages > SmartAssistant on Ask a Question
    AND Incident.Product equals Call Plans > Prepay
    THEN Do Not Create Incident
    AND Append Response Template to Response Field (Select the standard text you created.)
    AND Stop Processing Rules
  3. On the Rules editor, drag the Do Not Create Incident rule so it appears above the SmartAssistant rule in the list of rules within the state.

    Note: The rules engine needs to process the Do Not Create Incident rule before it gets to the SmartAssistant rule. Otherwise, customers will see suggested answers first, but will still have the option to submit their question, triggering an error message if Call Plans > Prepay is selected.
  4. Click Activate.

Redirect Customers

You can point your customers to specific pages when they attempt to submit questions to your support team.

  1. Open /views/pages/ask.php.

  2. Locate the following lines of code.

    <rn:condition content_viewed="2" searches_done="1">
        <rn:condition_else/>
            <rn:widget path="input/SmartAssistantDialog"/>
    </rn:condition>
  3. Delete the three lines with condition tags.

    If you don’t remove the conditional text tags around the widget, the widget won’t appear to customers who have viewed the necessary number of answers or performed searches, even if they select the Call Plans > Prepay product. All they will see is an error message telling them their question cannot be submitted.
  4. Edit the SmartAssistantDialog widget code to add the dnc_label_ attributes.

    Your code will resemble the following.
    <rn:widget path="input/SmartAssistantDialog" dnc_label_cancel_button="Close"
     dnc_label_banner="Your question cannot be submitted." dnc_label_dialog_title="This
     question cannot be submitted." dnc_redirect_url="/app/answers/list" />
  5. Save the file.

Require Information on the Ask a Question Page

Your business needs may require you obtain additional information from customers when they use the Ask a Question page.

  1. Open /views/pages/ask.php.

  2. Locate the following lines of code.

    <rn:condition content_viewed="2" searches_done="1">
        <rn:condition_else/>
            <rn:widget path="input/SmartAssistantDialog"/>
    </rn:condition>
  3. Delete the three lines with condition tags.

    If you don’t remove the conditional text tags around the widget, the widget won’t appear to customers who have viewed the necessary number of answers or performed searches, even if they select the Troubleshooting category. All they will see is an error message telling them their question cannot be submitted.
  4. Edit the SmartAssistantDialog widget code to add the dnc_label_ attributes.

    Your code will resemble the following.
    <rn:widget path="input/SmartAssistantDialog" dnc_label_cancel_button="Complete Form"
     dnc_label_banner="We need more information before submitting your question."
     dnc_label_dialog_title="More information required" />
  5. Save the file.

Account Pages

Change the Account Overview Page Headings

This example show you how to customize the page heading on the Account Overview page.

  1. Open /views/pages/account/overview.php.

  2. Locate <h2><a class="rn_Questions" href="/app/account/questions/list#rn:session#">#rn:msg:MY_SUPPORT_QUESTIONS_LBL#</a></h2>.

  3. Edit the code with your revised heading.

    <h2><a class="rn_Questions" href="/app/account/questions/list#rn:session#">
    Incidents You Have Submitted</a></h2>
  4. Save the file.

Display Service Contracts on the Account Overview Page

If your organization uses SLAs and you want them to be visible to your customers, you can add the Service Contracts section to the Account Overview page.

  1. Open /views/pages/account/overview.php.

  2. Locate this code:

    <a href="/app/social/questions/list/author/#rn:profile:socialUserID#/kw/*#rn:session#">
    #rn:msg:SEE_ALL_MY_DISCUSSION_QUESTIONS_LBL#</a>
    </rn:container>
    </div>
  3. Add this code just after the code you located in the previous step.

    <h2><class="rn_Contracts">#rn:msg:SERVICE_CONTRACTS_LBL#</strong></h2>
    <div class="rn_Contracts">
        <rn:widget path="reports/Grid" report_id="185" label_caption=
    "#rn:msg:YOUR_SERVICE_CONTRACTS_LBL#"/>
    </div>
  4. Save the file.

Add Login Information to the Account Overview Page

You can add the login statistics reports to the Account Overview page.

  1. Open /views/pages/account/overview.php.

  2. Locate this code:

    <a href="/app/social/questions/list/author/#rn:profile:socialUserID#/kw/*#rn:session#">
    #rn:msg:SEE_ALL_MY_DISCUSSION_QUESTIONS_LBL#</a>
    </rn:container>
    </div>
  3. Add the appropriate code just after the code you located in the previous step.

    • To show Contact Login Statistics, add <rn:widget path="reports/Grid" report_id="10046" label_caption="Previous Logins" date_format="date_time"/>.
    • To show Unsuccessful Login Attempts by Contact, add <rn:widget path="reports/Grid" report_id="10047" label_caption="Previous Unsuccessful Login Attempts" date_format="date_time"/>.
  4. Save the file.

Remove the Search Field from the Support History Page

You can remove the search field from the support history page.
  1. Open /views/pages/account/questions/list.php.

  2. Delete the following lines of code.

    <div class="rn_SearchControls">
        <h1 class="rn_ScreenReaderOnly">#rn:msg:SEARCH_CMD#</h1>
        <form onsubmit="return false;" class="translucent">
            <rn:container report_id="196">
                <div class="rn_SearchInput">
                    <rn:widget path="search/KeywordText" label_text="#rn:msg:
                     SEARCH_YOUR_SUPPORT_HISTORY_CMD#"label_placeholder=
                     "#rn:msg:SEARCH_YOUR_SUPPORT_HISTORY_CMD#" initial_focus="true"/>
                </div>
                <rn:widget path="search/SearchButton"/>
            </rn:container>
        </form>
        <div class="rn_SearchFilters">
            <rn:widget path="search/ProductCategorySearchFilter" />
            <rn:widget path="search/ProductCategorySearchFilter" filter_type="Category"/>
        </div>
    </div>
  3. Save the file.

Change the Report on the Support History Page

By default, the Support History page uses the Questions report.

  1. Open one of these files.

    • /views/pages/account/questions/list.php
    • /views/pages/mobile/account/questions/list.php
  2. Locate <rn:container report_id="196">.

  3. Replace 196 with the ID for the standard or custom report you want to use.

  4. Save the file.

Display All Incidents from a Customer’s Organization

The OrgList2 widget lets customers choose which incidents they see.

  1. Open /views/pages/account/questions/list.php.

  2. Locate <div class="rn_PageContent rn_Container">.

  3. Enter <rn:widget path="search/OrgList" search_on_select="true" /> just above the page container tag.

    <rn:widget path="search/OrgList" search_on_select="true" />
    <div class="rn_PageContent rn_Container">
  4. Save the file.

Configure the Account Settings Page

The Account Settings page lets your customers update their account information.

The Public Profile section lets users change their display name and avatar. Any contact custom fields given End-user Read/Write Visibility appear on this page.
  1. Open /views/pages/account/profile.php.

  2. To edit the title, replace the content between the <h1> tags with the new title.

    <h1>#rn:msg:ACCOUNT_SETTINGS_LBL#</h1>
  3. To add a field to the Account Settings page, insert a line of code that calls the FormInput widget in the location on the page where you want the field to appear.

    To add the alternate email address fields to the page, add these lines of code.
    <rn:widget path="input/FormInput" name="Contact.Emails.ALT1.Address"
     label_input="Alternate Email 1" />
    <rn:widget path="input/FormInput" name="Contact.Emails.ALT2.Address"
     label_input="Alternate Email 2" />
  4. To add a radio button selection that lets customers opt in to communications from your marketing department, add <rn:widget path="input/FormInput" name="Contact.MarketingSettings.MarketingOptIn" label_input="Opt in to marketing communications from us?"/> wherever you want in the block of FormInput widgets on the page.

  5. To remove one of the contact fields, locate the line of code that displays the field and delete it.

    To remove the phone field, you would delete <rn:widget path="input/FormInput" name="Contact.Phones.HOME.Number" label_input="#rn:msg:HOME_PHONE_LBL#">.
    Note: The profile.php code contains conditional sections that display the physical address fields in a different sequence if the browser is using an Asian language. If you want to remove any or all of these fields for all languages, be sure to remove them from both conditions.
  6. To remove the Public Profile section, delete the code leaving only the closing form and div tags.

        </form>
    </div>
  7. Save the file.

Configure the Public Profile Page

The Public Profile page displays the community user’s display name and avatar, recent community activity, a search field, a section that displays the user’s contribution activity, and a print button.

  1. Open views/pages/public_profile.

  2. To change the user’s avatar size from the default of extra large, add the avatar_size attribute to the AvatarDisplay widget and set its value to small, medium, or large.

    <rn:widget path="user/AvatarDisplay" avatar_size="medium"/>
  3. To change the avatars used in the Recent Activity section from the default of medium, add the avatar_size attribute to the UserActivity widget and set its value to none, small, large, or xlarge.

    <rn:widget path="user/UserActivity" avatar_size="large"/>
  4. To remove the “Member since” information from the header, delete #rn:msg:MEMBER_SINCE_LBL# <span itemprop="dateCreated"><rn:field name="SocialUser.CreatedTime" /></span>.

  5. To limit the types of user activity displayed on the Public Profile page, add the type attribute to the UserActivity widget and set the value to a comma-separated list of only the activity types you want to display.

    <rn:widget path="user/UserActivity" type="bestAnswerGivenToUser,commentRatingGivenToUser,
     commentRatingGivenToUser,questionRatingGivenToUser"/>
  6. To remove the search field, delete this code.

    <div class="rn_ProfileSearch">
        <fieldset>
            <legend>#rn:msg:SEARCH_USERS_CONTRIBUTIONS_LBL#</legend>
            <rn:widget path="search/SimpleSearch" icon_path=""
             report_page_url="/app/social/questions/list" add_params_to_url="author:userFromUrl"/>
        </fieldset>
    </div>
  7. To limit the types of contributions displayed in the User’s Contributions section from the default of questions, comments, and answers, add the contribution_types attribute to the UserContributions widget and select only the type of contributions you want to display.

    <rn:widget path="user/UserContributions" contribution_types="comments, answers"/>
  8. To remove the user’s contribution section, delete <rn:widget path="user/UserContributions"/>.

  9. To remove the option to print the page, delete <rn:widget path="utils/PrintPageLink"/>.

  10. Save the file.

Modify the Avatar Selection Options

You can modify the order or remove options from the default avatar selections: default, gravatar, and avatar_library.

  1. Open /views/pages/account/profile_picture.php.

  2. Locate <rn:widget path="input/SocialUserAvatar" />.

  3. Edit the widget code to add the avatar_selection_options attribute.

    • To remove an option, delete the option value from the avatar_selection_options list:
      <rn:widget path="input/SocialUserAvatar" 
       avatar_selection_options="default,avatar_library" />
    • To change the option order, reorder the option values:
      <rn:widget path="input/SocialUserAvatar"
       avatar_selection_options="avatar_library,default,gravatar" />
  4. Save the file.

Add or Remove Incident Details on the Question Details Page

The Additional Details section on the Question Details page provides additional incident and customer information.

  1. Open /views/pages/account/questions/detail.php.

  2. Locate <div class="rn_AdditionalInfo">.

  3. To add an incident detail, add a line of code that adds the DataDisplay widget to the block of DataDisplay code for incident fields.

    For example, you can include the time the incident was closed by adding <rn:widget path="output/DataDisplay" name="Incident.ClosedTime" label="Closed" />.
  4. To remove one of the incident fields, locate the line of code that displays the field and delete it.

  5. Save the file.

Prevent Customers from Solving Incidents

You can remove the status field from the page, which prevents customers from solving incidents.

When customers select “No, I don’t need this question answered now” from the Do You Want a Response? drop-down menu and then click Submit, the incident’s status is set to Solved automatically.
  1. Open /views/pages/account/questions/detail.php.

  2. Delete the following line of code.

    <rn:widget path="input/FormInput" name="Incident.StatusWithType.Status"
     label_input="#rn:msg:DO_YOU_WANT_A_RESPONSE_MSG#"/>
  3. Save the file.

Prevent Customers from Updating Solved Incidents

You can change the amount of time until an incident can no longer be updated or you can prevent customers from ever updating a closed incident.
  1. Open /views/pages/account/questions/detail.php.

  2. Locate this code.

    <rn:condition incident_reopen_deadline_hours="168">
  3. Edit the code to change the value for the incident_reopen_deadline_hours attribute to 0.

    <rn:condition incident_reopen_deadline_hours="0">
  4. Save the file.

Remove Notifications from the Notifications Page

The Notifications page displays all answer notifications, product/category answer notifications, discussions, and product discussion notifications the customer is subscribed to.

  1. Open /views/pages/account/notif/list.php.

  2. To remove the Answer Notifications section, delete the following lines of code.

    <h2>#rn:msg:ANS_NOTIFICATIONS_LBL#</h2>
    <rn:widget path="notifications/AnswerNotificationManager" />
  3. To remove the Product/Category Notifications section, delete the following lines of code.

    <h2>#rn:msg:PRODUCTCATEGORY_ANSWER_NOTIFICATIONS_LBL#</h2>
    <rn:widget path="notifications/ProdCatNotificationManager" 
     report_page_url="/app/#rn:config:CP_PRODUCTS_DETAIL_URL#" />
  4. To remove the Discussion Notifications section, delete the following lines of code.

    <h2>#rn:msg:DISCUSSION_NOTIFICATIONS_LBL#</h2>
    <rn:container report_id="15104">
        <rn:widget path="reports/ResultInfo" static_filter="User=#rn:profile:socialUserID#"/>
        <rn:widget path="notifications/DiscussionSubscriptionManager" 
         static_filter="User=#rn:profile:socialUserID#"/>
    </rn:container>
  5. To remove the Product Discussion Notifications section, delete the following lines of code.

    <h2>#rn:msg:PRODUCT_DISCUSSION_NOTIFICATIONS_LBL#</h2>
    <rn:container report_id="15105">
        <rn:widget path="reports/ResultInfo" static_filter="User=#rn:profile:socialUserID#"/>
        <rn:widget path="notifications/DiscussionSubscriptionManager"
         static_filter="User=#rn:profile:socialUserID#" subscription_type="Product"
         label_no_notification="#rn:msg:CURRENTLY_DONT_ANY_DISC_NOTIF_MSG#"/>
    </rn:container>
  6. Save the file.

Remove Notifications from Customer Portal

If you don’t want customers to subscribe to answers, you’ll need to remove the Notify Me link from the Answer Details and Community Question Details pages.

  1. Remove the Notify Me icon from the Answer Details page.

    1. Open /views/pages/answers/detail.php.

    2. Delete this code:

      <rn:condition logged_in="true">
          <rn:widget path="notifications/AnswerNotificationIcon" />
      </rn:condition>
    3. Save the file.

  2. Remove the Subscribe link from the Community Question Details page.

    1. Open views/pages/social/questions/detail.php.

    2. Delete this code.

      <rn:widget path="notifications/DiscussionSubscriptionIcon"/>
    3. Save the file.

Configure the PasswordInput Widget

The PasswordInput widget lets you define the strength of customer passwords on the administration interface.

  1. Open /views/pages/account/change_password.php.

  2. Locate this code.

    <rn:widget path="input/PasswordInput" name="Contact.NewPassword" require_validation="true" 
     require_current_password="true" label_input="#rn:msg:PASSWORD_LBL#"
     label_validation="#rn:msg:VERIFY_PASSWD_LBL#" initial_focus="true"/>
  3. To enable the customer’s web browser to auto-complete the password values, add the disable_password_autocomplete attribute and set it to false.

    <rn:widget path="input/PasswordInput" name="Contact.NewPassword" require_validation="true"
     require_current_password="true" disable_password_autocomplete="false" 
     label_input="#rn:msg:PASSWORD_LBL#" label_validation="#rn:msg:VERIFY_PASSWD_LBL#"
     initial_focus="true"/>
  4. To remove the Current Password field from the form so that customers must enter only the new password value, delete the require_current_password attribute.

  5. To remove the validation requirement that causes the Verify Password field to appear, delete the require_validation attribute.

  6. Save the file.

Community Home Page

Modify the Community Announcement Text

You can greet the community or your community moderators with a message tailored to your business needs.

  1. Open one of these text files:

    • /assets/others/community-announcement.txt
    • /assets/others/moderator-announcement.txt
  2. Modify the text, as needed.

  3. Save the file.

Modify Common Widgets Used in the Community Page

You can customize the numerous widgets used in the reference community home page file.

  1. To modify the utils/AnnouncementText widget, set the required attribute file_path to the location in /assets/ for the file containing your announcement text.

  2. To modify the discussion/ForumList widget, add or change these attributes and values:

    1. To change the date format, modify the last_activity_date_format attribute.

      • full_textual (example: January 1, 2000)

      • short_textual (example: Jan 1, 2000)

      • numeric (example: 1/1/2000)

    2. To include a column of information about the forum, add the show_columns attribute and the value for the column.

      • question_count

      • comment_count

      • last_activity

      This example code removes the column containing information about the last activity.
      <rn:widget path="discussion/ForumList" show_column="question_count,comment_count">
    3. To change the number of forums shown in the list, modify the max_forum_count attribute.

      The max_forum_count is set to 10 by default, but can include as many as 40 forums.
    4. To change the amount of text shown in the forum description, modify the maximum_description_length attribute.

  3. To modify the user/UserList widget, add or change these attributes and values:

    1. To modify the time period considered for displaying users, set the activity_time_period attribute.

      • past_day

      • past_week

      • past_month

      • past_year

      • any_time

      This example code includes only users active in the past week.
      <rn:widget path="user/UserList" activity_time_period="past_week" content_display_type="table_view" avatar_size="small"/>
    2. To change the size of the avatar displayed, modify the avatar_size attribute.

      • none

      • small

      • medium

      • large

    3. To set the format the content is displayed in, modify the content_display_type attribute.

      • table_view

      • list_view

    4. To set which content is listed in the results, add the content_type attribute.

      • questions

      • comments

      • best_answers

      This example code includes a list of users active in the comments.
      <rn:widget path="user/UserList" content_type="comments" content_display_type="table_view" avatar_size="small"/>
    5. To set the maximum number of users shown in the list, add the max_user_count attribute.

    6. To remove the avatar from the list, se the show_avatar attribute to false.

  4. To modify the user/RecentlyActiveUsers widget, add or change these attributes and values:

    1. To change the size of the avatar displayed, modify the avatar_size attribute.

      • none

      • small

      • medium

      • large

    2. To set the format the content is displayed in, modify the content_display_type attribute.

      • grid_view

      • list_view

    3. To change the date format, modify the last_active_date_format attribute.

      • full_textual (example January 1, 2000)

      • short_textual (example Jan 1, 2000)

      • numeric (example 1/1/2000)

    4. To modify the time period considered for displaying users, set the show_users_active_in attribute.

      • past_day

      • past_week

      • past_month

    5. To determine which information shows for each user when the content is rendered as a list, set the specify_list_view_metadata attribute with at least one of these values:

      • user_avatar

      • display_name

      • last_active

      • default: user_avatar, display_name, last_active

    6. To change the maximum number of users displayed, set the max_user_count attribute.

  5. To modify the utils/TwitterPosts widget, add or change these attributes and values:

    1. To set the required attribute fetch_tweets_using, add one of these values:

      • account

      • hashtag

      • search_query

    2. To display a specific number of tweets, add the data_tweet_limit attribute and set the value between 1 and 20.

    3. To set the Twitter account used to fetch tweets, add a value to the twitter_account attribute.

      Your code will look something like this:
      <rn:widget path="utils/TwitterPosts" twitter_account="OracleCX"/>

Chatting on the Customer Portal

Overview of Chat on the Customer Portal

When Chat is enabled on your site, the Contact Us sidebar on the Results and Answer and Discussion Details pages automatically includes a Live Chat link.

Occasionally, your customers may not find the information they are looking for on your support site or need an answer more quickly than a typical email response.

When a customer clicks a Chat link on your customer portal, the Live Help page opens and displays a small chat request form. After the request is submitted, the Chat page opens indicating the customer’s position in the queue. After an agent accepts the chat request, the Chat page provides a place for the customer to post messages to the agent, and displays a transcript of the chat session.

The Live Help page is where your customers submit a request for a chat session. After the request has been submitted, the Chat page opens and the customer can begin chatting with an available agent. The Live Help page is opened when customers click the Live Chat navigation link in the Contact Us sidebar or any other Chat link that may have been added to your customer portal.

The default Live Help page displays the customer’s first and last names and email address if the customer is logged in. If the customer is not yet logged in, the fields are blank waiting for customer input. If you have incident custom fields with chat visibility, those fields are displayed on the default Live Help page as well, with required custom fields noted by a red asterisk. The page also contains a Submit button, a chat status message, and the chat hours listing.

Change the Live Help Page Message Bases

You can modify the Live Help page labels and headings.

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

  2. To change the Live Help heading, locate <h1>#rn:msg:LIVE_HELP_HDG#</h1> and enter the new heading between the <h1> and </h1> tags.

  3. To change the Chat subheading, locate <span class="rn_ChatLaunchFormHeader">#rn:msg:CHAT_MEMBER_OUR_SUPPORT_TEAM_LBL#</span> and replace the message base with your replacement heading.

    <span class="rn_ChatLaunchFormHeader">Talk to someone on our support team
     right now!</span>
  4. To change the Chat Support available message, locate <rn:widget path="chat/ChatStatus"/> and add the label_chat_available attribute to the widget.

    <rn:widget path="chat/ChatStatus"
     label_chat_available="Agents are currently available." />
  5. To remove fields from the Live Help page, locate this code.

    <rn:widget path="input/FormInput" name="Incident.Subject" initial_focus="true"
     label_input="#rn:msg:SUBJECT_LBL#"/>
        <rn:condition config_check="COMMON:intl_nameorder == 1">
            <rn:widget path="input/FormInput" name="Contact.Name.Last"
             label_input="#rn:msg:LAST_NAME_LBL#" required="true"/>
            <rn:widget path="input/FormInput" name="Contact.Name.First"
             label_input="#rn:msg:FIRST_NAME_LBL#" required="true"/>
        <rn:condition_else/>
            <rn:widget path="input/FormInput" name="Contact.Name.First"
             label_input="#rn:msg:FIRST_NAME_LBL#" required="true"/>
            <rn:widget path="input/FormInput" name="Contact.Name.Last"
             label_input="#rn:msg:LAST_NAME_LBL#" required="true"/>
        </rn:condition>
        <rn:widget path="input/FormInput" name="Contact.Emails.PRIMARY.Address"
         required="true" label_input="#rn:msg:EMAIL_ADDR_LBL#"/>
        <!-- optional fields -->
        <rn:widget path="input/CustomAllInput" table="Incident"
         chat_visible_only="true" always_show_mask="false" />
    1. To remove the Subject field, delete <rn:widget path="input/FormInput" name="Incident.Subject" initial_focus="true" label_input="#rn:msg:SUBJECT_LBL#"/>.

    2. To remove the Last Name field and display only the first name, delete <rn:widget path="input/FormInput" name="Contact.Name.Last" label_input="#rn:msg:LAST_NAME_LBL#" required="true"/> from both condition cases.

    3. To remove the Email Address field, delete <rn:widget path="input/FormInput" name="Contact.Emails.PRIMARY.Address" required="true" label_input="#rn:msg:EMAIL_ADDR_LBL#"/>.

    4. To remove incident custom fields, delete this code.

      <!-- optional fields -->
      <rn:widget path="input/CustomAllInput" table="Incident"
       chat_visible_only="true" always_show_mask="false" />
  6. Save the file.

Change Available Chat Hours

You change chat hours on the administration interface. Those hours are listed on the Live Help page.

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

  2. Click the interface you want to edit chat hours for.

  3. Click Chat Hours.

  4. To add a day, click Add and select a day.

  5. To edit the start hour and minute or the end hour and minute for any day, click in the field and enter the new value.

  6. Click Save.

Chat Page

The Chat page opens after customers submit a chat request.

By default, the chat_landing.php file for the Chat page contains the include_chat page meta tag, which is set to true. If you create additional pages that contain a chat application, you must include this meta tag and set it true in the page file. When the include_chat tag is set to true, the page includes all the required JavaScript files for Chat.

Although the default Chat page includes multiple widgets, these widgets are necessary to create a usable Chat page.

  • ChatServerConnect

  • ChatTranscript

  • ChatPostMessage

Configure the ChatServerConnect Widget

You can change labels, icons, and other attributes of the ChatServerConnect widget.

  1. Open one of these files:

    • /views/pages/chat/chat_landing.php
    • /views/pages/mobile/chat/chat_landing.php
  2. Locate <rn:widget path="chat/ChatServerConnect"/>.

  3. To change the loading icon, add the loading_icon_path attribute to the widget.

    <rn:widget path="chat/ChatServerConnect" loading_icon_path="images/indicator_2.gif" />
  4. To edit any of the default labels (shown in quotation marks), add the associated attribute and define it with your new label.

    • label_connecting—“Please wait while we establish a connection to the Chat Server.”

    • label_connection_fail—“There was a problem connecting to the Chat Server.”

    • label_connection_success—“A connection to the Chat Server has been established successfully.”

    • label_prevent_anonymous_chat—“One or more required contact fields are missing. Please review all fields and re-submit the chat request.” This attribute applies only when you prevent anonymous chat requests by requiring one or more of the email, first name, and last name fields (the email_required, first_name_required, or last_name_required attributes).

    • label_terminate_session—“This action will terminate your current session. Do you want to continue?”

    <rn:widget path="chat/ChatServerConnect" label_connecting="We are connecting
     to the chat server now." />
  5. Save the file.

Disable New Message Notifications

You can disable the notification customers receive when the chat agent sends a new message and the transcript window does not have focus.

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

  2. Locate <rn:widget path="chat/ChatTranscript"/>.

  3. Add the unread_messages_titlebar_enabled attribute to the widget and set it to false.

    <rn:widget path="chat/ChatTranscript" unread_messages_titlebar_enabled="false" />
  4. Save the file.

Replace the ChatTranscript Widget Icons

You can replace the default icons by defining the path and file name for the replacement icon.

All default icons are in the /cp/customer/assets/themes/standard/images folder, but you can reference the path in the widget attribute by entering images/<filename>.
  1. Open chat_landing.php.

  2. Find <rn:widget path="chat/ChatTranscript" />.

  3. Add the appropriate attributes to the widget.

    • Agent Message Icon—agent_message_icon_path
    • Alert Icon—alert_icon_path
    • End-user Message Icon—enduser_message_icon_path
    • Off the Record Icon—off_the_record_icon_path
    <rn:widget path="chat/ChatTranscript" agent_message_icon_path="images/chat_agent_new.png" />

Edit the Chat Instructions Label

You can change the message that is displayed to the customer.

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

  2. Locate <rn:widget path="chat/ChatPostMessage"/>.

  3. Add the label_send_instructions attribute to the ChatPostMessage widget.

    <rn:widget path="chat/ChatPostMessage" label_send_instructions="Your new instructions for sending a message." />
  4. Save the file.

Notify Customers of Incoming Messages

You can bring the chat window to the top or flash the task bar button to notify customers that a new response is available.

This functionality is only available for customers using Internet Explorer.
  1. Open /views/pages/chat/chat_landing.php.

  2. Locate <rn:widget path="chat/ChatPostMessage"/>.

  3. Add the focus_on_incoming_messages attribute to the ChatPostMessage widget.

    <rn:widget path="chat/ChatPostMessage" focus_on_incoming_messages="true" />
  4. Save the file.

Add the ChatCobrowsePremium Widget

You can let customers share their desktop with agents who are chatting with them.

  1. Do one of the following:

    • Open /views/pages/chat/chat_landing.php.
    • Open /views/pages/mobile/chat/chat_landing.php.
  2. Locate this code.

    <div id="rn_InChatButtonContainer">
        <rn:widget path="chat/ChatAttachFileButton"/>
        <rn:widget path="chat/ChatSendButton"/>
  3. Add <rn:widget path="chat/ChatCobrowsePremium" />.

    <div id="rn_InChatButtonContainer">
        <rn:widget path="chat/ChatAttachFileButton"/>
        <rn:widget path="chat/ChatSendButton"/>
        <rn:widget path="chat/ChatCobrowsePremium" />
  4. Save the file.

Change the Chat Window Size

The size of the Chat window is determined by the ChatLaunchButton widget used on the Live Help page.

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

  2. Locate this code.

    <rn:condition config_check="MOD_VA_ENABLED == 0">
        <rn:widget path="chat/ChatLaunchButton" launch_width="390" launch_height="595"
         error_location="rn_ErrorLocation" add_params_to_url="q_id,pac,request_source,p,c,
         survey_send_id,survey_send_delay,survey_comp_id,survey_term_id,chat_data,
         survey_term_auth,survey_comp_auth"/>
    <rn:condition_else/>
        <rn:widget path="chat/ChatLaunchButton" launch_width="390" launch_height="800"
         error_location="rn_ErrorLocation" add_params_to_url="q_id,pac,request_source,p,c,
         survey_send_id,survey_send_delay,survey_comp_id,survey_term_id,chat_data,
         survey_term_auth,survey_comp_auth,survey_send_auth,i_id"/>
    </rn:condition>
  3. Edit the launch_height and launch_width attributes to both instances of the ChatLaunchButton widget.

    ...
    <rn:widget path="chat/ChatLaunchButton" launch_width="250" launch_height="250"
    ...
    <rn:condition_else/>
        <rn:widget path="chat/ChatLaunchButton" launch_width="250" launch_height="500"
    ...
  4. Save the file.

Change the Answer Window Size

You can control the size of the window that opens when the Search button is clicked.

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

  2. Locate <rn:widget path="chat/ChatQueueSearch" popup_window="true"/>.

  3. Add the following attributes and set their percentage value.

    1. popup_window_height_percent (default 42 percent).

    2. popup_window_width_percent (default 30 percent).

    <rn:widget path="chat/ChatQueueSearch" popup_window="true"
     popup_window_height_percent="75"
     popup_window_width_percent="75" />
  4. Save the file.

Configure Chatting Off the Record

The default Chat page contains a button that customers can click to send an off-the-record message.

Any information the customer types in the Off the Record Message dialog will not appear on the Messages tab of the incident created from the chat session. Instead, the incident will show “Message Removed.” Text that is submitted off-the-record is displayed with a different color and icon in the chat transcript window.
  1. Open the appropriate chat landing file.

    • /views/pages/chat/chat_landing.php
    • /vies/pages/mobile/chat/chat_landing.php
  2. To set all chat posts off the record, edit the ChatPostMessage code to add the all_posts_off_the_record attribute.

    <rn:widget path="chat/ChatPostMessage" all_posts_off_the_record="true" />
  3. To remove the off-the-record chat option, delete these two lines of code.

    • <rn:widget path="chat/ChatOffTheRecordDialog"/>

    • <rn:widget path="chat/ChatOffTheRecordButton"/>

  4. Save the file.

Remove the Search Field from the Chat Page

You can delete the search field from the Chat page.

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

  2. Delete this code.

    <div id="rn_ChatQueueSearchContainer">
        <rn:widget path="chat/ChatQueueSearch" popup_window="true"/>
    </div>
  3. Save the file.

Remove Virtual Assistant Widgets

If your customer portal is not integrated with B2C Service Virtual Assistant, you should remove the Virtual Assitant widgets.

The reference implementation default Chat page includes these virtual assistant widgets: VirtualAssistantAvatar, VirtualAssistantBanner, VirtualAssistantSimilarMatches, and VirtualAssistantFeedback.
  1. Open /views/pages/chat/chat_landing.php.

  2. Delete these two sections of code.

    <div id="rn_VirtualAssistantContainer">
        <rn:widget path="chat/VirtualAssistantAvatar"/>
        <rn:widget path="chat/VirtualAssistantBanner"/>
    </div>
    <rn:widget path="chat/VirtualAssistantSimilarMatches"/>
    <rn:widget path="chat/VirtualAssistantFeedback"/>
  3. Save the file.

Configure the ConditionalChatLink Widget

There are a number of attribute you can set for the ConditionalChatLink widget.

  1. Open the page to edit.

    • Open the page that includes the ContactUs widget where you want to configure conditional chat.
    • Open the page where you’ve added the ConditionalChatLink widget.
  2. To detect an incident ID and pass it through the URL for the chat agent, add the auto_detect_incident attribute to the widget and set its value to true.

    <rn:widget path="utils/ContactUs" auto_detect_incident="true" />
  3. To change the Launch page that opens when customers click the chat link, add the chat_login_page attribute and set its value to the new page.

    <rn:widget path="utils/ContactUs"
     chat_login_page="/app/chat/chat_launch_alternate1" />
  4. To hide the chat so it appears on your customer portal only when agents are available, add the hide_on_unavailable attribute and set its value to true.

    <rn:widget path="utils/ContactUs" hide_on_unavailable="true" />
  5. To consider information entered by customers after they’ve been pre-routed, enabling routing rules to check the values of customer fields and re-route the request accordingly, add the ignore_preroute attribute and set it to true.

    <rn:widget path="utils/ContactUs" ignore_preroute="true" />
    Note: The ignore_preroute attribute should be enabled only when necessary for achieving a specific business goal. The agent availability detection and pre-routing functions occur before routing rules are applied. As a result, when the ignore_preroute attribute is enabled, customers may be routed to a different queue than the one originally determined by agent availability, even a queue for which no agent is immediately available. This can conflict with the indication of availability expressed by the widget itself, leading to customer confusion.
  6. To open the Chat Launch page in a new window, add the open_in_new_window attribute, set it to true, and then define the size with the chat_login_page_height and chat_login_page_width attributes.

    <rn:widget path="utils/ContactUs" open_in_new_window="true"
     chat_login_page_height="500" chat_login_page_width="500" />
  7. Save the page.

Offering Customers a Chat Session

You can offer customers a chat session when it appears they are not finding the information they are looking for.

You can proactively offer a chat session from your customer portal pages as well as from any external page on your website.

These events occur when a customer accepts a chat offer through either the ProactiveChat widget in the /cp/core/widgets/standard/chat folder or the syndicated ProactiveChat widget.

  • Before the chat is offered to the customer, the chat session routing rules determine what queue the chat request will be directed to based on products, categories, custom fields, and other rule conditions.

  • When the customer accepts the chat request, the Chat page that opens contains any incident custom fields that have chat visibility.

  • If the customer changes any of the information on the Chat page, that information is passed to the agent on the chat session workspace. The rules engine does not run again. As a result, the customer may change a field that would have triggered the chat being assigned to a different queue, but because rules are not run on the updated Chat page, the original queue assignment does not change.

We recommend that you do not add any fields to the Chat page that would result in a queue reassignment if the customer edits that field since reassignment does not occur with either the standard or syndicated widget. If you want to display a different page to customers who enter a chat session through a proactive chat offer, you can create a custom Chat Login page. After you create the custom page, change the chat_login_page attribute for the widget to specify the custom page.

If you want to place the ProactiveChat widget on the /answers/list.php page, place it within the container defined by <rn:condition url_parameter_check="kw != null">. Then when a search is performed while viewing all published answers, the page is loaded with the ProactiveChat widget in place. Otherwise, it may not appear due to the page refresh that occurs when a search term is entered.

Chat sessions are not offered in these situations.

  • If the customer’s browser does not accept cookies, no chat is offered during the customer session.

  • If the widget looks for a chat queue ten times without finding one, no chat is offered on that page.

  • If a chat is offered (whether or not it is accepted), a cookie is set and no more chat offers are made during the current customer session.

  • If a chat is offered and the customer refuses, a cookie is set and no more chat offers are made for 30 days.

Reports for ProactiveChat

There are two standard reports available for the ProactiveChat widget.

The standard reports available can be found in the Reports explorer Public Reports/Service/Chat Reports/Proactive Chat.

  • Proactive Chat Offer Statistics—Shows the number of site visits, proactive chat invitations, and accepted, declined, refused, and ignored chat invitations.

  • Proactive Chat Summary Statistics—Shows the number of chat requests resulting from a proactive chat invitation and the number of chat sessions that were deflected, abandoned, and accepted (with and without agent interaction).

Add the ProactiveChat Widget to a Page

This example adds the ProactiveChat widget to the results page.

Chat must be enabled and agents must be available before a chat will be offered to a customer. The customer’s browser must be configured to accept cookies.
The default code for the ProactiveChat widget will not trigger a chat offer until you add an attribute that defines the trigger for the offer. You must add at least one of the following attributes to the code: seconds, searches, or profile_ attributes.
  1. Open /views/pages/results.php.

  2. Locate <rn:widget path="reports/Paginator" />.

  3. Add the ProactiveChat widget.

    <rn:widget path="reports/Paginator" />
    <rn:widget path="chat/ProactiveChat" />
    1. To trigger the chat offer based on the customer’s inactive time on the page, add the seconds attribute to the code.

      <rn:widget path="chat/ProactiveChat" seconds="60" />
    2. To trigger the chat offer based on the number of searches the customer conducted, add the searches attribute to the code.

    <rn:widget path="chat/ProactiveChat" searches="3" />
  4. Save the file.

Trigger Chat Offers

When one of the required attributes has been met, an AJAX request is made to the server, which sends back the number of available agents and the minimum wait time.

You must define at least one of these attributes before the chat offer will be triggered: seconds, searches, and profile_.
  1. To offer chat based on page time, add the seconds attribute.

    <rn:widget path="chat/ProactiveChat" seconds="60" />
  2. To offer chat based on number of searches, add the searches attribute.

    <rn:widget path="chat/ProactiveChat" searches="3" />
  3. To offer a chat based on customer profile information, define the profile_item, profile_operator, and profile_value attributes.

    <rn:widget path="chat/ProactiveChat" profile_item="org_id"
     profile_operator="equals" profile_value="81945" />

    The following list includes all the profile items you can use as conditions for offering chats to customers.

    • slac—The number of chat incidents the customer’s SLA allows.

    • slai—The number of self-service incidents the customer’s SLA allows.

    • web_access—The customer’s SLA allows self-service.

    • org_id—The ID of the organization associated with the customer.

    • o_lvlN—The ID of the organization’s sublevel, if the organization has subsidiaries, where N is the organization level.

    Any of the following operators are valid for defining profile items.
    • Equals

    • Less than or equals

    • Greater than or equals

    • Not equal

    • Less than

    • Greater than

  4. To offer a chat based on an event, you must use custom code:

    1. Create an event called evt_customProactiveInitialization.

    2. Set the initiate_by_event attribute of the ProactiveChat widget to true.

If your organization requires SLAs in order for customers to chat with agents, you’ll want to verify that the customer has an SLA with available chat incidents before a chat session is offered. The profile attributes of the ProactiveChat widget can do that for you.

Add the profile_item, profile_operator, and profile_value attributes to the code for the ProactiveChat widget.

Your edited code will resemble the following.

<rn:widget path="chat/ProactiveChat" seconds="30" profile_item="slac"
 profile_operator="greater than" profile_value="0" />

Configure the ProactiveChat Widget

A number of attributes are available to customize and configure the ProactiveChat widget.

Define the seconds, searches, or profile_ attributes in order to Trigger Chat Offers.
  1. To edit the chat invitation message, add the label_chat_question attribute.

    <rn:widget path="chat/ProactiveChat" seconds="30"
     label_chat_question="Staff members are available now.
     Would you like to chat with someone?" />
  2. To change the Chat Login page, add the chat_login_page attribute.

    <rn:widget path="chat/ProactiveChat" seconds="30"
     chat_login_page="/app/chat/alternate_chat_launch_page" />
  3. To change the size of the chat login window, add the chat_login_page_height and chat_login_page_width attributes.

    <rn:widget path="chat/ProactiveChat" seconds="30" chat_login_page_height="500"
     chat_login_page_width="600" />
  4. To open the Chat Login page in the same window, add the open_in_new_window attribute.

    <rn:widget path="chat/ProactiveChat" seconds="30" open_in_new_window="false" />
  5. To define the maximum wait time, add the wait_threshold attribute.

    <rn:widget path="chat/ProactiveChat" seconds="30" wait_threshold="60" />
  6. To define the minimum number of agents, add the min_agents_avail attribute.

    <rn:widget path="chat/ProactiveChat" seconds="30" min_agents_avail="2" />

Add the Syndicated ProactiveChat Widget to a Web Page

You can place the syndicated ProactiveChat widget on external sites, instead of being restricted to just customer portal pages.

Your profile must have WebDAV permission enabled, and you must log in with your user name and password.
  1. Open https://<your_site>/ci/tags/syndicated_widgets/standard/ProactiveChat.

  2. Scroll down to the Configure Widget section and begin modifying the widget attributes as you choose.

  3. To preview your changes, click Apply.

  4. Click the top Select Text button and copy the code.

  5. Open the web page you want to add the widget to.

  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. In the generated code, click the second Select Text button and copy the code that defines the widget.

  8. Paste the copied code just below the code you pasted, earlier.

  9. Add <div_id="myDiv"></div> to the page code where you want the widget to appear.

  10. Save the page.

Trigger Syndicated Chat Offers

You can define additional conditions that must be met before a chat is offered.

You must set the seconds attribute before a chat offer will be triggered. You could also create custom rules that trigger the chat offer.
The syndicated ProactiveChat widget opens a chat invitation to your customers after they spend a specified amount of time on the page where you placed the widget. The default code for the syndicated ProactiveChat widget will not trigger a chat offer because the default values for the seconds attribute is 0.
  1. Open the syndicated ProactiveChat widget page.

  2. To trigger chat offers based on page time, enter a value in the field for the seconds attribute.

  3. To define the minimum number of agents, enter a value in the field for the min_agents_avail attribute.

  4. To define the maximum wait time, enter a value in the field for the wait_threshold attribute.

Configure the Syndicated ProactiveChat Widget

A number of attributes are available to customize and configure the syndicated ProactiveChat widget.

  1. Open the Syndicated ProactiveChat Widget page.

  2. To define a default product, enter the product ID in the field for the p attribute.

  3. To define a default category, enter the category ID in the field for the c attribute.

  4. To change the Chat Login page, enter a value in the field for the chat_login_page attribute.

  5. To open the Chat Login page in the same window, clear the Enabled check box in the open_in_new_window attribute.

  6. To change the size of the chat login window, enter new height and width attribute values.

    1. Enter the new height of the window, in pixels, in the field for the chat_login_page_height attribute.

    2. Enter the new width of the window, in pixels, in the field for the chat_login_page_width attribute.

  7. To replace default images, reference new image files in /cp/customer/assets/images/.

    1. To replace the avatar image, enter the image file path in the field for the avatar_image attribute.

    2. To replace the logo image, enter the image file path in the field for the logo_image attribute.

    3. Leave the fields blank if you do not want to display any images.

  8. To edit chat invitation messages, edit the label attribute.

    1. To edit the Yes button, enter the new label in the field for the label_accept_button attribute.

    2. To edit the No button, enter the new label in the field for the label_reject_button attribute.

    3. To edit the label for the chat refusal check box, enter the new label in the field for the label_refuse_checkbox attribute.

  9. To edit alternative (alt) text for images.

    1. Enter the new label for the avatar image in the field for the label_avatar_image attribute.

    2. Enter text in the corporate logo image field for the label_logo_image attribute.

  10. To edit the dialog header and title bar, add your own data.

    1. For the header label, enter the new label in the field for the label_dialog_header attribute.

    2. For the title bar, enter the new label in the field for the label_title attribute.

  11. To edit the chat invitation, enter a new chat invitation message in the field for the label_question attribute.

  12. To edit the div element, enter a new name for the div element in the field for the div_id attribute.

    <div id="newDiv"></div>
  13. To edit the instance ID, replace the “0” in “spac_0” in the instance_id attribute with another value for each widget you add to the page. If you have more than one syndicated ProactiveChat widget on a page, you must have unique ID values for each of them. The default value is spac_0.

  14. To change the dialog to modal, select the Enabled check box for the modal attribute.

Custom Rules for Syndicated ProactiveChat

You can define custom rules that specify other conditions for triggering a chat offer.

You may want to offer a chat to customers who have a certain dollar value or a specific type of product in their shopping cart.

The syndicated ProactiveChat widget includes two JavaScript API functions.
  • The chatAvailability() function, for checking agent availability

  • The offerChat() function, for offering a chat invitation

You can call these functions from your web pages on a specific instance of the ProactiveChat widget. This can be done either through an event or with a direct method call. The custom code to trigger a chat offer must appear on the same page where you place the syndicated ProactiveChat widget.

Expose the API Functions

You can request agent availability, offer a chat session using the offerChat() function, and offer a chat using an event.

  1. Open the web page you want to expose the API functions.

  2. Add this code for each widget instance.

    <script type="text/javascript">
        RightNow.Client.Controller.addComponent(
            {
                modal: true,
                instance_id: "spac_0",
                div_id: "myDiv",
                seconds: 0,
                module: "ProactiveChat",
                type: 2
            },
            "http://[your_site]/ci/wsf/get"
        );
    </script>

Use the chatAvailability() Function

You can use this function to check the queue id that is currently assigned to the chat instance, the number of agents available, and the current wait time.

The chatAvailability() function of the syndicated ProactiveChat widget requests agent availability. In this example, the chatAvail() function calls the chatAvailability() function on the spac_0 instance of the syndicated ProactiveChat widget. The callback method, chatDataAvail, displays alerts for the queue ID, agent availability, and wait time data of the result argument.
  1. On the web page containing the widget, add this code to define a function that calls chatAvailability() and to define a callback method.

    function chatAvail(){
        spac_0.chatAvailability(chatDataAvail);
    };
    function chatDataAvail(result){
        alert("q_id "+result.queueId);
        alert("agent_avail "+result.availableAgentSessions);
        alert("wait_time "+result.expectedWaitSeconds);
    };
  2. Make sure that your code calls the function that makes the call to chatAvailability(), which in the example is the chatAvail() function.

Use the offerChat() Function

You can use the offerChat() function to offer a chat session if its Boolean argument is true.

The offerChat() function of the syndicated ProactiveChat widget lets you offer a chat to a user. In this example, the chatAvail() function calls the chatAvailability() function on the spac_0 instance of the syndicated ProactiveChat widget. The callback method, chatDataAvail, examines the result argument to verify that more than one agent is available and, if so, calls the offerChat() function to offer a chat to the user.
  1. On the web page containing the widget, add this code to define a function that calls chatAvailability() and to define a callback method that calls the offerChat() function.

    function chatAvail(){
        spac_0.chatAvailability(chatDataAvail);
    };
    function chatDataAvail(result){
        if(result.availableAgentSessions > 0) {
            alert("offering a chat now");
            spac_0.offerChat(check);
        }
    };
  2. On the web page, make sure that your code calls the function that makes the call to chatAvailability(), which in the example is the chatAvail() function.

Request Chat Availability Using an Event

You can request chat availability through an event.

The code must first subscribe to the evt_chatAvailabilityResponse event and then fire an evt_chatAvailabilityRequest event.
  1. Add this code to the web page containing the syndicated ProactiveChat widget.

    function chatAvailEvent(){
        RightNow.Client.Event.evt_chatAvailabilityResponse.unsubscribe(onDataReady);
        RightNow.Client.Event.evt_chatAvailabilityResponse.subscribe(onDataReady);
        RightNow.Client.Event.evt_chatAvailabilityRequest.fire();
    };
  2. Add code to call the function that requests chat availability, which in the example is chatAvailEvent().

Offer a Chat Using an Event

You can offer a chat session by firing an evt_chatOfferRequest event.

The checkAvailability parameter of the evt_chatOfferRequest event determines whether the request first checks for agent availability. If the argument is set to true, the evt_chatAvailabilityResponse event is first fired, which determines whether agents are available. If the argument is set to false, a chat is offered immediately.
  1. Add this code to the web page containing the syndicated ProactiveChat widget.

    function offerChatEvent(){
        RightNow.Client.Event.evt_chatOfferRequest.fire({data:{checkAvailability: true}, id: "spac_0"});
    };
  2. Add code to call the function that offers the chat, which in this example is offerChatEvent().

Community Self Service Overview

Overview of Community Self Service

Peer-to-peer support has become an increasingly important part of web self-service customer support.

Your customers expect a support site that integrates official company knowledge with solutions from other customers.

Note: This section discusses the Community Self Service feature integrated with Customer Portal Framework Version 3.3 in the August 2015 release. If you are looking for information about configuring B2C Service Social Experience communities, go to Communities on the Customer Portal in the May 2015 documentation.

Your customers have always been able to search for an answer in your knowledge base and ask a question of your customer support agents. Community Self Service adds an extra layer of information for your customers. When they seek an answer to their questions, the Customer Portal returns community content in addition to your published answers. And when they want to ask a question, they now have the option of asking for help from other customers. Even SmartAssistant returns community discussions as well as published answers.

Gaining crowd knowledge from other users means that your customers have a powerful new self-service channel that can reduce the number of incidents your customer support agents need to resolve.

Community Self Service Users

There are several different kinds of users in Community Self Service.

Community users have a Public Profile page associated with their account that includes information about their recent public activity within the Community, including their questions, comments, and answer ratings.

The Community feature prevents anonymous interactions. Unless Community users have a contact record in your database, they can read content but they may not comment, flag information, or forward content. To allow Community interaction, contact records must be extended to include a Community user record that includes display name and avatar. Customers who have a contact record but do not yet have a Community record will be prompted to enter a display name prior to interacting on the Community. Customers who do not have a contact record will be prompted to create both a contact record and a Community record.

Table Community Self Service User Types

User Types Functionality
Unregistered Community users
  • Can browse and search the knowledge base.

Registered Community users When we talk about Community users, we’re generally referring to registered Community users.
  • Can browse and search the knowledge base.

  • Can ask questions.

  • Can provide support to other customers.

Moderators You can configure moderation on your customer portal to create different types of moderators with different privileges and access levels.
  • Can interact with user-generated content and Community users.

  • Can edit, move, and remove content.

  • Can manage customers who disrupt the Community.

  • Can be a staff member or a customer.

Agents Agents who ask or answer questions on the Community will need a Community account in addition to their staff member account on the agent desktop.
  • Can monitor the Community for unanswered questions and respond where appropriate.

Analysts
  • Can review the analytics generated by the Community.

  • Can review reports on the agent desktop.

Administrators
  • Configures the Community Self Service feature on the agent desktop.

  • Can update user roles and permissions.

  • Can extend or create new reports.

  • Can modify configuration settings.

Customer Portal developers
  • Can develop, launch, and maintain your customer portal, including your Community.

Community Self Service Actions

There are a number of actions available for different users within a discussion.

These actions are available within discussions.

  • Questions/Discussions—A question in the community is similar to a B2C Service incident or a discussion in a forum. At a minimum, a question has a title and body, and it may have additional custom fields. Questions cannot have image or file attachments.
    • Asking a question/creating a new discussion—Community users can create new questions, which consist of a title and body text. You may want to extend a question with custom attributes.

  • Associating a product or category to questions—Community users can associate their questions with a product or category.

  • Selecting best answers—Moderator or the question’s author can select the comment that best answered the question. Best answers are displayed near the original question so other users can easily find them. By default, the Support Home page displays only the recent community discussions that have a best answer. Child comments can also be marked as the best answer.

  • Editing questions—Original authors can edit their own questions, and moderators can edit questions from community users.

  • Deleting questions—Original authors can delete their own questions. When comments are associated with a question that is deleted, the comments are also deleted.

  • Comments/Replies—Community users can respond to the original question with their feedback. The reply, or comment, is a single field that cannot contain image or file attachments, but it can contain hyperlinks. If the question includes many replies, the question is paginated with newer comments at the end. Community users can edit or delete their own comments. Users can also subscribe to a question or comment in order to be notified when someone has posted new content to the discussion.

  • Ratings—Community users can rate replies to questions by upvoting the comments they like. They can also upvote questions to indicate that they also have a question similar to the one posed by the question’s author.

Community Public Profile Page

The Public Profile page allows users to manage their public profile.

This page also allows users to manage what information displays to the community when they post a question or comment and displays information about their recent activity in the community.

Community users can click their display name in the upper right corner of the customer portal window to view their account information, account overview, support history, and account settings.

Community Access Control

Access control defines the circumstances in which different users can perform actions.

Depending on their permissions, community users can perform a wide variety of actions on community content and users. Using access control, you can set up permissions. Although the Community Self Service feature allows countless combinations of its elements to offer you maximum flexibility in assigning permissions, it also includes basic default access control components that should meet most business needs.

For example, you might set permissions so that your community users are restricted to editing and deleting their own content, while moderators are able to edit and delete content from any user, but only for specific products.

Community Moderation

You can assign moderator privileges to your staff and trusted community users.

Moderators can interact with other users and with user-generated content by editing, moving, and removing it. They can manage users who disrupt your community. Moderation privileges are configurable so your organization can have multiple levels of moderation.

Moderators are responsible for managing inappropriate content and users, organizing content and keeping it on track, and keeping a site active. Moderators can use the moderation dashboards to identify flagged content, review, and suspend or restore it. They can suspend disruptive community members or delete their accounts entirely. They can also edit and lock discussions from within the discussion.

Search for Community Discussions

Users can search for specific discussions and filter on product (or category), age, and whether the discussion includes a best answer.

  1. On the Community page, to search by general search terms, enter search terms in the Ask a Question field.

  2. Apply filters as needed.

    • To filter by product, click Filter by Product and select a product.
    • To filter by age, click the Filter by Age and select one of the options: Last Day, Last Week, Last Month, or Last Year.
    • To filter by discussions that have a best answer, click Filter by Best Answer and select Yes.
  3. Click Search.

Ask a Question to the Community

This process outlines the steps community users take to post a question to the community.

By default, you will receive an email whenever a comment is posted to your question.
  1. Click Ask a Question.

  2. Click Ask Our Community.

  3. Enter the subject in the Subject field.

  4. Enter more information about your question in the Question field.

  5. To select a product, click Product and select the product or subproduct associated with your question.

  6. Click Post Your Question.

Overview of Attaching Files in Community Self Service

You can attachment documents, templates, and snippets to incidents, answers, and community questions and comments.

Attachments can contain malicious code (malware) or data. All incoming attachments are put through an Abuse Detection System (ADS) and scanned for malware. Questionable attachments or attachments that fail the scan are rejected.
Caution: You should always consider the possibility that attackers could evade detection.

Users can attach files to community questions and comments. Clicking on the file link on the Discussion page will force the user to download the attachment to their local system. The file URL is associated to the current user’s session. This means a user cannot forward the file URL to other users.

Users must have the appropriate read or write permissions in order to view a file attachment or to attach a file. The system generates an error page for users trying to view an attachment without the appropriate permissions. You controll these permissions using Access Control.

There is a server-controlled list of allowed file extensions. This list is applied using the widget attribute. Attachments are forced to be downloaded. You cannot choose to have them open into a browser window or tab. For additional security, if the file name contains unreliable characters, the file name is sanitized to a harmless string.

Add Comments to a Discussion

This process outlines the steps community users take to add comments to discussions.

  1. Open a discussion.

    • To add a comment to the question, enter your comment in the Add a New Comment field.
    • To reply to another comment, click Reply and enter your response in the Reply to this Comment field.
  2. Click Post Comment.

Flag and Rate Questions and Comments

This process outlines the steps community users take to flag and rate questions and comments.

From the community question or comment, select the feedback.

  • To flag a question or comment as inappropriate, click the Flag link.
  • To indicate that you have the same question as the one being asked, click the up arrow.
  • To indicate that you agree with a comment that has been made, click the up arrow to the right of the Reply and Share links.
    Note: Users cannot upvote their own question or comment.

Share Community Discussions

This process outlines the steps community users take to email a discussion or share a link to a discussion.

  1. To email a discussion:

    1. Click Email This Page.

    2. Enter an email address in the Recipient Email field.

    3. Click Send Email.

  2. To share a discussion on social media:

    1. Click Share.

    2. Select the social media site where you want to share the discussion.

  3. To share a link to a comment within a discussion:

    1. Click Share.

Edit Your Community Questions

This process outlines the steps community users take to edit their questions.

  1. Click Edit.

  2. To edit the subject, enter new text or edit existing text in the Subject field.

  3. To edit the question, enter new text or edit existing text in the Question Body field.

  4. To change the product associated with the question, click the Product drop-down menu and select a different product.

  5. Click Save.

Delete Your Community Questions

This process outlines the steps community users take to delete their questions.

  1. Click Edit.

  2. Click Delete This Question.

  3. Click Yes.

Edit Your Community Comments

This process outlines the steps community users take to edit their comments.

  1. Click Edit.

  2. To edit the comment, enter new text or edit existing text in the Edit This Comment field.

  3. Click Save.

Delete Your Community Comments

This process outlines the steps community users take to delete your comments.

  1. Click Edit.

  2. Click Delete.

  3. Click Yes.

Format Questions and Comments

You can enter questions and comments using plain text or formatted text.

  1. To mark text as bold, select the text and click B.

  2. To mark text as italic, select the text and click I.

  3. To create a bulleted list, select the paragraphs and click the bulleted list icon.

  4. To create a hyperlink, select the link text and click the link icon.

    1. Enter the URL where the link should point in the Links To field.

    2. Click OK.

  5. To view the text as plain-text markdown instead of the default rich text mode, click Advanced Mode.

Select the Best Answer to a Question

This process outlines the steps community users take to identify and select the best answer to their question.

  1. Click Mark as the Best Answer by Author.

  2. To change your selection of the best answer, select a different best answer.

  3. To remove your selection of best answer without selecting another best answer, click Unmark as Best Answer by Author.

Search Questions from a User

This process outlines the steps community users take to search for questions by a particular community user.

  1. Click the avatar or user name of a community member to go to that member’s public page.

  2. Enter a search term in the Search field.

  3. To remove the author filter on the Search Results page, click X.

Edit Community Profile

This process outlines the steps community users take to edit their profile.

  1. Click the drop-down menu on your display name in the upper right corner and select Public Profile.

  2. Click Update.

  3. To change your avatar, follow these steps.

    1. Click Change Your Profile Picture.

    2. To use the default picture (the first letter of your user name), click Apply next to default picture.

    3. To use your Gravatar profile picture, click Apply next to Gravatar.

      Note: Gravatar is a Globally Recognized Avatar, an image that appears besides your name on the community as well as other social sites where you post or comment. You can register an account at Gravatar and upload an avatar that is associated with your account.
    4. Click Save Changes.

  4. To change your user name, follow these steps.

    1. Enter the new name in the Display Name field.

    2. Click Save Changes.

Configuring Your Community

Overview of the Community Access Control

Access Control lets you define each user’s ability to interact with content on your community site.

Access Control lets you define what community users have access to in the community and is configured on the agent desktop of B2C Service. The Access Control home contains two links.
  • View Active Access Control—displays the access controls currently available on your production site.

  • View Pending Access Control Paths—displays the access control changes that have been made but not yet deployed.

Access control paths offer a top-to-bottom view of the access control elements and show the components that make up role sets.
  • roles

  • permission sets

  • permission set filters

  • the user ownership constraint

The reference implementation includes default permission sets, roles, and role sets that should meet most of your access control needs. The Community Self Service feature offers you maximum flexibility in assigning permissions by allowing countless combinations of its components.

Permissions are the most granular element of access control, and each permission allows a user the ability to perform a single activity. More than forty permissions are available to allow users to view, create, edit, move, flag, and rate questions and comments, as well as perform a variety of community moderation activities.

Permission sets are groups of permissions. The reference implementation includes six default permission sets to address basic community user needs.
  • view

  • author

  • flag

  • rate

  • moderation questions and comments

  • select best answers

Other permission sets allow users to create, edit, and moderate user profiles and delete community members.

Permission set filters and user ownership constraints restrict where on the community individual permissions and permission sets apply. The reference implementation includes one default permission set filter, the Default Nowhere Permission Set Filter, which is an empty filter that you can use to create additional filters.

Every user must have at least one role, and several default roles are included in the reference implementation. Roles combine the permissions granted in the permission sets with the product or category filters of the permission set filters.

Because one person can have multiple roles, role sets are a combination of roles. Roles sets can then be assigned to contacts in your knowledge base.

Community Role Sets

Understanding the role set defaults can help you determine what changes you want to make.

Access control elements are stored in Community (default) and Custom folders. You cannot edit or delete any of the Community access control elements or move them from the Community folder. Although you can create and move additional custom folders, subfolders, and access control elements, you cannot move any custom element or folder into a Community folder.

The Customer Portal reference implementation includes six default role sets created to address a variety of business needs. All community users automatically have three role sets assigned to their user profile: Everyone, Default Community User, and Default Contact.

When staff members add contacts to your database and when new customers create accounts on the customer portal, they automatically have these permissions. If you have existing customers that were created before you began using the community self service feature, they are prompted to create a user profile (that is, add a display name) before interacting on the community pages. The creation of a user profile then grants them the same default permissions that all community users have.

  • By default, all users have these permissions.

    • View all questions and comments as well as the flags and ratings for all.

    • View all community users.

    • Create, flag, and rate questions and comments.

    • Choose the best answer for their own questions.

    • Delete any flags or ratings they have assigned.

    • Edit their own questions and comments.

    • Delete their own questions and comments.

    • Create and edit their own user profile, including display name and avatar.

  • Three additional role sets exist.

    • Default Account

    • Community Moderator—In addition to the permissions assigned to everyone, users with the this role set can:

      • Create, flag, and rate questions and comments for other users.

      • Choose the best answer for a question.

      • Delete flags and ratings for questions and comments from other users.

      • Edit questions and comments from other users.

      • Edit status and make rating adjustments for other users’ questions and comments.

      • Delete questions and comments.

      • Lock discussions.

      • Work on the moderator interface.

      • Edit a community user’s display name, avatar, and status.

      • View contact information for a user.

    • Community User Admin—Can view the moderator interface and create and delete community users.

Add Access Control to a Navigation Set

Users need the Access Control item in their navigation set before they can configure access control.

  1. Open Navigation Sets in Configuration > Application Appearance.

  2. Right-click the navigation set you want to edit and select Open.

  3. Select Configuration in the upper right column of the editor.

  4. In the left column, expand Components > Common and select Access Control.

  5. Click Add.

  6. Click Save.

Add the Access Control Profile Permission

This procedure lets staff members create and modify access controls for your community.

  1. Double-click Profiles in Configuration > Staff Management.

  2. Right-click the profile you want to edit and select Open.

  3. Click Search.

  4. Select a navigation set containing Access Control permission.

  5. Click Permissions.

  6. Select Access Control.

  7. Click Contacts.

  8. Select Access Control.

  9. Click Save.

Set the Access Control Filter

This process changes the filter from the default of products to categories.

You cannot filter by both products and categories.
  1. Double-click Configuration Settings in Configuration > Site Configuration.

  2. Click (Select All).

  3. Enter SSS_PERMISSION_BY_PRODUCTS in the Key field and click Search.

  4. Click Value, then click the drop-down menu and select No.

  5. Click Save.

Create a Contact Workspace for Assigning Role Sets

The standard contact workspace does not include the control for assigning role sets to a contact. Therefore, you must first create a custom contact workspace with the control.

  1. Double-click Workspaces/Workflows in Configuration > Application Appearance.

  2. Click Standard.

  3. Right-click Contact and select Copy.

  4. Enter the name for the new workspace in the Name field.

  5. Click OK.

  6. Click Workspaces and Workflows.

  7. Right-click the copied workspace and select Open.

  8. Right-click the tab on the far right of the tab set and select Add Tab After.

  9. Name the New Tab.

    1. Click the tab.

    2. Click Design.

    3. Click Text.

    4. Select New Tab 1.

    5. Enter Role Sets View.

    6. Press Enter.

  10. Click Insert Control.

  11. Drag the Role Sets View control to the new tab.

  12. Click Save.

Assign Role Sets to a Contact

Staff members whose profiles include a custom contact workspace with the Role Set Views control can assign role sets to existing contacts.

  1. Double-click the name of the contact you want to edit in an open contact report.

  2. Click Role Sets View.

  3. Expand the Community and Custom folders.

  4. Select any other role sets you want to assign to the user.

  5. Click Save.

Search an Access Control Report

If the report contains many entries, it may be easier to search than to scroll through the list looking for what you want.

  1. Open the report you want to search and click Search.

  2. Select filters that match your search criteria.

  3. To search by name, enter the first few letters of the element’s name followed by an asterisk or percent sign in the Name Like field.

  4. Click Search.

Reset an Access Control Report

After you’ve search the report using specific filters, you might want to return to the original search criteria.

  1. Open the report you want to reset.

  2. Click Reset.

Refresh an Access Control Report

Sometimes after you’ve added or deleted items, you will need to refresh the report in order to reflect your changes.

  1. Open the report you want to refresh.

  2. Click Refresh.

Permissions

Permissions define which users can interact with community content and user information, what kinds of interactions are allowed, and where they have these permissions. You cannot customize an existing permission or add a new one.

Permissions are defined to allow actions on information in the database, and the default permissions are set. More than forty permissions exist to let community users view, create, edit, move, flag, and rate discussion content and user information. Additional permissions include options for moderators.

The Permissions report, opened by double-clicking Access Control on the navigation pane and clicking Permissions, displays a read-only list of all community permissions.

Note: Although the Edit button is active, you cannot edit individual permissions. And although the New button is active when Edit is selected, you cannot create permissions. Instead, the New button opens the Permission Set workspace.

When the Permissions report is open, you can search, reset the search parameters, and refresh the report using the buttons on the top left of the tab. You can sort the report on each of the column headings.

The Permission Data Conditions column lists the possible constraints for each permission. For example, the User Owned constraint on the Edit Community User Avatar means that you can constrain the permission so that community users with that permission can change only their own avatar.

The # Permission Sets link lets you drill down to view which permission sets include the selected permission. Drilling down on the Edit Community User Avatar shows the two permission sets that use the permission.

The Access Control Path link lets you drill down to view all the paths of Role Set > Role > Permission Set > Permission Set Filters > Constraints that use that specific permission.

Overview of Community Permission Sets

The forty-four community permissions can be grouped into any combination of permission sets.

Six default permission sets are included in the reference implementation to address basic community user needs.

  • Default Community User—Users can create and edit their own community user profile, including display name and avatar.

  • Default Community Viewer—Users have read-only access to community users, questions, comments, ratings, and flags.

  • Default Community Author—Users can create, flag, and rate questions and comments. Users also have permission to change the content they have authored. They can edit and delete questions and comments, delete ratings and flags for questions and comments, and select a best answer.

  • Default Community Moderator—Moderators can choose a best answer, view the moderator-only elements of the user interface, lock questions, and move comments. They can also delete questions and comments, flags, and ratings, as well as edit questions and comments, rating adjustments, and status, and the question interface.

  • Default Community Moderator – Users—Moderators can edit a community user’s display name, avatar, and status, view the moderator-only elements of the user interface, and view contact details for a community user.

  • Default Community Admin – Users—Moderators can create and delete community users and view the moderator-only elements of the user interface.

When you click Permission Sets in the ribbon of the Access Control window, the permissions sets report displays in the default View Active mode.

When you click the Edit button in the ribbon, the permission sets report displays these columns.

  • Created Time

  • Created By

  • Deployment Action

You can view the permissions included in the permission set by clicking the #Permissions Assigned link to display the permissions. The Default Community User permission set, for example, contains four permissions. Notice that the drill-down report title includes the Permission Set ID value (1 in this example) instead of the Permission Set name.

Create a Permission Set

In addition to the six default permission sets included in the reference implementation, you can create custom permission sets to more precisely define the exact permissions you want to grant to your community users and moderators.

  1. Double-click Access Control.

  2. Click Permissions Sets.

  3. Click Edit.

  4. Click New.

  5. Select Permission Set.

  6. Enter the permission set name in the Name field using only letters, numbers, and underscores.

  7. Enter a unique descriptive name for the permission set in the Labels field.

  8. To describe the permission set, enter information in the Descriptions field.

  9. To store the permission set in an existing subfolder rather than in the default Custom folder, click Search in the Folder field.

    1. Select the folder name.

    2. Click OK.

  10. To create a new subfolder for storing the permission set, click Search in the Folder field.

    1. Right-click Custom and select New Folder.

    2. Enter the folder name and press Enter.

    3. Select the new folder.

    4. Click OK.

  11. Click the arrow next to the Community check box to expand the list of permissions.

  12. Select the individual permissions you want the new permission set to include.

  13. Click Save.

Deploy Access Control Changes

Copy a Permission Set

It’s possible that a default or custom permission set is almost identical to the one you want to create. You can copy the existing permission set so you can edit it and make your changes.

  1. Click Edit.

  2. Click Permission Sets.

  3. Right-click the permission set you want and select Copy > Permission Set.

  4. To change the default name of the copied permission set, enter the new name in the Name field.

  5. Enter a new name for the permission set in the Labels field.

  6. Click Save.

Edit a Permission Set

You can edit any permission set in the Custom folder or its subfolders, but you cannot edit the default Community permission sets.

  1. Click Edit.

  2. Click Permission Sets.

  3. Right-click the permission set you want to edit and select Open > Permission Set.

  4. To edit the name, enter a new name in the Name field.

  5. To edit the label, enter a new label in the Labels field.

  6. Expand the Community permissions in the left column.

  7. To add a permission, select its check box.

    1. To add a constraint to the selected permission, select the Constrain By check box.

    2. To remove a constraint from a permission, clear the Constrain By check box.

  8. To remove a permission, clear its check box.

  9. Click Save.

Delete a Permission Set

You can delete any permission set in the Custom folder or its subfolders, but you cannot delete the default Community permission sets. Nor can you delete a permission set that is used in a role.

  1. Click Edit.

  2. Click Permission Sets.

  3. Right-click the permission set you want to delete and select Delete > Permission Set.

  4. Click Yes.

View Where Permissions are Used

This process lets you determine where a permission set is in use.

  1. Click Used In.

  2. Click links to view:

    • the number of permission sets in each role
    • the assigned permission set filters
    • the number of role sets using the permission set
    • the access control path

Create a Permission Set Filter

Permission set filters are used for permissions that have a product or category restraint.

  1. Double-click Access Control.

  2. Click Permissions Set Filters.

  3. Click Edit.

  4. Click New.

  5. Select Permission Set Filter.

  6. Enter the permission set filter name in the Name field using only letters, numbers, and underscores.

  7. Enter a descriptive name for the permission set filter in the Labels field. You can use spaces and special characters, but each custom permission set filter must have a unique label.

  8. To describe the permission set filter, enter information in the Descriptions field.

  9. Select one or more products (or categories) in the left column.

  10. Click Save.

Copy a Permission Set Filter

You can copy the default permission set filter or a custom filter to create a new filter.

  1. Click Edit.

  2. Click Permission Set Filters.

  3. Right-click the filter you want and select Copy > Permission Set Filter.

  4. To change the default name of the copied permission set filter, enter the new name in the Name field.

  5. Enter a new name for the permission set filter in the Labels field.

  6. Click Save.

Delete a Permission Set Filter

You can delete any permission set filter that is not being used in a role, but you cannot delete the default Nowhere Permission Set filter.

  1. Click Edit.

  2. Click Permission Set Filters.

  3. Right-click the filter you want to delete and select Delete > Permission Set Filter.

  4. Click Yes.

User-Owned Constraints

Individual permissions and permission sets apply everywhere on the community unless they are constrained. Some permissions have the ability to be constrained by user ownership.

User-owned constraints apply when a permission applies only to the owner of a profile or content. Without a user-owned constraint, for example, any user with the Edit Comment permission could edit any other user’s comments. You want to let users edit their own comments, but it’s unlikely you want them editing the comments of other users. For that reason, the Edit Comment permission is constrained by user ownership by default. However, you may want to let moderators edit comments, so you would clear the Constrain by User Owned check box in a moderator permission set.

Product and Category Constraints

Individual permissions and permission sets apply everywhere on the community unless they are constrained. Some permissions have the ability to be constrained by product/category.

You can also constrain permissions by either product or category. Whichever constraint you select—product or category—applies for all permissions across your site. In other words, you cannot constrain some permission sets by product and others by category. By default, products are used, but you can change the constraint to categories.

Least Restrictive Path Permissioning

A role set with multiple permission sets will use the least restrictive permission set.

When multiple permission sets are used in a role set and a permission in one set is unconstrained while the same permission in another permission set used in that role set is constrained, the user with that role set will have the unconstrained permission. Assume, for example, a role set that contains two roles. Each of the roles has very similar permission sets, except that one permission set lets the user edit only the user-owned questions and comments, while the other set does not have the user ownership constraint. Users who are assigned to that role set will be able to edit all questions and comments, regardless of who the owner is. The least restrictive permission path takes precedence.

The least restrictive path also applies to permission set filters. Permissioning can get complicated with the combination of permission sets, permission set filters, and user ownership constraints. Every access control report contains a link to let you view the complete access control path from individual permissions to the role set. Clicking Access Control Paths in the Access Control editor’s ribbon lets you view every path.

Overview of Community Roles

Roles combine the permissions granted in the permission sets with the product or category filters of the permission set filters.

Every user has at least one role, and several default roles are included in the reference implementation. When you click Roles in access control, the roles report displays.

You can drill down on these values in the report.

  • The number of permission sets assigned to the role
  • The number of permission set filters assigned to the role
  • The number of role sets that include the role

You can also click the View link to see the access control path from individual permissions to role sets.

Seven default roles are included in the reference implementation.

  • Everyone—This role uses the Default Community Viewer permission set that gives users read-only access to community content.
  • Default Contact—This role uses these permission sets.
    • Default Community User—Lets users create and edit their community profile.
    • Default Community Author—Lets users create, flag, and rate questions and comments as well as manage their own content (edit, delete, and select best answer).
  • Default Account—Same as Default Contact.
  • Default Community User—Same as Default Contact and Default Account.
  • Community User Moderator—This role uses the Default Community Moderator Users permission set that lets moderators edit community user profiles and view contact details.
  • Community User Administrator—This roles uses the Default Community Admin Users permission set that lets moderators create and delete community users.
  • Community Content Moderator—This role uses these permission sets.
    • Default Community Moderator—Lets moderators choose a best answers, lock questions, move comments, and edit and delete questions, comments, flags, and ratings.
    • Default Community Author—Lets users create, flag, and rate questions and comments as well as manage their own content (edit, delete, and select best answer).

Edit a Role

You can edit roles to change the associations with permission sets and permission set filters.

  1. Click Edit.

  2. Click Roles.

  3. Right-click the role you want to edit and select Open > Role.

  4. To add a permission set, click Add and select the permission set from the drop-down menu in the Permission Set column.

  5. To change a permission set, click the associated Permission Set drop-down menu and select a different permission set for the role.

  6. To define a permission set filter, follow these steps:

    1. Clear the Unconstrained check box.

    2. Click Permission Set Filter.

    3. Expand the Community or Custom folder.

    4. Select the permission set filter.

  7. Click Save.

Create a Role

In addition to editing default and custom roles, you can also create new roles.

  1. Click Edit.

  2. Click Roles.

  3. Click New and select Role.

  4. Enter the role name in the Name field using only letters, numbers, and underscores.

  5. Enter a descriptive name for the role in the Labels field.

    You can use spaces and special characters, but each custom role must have a unique label.
  6. To describe the role, enter information in the Descriptions field.

  7. To add permission sets and permission set filters, complete these steps for each set:

    1. Click Add and select a permission set from the drop-down menu in the Permission Set column.

    2. To define a permission set filter, follow these steps:

      1. Clear the Unconstrained check box.
      2. Click Permission Set Filter.
      3. Expand the Community or Custom folder.
      4. Select the permission set filter.
  8. Click Save.

Delete a Role

You can delete any role in the Custom folder or its subfolders, but you cannot delete the default Community roles. Nor can you delete a role that is used in a role set.

  1. Click Edit.

  2. Click Roles.

  3. Right-click the role you want to delete and select Delete > Role.

  4. Click Yes.

Create a Role Set

Although you cannot edit or delete the default role sets, you can create custom role sets to address your specific business needs.

  1. Double-click Access Control.

  2. Click Role Sets.

  3. Click Edit.

  4. Click New and select Role Set.

  5. Enter the role set name in the Name field using only letters, numbers, and underscores.

  6. Enter a descriptive name for the role set in the Labels field. You can use spaces and special characters, but each custom role set must have a unique label.

  7. To describe the role set, enter information in the Descriptions field.

  8. Click the arrows next to the Community and Custom check boxes on the Roles tab to expand the list of roles.

  9. Select the roles you want the new role set to include.

  10. Click Save.

Copy a Role Set

You can copy a default or custom role set to create a new role set.

  1. Click Edit.

  2. Click Role Sets.

  3. Right-click the role set you want and select Copy > Role Set.

  4. To change the default name of the copied role set, enter the new name in the Name field.

  5. Enter a new name for the role set in the Labels field.

  6. Click Save.

Edit a Role Set

You can edit existing custom role sets.

  1. Click Edit.

  2. Click Role Sets.

  3. Right-click the custom role set you want and select Open > Role Set.

  4. To change the name of the role set, enter the new name in the Name field.

  5. To change the label of the role set, enter the new label in the Labels field.

  6. To select additional roles to include in the role set, select the check box for the role you want to add.

  7. To remove roles from the role set, clear the check box for the role you want to remove.

  8. Click Save.

Add Role Set Callout to Community Questions

You can configure role set callouts on community questions and comments to highlight community activity. Attribute settings must include the role set ID, a pipe separator, and the text of the callout.

  1. Open /views/pages/social/questions/detail.php.

  2. Locate <rn:widget path="discussion/QuestionDetail" sub:prodcat:verify_permissions=”Create” />.

  3. Edit the widget code to add the author_roleset_callout attribute and modify the label. <rn:widget path="discussion/QuestionDetail" sub:prodcat:verify_permissions=”Create” author_roleset_callout="5|Posted by Advanced Moderator" />

  4. Save the file.

Delete a Role Set

You can delete any role set in the Custom folder or its subfolders, but you cannot delete the default role sets.

  1. Click Edit.

  2. Click Role Sets.

  3. Right-click the role set you want to delete and select Delete > Role Set.

  4. Click Yes.

View Users on the Access Control Editor

You can view a list of all active users on the Access Control editor, or you can search for users by role sets. When Users are selected on the ribbon, the Edit button is disabled. When the Edit button is selected, the Users button is disabled.

  1. Double-click Access Control.

  2. Click Users.

  3. To display only the users who have specific role sets, expand the Community and Custom lists and select the role sets.

  4. To display all users, select (Select All) in the Role Sets menu.

  5. To view a user’s permissions, click view in the Effective Permissions column.

  6. To view a user’s access control paths, click the View link.

View Pending Access Control Changes

The changes you’ve been making to access control elements are still pending until you deploy them, which pushes them to your production site. Review your changes before deploying them.

  1. Double-click Access Control.

  2. Click View Pending.

  3. Click OK.

Roll Back Pending Access Control Changes

Rolling back is the process of deleting the pending changes. Rolling back does not revert your production site to the previously deployed version.

  1. Double-click Access Control.

  2. Click Rollback.

  3. Click Yes.

  4. Click OK.

Deploy Access Control Changes

Before you deploy changes, be certain that you want to implement the access control changes. After you deploy, you cannot revert to the previously deployed version. The Rollback operation merely deletes the pending changes.

  1. Double-click Access Control.

  2. Click Deploy.

  3. Click Yes.

  4. Click OK.

Modify Social Filters to Use Categories

When setting up permissions for your community, you can define filters that are designed to work with either products or categories. The default selection is product.

Review the widget documentation to ensure you’re modifying the appropriate attributes.
  1. Open /views/pages/social/ask.php.

  2. Locate any lines of code referencing uicontrol.

    <rn:widget path="input/ProductCategoryInput" name="SocialQuestion.Product" verify_permissions="Create" />
  3. Modify the widget code.

    <rn:widget path="input/ProductCategoryInput" name="SocialQuestion.Category" verify_permissions="Create" />
  4. Repeat the above steps on these pages.

    1. account/notif/list.php

    2. social/questions/detail.php

    3. products/lists.php

    4. moderate/comment.php

    5. moderate/question.php

Modify the Community Question Rating Type to Stars

The available rating types include upvote, star, and updown.

  1. Open /views/pages/social/questions/detail.php.

  2. Locate <rn:widget path="discussion/QuestionDetail" sub:prodcat:verify_permissions=”Create” />.

  3. Edit the widget code to add the rating_type attribute and modify the label.

    <rn:widget path="discussion/QuestionDetail" sub:prodcat:verify_permissions=”Create” sub:rating:rating_type=”star”label_be_first_to_vote=”Rate this question” /> 
  4. Save the file.

Modify the Community Comment Rating Count to Graphical

The default rating count on community questions and comments is numerical. The available rating count types include numerical and graphical.

  1. Open /views/pages/social/questions/detail.php.

  2. Locate <rn:widget path="discussion/QuestionComments"/>.

  3. Edit the widget code to add the rating_count_format attribute and modify the label.

    <rn:widget path="discussion/QuestionComments" sub:rating:rating_type="star" label_be_first_to_vote="Rate this question" sub:commentRating:rating_count_format="graphical"/> 
  4. Save the file.

Remove the Best Answer Voting Option

User, moderators, and administrators can select which answer best addresses the posted question. This option is enabled by default.

  1. Open /views/pages/social/questions/detail.php.

  2. Locate the following line of code.

    <rn:widget path="discussion/QuestionComments"/>
  3. Edit the widget code to add the best_answer_types attribute.

    <rn:widget path="discussion/QuestionComments" best_answer_types="none"/> 
  4. Save the file.

Overview of the Customer Portal Avatar Library

You can add images to your avatar library for your users to choose from.

Community users can update their public profile to use an avatar image. By default, the user’s avatar is a square with the initial letter of their user name.

As a community administrator, you can customize the avatar library. You may want to add branded images to personalize your customer’s experience or promote a product release.

Source files for the avatar library are stored in two folders located in assets/images/avatar_library/.
  • display/everyone/—images that display next to the user’s name in posts and on the Profile page

  • gallery/everyone/—images (limited to 160 x 160 pixels) that appear on the Gallery page

You can set these attributes for the avatar library.
  • file size: default=150k; max=250k

  • file type: default=png; other options=gif, jpg, jpeg

  • total avatars: default=100; max=500

Create Role Set Avatar Library for Moderators

You can customize the avatar choices available by groups, based on role sets.

  1. Identify the Role Set ID.

    1. Click Access Control.

    2. Click Role Sets.

    3. Identify the Role Set ID for Community Moderator Role Set.

  2. Create a folder for the moderator role set avatar library.

    1. Open the file location: assets/images/avatar_library/.

    2. Create a new folder named moderators in the display and gallery folders.

    3. Upload images to both moderators folders.

  3. Open views/pages/account/profile_picture.php.

  4. Locate this code.

    <div class="rn_PageContent rn_Profile rn_Container">
    <rn:widget path="input/SocialUserAvatar" avatar_library_folder_roleset_map="1|everyone|All Users" />
    </div>
  5. After All Users, enter code for the additional folder views in this format: roleset ID|folder|label.

    <rn:widget path="input/SocialUserAvatar" avatar_library_folder_roleset_map="1|everyone|All Users;5|moderators|Moderators" />

Support Use of Facebook Profile Picture

If you’ve enabled Facebook login support, you can allow Facebook users to use their Facebook profile picture in Customer Portal.

  1. Make sure the following widgets are activated: SocialUserAvatar (v.1.2) and OpenLogin (v.1.5).

  2. Open views/pages/account/profile_picture.php.

  3. Add Facebook to the avatar_selection_options attribute.

    Your code should resemble the following.
    <rn:widget path="input/SocialUserAvatar" avatar_selection_options="default,avatar_library,gravatar,facebook" />

Moderating Community Self Service

Moderators and Community Self Service

Community Self Service tools help moderators identify content that needs their attention and lets them take appropriate action.

Your Community Self Service community will no doubt be a busy place, and you’ll want to be sure it remains useful, well organized, and respectful for your community users. When you assign moderators—either from your organization’s staff or from within your user community or both—you give them permission to interact with user-generated content and with community users.

A moderator’s role primarily includes managing content and users. Your moderators can edit, remove, and delete discussion content. For example, they may mark a comment as the best answer to the question, suspend a comment so it is visible only to moderators, lock a question, change the product associated with the question, or pin a question to the top of the list of discussions. They can also suspend, delete, and restore users as needed.

You can configure different types of moderators with different permissions and roles. For example, you might want to allow trusted members of your community to moderate content but restrict the moderation of users to staff members. The Access Control component contains several default permission sets and roles that should meet your needs. And, if you need more flexibility, you can create your own moderator role set using any combination of the available permissions and filters.

Moderator Accounts

A moderator has the ability to edit, move, suspend, delete, and restore community users and their content.

A moderator’s ability to moderate your community depends ultimately on how you define the moderator’s access controls. You can create a variety of moderator role sets with whatever combination of permissions you choose.

Users with the Community Moderator role set have all the permissions assigned to general community users—creating and editing a user account, adding, editing, and deleting their own discussion content, and viewing, flagging, and rating all community content. Moderators with this role set can also:

  • Work on the moderator interface.

  • Create, edit, and delete questions, comments, flags, and ratings of other users.

  • Change the product associated with the question.

  • Edit community users’ display name, avatar, and status and view users’ contact data.

  • Choose the best answer for a question.

  • Edit status and make rating adjustments for other users’ questions and comments.

  • Lock discussions.

Users with the Community User Admin role set can view the moderator interface and create and delete community users.

Some of the questions you might consider as you go about defining moderator roles for your community include:

  • Do you want moderators to be able to suspend, restore, and delete users?

  • Do you want to let them edit or delete another user’s content?

  • Will you restrict them by product or category?

  • Do you want moderators who can suspend content to be able to approve it, or do you want a different group of moderators to approve it?

The Moderation Overview Page

The moderation dashboards provides moderators an overview of all community activity and lets them perform multiple actions.

For the best experience, moderation dashboard users should use Chrome, Firefox, or Internet Explorer 10 and above. If your moderate role set does not include permissions for moderating users, you will not see the Moderate Users tab or information about users on the Moderation Overview page.

The logged-in moderator selects Moderation from the drop-down menu that appears when the display name is clicked. This link and menu is generated by the AccountDropdown widget on the standard template.

The Moderation Overview page opens to provide a snapshot of question, comment, and user activity for the past 90 days. The table, generated by the ModerationSummaryTable widget, breaks the totals down into suspended, active, and archived statuses. Moderators can drill into any of the values to see a list of selected items having the particular status. Drilling down on these values opens the same moderation dashboards that are accessed through the Moderate Comments, Moderate Questions, and Moderate Users tabs in the header.

Announcements are displayed at the top of the page and are rendered with the AnnouncementText widget.

The bottom of the Moderation Overview page contains a graph of new questions and comments for each of the last seven days and a similar graph of new users for the last seven days. Both graphs are rendered by the ActivityCharts widget.

Content Moderation

Moderators can take a variety of actions on questions and comments in your community.

Moderators can take these actions on discussion content submitted by community users, if you have given them sufficient permissions.

  • Editing content—Changing the subject and body of a question and the body of a comment (comments do not have subjects) and changing the product associated with the question.

  • Suspending content—Making content not visible to non-moderator community users but visible to community moderators.

  • Approving/restoring content—Making content visible to the community again after it has been suspended by a moderator (approving) or set to pending by the system (restoring).

  • Deleting content—Removing content from a discussion so the content remains in the database but has its status set to Deleted (soft delete) or deleting content from the database (hard delete).

  • Locking discussions—Preventing additional comments from being made and flags or ratings from being set.

  • Moving questions—Associating a question with a different product (or category) by editing the question and selecting a new product.

  • Resetting flags—Setting the flag count back to zero.

User Moderation

Moderators have access to your customer’s community profiles.

Moderators can take these actions on community users, if you have given them sufficient permissions. These actions affect only the customer’s community profile, not their contact record in your database.

  • Suspending users—Preventing a user from logging in, creating content, and receiving subscription emails. This user’s active content remains visible. You would expect this user to be restored.

  • Archiving users—Same as suspending, except you would not expect to restore these users, for example, staff members who have left your organization.

  • Restoring users—Changing the user’s status back to active.

  • Deleting users—Removing a user without the possibility of restoring the account.

  • Viewing user information—Viewing information from the user’s contact record.

  • Changing avatar and display name—Replacing the user’s picture and changing the display name used by the account.

The Comment Moderation Dashboard

The ModerationAction widget lets users with the role set perform a combination of actions from the Comment Moderation dashboard.

None of the moderation action buttons are active until at least one comment is selected. If you do not have permission to perform an action, the associated moderation action button is disabled. No comments from deleted questions appear in the Comment Moderation dashboard.

  • Suspend—When you suspend a comment by setting its status to Suspended, only users with permission to view the moderator user interface can view the comment.

  • Approve/restore—You can approve a suspended comment to change its status from Suspended to Active, where every user can see it. When comments are approved, the flag count is automatically reset to zero.

  • Delete—You can delete a comment to make it invisible to all users, including moderators.

  • Reset flags—When you reset a comment’s flags, the flag count is set to zero.

  • Suspend author—You can suspend the author of a comments.

  • Approve/restore author—You can approve one or more suspended authors or restore pending authors.

Filter Community Comments

The Comment Moderation dashboard lets you filter your results.

  1. Click Select Filters.

  2. To filter comments by date, select one of the options in the Updated Date column.

    • If you want to specify a custom date range, select the last option in the list.
    • Enter dates in the From and To fields or use the calendar to select the dates.
  3. To filter comments by status, select Active or Suspended or both in the Status column.

  4. To filter comments by products, click Select a Product and select a product or subproduct.

  5. Click Apply to display filtered results.

  6. To remove one of the filters you selected, click the X next to the filter name.

  7. To sort by the number of flags each comment has, click the up or down arrow next to the red flag symbol in the header row.

  8. To sort by the date the comment was most recently updated on, click the up or down arrow next to the Updated On column header.

Suspend Community Comments

Only users with moderation permissions can see suspended comments.

  1. Do one of the following:

    • Select one or more comments you want to suspend by selecting the check box to the left of each comment.
    • Select all comments on the page by selecting the check box in the heading row.