Add-on AppTier installation package definitions

This section includes the following topics:

Add-on AppTier installation package descriptor file
Add-on AppTier installation package contents
ETD file
About the titles file or files

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

Element

Description

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

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 Types	Description
major	For documentation of the Add-on AppTier installation package version.
minor	For 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 Name	Description
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 Name	Description
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 Name

Description

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 Name	Description
eid	If 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 Name	Attributes
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-time

Description

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 Name	Description
zoom-displays	This 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 Name	Description
performance	This 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 Name

Description

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 Name	Description
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 Name

Description

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 Name	Description
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 Element

Description

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 Element	Description
filter	This 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 Name

Description

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 Element	Description
service-time	This 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 Element

Description

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 Name	Description
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 Name	Description
color	Specifies the color code for Insight bar graphs. Value: Figure A-1 The value is the sequential number before the bracket. Mandatory: Yes
colorRGB	Specifies the color code for Report Manager reports. Value: Figure A-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.

Format	GUI Definition	Description
Duration	sum-format: HH:MI:SS avg-format: HH:MI:SS.TTT	Time counter (format for Service-time classification)
int Count	number	Integer counter, big numbers, display as K/M/G.
float Count	numberFloat	Execution classified counter must have sum-format="number" and avg-format="". Statistical classified counters have number, numberFloat, or byteFloat.
Bytes	byteFloat	Bytes; 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 Name	Description
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 Element

Description

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 Name	Description
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 Name	Description
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 Field	Description
timestamp	The 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 Element	Description
agent-installer-params	This 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 Name	Description
id	The 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 Name

Description

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 Name	Description
id	The value is the same as the <counter> element's attribute tid value for the relevant counter from the ETD file.
Class	The 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.

Content

Space Tools

Add-on AppTier installation package descriptor file

Add-on AppTier installation package descriptor file example

Add-on AppTier installation package contents

ETD file

ETD file example

About ETD file definitions

About ETD file application-level entities

About ETD file entities

About etd file counters

About the titles file or files