This section includes the following topics:

Add-on AppTier installation package descriptor file

The Add-on AppTier installation package zip file should be accompanied by a descriptor XML file. AdminPoint receives the descriptor XML file when the Add-on AppTier is plugged-in.

The Add-on AppTier installation descriptor file carries the same name as the Add-on AppTier installation package zip file. The descriptor file extension is xml.

Add-on AppTier installation package descriptor file example

The following is an example of an Add-on AppTier installation package descriptor file.

<sdk-package>
     <apptier-name> Generic Mail Server </apptier-name>
     <package-files>
          <package-file package-to-set="true"> GenericMailServer.zip
          </package-file>
     </package-files>
</sdk-package>

The following is the basic hierarchy of an XML-based descriptor file:

The root element <sdk-package>; has no attributes

  • AppTier name element; has no attributes. Its text value is the Add-on AppTier name and it is used in AdminPoint plug-in dialog screen.
  • Package files element has two Package file child elements. Their text values are the names of the Add-on AppTier installation package zip file and the descriptor XML file.
  • The Package file element for the Add-on AppTier installation package zip file should have one attribute named package-to-set with a value of "true."

Add-on AppTier installation package contents

The Add-on AppTier plug-in installation package defines to the Precise environment how the information is structured. It defines the general characteristics of the application, entities, and counters.

There are several files inside the installation package. These XML files are prepared before Add-on AppTier installation on a server. All of the files are placed together in a zip file.

The following files are found in the installation package:

  • External Technology Designer (ETD) file
  • GUI resource file or files

The software designer assigns a version number to the Add-on AppTier installation package in order to differentiate between future versions of the information structure that may not be compatible.

The name of the installation package zip file should be as follows: I3SDK_application-name_version.zip

Table 1 Installation package definitions

ElementDescription
I3SDK

This the root element and identifies the installation package for the Add-on AppTier.

Value: always I3SDK

application-name

Defines the application name, maximum 10 characters.

Value: String

version

Identifies the current version for this installation package.

Value: Numeric

ETD file

The ETD file defines entities and counters for each performance record.

ETD file example

The following is an example of the ETD file in the Add-on AppTier installation package. Notice the hierarchy of all elements, attributes, and sub-elements.

The following is the basic hierarchy of an XML-based ETD file:

  • The root element is <SDK>
  • General characteristics of the application and their attributes
  • Entities and their attributes
  • Counters and their attributes

<etd version="1.0">
     <version major="0" minor="1"/>
     <!-- application level definitions -->
     <application id="MS" tid="1" internal_name="MAILSERVER" range="20000">
          <integration network="no" availability="no" instance-is-server="no" agent-type="file" /> <!-- "file" or "arm" collection mode -->
          <pw threshold="0"/>
          <sla-entity eid="A" />
          <collection dir="products/sdk/MS" remote="no" min-activity-report="3" max-activity-report="15" availability-report="15" />
          <service-time>
               <counter tid="100" />
          </service-time>
          <zoom-displays />
          <performance />
     </application>
     <entities>
          <!-- mail msg, activity -->
          <entity eid="A" tid="501" plural-tid="502" grouping-tid="503" plural-grouping-tid="504" length="256">
               <display mandatory="yes" order="1" />
               <data class="activity" type="varchar" dbcolumn="MAIL_MSG" mandatory="yes" last-summary="all" collection-id="msg" />
               <load allow-drop="no" />
               <integration alerts="no" foresight="yes" />
               <service-time />
          </entity>
          <!-- sender, user classification -->
          <entity eid="U" tid="511" plural-tid="512" grouping-tid="513" plural-grouping-tid="514" length="256"
               <display mandatory="no" order="6" />
               <data class="user_name" type="varchar" dbcolumn="SENDER" mandatory="yes" last-summary="all" collection-id="sender" />
               <load allow-drop="no" />
               <integration alerts="no" foresight="yes" />
               <service-time />
          </entity>
          <!-- sender ip, "client ip" classification -->
          <entity eid="C" tid="521" plural-tid="522" grouping-tid="523" plural-grouping-tid="524" length="256">
               <display mandatory="no" order="7" />
               <data class="client_ip" type="varchar" dbcolumn="SENDER_IP" mandatory="yes" last-summary="all" collection-id="C_IP" />
               <load allow-drop="no" />
               <integration alerts="no" foresight="yes" />
               <service-time />
          </entity>
          <!-- msg type, "user defined" classification, no grouping -->
          <entity eid="T" tid="531" plural-tid="532" length="256">
               <display mandatory="no" order="9" />
               <data class="user-defined" type="varchar" dbcolumn="MSG_TYPE" mandatory="yes" last-summary="all" collection-id="type" />
               <load allow-drop="no" />
               <integration alerts="no" foresight="yes" />
               <service-time />
          </entity>
          <!-- instance - name of mail server -->
          <entity eid="I" tid="541" plural-tid="542" grouping-tid="543" plural-grouping-tid="544" length="256">
               <display mandatory="yes" order="2" />
               <data class="instance" type="varchar" mandatory="yes" last-summary="all" />
               <load allow-drop="no" />
               <integration alerts="no" foresight="yes" />
               <service-time />
          </entity>
          <!-- server machine -->
          <entity eid="S" tid="551" plural-tid="552" grouping-tid="553" plural-grouping-tid="554" length="256">
               <display mandatory="yes" order="3" />
               <data class="server" type="varchar" mandatory="yes" last-summary="all" />
               <load allow-drop="no" />
               <integration alerts="no" foresight="yes" />
               <service=time />
          </entity>
     </entities>
     <counters>
          <!-- delivery time - service time -->
          <counter tid="100">
               <display color="34" colorRGB="123" sortable="yes" sum-format="duration-HH:MI:SS" avg-format="avgDuration-HH:MI:SS.TTT" />
               <data class="service" type="float" dbcolumn="DELIVERY_TIME" mandatory="yes" func="SUM" collection-id="delivery" />
          </counter>
          <!-- msg size - statistical counter -->
          <counter tid="110"
               <display color="30" colorRGB="125" sortable="yes" sum-format="byteFloat" avg-format="byteFloat" />
               <data class="statistic" type="float" dbcolumn="MSG_SIZE" mandatory="yes" func="SUM" collection-id="size" />
          </counter>
          <!-- recipients - execution counter -->
          <counter tid="120">
               <display color="33" colorRGB="126" sortable="yes" sum-format="number" avg-format="" />
               <data class="execution" type="float" dbcolumn="REQUESTS" mandatory="yes" func="SUM" collection-id="recipients" />
          </counter>
     </counters>
     <misc-fields>
          <!-- timestamp field -->
          <field tid="999">
               <data class="timestamp" type="timestamp" dbcolumn="TIMESTAMP" mandatory="yes"
               <collection-id="D" />
          </field>
     </misc-fields>
     <agent-installer-params />
</etd>

About ETD file definitions

Each entity and each counter has a set of properties that describe how they are received, stored, and displayed in Precise products.

The following table specifies version types under the EDT file SDK root element.

Table 2 Types of versions under the ETD file SDK root element

Version TypesDescription
majorFor documentation of the Add-on AppTier installation package version.
minorFor documentation of the Add-on AppTier installation package version.

About ETD file application-level entities

Application-level definitions are a set of properties that describe the scope and display of data from the Add-on AppTier application.

The following table specifies the various identifiers for the add-on technology. The <application> element is a mandatory child element of the root element.

Table 3 Application element positioned under the Precise root directory

Application Attribute NameDescription
tid

The title ID for the technology name.

Value: Numeric. Always exists in the file or files.

Mandatory: Yes

internal_name

Internally identifies a Precise product.

Value: max length of 18. Always uppercase letters or digits only (no blanks or underscore used). Usually the value is derived from the title of the application.

Mandatory: Yes

id

Identifies the add-on technology.

Value: always 2 characters; provided as part of the Precise registration procedure.

Mandatory: Yes

range

Used in conjunction with tid attributes to make the values unique across technologies.

Value: Numeric; provided as part of the Precise registration procedure.

Mandatory: Yes

The following table specifies the collection mode and possible integration with Precise components. The <integration> element is a mandatory child element of <application>.

Table 4 Integration element positioned under the application element

Integration Attribute NameDescription
network

Specifies whether integration network monitoring is currently available. Must always be either Yes or No.

Value: Yes, if integration network monitoring is currently supported.

Value: No, if integration network monitoring is currently not supported. "No" is the default value.

Mandatory: No

availability

Specifies whether monitoring for availability is currently available. Must always be either Yes or No.

Value: Yes, if monitoring for availability is currently supported.

Value: No, if monitoring for availability is currently not supported. "No" is the default value.

Mandatory: No (for future use)

instance-is-server

Specifies whether the same entity is used as both instance and server. Must always be either Yes or No.

Value: Yes, if instance is installed on a server.

Value: No, if instance is not installed on a server. "No" is the default value. Mandatory: No (for future use)

agent-type

Identifies the File or ARM collection.

Value: either "file" or "arm".

Mandatory: Yes

The following table specifies possible parameters for the PMDB load process. The <pw> element is an optional child element of <application>.

Table 5 PMDB element positioned under the application element

PW Attribute NameDescription
threshold

The load threshold. Rows with a service time smaller than specified are collapsed into one row.

Value: Numeric, if specified.

Mandatory: No (for future use)

The following table specifies the entity that is used for SLA calculations. The <sla-entity> element is an optional child element of <application>.

Table 6 sla-entity element positioned under the application element

sla-entity Attribute NameDescription
eidIf an entity with a Precise classification activity was defined, put its entity as value. Otherwise, use an empty string.

The following table specifies the collection properties. The <collection> element is a mandatory child element of <application>.

Table 7 Collection element positioned under the application element

Collection Attribute NameAttributes
dir

The relative path under the Precise Listener where Collector files are harvested. A valid path name always includes a forward slash "/" as a file separator. For example: products/sdk/MS.

Mandatory: Yes

remote

Specifies whether remote collection is available.

The server where the Collector runs is different than the server where the monitored application runs.

Value: Yes, No. "No" is the default value.

Mandatory: No

min-activity-report

Specifies the minimum frequency for reporting activity data (largest time slice).

Value: Numeric, if specified.

Mandatory: No (for future use)

max-activity-report

Specifies the maximum frequency for reporting activity data (smallest time slice).

Value: Numeric, if specified.

Mandatory: No (for future use)

availability-report

Specifies the frequency for reporting availability data (size of time slice).

Value: Numeric, if specified.

Mandatory: No (for future use)

The following table specifies the counters that make up the application's service time. The <service-time> element is a mandatory child element of <application>.

Table 8 Service-time element positioned under the application element

Service-timeDescription
service-time

Specifies the display order for the service time breakdown in Insight and Report Manager. Must have at least one child element <counter>; multiple children are allowed.

Each counter child must have a "tid" attribute with a value equal to the counter's "tid". (The child for the <counters> element is equal to the child of the root.)

This element has no attributes.

The following table specifies a zoom display. The <zoom-displays> element is an optional element of <application>.

Table 9 Zoom-displays element positioned under the application element

Zoom-displays Element NameDescription
zoom-displaysThis element has no attributes (for future use).

The following table specifies performance. The <performance> element is an optional element of <application>.

Table 10 Performance element positioned under the application element

Performance Element NameDescription
performanceThis element has no attributes (for future use).

About ETD file entities

This section contains functional and technical specifications for Add-on AppTier entities.

The following table specifies the entities for the Add-on AppTier. The <entities> element is a mandatory child element of the root.

Table 11 Entities element positioned under the root element

Entities Element NameDescription
entities

Must have at least one child element <entity>. Multiple children are allowed.

The Instance and Server entities are mandatory. There must be one entity with a class activity.

This element has no attributes.

Only one entity per class attribute: client_ip, activity, program, application, user_name, instance or server, can be defined. Multiple entities with user-defined class are allowed.

The following table defines one entity. The <entity> element is a mandatory child element of <entities>. Multiple instances are allowed.

Table 12 Entity element positioned under the entities element

Entity Attribute NameDescription
eid

Uniquely identities an entity.

Value: One character, uppercase letter only.

Mandatory: Yes

tid

The Title ID for an entity, as it appears in the drop-down menu list.

Value: Numeric, always exists in the file or files.

Mandatory: Yes

plural-tid

The Title ID for an entity in plural form, as it appears in the graph title.

Value: Numeric, always exists in the file or files.

Mandatory: Yes

grouping-tid

If specified, this entity has a grouping function. It specifies the Title ID for a grouped entity, as it appears in the drop-down menu list.

Value: Numeric, always exists in the file or files.

Mandatory: No

plural-grouping-tid

If specified, this entity has a grouping function. It specifies the Title ID for a grouped entity in plural form, as it appears in the graph title.

Value: Numeric, always exists in the file or files.

Mandatory: No

length

The maximum length value in numbers.

Value: Numeric

Mandatory: Yes

These entities have the following length limitations:

  • Entity Name (singular), maximum 30 characters
  • Entity Name (plural), maximum 30 characters
  • DB Column Name, 2 - 20 characters

The following table defines the display properties of the entity. The <display> element is a mandatory child element of <entity>.

Table 13 Display element positioned under the entity element

Display Attribute NameDescription
mandatory

Defines whether the entity graph can be hidden in Insight display settings.

Value: Yes, No

Mandatory: Yes

order

Defines the position of the entity's graph in the Insight "all" display.

Value: Numeric

Mandatory: Yes

The following table defines the database related properties. The <data> element is a mandatory child element of <entity>.

Table 14 Data element positioned under the entity element

Data Attribute NameDescription
class

Defines the classification used to map the entity to the Insight Cross-AppTier display.

Valid values: "activity", "program", "application", "user_name", "instance", "server", "client_IP", or "user_defined".

Mandatory: Yes

type

Defines the data type of a database column.

Value: "varchar"

Mandatory: Yes

dbcolumn

The name of the database column.

Value: Yes, No

Mandatory: Yes

Instance and Server entities have fixed database column names that are automatically set by Precise during plug-in installation. The attribute cannot be specified for these entities in the ETD file.

mandatory

Defines whether the database column is nullable.

Values: Yes or No

Mandatory: yes

last-summary

Specifies whether an entity exists in all PW summary levels.

Valid values: "all", "T", "H", "G", "D", or "W".

Mandatory: No (for future use)

collection-id

The name of a field in a Collector file.

Value: a valid XML tag.

Mandatory: Yes

NOTE:     Instance and Server entities have no collection-id. The values for these entities in the

Collector file are specified in the rowset level; not in the row level.

The following table specifies loading parameters. The <load> element is an optional child element of <entity>.

Table 15 Load element positioned under the entity element

Load ElementDescription
allow-drop

Specifies whether this entity can be dropped during loading. (This option appears in PW load process parameters.)

Value: Yes, No

Mandatory: No (for future use)

The following table defines whether an entity can be filtered. The <filter> element is an optional child element of <entity>. If specified, it must have one child element <value> with a text value.

Table 16 Filter element positioned under the entity element

Filter ElementDescription
filterThis element has no attributes (for future use).

The following table specifies whether this entity is applicable for other Precise products besides Insight. The <integration> element is an optional child element of <entity>.

Table 17 Integration element positioned under the entity element

Integration Attribute NameDescription
alerts

Specifies whether this entity is applicable for Alerts.

Values: Yes, No

Mandatory: No (for future use)

report manager

Specifies whether this entity is applicable for Report Manager.

Values: Yes, No

Mandatory: Yes

The following table specifies whether this entity has a special service time breakdown. The <service-time> element is an optional element of <entity>.

Table 18 Service-time element positioned under the entity element

Service-time ElementDescription
service-timeThis element has no attributes (for future use).

About etd file counters

This section contains functional and technical specifications for Add-on AppTier counters.

The following table specifies the counters for the Add-on AppTier. The <counters> element is a mandatory child element of the root.

Table 19 Counters element positioned under the root

Counters ElementDescription
counters

Specifies the counters for the Add-on AppTier. The <counters> element must have at least one child element <counter>.

There must be at least one counter with a class service. It must be the first one in the counters section (in the etd file).

This element has no attributes.

Execution counter must be defined in the etd.xml file (only one can be defined). Although the counter is defined, the agent does not need to report this counter in the data file.

The following table defines the attribute for one counter only. The <counter> element is a mandatory child element of <counters>.

Table 20 Counter tid element positioned under the counters element

Counter Attribute NameDescription
tid

The Title ID for a counter.

Value: Numeric, always exists in file or files. For different counters, the values of tid must be specified in intervals of 10.

Mandatory: Yes

The following table defines the display properties of the counter. The <display> element is a mandatory child element of <counter>.

Table 21 Display element positioned under the counters element

Display Attribute NameDescription
color

Specifies the color code for Insight bar graphs.

Value: Figure 1

The value is the sequential number before the bracket.

Mandatory: Yes

colorRGB

Specifies the color code for Report Manager reports.

Value: Figure 1

The value is the hexadecimal value on the right of the color that then needs to be converted to its equivalent decimal value. For example color with the code 0 and hexdecimal value 071685 becomes 464516 decimal.

Mandatory: Yes

sortable

Specifies whether a counter appears in an Insight sort drop down list.

Value: Yes, No

Mandatory: Yes

sum-format

Displays the format summed value.

Value: see counter display formats table for Display sub-elements.

Mandatory: Yes

avg-format

Displays the format average value.

Value: see counter display formats table for Display sub-elements.

Mandatory: Yes

The following figure displays the color codes that can be used for the color and color RGB attributes of the display element.

Ignore the diagonal lines in some of the color boxes.

Figure 1 Color code table

The following table specifies counter display formats for Display sub-elements positioned under the counter sub-element.

Table 22 Counter display formats for the Display sub-elements positioned under the counter sub-element.

FormatGUI DefinitionDescription
Duration

sum-format: HH:MI:SS

avg-format: HH:MI:SS.TTT

Time counter (format for Service-time classification)
int CountnumberInteger counter, big numbers, display as K/M/G.
float CountnumberFloat

Execution classified counter must have sum-format="number" and avg-format="".

Statistical classified counters have number, numberFloat, or byteFloat.

BytesbyteFloatBytes; may be displayed as bytes, KB, MB, GB.

The following table defines database-related properties. The <data> element is a mandatory child element of <entity> and <counter>.

Table 23 Data element positioned under the counter element

Data Attribute NameDescription
class

Defines the classification used to build a service time breakdown and statistical graphs.

Value: "service", "execution", or "statistic".

Mandatory: Yes

type

Defines the data type for a database column.

Value: float

Mandatory: Yes

dbcolumn

The name of a database column.

Value: valid database column.

Mandatory: Yes

Execution classified counter has a fixed dbcolumn name: "REQUESTS".

mandatory

Defines whether the database column is nullable.

Value: Yes, No

Mandatory: Yes

func

An aggregation function for the PW summary process.

Value: sum

Mandatory: No

collection-id

The field name in a Collector file.

Value: a valid XML tag.

Mandatory: Yes

The following table specifies additional fields that are neither entities or counters. The <misc-fields> element is a mandatory child element of the root.

Table 24 Misc-fields element positioned under the root element

Misc-fields ElementDescription
misc-fields

Must have at least one child element <field>. Multiple children are allowed.

Currently, one field child is mandatory: timestamp field.

This element has no attributes.

The following table defines the field for a counter. The <field> element is a mandatory child element of <misc-fields>.

Table 25 Field element positioned under misc-fields element

Field Attribute NameDescription
tid

A dummy Value.

Value: "999"

Mandatory: Yes

The following table defines the database related properties. The <data> element is a mandatory child element of <field>.

Table 26 Data element positioned under field element

Data Attribute NameDescription
Class

Defines the classification.

Value: "timestamp"

Mandatory: Yes

dbcolumn

The name of a database column is fixed.

Value: "TIMESTAMP"

Mandatory: Yes

mandatory

Defines whether the database column is nullable.

Value: Yes

Mandatory: Yes

Type

Defines the data type of a database column.

Value: timestamp

Mandatory: Yes

collection-id

The field name in a Collector file.

Value: a valid XML tag.

Mandatory: Yes

The following table specifies the name of the timestamp field in the Collector file. The timestamp field is a mandatory field child element of <misc-fields>.

Table 27 Timestamp field positioned under the misc-fields element

Timestamp FieldDescription
timestampThe collection-id attribute.

The following table specifies needed parameters for installation. The <agent-installer-params> element is an optional child element of the root.

Table 28 Agent-installer-params element positioned under the root element

Agent-installer-params ElementDescription
agent-installer-paramsThis element has no attributes (for future use).

The following are counter guidelines:

  • Service Time, at least one is required
  • Executions, always fixed
  • Counter Name, maximum 15 characters
  • DB Column Name, between 2 - 20 characters

About the titles file or files

The titles file or files specify captions and headings that are displayed in Precise products. These are the application names as well as entity and counter names. A different titles file exists for each required language. At the least, one English-language titles file named titles-en.xml has to be created.

Precise displays captions in English and Japanese only for Precise supported technologies.

The following is an example of a titles file in English.

<titles-en>
     <tid="1"> Generic Mail Server </t>
     <displays>
     </displays>
     <entity-single>
          <tid="501"> Mail Msg </t>
          <tid="511"> Sender </t>
          <tid="521"> Sender IP </t>
          <tid="531"> Msg Type </t>
          <tid="541"> Instance </t>
          <tid="551"> Server </t>
     </entity-single>
     <entity>
          <tid="502"> Mail Msgs </t>
          <tid="512"> Senders </t>
          <tid="522"> Sender IPs </t>
          <tid="532"> Msg Types </t>
          <tid="542"> Instances </t>
          <tid="552"> Servers </t>
     </entity>
     <entity-grouping-single>
          <tid="503"> Mail Msgs (Grouped) </t>
          <tid="513"> Senders (Grouped) </t>
          <tid="523"> Senders Location </t>
          <tid="543"> Instances (Grouped) </t>
          <tid="553"> Servers (Grouped) </t>
     </entity-grouping-single>
     <entity-grouping>
          <tid="503"> Mail Msgs (Grouped) </t>
          <tid="513"> Senders (Grouped) </t>
          <tid="523"> Senders Location </t>
          <tid="543"> Instances (Grouped) </t>
          <tid="553"> Servers (Grouped) </t>
     </entity-grouping>
     <fields>
          <tid="100" class="service" > Delivery </t>
          <tid="110" class="statistic" > Msg Size </t>
          <tid="120" class="execution"" > Recipients </t>
     </fields>
</titles-en>

The titles file naming convention (for languages other than English) is as follows: titles_language-code.xml

The following is the basic hierarchy of an XML-based titles file:

  • The root element is named with the language code; has no attributes
  • Add-on AppTier name
  • Entity names in a single variation
  • Entity names in a plural variation
  • Entity group names in a single variation
  • Entity group names in a plural variation
  • Counter names

The following table specifies the properties for the Add-on AppTier name element. The <t> element is a mandatory child element of the root element.

Table 29 Add-on AppTier name element properties

t Atribute NameDescription
idThe value is the same as the value for the attribute tid element <application> in the ETD file.

The text value for the <t> element, under the root element, is the Add-on AppTier name.

All elements under the root element have the same basic hierarchy; multiple <t> sub-elements, each specifying the name of one entity or counter. All <t> sub-elements have one attribute named "id" with a value that connects the ETD file entity or counter to its name.

<t> sub-element properties vary under the following elements:

  • <entity> element
  • <entity-single> element
  • <entity-grouping> element
  • <entity-grouping-single> element

The following table specifies <t> sub-element properties for various elements.

Table 30 Sub-element properties for <t> under various elements

t Attribute NameDescription
id

Under the <entity> element, the value is the same as the <entity> element's attribute plural-tid value for the relevant entity from the ETD file.

Under the <entity-single> element, the value is the same as the relevant <entity> element's attribute tid from the ETD file.

Under the <entity-grouping> element, the value is the same as the relevant <entity> element's attribute plural-grouping-tid from the ETD file.

Under the <entity-grouping-single> element, the value is the same as the relevant <entity> element's attribute grouping-tid from the ETD file.

The text value for the <t> element is the entity name as it should be displayed by Precise products. The following table specifies the properties for <t> sub-elements under the <fields> element.

Table 31 Sub-element properties for <t> under the <fields> element

t Attribute NameDescription
idThe value is the same as the <counter> element's attribute tid value for the relevant counter from the ETD file.
ClassThe value is the same as the <data> sub-element's attribute class for the relevant counter element <counter> from the ETD file.

The text value for the <t> element is the counter name as it should be displayed by Precise products.


IDERA |  Products | Purchase | Support |  Community |  Resources |  About Us  | Legal