Timelines

Timelines enable the Remember The Milk API to allow certain actions to be undone. The Remember The Milk web application requests a new timeline every time the application is visited — it is up to the API user to determine how often to request a new timeline. Timelines do not expire, but they must always be used.

Timelines can be thought of as long-running database transactions within which individual sub-transactions (API method calls) can be reverted. The start of a timeline is a snapshot of the state of a users' contacts, groups, lists and tasks at that point in time. Method calls can be reverted continouously until the start of the timeline is reached.

Most contact, group, list and task methods require a timeline. New timelines can be obtained by calling the rtm.timelines.create method.

If successful, the contact, group, list and task methods return a <transaction> element. The id attribute of this element points to a transaction within the timeline passed to the called method. If the called method is revertable, an undoable attribute is set on the <transaction> element with a value of 1.

A call to rtm.transactions.undo with a transaction_id that is undoable will revert a contact, group, list or task to its state prior the method call being reverted.

Example

After authentication and getting a valid token, we ask for a timeline (rtm.timelines.create):

<rsp stat="ok">
  <timeline>744432</timeline>
</rsp>

We then use this timeline value to call rtm.tasks.setPriority to change the priority of a task from 2 to 1.

<rsp stat="ok">
  <transaction id="448653398" undoable="1"/>
  <list id="387546">
    <taskseries id="650390" created="2015-05-08T11:33:22Z" modified="2015-05-08T11:34:28Z"
               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="1" postponed="0" estimate=""/>
    </taskseries>
  </list>
</rsp>

We now have our undoable <transaction> element. We decide that we want to revert the task's priority back to what it was (2) – so we call rtm.transactions.undo with a transaction_id of 448653398.

<rsp stat="ok"/>

We then check the state of our task by calling rtm.tasks.getList...

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

And we note that the task now has its old priority of 2.