16. Documentation for Agent Plugins

Owned by Jenni Wallin
Last updated: May 16, 2023 by Former user (Deleted)

This chapter describes how to create online help content for agent plugins.

User's Guide Contents

Documentation of an application should follow a certain structure to be consistent with existing user documentation, provided in . There is a set order of sections where the information should be presented in the following way:

SectionDescription

Section 1 - Introduction

  • Contains information about the agent type (real-time/batch), and whether it is available in the Platform or as a  plugin etc.

  • Section 1.1 - Prerequisites

  • Section 1.2 - Documentation (if applicable)

  • Section 1.3 - Abbreviations and Terms (if applicable)

Section 2 - Installation/ Further Info/ Setup (if applicable)

This section is optional and will specify required procedures for configuring the application as declared in the following sections.

Section 3 - Profile (if applicable)

If there is a profile that needs configuration, it should be described before the agent configurations are described.

There must be a screenshot of the GUI provided, with all the GUI items listed and described below. The items are listed in two columns with items to the left and the description to the right. Also, if applicable, suggested values or examples may be provided.

If the GUI contains configurations in separate tabs, each tab must be described in its own subsection, each providing a screenshot of GUI and item listing.

Section 4 - Agent

This section, including all subsections, are repeated for each agent in the User's Guide; Collection, Processing, Forwarding etc.

  • Section 4.1 - Configuration

    There must be a screenshot of the GUI provided, with all the GUI-items listed and described below. The items are listed in two columns with items to the left and the description to the right. Also, if applicable, suggested values or examples may be provided.

    If the GUI contains configurations in separate tabs, each tab must be described in its own subsection, each providing a screenshot of GUI and item listing.

  • Section 4.1 - Transaction Behavior

    Possibly a description of transaction behavior if not self explanatory.

    • Section 4.1.1 - Emits

      List the possible transaction methods the agent is sending out. If nothing is emitted, write "This agent does not emit any transaction methods" in this section.

    • Section 4.1.2 - Retrieves

      List the possible transaction methods the agent can receive. If nothing is retrieved "This agent does not retrieve any transaction methods." in this section.


  • Section 4.2 - Input/Output Data

    Describe the data types the agent produces and consumes.

  • Section 4.3 - MIM

    • Section 4.3.1 - Publishes

      List the MIM Resources produced by the agent, including a short description. If no MIMs are produced, write "This agent does not publish any MIMs." in this section.

    • Section 4.3.2 - Accesses

      List the MIM Resources fetched by the agent, including a short description. If no MIMs are accessed, write "This agent does not access any MIMs." in this section.

    Include a reference to the Desktop - User's Guide, for a listing of general MIM resources.

  • Section 4.4 - Agent Message Event

    List the Agent Message Events produced by the agent, including a short description of when they occur. If no Agent Message Events are produced, write "This agent does not produce any events." in this section.

Section 5 - Inspection (if applicable)

If there is an inspection tool available, it should be described following the agent configuration descriptions.

There must be a screenshot of the GUI provided, with all the GUI-items listed and described below. The items are listed in two columns with items to the left and the description to the right. Also, if applicable, suggested values or examples may be provided.

If there is a Search option to limit the inspection, this GUI must be described in its own subsection, providing a screenshot and item listing.

Section 6 - Example (optional)

Where the usage of an application is complex, it is sometimes helpful to provide an example of a "real" situation, including corresponding configurations. If this is necessary, the section is placed at the end of the User's Guide.


Online Help Search Index

In order to make the menu item Complete Documentation available from the Help menu in  Desktop, a search index has to be generated and included in the .hs file:

  1. Download and install JavaHelp 2.0 from:

    http://javahelp.java.net

  2. Go to the directory where the javahelp files are stored:

    cd <directory including javahelp files> 

  3. Run the jhindexer command to create a search index directory:

    jhindexer .

    The command generates a new directory called JavaHelpSearch which contains the search index.

  4. Specify the new JavaHelpSearch directory as the search index directory in the .hs script:

    <view>
    <name>Search</name> 
    <label>Search</label> 
    <type>javax.help.SearchView</type> 
    <data engine="com.sun.java.help.search.DefaultSearchEngine">JavaHelpSearch</data> 
</view>
  5. Make sure that the JavaHelpSearch directory is included in the resulting  package. See Creating a User Defined Package in 3. Creating a DTK Plugin for information on how to create  packages.

The menu item Complete Documentation in the Help menu will be available after the  package containing a correctly configured search index directory has been sent to the Platform with the pcommit command.

Note!

A Desktop restart might also be necessary.

Next:
17. Agent Plugin Examples