TBSM UI Data Provider: "Tree Template" Datasets Version 1.1 July 28, 2014 Notices References in content to IBM products, software, programs, services or associated technologies do not imply that they will be available in all countries in which IBM operates. Content, including any plans contained in content, may change at any time at IBM's sole discretion, based on market opportunities or other factors, and is not intended to be a commitment to future content, including product or feature availability, in any way. Statements regarding IBM's future direction or intent are subject to change or withdrawal without notice and represent goals and objectives only. Please refer to the developerWorks terms of use for more information. "Tree Template" Datasets Version 1.1 Contents 1 Introduction ............................................................................................................................................................... 4 1.1 2 3 1.1.1 Exposing Legacy “Tree Template” Data......................................................................................................... 4 1.1.2 DASH Visualization of “Tree Template” Data ................................................................................................ 4 1.1.3 DASH Integration Points ................................................................................................................................ 4 A Quick Example ........................................................................................................................................................ 5 2.1 “Day Trader” Tree Template............................................................................................................................... 5 2.2 Visualized in Legacy TBSM “Service Tree”.......................................................................................................... 6 2.3 Visualized in DASH “Tree Table” Widget ............................................................................................................ 6 2.4 Visualized in DASH “Topology” Widget .............................................................................................................. 7 TBSM UI Data Provider Changes ................................................................................................................................ 8 3.1 Automatically Excluded “Tree Templates”.................................................................................................... 8 3.1.2 Responding to External Changes of the “Tree Template” Artifacts .............................................................. 8 The "<TreeTemplate>" Dataset .......................................................................................................................... 9 3.2.1 Dataset Parameters....................................................................................................................................... 9 3.2.2 Dataset Columns ......................................................................................................................................... 10 3.2.3 DASH Limitations / Issues ............................................................................................................................ 12 3.2.4 Dataset Context Menus............................................................................................................................... 12 DASH Visualization ................................................................................................................................................... 13 4.1 “Tree Table” Widget ......................................................................................................................................... 13 4.1.1 Toolbar actions ............................................................................................................................................ 13 4.1.2 Additional Capabilities................................................................................................................................. 13 4.1.3 Advanced Capabilities ................................................................................................................................. 13 4.1.4 Limitations ................................................................................................................................................... 13 4.1.5 Widget Configuration .................................................................................................................................. 14 4.2 “Topology” Widget ........................................................................................................................................... 15 4.2.1 Additional Capability ................................................................................................................................... 15 4.2.2 Multiple Status Icons on Nodes................................................................................................................... 15 4.3 5 The “TBSM Tree Templates” Data Source .......................................................................................................... 8 3.1.1 3.2 4 30,000 Foot Plan Summary................................................................................................................................. 4 Scalar Widgets .................................................................................................................................................. 15 Companion Collection of Artifacts ........................................................................................................................... 16 5.1 Using these Artifacts on Your TBSM................................................................................................................. 16 5.1.1 Prerequisite ................................................................................................................................................. 16 5.1.2 Unpacking the ZIP........................................................................................................................................ 16 A New Feature in TBSM 6.1.1 FP001 Page 2 of 16 7/28/2014 "Tree Template" Datasets Version 1.1 5.1.3 Customizing for Your TBSM and DASH ........................................................................................................ 16 5.1.4 Making the Artifacts .................................................................................................................................... 16 5.1.5 Deploying the Artifacts to Your TBSM......................................................................................................... 16 A New Feature in TBSM 6.1.1 FP001 Page 3 of 16 7/28/2014 "Tree Template" Datasets Version 1.1 1 Introduction This document describes how TBSM 6.1.1 FP001 has exposed legacy TBSM “tree template” data as UI data provider datasets. This provides a Service Tree-like presence in DASH for the first time. 1.1 30,000 Foot Plan Summary 1.1.1 Exposing Legacy “Tree Template” Data Additional TBSM datasets now contain the data that’s currently seen on a customized legacy Service Tree. Each dataset corresponds to a “tree template” that’s maintained using the Tree Template Editor [found at Administration > Service Configuration > Service Navigation > Services]. Each dataset contains relationships (vs. being a flat dataset). In that regard, it’s like the TBSM Topology dataset. 1.1.2 DASH Visualization of “Tree Template” Data 1.1.2.1 Primary Visualization Due to the hierarchical nature of this dataset and its typical legacy use, it’s expected that the Tree Table widget will primarily be used to visualize these new datasets. It provides the closest visual proximity to the legacy Service Tree. Refer to the screen capture on page 6. 1.1.2.2 Secondary Visualizations Alternately, the Topology widget can be used. Refer to the screen capture on page 7. The other collection widgets (List or Table) can be used to display these datasets. This does result in the loss of the defined hierarchical relationships. Since the dataset can be configured to return just one service, it can also be used by the scalar widgets. This allows a great deal of flexibility in visualizing service data when there is no intersection of the template(s). Many options are now possible based on the imaginative ways that a page designer can construct a tree template. 1.1.3 DASH Integration Points The new datasets provide the same TBSM/DASH integration points available with all of the other TBSM datasets: events, page launches, dynamic updates, context menus, etc. The remainder of this document provides more detail about the datasets including new capabilities and/or limitations compared to the legacy TBSM implementation. A New Feature in TBSM 6.1.1 FP001 Page 4 of 16 7/28/2014 "Tree Template" Datasets Version 1.1 2 A Quick Example 2.1 The “Day Trader” Tree Template The following tree template is based on the standard “Day Trader” sample service model. A ZIP file containing all of the TBSM artifacts discussed in this document is available to get you up and running even faster. For more details, refer to chapter 5 Companion Collection of Artifacts on page 16. A New Feature in TBSM 6.1.1 FP001 Page 5 of 16 7/28/2014 "Tree Template" Datasets Version 1.1 2.2 Visualized in Legacy TBSM “Service Tree” 2.3 Visualized in DASH “Tree Table” Widget A New Feature in TBSM 6.1.1 FP001 Page 6 of 16 7/28/2014 "Tree Template" Datasets Version 1.1 2.4 Visualized in DASH “Topology” Widget A New Feature in TBSM 6.1.1 FP001 Page 7 of 16 7/28/2014 "Tree Template" Datasets Version 1.1 3 TBSM UI Data Provider Changes 3.1 The “TBSM Tree Templates” Data Source This new data source provides a dataset for the tree templates currently defined in TBSM (whether provided out-ofthe-box by TBSM or created by customers). 3.1.1 Automatically Excluded “Tree Templates” These TBSM provided tree templates are automatically excluded: 1. DatasetConfig 2. ServiceComponentRepository 3. ServiceTemplate The ServiceInstance tree template is not excluded but it is not very useful since all of its columns are automatically excluded (due to its exclusive use of “built-in” attributes; this is discussed in an upcoming section). Modification of this tree template is not recommended, so this dataset would typically never be used. 3.1.2 Responding to External Changes of the “Tree Template” Artifacts When a tree template artifact is externally created, updated, or removed, the rad_reinitcanvas command must be run so that the running TBSM dashboard server re-loads all of the available artifacts (which include tree templates). The tree template data source always accesses the current set of tree templates (vs. caching the artifacts available when the server started) to insure that the datasets accurately reflect the current artifacts. A New Feature in TBSM 6.1.1 FP001 Page 8 of 16 7/28/2014 "Tree Template" Datasets Version 1.1 3.2 The "<TreeTemplate>" Dataset This dataset operates much like the standard TBSM topology dataset: services are gathered from a root service by following the child relationship (i.e. levels down). The major difference is that these datasets contains additional service data based on the tree template’s definition. In summary, we have a topology dataset extended to include columns externally defined by the tree template. All tree template datasets have the same parameters and follow the same pattern for its columns. 3.2.1 Dataset Parameters The following parameters are supported: P-1 P-2 P-3 Parameters Text Seen on the UI Description / Notes Data Examples TBSM Service P-1: The specific service that will become the tree root node <service> Required? Yes (but not enforced by the UI) Levels Down Required? no As with all TBSM datasets, the user can use Add… to locate any desired service. It is possible to specify multiple root services. While not recommended, leaving this parameter blank will simply result in an empty dataset. P-2: The number of levels to recurse from the root node to gather children Range: 0 – 15 Default: 4 By supporting a Levels Down value of zero, the resulting dataset will contain just the single TBSM Service and thus is usable by the scalar widgets Of course, there is a direct relationship between this parameter and performance. The dataset is built completely when it’s initially requested (i.e. all branches and leaf nodes determined), so best practice is to keep this value as low as possible. Additional Status Icons P-3: The number of additional status icons to display on nodes. Required? no This parameter is only applicable when the Topology widget is used for visualization. It is ignored for all other widgets. Range: 0 – 5 Default: 0 See 4.2.2 Multiple Status Icons on Nodes on page 15 for more details A New Feature in TBSM 6.1.1 FP001 Page 9 of 16 7/28/2014 "Tree Template" Datasets Version 1.1 3.2.2 Dataset Columns Basic set of TBSM data Columns The standard TBSM columns [service instance name, display name, TBSM status, primaryTag, description] are always included “Tree Template” defined columns One for every column defined by the tree template (i.e. the tree template defines the meta data for the dataset) The Tree Template Editor defines the column layout along with the mappings of how data is displayed in the column’s cells. It will continue to define the columns available for visualization as well as their default order. The resulting tree template can be displayed in legacy TBSM and/or a DASH widget. Exception to the Rule Any column that maps to one of these built-in attributes is automatically excluded: 1. serviceStatusImage 2. slaStatusImage 3. rawEventsImage A New Feature in TBSM 6.1.1 FP001 Note: substitute the base TBSM Status column instead Page 10 of 16 7/28/2014 "Tree Template" Datasets Version 1.1 3.2.2.1 Supported Column Data Types A dataset must define the one data type that will be contained in each column as part of the contract between a dataset and the widget visualizing its data. So each tree template column will be assigned one of these data types. Data Type Tree Template Column String Used if: 1. each of the template rules defined for this column is a text rule 2. there is a mix of template rule data types; that is, a combination of text, numeric, and/or status Used if each template rule defined for this column is a numeric rule Used if each template rule defined for this column is a status rule Double Status This assignment is made by analyzing the rule mappings defined for each service template referenced. Below, the templates define a mixture of attribute data types. @Status is a Status data type, @CityID is a String data type, while all other attributes are Double data type. Both templates map Double attributes to the Buy and Sell columns. A New Feature in TBSM 6.1.1 FP001 Page 11 of 16 7/28/2014 "Tree Template" Datasets Version 1.1 3.2.3 DASH Limitations / Issues These are some differences in the DASH implementation compared to the legacy TBSM Service Tree… 3.2.3.1 No Customization of Cell Content via the “GetTreeColumnValue” Policy Often, TBSM customers use this dedicated policy to transform the normal cell value and/or create unique HTML rendering within a cell. This enables the display of special images, hyperlinks, text formatting/colorization, etc in the legacy Service Tree. No DASH widget allows a dataset column to contain HTML coding, so this policy will not be driven for these datasets. Only the standard data type rendering will be available (on a column basis). Note: A DASH Request For Enhancement has been created to get this limitation addressed 3.2.3.2 Tree Template Changes Can Affect Saved Dash Pages The tree template defines the data columns available in this dataset. The column heading, say “BasePrice”, is internally used to identify the column. 3.2.3.2.1 Column Heading Changed The column identify is saved as part of each page where the dataset is used. If column heading is simply changed to “Base Price”, all saved pages that referenced “BasePrice” will no longer render properly. This applies to all widgets except Topology. To correct this, each widget based on the dataset that explicitly referenced the column will need to be edited and have the column re-configured. Examples include when the column was: 1. used as the value of a gauge widget 2. displayed in a List, Table, or Tree Table Note: this same issue applies to the Template-based datasets too if a rule is renamed… 3.2.3.2.2 Columns Re-ordered If the column order is changed in the Tree Template Editor, this does not result in a change to any column’s identity. So no saved pages are affected. 3.2.4 Dataset Context Menus The context menus for TBSM’s datasets are defined in the DatasetConfig.xml artifact. To get custom context menu items displayed on a specific tree template dataset, define a new <templateTreeMapping> element whose primaryTemplateName attribute is the tree template name. Tto define context menus for the “DayTrader” tree template, you would add the following element to DatasetConfig.xml: <templateTreeMapping primaryTemplateName="DayTrader"> <actionMapping clickType="~popupMenu" actionName="<action reference>"/> … </templateTreeMapping> Due to the constraint of this XML artifact, there is a loss of function compared to the legacy TBSM implementation. The granularity of defining unique menu items on a service template basis is no longer possible… “Advanced Topics” reference: the Dataset Context Menus document covers the complete context menu process A New Feature in TBSM 6.1.1 FP001 Page 12 of 16 7/28/2014 "Tree Template" Datasets Version 1.1 4 DASH Visualization 4.1 “Tree Table” Widget The figure below shows the visualization of a tree template dataset. TT-1 Note: the cells displaying a dash (-) indicate no value defined per IBM Usability Guidelines… 4.1.1 Toolbar actions • TT-1 filtering • can be used to find services that are currently in the dataset being visualized • Unfortunately, Advanced Filtering is not available… 4.1.2 • • • Additional Capabilities The standard TBSM data columns are always available (despite not being part of the tree template) The page designer can locally re-order and/or exclude columns provided by the tree template Multiple root nodes can be defined 4.1.3 Advanced Capabilities If the dataset will be viewed in multiple languages, column name translations can be provided using the external scorecard_labels.properties file along with its various language translations (i.e. scorecard_labels_fr.properties, etc). Details can be found in this Knowledge Center page: http://www-01.ibm.com/support/knowledgecenter/SSSPFK_6.1.1/com.ibm.tivoli.itbsm.doc_6.1.1/bsma/10/bsm_tbsm_servtree_port.html 4.1.4 • Limitations The widget does not properly support a service (node) being in the tree at multiple locations. The tree initially renders OK, but there are subsequent usability issues. The current work-around is to use the Topology widget A New Feature in TBSM 6.1.1 FP001 Page 13 of 16 7/28/2014 "Tree Template" Datasets Version 1.1 4.1.5 Widget Configuration 4.1.5.1 Visualization Attributes This is the Quick Edit panel used to configure the widget’s visualization attributes QE-1 QE-2 QE-3 . Notes: • • • • QE-1 provides the page designer additional control over the dataset’s visualized columns, independently of what the tree template has defined. Column(s) can be hidden and/or re-ordered. Also note that the standard base TBSM dataset columns are available QE-2 must be set to Single for proper inter-page context sharing via events (along with configuring the widget to publish NodeClickedOn events) QE-3 allows automatic saving of the operator’s direct manipulation of the columns (recommended) The “Enable UI Previews” checkbox is not shown above. If both TBSM and DASH have been configured to support OSLC, then it would be available to enable UI previews from this widget. A New Feature in TBSM 6.1.1 FP001 Page 14 of 16 7/28/2014 "Tree Template" Datasets Version 1.1 4.2 “Topology” Widget 4.2.1 Additional Capability Tree template datasets are the first TBSM datasets that make additional service data available from this widget. This is primarily manifest in the node representing a service, the node’s flyover tooltip and the Properties window. 4.2.2 Multiple Status Icons on Nodes The Additional Status Icons parameter (P-3) allows the page designer to visualize up to 5 additional status icons on nodes. The upper right corner is always the TBSM Status. The additional status icons are placed clockwise around the edge of the node as shown below. The source tree template defines if additional status column(s) are available along with their visualization order. The numbers below correspond to the icons pictured above. 1 2 3 The node tooltip provides a legend of the displayed icons as shown in the tooltip in the previous section. 4.3 Scalar Widgets It is possible to use these datasets with scalar widgets if 1. TBSM Service (P-1) is set to one specific service instance and 2. Levels Down (P-2) is set to zero A tree template can be defined that would use multiple, disjoint service templates to map data into a common set of columns… So when the service context changes, that service’s data would be displayed. A New Feature in TBSM 6.1.1 FP001 Page 15 of 16 7/28/2014 "Tree Template" Datasets Version 1.1 5 Companion Collection of Artifacts A ZIP file containing all of the TBSM artifacts discussed in this document is available to get you up and running even faster: DataProvider-TreeTemplateDatasets_1.1.zip The file does not contain the actual files that were put into the TBSM system as artifacts, but rather a set of template files and an Ant make process. The make process is required to merge values that are specific to your TBSM installations into the template files. Once that’s done, you use the generated script to put the customized artifacts into TBSM. You define your installation specific information in the my-artifact-values.properties. Directory created Description Notes TBSM artifacts created for the tree Set of tree templates that are based on the eDayTrader Samtemplates ple TBSM Service Model provided on the “Advanced Topics” page templates Template files Each template contains data inserts for system specific data automation so reusable on your TBSM system The make process generates these directories: Directory Description automation Generated scripts to put all of the created artifacts into TBSM Notes Includes both Windows and Unix scripts 5.1 Using these Artifacts on Your TBSM 5.1.1 Prerequisite For proper operation of these artifacts, the Sample TBSM Service Model: eDayTrader must be installed. It is available from the TBSM Advanced Topics page. 5.1.2 Unpacking the ZIP Unzip the artifacts file to a convenient directory on the same machine where the TBSM XML Toolkit is installed. \my-artifacts 5.1.3 Customizing for Your TBSM and DASH Edit \my-artifacts\my-artifact-values.properties and update the values to correspond to your TBSM environment. This includes things like user IDs, etc. 5.1.4 Making the Artifacts 1. cd \my-artifacts 2. install on Windows or ./install.sh on Unix 5.1.5 Deploying the Artifacts to Your TBSM 1. cd \my-artifacts\automation 2. put-artifacts on Windows or ./put-artifacts.sh on Unix A New Feature in TBSM 6.1.1 FP001 Page 16 of 16 7/28/2014