Redmine Time & Expense

User Guide
Version 1.7
July 31, 2014

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

Revision History
Date

Version

Description

Author

05/28/2013

1.5

Initial Revision

T.Suganya

08/27/2013

1.6

Time & Expense 1.6 updates

T.Suganya

07/31/2014

1.7

Time & Expense 1.7 updates

T.Suganya

2014 , Adhi Software Pvt Ltd

Page 2 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

Table of Contents
1. Introduction.................................................................................................................................... 5
2. Timesheet ..................................................................................................................................... 5
2.1 Timesheet List ...................................................................................................................... 5
2.2 New timesheet ..................................................................................................................... 5
2.3 Custom fields ....................................................................................................................... 6
2.3.1 Spent time Custom Fields .................................................................................................. 6
2.3.2 Timesheet Custom Fields................................................................................................... 6
3. Expense Sheet .............................................................................................................................. 7
3.1 Expense Sheet List .............................................................................................................. 7
3.2 New Expense Sheet ............................................................................................................. 7
3.3 Detail and Report Page ........................................................................................................ 7
4. Approval System ........................................................................................................................... 8
4.1 Status .................................................................................................................................. 8
4.2 Workflow .............................................................................................................................. 9
5. Redmine Settings .......................................................................................................................... 9
5.1 Permissions ......................................................................................................................... 9
5.1.1 Issue Visibility .................................................................................................................. 10
5.2 Start of Week ..................................................................................................................... 10
6. Plugin Settings............................................................................................................................. 11
6.1 Display Settings ................................................................................................................. 11
6.1.1 Work time header............................................................................................................. 11
6.2 Export Settings................................................................................................................... 11
6.3 Approval Settings ............................................................................................................... 12
6.3.1 Use Approval System....................................................................................................... 12
6.3.2 Auto approve .................................................................................................................. 12
6.3.3 Approve own time/expense sheet..................................................................................... 13
6.3.4 Submission ack text ......................................................................................................... 13
6.3.5 Email Notification ............................................................................................................. 13
6.3.6 Submission deadline ........................................................................................................ 13
6.3.7 Non submission email message ....................................................................................... 13
6.4 Time & Expense Settings ................................................................................................... 13
6.4.1 Include closed issues ....................................................................................................... 14
6.4.2 Previous week template ................................................................................................... 14
6.4.3 Issue input format ............................................................................................................ 14
6.4.4 Allow Blank Issue ............................................................................................................. 14
6.4.5 Enter comment in row ...................................................................................................... 15
6.4.6 Use detail time entry popup.............................................................................................. 15
6.4.7 Allow User Filtering to My Issues ...................................................................................... 15
6.5 Time Settings ..................................................................................................................... 16
6.5.1 Max hour ......................................................................................................................... 16
6.5.2 Enforce Max hour............................................................................................................. 16
6.5.3 Min hour .......................................................................................................................... 16
6.5.4 Enforce Min hour.............................................................................................................. 16
6.5.5 Filter Issue by Tracker...................................................................................................... 16
6.5.6 Allow User Filtering by Tracker ......................................................................................... 17
6.5.7 Enter custom field in row1 ................................................................................................ 17

2014 , Adhi Software Pvt Ltd

Page 3 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

6.5.8 Enter custom field in row2 ................................................................................................ 17

6.6 Expense Settings ............................................................................................................... 17
6.6.1 Expense project ............................................................................................................... 17
6.6.2 Filter issue by tracker ....................................................................................................... 17
6.7 Approve Time Logs Permission .......................................................................................... 17
6.8 Public holidays ................................................................................................................... 18
7. REST API .................................................................................................................................... 18
7.1 List Time/Expense Sheets .................................................................................................. 18
7.2 Create Time/Expense Sheet ............................................................................................... 19
7.3 Get Time/Expense Sheet ................................................................................................... 21
7.4 Update Time/Expense Sheet .............................................................................................. 23
7.5 Delete Time/Expense Sheet ............................................................................................... 25
7.6 Delete Time/Expense Entries ............................................................................................. 25
8. PDF & CSV ................................................................................................................................. 26
9. Troubleshooting ........................................................................................................................... 26

2014 , Adhi Software Pvt Ltd

Page 4 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

1.

Introduction

The Time Entry feature of Redmine allows a user to enter against a Project Issue, this entry can be
made one by one. The Time & Expense plugin revamps the time entry feature to allow for weekly
time entry in one screen. This plugin provides the capability to submit both Time & Expense in weekly
format within Redmine. The user must be a member of a project with permission to log time. If the
user has Edit time logs permission, then he can manage other team member's Time & Expense as
well. Users without edit permissions cannot edit/delete time & expense entries. The time & expense
sheets can be exported into pdf and csv format.

2.

Timesheet

Timesheet is used to log the spent time for projects by their members for a week. The member should
have log time permission to fill out the timesheet.
2.1

Timesheet List

The list page by default displays the timesheets for the current month. Date range filters can be
applied to the list page. The users with Edit time logs permission will have additional filters; project,
member, group and status dropdowns. The list page displays the list of timesheets satisfying the filter
criteria. The project/group dropdown is used for filtering the member dropdown.

Note: Users who have edit permissions on all projects within a timesheet will be allowed to delete a
timesheet from this list page.
2.2
New timesheet
Here are the steps to add a new timesheet.
-

Click on the top menu Time & Expense,

Select the tab Time
Click on New Timesheet hyperlink
Enter the start date of the week for the new timesheet and if previous week template is
needed check the previous week template checkbox, else uncheck it
Click Continue to create timesheet.

The screenshot represent the timesheet page. Using the Add row link, the user can enter new time
entry. Choose the project, issue and activity from their respective dropdowns. Rows can be deleted
using the delete icon at the end of the row.

2014 , Adhi Software Pvt Ltd

Page 5 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

The Previous and Next link helps the user to navigate to the previous and next week timesheet.
2.3
Custom fields
Custom fields can be added at the Timesheet level and also at the individual spent time level.
Administrators can create custom fields by navigating to Administration
Custom fields menu

New custom field link. To create individual spent time custom fields choose the Spent time
option and for timesheet custom fields choose the Weekly Time option from the Custom fields page.

2.3.1 Spent time Custom Fields

The spent time custom fields are applicable to the individual cells within a timesheet; these are
attributes of Spent Time entity. These custom fields can be configured for a row (discussed in section
6.5.7 and 6.5.8) instead of a cell and by default it will be shown in detail time entry popup (discussed
in section 6.4).
2.3.2

Timesheet Custom Fields

These custom fields are applicable to the whole timesheet and are created from the Weekly Time tab
from the Custom fields page. For e.g., the Purchase Order field applies to the whole timesheet.

2014 , Adhi Software Pvt Ltd

Page 6 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

3.

Expense Sheet

Expense sheet is used to fill out the expenses incurred on various projects. It works same as the
timesheet. In addition to project, issue and activity fields, it has the currency field as well. Even
though different currencies can be used for different rows, the currency from the last row is used for
the day total and week total. Custom fields are not available for Expense Sheet.
3.1
Expense Sheet List
This page list the expense sheets based on the filter criteria chosen on the page. This page is similar
to the timesheet list page described in section 2.1.
3.2
New Expense Sheet
The steps for adding a new expense sheet is same as that of the timesheet.

3.3

Detail and Report Page

The expense detail and report page resembles the spent time detail and report page of redmine. The
navigation for the expense Detail and Report page is Projects
Edit project
Expense Report. The
project members with View Spent Time permission have access to this page.

The details tab will list individual expense entries made for the project. We can edit and delete
expense entries from here as well. The edit link will take the user to the corresponding expense sheet.
Individual expense entries can be deleted from this page as well. The report tab can be used to
summarize data at various levels; member, tracker etc.

2014 , Adhi Software Pvt Ltd

Page 7 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

4.

Approval System

The Time & Expense sheets can be approved / rejected by supervisors after it is submitted by Project
Members.
4.1
Status
The various statuses of the time & expense sheets are:
- New
- Submitted
- Approved
- Rejected.
The time & expense sheet is in New status when it is created. Once the timesheet is submitted, it
goes to the Submitted status. It goes to Approved status when the supervisor approves it. When
the timesheet is rejected, it goes to the Rejected status and goes backs to the project member for
resubmission. The Time & Expense Sheet returns to the New status when it gets un-submitted.

On unsubmit
time/expense
sheet goes for
re-submission

On unapprove,
time/expense
sheet goes to
submitted status

NEW

APPROVED

2014 , Adhi Software Pvt Ltd

Rejected
time/expense sheet
goes back for resubmission

SUBMITTED

REJECTED

Page 8 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

4.2
Workflow
The workflow of Approval system is as follows.
i)

ii)
iii)
iv)
v)
vi)
vii)

5.

The Time & Expense sheet has the Submit button in addition to the Save button.

A team member can save a time & expense sheet any number of times, but can only submit
once.
Once a time & expense sheet is submitted, the user with Approve time logs permission can
approve / reject it, the project member can also un-submit his time & expense sheet, if he
wants to take back his submission.
Once approved, the time & expense sheets can never be edited.
If the time & expense sheet is rejected, then it goes back to the project member for resubmission. An email about the rejection is sent to the Project Member.
Once approved, a time & expense sheet can be unapproved; it sends the time & expense
sheet back to submitted state.
If the timesheet is not submitted before deadline, then an email notification will be sent to the
project member.

Redmine Settings

There are certain settings of redmine which influence the functionality of the Time & Expense plugin.
5.1
Permissions
The roles (manager, developer, reporter etc.) defined in redmine are assigned with a set of
permissions. Administrators can define roles and configure its permission by navigating to
Administration
Roles and permissions. A user can have different roles for different projects and
also a project member can have multiple roles assigned for single project.

2014 , Adhi Software Pvt Ltd

Page 9 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

Following are some of

Guide]
Log spent time
View spent time
Edit time logs
Edit own time logs

the privileges defined in time tracking section [An extract from Redmine User
-

Allow user to log time on the project

Allow user to view the time logs on the project
Allow user to edit any time log
Edit own time logs

The rules for Roles and permission in the context of Time & Expense is as follows
#

Feature

1
2
3
4
5

Time & Expense List Page

New Time & Expense Sheet
Edit Time & Expense sheet
Edit Others Time & Expense Sheet
Approve Time & Expense

View
spent
time
X

Log
spent
time
X
X

Edit own
time
logs

Edit
time
logs

Approve
time
logs

X
X
X

Note: There are no separate permissions for expense; it uses the permission from spent time.
5.1.1

Issue Visibility

[An extract from Redmine User Guide]

Assuming that the role includes the View Issues permission, the following rules apply to the issues of
the projects the user is tied to through it:
All issues - the user can see all issues. This is the default.
All non-private issues - the user can see all issues which are not marked as private.
Issues created by or assigned to the user - the user can only see issues created by or assigned to

The issue dropdown in time & expense sheet is filled based on Issue Visibility for the role assigned to
project members.
5.2
Start of Week
The start of the week on the time & expense sheet can be configured to Monday, Saturday,
Sunday or Based on users language. If Based on users language is set, then start of the week
will be the day defined in language file. Start of the week can be configured by navigating to
Administration
Settings
Display
Start calendars on

2014 , Adhi Software Pvt Ltd

Page 10 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

6.

Plugin Settings

The plugin can be configured from the plugin settings page to customize its behavior. Only the
administrators can access this page. The plugin configurations are grouped into the following
categories; Display Settings, Export (for pdf) Settings, Time & Expense Settings, Approval system
Settings.
The settings defined in the Time & Expense section are common to both timesheet and expense
sheet. There is also separate section for Time and Expense as well, the settings which comes
under these sections is specific to its sheets.
6.1

Display Settings

The project, issue and activity dropdown width can be adjusted using these settings.

6.1.1 Work time header

Work time header contains the start and end time of a work day, this header is used to get the total
number of hours worked in a day and also serves as a reminder on the number of hours left to be
logged. The start and end times are not persistent. This header can be shown / hidden by using this
configuration.
6.2

Export Settings

The time & expense sheet can be exported to pdf and csv. The pdf page width, height, top margin,
bottom margin, left margin, right margin, line space and logo can be configured.

2014 , Adhi Software Pvt Ltd

Page 11 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

6.3
Approval Settings
Approval System is common to both Time and Expense except for email notification on nonsubmission which is applicable only to Time.

6.3.1 Use Approval System

If Use Approval System checkbox is checked, then approval system is used.
6.3.2 Auto approve
If the setting Auto approve Time & Expense is enabled, then the time & expense sheet gets
automatically approved by the system upon submission. The project member will not be able to
unsubmit his time/expense sheet since it goes to approved status immediately.

2014 , Adhi Software Pvt Ltd

Page 12 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

6.3.3 Approve own time/expense sheet

If the setting Approver Can Approve their own Time & Expense is enabled, then the project
member with Approve time logs along with Edit time logs and Log spent time permission can
approve/reject his own time & expense sheet.
6.3.4 Submission ack text
The text given in the Submission Acknowledgement Text is the message shown during Time &
Expense submission. (Please see screenshot below)

6.3.5

Email Notification

The setting Send email for non submission is only for Time. If this setting is enabled, then an
email notification is sent to the user about his non submission of timesheet for the previous week.
Please note, this setting required rufus scheduler gem.
6.3.6

Submission deadline

Timesheet submission deadline can be configured using this setting. If the project member did not
submit the timesheet before the configured Submission Deadline, then an email notification is
sent only when the configuration Send email for non submission is enabled.
6.3.7

Non submission email message

The text for non-submission timesheet notification email message can be configured using the setting
Non submission email message. The text given in this configuration will be used as the email
message body along with the name of the project member, submission deadline, the week for which
timesheet need to be submitted.
6.4

Time & Expense Settings

2014 , Adhi Software Pvt Ltd

Page 13 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

6.4.1

Include closed issues

The issue dropdown in time & expense sheet will list only issues which are currently open. To include
previous weeks closed issues, enable the configuration Include Previous Week's Closed Issues.
Note: The current weeks closed issue is not affected by this setting it will always be shown in issue
dropdown.
6.4.2

Previous week template

The new time & expense sheets can be created using previous week sheets as template. There is a
checkbox Previous weeks template in the new time & expense sheet page. If it is checked, then
previous week(s) time & expense sheet are used as template.
The number of previous weeks to be considered can be configured using the setting Number of
Weeks to consider for previous week template.
6.4.3

Issue input format

By default, the issues will be listed as dropdown in time & expense sheet. Issues can be entered as
ID or Subject by enabling the configuration Enter issue as ID/Subject. If enabled, a checkbox
Enter issue as ID/Subject appears on the time & expense sheet.
If the checkbox on the time & expense sheet is checked, then both the project and issue dropdown
will be replaced by an issue textbox which can be used for entering either issue id or issue subject
and complemented by auto completion

6.4.4 Allow Blank Issue

This Time & Expense entries can be made directly to a project without selecting an issue and this
configuration Allow Blank Issue enables that. If the setting is enabled, then the issue dropdown in
time & expense sheet will contain a blank option.

2014 , Adhi Software Pvt Ltd

Page 14 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

6.4.5

Enter comment in row

Comments on the Time & expense entries can be made from the row using this setting Enter
comment in row. This setting allows for one common comment for all entries of a unique
combination of project, issue and activity. If this setting is enabled, there will be a textbox for comment
in addition to project, issue and activity dropdown.

6.4.6

Use detail time entry popup

The setting Use Detail Time Entry Popup can be used for entering additional details like comments
and custom fields on a time & expense entry. If this setting is enabled there will be an icon next to the
entry textbox for popping up a detail dialog box.

6.4.7

Allow User Filtering to My Issues

2014 , Adhi Software Pvt Ltd

Page 15 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

The setting Allow User Filtering to My Issues is used to filter issues which are assigned to them or
created by them in time and expense sheet page. If the setting is enabled, then the user will be
allowed to override the Issue Visibility setting of Redmine core
6.5
Time Settings
The settings which are defined under this section are only applicable to Time sheets.
6.5.1

Max hour

Maximum hour for a day can be configured using the Max hour per day. This is used to limit the
number of hours entered by a project member for a particular day.
6.5.2

Enforce Max hour

If the setting Enforce Max hour per day is enabled, then validation will be done to check if the
entered time per day is above the configured Max hour per day.
6.5.3

Min hour

Minimum hour for a day can be configured using the Min hour per day.

6.5.4

Enforce Min hour

If the setting Enforce Min hour per day is enabled, then validation will be done to check if the
entered time per day is below the configured Min hour per day. Validation will be done only for
working days, for the non-working days validation will be done only when user enters time.
Note:
1. The min and max configurations are only applicable to timesheet.
2. Non working days can be configured by Administrators (Administration
Settings
Issue
tracking
Non-working days).
3. Min hour settings are applicable only when approval system is enabled
4. By default, the max hour is 8 and min hour is 0
6.5.5

Filter Issue by Tracker

Tracker is basically used to categorize issues like bug, support etc. This setting Filter Issue by
Tracker is set separately for time and expense. This setting is used to restrict entries for a particular
set of trackers. Only the issues from the configured trackers will be listed in the issue dropdown in the
time & expense sheet. If no tracker is configured then all issues will be listed in issue dropdown.

2014 , Adhi Software Pvt Ltd

Page 16 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

6.5.6

Allow User Filtering by Tracker

If Allow User Filtering by Tracker is enabled then user will be allowed to override the tracker filters
set on the settings page.

6.5.7

Enter custom field in row1

The spent time custom fields are entered through detail popup by default. The setting Enter custom
field in row1 can be used to enter a spent time custom field from the row. If this setting is enabled,
there will be a textbox for the configured custom field in the row.
6.5.8 Enter custom field in row2
Same as Enter custom field in row1
Note: Only two spent time custom fields can be configured to be in the row.
6.6

Expense Settings

This section contains settings that are applicable to expense sheets.

6.6.1 Expense project

Separate list of projects can be configured for Expenses. This setting Restrict Expense Entry to
these projects allow members to charge expense only to those configured projects.
6.6.2

Filter issue by tracker

This is same as section 6.5.5, but in the context of an expense.

6.7
Approve Time Logs Permission
A new permission is defined for time/expense sheets approval under Time tracking section. The
user with Approve time logs permission along with Log spent time and Edit time logs
permission will be allowed to approve, unapprove and reject time and expense sheets.

2014 , Adhi Software Pvt Ltd

Page 17 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

6.8
Public holidays
The Public Holidays can be configured for the year. The days which are configured as public
holidays will not be validated for min and max hours on time sheets.

7.

REST API

Time & Expense REST API supports both XML and JSON. It supports following functionalities.
-

Get list of time/expense sheets

Create time/expense sheet
Get a time/expense sheet
Update a time/expense sheet
Delete a time/expense sheet
Delete a time/expense entries

Time & Expense API requires authentication for each request. The API validates the user and
responds with 401 Unauthorized if user did not have required privileges. For more information on
REST API configuration, please refer to the Redmine User Guide.
7.1
List Time/Expense Sheets
List of time and expense sheet can be retrieved using the list API. By default, it returns time and
expense sheets for the current month if the parameters from and to is not specified. If from and to is
specified then time/expense sheet for that particular date range will be retrieved.
Request
Type
GET

URL

Response

Time
/wktime/index.xml?user_id=9999&from=2013-01-01
&to=2013-08-01

list of timesheets of a
user as xml/json

/wktime/index.json?user_id=9999
GET

Expense
/wkexpense/index.xml?user_id=9999
&from=2013-01-01&to=2013-08-01

2014 , Adhi Software Pvt Ltd

list of expense sheets

of a user as xml/json

Page 18 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

/wkexpense/index.json?user_id=9999
&from=2013-01-01&to=2013-08-01&limit=25&offset=0
Parameters
user_id

Required

project_id

Optional

from
to
offset
limit

Optional
Optional
Optional.
Optional

user_id for whom, list of time/expense sheet is to be retrieved.

If 0, then list of time/expense sheets for all user is retrieved.
Use this parameter, if user_id = 0 is used i.e., to get list of
time/expense sheets of all user under one project.
Specifies the start of the date range
Specifies the end of the date range
The offset of the first item to retrieve
Number of records to be retrieved (default is 25)

Sample XML Response (for Time)

<?xml version="1.0" encoding="UTF-8"?>
<wk_times total_count="1" offset="0" limit="25" type="array">
<wk_time>
<user id="5" name="Chandra Durairaj"/>
<hours>10.0</hours>
<startdate>2013-08-19</startdate>
<status>n</status>
</wk_time>
</wk_times>
Sample JSON Response (for Time)
{"wk_times":
[
{
"user":{"id":5,"name":"Chandra Durairaj"},
"hours":10.0,
"startdate":"2013-08-19",
"status":"n"
}
],
"total_count":1,
"offset":0,
"limit":25
}
7.2
Create Time/Expense Sheet
Time and Expense sheet can be created using the create API.
Request
Type
POST

URL
Time
/wktime/update.xml?wktime_save=Save
/wktime/update.xml?wktime_submit=Submit

POST

Expense
/wkexpense/update.xml?wktime_save=Save

2014 , Adhi Software Pvt Ltd

Response

200 OK.
Creates a timesheet
200 OK.
Creates and set timesheet to
submitted state
200 OK.
Creates an expensesheet

Page 19 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

/wkexpense/update.json?wktime_submit=Submit

200 OK.
Creates and set expensesheet
to submitted state

Sample XML data to be posted (for Time)

<?xml version="1.0" encoding="UTF-8"?>
<wk_time>
<user name="Chandra Durairaj" id="5"/>
<startday>2013-08-19</startday>
<status>New</status>
<total>6.0</total>
<custom_fields type="array">
<custom_field name="Purchase Order" id="12">
<value/>
</custom_field>
</custom_fields>
<time_entries type="array">
<time_entry>
<project name="Vitals Software" id="1"/>
<issue id="1"/>
<user name="Chandra Durairaj" id="5"/>
<activity name="Design" id="10"/>
<hours>4.0</hours>
<comments/>
<spent_on>2013-08-19</spent_on>
<custom_fields type="array">
<custom_field name="Difficulties" id="15">
<value/>
</custom_field>
</custom_fields>
</time_entry>
<time_entry>
<project name="Vitals Software" id="1"/>
<issue id="1"/>
<user name="Chandra Durairaj" id="5"/>
<activity name="Design" id="10"/>
<hours>2.0</hours>
<comments/>
<spent_on>2013-08-21</spent_on>
<custom_fields type="array">
<custom_field name="Difficulties" id="15">
<value/>
</custom_field>
</custom_fields>
</time_entry>
</time_entries>
</wk_time>
Sample XML data to be posted (For Expense)
<?xml version="1.0" encoding="utf-8"?>
<wk_expense>
<user id="5" name="Chandra Durairaj"/>
<startday>2013-08-26</startday>
<status>New</status>
<total>75.0</total>

2014 , Adhi Software Pvt Ltd

Page 20 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

<wk_expense_entries type="array">
<wk_expense_entry>
<id>84</id>
<project id="22" name="Expense"/>
<issue id="50"/>
<user id="5" name="Chandra Durairaj"/>
<activity id="8" name="Design"/>
<amount>25.0</amount>
<currency>$</currency>
<comments/>
<spent_on>2013-08-26</spent_on>
</wk_expense_entry>
<wk_expense_entry>
<id>85</id>
<project id="22" name="Expense"/>
<issue id="51"/>
<user id="5" name="Chandra Durairaj"/>
<activity id="8" name="Design"/>
<amount>50.0</amount>
<currency>$</currency>
<comments/>
<spent_on>2013-08-27</spent_on>
</wk_expense_entry>
</wk_expense_entries>
</wk_expense>
7.3

Get Time/Expense Sheet

Request
Type

URL

Response

GET

Time
/wktime/edit.xml?user_id=9999&startday=2013-07-29

GET

/wktime/edit.json?user_id=9999&startday=2013-07-29
Expense
/wkexpense/edit.xml?user_id=9999&startday=2013-07-29

Timesheet of a user for

a week

Expensesheet of
user for a week

/wkexpense/edit.json?user_id=9999&startday=2013-07-29
Parameters
user_id
startday

Required
Required

User_id for whom time/expense sheet is to be retrieved

Specifies the start of the week

Sample XML Response (for Time)

<?xml version="1.0" encoding="UTF-8"?>
<wk_time>
<user name="Chandra Durairaj" id="5"/>
<startday>2013-08-19</startday>
<status>New</status>
<total>6.0</total>
<custom_fields type="array">
<custom_field name="Purchase Order" id="12">
<value/>
</custom_field>

2014 , Adhi Software Pvt Ltd

Page 21 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

</custom_fields>
<time_entries type="array">
<time_entry>
<id>1506</id>
<project name="Vitals Software" id="1"/>
<issue id="1"/>
<user name="Chandra Durairaj" id="5"/>
<activity name="Design" id="10"/>
<hours>4.0</hours>
<comments/>
<spent_on>2013-08-19</spent_on>
<custom_fields type="array">
<custom_field name="Difficulties" id="15">
<value/>
</custom_field>
</custom_fields>
</time_entry>
<time_entry>
<id>1507</id>
<project name="Vitals Software" id="1"/>
<issue id="1"/>
<user name="Chandra Durairaj" id="5"/>
<activity name="Design" id="10"/>
<hours>2.0</hours>
<comments/>
<spent_on>2013-08-21</spent_on>
<custom_fields type="array">
<custom_field name="Difficulties" id="15">
<value/>
</custom_field>
</custom_fields>
</time_entry>
</time_entries>
</wk_time>
Sample JSON Response
{"wk_time":
{
"user":{"id":5,"name":"Chandra Durairaj"},
"startday":"2013-08-19",
"status":"New",
"total":6.0,
"custom_fields":[
{"id":12,"name":"Purchase Order","value":"233"}
],
"time_entries":[
{
"id":1506,
"project":{"id":1,"name":"Vitals Software"},
"issue":{"id":1},
"user":{"id":5,"name":"Chandra Durairaj"},
"activity":{"id":10,"name":"Design"},
"hours":4.0,
"spent_on":"2013-08-19",
"custom_fields":[
{"id":15,"name":"Difficulties"}

2014 , Adhi Software Pvt Ltd

Page 22 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

]
},
{
"id":1507,
"project":{"id":1,"name":"Vitals Software"},
"issue":{"id":1},
"user":{"id":5,"name":"Chandra Durairaj"},
"activity":{"id":10,"name":"Design"},
"hours":2.0,
"spent_on":"2013-08-21",
"custom_fields":[
{"id":15,"name":"Difficulties"}
]
}]
}
}
7.4
Update Time/Expense Sheet
Time & Expense sheet can be updated suing update API. Any one of the following action and its
value should be sent for the corresponding functionalities.
- wktime_save=Save
- wktime_submit=Submit
- wktime_unsubmit=Unsubmit
- wktime_approve=Approve
- wktime_reject=Reject
- wktime_unapprove=Unapprove
Request Type

URL

POST

Time
/wktime/update.xml?wktime_save=Save
/wktime/update.xml?wktime_submit=Submit

/wktime/update.xml? wktime_unsubmit=Unsubmit

/wktime/update.xml?wktime_approve=Approve
/wktime/update.xml?wktime_reject=Reject
/wktime/update.xml?wktime_unapprove=Unapprove

POST

Expense
/wkexpense/update.xml?wktime_save=Save
/wkexpense/update.xml?wktime_submit=Submit

/wkexpense/update.xml?wktime_unsubmit=Unsubmit

/wkexpense/update.xml?wktime_approve=Approve

2014 , Adhi Software Pvt Ltd

Response
200 OK.
Updates a timesheet
200 OK.
Update and set timesheet
status to Submitted
200 OK.
Updates the timesheet status
to New
200 OK.
Approves a timesheet
200 OK
Rejects a timesheet
200 OK.
Unapproves a timesheet
200 OK.
Updates an expensesheet
200 OK.
Update and set timesheet
status to Submitted
200 OK.
Updates the expensesheet
status to New
200 OK.
Approves an expensesheet

Page 23 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

/wkexpense/update.json?wktime_reject=Reject

200 OK
Rejects an expensesheet

/wkexpense/update.xml?wktime_unapprove=Unapprove

200 OK.
Unapproves an expensesheet

Note: If validation failure occurs, then API response will be 422 Unprocessable Entity otherwise
response will be 200 OK for successful updates.
Sample XML data to be posted (for Time)
In the below sample, two time_entry object contains id and one did not have id, then API will update
the two entries which has id and creates a new time_entry for which id is not specified.
<?xml version="1.0" encoding="UTF-8"?>
<wk_time>
<user name="Chandra Durairaj" id="5"/>
<startday>2013-08-19</startday>
<custom_fields type="array">
<custom_field name="Purchase Order" id="12">
<value/>
</custom_field>
</custom_fields>
<time_entries type="array">
<time_entry>
<id>1506</id>
<project name="Vitals Software" id="1"/>
<issue id="1"/>
<user name="Chandra Durairaj" id="5"/>
<activity name="Design" id="10"/>
<hours>4.0</hours>
<comments/>
<spent_on>2013-08-19</spent_on>
<custom_fields type="array">
<custom_field name="Difficulties" id="15">
<value/>
</custom_field>
</custom_fields>
</time_entry>
<time_entry>
<id>1507</id>
<project name="Vitals Software" id="1"/>
<issue id="1"/>
<user name="Chandra Durairaj" id="5"/>
<activity name="Design" id="10"/>
<hours>2.0</hours>
<comments/>
<spent_on>2013-08-21</spent_on>
<custom_fields type="array">
<custom_field name="Difficulties" id="15">
<value/>
</custom_field>
</custom_fields>
</time_entry>
<time_entry>
<project name="Vitals Software" id="1"/>
<issue id="2"/>
<user name="Chandra Durairaj" id="5"/>
<activity name="Design" id="10"/>

2014 , Adhi Software Pvt Ltd

Page 24 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

<hours>4.0</hours>
<comments/>
<spent_on>2013-08-20</spent_on>
<custom_fields type="array">
<custom_field name="Difficulties" id="15">
<value/>
</custom_field>
</custom_fields>
</time_entry>
</time_entries>
</wk_time>
7.5

Delete Time/Expense Sheet

The project member with edit permission will be allowed to delete time and expense sheet using
delete API.
Request
Type

URL

Response

DELETE

Time
/wktime/destroy.xml?user_id=9999&startday=2013-08-12

DELETE

/wktime/destroy.json?user_id=9999&startday=2013-08-12
Expense
/wkexpense/destroy.xml?user_id=9999&startday=2013-08-12

200 OK.
Deletes a timesheet

200 OK.
Deletes an expensesheet

/wkexpense/destroy.json?user_id=9999&startday=2013-08-12
Parameters
user_id
startday
7.6

Required
Required

user_id for whom time/expense sheet is to be deleted

Specifies the start of the week

Delete Time/Expense Entries

The project member with edit permission will be allowed to delete time and expense entries using
deleteEntries API.
Request
Type

URL

DELETE

/wktime/deleteEntries.xml

Response
Time
200 OK.
Deletes a time entries

/wktime/deleteEntries.json
Expense
DELETE

/wkexpense/deleteEntries.xml
/wkexpense/deleteEntries.json

200 OK.
Deletes an expense entries

Sample XML data to be posted (for Time)

<?xml version="1.0" encoding="utf-8"?>
<time_entries type="array">
<time_entry>
<id>1535</id>
<project id="1" name="Vitals Software"/>
<issue id="1"/>

2014 , Adhi Software Pvt Ltd

Page 25 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

<user id="3" name="Suganya Thulasiraman"/>

<activity id="10" name="Design"/>
<hours>4.0</hours>
<comments/>
<spent_on>2013-12-23</spent_on>
<custom_fields type="array">
<custom_field id="15" name="Difficulties">
<value/>
</custom_field>
</custom_fields>
</time_entry>
<time_entry>
<id>1537</id>
<project id="1" name="Vitals Software"/>
<issue id="1"/>
<user id="3" name="Suganya Thulasiraman"/>
<activity id="10" name="Design"/>
<hours>4.0</hours>
<comments/>
<spent_on>2013-12-25</spent_on>
<custom_fields type="array">
<custom_field id="15" name="Difficulties">
<value/>
</custom_field>
</custom_fields>
</time_entry>
</time_entries>

8.

PDF & CSV

The time & expense sheet can be exported into pdf or csv format. To take a csv report click on the
csv link and for the pdf report click on the pdf link.

9.

Troubleshooting
1. The issues associated with each project do not show up in the drop down list
This might be the issue visibility configuration issue. Check under Administration
Roles
and Permissions
Edit user role
Issue Visibility.
(For further detail refer section 5.1.1)
2. Is it possible to change the default currency of expenses

First one from the currency dropdown is the default. To have the currency of your choice to be
the default in currency dropdown, add the following lines within number in the language file
(for e.g., config/locale/cs.yml )

2014 , Adhi Software Pvt Ltd

Page 26 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

currency:
format:
format:"%u%n"
unit: "CZK"
3. There is no submit button
The submit button will be visible only when Approval System is enabled.
4. How to approve the manager time-sheet?
If the setting Approve own time/expense sheet is enabled, then the manager can approve
his own timesheet.
5. Why is the plugin not maintaining comments separately for each time entry?
If we have set Enter comment in row, it will allow only one comment per row. The timesheet
will allow only one combination of project, issue and activity on multiple rows. To allow for
separate comments per time entry, do not use the setting Enter comment in row.
6. The pdf export is not working. It is showing Internal error

The rmagick gem is required for displaying the logo in the pdf. If the rmagick gem is not
installed, this error is encountered. Other alternative is to remove the logo from the pdf. To
remove the logo, go to the plugin configuration page and empty the report logo field.
7. Some of the time entries are disabled on edit for project manager
The project manager (with Edit time logs permission) can add/edit a time & expense sheet
for their project members. If the project members dont have the edit time log permissions,
then the manager also cannot edit it.

8. Can we log time using core Redmine when a Time & Expense is in approved state ?
Apart from the Time & Expense plugin, there are two other ways of logging time
- Project
Edit Project
Log time
- Project
Edit Project
Edit Issue
Update
There will be warning messages on both these pages if the timesheet was approved for that
week.

2014 , Adhi Software Pvt Ltd

Page 27 of 28

Redmine Time & Expense Plugin User Guide

Version: 1.7
Date: July 31, 2014

The Log Time page will actually throw an error when trying to save for an approved period.
But the Edit Issue page will not throw any error and will actually save, because there are no
hook codes available from Edit Issue page.

2014 , Adhi Software Pvt Ltd

Page 28 of 28