I'm looking for a part-time remote job.

Hire me

I'm the author of:

Mastering Redmine is a comprehensive guide with tips, tricks and best practices, and an easy-to-learn structure.

Check the book's project or

Buy the book

Social pages of the book:

By buying this book you also donate to Redmine (see this page).

Follow me:

Usage manual

Important notes

There are things you should take care of. Here they go:

  1. Anything not recognized otherwise is treated as a description of a task. That is any “thoughts”, unsupported queries or free-form statements will be taken as a description. See Canceling operation for how to cancel an accidentally created task.
  2. Orangutan does not guess. He is unable to... So be sure that your statements are gramatically correct, full and not ambiguous. See Canceling operation for how to cancel an accidentally created task.
  3. Do read what he writes! Do answer on what he asks unless your are ready for default actions he will do. Often user type something and do not read that it was taken as a task description. And often users ignore questions and then wonder why he does something.

The main problems experienced by users using Orangutan are:

  1. Pseudo free form syntax leads to confusion. Having many possible options of requests users are unable to remember and choose one of the options. Trying their own options (sometimes grammatically incorrect, incomplete or ambiguous) it happens that they get unexpected results.
  2. Orangutan often makes assumptions that is does some actions which look to be correct in some situations (usually he asks for confirmation). These actions are not always correct for a user.
  3. Users know that Orangutan is a bot. That’s why they usually do not read what Orangutan writes or read uncarefully. Users generally feel uncomfortable with a bot which is too stupid to be a human and too smart to be a bot.


This section gives examples of the requests you can send to Orangutan. Remember that Orangutan is built to support natural language queries that is if you send some query which seems to be correct but Orangutan did not recognize it then most likely you have found a bug. For each subsection you will see several (but not all supported) request samples.


Changing primary project

Orangutan asks you about your primary project when you add him to your contact list. You can change this project by:

You: I moved to PayPartners
You: Now I'm on Vendini
You: Main project is Nexera

Of course, the project should exist in Redmine and the name used here should be correct.

Changing main issue

If you are working on the same issue for a long time you can choose it as your default issue. This way you won’t need to specify issue for each task.

You: Change my default issue to #50
You: Main issue is #32

If later you begin to work on many small issues you can unset default issue:

You: Remove primary issue
You: Unset default issue id

Changing main activity

You: Main activity is work time
You: From now main activity is QA testing

Specifying work day length

For some of the functionality you need to tell Orangutan how long is your work day. Default is 8 hours.

You: I work full time
You: I work half time
You: I work part time

Here “full” means 8 hours workday, “half” - 4 hours workday and “part” means you work on hours basis (that is you don’t have to work a fixed amount of hours).

You can also specify number of hours:

You: I work 2 hours
You: I work 8 hours per work day

Specifying when your work day starts

For some functions you should specify when your working day starts. This should be official time. That is saying if you come 12:00 and work till 19:00 but your workday lasts 4 hours. You should specify something like 14:00. This time and workday length are used to calculate your work day end time. Default is 10:00.

You: My workday starts at 10:00
You: I start working at 14:00

Specifying your working days

Saying you do not work on Mondays. Tell this to Orangutan as follows:

You: I do not work on Mondays

If you started working on Mondays do:

You: Now I work on Mondays

Specifying minimum break time

If you were away for more than 5 minutes Orangutan assumes you had a break. For some users this can be too short time for a break. You can change it this way:

You: Don't ask me to record a break if I am away for less than 20 minutes!
You: Don't ask to break tasks when I'm away for less than 10 minutes!
You: Break can't last less than 15 minutes...

Reminder configuration

One of the main feature of Orangutan is reminding - from time to time it asks users to tell what they are working on. For some users it can be annoying especially if they are not required to track time.

To turn off reminder tell:

You: Do not ever ask me to enter tasks!
You: Don't ask me to add tasks!
You: Please do not remind to tell tasks.

To turn it on back:

You: Please ask me to enter tasks.
You: Always remind me to specify tasks.

Work hours notification

Sometimes when working it is really hard to follow the clock. If you are one of such persons you can ask Orangutan to notify you when you have worked enough hours.

Ask Orangutan to notify you this way:

You: Let me know when I can leave.
You: Tell me if I may go home.
You: Notify me when my work hours are enough.

If you changed your mind:

You: Stop notifying me when I can leave.
You: Don't tell me when my work hours are enough.

Checking configuration

It’s easy to forget what are current values of your configuration options. For this Orangutan allows to check them by:

You: Show my configuration
You: List configuration options
You: What are configuration options?
You: Config

On these requests Orangutan will send a short report about all available configuration options. But you can request any of them separately:

Checking project
You: What is my default project?
You: Show main project
Checking issue
You: What's primary issue?
You: Default issue
Checking activity
You: Show default activity
You: Activity
Checking work day start and end times
You: What do I start working?
You: When does my workday start?
You: When working days ends?
Checking work day length
You: How many hours should I work per day?
You: How long my work day lasts?
You: How much time should I work?
Checking working days
You: Give me list of working days
You: Which week days should I work on?

Redmine changes notifications

Since 1.03 Orangutan is able to notify users about changes made to issues just like Redmine does by email. However receiving notifications by email and Jabber can be annoying. That’s why Orangutan allows to turn off any of these methods or even both.

FIXME: Redmine 1.1.x seems to support disabling email notification. Orangutan should be fixed to use Redmine native method.

Disabling email notifications

To disable email notifications tell:

You: Do not notify me using email messages
You: Turn off Redmine email notifications
You: Disable email notifications
You: Stop notifying me by email
Disabling Jabber notifications

Not sure why whould one select email but:

You: I do not want to be notified about changes made to issues
You: Never notify me about new issues
You: Turn off notifications
You: Disable notifications
Enabling email notifications

Email notifications can be turned on back using:

You: Enable email notifications
You: Notify me by email

Please note that if you remove Orangutan email notifications will be turned on back automatically.

Enabling Jabber notifications

That’s the right desicion!.. Do:

You: Notify me about new issues and changes made to issues
You: Turn on notifications
You: Enable notifications


Aliases (like BASH aliases) are “rules” defining how phrases or messages should be treated. That is you type one phrase or query and Orangutan understands it as another phrase or query. Users define aliases by themselves.

Aliases can be text (part text, substring or phrase) and message aliases.

Defining an alias

As it was told above an aliase can be a phrase/word alias or a message alias. Let’s check what are these types:

Saying we have two different aliases:

You: Message "CC" means "Cold calling on #150" 
You: Word "CC" means "#150" 

If you type “CC” it will be treated as “Cold calling on #150” that is the whole message will be replaced. If you type “Working on CC” it will be treated as “Working on #150” that is only the part of the message (a word) will be replaced.

So the syntax is:

You: <Type> <Source> means <Destination>

If no type is specified the whole message is assumed.

Check samples:

You: Use "Activity is Research" when I type "Researching" 
You: If I type word "FB" use it as "Fixing bugs on #869" 
You: Replace text "Critical issue" with #236
You: Always treat "Bye" as "Done" 
You: Message TODO means "Show my issues" 

Listing aliases

It is impossible to remember all the aliases you set. But you don’t need to... To check your aliases do:

You: What are aliases?
You: Show aliases
You: Aliases

Removing an alias

Aliases can be easily removed:

You: Don't treat "TODO" as anything else
You: Never replace "Researching" 
You: Remove word alias "Bye" 
You: Remove FB

Defining a custom field alias

Most likely you will want to create aliases for issue numbers which are always hard to remember. But it can be also hard to create many aliases for each issue id. Besides if you remember the alias and don’t remember issue id how are you going to refer it on meetings, when speaking to your co-workers etc? The answer is “use custom field alias” for issue ids instead of just alias.

Orangutan allows you to choose values of which custom field should be used as aliases for issue ids. This “technique” is called “custom field alias”. This way any manager will be able to set aliases once and to make it similar for every team member.

However not all custom fields can be used as aliases. Such custom field should meet the following requirements:

  • The type of the custom field should be either “string”, or “int” or “list”;
  • If not “list” the custom field should have a strict regexp defined (the stricter the better);
  • If “list” the number of values of the custom field should not be too huge (what means there should be a limited number of issues);
  • Single value should point to a single issue;
  • The custom field value if not “list” should have min. length and max. length defined.

Why so complex? The answer is simple - wrong custom field will dramatically slow down the work of Orangutan.

So the syntax:

You: Use values of custom field "AltID" as aliases for issue ids
You: Use "Alternative Name" as alias for issue
You: Use "SJ ID" as custom field alias

Checking custom field alias

If used for a long time users can forget which custom field is used as an alias. That’s why Orangutan supports requests for displaying it:

You: Values of which custom field are used as aliases for issue IDs?
You: Show custom field alias

Removing a custom field alias

Moved to another project? Don’t want to use custom field alias any more? Just remove it:

You: Don't use any custom field as alias for issue ID!
You: Remove custom field alias

Task creation and modification

Task creation

The main requirements to task creation request is that you must specify description.

The format of request is:

You: <Description> on #<Issue> for <Project> (<Activity>) since <Time>

All but description and project or issue is optional.


You: Fixing creation issue
You: Learning code on #25 since 12:00
You: Trying to reproduce bug #65 (Testing)
You: Showing the most complete example (Work time) since 10:00

Changing task’s start time

You: Change start time to 14:00
You: Set start time of the task to 15:30

Changing project of the current task

Each task should have an issue. The project is taken from the issue. Anyway you can specify the project:

You: Project is PayPartners
You: Task is on Nexera
You: Change project to Vendini

After this Orangutan will suggest you to select the issue of this project.

Changing issue of the current task

The issue of the current task can be changed this way:

You: The ID of the issue is #98
You: Change issue id to #15
You: Use issue #68
You: Issue is #52

If the issue is in different project the project of the task will be changed as well.

You can also remove issue from the current task:

You: Remove issue
You: Clear issue id

Changing activity of the current task

This changes activity of the current task. Used activity name should be available in the task’s project.

You: Activity is work time
You: Change activity to work time

Where “work time” is activity name.

See what are you doing

You: What I do?
You: What task
You: Show my current task

Finishing the task

To finish current task you can:

You: Done
You: Done at 18:30
You: I did it
You: I finished at 17:00
You: Task has been completed
You: Finish my task

Time is optional. If not specified the current time is used.

Resuming previous task

If you continue working on e.g. yesterday task just do:

You: Resume my previous task
You: Continue

You can optionally specify start time:

You: Continue since 10:00

Adding tasks

You can also add your previous tasks this way:

You: <Date> [ <StartTime> <EndTime> | <Hours> ] <Description> on #<Issue> for <Project> (<Activity>)

Date and activity are optional. Either start and end time or spent hours must be specified. If you have specified the default issue the issue can be skipped as well.


You: On Monday from 10:00 to 19:00 I was working on #52
You: On January 1 from 19:00 till 23:00 I was testing #23
You: On Wednesday 2:00: Working on #36

Dropping task

Made a mistake when adding task? Remove it using:

You: Drop task
You: Remove task
You: Delete my current task

Show previous tasks

Orangutan allows you to see what you were doing during some period (supports optional project, issue and activity):

You: What I was doing yesterday?
You: What were my tasks in August?
You: What did I do on PayPartners on Monday?
You: Show my tasks
You: Show tasks for 1st January till 1st August
You: What did I do from January 1 to August 1?
You: What did I do during the last week?
You: What did I do for #14?
You: Show Monday tasks
You: Show today tasks on Orangutan

The syntax is:

You: Show tasks on #<Issue> for <Project> (<Activity>) <Date>

Show time spent

In addition Orangutan is able to calculate the time you spent during some period and optionally some project, issue and activity. The syntax is:

You: Show time on #<Issue> for <Project> (<Activity>) <Date>
You: How much time did I spend on #<Issue> for <Project> (<Activity>) <Date>


You: How much time did I spend yesterday?
You: Show time in August?
You: How much time did I spend for PayPartners on Monday?
You: Show time
You: Show time for 1st January till 1st August
You: How much time did I spend from January 1 to August 1?
You: How much time did I spend during the last week?
You: How much time did I spend for #32?


Listing issues

For working with Orangutan you need to know issue ID. It’s not easy to remember all the issue IDs and what do they mean... But you don’t need to. Orangutan supports complex queries allowing to fetch list of issues.

Check out the syntax:

You: Show [all] [actual|overdue] [overtimed] [unassigned] <Status> <Priority> <Tracker>s [of <Issue>] <Status> [with <Priority> priority] on <Project>

The query supports 5 basic options:

Option Description
all List all issues including issues assigned to other users
actual List only actual issues (current date is between their start and due dates)
overdue List overdue issues (their due date is in past)
overtimed List issues with spent time greater than estimated hours
unassigned List issues not assigned to anyone

Let’s see examples:

Query Description
Show issues Will list issues assigned to you or unassigned from all projects you are a member of
Show all issues of Vendini Will list all open issues of Vendini project
Show my actual issues Shows actual issues assigned to you
Show all overdue issues in UPC Shows all overdue issues in TPII project
Show my overtimed issues Shows all overtimed issues assigned to you
List unassigned issues in ClipSync Lists issues which are to be assigned in ClipSync project
Show new bugs Will list bugs with status equal to “New”
Show critical bugs Will list issues with tracker name equal to “Bug” and with “critical” priority
Show subissues of #63 Will list issues under issue #63

Orangutan tries to support any human language requests for listing issues. Some examples:

You: Show me TODO list
You: What should I do next?
You: Give me list of all overtimed issues
You: Show my issues in UPC
You: Are there any bugs?
You: What are issues in Orangutan?

Viewing issues

Issue details

You can fetch all known information about an issue by executing queries:

You: Give me details of #470
You: Show #470
You: What is issue #470?
You: Show feature request #470
You: #470

As you probably mentioned in these queries you can use tracker names.

Issue notes

The previous query shows only a number of comments in the issue - it does not show comments themselves. You can fetch comments of an issue this way:

You: Show notes for bug #470
You: Comments of #470
You: Notes in #470

Modifying issues

Assigning issue

Orangutan lets you assign the issue to some user or remove its assignee:

You: Assign #470 to alundyak!
You: Assign #189 to me.
You: Alundyak takes #470
You: I'll take #189
You: Unassign #470
You: Assign #189 to nobody
Changing done ratio

You can change the done ratio of an issue using Orangutan:

You: Change done ratio of #171 to 20%
You: I have completed #171 at 30%
You: Change done to 20% for #171
You: #171 is done at 80%
You: 10% done on #171
You: #171 is completed
Adding notes

Orangutan also allows you to add comments to the issue:

You: Add notes to #470
You: Reply in #470
You: Comment #470

Redmine has Vote plugin. This plugin lets users express their attitude towards an issue. Orangutan allows users to vote through Jabber chat window:

You: Vote for #470
You: Vote against #470
You: I like #470
You: I don't like #470 any more!
You: +1 to #470
You: #470: -1


Redmine lets users watch issues. This means that when a new issue is created or an existing issue is modified Redmine checks watchers list of the issue and notifies them by email about what happened. Orangutan supports this functionality by notifying watchers by Jabber.

Orangutan also introduces watching projects.

Watching project or issue

If you would like to watch projects or issues do:

You: Notify me when new issues are added to Vendini
You: Notify me about changes in #528
You: Add me to watchers list of #685
You: Watch Orangutan
You: Watch #127

Listing watched objects

As it was mentioned earlier Orangutan allows watching issues and projects. It also allows users to quickly check what they are watching:

You: Which projects do I watch?
You: What am I watching?
You: List watched issues
You: Watch list

You can list issues and projects or you can list only projects or issues...

Stop watching

You can stop watching project or issue:

You: Stop notifying me about new issues in Vendini
You: Unfollow #528
You: Stop watching Orangutan


Canceling operation

You can cancel/undo previous operation (e.g. new task creating) using:

You: You did not understand
You: Undo
You: Don't do this
You: Cancel
You: Forget it

Checking version of Orangutan

You: Show current version
You: What is your version?

Checking new features

To see what is new in some version of Orangutan do (by default shows changes in current version):

You: What's new?
You: What's new in 1.05?


Listing projects

To see the list of projects do:

You: Show projects
You: What are projects?

You can list subprojects of some project:

You: Show projects of UPC

Listing issues

On how to list issues check Listing issues section above.

Listing activities

To see the list of activities for the project do:

You: Show activities on PayPartners
You: What are activities on Vendini?

List holidays

You: Show holidays
You: Show holidays in 2010

WARNING: Currently only Ukrainian holidays are supported.


Task names

In reports users usually write tasks names and optionally hours. Tasks names are not the same as issue title - they are short descriptions of what you do. A user can do the same on different days etc.

Orangutan can show you tasks names you worked on during some period: Check this:

You: Report for this month
You: Tasks report for the previous math
You: Give me my tasks report till August 1
You: Show tasks report on Orangutan for this month

The syntax is:

You: Show tasks for <Project> <Period>

If no period is specified a tasks report for the previous month is generated.


To get a very detailed report on time you spent for different activities of an issue ask:

You: How much time did I spend for each activity on #246?
You: How many hours I spent for activities on #203?
You: Show me activities report for #563
You: Report for #668


Not just a report - but a helping statistics to determine how much time you need to add and when. To see how much time did you spent each day do:

You: How much time did I spent per day during this month?
You: How many hours I spent per day?
You: Daily report for previous month
You: Days

The syntax is:

You: Daily report for <Project> <Period>


To get help:

You: Can you help me?
You: I need your help
You: Help

This gives a short tutorial on how to use Orangutan.

If you want more details ask any of the questions listed in FAQ:

You: FAQ

You can also refer to the question by number just after you typed “FAQ”.

Terms of use | Privacy policy