tracks/app/views/integrations/index.en.html.erb

<% has_contexts = !current_user.contexts.empty? -%>
<h1>Integrations</h1>
<p>Tracks can be integrated with a number of other tools...
  whatever it takes to help you get things done!
  This page has information on setting up some of these.
  Not all of these are applicable to all platforms, and some require more
  technical knowledge than others.
  See also <%= link_to "developer documentation for Tracks' REST API", url_for(:action => 'rest_api') %>.</p>
<br/><p>Contents:</p>
<ul>
  <li><a href="#email-cron-section">Automatically Email Yourself Upcoming Actions</a></li>
  <li><a href="#message_gateway">Integrate Tracks with an email server to be able to send an action through email to Tracks</a></li>
  <li><a href="#mailgun">Send emails to Tracks with Mailgun</a>
  <li><a href="#todo_rich_message_format">Rich Todo Message email format</a>
  <li><a href="#google_gadget">Add Tracks as a Google Gmail gadget</a></li>
</ul><br/>
<p>Do you have one of your own to add?
  <a href="http://www.getontracks.org/forums/viewforum/10/" title="Tracks | Tips and Tricks">Tell us about
    it in our Tips and Tricks forum</a> and we may include it on this page in a future versions of Tracks.
</p>

<a name="email-cron-section"> </a>
<h2>Automatically Email Yourself Upcoming Actions</h2>

<p>If you enter the following entry to your crontab, you will receive email every day around 5 AM with a list of the upcoming actions which are due within the next 7 days.</p>

<textarea id="cron" name="cron">0 5 * * * /usr/bin/curl -0 "<%= root_url %>todos.txt?due=6&token=<%= current_user.token %>" | /usr/bin/mail -e -s 'Tracks actions due in the next 7 days' youremail@yourdomain.com</textarea>

<p>You can of course use other text <%= link_to 'feeds provided by Tracks', feeds_path %> -- why not email a list of next actions in a particular project to a group of colleagues who are working on the project?</p>

<a name="message_gateway"> </a>
<h2>Integrated email/SMS receiver</h2>
<p>
  If Tracks is running on the same server as your mail server, you can use the integrated mail handler built into tracks. Steps to set it up:
</p>
<ul>
  <li>Go to <%= link_to t('layouts.navigation.preferences'), preferences_url %> and
    set your "<%= Preference.human_attribute_name('sms_email') %>" and
    "<%= Preference.human_attribute_name('sms_context') %>" for todos sent in
    via email (which could come from an SMS message)</li>
  <li>In sendmail/qmail/postfix/whatever, set up an email address
    alias to pipe messages to <pre>/PATH/TO/TRACKS/bin/rails r -e production 'MessageGateway.receive(STDIN.read)'</pre></li>
  <li>Send an email to your newly configured address!</li>
</ul>
<p>You can also use the Rich Todo API to send in tasks like "do laundry @ Home"
  or "Call Bill > project X". The subject of the message will fill description,
  context, and project, while the body will populate the tasks's note.
</p>
<p>
  You may need to configure your <tt>site.yml</tt> to tell the message gateway to look at the <tt>to:</tt> field or <tt>from:</tt> field to
  lookup Tracks' user from the email address in that field. </p>
  <p>You can also send all email to a specific Tracks user. Configure mail_dispatch in site.yml to <tt>single_user</tt> and pass the login of the user:
    <pre>TRACKS_MAIL_RECEIVER=<%=current_user.login%> /PATH/TO/TRACKS/bin/rails r -e production 'MessageGateway.receive(STDIN.read)'</pre>
</p>

<a name="mailgun"> </a>
<h2>Send emails to Tracks with Mailgun</h2>
<p>
If you want to email tasks to Tracks, but cannot run a mailserver on the same host,
you could use the <a href='www.mailgun.com'>Mailgun</a> support built in to Tracks.
</p>
<p>
For this to work your Tracks server will need to be reachable from the internet, so
that Mailgun can POST data to it.
<p>
<ul>
  <li>Go to <%= link_to 'http://mailgun.com' %> and register for a free account.</li>
  <li>Go to 'Routes' in the Mailgun control panel, and add a new route:</li>
  <ul>
    <li>'Filter expression' should be set to 'catch_all()'</li>
    <li>'Action' should be 'forward("http://mytracksserver.domain.com/mailgun/mime")'
  </ul>
  <li>Go to <%= link_to t('layouts.navigation.preferences'), preferences_url %> and
    enter your incoming Mailgun email address (e.g. tracks@user.mailgun.com) in the
    "<%= Preference.human_attribute_name('sms_email') %>" box.</li>
  <li>Select a default context for emails to be put in with
    "<%= Preference.human_attribute_name('sms_context') %>"</li>
  <li>Add your Mailgun API key (not the Public API key) to the Tracks 'site.yml'
  <li>Update the mailmap in 'site.yml' to define which senders can send emails to
    which incoming addresses. For example, to send emails from your work and home
    email accounts to your tracks Mailgun route, set it up like this:
    <pre class=code>
mailmap:
  tracks@user.mailgun.org:
  - me@myhome.domain.net
  - mr.user@work.company.com
</pre>
</ul>
<p>All the comments about the email format from the section above apply to the
Mailgun handling, as the data is processed the same way</p>

<a name="todo_rich_message_format"> </a>
<h2>Rich Todo Message Format</h2>
<p> For both of the above methods, the follow format can be used:</p>
<pre>my awesome todo @context ~project &lt;131012 &gt;131009 #tag1 #tag2 *</pre>
<p>The fields are:</p>
<table>
  <tr>
    <th>Symbol</th><th>Meaning</th>
  </tr>
  <tr>
    <td>@</td><td>The context to place the Todo in</td>
  </tr>
  <tr>
    <td>~</td><td>The project to place the Todo in</td>
  </tr>
  <tr>
    <td>&lt;</td><td>The due date for the Todo (may be 2 digits for day, 4 digits for month-day, or 6 digits for yeah-month-day)</td>
  </tr>
  <tr>
    <td>&gt;</td><td>The due date for the Todo (may be 2 digits for day, 4 digits for month-day, or 6 digits for yeah-month-day)</td>
  </tr>
  <tr>
    <td>#</td><td>A tag to apply to the Todo - may be used multiple times</td>
  </tr>
  <tr>
    <td>*</td><td>Flag to star the Todo</td>
  </tr>
</table>
<p>All symbols are optional, and text up to the first symbol (or end of string) is used as the description of the todo</p>

<a name="google_gadget"> </a>
<h2>Add Tracks as a Google Gmail gadget</h2>
<p>
  You can now manage your projects/actions inside Gmail using Tracks Gmail Gadget.
  Add Tracks Gmail gadget to the sidebar of Gmail and track your next actions
  or add new action without explicitly open new browser tab for Tracks. Steps to set it up:
</p>
<ul>
  <li>Sign in to Gmail and click Settings in the top right of your Gmail page. In Gmail setting page, click Labs tab</li>
  <li>Enable the "Add any gadget by URL" feature. You will find it at bottom of the list. Select Enable radio button and click Save Changes button.</li>
  <li>Now you can see Gadgets tab added to Gmail Settings. Go to the Gadgets tab</li>
  <li>Paste following link to the Add a gadget by its URL: and then click Add button:<br/>
    <pre><%= integrations_url + "/google_gadget" %></pre></li>
</ul>