Uploading a BIRT Report

BIRT is an acronym for Business Intelligence and Reporting Tools, it is an open-source program that works inside Eclipse. As of HoudiniESQ version 1.8 you can upload and run custom reports generated with BIRT in HoudiniESQ. This Knowledge Base article will instruct you how to take an already existing BIRT report and add it to the report section in HoudiniESQ. 

In the ribbon that appears at the top of the screen in HoudiniESQ you will see four ribbons, Practice, Billing, Reports, and Settings. To upload a Birt report click on the Settings button.

Inside Settings we are interested in the column called Data and the text 'Report Mgr'. Important Note: In order to see this you must have admin access to your instance of HoudiniESQ!

Once the Report Mgr button is clicked a new window will appear. This is your Report Manager window, it allows you to upload, edit, and delete BIRT reports from HoudiniESQ. Every BIRT report saved in HoudiniESQ will be listed here. The four columns of information below are the default columns that display information about each one of your reports. The 'Name' column is a title you will assign for the report, the 'Report' column is the literal file name of the report as it is named in BIRT. 'Menu' will either state Reports or Billing, this indicates whether a BIRT report will be made available in the Reports ribbon or the Billing ribbon. 'GroupAccess' refers to what groups have been given permission to run the report. More columns can be added by clicking the gear icon adjacent to the drop down displaying the text default. The bottom left of the Report Manager window has an 'add' and an 'edit' button. To populate Houdini with BIRT reports click the 'add' button. 

TIP: If you ever see the Name column in the Report Manager window appear as #8888FF, or some other series of characters you did not enter, hold down the shift key and click on the refresh icon (the arrow that is in a circle).

After clicking the add button the Report Editor will appear. This window allows you to upload new BIRT reports and edit existing ones already in HoudiniESQ. The first thing to do when adding a new report is to click the 'upload BIRT report' button.

Prior to clicking the button you should already have created or downloaded a BIRT report specifically made for HoudiniESQ. All reports for BIRT end with the file extension '.rptdesign'. Clicking the button brings the Bulk File Uploader window up. This is a HoudiniESQ tool for importing various documents into the program. While the tool can be used to upload multiple documents simultaneously, it is recommended that you only upload one BIRT report at a time. The 'add files' button at the bottom of the window lets you search your computer for Birt reports

Once you have clicked the report you want, the title of it will appear listed under File. Click the 'save/upload' button to return to the Report editing window.

In the Report Editor window you can now select several options for your report:

1. Display Name     2. Access by Group     3. Menu Placement     4. Description     5. Color code     6. Report Parameter Name     7. Label    8. Control Type

1. The textbox titled 'Display Name' is where you give your report it's name. This name is what all the other staff members will see it displayed as in the Reports ribbon or Billings ribbon.

2. The 'Access by Group' dropdown allows you to select specific members of your staff who can run the report, example; if the report contains client billing information assign it to the billing group. Further information on staff groups and how to assign them and create your own can be found here, Staff Roles and Staff Group Memberships. Leaving this drop down blank will allow the report to be accessed by all groups and staff members.

3. 'Menu Placement' refers to which ribbon the report will be listed in. There are two options, Reports for the Reports ribbon and Billing for the Billing ribbon.

4. The text box below Menu Placement and Access by Group is for a description. This is optional, if you choose to add a desription for a report it will appear in the Report Manager window IF you add the Description column to that window (which can be done by clicking the gear icon). Description does not display in the Report Window by default.

5. HoudiniESQ allows you to color code matters, events, and now reports. Clicking on the colored square icon will bring up an assortment of colors to choose from. 

6. Parameters are an important part of BIRT reporting. A parameter is simply a variable; in BIRT you can set up specific parameters that the user (the person who runs the report) can enter prior to running it. This allows the report to focus it's output into something that can be more meaningful and/or specific. The three columns Report 'Parameter Name', 'Label', and 'Control Type' are all related. Think of a parameter as a variable. Instead of getting a list of all every matter you have have saved in HoudiniESQ, you can use generate a report that includes two date parameters, one for a beginning date, the other for an end date. The user can enter whatever date values he/she wishes to enable the report to specifically show the information they wish within a chosen time frame.

     a.Where BIRT parameters come from: All BIRT reports are generated in Eclipse. If you create your own reports you will do so in Eclipse. A BIRT report that is a work-in-progress may look something like this.

The above screenshot is Eclipse's BIRT tool for creating reports. If you plan on making your own in the future you will be become very aquainted with this program. The purpose of the screenshot is to explain where a parameter comes from in BIRT and why you need to know it for HoudiniESQ. Notice the indention with the two listings on the left. They are { } startParam and { } endParam. These are two parameters created for this report. If you upload a BIRT report to HoudiniESQ you need to know if it has parameters! This information needs to be provided to you from the source that has given you the report.

     Parameters are defined and named in Eclispse's BIRT tool by the report creator. All parameters must correspond to one of six categories. Staff, matter, contact, text, date, and check box. Staff is simply the name of a person who is denoted as a staff member in HoudiniESQ. Having this parameter added to a report allows the report to be filtered to include results correlated with a chosen staff member. Matter is a listing of matters in the program and, like the staff parameter, this allows you to select a single matter to focus on in your report results. Contact refers to all the contacts saved in Houdni and date means that a date may be entered; text and checkbox do not refer to any field specifically in HoudiniESQ. Text means that a user can enter any text string and use that as a variable to search for matches (example: if you want to search for a billing amount that exceeds $10,000.00, have the user enter a numeric entry in a text category) and checkbox is a 'yes or no' (boolean) criteria.

     b. What you need to know about parameters when upoading a report: If your report contains parameters, you must enter them verbatim in the 'Report Parameter Name' column! Not doing so will generate an error at runtime. Bascially, the { } startParam and { } endParam seen in the screenshot above must be entered as startParam and endParam in the Report Editor (the wavy brackets are excluded).

7. The next column, 'Label', is what the parameter will be called when the report is run. It needs to be descriptive so any staff memeber can easily understand what he/she is being asked to enter. Example, a label for a staff parameter could state, "Select Staff Member", and a text label meant to correspond with a revenue amount could state, "Enter Minimum Monetary Amount". The example below includes two date parameters, one for a beginning date and another for an end date. 

8. Once you have entered descriptive labels pick the 'Control Type'. For the example above Date will be selected for both of them since the parameters are date variables. If the parameter is a staff parameter, then you must chose Staff. The same applies to Contact and Matter parameters. Once this is done and you are sure the information has been entered correctly, click the 'save' button. The Report Editor  will disapear and you will be back at the Report Manger window (unless you closed it earlier).

Editing and Deleting a BIRT Report

If you need to edit a BIRT report already in HoudiniESQ you begin by clicking the Settings ribbon and then Report Mgr in the far right. This will bring up the Report Manager window and a listing of all BIRT reports currently in HoudiniESQ. From the Report Manager window click on a report Name to hightlight it, then click the 'edit' button at bottom left of the window. 

All the options that were available when uploading a report are also present when you edit it. If you entered in the 'Report Parameter Name' incorrectly or you want to assign the report to a specific group, this can be done in the Report Editor window. Once you are finished making modifications, click the 'save' button. To delete a report, click the 'delete' button. A confirmation window will appear asking you to to confirm. Click 'OK' and the report is gone.