User Guide

User Guide


Prerequisites

When using Horreum Project Budget Manager (Horreum PBM), you need no extra tools. It uses Jira’s time tracking. It reads worklogs of your users from Jira. It is important to point out that your data is safely stored in Jira and it won’t be altered by using Horreum PBM. 


As Horreum PBM is using Jira’s time tracking it may not work if you use a different time tracking tool.


To use reporting feature in Horreum PBM you should allow pop-ups in your browser (click on the report icon for the first time will make allowing pop-ups icon appear next to to the bookmarks icon; you have to do this only once)


Important notes

  1. If you're using Tempo Timesheets to log time on projects, Horreum PBM will not be able to read user's timelogs, and will not work.
  2. Horreum PBM is enabled to support Jira in German and Spanish language, and if you choose to view Jira in these two languages, Horreum PBM will be translated also. For more information on multi-language support click here.
  3. To use Horreum PBM with Jira next-gen projects, please enable time tracking for every Jira issue type in order for the plugin to work.


Step 1 - Installation


Visit Horreum Project Budget Manager in the marketplace at:

https://marketplace.atlassian.com/apps/horreum-project-budget-manager

                                                                                            Image: Horreum Project Budget Manager

Then click on the Get it now button to install Horreum PBM and start using your free app. You can also find Horreum PBM via the Jira Settings page and Atlassian Marketplace for Jira.  Just click on Find new apps and search the Marketplace for Horreum Project Budget Manager.

                 

                                                                                            Image: Find new apps

   

                                                                                            Image: Horreum Project budget Manager in Atlassian Marketplace for Jira 


Make sure you installed Horreum Project Budget Manager by checking the Manage Add-ons page at

https://YOUR_INSTANCE.atlassian.net/plugins/servlet/upm

                                                                                     

                                                                                            Image: The user-installed apps

Step 2 - Configuration


When installed, in the “Jira settings” page, by clicking on “Apps”(https://YOUR_INSTANCE.atlassian.net/plugins/servlet/upm),

you should be able to see a new item “HORREUM Project Budget Manager”.

In your project’s settings page HORREUM PBM - Settings will appear with the following sections available when clicked on:


Budget Project Settings

  • Enable Horreum PBM for the specific project
  • Set the budget and currency for your project and a few other useful options

Budget Project User Cost ​

  • Set/edit/delete the hourly rate of each user

Reporting Schedule

  • Choose which of your project administrators will receive the mail with the project budget report and when

Permission Manager

  • Choose who of your project administrators will have the permission to access the Horreum PBM add-on

Expense Categories Manager

  • Add/edit/delete the expense category

The expense category will be displayed as a new item in the table on the Expenses page and Report page. 


Step 3 - Enable your projects


In order for a project to appear in the Project Budget Manager report, you need to enable it.

Open your project and click the Project settings item at the bottom of Jira’s side menu.

                                                                                           

                                                                                           

                                                                                            Image: Project settings item

Scroll down and find the HORREUM PBM - Settings item. 

                                                                                            Image: HORREUM PBM - settings item

It is necessary to enable your budget tracking by clicking on the Track Budget slider. 

                                                                                            Image: Budget Project Settings Initially


When budget tracking is enabled the previously gray slider turns green and looks like this  .

After enabling budget tracking, there are 5 sections:

  1. Budget Project Settings
  2. Budget Project User Costs
  3. Reporting Schedule
  4. Permission Manager
  5. Expense Categories Manager


Budget Project Manager Settings


             

                                                                                            Image: Budget Project Settings

Project Name represents the project name, it is displayed automatically and cannot be changed. 


The Project Currency can be selected from the list of available currencies. 


It is possible to set Default Hourly Rate, which will be used if Auto Budgets is enabled for users who don’t have an hourly rate specified. If Auto Budgets is disabled, the default hourly rate won’t be used and worklog for users without a specified hourly rate will be multiplied by 0. Auto Budgets can’t be enabled or disabled until you set the default hourly rate. 


The Cost represents the project budget, and this field is optional. When you generate the report you will be able to see if you are on/off budget or on track. As defining budget is optional, the report will be generated only if a fixed budget is defined, otherwise, you will not be able to access the page where it is possible to generate reports. 


The possibility of inline editing of the Expenses page can be enabled/disabled by clicking on the slider next to Inline edit.


All of these parameters can be changed except the project name. 


If you try to change the currency, you will get the following dialog to confirm that you are sure about your decision, since if you proceed with currency change the currency will be changed but the cost values will remain in the previous currency.


                                                                                            Image: Warning dialog for currency change

Note: People must be added as project people for their name to appear in the user tables in the following sections Budget Project User Costs, Reporting Schedule, and Permission Manager. Also, their email must be visible to everyone.

To make your email visible to everyone, follow these steps:

1. Click on the icon with your avatar in the upper right corner and go to the Profile page

                                                                                            Image: Profile item 

2. Click on the Manage your account button

                                                                                            Image: Manage your account button

3. Change settings for an email address to Anyone

                                                                                            Image: The email visibility settings

Budget Project User Costs


After selecting the Budget Project User Costs section, a table with project users and their hourly rates is displayed. Horreum PBM allows adding multiple rates for a single user because the user’s rate may change over time. This way you will have a chronological overview of your project user’s rates for a better understanding and precise tracking of the project’s costs. Also, it is possible to edit and delete the hourly rate for the specific user. 

                                                                                           

                                                                                            Image: Budget Project User Costs


  • To add a new hourly rate for a specific user, click on Add button () for that user. This makes a new input field for an hourly rate, Add button and Discard button () appear.

                                                                                            Image: Adding New Hourly Rate


Enter the hourly rate value in the field and click on Add button, to finish with adding a new hourly rate. By clicking on Discard button () new hourly rate won’t be added, also input field for a new hourly rate, Add button and Discard button will disappear, and Add button will appear again.


  • To edit the hourly rate of a specific user, change the value in the specific hourly rate input field for that user, and then click on Edit button () for that hourly rate to save changes.
  • To delete the hourly rate of a specific user, click on Delete button () for a specific hourly rate for that user. This brings up a dialog to confirm hourly rate deletion. Click the Delete button to confirm the deletion or otherwise click the Cancel button. Make sure you really want to delete the specified hourly rate before proceeding.


                                                                                            Image: Hourly Rate Deleting Dialog

Reporting Schedule


After selecting the Reporting Schedule section, it is possible to specify who of the project administrators should periodically receive a report via mail and when (which days and at what time). Also, there is an option to select the type of file you want them to receive the report in: .xlsx, .pdf or both. The selected file type will be attached to the notification email. 

Fill in the Time field, enable days you want, enable administrators you want from the table of project administrators and click the Save button so that ones you chose could start receiving report via mail.

                                                                                            Image: Reporting Schedule

Permission Manager


After selecting the Permission Manager section, a table with project administrators which you can enable/disable is displayed. There is possible to set who of your project administrators will have permission to access the add-on pages. After enabling/disabling the administrator click on the Save button to save it changes. It is not possible to change permission to site-admins because they should always be allowed to access add-on pages. Also, it is not possible to change your permission.

 

                                                                                            Image: Permission Manager

Expense Categories Manager 


After selecting the Expense Categories Manager section, a table with expense categories is displayed. Horreum PBM allows adding, editing and deleting expense category. 

                                                                                            Image: Expense Categories Manager

  • To add a new category, click on the New category button. This will bring up the Add new category dialog. Enter the category name in the field and click on the Save button, to finish with adding a new category. By clicking on the Cancel button new category won’t be added.

                                                                                            Image: Adding New Category

  • To edit the category name, click on the Edit button for that category. The Edit category dialog is displayed. Enter a new category name and click on the Save button to save changes. By clicking on the Cancel button category name won’t be changed. 

                                                                                            Image: Editing Category

  • To delete the specific category, click on the Delete button for that category. This brings up a dialog to confirm category deletion. Click the Delete button to confirm the deletion or otherwise click the Cancel button. Make sure you really want to delete the specified category before proceeding.   

                                                                                            Image: Category Deleting Dialog

Step 4 - View the report


Once your project members have logged some hours on their tasks, you will be able to start monitoring the cost of your tasks and expenses in the Project Budget Manager Report.


In your Jira project sidebar, every project will have a new icon that opens the HORREUM Project Budget Manager - Report page.


Go to your project and find HORREUM PBM - Report icon in the left side menu. 

                                                                                            Image: HORREUM PBM - Report icon


Project budget, costs total and remaining budget are displayed in the report, as well as cost of expenses, individually and summed, and task costs, also individually and summed. There is a progress bar which color indicates if you are on/off budget or on track. If the progress bar is green: you are on budget, if it is red: you are off budget, while blue means that you’re on track.


                                                                                            Image: Budget Project Report


  • Budget

Represents a planned budget.


  • Budget consumption/costs total

Represents the budget that has been executed so far.


  • Remaining

Represents the total budget remaining.


Download report

There is a possibility to export the project budget report in the .xlsx and .pdf format. The buttons for exporting report are located in the most upper right corner of the report page. 

After clicking on the export to .xlsx button (), the report will be downloaded as a .xlsx file.

                                                                                            Image: Project Budget Report exported in .xlsx format


After clicking on the export to .pdf button (), a new tab will open in your browser with the .pdf version of the report. You can download the report in .pdf format directly from that tab.

                                                                                            Image: Project Budget Report exported in .pdf format


Step 5 - Log other expenses


In your Jira project sidebar, every project will have a new icon that opens the HORREUM Project Budget Manager - Expenses page.


Go to your project and find the HOREUM PBM- Expenses icon in the left side menu.

                                                                                            Image: HORREUM PBM - Expenses icon

Here, every project administrator can log his/her expenses. Each administrator can see his/her own expenses as well as the expenses of other administrators.

Expenses are summed and displayed in the report. Also, it is possible to generate a report for a specific user.

         

                                                                                            Image: Budget Project Expenses

Adding an expense


To add a new expense, click on the New expense button in the upper left corner above the table with expenses. Section for adding new expense will appear. Fill in the DateAmount, Category, Incurred by and Name and Description fields and click on the Save button to add the expense. If you don’t want to add a new expense, you can click on the Hide button to hide the section for adding a new expense.

                                                                                            Image: Adding New Expense

Editing an expense


  • When inline editing is not enabled, in order to edit existing expense click on Edit button () for that expense. This will bring up the expense edition dialog. The details which can be changed are DateAmount, Category, Incurred by and Name and Description fields. After editing some details it is necessary to click on the Update button to save changes or otherwise click the Cancel button.

                                                                                            Image: Expense Editing Dialog


  • When inline editing is enabled, to edit existing expense click on the field you want to edit for that expense. The field you clicked on will become an input field, and buttons for saving and discarding changes will appear. It is necessary to click on the Save changes button () to save changes or otherwise click the Discard changes button ().


                                                                                            Image: Inline Expense Editing

Deleting an expense


In order to delete a specific expense, click on the Delete button () for that expense. This brings up a dialog to confirm expense deletion. Click the Delete button to confirm the deletion or otherwise click the Cancel button. Deletion is permanent, thus make sure you really want to delete an expense before proceeding.

                                                                                            Image: Expense Deleting Dialog

Generating report for specific user


There is a possibility to export the report for the specific user in a .xlsx and a .pdf format. The buttons for exporting report are located next to the Generate report for user field. 


In order to export the report for a specific user, you should select the specific user in Generate report for user field and click on the appropriate button for exporting the report. 

                                                                                            Image: Generate report for user button


After clicking on the export to .xlsx button (), the report will be downloaded as a .xlsx file.

                                                                                            Image: User Report exported in .xlsx format 

After clicking on the export to .pdf button (), a new tab will open in your browser with the .pdf version of the report. You can download the report in .pdf directly from that tab.

                                                                                            Image: User Report exported in .pdf format 

Attaching files to an expense


There is the possibility to attach a file to an expense in order to keep related document at hand (invoice, quotation, etc.). To attach a file to an expense, click on the Choose File button for that expense. This will bring up a dialog where you can pick a file. After choosing a file, click on Upload button () to upload a file. The Upload button is disabled until the file is chosen. Files of any type can be attached to an expense.


                                                                                    Image: Uploading Expense File

Viewing file attached to an expense


To view the file attached to a specific expense, click on the View button  (for that expense. If the specific expense doesn’t have an attached file, the View button for that expense is disabled. The PDF files will be shown in a modal box, image files will be opened in a new tab, other file types will be downloaded.


                                                                                             Image: Expense File Preview