Running Diagnostics with Diagnostics Framework

This chapter provides an overview of Diagnostics Framework and discusses how to:

Set up security for Diagnostics Framework.
Run diagnostics.
Import post-release plug-ins.

Understanding Diagnostics Framework

This section discusses:

The purpose and benefits of Diagnostics Framework.
The architecture of Diagnostics Framework.

The Purpose and Benefits of Diagnostics Framework

PeopleSoft provides a framework for defining and retrieving application data diagnostics within the PeopleSoft Pure Internet Architecture (PIA) environment. Diagnostics Framework retrieves diagnostic information from a PeopleSoft database. With this diagnostic information, you can:

Discover problematic application-related data.
Explore setup details.
Present information to PeopleSoft support in a common format.

Using Diagnostics Framework, you can perform diagnostic tests on your system with minimal instructions from the PeopleSoft Global Support Center. These tests answer application-specific questions to help development and user support teams diagnose and troubleshoot any problems that you may be experiencing.

The tests can request additional parameters to tailor the diagnostics to your situation. They output HTML pages that you can open using any PeopleSoft-supported browser, and XML documents containing the same information in a form suitable for programmatic processing. You can email the HTML or XML documents to an application expert.

Diagnostics Framework is not designed to be a reporting tool, such as Query or Crystal Reports. Diagnostics Framework should not be used to return large amounts of data. Use it only to get small sets of diagnostic data, for example 100 rows of data or fewer.

The Architecture of Diagnostics Framework

Diagnostics Framework includes:

Delivered base classes in application packages.
Delivered application diagnostic plug-ins developed from the base classes and application packages.
The capability to extend delivered base classes to develop additional diagnostic plug-ins and to register the new plug-ins.
A common user interface for all diagnostic plug-ins.

Note. The PeopleSoft Global Support Center (GSC) might give you additional plug-ins to diagnose specific problems. These plug-ins are implemented differently from the plug-ins that you develop.

Diagnostics Framework is installed automatically when you install PeopleTools. Use standard PeopleSoft security administration to grant access to the user interface.

See Setting Up Security for Diagnostics Framework.

Application Classes and Packages

By definition, each application class is responsible for asking one diagnostic question. Each class has a method that is called by Diagnostics Framework. This method, in turn, gathers the information and calls methods in extended base classes that return the information to Diagnostics Framework. An application package is a container for application classes or other application packages.

See Application Classes.

Diagnostic Plug-ins

Application packages that are used in Diagnostics Framework are referred to as diagnostic application packages. Each is a collection of application classes and methods encapsulated within an application package. The metadata that defines a diagnostic application package is referred to as a diagnostic plug-in. In this documentation, we refer to diagnostic application packages as diagnostic plug-ins or simply as plug-ins.

Diagnostic plug-ins probe the application for diagnostic information. When you perform diagnostic tests on your PeopleSoft system, Diagnostics Framework executes programs within these plug-ins and then returns the information from those programs in an HTML or XML document. Because of Diagnostics Framework, these plug-ins supply a consistent method of gathering relevant diagnostic information from your system.

There are three categories of diagnostic plug-ins:

Delivered diagnostic plug-ins that are automatically installed when you install PeopleTools and PeopleSoft applications.

The available diagnostic plug-ins depend on which applications you have installed. Appropriate plug-ins are automatically available after your application installation is complete.
Post-release diagnostic plug-ins that PeopleSoft Global Support Center might send to you for specific diagnostic purposes.

You import these plug-ins to Diagnostics Framework using PeopleSoft Application Designer.
Custom diagnostic plug-ins that you develop.

You must register custom plug-ins before you can use them.

Note. If you want to register existing plug-ins from other PeopleSoft releases, you must ensure that they're defined according to the guidelines used for custom plug-ins in the current release.

All registered plug-ins appear in the Diagnostics Framework user interface. Delivered plug-ins are grouped according to installed PeopleSoft applications and functional areas within the applications. From here, you can select which plug-ins to run. A user support person may ask you to run a particular plug-in, depending on the problem that you are reporting.

Setting Up Security for Diagnostics Framework

This section provides an overview of security for Diagnostics Framework and discusses how to:

Grant access Diagnostics Framework pages.
Grant access to the WEBLIB_PTDIAG web library.

Understanding Security for Diagnostics Framework

To gather information using Diagnostics Framework, you must have access to:

The Diagnostics Framework pages.
The WEBLIB_PTDIAG web library.

You use the PeopleTools Security pages to select or create a permission list to which you can add the necessary permissions for these elements. That permission list should ultimately be assigned through a role to the users who will run diagnostics.

Pages Used to Set Up Security for Diagnostics Framework

Page Name	Object Name	Navigation	Usage
Pages	ACL_GENERAL	PeopleTools, Security, Permission & Roles, Permission Lists, Pages	Set up security access to menus.
Component Permissions	ACL_COMPONENT2	Click Edit Components on the Pages page.	Set up security access to components.
Page Permissions	ACL_PAGES2	Click Edit Pages on the Component Permissions page.	Set up security access to pages.
Web Libraries	ACL_WEBLIBS	PeopleTools, Security, Permission & Roles, Permission Lists, Web Libraries	Set up security access to web libraries.
Web Lib Permissions	ACL_WEBLIB_ACCESS	Click Edit on the Web Libraries page.	Set up security access to web library functions.

Granting Access to the Diagnostics Framework Pages

To run diagnostics, you must have access to the following Diagnostics Framework pages:

PT_DIAG_PLUGIN
PT_DIAG_FRAME_REG

To set up security access to these pages:

Select or define a permission list to which you want to add Diagnostics Framework permissions.

See Setting Up Permission Lists.
Access the Pages page for the selected permission list.

This page lists the menus to which this permission list has some degree of access.
If the PT_DIAGNOSTICS menu isn't listed on this page, add a new row and select it.
Click the Edit Components link for the PT_DIAGNOSTICS menu.

The Component Permissions page appears.
Click the Edit Pages link for the PT_DIAG_LAUNCH component.

The Page Permissions page appears.
Click Select All to grant full access to the PT_DIAG_PLUGIN page, then click OK to return to the Component Permissions page.
Click the Edit Pages link for the PT_DIAG_FRAME_REG component.

The Page Permissions page appears.
Click Select All to grant full access to the PT_DIAG_FRAME_REG page, then click OK to return to the Component Permissions page.
Click OK, then save the permission list.

Granting Access to the WEBLIB_PTDIAG Web Library

To set up security access to WEBLIB_PTDIAG:

Access the Web Libraries page for the permission list for which you've already granted access to the Diagnostics Framework pages.

This page lists the web libraries to which the permission list has some degree of access.
If the WEBLIB_PTDIAG web library isn't listed on this page, add a new row and select it.
Click the Edit link for the WEBLIB_PTDIAG web library.

The Weblib Permissions page appears.
Click Full Access (All) to grant full access to the WEBLIB_PTDIAG web library.
Click OK, then save the permission list.

Running Diagnostics

This section discusses how to:

Launch diagnostic plug-ins.
Provide additional information.
Obtain diagnostic results.

Launching Diagnostic Plug-Ins

Select Application Diagnostics, Launch Diagnostics to access the Launch Diagnostics page.

This page displays a list of available diagnostic plug-ins. Only registered plug-ins appear.

Plug-In Name	Displays the name of the application package that defines each diagnostic plug-in.
Select	Select this check box for each diagnostic plug-in package that you want to run. Click the Select All link to include all of the listed plug-ins, or the Clear All link to exclude all of the listed plug-ins from the diagnostics Note. You must select at least one diagnostic plug-in.
Display report in browser	Select to display the generated HTML diagnostic report in a new browser window.
Email report	Select to generate an email containing HTML and XML copies of the generated diagnostic report. The following standard email fields appear: Email From To CC (optional) Subject (optional) Note. Before you can use this option, you must configure the application server domain to handle SMTP email. See SMTP Settings.
Generate Diagnostics	Click to launch the selected diagnostics, and either display or email the resulting report.

Providing Additional Information

When you click the Generate Diagnostics button on the Launch Diagnostics page, one or more of the diagnostic plug-ins you selected might have been designed to dynamically prompt you for relevant parameters. The Additional Information page appears to enable you to enter the required parameters.

The fields that appear on this page depend on the diagnostic plug-ins that you specified on the Launch Diagnostics page. The Additional Information page includes a section for each plug-in that requires information. Each section can contain fields that are specific to individual classes, or fields that apply globally for the plug-in. For the diagnostic plug-ins delivered with your PeopleSoft application, your application documentation explains what values are required for each field.

Obtaining Diagnostic Results

When all of the diagnostic results have been gathered, they're disseminated based on the option you selected on the Launch Diagnostics page.

If you selected Display report in browser, the resulting PeopleSoft Diagnostics page appears in HTML format in a new browser window. Following is an example of the PeopleSoft Diagnostics page in HTML format.

Rowset information is presented on the page in tabular form, and non-rowset information is presented in list form. You can use your browser's Save As functionality to save the page to your local machine.

If you selected Email report, the resulting PeopleSoft Diagnostics page is emailed as HTML and XML attachments to the address you specified. Following is an example of the XML that comprises a PeopleSoft Diagnostics page.

<?xml version="1.0"?>
<PeopleSoftDiagnostics>
  <UserInformation>
	<Database_Name>QE845DVL</Database_Name>
	<User_ID>QEDMO</User_ID>
	<Date_Created>2004-01-30-16.04.54.000000</Date_Created>
	<Database_Type>MICROSFT</Database_Type>
  </UserInformation>
  <ApplicationDiagnostics>
    <PT_DIAGNOSTIC_PLUGIN>
      <GetLanguages>
        <Purpose>This is a diagnostic to determine all of the languages installed in your PeopleSoft Database. This diagnostic
tests AddRowset functionality.</Purpose>
        <Result>
          <LANGUAGE_CD>CFR</LANGUAGE_CD>
          <CHARSET>ISO_8859-1</CHARSET>
          <INSTALLED>0</INSTALLED>
          <VERITY_LOCALE>frenchx</VERITY_LOCALE>
          <SCLANG>SC16</SCLANG>
          <WINDOWS_CHARSET>CP1252</WINDOWS_CHARSET>
          <VERITY_CHARSET>CP1252</VERITY_CHARSET>
          <ISO_LOCALE>fr-ca</ISO_LOCALE>
        </Result>
        <Result>
          <LANGUAGE_CD>DAN</LANGUAGE_CD>
          <CHARSET>ISO_8859-1</CHARSET>
          <INSTALLED>0</INSTALLED>
          <VERITY_LOCALE>danishx</VERITY_LOCALE>
          <SCLANG>SC09</SCLANG>
          <WINDOWS_CHARSET>CP1252</WINDOWS_CHARSET>
          <VERITY_CHARSET>CP1252</VERITY_CHARSET>
          <ISO_LOCALE>da</ISO_LOCALE>
        </Result>
        <Result>
          <LANGUAGE_CD>ENG</LANGUAGE_CD>
          <CHARSET>ISO_8859-1</CHARSET>
          <INSTALLED>1</INSTALLED>
          <VERITY_LOCALE>englishx</VERITY_LOCALE>
          <SCLANG>SC00</SCLANG>
          <WINDOWS_CHARSET>CP1252</WINDOWS_CHARSET>
          <VERITY_CHARSET>CP1252</VERITY_CHARSET>
          <ISO_LOCALE>en</ISO_LOCALE>
        </Result>
      </GetLanguages>
      <GetRecFieldsBeginningWith>
        <Purpose>This is a diagnostic to print out a listing of fields from records in your PeopleSoft database that matches
search criteria.  This diagnostic tests globalType and classType prompting.  The global prompt is retrieved from inputs defined
by a different class in this plug-in.</Purpose>
        <AdditionalInformation>
          <Question>Enter Records to search for, beginning with:</Question>
          <Answer>MAINT</Answer>
        </AdditionalInformation>
        <AdditionalInformation>
          <Question>Enter FieldNames to retrieve, beginning with:</Question>
          <Answer>REL</Answer>
        </AdditionalInformation>
        <Result>
          <Descr>Record: MAINTENANCE_LOG has the following field that matches your criteria: </Descr>
          <Type>String</Type>
          <Answer>RELEASEDTTM</Answer>
        </Result>
        <Result>
          <Descr>Record: MAINTENANCE_LOG has the following field that matches your criteria: </Descr>
          <Type>String</Type>
          <Answer>RELEASELABEL</Answer>
        </Result>
        <Result>
          <Descr>Record: MAINTLOGREL_VW has the following field that matches your criteria: </Descr>
          <Type>String</Type>
          <Answer>RELEASEDTTM</Answer>
        </Result>
        <Result>
          <Descr>Record: MAINTLOGREL_VW has the following field that matches your criteria: </Descr>
          <Type>String</Type>
          <Answer>RELEASELABEL</Answer>
        </Result>
      </GetRecFieldsBeginningWith>
    </PT_DIAGNOSTIC_PLUGIN>
  </ApplicationDiagnostics>
</PeopleSoftDiagnostics>

Importing Post-Release Plug-Ins

If information that you generate from the delivered plug-ins is not sufficient to diagnose your problem, the PeopleSoft Global Support Center (GSC) might give you additional plug-ins. You import these plug-ins into your database using the Copy Project from File command in PeopleSoft Application Designer.

A plug-in project is an upgrade project, and it must contain the following definitions:

Application Packages.
Diagnostic Plug-Ins.
Application Package PeopleCode.

If you need to send a file to GSC or move a file between databases, use the Copy Project to File command in PeopleSoft Application Designer.

See Upgrading with PeopleSoft Application Designer.

Plug-ins that you import are registered automatically; they become immediately available on the Launch Diagnostics page.