API

Build cool stuff that works with Remember The Milk.

menu

Tasks

Tasks are identifed in Remember The Milk API via their list_id, taskseries_id and task_id. Therefore, most methods in rtm.tasks require that these three arguments be provided (all three are checked for validity and permissibility prior to method execution).

The path to a task

list_id specifies the list in which a taskseries resides.

taskseries_id specifies the task series in which a task resides.

And finally, task_id specifies the task on which to operate.

What's a task series?

A task series is a grouping of tasks generated by a recurrence pattern (more specifically, a recurrence pattern of type every – an after type recurrence generates a new task series for every occurrence).

Task series' share common properties such as:

  • Name.
  • Recurrence pattern.
  • Tags.
  • Notes.
  • Priority.

Therefore, when invoking methods such as rtm.tasks.setRecurrence on a list_id/taskseries_id/task_id it is infact the task series state that is modified. task_id is required to establish consistency across the API, since the concept of a task series is somewhat of an implementation detail.

Understanding the output of rtm.tasks.getList

We'll start by retrieving all tasks in list 387546 (rtm.tasks.getList(list_id=387546)):

<rsp stat="ok">
  <tasks>
    <list id="387546">
      <taskseries id="650390" created="2015-05-08T11:33:22Z"
      modified="2015-05-08T11:37:18Z" name="Demonstrate Timelines"
      source="api">
        <tags />
        <participants />
        <notes />
        <task id="815255" due="" has_due_time="0"
        added="2015-05-08T11:33:22Z" completed="" deleted=""
        priority="2" postponed="0" estimate="" />
      </taskseries>
    </list>
  </tasks>
</rsp>

Let's add a task, Demonstrate Tasks, with rtm.tasks.add(list_id=387546,name="Demonstrate Tasks").

<rsp stat="ok">
  <transaction id="449135792" undoable="0" />
  <list id="387546">
    <taskseries id="650834" created="2015-05-08T13:52:26Z"
    modified="2015-05-08T13:52:26Z" name="Demonstrate Tasks"
    source="api">
      <tags />
      <participants />
      <notes />
      <task id="815784" due="" has_due_time="0"
      added="2015-05-08T13:52:26Z" completed="" deleted=""
      priority="N" postponed="0" estimate="" />
    </taskseries>
  </list>
</rsp>

We'll fetch the list again to see the new task in the list.

<rsp stat="ok">
  <tasks>
    <list id="387546">
      <taskseries id="650834" created="2015-05-08T13:52:26Z"
      modified="2015-05-08T13:52:26Z" name="Demonstrate Tasks"
      source="api">
        <tags />
        <participants />
        <notes />
        <task id="815784" due="" has_due_time="0"
        added="2015-05-08T13:52:26Z" completed="" deleted=""
        priority="N" postponed="0" estimate="" />
      </taskseries>
      <taskseries id="650390" created="2015-05-08T11:33:22Z"
      modified="2015-05-08T11:37:18Z" name="Demonstrate Timelines"
      source="api">
        <tags />
        <participants />
        <notes />
        <task id="815255" due="" has_due_time="0"
        added="2015-05-08T11:33:22Z" completed="" deleted=""
        priority="2" postponed="0" estimate="" />
      </taskseries>
    </list>
  </tasks>
</rsp>

As we can see, the new task is now part of the list. We'll modify the priority of the task. Let's give it a priority of 2 by calling rtm.tasks.setPriority(list_id=387546,taskseries_id=650834,task_id=815784,priority=2).

<rsp stat="ok">
  <transaction id="449183149" undoable="1" />
  <list id="387546">
    <taskseries id="650834" created="2015-05-08T13:52:26Z"
    modified="2015-05-08T14:04:01Z" name="Demonstrate Tasks"
    source="api">
      <tags />
      <participants />
      <notes />
      <task id="815784" due="" has_due_time="0"
      added="2015-05-08T13:52:26Z" completed="" deleted=""
      priority="2" postponed="0" estimate="" />
    </taskseries>
  </list>
</rsp>

The task now has a priority of 2. Let's imagine that Bob actually changed the priority of this task (he shares my account and is logged in via the web application). We don't want to retrieve the whole list every few minutes – a large list might take a long time to transfer or process by a client application. So we'll pass the last_sync parameter to the rtm.tasks.getList method.

We can use an arbitrary value (the last time we requested the list is a good candidate), or, perhaps, the creation date of the Demonstrate Tasks task. Calling rtm.tasks.getList(list_id=387546,last_sync="2015-05-08T13:52:26Z") returns:

<rsp stat="ok">
  <tasks>
    <list id="387546" current="2015-05-08T13:52:26Z">
      <taskseries id="650834" created="2015-05-08T13:52:26Z"
      modified="2015-05-08T14:04:01Z" name="Demonstrate Tasks"
      source="api">
        <tags />
        <participants />
        <notes />
        <task id="815784" due="" has_due_time="0"
        added="2015-05-08T13:52:26Z" completed="" deleted=""
        priority="2" postponed="0" estimate="" />
      </taskseries>
    </list>
  </tasks>
</rsp>

Only tasks modified since last_sync have been returned.

What happens to deleted tasks?

We'll delete the Demonstrate Timelines task by calling rtm.tasks.delete(list_id=387546,taskseries_id=650390,task_id=815255):

<rsp stat="ok">
  <transaction id="449274118" undoable="1" />
  <list id="387546">
    <taskseries id="650390" created="2015-05-08T11:33:22Z"
    modified="2015-05-08T14:26:47Z" name="Demonstrate Timelines"
    source="api">
      <tags />
      <participants />
      <notes />
      <task id="815255" due="" has_due_time="0"
      added="2015-05-08T11:33:22Z" completed=""
      deleted="2015-05-08T14:26:47Z" priority="2" postponed="0"
      estimate="" />
    </taskseries>
  </list>
</rsp>

The deleted attribute on the <task> element notes the time at which the task was deleted.

Let's retrieve the list again, with the same last_sync value as the previous call. Calling rtm.tasks.getList(list_id=387546,last_sync="2015-05-08T13:52:26Z") returns:

<rsp stat="ok">
  <tasks>
    <list id="387546" current="2015-05-08T13:52:26Z">
      <taskseries id="650834" created="2015-05-08T13:52:26Z"
      modified="2015-05-08T14:04:01Z" name="Demonstrate Tasks"
      source="api">
        <tags />
        <participants />
        <notes />
        <task id="815784" due="" has_due_time="0"
        added="2015-05-08T13:52:26Z" completed="" deleted=""
        priority="2" postponed="0" estimate="" />
      </taskseries>
      <deleted>
        <taskseries id="650390">
          <task id="815255" deleted="2015-05-08T14:26:47Z" />
        </taskseries>
      </deleted>
    </list>
  </tasks>
</rsp>

The <list> now has child element, <deleted>, that advises us that a task (specified by the taskseries_id/task_id) was deleted since our last sync.