Chuck Grimmett

Today I released my first personal project on Github: Toggl Slash Command for Slack.

It is a custom slash command that enables users to put time entries into Toggl from Slack.

I like to learn by giving myself projects. I treat them as if I were releasing them to the public, even if I’m going to move on after I’ve learned what I want to learn. This is one of those projects. I created a roadmap of features that I probably won’t ever implement, but I learned a ton getting what I have so far to work, so I’m calling this a win.

What I learned

• How to read from and write to an API
• How to structure complex if/then statements to parse input text
• Dealing with arrays in PHP
• Deeper regex processing
• Unicode conversions
• Releasing code to a public repo on Github
• Designing security measures for a system deployed on the web
• How to structure and design a codebase from scratch
• How to work within the bounds of the different systems you are working in and finding ways around barriers
• Implementing command line options
• Using other projects in your own project via dependency managers like Composer
• Writing documentation

Features

• Show a list of projects and their corresponding IDs in a given workspace
• Show a list of tasks associated with a given project
• Add time entries to Toggl straight from Slack’s message input box

Screenshots

Setup & Installation

Dependencies

• You must have PHP 5.3.2+ installed locally and on an accessible server.
• You need Composer installed locally to install the third-party dependencies.

Two third-party libraries are dependencies included via Composer:

• guzzle-toggl by arendjantetteroo
• GetOptionKit by c9s

Local Installation

• Clone or download this repository onto your local machine
• Install Composer in this repository if you don’t already have it
• Open a command line terminal and navigate to this directory.
• Run: php composer.phar install via the command line to install the third-party dependencies

Configure the variables file.

1. Copy the variables-dist.php file to variables.php
2. Fill out the Slack token you got while setting up the slash command.
3. Fill out users’ Slack usernames with their corresponding Toggl API keys in the array. They can get those keys at the bottom of https://toggl.com/app/profile.
4. Enter a workspace ID for your team. to find yours, log in to Toggl, then go to https://www.toggl.com/api/v8/workspaces. Pick the ID of the workspace you want to use. Don’t wrap it in quotes; it needs to be an integer.
5. Set your team’s default timezone. Right now it is set to america/new_york.
6. Save the file as variables.php in the same directory and you are good to go!

Upload to a server with a valid SSL certificate

1. Once the dependencies are installed, upload the whole directory to a server running PHP 5.3.2+
2. Ensure you have a valid SSL certificate. Slash command URLs must support HTTPS and serve a valid SSL certificate. Self-signed certificates are not allowed. Check out CloudFlare for an easy way to obtain a valid certificate.

Configure a custom slash command on Slack

1. Log in to your Slack account and navigate to Custom Integration to set up a custom slash command.
2. Click Add Configuration.
3. Choose the command you want (I use /toggl).
4. Fill out the path to the slash_parsing.php file on your server from above.
5. Set the method to be POST.
6. Copy the token and save it for variables.php below.
7. Set a fun name and icon. I use Toggl’s logo from their media kit.

Usage

• /toggl help - Shows the syntax below
• /toggl about - Shows info about this slash command and directs people to this repository
• /toggl show projects - Shows the list of projects associated with API key of the user the workspace ID set in variables.php
• /toggl show tasks [project ID] - Shows a list of tasks associates with a given project ID.
  • Example: /toggl show tasks 10692310
• /toggl add -p [project ID] -d "description" -t [duration in hh:mm:ss] - Adds a time entry to Toggl. Don’t include the [ ].
  • Example: add -d "Weekly check-in" -p 10692310 -t 00:15:00
  • Additional options:
    • --date [mm/dd/yy] - Adds the time entry to a specific date. If none is passed, it defaults to today’s date.
    • --task [task id] - Adds the time entry to a task ID. See above to find your task ID for a project.

Logging

• I added basic logging to CSV for usage stats and debugging. This happens individually per project, stored in log.csv. Nothing is transmitted back to me.
• If you’d prefer to not log usage, simply comment out lines 14-19 in slash_parsing.php.
• Since the log includes a Slack token, you’ll want to deny access to log.csv on your webserver. I achieved that via my .htaccess file.