Advanced Modifications

This article contains the following topics:
casm1401
This article contains the following topics:
You must be aware of various aspects of modifying web pages if you elect to use tools other than Web Screen Painter to modify HTMPL, or if you have unusually complex customization requirements. However, we strongly recommend that you work with WSP to modify CA SDM web pages before trying any other approach. WSP is capable of doing almost any modification you need, and it automatically handles housekeeping issues, such as placing updates in the site mods directory, and distributing published files to all servers.
The Web Engine and Its CacheIf you decide to create version any
When modifying web pages, it is helpful to understand the structure of the CA SDM web server. The web interface uses either a J2EE servlet container, such as Tomcat, or a standard HTTP server, such as Apache or Microsoft Internet Information Server (IIS). When a user requests a CA SDM web page, the HTTP server invokes the supplied program pdmweb.exe.
After it starts, pdmweb.exe sets up a connection with a CA SDM daemon (or Windows service) called the web engine. The web engine interprets the user's request. Most requests require the web engine to look up a template (HTMPL) file and translate it into standard HTML. Usually, the translation process requires the web engine to communicate with a CA SDM server to read or update the database, and include database information in the generated HTML. After the HTML is complete, the web engine sends it to pdmweb.exe, which in turn sends it back to the user's browser.
To maximize performance, the web engine typically reads each HTMPL file only once. After parsing the file and determining how to translate it to HTML, the web engine stores the parsed file in its cache, significantly reducing the processing time the next time the file is requested. While the cache is beneficial in a production environment, it can be inconvenient in development, as it means that changes to HTMPL files do not take effect until either the web engine is recycled or the pdm_webcache utility is used. In a development environment, you can avoid this behavior by specifying the configuration file property SuppressHtmplCache. However, we recommend that you do not suppress the HTMPL cache in a production environment because it severely impacts overall performance of the web engine.
The web pages served up by pdmweb.exe are generated by reading HTMPL files and using them to generate HTML. HTML template files are identified by a file suffix of .htmpl. You can modify these template files, and thereby modify the CA SDM web pages.
The pdm_webcache Utility
Use the pdm_webcache utility to remove one or more HTMPL forms from the web engine cache. This forces the web engine to fetch these forms from the disk the next time they are used, allowing changes to forms to take effect.
pdm_webcache [-f form-name] [-g form-group] [-i interface] [-p process] [-v]
  • -f
    form-name
    Specifies the name of the form to be removed from the cache, such as detail_cr.htmpl. You can use '%' (or '*') as a wildcard character to select more than one form. For example, the specification:
    -f detail%
    selects all detail forms.
    This argument is optional. If it is omitted, all forms in the cache are selected.
  • -g
    form-group
    Specifies the name of the form group to be removed from the cache, such as Analyst. You can use '%' (or '*') as a wildcard character to select more than one form group
    .
    For example, the specification:
    -g Anal%
    selects all form groups beginning with "Anal”.
    This argument is optional. If it is omitted, all form groups in the cache are selected.
  • -i
    interface
    Specifies the name of the web interface to be removed from the cache, such as analyst, customer, or employee. You can use '%' (or '*') as a wildcard character. For example, the specification:
    -i a%
    selects the analyst interface.
    This argument is optional. If it is omitted, all interfaces in the cache are selected.
  • -p
    process
    Specifies the name of the web engine process whose cache is to be modified, such as web:local.
    This argument is optional. If it is omitted, all web engines are selected.
  • -v
    Specifies verbose output. When this argument is specified, pdm_webcache lists the full name of every form removed from the cache, in the form:
    interface
    :
    form-group
    :
    form-name
    This argument is optional. If it is omitted, pdm_webcache reports only a count of forms removed from each web engine's the cache.
How to Modify HTML Templates
Typically, you can make two types of changes to the HTML templates:
  • You can make modifications that will be visible to the user but will not be altered by the web interface prior to display. For example, you could add a GIF file for your company logo to the web interface pages (a “pass through”) by adding the reference to the appropriate template file or you could add JavaScript to your page to validate input. Any changes you make to the HTMPL file that are not contained within a PDM tag, as defined in the following, are passed unchanged in the HTML returned to the user.
  • You can modify the replaceable sections of the templates. For example, you can add new application data to the request detail page.
Several kinds of template entries let you do the following:
  • Display information from CA SDM to the user.
  • Set up a query page.
  • Create links to other CA SDM pages using link tags.
Files That Should Not be Modified
Certain HTMPL templates and JavaScript files contain information required by many CA SDM web forms. The information in these templates is both release dependent and critical to the successful operation of the CA SDM web interface. Therefore, these files are always replaced when a new version of CA SDM is released; changes made to them are not upgraded.
The templates affected by this restriction are as follows:
  • ahdtop.htmpl
    Contains styles, scripts, and JavaScript variables used throughout the CA SDM web interface. This file is part of the main frameset of the web interface, and is always present during a session. All CA SDM forms have access to the JavaScript variable ahdtop that references the window containing ahdtop.htmpl.
  • menu_frames.htmpl
    Defines the HTML frameset used by the CA SDM main form.
  • msg_cat.js
    Contains the text of all messages used in CA SDM JavaScript files.
  • reports.htmpl
    Contains data required for web reports.
  • std_body.htmpl
    Contains standard information used at the beginning of the BODY section of most HTMPL templates.
  • std_footer.htmpl
    Contains standard information used at the end of the BODY section of most HTMPL templates.
  • std_head.htmpl
    Contains standard information used at the beginning of the HEAD section of almost all HTMPL templates.
  • styles.htmpl
    Contains CSS styles used throughout the CA SDM web interface.
Although you cannot modify these files directly, you can add additional information to them. Each restricted file xxx.htmpl (except for menu_frames.htmpl and reports.htmpl) has a corresponding xxx_site.htmpl file that you can modify. For example, you can add additional information to ahdtop.htmpl by modifying ahdtop_site.htmpl, or add new messages by modifying msg_cat_site.js.
The xxx_site.htmpl file corresponding to each restricted file is loaded after the main file so you can override or change JavaScript in the main file. Use caution when adding information, as badly designed changes to these files can cause unexpected problems throughout the CA SDM web interface.
Guidelines for New HTMPL Files
You can add your own HTMPL files to the CA SDM web interface. Follow these guidelines to help ensure your HTMPL file works well with the rest of the CA SDM interface:
  1. Include the following statement somewhere in the <HEAD> section of the file. This statement should follow the <TITLE> statement (if any). It defines several JavaScript global variables required by CA SDM web interface, and also registers your page with the CA SDM window manager:
    <PDM_INCLUDE FILE=std_head.htmpl>
  2. Include the following attribute as part of the <BODY> tag of the file. This attribute helps the CA SDM window manager keep track of your page:
    onUnload="deregister_window()"
  3. Include the following statement at the beginning of the <BODY> section of your file. The “menubar=no” argument is optional; if specified, it suppresses the CA SDM menu bar:
    <PDM_INCLUDE FILE=std_body.htmpl [menubar=no]>
  4. Include the following statement at the end of the <BODY> section of your file.
    <PDM_INCLUDE FILE=std_footer.htmpl>
How to Add User Defined State Information
Many customers want to be able to embed their own state information in the CA SDM web pages, and have CA SDM pass the state information to all subsequent pages it serves up to the user's session. This information can be interrogated with conditional statements in the HTMPL files.
State information for a user's session is accomplished by setting the special attribute USER_STATE in your links or forms. After it is submitted into the CA SDM web engine, every page that is presented to the user will have the HTMPL variable USER_STATE available and set to the value last submitted for USER_STATE.
The following examples show how you might set up an entry into CA SDM from some other part of your site, such as from pages that are oriented to your sales force:
  • Using a hyperlink
    <a href="/CAisd/pdmweb.exe?USER_STATE=Sales">Service Desk</a>
  • Using a form with a hidden field
    <form action="http://yourhost.com/CAisd/pdmweb.exe"> <input type=hidden name=USER_STATE value=Sales>
    Click the button for the Service Desk
    <input type=submit> </form>
Then you can modify your HTMPL forms based on the state information:
<PDM_IF "$USER_STATE" == "Sales">
custom information for sales audience
<PDM_ELIF "$USER_STATE" == "Engineering">
custom information for engineers
<PDM_ELSE>
information for everyone else
</PDM_IF>
How to Directly Create a Request from a Template
It is possible to create a Request directly from a Template using an URL.
Example
http://machinename/CAisd/pdmweb.exe?FACTORY=cr+OP=CREATE NEW+PERSID=cr:3106+use_template=1
where cr:3106 is the persid of the template.
Directories Used by Your HTTP Server
The default installation of CA SDM defines two virtual directories to your HTTP server:
  • The CAisd virtual directory points to the following directory in your CA SDM installation:
    1. In Windows:
      installation-directory
      \bopcfg\www\wwwroot
    2. In UNIX: $NX_ROOT/bopcfg/www/wwwroot
  • The CAisd/sitemods virtual directory points to the following directory in your CA SDM installation:
    1. In Windows:
      installation-directory
      \site\mods\www\wwwroot
    2. In UNIX: $NX_ROOT/site/mods/www/wwwroot
Subdirectories under these virtual directories are:
Subdirectory
Stores
css
Style sheets
help
Web interface help
html
HTML files
img
Graphic files
scripts
JavaScript
sitemods
Site-defined modifications
If you decide to create versions of any of the files in the css, html, img, or scripts directories, we strongly recommend that you do not update the file in /CAisd. Instead, store the file in the appropriate subdirectory of /CAisd/sitemods. For example, if you decide to modify a style sheet in /CAisd/css, store your modified version in /CAisd/sitemods/css. When the web engine parses an HTMPL file, it automatically modifies file names beginning with $CAisd to point to sitemods if the file exists in a subdirectory of sitemods.
Using the /CAisd/sitemods directory has these advantages:
  • It allows you to keep a record of the distributed files you have changed.
  • It gives you easy access to the original version in case there is a question or a problem.
  • It makes the process of installing maintenance or a new release easier, since CA SDM installation never places anything in the /CAisd/sitemods directory.
There is no /CAisd/sitemods/help subdirectory. Because the help data is in standard HTML files (not HTMPL templates), the web engine cannot dynamically change file references. If you need to modify help, you must make your changes in /CAisd/help.
The HTML subdirectory contains a few heavily used files that do not need to be processed by the web engine and can improve performance when cached on the browser. If you create version of any of these files, carefully check the file for references to other modified files. Because there is no web engine processing, you must manually insert a reference to sitemods where appropriate.
Download PDF Attachments
When you download and try to view a PDF attachment in CA SDM, the PDF file may not display correctly, or a blank window may appear after you upgrade to Adobe Acrobat release 7.0 or 8.0. With CA SDM, you can display the PDF file correctly by completing the following steps:
  1. Set the
    forceDecompressOnDownload
    parameter to YES in $NX_ROOT\bopcfg\www\CATALINA_BASE\webapps\CAisd\WEB-INF\web.xml.
    On Linux, $NX_ROOT is /opt/CAisd
  2. Restart the CA SDM services.