How to define a custom report in v3

There are 2 ways to generate a report on a project. One is to right-click on a project and select "Reports", and the other is to select from the File menu: File -> Menu -> Custom Reports and then select the type of report you want and its subject. For example using File->Export we can select a "Work Log" report for a person or a task.

What if the report we want isn't in the list? Can you write your own report template? Yes you can - that's what this article is about.

Let's say I want a report on a task in the project. I need to define an "Action" in the process I'm using, identify that action as an "Export Action" (checkbox in the Action dialog) and define the file extension for the report. Let's say in this case we want an html file. You can see in the screenshot this action being defined. Note that the "Applicable to:" field has been filled in as "Task" and also the "Expression:" field has been given the value "name". This won't be a terribly fascinating report but even so let's run it!

Use the File-> Export-> Custom Reports menu and select one of the tasks in your project as the subject of the report. Once you've supplied a filename and pressed "Finish" you should find that a browser is launched and a page generated containing the name of your task. Congratulations you've generated your first xProcess custom report!

So what about doing someting a bit more interesting. As you've probably guessed by now that will mean looking in a bit more detail at the "Expression" field. The script that goes in this field must be written in OGNL so you need to know a bit about that language - if you'd like to read the (quite small) reference manual click here - and a little bit about the xProcess Java API. (You'll also find the OGNL reference manual in the xProcess Help documentation.)

So let's try a slightly larger bit of OGNL to generate our task report. How about this:

'<h1>' + name + '</h1>' + '<br>' +
description + '<br>' +
'Start: ' + start + '<br>' +
'End: ' + end50 + '<br>' +
'Closed?: ' + closed

You could even turn this into a report on all tasks in your project. First change the "Applicable to:" field to "Project" (this will also mean you can invoke it by right-clicking on your project) and turn the above code into a subroutine that can be called for every task. Like this...

#taskReport = :[
#output = #output +
'<h1>' + name + '</h1>' + '<br>' +
description + '<br>' +
'Start: ' + start + '<br>' +
'End: ' + end50 + '<br>' +
'Closed?: ' + closed
],
#output = '',
allTasks.{#taskReport(#this)},
#output

Browse other Actions in the predefined processes to see other examples of using OGNL. Then if you make a report you think others will find useful - or if you need help with syntax or the API - post it to one of the xProcess Forums on SourceForge. See xProcessForums.