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 A-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
<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 A-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 A-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 A-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 A-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 A-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 A-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.
NOTE: 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 A-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 A-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 A-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 A-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 A-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
Table A-12 Entity element positioned under the entities element
Entity attribute name Description
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 A-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 A-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
NOTE: 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.
Table A-14 Data element positioned under the entity element
Data attribute name Description
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 A-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 A-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 A-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 A-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 A-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 A-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 A-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 on page 37
NOTE: The value is the sequential number before the bracket. Mandatory: Yes
colorRGB Specifies the color code for Report Manager reports. Value: Figure A-1 on page 37
NOTE: 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.
NOTE Ignore the diagonal lines in some of the color boxes.
Figure A-1 Color code table
The following table specifies counter display formats for Display sub-elements positioned under the counter sub-element.
Table A-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 A-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
Note: 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 A-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 A-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 A-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 A-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 A-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.
NOTE 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 A-29 Add-on AppTier name element properties
t attribute 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 A-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 A-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.