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

6 April 2017

Features

  • (Public Beta) Zapier Integration!

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

19 February 2015

Features

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

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.

15 December 2014

Features

Developing for Inthe.AM

https://travis-ci.org/coddingtonbear/inthe.am.png?branch=development

Environment Architecture

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

_images/docker_diagram.png

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

Prerequisites

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.

  1. Go to Google’s developer console.

  2. Create a new project.

  3. From within your project, create a new “Client ID” by going to “APIs & Auth” > “Credentials” and clicking on the “Create New Client ID” button.

  4. Select “Web Application”

  5. Enter the following for ‘Authorized Javascript Origins’:

    http://127.0.0.1
    http://localhost
    
  6. Enter the following for ‘Authorized Redirect URI’:

    http://127.0.0.1:8000/complete/google-oauth2/
    
  7. Save

  8. You will be presented with your newly-generated client ID.

  9. Enter the value of “Client ID” into your environment_variables.sh as the value of the TWWEB_SOCIAL_AUTH_GOOGLE_OAUTH2_KEY.

  10. Enter the value of “Client Secret” into your environment_variables.sh as the value of the TWWEB_SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET.

  11. If you are currently running an existing runserver session, you will want to close it, run source environment_variables.sh to update your environment with the environment variables you’ve set, and start the runserver 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:

  1. Resets your Taskserver synchronization settings such that Inthe.AM will synchronize with the built-in Taskserver.
  2. Clears any previously-synced tasks from your Inthe.AM Taskserver account. This is to make sure that you have a clean slate.
  3. 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.

  1. 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.

  2. 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:

  1. 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 is 9d2b26ef-c4cf-491b-8b9a-6a8d9fe67c72@inthe.am, the e-mail address you’d add as a contact would be 9d2b26ef-c4cf-491b-8b9a-6a8d9fe67c72+review@inthe.am.

  2. 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.