Working with the Dynamic Template Designer > Using Methods in Dynamic Templates
  
Version 10.2.01P10
Using Methods in Dynamic Templates
Methods enable special processing to be incorporated into a Dynamic Template. This mechanism enables modular programming, where processing, such as a sub-query, can be defined once and then used in many Dynamic Templates. A Method can take parameters, perform an action, such as a complex calculation, and then return a value. For example, for the job enterprise object, a method can be used to derive the details about the last full backup: client ID, finish date, and job ID.
Methods have the following advantages:
• Modular: Create small, modular pieces of code to query specific data. Combine several methods in one Dynamic Template.
• Re-usable: Create SQL code that can be used in many Dynamic Templates. Simply drag-and-drop methods into a Dynamic Template.
• Easier to Maintain: Use similar logic in multiple templates. Modifications to a method then get applied to all relevant templates.
• More Filter Parameters: More tokens, selected at run time, can be passed into methods (compared to SQL templates). Example: client list.
This advanced feature requires experience in SQL (Structured Query Language) query development, similar to queries written in the SQL Template Designer. Methods can be used only in report templates that have been created using the Dynamic Template Designer.
APTARE IT Analytics provides a set of pre-defined system methods that can be used to incorporate complex processing into report templates. Administrators with SQL knowledge can create additional methods. When an administrator creates a method, it is available only to users within the same APTARE IT Analytics Domain.
For a complete, current list of pre-defined methods available in the Portal, go to
Tools > Templates > Method Designer.
See the following sections for Method details:
• Overview of Method Creation
• System Methods
• Viewing Methods
• Adding or Editing Methods
• Tokens for Methods
• Exception Tables for a Method’s Join Clause
• Validate and Save a Method
• Delete a Method
Overview of Method Creation
Action
Description
View the list of system and user-defined methods that have already been created. Only user-defined methods can be edited.
Several components within a method require configuration:
• Name - User-defined name for the method.
• Short Name - Unique name for the method.
• Short Description - Displayed in the Method View pane.
• Long Description - Provides supplementary details.
• With Clause - (Optional) WITH clause for the query.
• Query - The SQL query to extract data from the database.
• Join Clause - (Optional) JOIN clause to use multiple tables.
• Fields - Select fields that will make the method available in report templates.
System Methods
The following methods are packaged with the APTARE IT Analytics system, for use in the Dynamic Template Designer.
System Method
Vendor Product
Description
Backup Manager Methods: Job Enterprise Object
Backup Window
All Supported Backup Products
Returns the start and finish dates in a backup window.
Client Last Backup Job Info
All Supported Backup Products
Returns the finish date and the corresponding job IDs of the most recent full or incremental backup jobs that are in a successful or partial state. The data returned is per client. This is a stand-alone function and cannot be used in combination with other objects or functions.
CommVault Backup Copy Info
CommVault Simpana
Returns the minimum Backup Copy Identifier for a given CommVault Simpana job.
Commvault Job Attempts
CommVault Simpana
Returns Simpana backup jobs and try count for a client list for CommVault Simpana jobs.
CommVault Running and Queued Job Count
CommVault Simpana
Returns the count of CommVault Simpana backup jobs that are in the running state in the last 90 days. The counts returned are per server.
Data Domain Last Backup Job Info
Data Domain
Returns the details for Data Domain backup jobs. The data returned is per client and logical storage unit.
Disk and Tape Usage Summary
All Supported Backup Products
 
For the most recent successful or partial job, this method returns the finish date, corresponding job ID, number of kilobytes saved in tape media, number of kilobytes saved in disk media, number of files saved in tape media and number of kilobytes saved in disk media. The data returned is per server, client, product type and job type.
Failed Backup Job Detail
All Supported Backup Products
 
For the failed backup jobs within the selected, required time period, this method returns the following data on a per-client basis: client ID, along with its corresponding job ID, the count of failed backups, and the date of the last failed backup job.
Failed Full Backup Job Detail
All Supported Backup Products
 
For the failed full backup jobs within the selected, required time period, this method returns the following data on a per-client basis: client ID, along with its corresponding job ID, the count of failed full backups and the last failed full backup date.
HP DP Session Tape Media List
HP Data Protector
For any HP Data Protector (HP DP) session, this method returns a comma-separated list of the tape media associated with the job. The data will be returned in the following format: id1,name1|id2|name2. The IDs can be used for report drilldowns.
Job Tape Media List
All Supported Backup Products
For any successful or partial job, this method returns a comma-separated list of the tape media associated with the job. This method returns the tape media list if the job’s status is success or warning.
NetBackup Job Error Msg
Veritas NetBackup
Relevant only for NetBackup. It returns the error message if either the job or its parent job is in an error state.
NetBackup Job Tape Media List
Veritas NetBackup
Relevant only for NetBackup. For any successful or partial NetBackup job, this method returns a comma-separated list of the tape media associated with the job. This method returns the tape media list if the job or its parent job’s status is success or warning.
NetBackup Running and Queued Job Count
Veritas NetBackup
Relevant only for NetBackup. The method returns the number of jobs that are in the running state and the number of jobs in the queued state. The counts returned are per backup server.
NetBackup Running Job Info
Veritas NetBackup
Relevant only for NetBackup. The method returns a value of 1 if a NetBackup job is long-running, slow-running, or stalled, based on the policies that are configured for a host group.
NetWorker Running Job Count
EMC NetWorker
Relevant only for EMC NetWorker. The method returns the number of backup jobs in a running state. The data returned is per NetWorker server.
NetWorker Running Job Info
EMC NetWorker
Relevant only for EMC NetWorker. The method returns a value of 1 if a NetWorker job is long-running, slow-running, or stalled, based on the policies that are configured for a host group.
Restore Successful Job Detail
All Supported Backup Products
 
For successful restore jobs within the selected, required time period, this method returns the following data on a per-client basis: client ID, along with its corresponding job ID, the count of successful restore jobs, the number of files restored, and the last successful restore date.
Successful Backup Job Detail
All Supported Backup Products
 
For the successful full and partial backup jobs within the selected, required time period, this method returns the following data on a per-client basis: client ID along with its corresponding job ID, the count of the number of successful backups, the last successful backup date, amount of data (in MB) saved to tape media, and the amount of data (in MB) saved to disk media.
Successful Full Backup Job Detail
All Supported Backup Products
 
For the successful full backup jobs within the selected, required time period, this method returns the following data on a per-client basis: client ID along with its corresponding job ID, the count of the number of successful full backups, the last successful full backup date, amount of data (in MB) saved to tape media, and the amount of data (in MB) saved to disk media.
Backup Manager Methods: Data Domain Enterprise Object
Data Domain Filesystem Capacity
Data Domain
This method returns total and used filesystem capacities at the Data Domain system level.
Requirement: When using this method in a template, the Scope Selector must have the Filesystem Names component selected.
Data Domain Raw Capacity
Data Domain
Returns raw capacities at the Data Domain system level. Use this method to include the total raw capacity in a report template.
Data Domain Tape Capacity
Data Domain
Returns tape capacities at the Data Domain system level. Use this method in a report template to display the total tape capacity, as well as the total used tape capacity.
Data Domain VTL Count
Data Domain
Returns the number of virtual tape libraries (VTLs) at the Data Domain system level. Use this method to include a VTL count in a Data Domain report template.
Capacity Manager Methods: Array Enterprise Object
Array Site Disk Info
IBM
Relevant only for IBM Arrays. For each Array Site, the method returns aggregated information from the physical disk.
Data Mover CPU and Memory Usage
EMC VNX (Celerra)
Returns data only for EMC VNX (Celerra) arrays: Peak CPU Usage Percentage and Peak Memory Usage Percentage for the Movers for the specified arrays.
LUN Array Group List
All Arrays
Returns a comma-separated Array Group list for each logical unit.
LUN Array Port WWN List
All Arrays
 
Returns a comma-separated Array Port WWN list of all logical units.
Top 10 Tiers Chargeback Capacity
All Arrays
 
Lists the chargeback capacity per array in kilobytes and the policy name for the top 10 chargeback policies defined in the system.
File Analytics Methods: Host Enterprise Object
Analytics Host Summary
File Analytics
Lists a capacity summary for hosts from which file data has been collected. Use this method to get an overview of how devices and volumes are being used, including an indicator of how much is duplicated.
Virtualization Manager Methods: Host Enterprise Object
VM CPU Performance Detail
Virtualization Manager
This method returns details about VM CPU Performance, based on the time period or dates selected in the report's scope selector. The VM CPU Performance Summary enables a Storage Administrator to have an at-a-glance look at CPU I/O performance statistics.
VM Disk Performance Detail
Virtualization Manager
This method returns details about VM Disk Performance, based on the time period or dates selected in the report's scope selector. The VM Disk Performance details enable a Storage Administrator to have an at-a-glance look at I/O performance statistics for disks.
VM Guest Detail
Virtualization Manager
This method returns details about VM Guests. Use this report to find the largest Virtual Machines. This report lists virtual guests/hosts with usage and status information. NOTE: VMTools must be installed to enable collection of the IP address, Host name, mount points, and guest operating system of the VM.
VM Memory Performance Detail
Virtualization Manager
This method returns details about VM Memory Performance, based on the time period or dates selected in the report's scope selector. The VM Memory Performance Summary enables a Storage Administrator to have an at-a-glance look at memory I/O performance statistics,
VM Server Detail
Virtualization Manager
Use this report to view the list of Virtual Machine Servers, with access to reports that provide details to help you determine what is using the space on a datastore. This report lists ESX servers, one line item for each physical server, with usage and status information.
Fabric Manager Methods: Host Enterprise Object
Host Zones and Hops Details
Fabric Manager
Returns the total number of zones and hops for each host within a fabric.
Switch and Fabric Name List Details
Fabric Manager
Returns a comma-separated list of the switch and fabric names associated with a host.
Capacity Manager Methods: Host Enterprise Object
Filesystem Summary
Capacity Manager
Use this method to list file system capacity and the most/least used file systems.
Hosts At Risk Details
Capacity Manager
Identifies hosts that require your immediate attention. Hosts at risk are determined by evaluating current and projected usage.
Host Utilization Details
Capacity Manager
Use this method to get an overview of host utilization to determine if there is contention for storage.
Over Provisioned Host Details
Capacity Manager
This method returns details about over-provisioned hosts, based on the time period or dates selected in the report's scope selector.
Stand-Alone Methods
• Some pre-defined methods are stand-alone methods—that is, they cannot be combined with fields or methods that are not in the stand-alone method. These stand-alone methods typically contain complex processing that falls outside of the scope of basic Dynamic Template Designer functionality. If you use fields from a stand-alone method in a Dynamic Template, no other methods or fields can be added to the template.
• A stand-alone method enables you to build a SQL query that can be used in a Dynamic Template; therefore, SQL knowledge is required to author a stand-alone method.
• Stand-alone methods are not associated with an enterprise object, but with specific products, such as backup products.
• To determine if a pre-defined method is a stand-alone method, view/edit the method and note that the JOIN clause is null.
• For Line Charts, if the template uses a stand-alone method, the Top/Bottom scope selector component is not supported.
Viewing Methods
Methods, for use in the Dynamic Template Designer, are listed in the Methods View panel. See Using Methods in Dynamic Templates.
To access methods, take the following steps:
1. In the Portal, select Tools > Templates > Method Designer
The methods view panel lists existing methods, with details about each.
Method Name
This name is provided by the author of the method.
Product
The APTARE IT Analytics product, such as Capacity Manager or Backup Manager.
Subsystem
Some methods are specific to the type of data collected from a particular subsystem, such as a backup product; others are available for all systems for the APTARE IT Analytics product.
Description
Description of the value and use case for the method.
Internal Method Name
This unique, internal name is created by the Dynamic Template Designer. Use this name if you are creating or editing a method that has a query that needs a WITH or JOIN clause. During query validation, you may see this name listed in error messages.
Last Modified
The date the method was created.
2. Buttons at the top of the Methods View panel enable the following actions, depending on which method you select: Add, Delete, Details, and Edit. These same options are available when you right-click in the browser window. System Methods, provided as part of the APTARE IT Analytics software, cannot be modified or deleted. See also, User-Defined Methods and System Methods.
Adding or Editing Methods
Methods that can be used in report templates are created with the Dynamic Template Designer. These methods are listed in the Methods View panel. This list includes both system methods and user-defined methods.
User-Defined Methods
For an example of a user-defined method, see Example of Using a Method to Create a Sparkline Chart in a Dynamic Template.
Only user-defined methods can be edited or deleted. When you select a user-defined method in the Methods View panel, at the top of the Methods View pane, you’ll see the following buttons that enable updates.
A method cannot be edited under the following circumstances:
• The fields in the method are in use in a report template.
• A table used in the Join clause is not relevant for the enterprise object.
Within the Method Designer window, the following buttons enable functionality that is available only for user-defined methods. Note that System Methods will have certain buttons disabled, as described in System Methods.
• Validate Query - Validates valid syntax only for the query and the With clause, if used.
• Save - Before saving, the query is validated. See Validate and Save a Method.
• Save As - Enables a copy and save function so that you can clone and modify methods.
• Cancel - Ignores any changes that have been made since the last save.
• Help - Accesses the context-sensitive help for methods, with details that can assist in method creation.
System Methods
System methods shipped with APTARE IT Analytics cannot be edited or deleted. When you select a system method in the Methods view panel, at the top of the Methods view pane, you’ll see the following available buttons.
Within the Method Designer, the following buttons are available only for user-defined methods.
• Validate Query and Save are disabled for System Methods.
• Save As - Clone and modify system methods to take advantage of factory-shipped functionality.
• Cancel - Dismisses the dialog window.
• Help - Accesses the context-sensitive help for methods, with details that can assist in method creation.
Accessing Methods
1. In the Portal, select Tools > Templates > Method Designer.
2. To Add a Method, click Add at the top of the view panel to launch the Method Designer window.
3. To Edit a Method, double-click a method or select a method and click Edit.
4. In the Method Designer, define and edit the following method components.
Name
This user-defined name for the method, limited to 100 characters, must be unique.
Short Name
This user-defined, case-insensitive name must be unique, with the following constraints:
• Limited to up to 23 characters.
• Cannot begin with a number.
• Cannot contain special characters or spaces.
Use this name when defining a WITH or JOIN clause. During query validation, you may see this name listed in error messages.
Short Description
This description, limited to 200 characters, is displayed in the methods view panel.
Long Description
The long description is limited to 4,000 characters. Use this description to provide essential details, such as prerequisites, which will aid anyone wanting to customize the method.
With Clause
Use the SQL WITH clause to assign a name to a subquery block so that it can be easily referenced in the query. The WITH clause must follow these rules:
• WITH clause aliases must be unique across all the functions used in a report template; therefore, create an alias in the following format:
<function_name><number>

Example: BackupWindow1
• Cannot contain Oracle reserved words that can alter data in the database; for example, DELETE, UPDATE, or INSERT.
Query
Define the SQL query with SELECT statements to return data from the database.
• Cannot contain Oracle reserved words that can alter data in the database; for example, DELETE, UPDATE, or INSERT.
• All columns in the SELECT clause must be aliased; for example,
SELECT decode(client_id,1,'121212',2,'2323',5) A
FROM apt_v_job
• The function, collectString, can be used in the Method Designer to concatenate distinct values. The Oracle function, aptStringConcat with DISTINCT or UNIQUE, cannot be used to concatenate values in a method, even though the method will validate and save. When that method is used in a report template, it will fail.
Join Clause
Use the SQL JOIN clause to combine results from the Method with the results of the template. The JOIN clause must follow these rules:
• The JOIN conditions should use relevant enterprise object tables only. See the Dynamic Template Designer to view the table associated with a field.
• Only the equal sign (=) is supported.
• The method’s field should always be defined on the left side of the equal sign (=) .
• SQL functions, such as UPPER, DECODE, or LOWER cannot be used in a JOIN clause.
• Certain database tables cannot be used in JOIN clauses. See Exception Tables for a Method’s Join Clause.
5. Click Validate Query at the bottom of the Method Designer window to validate the query.
Validate Query only validates the With and Query components. If an error exists, both components will be bordered in red, indicating that the validation has failed. In addition, after validation, the Fields pane will be populated with the fields (database columns) that are used in the query.
6. At the right of the Method Designer window, the Fields and Resources buttons enable the following configurations and capabilities.
Fields
When adding a Method, the Fields pane will be populated only after the query has been successfully validated.
Check the boxes to select the fields that will be available in the Dynamic Template Designer so that the method can be included in a report template.
Several entries are required for each field before the method can be successfully saved.
• Label: User-supplied. This label is what will appear in the Report Template.
• Field Name: Pre-defined by the Method Designer.
• Short Description: User-supplied.
• Long Description: User-supplied.
Resources
• Enterprise Object: Select an enterprise object. This selection makes a method available to only templates created for that object. It also drives the list of tokens that are available for use in a query to enable variable substitution at report run time.
• Product: Select a specific vendor product (subsystem) for the enterprise object; for example, for a storage array enterprise object, EMC VNX (Celerra).
• Tokens: These tokens can be used in a query to enable variable substitution at run time. Place your cursor at the insertion point in the query and double-click the token. See Tokens for Methods. The list of relevant tokens is driven by the selected Product Group.
7. Click Save. See Validate and Save a Method and User-Defined Methods for the rules that are being checked before saving the method.
Tokens for Methods
To access the pre-defined tokens provided for certain product groups, take the following steps:
1. In the Portal, select Tools > Templates > Method Designer.
2. To Add a Method, click Add at the top of the view panel to launch the Method Designer window.
3. To Edit a Method, double-click a method or select a method and click Edit at the top of the view panel to launch the Method Designer window.
4. In the Method Designer, click Resource at the right of the window.
5. Select a Product Group to view the relevant tokens.
Product Group
Token Name
Backup Manager
${backupWindow}
Backup Manager
${endDate}
Backup Manager
${startDate}
Backup Manager
${jobList}
Backup Manager
${hosts}
Backup Manager
${user}
Capacity Manager
${domainList}
Capacity Manager
${endDate}
Capacity Manager
${startDate}
Capacity Manager
${arrayList}
Capacity Manager
${user}
Capacity Manager
${spArrayList}
Exception Tables for a Method’s Join Clause
The following tables cannot be used in a JOIN clause of a method.
Enterprise Object
Table Name
Job
apt_server_instance
Job
apt_host
Job
apt_leg_volume_pool
Job
ptl_volume_pool
Job
apt_leg_cr_group
Job
ptl_nbu_storage_unit
Job
ptl_nbu_retention_level
Job
apt_tsm_stgpool_contents
Job
apt_attr_host
Job
apt_host_detail
Job
apt_host_info
Array
aps_emc_sym_storage_pool
Array
aps_vnx_storage_pool
Validate and Save a Method
Once you have configured all the mandatory elements of a method, you can save the method.
• Save - When saving, the method is validated. This button is disabled for System Methods.
• Save As - “Save As” also validates the method. This option enables a copy-and-save capability so that you can clone and modify methods. This is especially useful for tailoring System Methods to take advantage of factory-shipped, advanced functionality.
Method Validation
When a method is saved, the following checks are made.
• All mandatory elements have values: Name, Short Name, Short Description, Long Description, and Query
• Short Name is unique
• Query validates
• At least one field is checked
• All checked fields have been filled in: Label, Short Description, Long Description
If any of the above validations have issues, the relevant method pane(s) will be flagged with a red border. When possible, a red information icon will display, which you can click for additional information.
Delete a Method
APTARE IT Analytics ships with system methods that cannot be deleted. Only user-defined methods can be deleted. And, a method can be deleted only if it is not being used by a report template.
To delete a method, take the following steps:
1. In the Portal, select Tools > Templates > Method Designer.
The methods view panel lists existing methods.
2. Click on a method to select it.
3. Click the Delete button at the top of the methods view pane.
If the method is currently being used by a report template, a pop-up window will notify you and prevent you from deleting the method.