The following document will assist with best practices for developing one or more service request portals. This document is written to assist and technical developer putting together a portal who has had training using Kinetic Request.
You can also use a bundle as a starting place for building a portal. Some bundles (eg. Air) even have an example portal available for download. Bundles are web-based add ons to Kinetic Request which allow you to quickly create a web interface to your request catalog. Bundles include all of the files that you need to get started and come in different themes for styling and branding. A typical bundle includes a category listing page which allows the user to browse through the catalog, a display page for your service items, a submissions page which lists all the submitted, closed and pending requests for the user and a submission details page which shows all of the details and tasks for each request.
As discussed in other documents, a portal is a page or pages that a user accesses to view links to available service items (forms). This page can be styled to appear similar to other pages in a corporate intranet or other corporate branding. The service items are typically categorized and will only show those items that the user has access to.
The Portal JSP page
Create Your Own JSP
For most situations, it is best to create a copy of this file so that it can be customized to your own needs, without affecting the sample. Call this something similar to myITPortal.jsp and keep it in the root of the /kinetic/ directory so the references to other files are still intact. Then, on the “Advanced” tab of the Kinetic Request – Service Catalog Console, change the DisplayPage (JSP) value from the default JSP to the name of your copied JSP. Now, when the page is rendered, it will use your JSP instead of the default.
Customize the JSP
From here, you will want to customize the JSP further with your own HTML. While the sample Sithco launcher includes the header image and left column defined in the form using Kinetic Request, most production implementations would have this code included in the JSP itself.
Be sure to reference the branding standards defined in the Delivery Model – Branding document. Often HTML can be cut directory from the pages referenced in that document and placed in your JSP.
You will likely want your pages to have a consistent look/feel with your entire service portfolio including the portal and forms themselves. Each page will have similar header images, fonts, borders and other style elements. As a best practice define these consistent styles in a CSS. This file can be manually deployed in your web server(s) when you deploy your custom JSP and a reference to this file in your JSP, or you can attach the file on the “Advanced” tab where you set your JSP page. Attaching a stylesheet this way will automatically create a reference in the HTML when the page is rendered.
You may also have a corporate stylesheet already defined for your site(s). Instead of creating a new one (or in addition to), you could add this reference into the <head> of the JSP.
When your forms are created, they can also reference any of the stylesheets mentioned here, using a customized JSP for your forms, or by adding “Custom Header Content” on the “Advanced” tab of the console. This is discussed further in the Delivery Model – Creating Forms document.
On your portal (and associated forms) you can route AJAX requests to a particular JSP component or “partial” and then define what HTML element to update when this request returns. The category boxes are handled this way as is the “My Service Items” table. Partials are typically HTML snippets but could also be XML or plain text.
The process enacted to utilize a partial is:
1. A SimpleDataRequest (SDR)call is made from the browser to the web server (on display or another event). This call includes the instanceId of the SDR is included in the call. The SDR is configured in Remedy to perform a specific query and take in parameters for that query.
2. The web server validates the request then includes the parameters in the query and retrieves the appropriate Remedy records.
3. The web server looks for a parameter on the URL to determine whether to output the contents of the query via a partial. If so, the request is forwarded to the JSP for eventual output back to the browser. If no parameter is found, a simple XML document with the record information is returned.
Partials are found in the /kinetic/resources/partials directory on your web server(s).
When customizing an existing partial, it is best to copy it rather than customizing the out of the box partial.
Segmenting Your Portfolio
You will want to think long-term about your entire service portfolio and what forms will likely be there a year or more from now. When figuring out what forms to include, think about these items:
Do you want different people/groups to manage different service portfolios? For example: IT and HR. They likely don’t want their service portfolios combined and those people creating HR service item forms shouldn’t be able to change IT ones. Keep these types of forms separate in different catalogs within Kinetic Request.
Can different people view different forms but with significant overlap? For example: You have vendors that view some service item forms and employees can view those as well as others. In this situation it is probably best to have all the forms in one catalog, but have two separate portals. The additional benefit of this is you can include vendor-specific text/information on your vendor portal and employee information on the other giving each a better customer experience.
Do you have shared forms like “Login Help Form” or “Generic Question” form? A best practice in this situation is to create a “Shared” catalog where shared forms will be stored. The catalog won’t have a portal, but rather these forms will be included in other areas such as the portal login page or a link on confirmation pages.
Are you authenticating solely against Remedy? Create a “Login” page using the same JSP created for your portal. Login pages are also considered “Launchers” and are typically found either in the Shared catalog mentioned earlier or in their own catalog if they use a different look. The easiest way to create a login page is to clone the Sithco sample login or just add the login HTML from that page into your own.
You've got the requirements for the branding, the templates, and service items. The next step is to go build finish building it all out: Kinetic Request User Guide.