Inthe.AM¶
What’s New?¶
16 October 2020¶
- Docker: Inthe.am’s development and production environments have been containerized. You can now start up a development environment much more easily than before; see Setting up a Development Environment.
15 December 2018¶
- Bugwarrior support removed (see https://github.com/coddingtonbear/inthe.am/issues/303)
25 July 2015¶
Features¶
- Bugwarrior: Bugwarrior is a tool that allows you to synchronize issues assigned to you from JIRA, Github, and other services with your Taskwarrior task list. Now, you can use Bugwarrior directly with Inthe.AM.
5 July 2015¶
Features¶
- iCal feeds: In addition to our existing RSS and Pebble Cards feeds, you can now enable two iCal feeds showing the due dates or waiting dates of your tasks.
- (Public Beta) Trello Integration: By turning on this feature, Inthe.AM will create a new Trello board on your account, and will automatically synchronize changes between your Trello board, Inthe.AM and your local Taskwarrior task list. Relatedly, cancelled earlier Kanban Boards Project: #146 Kanban Board <https://github.com/coddingtonbear/inthe.am/issues/146>.
- Added Gitter channel <https://gitter.im/coddingtonbear/inthe.am> replacing the existing Freenode IRC channel.
Technical¶
- Altered the way synchronizations and task changes are announced within the system for triggering synchronizations to use Redis’ PubSub rather than periodically synchronizing and announcing newly-found events.
- Various changes to testing behavior to increase speed including enabling
fast-fail of tests, and installing Taskserver and Taskwarrior from
deb
packages. - Disabled full integration testing of the Google log-in process. Google has began requiring that the user walk through a verification process after signing-in, and the complexities involved in making a bot able to walk through that verification process outweighs the risks of the feature breaking.
- Began sending logging events to Loggly for easier analysis.
19 April 2015¶
Deprecations¶
- Non-local Sync: Synchronization with non-local taskservers was deprecated. See #167: Deprecate synchronization using non-local Taskservers for more information.
19 February 2015¶
Features¶
- Added functionality allowing a user to configure under what circumstances should Inthe.AM reply to incoming text messages; this addresses concerns raised in #164.
16 February 2015¶
Features¶
- (Private Beta) Team Kanban Boards: Added configurable Kanban Board functionality allowing teams to collaborate on shared tasks. Completes Phase 1 of #146 Kanban Board.
Technical¶
- Updated sync behavior in a few fundamental ways:
- Inthe.AM will automatically synchronize local user task lists as sync events are seen in the Taskserver logs.
- Rather than periodically initiating a sync while connected to the status stream; simply waits for head changes from the synchronization operation finished in the above step.
- Users using non-local Taskservers will no longer have access to streaming task information, and will instead need to click the ‘Refresh’ button to synchronize tasks.
- Removed functionality allowing one to disable the task update stream. Very few users were using the functionality allowing one to disable it.
Deprecation Warnings¶
- Synchronization using non-local Taskservers will be disabled after 1 April 2015. Configuring an existing account to synchronize with a non-local Taskserver will be disabled in the near future. See #167: Deprecate synchronization using non-local Taskservers for more information.
30 January 2015¶
Features¶
- Attachment annotations: New attachments will now add annotations containing a link to the uploaded attachment in S3; this makes it easier to access your annotations when using Taskwarrior clients other than Inthe.AM.
- Automatic SMS arguments: You can now specify default tags and attributes for incoming SMS messages; this makes it easy for you to make sure you can those messages you wrote while on a bumpy bus or train so you can clean up those tasks later.
18 January 2015¶
Features¶
- Updated documentation and added link to documentation to the page UI.
Technical¶
- Updated front-end Javascript code to use Ember-CLI to remove the existing one-off Javascript bundle build process.
- Completed #133: “Switch from using one-off $.ajax requests to using promises.”.
- Completed #132: “Show loading animation when performing XHRs from the configuration page.”.
- Completed #131: “Display returned errors rather than a generic error message when interacting with the configuration page.”.
15 December 2014¶
Features¶
- Added keyboard shortcuts and the
?
UI. - Created Taskwarrior Inthe.AM Utility.
Developing for Inthe.AM¶

Environment Architecture¶
Inthe.AM requires an array of docker containers to operate; the below diagram outlines which services connect to one another.

Event Bus Messages¶
Inthe.AM relies on a Redis PubSub queue for interprocess communication; these events convey real-time information about things like when a synchronization has taken place, and what tasks were changed. Below, organized by emitting service, you’ll find information about what sorts of information can be found on the event bus.
Web¶
__general__¶
Emitted to send out general public announcements.
interface Message {
title: string // Toast message title
message: string // Toast message body
system: boolean
}
personal.<USERNAME>¶
Emitted to cause a toast message to be displayed to a particular user.
interface Message {
username: string
title: string // Toast message title
message: string // Toast message body
}
local_sync.<USERNAME>¶
Emitted after a synchronous synchronization between the Inthe.AM web interface and the Taskd server has completed.
interface Message {
username: string
debounce_id: string // Used for debouncing sync requests
start: str // Git SHA
head: str // Git SHA
}
changed_task.<USERNAME>¶
After completing any task operation, one message of this type is emitted for every changed task.
interface Message {
username: string
start: string // Git SHA
head: string // Git SHA
task_id: string // UUID
task_data: {
[key: string]: any
}
changes: {
[key: string]: str[]
}
}
log_message.<USERNAME>¶
Emitted when a new log message is written to a user’s taskstore logs.
interface Message {
username: string
md5hash: string // Deduplication hash
last_seen: string // Datetime
created: string // Datetime
error: boolean
silent: boolean
message: string
count: number // Number of times this message has been seen
}
incoming_mail.<USERNAME>¶
interface Message {
username: string
message_id: number
subject: string
accepted: boolean
rejection_reason?: 'passlist' | 'subject' // If not accepted
task_id?: string // UUID
}
incoming_trello_change.<USERNAME>¶
Emitted when incoming data is received from Trello; usually indicating that a change occurred in Trello that we should update the relevant task list for.
interface Message {
action: {
id: string
type: string
},
model: {
id: string
}
}
Note that the above interface is extremely incomplete. Please consult https://developer.atlassian.com/cloud/trello/guides/rest-api/webhooks/ for more information about what might be possible in this type of message.
Taskd¶
sync.<USERNAME>¶
Emitted immediately after completion of a sync event.
interface Message {
action: 'sync'
username: string
org: string
client: string
ip: string
port: number
client_key: string
record_count: number
branch_point: string
branch_record_count: number
delta_count: number
stored_count: number
merged_count: number
service_duration: number
}
taskd.certificate.<USERNAME>¶
Emitted at the conclusion of determining whether a user-provided synchronization certificate should be accepted.
interface Message {
username: string
org: string
client: string
ip: string
port: number
fingerprint: string
certificate_recognized: bool
certificate_accepted: bool
}
Setting up a Development Environment¶
Setup¶
Before starting your environment, you will need to generate a keypair for the HTTPS server. From a your clone of the Inthe.AM repository, run the following commands:
cd docker/nginx/secrets
openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt -days 365 -nodes
After that, you can bring up your development environment:
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up
Note
Specifying the dockerfiles as shown above will launch your server in “development” mode. This has the following effects:
- Your server is started using Django’s built-in runserver. This runserver is configured to automatically restart should you make any changes to relevant source files.
- A debugger is available on port 3000. This is pre-configured for use in Vscode via the “Connect to Django” debugger.
- The event stream will be disabled; so you will need to manually refresh tasks using the “Refresh” button on the top of the screen.
Running in this mode is useful for development,
but does make it impossible for you to work on changes to the event stream.
If you do need to make changes to the event stream,
be sure to start the server in the more-basic way
(i.e. docker-compose up
),
but keep in mind that the other helpful functions provided to you
will also no longer be available.
You can now access the site by connecting to https://localhost/.
Troubleshooting your Development Environment¶
- Various environment variables are set in
.private.env
, and you will need to set at least the following two environment variables to use the site; see Google OAuth Keys for details regarding what you should set these variables to:SOCIAL_AUTH_GOOGLE_OAUTH2_KEY
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET
Testing¶
Running Tests¶
You can easily run the tests from the development environment by running the following command:
python manage.py runtests
Note
By default, tests run in PhantomJS, but if you would like to
see the tests in action, you can run them in Firefox by setting
the the TWWEB_WEBDRIVER_BROWSER
environment variable to
firefox
; for example:
TWWEB_WEBDRIVER_BROWSER=firefox python manage.py runtests
Contribution Guidelines¶
Contributions are welcome – especially for bug fixes – but, if you
would like to add a new feature, please open up a new issue in
the issue tracker
or discuss the proposed changes with coddingtonbear
on
the gitter.im channel https://gitter.im/coddingtonbear/inthe.am before getting started to ensure work is not
already ongoing toward solving your problem – nobody likes wasting their
time!
Google OAuth Keys¶
Follow the following steps to generate Google OAuth credentials to use for development and testing. These are used for the log-in process, and are functionally essential for doing much of anything with Inthe.AM.
Go to Google’s developer console.
Create a new project.
From within your project, create a new “Client ID” by going to “APIs & Auth” > “Credentials” and clicking on the “Create New Client ID” button.
Select “Web Application”
Enter the following for ‘Authorized Javascript Origins’:
http://127.0.0.1 http://localhost
Enter the following for ‘Authorized Redirect URI’:
http://127.0.0.1:8000/complete/google-oauth2/
Save
You will be presented with your newly-generated client ID.
Enter the value of “Client ID” into your
environment_variables.sh
as the value of theTWWEB_SOCIAL_AUTH_GOOGLE_OAUTH2_KEY
.Enter the value of “Client Secret” into your
environment_variables.sh
as the value of theTWWEB_SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET
.If you are currently running an existing
runserver
session, you will want to close it, runsource environment_variables.sh
to update your environment with the environment variables you’ve set, and start therunserver
once again.
API Documentation¶
Inthe.AM provides a RESTful API that you can use for creating, modifying, or deleting tasks in your task list.
Authentication¶
Inthe.AM relies upon you supplying your API key in the Authorization
header; if your API key
was “MYAPIKEY”, you would add the following header:
Authorization: Token MYAPIKEY
You can find your API key in the “API Access” section of your Inthe.AM Configuration.
Response Codes¶
All endpoints share the following list of common response codes:
Response Code | Description |
---|---|
200 | Success |
201 | Successfully created |
400 | Your request was malformed, or the requested operation was impossible. A description of the problem will be included in the response. |
401 | Your request did not include proper authentication headers. Make sure that you have properly sent the Authorization header described in Authentication. |
403 | Your request was not properly authenticated or you have requested an entity for which you do not have access. Make sure that you have properly sent the Authorization header described in Authentication. |
404 | The entity you requested does not exist. |
405 | The request method used is not allowed for the endpoint you are sending it to. Please review the below documentation and alter your request to use an acceptable method. |
409 | Your repository is currently locked. See Repository Lock for more details. |
500 | A server error occurred while processing your request. An error was logged and the administrators of the site have been notified. Please try your request again later. |
Task Format¶
Each task has at least the following fields:
Field | Description |
---|---|
id |
(read-only, primary key) The unique ID number of a task. These are stable and can be used in situations where you may want to retrieve a task after it has been completed. |
uuid |
(read-only, primary key) DEPRECATED Please use id to
fetch your task’s ID number. |
short_id |
(read-only, primary key) Returns the short ID of the task. Note that this number is unstable and will change as tasks are added/removed from the pending task list. |
resource_uri |
(read-only) This is the URL at which this task can be retrieved again in the future. It will match the URL you used for fetching this task unless you fetched this task from a listing endpoint. |
status |
One of ‘pending’, ‘completed’, ‘waiting’, or ‘deleted’. New tasks default to ‘pending’. |
urgency |
(read-only) A float representing the current calculated urgency level of a task. This is generated internally by Taskwarrior. |
description |
The title of the task. |
priority |
One of ‘H’, ‘M’, or ‘L’. |
due |
A date string [1] representing this task’s due date and time. |
entry |
(read-only) A date string [1] representing this task’s entry date and time. |
modified |
(read-only) A date string [1] representing the last time that this task was modified. |
start |
A date string [1] representing the date and time this task was last started. |
wait |
A date string [1] representing the minimum date and time at which this task should appear in the pending task list. |
until |
A date string [1] representing the maximum date and time at which this task should appear in the pending task list. |
scheduled |
A date string [1] representing the minimum date and time at which this task is scheduled. |
depends |
A list of tasks upon which this task is dependent. |
annotations |
A list of annotations added to the task [#annotations]_. |
tags |
A list of tags assigned to this task. |
imask |
(read-only) A value representing this task’s imask . This is a
property used internally by Taskwarrior for recurring tasks. |
The task is formatted into JSON for use by the API; for example, below is a JSON-formatted task:
{
"annotations": [
"Chapter 1",
"Chapter 2",
],
"depends": null,
"description": "The wheels on the bus go round and round",
"due": null,
"entry": "2014-02-03T01:52:51Z",
"id": 1,
"imask": null,
"modified": "2014-02-03T01:52:51Z",
"priority": null,
"project": "Alphaville",
"scheduled": null,
"start": null,
"status": "waiting",
"tags": ["very_unimportant", "delayed"],
"urgency": -0.1,
"uuid": "b8d05cfe-8464-44ef-9d99-eb3e7809d337",
"wait": "Thu, 6 Feb 2014 01:52:51 +0000"
}
Warning
If you neglect to supply a timezone offset in a supplied date string, the incoming date string will be interpreted to be a UTC timestamp.
[1] | (1, 2, 3, 4, 5, 6, 7) ISO-8601 format. |
Endpoints¶
Pending Tasks¶
Task List¶
URL: https://inthe.am/api/v2/tasks/
Method | Description |
---|---|
GET |
List all pending tasks. |
POST |
Given a task payload, create a new task. |
Task Details¶
URL: https://inthe.am/api/v2/tasks/<TASK_UUID>/
Method | Description |
---|---|
GET |
Get task details. |
PUT |
Given a JSON task payload, update the task’s details. |
DELETE |
Mark the existing task as completed. |
Non-users of Taskwarrior may be surprised by the DELETE
method’s
behavior of this endpoint given that the task is not actually deleted, but
instead marked as completed, but this implementation is much more consistent
with Taskwarrior workflows.
Note
To truly delete a task, see Delete a Task below.
Delete a Task¶
URL: https://inthe.am/api/v2/tasks/<TASK_UUID>/delete/
Method | Description |
---|---|
POST |
Mark an existing task as deleted. |
Although using the DELETE
method on the
Task Details endpoint may seem to be more intuitive, it is far
more common for one to mark a task as completed than deleted.
If that doesn’t set your mind at ease, try to think
of the Task List and Task Details endpoints as being listings of
only pending tasks, and that by issuing a DELETE
request
you’re removing it from your pending task list (and
moving it to your completed task list).
Start a Task¶
URL: https://inthe.am/api/v2/tasks/<TASK_UUID>/start/
Method | Description |
---|---|
POST |
Mark an existing task as started. |
Stop a Task¶
URL: https://inthe.am/api/v2/tasks/<TASK_UUID>/stop/
Method | Description |
---|---|
POST |
Mark an existing task as stopped. |
Feeds¶
RSS Feed¶
Returns an RSS representation of your current pending tasks.
Note
This endpoint is not authenticated, and is thus disabled unless specifically enabled in your configuration.
After enabling this endpoint in your configuration, you will be
given the proper URL to use (including your SECRET_ID
).
URL: https://inthe.am/api/v2/tasks/feed/<SECRET_ID>/
Method | Description |
---|---|
GET |
RSS Tasks Feed. |
Utility Endpoints¶
Repository Lock¶
Warning
Do not use this endpoint unless you absolutely know what you are doing. Manually unlocking your repository while an action is in progress may result in data loss!
URL: https://inthe.am/api/v2/tasks/lock/
Method | Description |
---|---|
DELETE | Manually unlock your repository. |
GET | Check whether your repository is currently locked. Will return a 200 if it is, and a 404 if it is not. |
Enable Synchronization¶
You can re-enable synchronization if it has been disabled
by sending an empty POST
to this endpoint.
URL: https://inthe.am/api/v2/user/enable-sync/
Method | Description |
---|---|
POST |
Enable synchronization. |
User Information¶
Status¶
Returns brief JSON-formatted information about the currently logged-in user.
Note
This endpoint does not require authentication. If you are not authenticated via an API key or a cookie, you will receive only limited information.
URL: https://inthe.am/api/v2/user/status/
Method | Description |
---|---|
GET |
Get user data. |
Announcements¶
Returns a JSON-formatted list of recent announcements.
URL: https://inthe.am/api/v2/user/announcements/
Method | Description |
---|---|
GET |
Get announcements. |
Download my certificate¶
Returns your currently-active certificate used for communicating with Inthe.AM.
URL: https://inthe.am/api/v2/user/my-certificate/
Method | Description |
---|---|
GET |
Get certificate. |
Download my key¶
Returns your currently-active key used for communicating with Inthe.AM.
URL: https://inthe.am/api/v2/user/my-key/
Method | Description |
---|---|
GET |
Get key. |
Download CA certificate¶
Returns Inthe.AM’s certificate; this is used for synchronizing with Inthe.AM’s taskd server.
URL: https://inthe.am/api/v2/user/ca-certificate/
Method | Description |
---|---|
GET |
Get CA certificate. |
Configuration¶
Update .taskrc
¶
Locally, Inthe.AM runs Taskwarrior in a way that’s very similar to
how you interact with Taskwarrior on your personal computer, and a
.taskrc
file is read and used for calculating things like UDAs
and priorities.
Use this endpoint to see or set your current .taskrc
’s contents on
Inthe.AM.
URL: https://inthe.am/api/v2/user/taskrc/
Method | Description |
---|---|
GET |
Get .taskrc file’s contents. |
PUT |
Set .taskrc file’s contents. |
Generate a new taskserver certificate¶
If you would like to regenerate your Taskserver certificate, usually because your existing one has expired, you can do so using this endpoint.
URL: https://inthe.am/api/v2/user/generate-new-certificate/
Method | Description |
---|---|
POST |
Generate new Taskserver Certificate. |
Reset taskserver settings¶
If you’ve changed your Taskserver settings, but you’d like to reset
them such that Inthe.AM’s built-in taskserver is utilized, send an empty
POST
request to this endpoint.
Note
Using this endpoint does a number of things:
- Resets your Taskserver synchronization settings such that Inthe.AM will synchronize with the built-in Taskserver.
- Clears any previously-synced tasks from your Inthe.AM Taskserver account. This is to make sure that you have a clean slate.
- Clears the local Taskwarrior repository’s
backlog.data
file.
None of these should be considered particularly dangerous, but this is not an operation that can be undone without administrative intervention.
URL: https://inthe.am/api/v2/user/reset-taskd-configuration/
Method | Description |
---|---|
POST |
Reset Taskserver configuration. |
SMS messaging (Twilio) integration¶
You can configure or enable SMS integration by
sending a POST
request to this endpoint with
two form-encoded variables:
twilio_auth_token
: Your Twilio Auth Token. This is used for authenticating the SMS request from Twilio.sms_whitelist
: A newline-separated list of phone numbers from which you would like to accept new tasks.sms_replies
: An integer indicating under what conditions should Inthe.AM send SMS message replies. See the table below for information about what values are appropriate:Value Meaning 0 Do not reply to any incoming text messages 5 Reply only to error messages 9 Reply to all messages
URL: https://inthe.am/api/v2/user/twilio-integration/
Method | Description |
---|---|
POST |
Configure SMS Integration. |
Email integration¶
You can configure which e-mail addresses are allowed to send new
tasks to your personal task creation e-mail address by sending a POST
to this address with the following form-encoded variable:
email_whitelist
: A newline-separated list of e-mail addresses from which you will allow new tasks to be created when an e-mail email message is received.
URL: https://inthe.am/api/v2/user/email-integration/
Method | Description |
---|---|
POST |
Configure Email Integration. |
Clear task data¶
You can clear your taskserver information by sending a POST
request
to this endpoint.
Please note that this does not permanently delete your task information; it only clears your taskserver information; if you would like your taskserver information cleared permanently, please send an email to admin@inthe.am.
URL: https://inthe.am/api/v2/user/clear-task-data/
Method | Description |
---|---|
POST |
Clear Taskserver information. |
Colorscheme¶
You can configure the colorscheme used when displaying your tasks
by sending a PUT
request to this URL having a body matching
the colorscheme you would like to use.
Options include:
light-16.theme
dark-16.theme
light-256.theme
dark-256.theme
dark-red-256.theme
dark-green-256.theme
dark-blue-256.theme
dark-violets-256.theme
dark-yellow-green.theme
(default)dark-gray-256.theme
solarized-dark-256.theme
solarized-light-256.theme
You can also send a GET
request to find the name of the colorscheme
currently in use.
URL: https://inthe.am/api/v2/user/colorscheme/
Method | Description |
---|---|
GET |
Get current colorscheme. |
PUT |
Set colorscheme. |
RSS feeds¶
You can enable or disable the RSS feed showing your upcoming tasks by
sending a POST
request:
- To enable: Send a single form-encoded parameter –
enabled
in the request. - To disable: Send an empty request.
URL: https://inthe.am/api/v2/user/feed-config/
Method | Description |
---|---|
POST |
Enable/Disable RSS feed. |
Cookbook¶
To add items to this cookbook, click the ‘Edit on Github’ button in the upper-right corner.
Making it easy to find tasks submitted via SMS¶
If you’re anything like me, you usually submit your tasks via SMS only when you’re on a crowded train or bumpy car ride, so your tasks are abbreviated, often misspelled, and never include crucial information like project information and due dates.
You can make it easy on yourself by setting Inthe.AM to automatically
add a high-coefficient tag to tasks incoming via SMS by making a minor
change to both your .taskrc
file on Inthe.AM and your SMS configuration.
Update the field “Automatic Arguments” in “SMS Access” from your Configuration & Settings page to include the text
+review
. This will cause all tasks incoming via SMS to have that tag added to its attributes.Add a line to your
.taskrc
on Inthe.AM and locally that causes tasks having this tag to float to the top of your tasks list.For example:
urgency.user.tag.review.coefficient=99
The above urgency setting causes the urgency of tasks tagged with
+review
to increase by 99 points – almost certainly higher than any other tasks you might have.
Now, once you’re nearby your computer again, you’ll find those tasks at the top of your task list.
Making it easy to find tasks submitted via Email¶
Every once in a while, a task that I need to accomplish comes to mind when I’m far away from a computer and I might send my Inthe.AM account a quick e-mail to add a task. Usually, though, I don’t specify enough information, and want to add a little more data once it’s in my task list.
You can easily add a tag to incoming tasks that makes those tasks you’ve added appear at the top of your task list for easy prioritization by following these short steps:
Add a contact to your e-mail contact list that automatically assigns a tag
+review
to the created task, so you can use it for finding tasks that you need to review and prioritize next time I’m nearby a computer.You can do this by adding
+review
to the end of your Inthe.AM e-mail address; for example, if your Inthe.AM e-mail address is9d2b26ef-c4cf-491b-8b9a-6a8d9fe67c72@inthe.am
, the e-mail address you’d add as a contact would be9d2b26ef-c4cf-491b-8b9a-6a8d9fe67c72+review@inthe.am
.Add a line to your
.taskrc
on Inthe.AM and locally that causes tasks having this tag to float to the top of your tasks list.For example:
urgency.user.tag.review.coefficient=99
The above urgency setting causes the urgency of tasks tagged with
+review
to increase by 99 points – almost certainly higher than any other tasks you might have.
Now, while you’re on the go, you can just find that contact in your contact list and send off a quick message. When the task is added to your task list, it’ll appear at the top.
Note
Although posted on Github, the intention of this repository is to make it easier for users to find bugs, prototype features, and generally use this as a model for their own Django+Ember.JS sites.
Setting this up locally as a clone of Inthe.AM is, unfortunately, not supported.
Found a bug, or want to suggest a new feature? Enter an issue on Inthe.AM’s issue tracker.
Questions? Ask on Gitter.
Released under the GNU AFFERO GENERAL PUBLIC LICENSE.