kinamu reporter - sinergiacrmwiki.sinergiacrm.org/images/kinamu_reporter_manual_v1.5_part_1.pdfthe...

KINAMU Reporter http://www.kinamu.com

No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of KINAMU Business Solutions AG. The information contained herein may be changed without prior notice.

These materials are subject to change without notice. These materials are provided by KINAMU Business Solutions AG for informational purposes only, without representation or warranty of any kind, and KINAMU Business Solutions AG shall not be liable for errors or omissions with respect to the materials. The only warranties for KINAMU Business Solutions AG products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

www.kinamu.com April 2010

KINAMU Reporter v1.5 Beta of 40 © KINAMU Business Solutions AG. All rights reserved

INTRODUCTION ................................................................................................................................ 3

THE BASICS ................................................................................................................................................. 3

EDITIONS .................................................................................................................................................... 4

INSTALLATION ............................................................................................................................................. 4

CREATING A BASIC REPORT ................................................................................................................. 5

CREATING THE REPORTS BASIC DATA .............................................................................................................. 6

DEFINING SELECTION CRITERIA ....................................................................................................................... 7

DEFINING THE LIST FIELDS ........................................................................................................................... 10

ADDING DYNAMIC SELECTION OPTIONS ......................................................................................................... 14

ADVANCED REPORTING SETTINGS ....................................................................................................... 16

THE NOT EXISTS SELECTION CLAUSE .............................................................................................................. 16

BASIC GROUPING OF RESULTS ...................................................................................................................... 17

GROUPED VIEWS ........................................................................................................................................ 19

DEFINITION OF CUSTOM REPORTING FIELDS ................................................................................................... 20

ADDING CHARTS TO REPORTS ............................................................................................................ 23

EXPORTING DATA ........................................................................................................................... 28

EXPORT TO EXCEL ...................................................................................................................................... 28

EXPORT TO PDF ........................................................................................................................................ 28

EXPORT TO TARGETLIST ............................................................................................................................... 31

MANAGING SNAPSHOTS .................................................................................................................. 33

CAPTURING SNAPSHOTS OF REPORTS ............................................................................................................ 33

IMPORTANT THINGS TO KNOW ABOUT SNAPSHOTS .......................................................................................... 34

COMPARING SNAPSHOTS CHART BY CHART .................................................................................................... 35

COMPARING SNAPSHOTS USING THE TREND ANALYSIS ..................................................................................... 36

THE KINAMU REPORTER CHARTS DASHLET ......................................................................................... 39



Introduction

The Basics

The KINAMU reporter is a flexible tools to analyze the Data in SugarCRM and allow Users to

intuitively build queries in SugarCRM. It is built on state of the art Frameworks and also supports full

charting capabilities.

Screenshot 1 - HomeScreen with KINAMU Reporter Charts Dashlets

Asides creation of reports and dynamic analysis the reports can also be used to graphically enhance

the Home Screen through the Reported Dashlet, the Data can be exported to MS Excel or as PDF

(with or without Charts) and the results can also be used to create target lists for marketing purposes

that later on can be used in Campaigns.



Editions

The KINAMU Reporter is released in two Editions. A Basic Edition and a Premium Edition. The Basic

Edition is available for free under the GNU GPL v3 License. The Premium Edition can be used based

on a yearly subscription fee and offers additional Functionality as well as Support from KINAMU.

Basic Edition Premium Edition

Flexible Generation of Reports Flexible Definition of Reporting Fields Dynamic Report Selection by User Standard List Grid View on Results Enhanced Grouped Views Integrated Charts Excel Export of Results PDF Export including Charts Snaphots capturing Reports Snapshot Analysis and Comparison Dashlet to visualize on the Home Screen

Installation

To Install the KINAMU Reporter use the Module Loader that comes with SugarCRM. In addition to the

core package you will also need to install a patch if you want to use the “not exists” selection Clause.

This will patch one of the SugarCRM core files (data/Link.php) and add functionality the KINAMU

Reporter requires to evaluate those clauses. This is optional but not required but please be aware

that the reporter does not check this and in case you do choose not to install this core patch you can

still create reports with the not exists clause that will then cause the system to fail.

After loading the modules you will need to run a repair for either the complete system but at least

for the KReporter Module to create the database tables required (this will most likely change in the

future for the time being this should be an acceptable procedure).

Once installed you are ready to go and create your first report.



Creating a Basic Report

To create a new Report select the KINAMU Reporter Module from the Modules Menu. Like in all

regular SugarCRM Modules this will show you a Listview of all Reports in the System.

Screenshot 2 - The KINAMU Reporter main Screen

From the menu select Create Report. This will bring up the main Report Definition Screen. The Screen

is split into three Areas:

(1) the Module Tree where you can select all Modules and the modules that have relationships to the

Module. After selecting a Module this will Populate dynamically and let you select the Modules in a

hierarchical View

(2) the Field List where you can select all relevant Fields in a module selected in the Tree above.

(3) the Definition Area which has three Panels: One for the Selection Criteria where you can define

flexible selection criteria for the report, one for the List itself where you can define the Fiedls that

should be displayed as well as further functions on these Fields like functions (SUM, COUNT, …),

groupings, Output Options like the PDF orientation or the View Definitions. One for the Charts where

you can define the Chart Layout used as well as detailed Options on the Charts itself and the

dataseries used.



Screenshot 3 - Main Reporting Screen Layout

Creating the Reports Basic Data

When You create a new report first of all specify a name for

the Report and then select a Module from the Dropdownlist in

the ModuleTree section of the Window. In our Example We

have created a new report which we called “My First Report”

and selected Contacts from the Dropdown of the available

Modules. The Modules Dropdown will show all Modules

available in SugarCRM without any limitations. It is up to you

to decide which Module to use and for which you can

realistically create a report (e.g. no Reporting is really possible

for the Home Module). Nevertheless we think this is beneficial

and gives flexibility since also all custom reports will

automatically show.

After selecting the Module the Field List is automatically populated and will show all available Fields

for the Selected Module. What you will also notice that the Dropdown for the Modules is disabled

and a Button with a lock is enabled next to the Dropdown now. Since the main Module is a key

element to the Report this cannot be changed that easily. In case you want to change it you need to

first unlock the Module to open up the report again. Yet be advised that this will erase all Report

1

2

3

Screenshot 4 - selecting a Report Module



definitions you did thus far and basically mean starting from scratch again. If you press the unlock

button also a dialog box will appear and prompt you to confirm the action.

In the Modules Tree expand the Module Contacts by clicking the little triangle in front of the Module.

This will danymically expand the Tree and load all Modules linked to the one we have selected – in

our exmple all Modules related to the Contacts Module. Your screen should now look like the

following Screenshot.

Screenshot 5 - Report with Root Module selected

Defining Selection Criteria

The next Step in Report Creation is the Definition of the Selection Criteria defining what you are

looking for in the database. The Panel for the Selection criteria is open by default. The definition is

optional – if you e.g. just want a list of all contacts in the system leave the selection criteria blank and

proceed to the next step defining the list. In our case we want to define a set of Selection Criteria.

Selection Criteria are organized in Groups. A report always has one Group (the root entry) that is

there by default and can also not be deleted or changed. A group has several Fields that are selected

by which are defined in the second part of the Selection criteria Screen. To add a Field simply drag it

from the Fields Area into the Selection Area.

If we e.g. in our example want to select Contacts by Salutation select the Salutation Field in the Fields

Box and drag it to the Selection screen. To make finding fields easier you can use the find box at the

top of the Fields List and type any string in the Field. The result in the Box will be filtered for all Fields

that match your Selection Criteria. By clicking the header of the List you can also dynamically sort the



List ascending or descending. Select the Salutation Field by dragging the entry to the Selection Area

and the Result should look as follows.

Screenshot 6 - Adding a field to a Selection Group

A couple of further Fields are automatically created and populated. The Operator

is by default set to “=”. Select the Field and a Dropdown will bring further Options

depending on the field type. Salutation is an ENUM Field in SugarCRM, so a field

with defined values which limits the list. If this e.g. a date Field the options will

have different values. Depending on the operator selected the options for entering

values changes. The behavior of the Field is also driven by the field type again.

For the Salutation in our example and the operator “=” the system

will let you select a value from a Dropdownlist with the values for

the specific field as it is defined in SugarCRM. Since we have

selected “=” as an operator we can also only specify one value in

the Equals/From Column in the table. Other Operators will allow

further Selections which we will cover later on. In our Example we

will look for Contacts with the Salutation “Mr.” – so we select the value. Leave all other Fields as they

are.

Furthermore we now want to add a selection Criteria to the Report where we select only Contacts of

Accounts where the name Starts with a Letter between A and G. To do that select the Module

Accounts in the related modules to the module accounts in the module tree, search for the account



name field, drag it to the selection Screen, specify the operator “is between” and fill in an “A” in the

from Value Column and a “G” in the to Value Column. The Result should look as follows.

Screenshot 7 - multiple Selection Criteria

To remove any of the selection criteria select the line and push the Button.

Within a Group are either evaluated using an AND statement (so all criteria have to be matched) or

as an OR statement (where it is sufficient if one of the criteria is met). To define how the selection

criteria within a Selection Group are evaluated select the “Select Clause:” in the Toolbar of the

Selection Groups Part of the Screen. In Our example we will leave it as it is set by Default using the

AND Clause.

To have more complex Searches you can add further Selection Groups. To add a group select the

group where you want to add the group to (this is hierarchical) and press the Button in the

Toolbar. A Popup will prompt you to specify the name of the group where you can just give it a name

that is meaningful to you, select the group and add further Selection Criteria. In our example we

want to Add a Group for the First Names that should have two Conditions with an OR Clause on the

Last names of the Contacts. To do that we add A group to the Root Group which we call “Last Name

Clause”, specify the Operator “OR” and add the Field last name for the contact twice with different

values and Operators. One where the last name starts with an A and one where the Last Name is

between “D” and “H”.

The Result should look as follows.



Screenshot 8 - Multiple Selection groups

Depending on the selected group in the groups tree you will see the respective selection criteria. To

delete a group select the group and press the Button. To rename a Group, select the entry and

press the Button. In the Popup Box specify a new name.

You can add as many selection groups as you want hierarchically. A selection group is treated with

the same selection operator for the group where it is linked to. So in our example we are selecting

Contacts that have the Salutation “Mr.” and the account name they are assigned to is between A and

G and the Last Name of the Contact either starts with an A or is between D and H.

Defining the List Fields

Second step is to define the Fields for the List that will be displayed, will be available for the Charts

and will print on the PDF or Export to Excel.

To define the List Fields select the List Fields tab in the Report Definition Window and the List

Definition Area opens up looking as follows.



Screenshot 9 - List Fields Definition Window

Similar to the Definition of the Selection Criteria select the Modules in the Tree and drag Fields from

the Field Area to the List Fields Window dropping them there. In our Case we want to list the First

Name and Last Name of the Contact as well as the Account they are assigned to with the name of the

assigned user to that account and if exists an email address of the Contact. To add those Fields select

the respective Modules, then the Fields and drag them over.



Screenshot 10 - Definition of List Fields

In the Name Colum the name of the Field as defined in SugarCRM is populated but can be

overwritten. If you want to name the field different in the Report simply overwrite it here (e.g. in the

example above the “Account Name” for the name of the Account or the “Assigned User” for the

Username. With the Width Column (that is set to 100 by Default) you can overwrite and steer the

width of the Display Column as well as the Column Width for the PDF output.

To sort the List select a Sort Criteria (ascending or descending) in the Sort Column as well as a Sort

Sequence which should be a numerical value. With that you can define multiple Sort Criteria and e.g.

sort the List first by Account Name and then by Last name. To do that select for both fields a Sort

Criteria and enter sort sequence 1 for the Account Name and sort sequence 2 for the Last Name.

In the Required Field you can define if a Field is required for a dependent module. In our case we

want to also display Contacts without an email address so we flag the email address as optional. This

only has an impact on related entries but has no effect on fields in the report module itself.

In the Toolbar of the List Definition you can further specify Selection Limits (currently not Supported

that will follow in the next release!), the form of the Output (which we will cover later) and the

Format (Portrait or Landscape) of the PDF Output.



Screenshot 11 - Definition of Sort Sequences and optional Fields

To Change the Sequence of the Fields in which they are shown on the Report select any of the fields

and use the Buttons to move the Field in the List either up or down changing the Sequence. To

delete a Field from the List select the Field and push the Button.

To add a link in the Report for a specific List field select yes in the Link column. During rendering of

the report a link to the object and the specific record will be added dynamically allowing you to jump

directly to the record from the report results.

Save the Report by pressing the Save Button. The system will save the Report and take you in a next

step to the Results of the Report. The Result is shown in a Grid. At the right Bottom of the Grid the

number of found entries is displayed. The paging buttons on the left bottom of the grid allow to page

forward or backward or go to any specific page. Pushing the refresh Button will reload the list with

the current data in the system.

For our Report the Result is a list sorted by first account name and then last name. Emails addresses

are shown if available. To experiment with the option set the email address to required and see how

the result changes since then only records are displayed where the email address for the contact is

filled.



Screenshot 12 - Report Results (actual data grayed out)

Adding Dynamic Selection Options

Dynamic Selection Options allow you to create a report with all the details in the back but allow a

user during runtime of the report to change selected select criteria. You might e.g. prepare a report

for contact lists but add no specific criteria for the name selection and leave that up to the user to

enter or change when the report is executed.

To set the option for a dynamic selection edit the report and set the “allow edit” flag to yes for those

selection criteria that you want to be editable.

Screenshot 13 - setting selection criteria for dynamic editing



With doing that the dynamic options tab appears with the report results. It is folded by default but

can be unfolded with the arrow button on the right hand side of the panel.

Screenshot 14 - Dynamic Selection Panel

Unfolded the Options flagged as dynamic can be edited and with every change the report results will

update accordingly.

Screenshot 15 - Changing dynamic report options

kinamu reporter - sinergiacrmwiki.sinergiacrm.org/images/kinamu_reporter_manual_v1.5_part_1.pdfthe...

Documents