ZuckerReports Professional Manual 1.2.pdf - SugarForge

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/ZuckerReportsProfessional 1.2ManualPage 1 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/Table of ContentsIntroduction....................................................................................................................3ZuckerReports Module ..................................................................................................3Installation of Requirements..........................................................................................4Sugar Suite > 3.0........................................................................................................4Java Development Kit >= 1.4.2 .................................................................................4iReport (recommended) .............................................................................................4.net Framework 1.1 and Microsoft Office (on your desktop)....................................4Java Runtime Environment >= 1.4.2 and OpenOffice (on your desktop) .................4Installation Steps for ZuckerReports .............................................................................5Add ZuckerReports module to your Sugar installation .............................................5Prepare and configure ZuckerReports database.........................................................8Installation of additional libraries ..............................................................................8Connector/J 3.1 ......................................................................................................8iReport 0.5.0...........................................................................................................8Modify “Home” to include published reports................................................................9Modify your modules to allow “Module Binding”......................................................11ZuckerReports Administration.....................................................................................12Parametrization of your reports ...............................................................................12Defining a Parameter ...............................................................................................12Category Management.............................................................................................15Upload and Configuration of report designs............................................................16Bind and unbind parameters to report designs.........................................................17Definition of query templates ..................................................................................18Bind and unbind parameters to queries....................................................................19Binding Reports or Queries to a Module .................................................................20Upload and Configuration of Microsoft Office/OpenOffice files ...........................21Contact .........................................................................................................................22Page 2 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/IntroductionZuckerReports is an extension module for Sugar Suite, the well-known Open SourceCustomer Relationship Management software. In short, it provides the followingfunctions: Management of report definitions and query templates Management of Microsoft Office templates with binding to Sugar data(mailmerge with Word, Excel reports) Management of OpenOffice/StarOffice templates with binding to Sugar data(mailmerge with StarWriter) Management of parameter selection lists Parametrization and execution of report definitions and query templates Categorization of executed reports and query results for later use Export of executed reports and query results in various formatsBehind the scenes the excellent Open Source reporting library “JasperReports”(http://jasperreports.sourceforge.net/) is used for providing its outstanding, visuallyappealing and feature-rich reporting capabilities.ZuckerReports ModuleThe user and administration frontend is embedded asown module in Sugar Suite. It can be enabled/disabledfor each user just as with all the other modules comingwith Sugar Suite.The module provides the following functions for yourSugar administrators: Upload and configure report definitions andMicrosoft Office / OpenOffice templates Configure report parameters for resuse among yourreport definitions Manage report categories for clean separation ofreporting results for later use Define and configure query templates (arbitrarySQL)For your Sugar users, the module provides the followingfunctions: Parametrize and execute the report definitions andquery templates defined by your Sugaradministrators Export results in various formats Attach results to accounts, cases, projects etc. Publish results to “Home” viewPage 3 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/Installation of RequirementsPlease be sure to meet the following requirements before installation ofZuckerReports.Sugar Suite > 3.0This product has been tested with Sugar Suite 3.0x and 3.5x (including all currentpatches)Java Development Kit >= 1.4.2ZuckerReports uses a Java backend for providing it’s outstanding reportingcapabilities (http://java.sun.com/). Please be sure to install the DevelopmentKit, not only the Runtime Environment.iReport (recommended)iReport is a powerful, intuitive and easy to use visualreport designer, suitable for use with ZuckerReports(http://ireport.sourceforge.net/). Please follow our “FirstSteps”-tutorial after succesful installation ofZuckerReports for getting to know iReport..net Framework 1.1 and Microsoft Office (on your desktop)Please be sure to have a working installation of the .net Framework 1.1 and MicrosoftOffice on your desktop (in case you are using corresponding features ofZuckerReports).Java Runtime Environment >= 1.4.2 and OpenOffice (on yourdesktop)Please be sure to have a working installation of a Java Runtime Environment >= 1.4.2and OpenOffice on your desktop (in case you are using corresponding features ofZuckerReports).Page 4 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/Installation Steps for ZuckerReportsSince Sugar 3.5 the Sugar Module Loader is used for ZuckerReports installation. Incase you want to use ZuckerReports with Sugar 3.0, please contact us at support@gomobile.atto receive installation instructions.Add ZuckerReports module to your Sugar installationLogin to Sugar with your “admin” account and click on “Admin” (right on the top) toopen the “Admin”-module.Click on “Module Loader”Click on the “Browse…” button and select to file“ZuckerReports_Professional__module.zip” included in the ZuckerReportsdistribution. Click on the “Upload” button.Note: if you receive the error “Please specify a file and try again!”, then openyour php.ini with your favourite text editor, increase the maximum filesize forupload to 10M and restart apache afterwards:upload_max_filesize = 10MYou can now see ZuckerReports in the list of available modules. Click on the“Install” button to install the module.On the next screen click on “Commit” to start installation.Page 5 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/If everything works, you will see a screen telling that installation is completed.Note: you may receive more detailed information when clicking on “Display Log”Page 6 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/Click on the “Back to Module Loader” button to return to the module list. You cannow see ZuckerReports in the list of installed modules.Back in the „Admin“-module, click on „Configure Tabs”. You will see a line“ZuckerReports” in the “Hide Tabs” box.Select „ZuckerReports“ in the „Hide Tabs“ box and click on the arrow pointing to theleft. Click on the “Save”-button.You can now see the new “ZuckerReports” tab in Sugar.Page 7 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/Prepare and configure ZuckerReports database Login to your sugar database with administrative rights Execute the “setup.sql” script in your mysql prompt to prepare tables and data.cmd> mysql -u your-sugar-user -p your-sugar-db < setup.sqlInstallation of additional librariesDue to legal restrictions you have to obtain the following software includingappropriate licenses from the given sources separately.Connector/J 3.1Please point your browser to http://dev.mysql.com/downloads/connector/j/3.1.htmland get the current version of the “Connector/J” for MySQL. Copy the file “mysqlconnector-java--bin.jar”to the “/modules/ZuckerReports/jasper” folder.iReport 0.5.0If you want to use the charts capabilities of iReport, get the package fromhttp://ireport.sourceforge.net/ and copy the files “lib/jfreechart-0.9.21.jar” and“lib/iReport.jar” to the “/modules/ZuckerReports/jasper” folder.Page 8 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/Modify “Home” to include published reportsYou have to change the files “Home.html” and “index.php” within the “/modules/Home” directory. This step is optional.Note: please do a backup of these files before making the changes. You have to besomething familiar with PHP coding.Home.htmlAdd a “MYREPORTS” slot to the layout… …{MYREPORTS}{MYOPPORTUNITIES}{MYCASES}……index.phpAdd the code for the subpanel:…if(array_key_exists('ZuckerReports', $modListHeader))$panels['MYREPORTS'] ="modules/ZuckerReports/ReportHomeView.php";if(array_key_exists('Bugs', $modListHeader))$panels['MYBUGS'] = "modules/Bugs/MyBugs.php";…Page 9 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/Afterwards, you will find a the “Reports” panel showing the published reports on your“Home” view.Page 10 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/Modify your modules to allow “Module Binding”ZuckerReports allows the user to bind reports and queries to modules, which is veryuseful if you have reports or queries requiring the database identifier for a sugarobject (contact, account, project, …) as parameter. You can simply bind the report orquery to this module, defining the parameter to set on execution, and the report orquery can be called directly from the detail view of the other module (if you do thefollowing changes to this module).Unfortunately there currently is no other way to do this than making minor changes tothe existing Sugar program files. Sugar is organized into modules, where each modulehas its own directory beneath the “modules” directory. For each module you want tobe interlinked with ZuckerDocs, you have to change the file “DetailView.php” withinthe module directory.Note: please do a backup of DetailView.php before making the changes. You have tobe something familiar with PHP coding.Just add the lineat the very bottom of DetailView.php to include the ZuckerReports panel in a module.Afterwards, you will find a new “Reports, Queries and Letters” section when viewingthe details.Page 11 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/ZuckerReports AdministrationThis chapter describes common administration tasks necessary to use ZuckerReports.Parametrization of your reportsParametrization is one of the most important topics covered by ZuckerReports: itallows the runtime configuration of report and query execution in a user-friendly way.For example, when designing a report showing sales forecasts, it makes sense toinclude the timerange for which to do the forecast as a parameter (“Q1”-“Q4”), so youcan reuse the report design next year.To save your time, ZuckerReports maintains a “pool” of parameter definitions youcan reuse in all of your reports – for example if you have a bunch of reports showingvarious information about an account, you only have to define the “Account”-Parameter once and attach it to a number of reports handling the parameter.ZuckerReports enables your Sugar administrators to configure a user-friendlyselection box for a parameter, so your users don’t have to enter the value for theparameter with their keyboard, which is cumbersome and rather errorprone.Defining a Parameter Login to Sugar Suite with your “admin” account Within the “ZuckerReports” module click on “Report and Query Parameters”.You now see a list of already configured parameters.Page 12 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/ Click on “New Report Parameter” to define a new parameter, or on the nameof an existing parameter for making changes. Click on the “Save” button whenyou are ready.“Friendly Name” – Enter the name of the parameter as shown to the user. It should bea short, descriptive text telling the purpose of the parameter, for example “AccountSelection”“Default Name” – Enter the name of the parameter as defined in the report (seechapters on report and query definitions), for example “ACCOUNT_ID”“Default Value” (optional) – This value is the default value which is presented to theuser at report and query execution“Description” (optional) – A descriptive text for the parameter, which contains clearinformation on how to use this parameter“Selection” – you can choose between “Direct Input”, “User-Defined Query” and“User-Defined List”.Selection “Direct Input”When executing a reportor query, a textbox ispresented to the user forenter a value for theparameter by keyboard.Page 13 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/Category ManagementFor easy retrieval of your report and query result, you can assign it to a category,which essentially is the same concept as a “Folder” in common Operating Systems.You can create and delete subcategories in the “Report Archive”.Page 15 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/Upload and Configuration of report designsZuckerReports can handle reports designed for JasperReports, which are held in filesending in “.jrxml”. The ZuckerReports frontend supports the administrator in uploadand configuration of these report design files, as well as attaching and detachingparameters. Login to Sugar Suite with your“admin” account Within the “ZuckerReports” moduleclick on “Report and QueryTemplates”. You now see a list ofalready configured reports and queries. Click on “New Report Template” foruploading a new “.jrxml”-file. Click on the “Save” button when youare ready.“Template Name” - The name for thetemplate as shown to the user“Template File” – using the “Browse”-button select the “.jrxml” file to upload“Description” (optional) - A descriptivetext which contains clear information onhow to use this template“Allowed Formats” – select the formatsthe report can be exported to afterexecutionResource UploadIn case your report uses externalresources such as “.class”-files orpictures, upload them as well by using the“Browse”-button in the “OtherResources”-sectionSubreport UploadIn case your report is built on subreports,upload the “.jrxml”-files by using the“Browse”-button in the “Reports”-sectionNote: please consult the report design manual for correct usage of resources andsubreportsPage 16 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/Bind and unbind parameters to report designsFor your report designs you first have to define your parameters in the “.jrxml”-filewhen designing the report. Please be sure to use exactly the same value for theparameter name in ZuckerReports, as otherwise parameter handling won’t work. Login to Sugar Suite with your“admin” account Within the “ZuckerReports”module click on “Report andQuery Templates”. You now seea list of already configuredreports and queries. Click on the name of a report forshowing the details.Binding a parameter Select the parameter to bind in the“Parameter Selection” section on thebottom Enter the “Parameter Name” as usedin the report design or accept thesuggestion Optionally enter a “Default Value”to suggest to the user when executingthe report Click on the “Bind Parameter”-button. The attached parameter now isshown in the “Parameter Bindings”list.Unbinding a parameterSimply click on the “Unbind Parameter” button in the “Parameter Bindings” list todetach the parameter from the report.Page 17 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/Definition of query templatesZuckerReports enables Sugar administrator to define arbitrary SQL-queries and letthem execute by common Sugar users, including parametrization of the query. Login to Sugar Suite with your “admin”account Within the “ZuckerReports” moduleclick on “Report and Query Templates”.You now see a list of already configuredreports and queries. Click on “New Query Template” forentering an SQL-query. Click on the “Save” button when you areready.“Query Name” - The name for the template as shown to the user“Query” – enter your SQL query including placeholders for your parameters (seebelow)“Description” (optional) - A descriptive text which contains clear information on howto use this queryPage 18 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/Bind and unbind parameters to queriesFor filling your queries with parameters, you have to use placeholders when enteringthe query (see above). Use the parameter name prepended with a “$”, and theparameter value is filled in when executing the query – for example, if you have aparameter named “ACCOUNT_ID”, use the placeholder “$ACCOUNT_ID” in yourquery. Login to Sugar Suite with your“admin” account Within the “ZuckerReports”module click on “Report and QueryTemplates”. You now see a list ofalready configured reports andqueries. Click on the name of a query forshowing the details.Binding a parameter Select the parameter to attach in the“Parameter Selection” section on thebottom Enter the “Parameter Name” as usedas placeholder in the query oraccept the suggestion Optionally enter a “Default Value”to suggest to the user whenexecuting the report Click on the “Bind Parameter”-button. The attached parameter now isshown in the “Parameter Bindings”list.Unbinding a parameterSimply click on the “Unbind Parameter”button in the “Parameter Bindings” list todetach the parameter from the query.Page 19 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/Binding Reports or Queries to a ModuleZuckerReports allows the user to bind reports and queries to modules, which is veryuseful if you have reports or queries requiring the database identifier for a sugarobject (contact, account, project, …) as parameter. You can simply bind the report orquery to this module, defining the parameter to set on execution, and the report orquery can be called directly from the detail view of the other module (see chapterModify your modules to allow “Module Binding”). Login to Sugar Suite with your “admin”account Within the “ZuckerReports” moduleclick on “Report and Query Templates”.You now see a list of already configuredreports and queries. Click on the name of a report or queryfor showing the details.Binding to a module Select the module to bind to in the“Module Selection” section on the bottom Select the parameter to link the databaseidentifier for the module item to Click on the “Bind to Module”-button. The bound module now is shown in the“Module Bindings” list.Unbinding from a moduleSimply click on the “Unbind from Module” button in the “Module Bindings” list todetach the module from the query or report.Page 20 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/Upload and Configuration of Microsoft Office/OpenOffice filesZuckerReports can handle Microsoft Office and OpenOffice files bound to adatasource (Word, Excel and StarWriter). At runtime these files are connected to dataresulting from a ZuckerReport query template. The ZuckerReports frontend supportsthe administrator in upload and configuration of these queries and MicrosoftOffice/OpenOffice files.Note: Your Microsoft Office/OpenOffice files are always bound to a query templatedefined in ZuckerReports (see “Definition of query templates”). Parameter andmodule binding are always taken from these query templates. Login to Sugar Suite with your“admin” account Within the “ZuckerReports” moduleclick on “Report and QueryTemplates”. You now see a list ofalready configured reports and queries. Click on “New Office Template” foruploading a new “.doc”-file. Click on the “Save” button when youare ready.“Template Name” - The namefor the template as shown to theuser“Template File” – using the“Browse”-button select the file toupload“Description” (optional) - Adescriptive text which containsclear information on how to usethis template“Query” – select the querytemplate to bind toPage 21 of 22

go-mobileoffice@go-mobile.athttp://www.go-mobile.at/ContactFor licensing questions please contact us at mailto:sales@go-mobile.atFor support questions please contact us at mailto:support@go-mobile.atFor general questions please contact us at mailto:office@go-mobile.atPage 22 of 22