Usage manual¶
- Usage manual
Important notes¶
There are things you should take care of. Here they go:
- 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.
- 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.
- 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:
- 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.
- 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.
- 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.
Requests¶
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.
Configuration¶
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¶
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.
Examples:
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.
Examples:
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>
Samples:
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?
Issues¶
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? You: TODO
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
Voting¶
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
Watching¶
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
General¶
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¶
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.
Reports¶
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.
Activities¶
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
Days¶
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>
Help¶
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”.