Chapter 1 Introduction Guided Analytic Solutions .......................................................................................................................... 1 Configuring DecisionSite for Specific Tasks.......................................................................................... 3 Configured End-User Application .......................................................................................................... 8 Summary ................................................................................................................................................. 9 Who Should Read This Book.................................................................................................................... 10 How This Book Is Organized.................................................................................................................... 10 Part I: The DecisionSite Platform ......................................................................................................... 11 Part II: Configuring DecisionSite.......................................................................................................... 12 Part III: Client APIs............................................................................................................................... 12 Part IV: Information Services ............................................................................................................... 12 Part V: Integrating and Automating DecisionSite................................................................................. 13 Appendices ............................................................................................................................................ 13 What’s on the Download Site?.................................................................................................................. 13 Chapter 2 DecisionSite Components Chapter Objectives .................................................................................................................................... 15 How Does DecisionSite Fit In?................................................................................................................. 15 The Analytic Application Platform ........................................................................................................... 16 DecisionSite Components ......................................................................................................................... 17 Security and Administration.................................................................................................................. 18 User Authentication........................................................................................................................... 18 Custom Authentication Checking ..................................................................................................... 19 User and Group Management ........................................................................................................... 19 Custom Data Access Authentication................................................................................................. 20 Information Services ............................................................................................................................. 20 Computation Services ........................................................................................................................... 22 S-PLUS.............................................................................................................................................. 23 R Open Source .................................................................................................................................. 23 Application Manager............................................................................................................................. 24 Tools...................................................................................................................................................... 25 Guides.................................................................................................................................................... 26 Guided Applications.............................................................................................................................. 26 DecisionSite Library ............................................................................................................................. 26 DecisionSite Client and DecisionSite Posters....................................................................................... 27 Key Points ................................................................................................................................................. 28 Summary ................................................................................................................................................... 29 Chapter 3 DecisionSite Architecture Chapter Objectives .................................................................................................................................... 31 DecisionSite Architecture ......................................................................................................................... 31 DecisionSite Server ................................................................................................................................... 32 APIs........................................................................................................................................................... 34
Client APIs ............................................................................................................................................ 34 Application Manager APIs.................................................................................................................... 35 Import Agent APIs ................................................................................................................................ 35 Tool APIs .............................................................................................................................................. 36 Web Service APIs ................................................................................................................................. 37 Authenticating into the DecisionSite Server ..................................................................................... 37 Getting and Setting meta data ........................................................................................................... 37 Getting Data ...................................................................................................................................... 38 Running Stored Procedures............................................................................................................... 39 Java APIs............................................................................................................................................... 39 Data Access ............................................................................................................................................... 39 Integrations................................................................................................................................................ 41 Client Application Integrations ............................................................................................................. 41 Web Portals and Intranet Integrations................................................................................................... 42 Server-Side Integrations........................................................................................................................ 43 Key Points ................................................................................................................................................. 43 Summary ................................................................................................................................................... 43 Chapter 4 DecisionSite Developer Overview Chapter Objectives .................................................................................................................................... 45 What is DecisionSite Developer?.............................................................................................................. 45 DecisionSite Builder ................................................................................................................................. 45 Creating Projects ................................................................................................................................... 46 Registering Projects.............................................................................................................................. 48 Development Environment ....................................................................................................................... 50 Adding a Code Repository/ Source Control system.............................................................................. 50 Use your own IDE................................................................................................................................. 50 Local Testing......................................................................................................................................... 51 Common Tasks...................................................................................................................................... 52 Start a New Development Project ..................................................................................................... 52 Edit or review code in an existing project......................................................................................... 52 Test and Debug the Project ............................................................................................................... 53 Build a distribution............................................................................................................................ 53 Commit your changes to the repository ............................................................................................ 54 Sharing the Distribution .................................................................................................................... 54 Naming conventions.................................................................................................................................. 55 Spotfire Protocol ....................................................................................................................................... 56 Developer Utilities .................................................................................................................................... 56 API Terminal............................................................................................................................................. 63 Declared Variables ................................................................................................................................ 63 Declared Functions................................................................................................................................ 64 Resources .................................................................................................................................................. 65 The Spotfire Developer Network .......................................................................................................... 65 Developer Central ................................................................................................................................. 66 Spotfire Support .................................................................................................................................... 66 Registration ....................................................................................................................................... 66
Search the Knowledge Base.............................................................................................................. 68 Ask Spotfire....................................................................................................................................... 69 Spotfire Professional Services............................................................................................................... 72 Spotfire Training ................................................................................................................................... 73 Key Points ................................................................................................................................................. 75 Summary ................................................................................................................................................... 76 Chapter 5 Creating Applications and Extensions Chapter Objectives .................................................................................................................................... 77 Guided Application Framework................................................................................................................ 77 The Application Hierarchy........................................................................................................................ 79 Application and Extension Definitions ..................................................................................................... 80 The Application Definition Section ...................................................................................................... 83 The Dependencies Section .................................................................................................................... 84 The Layout Section ............................................................................................................................... 84 Licensing Extensions................................................................................................................................. 84 Configuration Files................................................................................................................................ 85 licenses.xml ....................................................................................................................................... 85 products.xml...................................................................................................................................... 86 bundles.xml ....................................................................................................................................... 86 Deployment ........................................................................................................................................... 87 Exercises.................................................................................................................................................... 88 Exercise 5.1 Creating a New DecisionSite Application........................................................................ 88 Exercise 5.2 Registering an Application ............................................................................................... 92 Key Points ................................................................................................................................................. 95 Summary ................................................................................................................................................... 95 Chapter 6 Adding Resources Chapter Objectives .................................................................................................................................... 97 Introduction ............................................................................................................................................... 97 Package.................................................................................................................................................. 98 definition.xml .................................................................................................................................... 99 resources.xml................................................................................................................................... 102 configuration.xml ............................................................................................................................ 102 modules.xml .................................................................................................................................... 103 Service................................................................................................................................................. 107 Resources ................................................................................................................................................ 109 Guide ................................................................................................................................................... 109 Implementing a Guide..................................................................................................................... 110 Using the Analysis Builder 110 Manually 110 Inserting a Guide ............................................................................................................................. 112 Tool ..................................................................................................................................................... 116 Dialog Tool ..................................................................................................................................... 116 Implementing a Dialog Tool 116 Inserting a Dialog Tool 119
WSC Tool........................................................................................................................................ 123 Implementing a WSC Tool 124 Inserting a WSC Tool 125 DLL Tool......................................................................................................................................... 129 Implement a Visual Basic DLL Tool 129 Implement a Visual C++ DLL Tool 130 Plug-in ............................................................................................................................................. 130 Implementing a Plugin 130 Inserting a Plugin 132 IS Filter............................................................................................................................................ 135 Implement an IS Filter 136 Inserting an IS Filter 142 Sxl Extension................................................................................................................................... 145 Implementing an Sxl Extension 146 Inserting an SxlExtension 149 Custom Resource............................................................................................................................. 151 Implementing a Custom Resource 152 Inserting an Custom Resource 152 External Link................................................................................................................................... 154 Implementing an External Link 154 Inserting an External Link 154 Help ................................................................................................................................................. 157 Implementing a Help File 157 Insertting a Help File 157 Controlling where Resources are displayed ............................................................................................ 160 Using the Category Name ................................................................................................................... 162 Using the Merger Attribute ................................................................................................................. 163 Testing the layout inside DecisionSite ................................................................................................ 166 Viewing the XML source of the layout............................................................................................... 167 Adding a Guide or Tool to an existing group...................................................................................... 167 Removing a Guide or Tool included in a parent application from a group ........................................ 168 Creating a new group .......................................................................................................................... 169 Creating a subgroup ............................................................................................................................ 171 Renaming an existing group................................................................................................................ 171 Removing an existing group ............................................................................................................... 172 Adding a ToolTip to a group............................................................................................................... 172 Replacing the content of an existing group......................................................................................... 172 Moving an existing group ................................................................................................................... 173 Exercises.................................................................................................................................................. 174 Exercise 6.1 Inserting a Guide ............................................................................................................ 174 Exercise 6.2 Inserting a Dialog and WSC Tool .................................................................................. 180 Exercise 6.3 Add a Resource Manually .............................................................................................. 180 Exercise 6.4 Create an External Link.................................................................................................. 181 Exercise 6.5 Create an SxlExtension................................................................................................... 181 Key Points ............................................................................................................................................... 183 Summary ................................................................................................................................................. 183
Chapter 7 Deploying Your Solutions Chapter Objectives .................................................................................................................................. 185 Deploying to the Server........................................................................................................................... 185 Validate your Project........................................................................................................................... 186 Configure Build Options and Build a Distribution ............................................................................. 186 What is a Distribution?.................................................................................................................... 188 Deploy the Distribution....................................................................................................................... 189 Verify the Deployment........................................................................................................................ 190 Setup Role Based Access .................................................................................................................... 191 Publishing to the Library......................................................................................................................... 192 Key Points ............................................................................................................................................... 195 Summary ................................................................................................................................................. 195 Chapter 8 Client APIs Chapter Objectives .................................................................................................................................. 197 Client APIs .............................................................................................................................................. 197 DecisionSite Client Object Model....................................................................................................... 198 Objects, Methods, and Properties........................................................................................................ 198 Application Object .................................................................................................................................. 199 Loading Data ....................................................................................................................................... 201 Visualization Object................................................................................................................................ 203 Collection Objects ................................................................................................................................... 203 Views Collection ..................................................................................................................................... 204 Adding Views...................................................................................................................................... 206 Axes......................................................................................................................................................... 206 Records.................................................................................................................................................... 207 Exporting Records............................................................................................................................... 208 QueryDevices .......................................................................................................................................... 208 Accessing Query Device Values ......................................................................................................... 209 Setting Query Device Values .............................................................................................................. 210 Columns .................................................................................................................................................. 211 Searching within Columns .................................................................................................................. 211 Calculating Columns ........................................................................................................................... 212 List Columns in a Guide...................................................................................................................... 212 Adding Columns to the Dataset .......................................................................................................... 214 Adding Column Methods ................................................................................................................ 215 Control Windows .................................................................................................................................... 216 Details-on-Demand ................................................................................................................................. 217 Editing the Details-on-Demand Template........................................................................................... 217 Applying the Template........................................................................................................................ 219 Trellising ................................................................................................................................................. 219 Curve Drawing ........................................................................................................................................ 220 Adding Curves for Trellis ................................................................................................................... 222 Background Images................................................................................................................................. 222 Event Handling........................................................................................................................................ 223
Event Handler...................................................................................................................................... 223 Event Manager .................................................................................................................................... 224 Exercises.................................................................................................................................................. 226 Exercise 8.1 Opening Data.................................................................................................................. 226 Exercise 8.2 Working with Views....................................................................................................... 228 Exercise 8.3 Working with Records and Columns ............................................................................. 230 Exercise 8.2 Working with Events...................................................................................................... 233 Key Points ............................................................................................................................................... 233 Summary ................................................................................................................................................. 234 Chapter 9 Application Manager APIs Chapter Objectives .................................................................................................................................. 235 Application Manager APIs...................................................................................................................... 235 ScriptArguments...................................................................................................................................... 236 Access to Client APIs.......................................................................................................................... 236 From a Guide................................................................................................................................... 236 From a Dialog Tool ......................................................................................................................... 236 From a WSC Tool and a Dialog Tool ............................................................................................. 237 Properties and Methods....................................................................................................................... 237 Global Variable Storage for Guides .................................................................................................... 238 Storing Settings for a Tool .................................................................................................................. 238 SfCreateObject ........................................................................................................................................ 239 Named Objects ........................................................................................................................................ 239 Adding A Named Object..................................................................................................................... 240 Retrieving Named Objects .................................................................................................................. 240 Removing Named Objects .................................................................................................................. 241 ClientCapabilities .................................................................................................................................... 241 Check Component Version ................................................................................................................. 241 Get File Version .................................................................................................................................. 242 Check if Component is Registered...................................................................................................... 242 Profile Manager....................................................................................................................................... 242 Resource Manager................................................................................................................................... 243 Tool Automation ..................................................................................................................................... 244 Define the Tool................................................................................................................................ 245 Implement the Tool ......................................................................................................................... 246 Validate the Parameters 246 Handle the User Interface 247 Integrate with the Analysis Builder 247 Return the Results 247 Invoke the Tool ............................................................................................................................... 247 Show up in Analysis Builder 248 Call a tool and Do Not Capture in the Analysis Builder 248 Example 248 SfRecordset ............................................................................................................................................. 250 Extending the Analysis............................................................................................................................ 256 Exercises.................................................................................................................................................. 258
Exercise 9.1 Implementing Tool Automation ..................................................................................... 258 Exercise 9.2 Extending the Analysis................................................................................................... 259 Key Points ............................................................................................................................................... 259 Summary ................................................................................................................................................. 259 Chapter 10 Import Agent APIs Chapter Objectives .................................................................................................................................. 261 Introduction ............................................................................................................................................. 261 Data Sources............................................................................................................................................ 262 Text Parser........................................................................................................................................... 263 File....................................................................................................................................................... 263 HTTPRequest ...................................................................................................................................... 264 OLEDB................................................................................................................................................ 264 IIS ........................................................................................................................................................ 265 Custom Data Source............................................................................................................................ 266 Create the Data Source.................................................................................................................... 266 Setup as a Custom Resource in a Package ...................................................................................... 274 Create an Import Agent Template................................................................................................... 275 Register the Import Agent Template............................................................................................... 275 Filtering ................................................................................................................................................... 275 Conditioning programmatically .......................................................................................................... 278 Reshaping data ................................................................................................................................ 278 Reducing data.................................................................................................................................. 281 Custom Filter........................................................................................................................................... 282 Favorites .................................................................................................................................................. 284 Template.............................................................................................................................................. 285 icon .................................................................................................................................................. 285 promptMode .................................................................................................................................... 286 Deploy as a Package............................................................................................................................ 286 Using the Import Agent Outside Spotfire ............................................................................................... 287 Exercises.................................................................................................................................................. 289 Exercise 10.1 Understanding the Import Agent Schema .................................................................... 289 Exercise 10.2 Using the Import Agent Outside Spotfire..................................................................... 290 Additional Exercises: Creating a Custom Data Source....................................................................... 292 Key Points ............................................................................................................................................... 292 Summary ................................................................................................................................................. 292 Chapter 11 Information Services Chapter Objectives .................................................................................................................................. 293 Information Services ............................................................................................................................... 293 Introduction to Information Designer ..................................................................................................... 294 General Work Flow............................................................................................................................. 294 Information Model Objects ................................................................................................................. 295 Data Sources.................................................................................................................................... 296 Creating a Data Source 297 Domains .......................................................................................................................................... 299
Creating a New Domain 299 Joins................................................................................................................................................. 300 Creating a Join 300 Freehand Joins 301 Column Elements ............................................................................................................................ 304 Creating a Column Element 305 Creating Multiple Column Elements 307 Column Calculations 309 Column Filters 309 Aggregated Columns 310 Aggregation Example 310 Using Drillable 312 Filter Elements ................................................................................................................................ 313 Creating a Filter Element 313 Subqueries 315 Filter Example 316 Exporting / Importing the Model .................................................................................................... 317 Permissions...................................................................................................................................... 319 Guidelines for Setting Up a Model ......................................................................................................... 320 Tips and Tricks.................................................................................................................................... 322 Replacing Null................................................................................................................................. 322 Limiting the Number of Records Returned..................................................................................... 322 Concatenating Strings ..................................................................................................................... 323 PL/SQL Functions........................................................................................................................... 324 Using Stored Procedures ................................................................................................................. 326 Pre- and Post-Update Procedures 327 Query Procedure 328 Information Builder................................................................................................................................. 333 Creating a New Information Link ....................................................................................................... 333 Filters in an Information Link ......................................................................................................... 334 Hard Filters 334 Run-time Filters 336 Independent Elements ..................................................................................................................... 337 Example 338 Displaying SQL Statements for an Information Link ......................................................................... 341 Editing Oracle Hints............................................................................................................................ 342 Editing Information Links................................................................................................................... 343 Viewing the SQL Log ......................................................................................................................... 346 Transforming the Data ............................................................................................................................ 346 Eliminating Duplicates........................................................................................................................ 346 Pivoting Data....................................................................................................................................... 347 Example........................................................................................................................................... 348 Example of Pivoting with Aggregation........................................................................................... 349 Exercises.................................................................................................................................................. 351 Exercise 11.1 Creating an Information Model .................................................................................... 351 Exercise 11.2 Building Information Links.......................................................................................... 365
Exercise 11.3 Opening Information Links .......................................................................................... 368 Exercise 11.4 Exporting an Information Model.................................................................................. 369 Exercise 11.5 Importing an Information Model.................................................................................. 370 Additional Exercises ........................................................................................................................... 371 Key Points ............................................................................................................................................... 371 Summary ................................................................................................................................................. 371
Chapter 12 Web Services APIs Chapter Objectives .................................................................................................................................. 373 SOAP Basics ........................................................................................................................................... 373 SOAP Message.................................................................................................................................... 373 Service Request ................................................................................................................................... 374 Service Response................................................................................................................................. 374 Service Failures ................................................................................................................................... 374 The Session Element ........................................................................................................................... 375 SOAP Router URLs ............................................................................................................................ 375 Security.................................................................................................................................................... 376 Log-in .................................................................................................................................................. 376 Log-out ................................................................................................................................................ 377 Information Model .................................................................................................................................. 377 listElements ......................................................................................................................................... 378 loadElement......................................................................................................................................... 379 saveElement ........................................................................................................................................ 384 deleteElement ...................................................................................................................................... 385 getQuerySQL ...................................................................................................................................... 386 getDataSourceMetadata ...................................................................................................................... 387 DAT......................................................................................................................................................... 389 Pipes .................................................................................................................................................... 390 QueryPipe........................................................................................................................................ 391 Reference an Information Link 391 Create a Query at Runtime 391 Filtering your Data 394 Reshape ............................................................................................................................................... 395 Key Columns (Identity Columns) ................................................................................................... 396 Category Columns........................................................................................................................... 396 Data-Columns.................................................................................................................................. 397 Additional-Columns ........................................................................................................................ 398 Column Ordering............................................................................................................................. 399 Memory Usage ................................................................................................................................ 399 Formatter ............................................................................................................................................. 400 XMLFormatter ................................................................................................................................ 400 row-tag 401 col-tag 401 row-index-mode 401 column-index-mode 402
CSVFormatter ................................................................................................................................. 402 Separator 402 Escape-style 403 Formatting Options ......................................................................................................................... 403 Include-metadata 403 Bytes-per-block or rows-per-block 404 Content-encoding 404 Data Format..................................................................................................................................... 404 character-encoding 404 use-utf8-bom 404 Open .................................................................................................................................................... 405 getData ................................................................................................................................................ 408 getMetadata ......................................................................................................................................... 410 reset ..................................................................................................................................................... 411 close..................................................................................................................................................... 412 Example Usage........................................................................................................................................ 413 Use Information Model Web Services to Update the Model Programmatically ................................ 413 Use Information Model to Validate Elements..................................................................................... 413 Exercises.................................................................................................................................................. 413 Exercise 12.1 Making Web Services Calls ......................................................................................... 413 Key Points ............................................................................................................................................... 417 Summary ................................................................................................................................................. 417 Chapter 13 Integrating and Automating DecisionSite Chapter Objectives .................................................................................................................................. 419 Introduction ............................................................................................................................................. 419 Stream data to DecisionSite from Server ................................................................................................ 419 Opening DecisionSite from a WebSite ................................................................................................... 420 Automating DecisionSite ........................................................................................................................ 421 Type Libraries ..................................................................................................................................... 422 Object browser .................................................................................................................................... 422 OLE/COM Object Viewer .................................................................................................................. 423 PROGIDs and CLSIDs........................................................................................................................ 424 How an Object Exposes Its Methods and Properties .......................................................................... 425 The Dispatch Interface .................................................................................................................... 426 Virtual Function Table (vtable)....................................................................................................... 426 Creating an Automation Client with Visual Basic .............................................................................. 426 Binding ............................................................................................................................................ 426 Early binding 426 Late binding 427 Choosing the correct type of binding 427 Creating a VB Automation Client Using Early Binding 428 Creating a VB Automation Client Using Late Binding 428 Automating a Running Instance of DecisionSite ............................................................................ 429 Creating an Automation Client with C++ ........................................................................................... 429 Automating DecisionSite using C++ Automation .......................................................................... 430
The IUnknown and IDispatch Interfaces 430 Passing Parameters and Receiving Return Values 433 Automating DecisionSite with straight C++ ................................................................................... 435 Error Handling 439 Automate a Running Instance of DecisionSite 439 Automating DecisionSite using MFC ............................................................................................. 440 The COleDispatchDriver Class 440 Creating an automation client with MFC 440 Exception Handling 444 Implement exception handling 444 Creating an Automation Client with Smart Pointers....................................................................... 445 Automating DecisionSite with ActivePerl .......................................................................................... 447 Automating DecisionSite with Python................................................................................................ 448 Automating DecisionSite with Delphi ................................................................................................ 448 Late Binding.................................................................................................................................... 448 Early Binding .................................................................................................................................. 451 Handling Events in DecisionSite............................................................................................................. 451 Using WithEvents in Visual Basic ...................................................................................................... 451 Event Handling with C++ ................................................................................................................... 453 Automating DecisionSite with Java ........................................................................................................ 453 Integrating into DecisionSite................................................................................................................... 454 Web Pages ........................................................................................................................................... 454 Java Applets ........................................................................................................................................ 455 Getting Spotfire Visualizations and Java Applets to Interact ......................................................... 455 How to Implement an Interactive Java Applet................................................................................ 456 Listening to Spotfire Events 457 Call Java Applet in Response to a Spotfire Event 457 Call Client APIs from Java Applet 458 Integrating into DecisionSite........................................................................................................... 459 Run from a Control Window 459 Run from a Custom Start Page 459 Exercises.................................................................................................................................................. 461 Exercise 13.1 Launching DecisionSite................................................................................................ 461 Key Points ............................................................................................................................................... 461 Summary ................................................................................................................................................. 461
