3K Report Tool
Administration database, User Guide
Version 14.1
Date of version: December 5th 2013
Table of Contents
What's new
3
Setting a report definition
3
Create a definition from a view
Creating new definition from existing one
Edit, add, delete and move fields
Default settings
Linked documents
Rights for using a report
Organize reports to folders
4
4
5
6
6
7
7
Scheduled reports
9
Enable running of schedule reports
Schedule reports running properties
11
11
License management
12
Customer data
License ordering
Licenses activation
Licenses deactivation
Manual license entry
12
12
13
14
14
Other settings
16
Modules
Users
Distribution modules
Managing access rights
Managing errors
Upgrade version 10.x to 14.1
16
16
16
17
17
17
2
What's new
Version 14 brings the following main improvements:
 Schedule reports. Schedule reports allow automatic periodical report generation, which
saves user time for complex reports and also enables possibility to prepare Lotus Notes data
for export to other systems. Scheduled reports
 Organize report definitions and saved reports to folders. Folders make access to reports
easier and more transparent. Organize reports to folders
 Improved license management. New version allows getting the license by email and manual
license entry. Therefor license can be activated also when internet connection is not
possible. Manual license entry
 Additional options for report definitions: creating new definition from existing one (Creating
new definition from existing one), changing column positions on definition (Edit, add, delete
and move fields) and setting number of default graph categories (Default settings).
Setting a report definition
Report definition provides the selection of Domino documents and data definitions to be used in a
report. Steps for creating a report definition:
1 In Administration database select view Settings > Report definitions.
2 Select view action »Add definition > New definition«.
3 You get a input form with following fields:
General
Identifier
Title
Search modules
Search formula
Date filter field
Description
Unique report definition identifier. For example INV01 for report about
invoices.
Report title which will be presented to users when creating a report in a
client.
Domino databases where report searches for documents. It’s possible to
select more than one database. Databases are defined through modules check chapter Other settings > Modules.
DB search formula for getting Domino documents to be included in a
report.
Date field for limit search formula. Date period is selected by user when
creating a report in a client. Date field must be defined among the report
fields.
Default settings
Category 1
Category 2
Category 3
Category 4
Sum column
Description
Fields which set report settings when opening a report. For the meaning
check chapter Setting a report definition > Default settings.
Report fields
From 1 to 50 fields
Description
Definition of report’s data. For creating a data from an existing view check
the chapter Setting a report definition > Create a definition from a view. For
3
manual editing check the chapter Setting a report definition > Edit, add,
delete fields
4 You save the definition by clicking »Save« button. When saving a definition required fields are
checked. In learning about a report definitions we strongly recommend you to make some
definitions from existing views (next chapter).
5 After successful save the report in ready for use in Report Tool client.
Create a definition from a view
The fastest and easiest way of creating a definition is creating form a view. Steps to create definition
from a view:
1 Create new definition and select search module.
2 After you select a search module an action »Create from view« appears on a form.
3 After selecting an action you are provided with list of all Domino views in a selected module.
4 Select the view and confirm selection by clicking »OK« button. After confirmation search formula
and report fields are transferred on a report definition. Search formula is equal to selection
formula of a chosen view and report fields match view columns. Field name is equal to column
title, calculation formula is equal to column formula, data types and display formats are calculated
form column data. If a view column is categorized, categorization is set to »Yes«.
Creating new definition from existing one
If you are creating a definition similar to existing definition, you can create new definition based on
that one. In view Settings > Report definitions select definition from which you want to create new
definition and select an action »Add definition > Add from existing«.
Action creates new definition with all data as on selected definition except definition id and title. On
new definition first enter id and title and then make appropriate changes.
4
Edit, add, delete and move fields
You can edit, add, delete or move fields by clicking an arrow
entered you will get the following options:
Option
Edit
Delete
Insert
Move up
Move down
Move to…
by field name. If field is already
Description
Editing data already defined for a field.
Deleting a field.
Inserting field before the selected field. The order of the fields is important
because the fields in the report appear in the same order as defined in
definition.
Moving field up for one position.
Moving field down for one position.
Moving field to selected position.
If you select an arrow by undefined field (last one), click means you are adding a field. When adding,
editing or inserting a field you will be provided with the following dialog box:
Field
Field name
Calculation formula
Data type
Display format
Description
Field name as it will appear on the report.
Formula to calculate field value in Lotus Domino @formula language.
Formula is calculated in a context of a found document. If formula
evaluation returns table, only a first value is included in report. If you want
all values of a table to included use @Implode function.
Field’s data type. Possible values are string, date or time (dateTime) and
number (double).
Defines the way dates and numbers are displayed. For example display
5
Categorization
Filter
Programmatic name
numner with 2 fixed decimal places. Field has no meanings with strings.
Select »Yes« if you want to categorize data by that field.
Select »Yes« if you want to filter data by that field.
Specify the programmatic name only if you want to use the field value in a
calculation formula of another field. The programmatic name should always
start with a $.
Default settings
By default settings you choose report settings when opening a report. In category fields you can use
those fields which have categorization value set to »Yes«. Definition has to have at least one default
category. Fields defined as categories and not used in default categories can be used for
categorization in client.
Field »Number of graph categories« states how many categories are shown in graph when report is
created. Default value is 12, entered number must be between 1 and 30 categories. In client user can
afterwards change this settings.
Field »Sum column« states which number field is used to sum up values in categories. You can use all
numeric fields or a value »Number of documents «. Selecting »Number of documents « means that
every Domino document will count as value 1. By the sum column there is a field to determine sum
function. Available values are Sum, Average, Percent and Percent in category.
Linked documents
Using linked documents you can include data that is not stored on a document found by search
formula (source document). The document from which we calculate further information must be in
conjunction with the source document (foreign key). Linked documents are of course not mandatory.
By using linked documents we can merge data from two different Notes documents in a single row
which can’t be done by using a Domino view. Compared with the commands in relational databases,
linked documents represent the equivalent of SQL JOIN sentence.
You include linked documents by choosing the field »Linked documents«.
Field for linked documents definition:
Field
Link module
Link view
Link formula
Link not found
Report opens
Description
Module where we search for linked documents. It can be the same or
different than module for source documents.
Domino view where we search for linked documents. View must have
contain linked documents and must have first column sorted by the value
from source document. Linked documents are searched by using a method
»GetAllDocumentsByKey«. If where are more linked documents found, they
are all included in a report – every document in a separate row.
Formula to calculate key in a Lotus Domino @formula language. Formula is
calculated in a context of a source document. Result of formula evaluation
is used as a key in searching a linked view.
Defines what to do if linked documents are not found.
Available options:
 Error by report execution. Terminates report execution.
 Document not included in report. Source document is skipped.
 In report include only documents without link. Only documents
without linked documents are included in a report.
Defines which document to open when selecting detail row in a client.
6
Fields order
Include condition
Available options:
 Source document.
 Link document.
Defines weather fields from source or link document appear first in a
report.
Available options:
 Fields from source document first
 Fields from link document first
If field is empty, all linked documents are included in a report. If we want
only certain link documents to be included, we can define include contition
in a Lotus Domino @formula language. Formula is calculated in a context of
a link document.
Fields from linked document are defined in the same way as for source document fields. Editing,
adding and deleting fields is the same as when defining source fields. Fields from linked documents
can also be used in default settings. Fields from linked documents can be populated from a view by
action Create from view > Fields for link document.
Rights for using a report
By default report can be used by all Lotus Domino users for whom Report Tool user license is
activated. Report definition can be limited only for a certain users by deselecting a field Report
access rights > All users.
In such case report users are defined in a field »Users«, where you can choose users or groups form
Domino address book.
Organize reports to folders
To improve transparency report definitions can be organized in folders. Folders are used in client
when creating new report. On report definition folder is set by action »Manage folder > Set folder«.
In dialog box enter folder and subfolder names:
You can enter five folder levels which must be entered in succession. Folder is set by confirming the
dialog window. Folder is deleted by action »Manage folder > Delete folder«.
Actions to set and delete folders are also available in view Settings > Report definitions. View actions
allow setting or deleting folders on more definitions at the same time.
7
Folders are also available for saved reports. Folders on saved reports are defined when saving
reports in client, but can also be changed by administrator n administration database. Managing
folders for saved reports is available in view Settings > Saved reports, by actions Manage folders > Set
folder, Delete folder. Organizing saved reports to folders make sense also when upgrading to version
14.1 since previous versions didn’t support folders.
8
Scheduled reports
Schedule report allows automatic report creation on server side. After creation report is available for
usage in client without waiting for data building. We can define unlimited number of scheduled
reports where every single one has its own building frequency. Steps for creating a scheduled report:
1 In Administration database select view Settings > Scheduled reports.
2 Select action »Add schedule«. Option »New schedule« creates new schedule, option »Add form
existing« creates schedule based on selected one.
3 To determine report data fill up fields in table »General«:
Field
Report definition
Start of the period
End of the period
Save report
Report saved name
Use folder from definition
Folder formula
Description
Selection from existing definitions. Determines definition to be used in
report creation.
Fields are available only for definitions with set date filter. Fields start and
end of the period are used for calculation of date filter period based on
report creation time. Available options:
 Today. Start/End of the period is date when report is created.
 Yesterday. Start/End of the period is on day before date when
report is created.
 Current week, Previous week. In this case is necessary to select
day in a week which sets start/end of the period.
 Current month, Previous month. In this case is necessary to select
day in a month which sets start/end of the period. It’s possible to
select first or last day in a month or exact day, for example 15.
 Current quarter, Previous quarter. In this case is necessary to
select start or end of the quarter. Dates 1st of January, 1st of April,
1st of July and 1st of October are considered as start of the
quarters.
 Current six months, Previous six months. In this case is necessary
to select start or end of the six months. Dates 1st of January and
1st of July are considered as start of the six months.
 Current year, Previous year. In this case is necessary to select start
or end of the year. 1st of January is considered as start of the year.
 Fixed date. In this case is necessary to select exact date.
 Date is not defined. This means that start/end of the period is not
set.
Field sets if the report is saved to database or not. Typical selection is
»Yes«. Option »No« is meant for cases where we only want to export build
report.
Field is available only when report is saved. To calculate the name you can
use tags which depend upon run time, start and end period. Detailed tags
description is available on definition form.
Field is available only when report is saved. When selected report will be
saved on the same folder as definition.
Field is available only when report is saved and the file » Use folder from
definition « is not selected. In field you can use Lotus Notes formula to
calculate folder. In formula separate folders with »\\«. The calculated value
can also be a new folder.
Formula example: "Maintenance requests\\" + @text(@year(@today)) +
9
"\\" + @right("0" + @text(@month(@today));2)
In case report is built in November 2013 report will be saved in folder
»Maintenance requests« - »2013« - »11«.
In case that evaluation of folder formula is not successful report is save
anyway to the root folder.
4 To determine report schedule fill up fields in table »Running schedule«:
Field
Running is enabled
Schedule
Don't run on weekends
Description
Field to enable or disable building a report.
Field to set the running frequency. Available options:
 Daily. In that case is necessary to set running time. It’s optional to
set additional running times which means building of the report
more than once a day.
 Weekly. In that case is necessary to set day in a week and running
time. Report will be built on all selected days in a week.
 Monthly. In that case is necessary to set months, day in month and
running time. Option »Run on all months« means that report will
be built every month. If option is not selected, running months are
selected in field »Run on selected months«. For day in a month we
can select first, last or exact day in month. It’s possible to select
more days. Report will be built on all selected months and days in
months.
If selected report won’t be built during weekeneds.
5 To determine export options fill up fields in table »Report export«:
Field
Export filename formula
Send by email
Description
If entered built XML file will be saved to working station/server where
schedule agent is running. In formula divide folders with »\\«.
Formula example: "c:\\reports\\" + @text(@year(@today)) +
@right("00"+@text(@month(@today));2)
+@right("00"+@text(@day(@today));2) + ".xml"
In case schedule is running on 19th of November 2013, report will be saved
to file »c:\reports\20131199.xml«.
In case that evaluation of export filename formula is not successful report
won’t be exported. For successful export calculated folder must exist on
working station/server where schedule agent is running.
If entered built XML file will be sent to entered email address. Email must
be entered in an internet form.
Both export options are in the first place meant for integration with other IT systems. Exported data
is stored in a XML file, which contains schema and data. For detailed explanation of exported XML
structure, please contact us on [email protected].
6 In case built report is saved to database users to access report are set in an table »Report export«:
Field
Users from definition
Users
Description
If selected all the users who can access report definition can all access built
report.
Field is available only when users to access built report defers from users of
report definition. Access to build report is granted to users and NAB groups
selected in a field.
7 Schedule is saved by action »Save«. When saving a schedule, required fields are checked.
10
8 After saving report schedule is ready for running. More about running schedule reports is stated
in following chapters.
Enable running of schedule reports
Running all schedule reports is done by Lotus Domino agent named »runScheduleReports«. Steps to
enable running schedule reports:
1 Open administration database in Lotus Domino Designer.
2 Select »Shared code\Agents« and select an agent »runScheduleReports«.
3 Select action »Enable«. In as dialog box select server to run an agent. Agent has to be signed with
a user with rights to run restricted LotusScript/Java agents. You can check the signer rights by
right click and select an option »Test«.
4 After agent is enabled select agent properties, tab »Design« and select »Prohibit design refresh or
replace to modify«.
By default schedule of Lotus Domino agent is set to every hour. Of course you can change it
according to your needs. When changing the schedule of Lotus Domino agent please consider
running properties described in a following chapter.
Important. To run properly agent’s property »Set runtime security level« must be set to »2. Allow
restricted operations«.
Schedule reports running properties
By running scheduled reports please consider the following:
 When Lotus Domino agent »runScheduleReports« is triggered it checks all schedule reports
and for each one determines if it has to be run or not. For running a schedule report the
report has to be enabled and the run time must be greater than time set on a schedule
document. Example. Schedule defines that report is built daily on 10.30. If Domino agent is
triggered at 10.00, report won’t be built, if triggered at 11.00 it will. After each report built
time of last execution is written on a schedule. Schedule is considered only when Domino
agent is running on server. When running on local all enabled schedules will be built without
modifying time of last execution. Running an agent locally is primary meant for testing
purposes.
 When running an agent on a server please consider that agent is run with signer rights. In
report there will be all the data which agent’s signer has the rights to access. All users with
access to report will see all built data even if they otherwise don’t have the rights to access
this data in Domino database.
 When exporting report to file please consider that agent is running on server there for file
path should be adjusted to server file structure.
11
License management
Customer data
You can edit the license data by selecting an action »Customer data« in a view Settings > Report
definitions.
Customer fields are divided in section Contact data, Billing data and Administration. Contact data
fields are by default populated with values entered in a registration form. Fields can be further
updated, changes will be synchronized with 3K IT every time when any license action is selected.
Contact data
Customer id
Organization Name
Contact Name
Job title
Email Address
Phone
Fax
Description
Your customer id, provided by registration.
The name of your company/organization.
Your name and surname.
Your job title.
Your email address. On that email you will receive any information
regarding 3K Report Tool product.
Your telephone.
Your fax.
Billing data
Address 1
Address 2
Town / City
Postal code
State
Country
Tax number
Description
Fields to be entered prior to making an order. Fields are used when sending
you an invoice.
Administration
Number of users
Description
Number of entered users. For managing users check chapter Other settings
> Users.
Administration user. User defined in this field can use product and doesn’t
count in defined users. It’s possible to enter one administration user.
Settings how client upgrades are made. Available options:
 Auto update. Clients are upgraded automatically when new
version is available on 3K IT web page.
 Manual. Clients are upgraded manually using an installation file.
Admin user
Clients upgrade
License ordering
After termination of 30 days evaluation period product can be used only by full license. Full license is
tied to the number of names users. Every named user requires one full license.
Working with licenses requires Internet connection. If you are using a proxy server, you should fill out
fields in »Proxy settings« section.
Steps for making an order:
12
1 Select action License > Order.
2 After selecting an action you get a dialog box:
3 Enter a number of licenses you want to order in a »Number of licenses« field. Confirm the input
by clicking »Order« button. After action is complete you will receive a pro forma invoice to your
email. Activation of new licenses is possible after payment is received.
Licenses activation
You activate licenses by selection an action License > Activation.
Activation type
Evaluation license
Full license
Developer license
Description
Meant for using a product in an evaluation period.
Meant for using a product afer termination of evaluation period. Acivation
is possible after receiving payment for an order. Number of activated full
licenses determines how many users can use a product.
Developer license is meant for partner companies. Partner companies are
13
entitled to resell licenses to third parties. If you are interested in a 3K
Report Tool partner program please contact us on [email protected].
Data about current license state are always available in License section. History of licenses request is
available in License history section.
Licenses deactivation
If you want to move Administration database to another location, you should first deactivate licenses
used by current Administration database. You can do this by selecting as action License >
Deactivation.
After deactivation the number of entered licenses will become free and you can use them in another
Administration database. You can use unlimited number of Administration databases as far as sum of
activated licenses in all Administration databases don’t exceed the number of all purchased licenses.
You can synchronize the state of licenses for current Administration database by selecting an action
License > Synchronize license.
Action License > License information returns information about licenses for all your Administration
databases.
Manual license entry
The way of exchanging licenses is determined by field »Communication type«. Available options:
 Internet. By this option license requests are exchanged through internet, requests are
processed immediately. To use this option computer, from which licenses are managed, must
be connected to internet.
 Email. By this option request is automatically send by email. After the request is processed
you will be informed by email. Returned email contains response, which must be manually
entered (description below).
 Manual. By this option you will get the dialog windows with license request. The license
request must be copied into an email message and sent to [email protected]. Mail subject
must be »License request«, because this subject guarantees automatic processing. Returned
email contains response, which must be manually entered (description below).
14
License from returned email is entered my action License > Manual entry. After processing license
history log is created, the same as when using internet communication type.
15
Other settings
Modules
Module documents contain information about Domino databases where reports search for
documents. Before Domino database can be used in a report definition it must be entered as module
document. Steps for creating a module document:
1 Select view Settings > Modules
2 Select view action »New module«.
.
3 Fields on module form:
Field
Identifier
Description
Server access
Serverand Path
Local access
Serverand Path
Description
Unique identifier for module document.
Module description meant for easier module management.
Domino server and path for Domino database. You can enter fields
manually or select database with clicking an arrow .
In case database is on local you have to enter those two fields.
Users
All Report Tool users must be added to a list of users. In evaluation version you can enter unlimited
number of users. When using a full version the maximum number of users is equal to the number of
activated licenses. Steps for creating a user document:
1 Select view Settings > Users.
2 Select view action »New user«.
3 In the field »User name« select user from Domino address book.
4 Select actions »Save« and »Exit«.
You can enter multiple users by selecting a view action »Import users«. In a dialog window select all
users and confirm selection.
You can delete users by selecting a view action »Delete users«.
Distribution modules
You can run 3K Report Tool from any Domino database. Database from which you want to run a
report must be first entered among modules. Next step is to create a distribution module document.
Steps for creating a distribution module document:
1 Select view Settings > Distribution modules.
2 Select view action »New distribution module«.
3 In a field »Distribution module« select module where you want to run a report.
4 Select action »Save«.
5 Select action »Copy design«. Action will copy all necessary design elements into a target database.
For successful execution you need at least Designer access rights in a target database.
After copying a design you have to open a target module in a Domino Designer. Add an action on a
form or view where you want to run a report. Set action label to »3K Report Tool« in implement the
following action formula:
@Command([ToolsRunMacro];"3KreportTool").
16
Managing access rights
For production use you have to set proper access rights for Administration database (ACL).
Steps for setting access rights:
1 Select view Settings > Report definitions
2 Select an action »About application«. Action is located on the right side of the action bar.
3 Section »Access rules settings« defines access rules.
4 Open Access Control List (ACL) of Administration database and set the access rights.
Managing errors
All errors which occur when using an application are logged in a view Administration > Error log. In
case of problems please send us the corresponding error log which will help us when solving a
problem.
Upgrade version 10.x to 14.1
To upgrade administration database to new version please follow these steps:
1 Open new administration database to local Lotus Notes »data« folder.
2 Sign the database in Domino Administrator client.
3 Match design names of previous and new version and refresh design.
4 (Optional) In case you are going to use schedule reports enable agent for running schedule
reports. Enable running of schedule reports
5 (Optional) If you want to organize report definitions and saved reports to folders, please follow
the description in chapter Organize reports to folders.
6 For all modules, where 3K Report Tool is distributed, code must be refreshed. Select view Settings
> Distribution modules. Open each distribution module and select actions »Edit« and »Copy
design«.
7 To use the client version 14.1 is required. If your clients are not upgraded automatically, you must
manually install new client version.
17