Microsoft Dynamics NAV Treemap Business Data Visualization for Microsoft Dynamics NAV 2009 R2 and Microsoft Dynamics NAV 2009 SP1 White Paper The Treemap Business Data Visualization is a RoleTailored client control add-in that provides a unique way to view and analyze business data in Microsoft Dynamics NAV. December 2010
OVERVIEW... 1 BUSINESS DATA VISUALIZATION OVERVIEW... 2 TREEMAP BUSINESS DATA VISUALIZATION... 2 TREEMAP VISUALIZATION COMPONENTS... 4 REDISTRIBUTABLE COMPONENTS... 4 SAMPLES... 4 SOFTWARE LICENSE TERMS - TREEMAP BUSINESS DATA VISUALIZATION.RTF FILE... 4 INSTALLING AND RUNNING THE TREEMAP VISUALIZATION... 5 QUICK INSTALLATION GUIDE... 5 DETAILED INSTALLATION GUIDE... 5 TREEMAP VISUALIZATION FEATURES IN THE DEMO DATABASE... 7 WALKTHROUGH: USING THE TREEMAP VISUALIZATION ON A SALES ORDER PAGE... 9 ADDING THE TREEMAP CONTROL ADD-IN TO THE SALES ORDER PAGE... 10 POPULATING THE TREEMAP CONTROL ADD-IN WITH DATA... 12 IMPLEMENTING FILTERING ON THE TREEMAP VISUALIZATION... 15 REACTING TO EVENTS FROM THE TREEMAP CONTROL ADD-IN... 16 EVENT MESSAGES FROM THE TREEMAP VISUALIZATION CONTROL ADD-IN... 16 TO ADD CODE TO HANDLE EVENT MESSAGES FROM THE TREEMAP CONTROL ADD-IN... 17 NEXT STEPS... 18
OVERVIEW The Treemap Business Data Visualization for Microsoft Dynamics NAV provides a unique view on business data. Its gives insight from different data perspectives and can be used to help identify outliers and actionable items. Combined with histogram-based visual filtering, integration into business logic, and the user interface (UI) of the RoleTailored client, this is a powerful tool for end users. The Treemap visualization is delivered as a RoleTailored client control add-in for Microsoft Dynamics NAV 2009 R2 and Microsoft Dynamics NAV 2009 SP1. It includes a server-side object, a codeunit for data processing, and a sample page. The sample uses the Treemap visualization control in a Treemap analysis place for customers so that you can see how to integrate the visualization into other application scenarios. You can use the Treemap visualization to integrate the visualization into customer projects and your addin solutions. No dedicated granule is required. For details about the license terms, see the Software License Terms - Treemap Business Data Visualization.rtf file. This white paper describes how to use Treemap visualizations in custom application scenarios. The guide starts with a high-level overview and then provides the steps to set it up for customer analysis. It describes the supported user interactions and provides step-by-step information for setting up and installing custom application scenarios. It also describes how to use the visualization add-in. For more information about RoleTailored client control add-ins, see Developing RoleTailored Client Control Add-ins in the MSDN Library. 1
BUSINESS DATA VISUALIZATION OVERVIEW Business data visualizations are characterized by the following five pillars. Picture your business (delivers mental models). Visualizations provide a mental model for business data and data dependencies. This can be characterized by the saying, A picture is worth a thousand words. By seeing a visual representation of data and data dependencies, even non-expert users can more easily understand business data. Understand your business; know state and trends (provides insight). Visualizations are an entry point for understanding the current state of a business and trends. Users can drill down and filter data to provide intuitive, ad hoc analysis. Know how to act (identifies actionable tasks). Users can use business data to find items of interest and outliers that are based on certain objectives or measures. These outliers can be converted into high-priority actionable tasks. Act wisely (provides decision support, problem solvers, and optimization). Problem solvers and optimizers help users decide on a strategy. They can provide suggestions for an action strategy that can lead to an optimal result for one or more objectives. Understand consequences (visualizes consequences before acting). Visualizations help users to understand the impact of actions before they are committed. Visualizers can account for dependencies, predict the outcome of actions, and provide visualizations to users. TREEMAP BUSINESS DATA VISUALIZATION Users look at business data from different perspectives. In a Treemap visualization, a perspective is composed of two measurements, which define the appearance of size and color for each data element. The brain can efficiently process large sets of data based on size and color, which makes the Treemap visualization very effective. The Treemap visualization is complemented with visual filtering on top of a data histogram for each selected measurement. The histogram provides an overview of how many data items appear in the range of values that is defined by the full measurement value range. Users can then use intuitive range filtering to adjust the upper or lower boundary of the range of values from which data objects are visualized. With visual filtering, users can see data items disappear or appear dynamically and transition smoothly in size and color. The brain can follow and keep track of dynamic changes for a large number of visual elements simultaneously, which makes the visualization even more effective. Users can use these visual tools to better understand a set of business objects with the range of values of multiple measurements in one picture. Users can then discover unexpected correspondences and also validate that data follows presumed correspondences. The Treemap visualization also helps identify actionable items and answers to questions such as: Which business data items fall out of typical procedures? Which data items are the most important ones to act on? Where does an action have the most impact? You can frequently answer these questions by looking at outliers in presumed correspondences of measurements for a business situation. These business data items typically do not follow the presumed correspondences and anticipated flow of data. 2
The Treemap visualization provides direct access to relevant UI pages so that users can act on the business data object behind a Treemap visualization field. 3
TREEMAP VISUALIZATION COMPONENTS The installation components are located in the Extras\Treemap Business Data Visualization folder on the Microsoft Dynamics NAV 2009 R2 installation media, from PartnerSource, or from CustomerSource. The Setup TreeMap Visualization.msi file installs the binary components and includes a.fob file with application objects to install in a Microsoft Dynamics NAV database. REDISTRIBUTABLE COMPONENTS Treemap visualization control add-in and language resource assemblies for the RoleTailored client. These files are used to add the Treemap visualization on RoleTailored client pages and can be redistributed to all computers running the RoleTailored client. Language resource assemblies for the following languages are included: Danish (Denmark), Dutch (Netherlands), English (United States), French (France, French (Canada), German (Germany), Italian (Italy), and Spanish (Spain). These files are located in the Add-ins folder of the RoleTailored client installation. By default, this folder is C:\Program Files\Microsoft Dynamics NAV\60\RoleTailored Client\Add-Ins\Treemap Business Data Visualization. Server-side data processing components. The Microsoft.Dynamics.Visualizations.TreeMap.DataBuilder.dll assembly and additional files are used for processing Treemap visualization data on the computer running Microsoft Dynamics NAV Server. This COM object is registered during installation. By default, these files are located in the C:\Program Files\Microsoft Dynamics NAV\60\Treemap Business Data Visualization folder. SAMPLES The TreeMap Visualization 1.1.0.0.fob file imports a codeunit for generic data handling and a sample page to demonstrate the Treemap visualization in an application scenario. By default, these files are located in the C:\Program Files\Microsoft Dynamics NAV\60\Treemap Visualization folder. SOFTWARE LICENSE TERMS - TREEMAP BUSINESS DATA VISUALIZATION.RTF FILE This file contains the terms for using the Treemap visualization. By default, this file is located in the C:\Program Files\Microsoft Dynamics NAV\60\Treemap Business Data Visualization folder. 4
INSTALLING AND RUNNING THE TREEMAP VISUALIZATION QUICK INSTALLATION GUIDE This procedure describes how to install the Treemap visualization components and samples on a single computer running a three-tier installation of Microsoft Dynamics NAV with the demo database. The installation includes the following high-level steps: Run the Setup TreeMap Visualization.msi file to install the components. Import the TreeMap Visualization 1.1.0.0.fob file. Run codeunit 55555 once. Run page 55555 from Page Designer or from an action on another page. DETAILED INSTALLATION GUIDE 1. On the computer with Microsoft Dynamics NAV, run the Setup TreeMap Visualization.msi file. By default, the files on a 32-bit edition of Windows are installed at: C:\Program Files\Microsoft Dynamics NAV\60\Treemap Business Data Visualization\ On a 64-bit edition of Windows, the files are installed at: C:\Program Files (x86)\microsoft Dynamics NAV\60\Treemap Business Data Visualization\ 2. In the Classic client, import the TreeMap Visualization 1.1.0.0.fob file. a. On the Tools menu, click Object Designer. b. On the File menu, click Import. c. Locate the TreeMap Visualization 1.1.0.0.fob file, and then click Open. d. If no conflicts are found, then click Yes to import all objects. e. In the Import Objects dialog box, click OK. The following objects are imported: Codeunit 55555, Treemap Addin This codeunit performs generic data handling for the Treemap visualization and can also be run to register the add-in. Page 55555, Customer Treemap Analysis This sample page uses the Treemap visualization control add-in to display Customer table data. 3. Run codeunit 55555 to register the Treemap add-in in the Client Add-in table. To manually register the Treemap visualization control add-in, open the Client Add-in table, and then add a row that has the following values: Control Add-in Name: TreeMapViz Public Key Token: 31bf3856ad364e35 Version (optional): 1.1.0.0 Note If you set a version number, then you must use 1.1.0.0. Otherwise, leave the field blank. If you use a different version number, then the control add-in will not work on the page. Description (optional): Treemap Business Data Visualization 5
4. To view the Treemap visualization, run page 55555, Customer Treemap Analysis, from Page Designer, or open the following URL: DynamicsNAV:////RunPage?Page=55555. You can also run page 55555 from an action on another page. The following procedure creates an action on page 22, Customer List, which opens page 55555. You promote the action to the Action Pane of the Customer List page, as shown in the following illustration. a. In Object Designer, open page 22, Customer List. b. Add an action that opens page 55555, Customer Treemap Analysis. Set the following properties on the action. Property Value Remarks CaptionML DAN=Treemap-analyse;DEU=Treemap Analyse;ENU=Treemap Analysis;ESP=Análisis de Treemap;FRA=Analyse Treemap;ITA=Analisi Treemap;NLD=Treemapanalyse;FRC=Analyse Treemap Defines a caption for the action in the different languages included with the Treemap visualization installation. Image Segment Assigns an icon called Segment to the action. Promoted Yes Promotes the action to the Action Pane. PromotedCategory Category4 Assigns the action to the fourth category in the Action Pane. PromotedIsBig Yes Assigns a large icon to the action. RunObject Page Customer Treemap analysis Runs page 55555. For information about adding actions the page, see Walkthrough: Adding Actions to a Customer List Page in the MSDN Library. c. To define the language captions for the promoted categories, set the PromotedActionCategoriesML property on the Customer List page to the following value: DAN=Ny,Proces,Rapport,Analyse;DEU=Neu,Vorgang,Bericht,Analyse;ENU=New,Process,Repor t,analysis;esp=nuevo,proceso,informe,análisis;fra=nouveau,processus,état,analyse; ITA=Nuovo,Processo,Report,Analisi;NLD=Nieuw,Proces,Lijst,Analyse;FRC=Nouveau, Processus,Rapport,Analyse For more information about defining promoted action categories, see How to: Define Promoted Action Categories in the MSDN Library. d. Run page 22, Customer List, and then in the Action Pane, click the Treemap Analysis action to run page 55555, Customer Treemap Analysis. 6
TREEMAP VISUALIZATION FEATURES IN THE DEMO DATABASE Page 55555 is a Treemap analysis place for customers. The Treemap visualization replaces the typical list-type representation for customers with the following color and size codes. Color code: Customers with large values of the color measure are displayed in blue, small values are displayed in red, and average values are displayed in gray. Size code: Customers with large values of the size measure are displayed as large rectangles, and small values are displayed as small rectangles. You can try the following interactions to better understand the UI concepts. Select a measure for the Show color for and Show size for fields. Set the focus in one of the dropdown menus, and then use the UP ARROW and DOWN ARROW keys to step through the measures. The visualizations are animated and change when you step through them. Click Customer List, and then click Advanced filter. Add a filter to see the visualization change to show the different set of customers in the dataset. Click a cell in the Treemap visualization and look at the information in the FactBoxes. Then, use the arrow keys to move to other cells in the visualization. When you move to another cell, after a halfsecond delay, the FactBoxes are updated to show the details of the selected cell. Double-click a cell, or click a cell and press ENTER. The Customer card for that customer in the cell opens. Experiment with the visual range filters for the color measure in the upper left of the Treemap and the size measure in the upper right. Integrated histograms and the value legend provide an intuitive filtering experience. 7
Range handles are located at each end of a range. To make a range larger or smaller, drag the handles. To move an entire range, drag the connection between the handles. Double-click the connection between the handles to revert to the full range or to the last reduced range. Customers who are included in the range for one measurement but not the other measurement are shown with a bar with hatched brush fill. These customers are shown in the histogram of the range that they are included in. 8
WALKTHROUGH: USING THE TREEMAP VISUALIZATION ON A SALES ORDER PAGE In the previous procedures, you registered the Treemap visualization control add-in in the database and enabled the sample page that runs the Treemap visualization on page 22, Customer List. In this walkthrough, you will create a Treemap visualization for a Sales Orders list page that will look similar to the following figure. The Treemap visualization extracts data from the Sales Header table. When you click a cell in the Treemap visualization, the FactBoxes on the right side update with the corresponding customer data for the sales order. When you double-click a cell in the Treemap visualization, the Sales Order card page for the corresponding sales order opens. This walkthrough illustrates the following tasks: Adding a Treemap control add-in to a page. Populating a Treemap visualization with data. Implementing filtering in a Treemap visualization. Reacting to events from the Treemap control add-in. 9
ADDING THE TREEMAP CONTROL ADD-IN TO THE SALES ORDER PAGE First, you create a new Treemap visualization page for sales orders. You use page 9305, Sales Order List, from the demo database as a starting point. 1. In Object Designer, open page 9305, Sales Order List, and then save it as another page with the ID 55556 and name Sales Order Analysis. The page looks similar to a typical list place, which includes several fields in a Repeater control. To implement the Treemap visualization, you will replace the fields in the Repeater control with a single field that is configured to the TreeMapViz control add-in. 2. In Page Designer for page 55556, remove the <Control1> group that has the Repeater subtype and all child fields. 3. Instead of the Repeater subtype, insert a control that has the Field type. 4. Set the ControlAddIn property for the new field to the TreeMapViz control add-in. 5. Save and compile the page. 10
6. To view the page, in Object Designer, select page 55556, Sales Order Analysis, and then click Run. The page looks similar to the following figure. The Treemap visualization does not show any data. To populate the Treemap visualization with data, go to the next procedure. 11
POPULATING THE TREEMAP CONTROL ADD-IN WITH DATA After you have updated the page, you must get data into the Treemap visualization control add-in. The control add-in processes XML data in a certain format. You create a function that calls the MakeTreeMapXmlData function. The MakeTreeMapXmlData function is a generic function that can be used on any table. For the Treemap visualization, it uses the Treemap Data Builder COM object to build valid XML data. The MakeTreeMapXmlData function collects information about all Decimal type fields in a table and includes this information in the Treemap XML data. The Treemap visualization uses this information to populate the drop-down field selectors for the size and color measures. A page that calls the MakeTreeMapXmlData function only sends the setup information when it initializes the page. The MakeTreeMapXmlData function also adds the values for the two referenced fields of all rows in the table to the Treemap XML data. Tip The Treemap visualization combines setup information and display data in one XML data stream that is sent to the visualization control. You can use this as a best practice for creating your own visualization control add-ins. 1. In Page Designer, open page 55556, Sales Order Analysis. 2. To bind the Treemap visualization control add-in field to XML data, create a global variable called _xml that has a DataType of BigText, and then set the _xml variable as the field s SourceExpr. 12
3. In the C/AL code for the page, add a global function that populates the _xml variable with data. a. Create a global function called MakeTreeMapData that has the following local parameters and variables. Local entity Name DataType SubType Length Parameter Variables addselectablemeasures Boolean myrec Record Sales Header recref RecordRef CurrentPos Text 1024 colorfield sizefield captionfield b. Create the following global variables. FieldRef FieldRef FieldRef Name DataType SubType Length _colorfieldno _sizefieldno _captionfieldno Integer Integer Integer _treemaputil Codeunit Treemap AddIn Code c. Add the following code to the MakeTreeMapData function on the page. myrec.copyfilters(rec); recref.gettable(myrec); IF (_colorfieldno >= 0) THEN colorfield := recref.field(_colorfieldno); IF (_sizefieldno >= 0) THEN sizefield := recref.field(_sizefieldno);captionfield := recref.field(_captionfieldno); currentpos := Rec.GETPOSITION(); recref.setposition(currentpos); _treemaputil.maketreemapxmldata(recref, captionfield, colorfield, sizefield, addselectablemeasures, _xml); 4. Add the following code to the OnInit trigger for page 55556. _captionfieldno := 3; _colorfieldno := 60; _sizefieldno := 122; 13
5. Add the following code to the OnOpenPage trigger for page 55556. MakeTreeMapData(TRUE); The new P55556.MakeTreeMapData function uses values for the currently selected cell in the Treemap visualization on the page to determine its color, size, and caption. These values are maintained as global page variables and initialized in the OnInit trigger. When the Treemap visualization page calls the XML data generation for the first time, it includes these values and setup information in the OnOpenPage trigger but only for the current instance of the page. 6. Run page 55556, Sales Order Analysis, to display the Treemap visualization. 14
IMPLEMENTING FILTERING ON THE TREEMAP VISUALIZATION You can filter the data that is displayed in the Treemap visualization by using filters that you set in the filter pane. When you change the filter, the Treemap visualization changes to reflect the updated data. It will remove or add Treemap visualization fields, and it will also change size and color based on the updated data. To support filtering, you add code to the page OnFindRecord trigger to detect filter changes, and you implement the OnNextRecord trigger. When the filter changes, new XML data is generated for the Treemap visualization. However, the setup information is not sent each time. 1. In Page Designer, open page 55556, and then define the following C/AL global variables. Name DataType SubType Length found _lastfilters Boolean Text 2. In the C/AL code for page 55556, add the following code to the OnFindRecord trigger. found := Rec.FIND(Which); IF (Which = '=><') THEN BEGIN END MakeTreeMapData(TRUE); ELSE IF ((Which <> '-') AND (Which <> '+') AND (Which <> '=')) THEN BEGIN IF (_lastfilters <> Rec.GETFILTERS()) THEN BEGIN _lastfilters := Rec.GETFILTERS(); MakeTreeMapData(FALSE); END; END; EXIT (found); 3. Add the following code to the OnNextRecord trigger: EXIT (Rec.NEXT(Steps)); 4. Save and compile the page. 5. Run the page to view the Treemap visualization. Note When you click different cells in the Treemap visualization, the FactBoxes do not update to the associated record in the selected cell. Also, when you double-click a cell, nothing happens because you have not yet configured any events in the Treemap visualization. 15
REACTING TO EVENTS FROM THE TREEMAP CONTROL ADD-IN Control add-ins can include events that occur as a result of user interaction on the page. With the Treemap visualization control add-in, you can use events to update FactBoxes when a user clicks a cell or to open a page when a user double-clicks a cell. Events send messages to the OnControlAddin trigger of a page that contains the control add-in. To handle event messages, you add code to the OnControlAddin trigger of the page. For information about events and triggers with control add-ins, see Calling Triggers From a RoleTailored Client Add-in in the MSDN library. EVENT MESSAGES FROM THE TREEMAP VISUALIZATION CONTROL ADD-IN The Treemap visualization control add-in sends the following messages through the OnControlAddIn trigger. Message ID Data Description Measures changed 100 Two comma-separated field numbers Occurs when you change the measures on the Treemap visualization. The Treemap visualization gets fresh data for the selected cells. Treemap field activated Treemap field selected 101 Record ID associated with the Treemap cell 102 Record ID associated with the Treemap cell Occurs when you double-click a Treemap visualization cell or press ENTER on a selected cell. The corresponding task page for the record that is underlying the Treemap visualization cell is opened. In this walkthrough, the Sales Order page is opened. Occurs when you select a Treemap visualization cell with the mouse or keyboard. The page synchronizes the FactBoxes with the selected record. In this walkthrough, the customer data for the selected sales order is updated. Note There is built-in latency before sending the event to ensure that the selection is intentional and that you are not cycling through the Treemap visualization with the keyboard. 16
TO ADD CODE TO HANDLE EVENT MESSAGES FROM THE TREEMAP CONTROL ADD-IN 1. In Page Designer, on page 55556, create a C/AL global function called HandleAddinMessage that has the following local parameters and variables. Local entity Name DataType SubType Parameters Index Data pos Integer BigText Integer myrec Record Sales Header Variables recid recref RecordID RecordRef mycard Page Sales Order txt Text 2. In the C/AL code of page 55556, locate the _xml - OnControlAddIn trigger, and then add the following code. HandleAddInMessage(Index, Data); 3. Add the following code to the HandleAddinMessage function to handle the messages from the Treemap visualization control add-in, CASE Index OF // EVENTID_MeasuresChanged 100: BEGIN pos := Data.TEXTPOS(','); Data.GETSUBTEXT(txt, 1, pos-1); IF (NOT EVALUATE(_colorFieldNo, txt)) THEN _colorfieldno := -1; Data.GETSUBTEXT(txt, pos+1, Data.LENGTH-pos); IF (NOT EVALUATE(_sizeFieldNo, txt)) THEN _sizefieldno := -1; MakeTreeMapData(FALSE); END; // EVENTID_ItemActivated 101: BEGIN recref.gettable(myrec); Data.GETSUBTEXT(txt, 1, Data.LENGTH); EVALUATE(recId, txt); 17
IF (recref.get(recid)) THEN BEGIN END; END; recref.settable(myrec); mycard.setrecord(myrec); mycard.run(); // EVENTID_ItemSelected 102: BEGIN recref.gettable(myrec); Data.GETSUBTEXT(txt, 1, Data.LENGTH); EVALUATE(recId, txt); IF (recref.get(recid)) THEN BEGIN END ELSE END; END; recref.settable(myrec); CurrPage.SETRECORD(myRec); MESSAGE('Not Found: ' + txt); 7. Run page 55556, and then click or double-click different cells in the Treemap visualization to see that FactBoxes update or that the Sales Order page opens as expected. NEXT STEPS You should be able to use the Treemap visualization in other scenarios. Find application scenarios that could benefit from using the Treemap Business Data Visualization, and work with your customers to try it out in real customer environments. Ask your customers and users how helpful the visualization is in performing their daily work. 18
Microsoft Dynamics is a line of integrated, adaptable business management solutions that enables you and your people to make business decisions with greater confidence. Microsoft Dynamics works like and with familiar Microsoft software, automating and streamlining financial, customer relationship, and supply chain processes in a way that helps you drive business success. U.S. and Canada Toll Free (888) 477-7989 Worldwide (1) (701) 281-6500 www.microsoft.com/dynamics The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, this document should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication. This white paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED, OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation. Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property. 2010 Microsoft. All rights reserved.