What are guidelines for customer portal customization on Knowledge Advanced sites?
Oracle B2C Service Knowledge Advanced
The business needs to customize the end user pages to suit their needs.
These are considerations when implementing customer portal page custom code
- Caching for performance: There are many places that caching can be used to improve performance and this can help reduce the overhead for subsequent page loads. Caching techniques to choose from include:
- Session Cache
This is a type of cache where the session is maintained by the browser through cookies (max limit of 4kb) and The data is cleared from cache on terminating the browser session or user logs-out from CP. The data is stored in the cp_session cookie and the site-wide config called CP_COOKIES_ENABLED to be enabled.
- Framework/Request Cache
This kind of cache also uses server memory but is used in request scope, i.e. it ceases to exist in the server once the request is served.
- Session Cache
- Custom Widgets
Customer Portal provides OOTB widgets that can be extended to create your own custom widgets. As a norm, it is essential to note the below points while creating custom widgets.
- Copy only necessary files required for customization
- While using custom files, ensure extra calls/invocation are necessary for the functionality
- If OOTB widgets are used to extend to a custom widget, bug fixes will be automatically propagated to the custom widget
- OKCS REST APIs
- OKCS model
You can invoke both the Knowledge Advanced content (IM) and search REST APIs directly from Customer Portal from 20B (20.5) release. There is a public function exposed in OKCS model class to invoke any KA REST API, called makeApiRequest function. You can write custom code to instantiate the model class, and then call the makeApiRequest function to invoke a content (IM) or a search API. You can include the custom code within a custom widget or custom model. You can find the complete list of Knowledge Advanced content (IM) and search resource URLs in the Tasks section of REST API for Oracle Service Cloud Knowledge Advanced, available at Oracle Help Center > Cloud Applications > B2C Service > REST API > Knowledge.
The makeApiRequest method has three parameters.
- $url − The API end-point URL of a REST API. Use \RightNow\Utils\Config::getConfig(OKCS_IM_API_URL) . '<resource_URL>' to invoke a content (IM) API and \RightNow\Utils\Config::getConfig(OKCS_SRCH_API_URL) . '<resource_URL>' to invoke a search API.
- $methodName − Method name is the type of method, including GET or POST.
- $postData − Post data is an array of variable names and values sent <in the body of the request message> by the POST method.
- Batch requests
Using batch REST API, we can batch multiple API requests in one call. It is a POST request with the one or more individual API's in the payload. Response of this call will contain the batch response of each individual API's sent in payload. Please refer the API documentation for more details.
- OKCS model
- Data loading
- Lazy loading
In order to improve page performance, the data fetched from the API can be loaded lazily on the page. It involves invocation of the initial (on page load) API call to fetch data for the first set of items to be displayed on the page. If there are more number of items, then they can be fetched in paginated manner as mentioned below.
- ‘More/Next' link - On the click of this link, next set of items are fetched from API and are displayed on the page. This is implemented in the OOTB OkcsProductCategorySearchFilter widget.
- Lazy scroll – Identify page scroll event on the page, and fetch the next set of items from API when user has reached the end of the page . This is implemented in the OOTB OkcsAnswerNotification widget.
All the KA REST API's, which return the list of items, have exposed the pagination option to fetch limited number of items on each call. Please refer KA REST API documentation for the example of particular API.
- Lazy loading
- Different Keys with the REST API
The developer has to decide what all data is expected out of the API call and use the 'mode' parameter in the API call appropriately. KA REST API's support four values for the parameter, to return minimum or full data: KEY, DATA, EXTENDED, and FULL. The information returned by any mode is super set information of previous level. For example, the DATA response object contains all the information of the KEY response object and some additional information. Below are the details of the way the parameter behaves for the content API used to fetch the information of an article
- When the KEY mode is used, the API returns a limited amount of article information, e.g. For the content API - title, document id, and date modified etc..
- When the DATA mode is used, the API returns much more information about the article, but not the contents of the article. This is the default value for any API if the mode is not specified explicitly.
- When the EXTENDED mode is used, the API returns all the information about the content, except for security and visibility filtering fields attributes such as categories, userGroups and views. The EXTENDED mode can be used to display an article to an end-customer, agent or author.
- When the FULL mode is used, the API returns all the information about the article. The FULL mode can be used so that a user or a program can update the article.
- Sample request URL - /content?mode=KEY (or) /content?mode=FULL etc.