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

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

KINAMU Reporter v1.5 Beta

Page 2 of 40

KINAMU Business Solutions AG. All rights reserved

www.kinamu.com

April 2010

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.

KINAMU Reporter v1.5 Beta

Page 3 of 40

KINAMU Business Solutions AG. All rights reserved

www.kinamu.com

April 2010

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.

KINAMU Reporter v1.5 Beta

Page 4 of 40

KINAMU Business Solutions AG. All rights reserved

www.kinamu.com

April 2010

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.

KINAMU Reporter v1.5 Beta

Page 5 of 40

KINAMU Business Solutions AG. All rights reserved

www.kinamu.com

April 2010

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
Screenshot 4 - selecting a Report Module

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

KINAMU Reporter v1.5 Beta

Page 6 of 40

KINAMU Business Solutions AG. All rights reserved

www.kinamu.com

April 2010

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
KINAMU Reporter v1.5 Beta

Page 7 of 40

KINAMU Business Solutions AG. All rights reserved

www.kinamu.com

April 2010

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
KINAMU Reporter v1.5 Beta

Page 8 of 40

KINAMU Business Solutions AG. All rights reserved

www.kinamu.com

April 2010

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.

KINAMU Reporter v1.5 Beta

Page 9 of 40

KINAMU Business Solutions AG. All rights reserved

www.kinamu.com

April 2010

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.

KINAMU Reporter v1.5 Beta

Page 10 of 40

KINAMU Business Solutions AG. All rights reserved

www.kinamu.com

April 2010

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.

KINAMU Reporter v1.5 Beta

Page 11 of 40

KINAMU Business Solutions AG. All rights reserved

www.kinamu.com

April 2010

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.

KINAMU Reporter v1.5 Beta

Page 12 of 40

KINAMU Business Solutions AG. All rights reserved

www.kinamu.com

April 2010

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.

KINAMU Reporter v1.5 Beta

Page 13 of 40

KINAMU Business Solutions AG. All rights reserved

www.kinamu.com

April 2010

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

KINAMU Reporter v1.5 Beta

Page 14 of 40

KINAMU Business Solutions AG. All rights reserved

www.kinamu.com

April 2010

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 v1.5 Beta

Page 15 of 40

KINAMU Business Solutions AG. All rights reserved