Eastgate

Email and Twitter from Tinderbox

Tinderbox helps you visualize, analyze, and share your ideas. Download and try it.

 

Email and Twitter from Tinderbox

Tinderbox talks to your colleagues and to Web 2.0

Prof. Kate Carter finds herself (as always) on deadline and on the spot. She's a biologist. The legislature of Pacifica is considering a measure to acquire Ely's Fields, the farm once owned by a noted novelist Horace Smithson and which is familiar to ornithologists and birdwatchers throughout the world. If the estate isn't protected this year, it may well be sold piecemeal to developers before the next session.

Kate emails her colleagues, and soon she has recruited a group of eager volunteers. Some are colleagues at other universities, some are students, others are activists or birdwatchers or the Smithson scholars. Some work right down the hall from Kate, but others are far away. There's not much time for planning, and no chance they can all meet together before the crucial vote. And while Kate's students use Tinderbox, some of the others don't. Indeed, some rely on cell phones for email, and some plan to check in at airport cybercafs.

Over the coming days, there's going to be lots of information to be gathered, lots of ideas and facts to be written and shared. How can Kate's Tinderbox notes help coordinate and share information?

This advanced tutorial is for Tinderbox users who want to send information automatically from Tinderbox to people and programs. It assumes you are using Tinderbox 4 or later. All the people, places, and institutions mentioned in the tutorial are fictitious, and any resemblance to actual people is entirely coincidental.

This tutorial uses the sendmail and curl programs that are built into MacOS X. These programs are useful and they're widely used, but they can be tricky and might require updating or configuration on your particular system. Your mileage may vary.

Simple Email

a container that emails notes to Web 2.0 services

Tinderbox makes it easy for Kate to jot down all the dozens of things that need to be done in the coming days. Who should be called? Whose support should be solicited? What facts need to be researched? Who will talk to the media?

There's a lot to do. There are plenty of volunteers, but how do they know what would be most useful? If Kate tries to phone everybody, she'll spend all her time on the telephone and still won't keep up.

One thing she can do right away: set up a Web-based ToDo list. A typical service is Backpack from 37 Signals. She signs up for a free account and jots does another thing to do: fundraising!

Kate could retype each of her Tinderbox notes into Backpack, or she could easily copy and paste. But there's an even easier way. She makes a new container called Backpack ToDo List; when she drags a note into this container, she wants Tinderbox to send an email to the backpack server to tell it that she wants a new item added to the group's list.

The container's OnAdd action is surprisingly simple. Backpack provides a magic email address for each user's ToDo list; she copies the address to the container's Email attribute. The Onadd action, then, sends email to $Email(parent) with the Subject line todo: [thing to be done]. runCommand needs a place to save its results; we'll make a new user attribute named result.

$Result=runCommand("sendmail -f [kate's email address] "+$Email(parent), "Subject: todo:"+$Name); BorderColor=poppy;

This assembles a command line

> sendmail -f [kate's email address] address@KateCarter.backpackit.com

This runs the built-in sendmail program, which sends an email from Kate to the backpack address. Sendmail finds the message in its standard input; the message is simply:

Subject: todo: [thing to be done]

So, as soon as Kate knows a task belongs on the group's ToDo list, she drops it in the Backpack container. That way, she also has a record of what she has posted even if someone has changed or deleted the original posting.

email/Backpack.jpg

"assembling a formatted email message with a template

This is fine for short messages to a Web service, but sometimes we'll want to include more information in email especially if it's intended for human readers.

For example, Kate's friend and mentor, Madison Fujihara wants to help, but she's in the field training a group of new graduate students. She doesn't have Web access, but can receive emails through her telephone. Can we keep her up to date?

Email under the hood

We're all accustomed to using email through a program like Mail or Outlook. But how does a program use email? Under the hood, the mechanism is very simple.

An email message begins with a series of headers that describe how the message should be delivered and what should happen if things go wrong. After the headers comes the text of the message. Headers themselves are very simple: the name of the header, a colon, and then the value of the header. For example:

From: "Kate Carter" <kcarter@miskatonic.edu>
To: some address
Subject: subject line

This is the message.

The sendmail program receives the destination address on the command line and the email headers and message from its standard input.

Tinderbox uses templates to build a message from a note; the template tells Tinderbox what information you want to send and how it should be arranged.

From: "Kate Carter" <kcarter@miskatonic.edu>

Subject: ELY'S FIELD: ^title

^text(plain)

-----

This message was sent from Kate Carter's Tinderbox.

We can store this template in a text file; we'll call it SimpleEmail.txt. The new container "Send To Prof. Fujihara" is almost identical to our simple Backpack container, but it uses the template to build more complete messages.

$esult=runCommand("sendmail -f [kate's email address] "+$Email(parent), exportedString(this,SimpleEmail.txt) ); BorderColor=poppy;

ExportedString takes the template and, when it finds a placeholder like ^title or ^text, it substitutes information from the note. So, dropping a note into this container immediately dispatches the note to the recipient(s) in the container's email field.

Assembling and sending a daily summary

using agents to send email you haven't sent before

This works, but it means Prof. Fujihara gets lots of little emails throughout the day. It would be nicer to get a single email, listing all the tasks added since the last update. Fortunately, this is easy to do!

To begin, we'll make a boolean user attribute called Emailed. The default value for Emailed is false; once we've sent the note to Prof. Fujihara, we'll mark Emailed as true.

We can now make an agent, DailySummary. It gathers notes for which Prototype=task & Emailed=false: that is, it gathers Tasks which haven't been emailed. Right now, it has three tasks.

email/Agent.jpg

We'll use a Tinderbox rule to send the email:

if(Emailed=false) {$Result=runCommand("sendmail -f [kate's email address] "+$Email(parent), exportedString(this,Summary.txt) ); Email=true;}

Now, whenever Kate turns the agent's Emailed attribute to false, the rule will run, send the email, and set Emailed once again to true. The email will contain the titles of all the notes that meet the agent's query: in this case, all the tasks that have not already been Emailed. When each task is added to the email, the template sets its Emailed to true, so that task won't be emailed again.

When the email has been composed and sent, the rule turns itself off by setting the agent's own value of Emailed to true. The rule won't run again, sending more emails. Tomorrow, Kate can set Email false, the rule will run, and the agent will send a fresh summary.

The Summary template is much like our SimpleEmail template, but it adds a line to say "include each child of the agent here":

From: "Kate Carter" <kcarter@miskatonic.edu>

Subject: ^title

^text(plain)

^justChildren(title)

The placeholder for ^justChildren will be replaced by a list, applying the template "title" in turn to each child of the agent. The template exports the name of the note, and also sets the note's Emailed attribute to true so that we know it's been sent.

^title

^action(Emailed=true)

Now, Kate simply clicks a checkbox every afternoon, and Professor Fujihara is automatically sent a summary email.
To: Prof Madison Fujihara
From: kcarter@miskatonic.edu
Subject: ELY'S FIELD: today's summary Here are the new tasks I've posted to the Ely's Field project today. Any help you can provide is really appreciated! -- Kate Local use: a talking point? Who are the relevant NGO's?

Twittering from Tinderbox

An adornment that sends messages

As the deadline for the vote nears, Kate's task force moves into high gear. There's a long list of tasks to do, and lots of coordination. In particular, it's essential to know who is committed to support the plan right away.
Twitter is perfect for this kind of tight coordination within a work group:
KCarter: Sen. Card is on board Birdsong: Just spoke to Dillenborth. She's waffling. I think we might lose her. Smithson: Just got back from faculty meeting. Looking tight, isn't it? KCarter: @Smithson Could you start calling with Samuelson and work down from there?
Much of the time, it's fine to type messages to Twitter in your cell phone or your browser or your IM client, but sometimes it might be nicer not to switch windows (or grab your phone!) Let's make an adornment that sends a message to Twitter. Twitter doesn't use email; to send a message to Twitter, you need to post it to a special Web URL. The system has a built-in command to do just this; instead of using sendmail, we use curl. The command line we want looks like this:
> curl -d 'status=message' -u username:password http://twitter.com/statuses/update.atom")

To Twitter, we simply make an adornment with an OnAdd action that assembles and runs this command.

result=runCommand("curl -d 'status="+$Title+":"+$Text+"' -u user:password http://twitter.com/statuses/update.atom")