Using script filters in Alfred Workflows

Workflows in Alfred are really incredible productivity tools. They let you basically build any automation you can think of and can be triggered in a range of ways. In this post I’m going to show you how I’m using script filters in Alfred workflows.

The end game

Below is a quick video showing you the workflow in action. After starting the Alfred bar, I type “wfx” to trigger the workflow, which is an abbreviation for WorkflowMax. WorkflowMax is the system we use at 3DN for job and billing management. That’s not really that important except that it has a RESTful API and it returns XML documents which you can parse out to obtain information about customers and the jobs for those customers.

Couple of things to notice about the workflow:

• It’s triggered by the term “wfx”
• After typing the trigger it’s expecting a customer name to be typed, in this example I typed “3dn”
• As you type is starts firing the script to talk to the workflowmax API doing a customer search and it shows the matched customer names
• After using the arrow keys to select a customer (only one in the list in this example) and pressing enter it then fires another call to the API to find all projects for that customer
• After selecting the project from the list it then opens a browser window and navigates to the selected project

Setting up the workflow

Here’s the workflow configured and finished in Alfred.

[caption id=”attachment_377" align=”aligncenter” width=”1024"]

The finished workflow in Alfred[/caption]

You’ll notice that there’s actually three trigger points in the workflow:

1. The main trigger that fires when you type “wfx” as shown in the video above
2. A trigger to update the API key for workflowmax
3. A trigger to update the access for for workflowmax

The latter of these two workflows are specifically designed to update the credentials required to use the workflowmax API. The credentials consist of two different values, an API key and an access key, both of which are stored in a plist file. This simply means that the credentials aren’t hardcoded into the main script, but rather obtained from the plist file as needed.

The script filter

I decided to use ruby to do this integration mainly because it’s not something I’m familiar with and wanted to learn, and there seems to be hundreds of resources and modules available for use and learning.

Firstly you’ll need to install a few gems to use this workflow:

• plist — makes it easy to read and write information into the plist file for saving the credentials and getting them out later
• alfred-3_workflow — this module allows you to easily take a list from one datasource and format it so that Alfred can display it a workflow list
• rest-client — the library used to call the RESTful api and manage the response
• nokogiri — this is a great xml library that allows you quickly parse an xml document or iterate through a list of nodes in an xml document.

The workflowmax API returns xml rather than JSON formatted data, hence the need for the xml library. Installing these modules is pretty easy. Open a terminal window and execute the following commands, some will only take a few seconds, others will install a range of dependancies.

sudo gem install plist
sudo gem install alfred-3_workflow
sudo gem install rest-client
sudo gem install nokogiri

[learn_more caption=”Side note on using gem”] I just found a really useful tool built into the the gem package manager. If you type “gem server” from a terminal window it starts up a web server on your local system that allows you to see all the packages installed and get links and description to the source and documentation. You can open a browser and navigate to http://localhost:8808 to see the results.[/learn_more]

The script filter consists of the following key components:

The script

query = "{query}"
require "plist"
require 'alfred-3_workflow'
require 'rest-client'
require 'nokogiri'
file_name = "keys.plist"
keys = Plist::parse_xml(file_name)
apikey = keys["apikey"]
accountkey = keys["accountkey"]
workflow = Alfred3::Workflow.new
response = RestClient.get 'https://api.workflowmax.com/client.api/search?apiKey=' + apikey + '&accountKey=' + accountkey + '&query=' + query
doc = Nokogiri::XML(response)
customers = doc.xpath("/Response/Clients/Client")
customers.each do |x|
        id = x.xpath("ID").text
    name = x.xpath("Name").text
workflow.result
    .uid(id)
    .title(name)
    .type('default')
    .arg(id)
    .valid(true)
end
print workflow.output
A breakdown of what's going on here:

• Line 1 sets the variable query to the value of the customer name passed in on the Alfred bar. We use this variable later on in the script to search the API.
• Lines 3 through 6 import the required packages that will be used later in the script.
• Line 8 sets the name of the plist file to the variable file_name.
• Line 10 instantiates an instance of the Plist library by calling the parse_xml creator passing in the file_name. It then stores the values from the plist file into a hash table called keys
• Lines 12 and 13 set the variables apikey and accountkey to their appropriate values from the hash table.
• Line 15 instantiates an instance of the Alfred3 workflow object
• Line 17 actually makes the call to the web service substituting the apikey and accountkey in addition to adding the query that was typed in the Alfred bar
• Line 19 instantiates an instance of the nokogiri xml object using the value returned from the call to the web service which in this case is an xml document.
• Line 21 creates an array from the xml document that contains all of the nodes found at the xpath address “/Response/Clients/Client”
• Line 23 through 33 loop through each of the clients returned from the service
• Line 24 & 25 store the ID and Name of the client into variables
• Lines 27 through 32 add an item to the output to be displayed on the Alfred bar
• Line 35 outputs the collected items from the loop into the JSON format that Alfred expects, with the help of the Alfred3-workflow library

Putting it all together

Create a new workflow as normal in Alfred, right click in the workspace and add a Script Filter Input.  You can then copy/paste the above into the script window.  Make sure to choose Ruby from the language list.
[caption id="attachment_382" align="aligncenter" width="1024"]

Screenshot of Alfred workflow configuration for Script Filter[/caption]
The exported package is available for you to download here.