JXCirrusDiary is a big database that contains a whole lot of time information. And what would a database be without the ability to run queries on it. So in true DB spirit, JXCirrusDiary provides query functionality.
The queries are defined in the database schema. If you are lucky enough to have had someone else create a couple of queries, you can just run them (see Running Queries) and even export them (see Exporting Queries).
If you want to create your own queries, you will need clamp your nerd hat firmly on your head. It would also help to read up a bit about the Database Schema - It will tell you a whole lot that you need to know about Object Specs and Variables.
Running queries is pretty simple. Just select the Query menu and pick the
query that you want (for mobile apps, this is under the button).
After it has run, a new tab will be opened with the results of the query displayed like a spreadsheet.
If you don't want that tab open any more, just select the tab (so
you can see the query results) and then select View -> Close
Tab (or
on the toolbar).
If you have made some changes to the diary since you ran the query, you don't need to close the query and re-run it. Just click on the query tab, and select View -> Refresh and the query will be re-run. Pressing F5 does the same thing...
The query results will be sorted in ASCII order on the first column (the same as text fields in Excel). If you want to sort on a different column, just click on the column header and the results will be re-sorted.
Clicking on any row will cause that entry to be selected in the rest of the diary.
Once you have run a query, you can export the results to a file.
To do this, click on the query tab, and select File -> Export -> Query. You will then be
prompted to enter a file name. Type the name of the file that you
want to save (and also pick its location), then press save.
Done! NOTE: iOS will not let you write out files,
sadly!
The queries are saved out as a CSV file (which stands for Comma Separated Values). This is a very basic but faintly handy format... You can load it into all sorts of other applications, like Microsoft Excel, Microsoft Access, Vim, Ed...
Queries return a table of results with:
Fields define the actual data from the database.
Entries are records in the database that match a set of conditions for the query.
A field is a column that appears in the results table. These columns can contain actual records from the matching entries, or values calculated by the system.
A field definition looks like this:
Field: Title=TITLE, Value=VALUE, From=TABLE, [TAG=VALUE];
Fields have 3 mandatory parts.
From=E+R
.
where R stands for Resources, or people).If field values contain more than one word, then they should be surrounded by quotes, for example:
Field:
Title="First
Name", Value=First_Name, From=E;
This field will show the value $<First_Name> as defined in your object spec.
Some field definitions can create several columns based on a range. The most common one of these is date ranges. The following defines a date range:
Field:
Title="%m-%y",
Value=ProjectPlannedPerResource, From=E+R,
RangeType=Date,
RangeStart="now
2AM",
RangeEnd="now
2AM +5 months",
TimeUnits=Hours,
RangeDiv="1
month";
The RangeType indicates that this is a date range. RangeStart tells which date to start at (this can be based on "now" or an actual date. RangeEnd says when the range ends. RangeDiv indicates the amount of time for each column. Field ranges are only available with the System Values listed below.
This query might produce the following:
Apr-11 | May-11 | Jun-11 | Jul-11 | |
65 | 5 | 16 | ||
62 | 3 | 16 | 14 | |
60 | 2 |
Conditions define which entries will appear in the results table.
Conditions have the general form:
Condition: CONDITION,
Value=VALUE, From=TABLE, [TAG=VALUE]
;
There are 3 mandatory fields:
Conditions have one of the forms:
Text="Bill"
).LessThan=10
returns
anything where the VALUE is less than 10).GreaterThan=10
).GreaterThan=10,LessThan=20
returns
anything with value between 10 and 20.Equal=12
). You can specify an
epsilon value for the match, for example Equal=12,Epsilon=0.01
will match between 11.99 and 12.01.Spec=Task
will match anything that has Task as a spec or has a spec that
inherits off Task. If you don't want inherited specs as well,
use the Exact keyword, for example Spec=Task,Exact=Yes
.It is possible to use a match against ALL fields in an object. To use this define Value="*". This is useful in combination with Regex conditions to search data. For example:
Condition:
Regex=".*Melbourne.*",
Value="*", From=E;
looks for any objects containing the word Melbourne in any field.
To make queries a bit more re-usable, it is possible to prompt users to enter values that can be used for the query.
Prompt:
Title=Name,
Value=Geoff;
This will pop up a form that will display the field "Name" with a default value of "Geoff" (the default does not have to be supplied).
This is how the prompt gets used:
Condition:
Regex=".*$<Name>.*", Value="*", From=E;
Prompt:
Title=Name;
This will search all fields for a match against name.
Most query fields use the variables from the object specs that you are querying. JXCirrus Diary provides some extra values from the system which are based on data from the entries, but not actual variables. This defines some of the system values that can be queried. These can be used in both Fields and Conditions.
These system values take a number of qualifiers, which change how they are presented.
They also need to know which tables (or data types) they come from. The choices that you have for this are:
Depending on the value you are getting back, you must use the correct value for "From Tables". They are listed next to each of the values.
Anyway, this is horribly hard to explain, and so it is much easier with an example...
This query will show the amount of planned time for each project for each person. This is a condition for greater than 0.1 days planned during the next 18 months.
Condition:
GreaterThan=0.1,
Value=ProjectPlannedPerResource, From=E+R,
End="now 1st 2AM +18
months",
Start="now
1st 2AM";
This displays the results of this as a breakdown for the next 18 months.
Field: Title="%b-%y",
Value=ProjectPlannedPerResource, From=E+R,
RangeType=Date,
RangeStart="now
1st 2AM",
RangeDiv="1 month";,
RangeEnd="now
1st 2AM +18 months";
Value | Description | From Tables | Qualifiers |
ProjectSpent | The amount of time spent working on a each task entry. | E | TimeUnits, WorkHours, Start, End |
ProjectRemaining | The amount of time remaining for a task. | E | TimeUnits, WorkHours |
ProjectDuration | The total duration of a task. | E | TimeUnits, WorkHours |
ProjectActivityPerResource | The amount of time spent + the amount of time planned for each task per person. | E+R | TimeUnits, WorkHours, Start, End |
ProjectSpentPerResource | The amount of time spent for each task per person. | E+R | TimeUnits, WorkHours, Start, End |
ProjectPlannedPerResource | The amount of time planned for each task per person. | E+R | TimeUnits, WorkHours, Start, End |
ProjectStart |
The start date of the task/project. |
E |
|
ProjectEnd |
The end date of the task/project. |
E |
|
ProjectDue |
The calculated due date of the task/project
(takes dependencies into account) |
E |
|
ProjectMustStart |
The date that a task must start by. |
E |
|
ProjectIdealStart |
The date that a task should start by in order
for everything to finish on time. |
E |
|
ResourceLeave | The amount of time a person is on leave. | R | TimeUnits, WorkHours, Start, End |
ResourceFreeTime | The amount of unallocated time for a person. | R | TimeUnits, WorkHours, Start, End |
ResourcePlannedTime | The amount of planned time for a person. | R | TimeUnits, WorkHours, Start, End |
ResourceWorkHours |
The number of work hours available that day. |
R |
TimeUnits, WorkHours, Start, End |
Let us imagine that we have an Object Spec that defines a person (say in an addressbook). It might look like this:
$<FirstName>
= prompt();
$<LastName>
= prompt();
$<FullName>
= eval("$<FirstName> $<LastName>");
$<Phone>
= prompt();
$<Address>
= prompt();
We could display an addressbook table for them like this...
Field:
Title="Last Name", Value=LastName, From=E;
Field:
Title = "First Name", Value=FirstName, From=E;
Field:
Title = "Phone Number", Value=Phone, From=E;
Condition: Spec=Person,
From=E;
Field: Title = "Address",
Value=Address, From=E;
Let us imagine that we have a Project spec that defines details of a project... It could be broken down into any number of sub-tasks.
This is a query that displays the time spent and the time planned for each person.
# The
first column will be the name of the person.
Field:
Title=Person, Value=Resource, From=R;
# The
second column will be the name of the project.
Field:
Title=Project, Value=Project, From=E;
# The
third (and onwards) columns will be the number of hours
# to be
worked or already worked on that project per month.
# - The
title will be "Month-Year" (see C-style date formats).
# - The
value it reports is ProjectActivityPerResource
# - The
data comes from a combination of project Entries (the
# actual
projects), and Resources (the people).
# - We
are breaking this down into a date rabnge.
# - We
will report in hours.
# - We
start 12 months ago.
# - We
finish in 12 months time.
# - We
break down the time by months.
Field:
Title="%b-%y", Value=ProjectActivityPerResource, From=E+R,
RangeType=Date,
RangeStart="now
1st 2AM +-12 months",
RangeEnd="now
1st 2AM +12 months",
TimeUnits=Hours,
RangeDiv="1
month";
# We will
only report on specs of type Project.
Condition:
Spec=Project,
From=E;
# The
person must have worked more than 0.5 hours on that project
# during
the reporting period.
Condition:
GreaterThan=0.5,
Value=ProjectActivityPerResource,
From=E+R,
TimeUnits=Hours,
End="now 1st 2AM +12
months";
Start="now 1st 2AM +-12 months",
If we wanted to display the amount of unused time for each person on our staff (from the JXCirrus Project samples).
# The
first column will be the name of the person.
Field:
Title=Person, Value=Resource, From=R;
# The
second (and onwards) columns will be the number of hours
# that
the person could be working, but are not assigned to any
# work.
# - The
title will be "Month-Year" (see C-style date formats).
# - The
value it reports is ResourceFreeTime
# - The
data comes the Resource table only.
# - We
are breaking this down into a date rabnge.
# - We
start this month.
# - We
finish in 12 months time.
# - We
break down the time by months.
Field:
Title="%b-%y", Value=ResourceFreeTime, From=R,
RangeType=Date,
RangeStart="now
1st 2AM",
RangeEnd="now
1st 2AM +24 months",
RangeDiv="1
month";
# This
makes sure the person is actually working during that time
# period
(otherwise, you would end up reporting on people who have
# left
the company).
Condition:
GreaterThan=0.1,
Value=ResourcePlannedTime, From=R,
Start="now
1st 2AM",
End="now
1st 2AM +24 months";
# This
only reports on people who have more than 0.1 days of free
# time
during the period.
Condition:
GreaterThan=0.1,
Value=ResourceFreeTime, From=R,
Start="now
1st 2AM",
End="now
1st 2AM +24 months";