HeapCL

Creating Content Extracting Installation and Configuration Video

HeapCL allows you to create messages, people, prospects and email templates from the command line. Why might you want to do this? Because if you have terminal access you can build this into an automation routine where otherwise you might need to hire a programmer.

Create a message

In the terminal where heapCL is installed type (on Windows, or if heapCL is in your path, you would not type the leading "./"):

./heapCL --title "My Title" --body "~/mynewmessage.txt" --files "image.jpg"

What's going on here? The title is explicitly specified as an option, but the body is specified by file; which means the content of "mynewmessage.txt" becomes the content of the message. This is something you can do with any filed in heapCL. Additionally, I've specified a file (in the current directory) I wish to upload.

The body variable will be parsed for advanced e-mail operators as described in this document (it will also be parsed for "[association:Name of Prospect]" despite that not being a normal message operator).

In the terminal where heapCL is installed type (on Windows, or if heapCL is in your path, you would not type the leading "./"):

./heapCL --title "My Title" --body "~/mynewmessage.txt" --simulate

The body variable will be parsed for advanced e-mail operators as described in this document (it will also be parsed for "[association:Name of Prospect]" despite that not being a normal message operator). However, the message will not be created.

Create a person

In the terminal where heapCL is installed type (on Windows, or if heapCL is in your path, you would not type the leading "./"):

./heapCL --name "John Doe" --custom "Birthday=1/1/1950, Source=Brother John" --categories "clients, website" --notes "notes.txt"

Here we are creating a new person named "John Doe". There is a couple of custom variables and categories we are specifying and, like the message example, we are using the fact that heapCL can use files to send a lot more text to the notes field.

Create a prospect

In the terminal where heapCL is installed type (on Windows, or if heapCL is in your path, you would not type the leading "./"):

./heapCL --name "John Doe" --email "john@doe.com" --value "100" --probability ".5" --template "New Lead" --type "lead"

A prospect is created any time you specify a numeric value for probability and value (even if that value is zero). However, once you are creating a prospect more fields are made available to you. For instance, I'm firing an event template on the prospect (obviously not possible on a person).

Create an email template

In the terminal where heapCL is installed type (on Windows, or if heapCL is in your path, you would not type the leading "./"):

./heapCL --subject "Subject Line" --content "My Content"

HeapCL allows you to search prospects and people, retrieve statistics, list history, the pipeline and activity and display email templates.

Search prospects

In the terminal where heapCL is installed type (on Windows, or if heapCL is in your path, you would not type the leading "./"):

./heapCL --search "James category:My Category" --save "results.csv"

So, this uses the same powerful search system you have access to in Heap. That means you can still use the same bucket selectors even though you are doing this from the command line. In addition to the search term I've instructed heapCL to save the results to a file.

Search people

In the terminal where heapCL is installed type (on Windows, or if heapCL is in your path, you would not type the leading "./"):

./heapCL --searchpeople "email:john@doe.com"

Just like the prospect search, this uses the same search system you have access to in Heap. You might have noticed in this case I didn't specify a file to save the results to. This means the results will be sent to the terminal window.

Get history

In the terminal where heapCL is installed type (on Windows, or if heapCL is in your path, you would not type the leading "./"):

./heapCL --history "John Doe" --save "results.csv"

This retrieves the transaction history for the prospect "John Doe" and saves them to a file.

Get statistics

In the terminal where heapCL is installed type (on Windows, or if heapCL is in your path, you would not type the leading "./"):

./heapCL --stats "John Doe" --save "results.csv"

This retrieves the statistics for the prospect "John Doe" and saves them to a file.

List e-mail templates

In the terminal where heapCL is installed type (on Windows, or if heapCL is in your path, you would not type the leading "./"):

./heapCL --list "emailtemplates" --save "emailtemplates.csv"

This retrieves your e-mail templates and saves them to a file. If I type something like:

./heapCL --list "emailtemplates Hello World!" --save "emailtemplates.csv"

I'll only get a CSV containing email templates where the subject like starts with "Hello World!". If I type something like:

./heapCL --list "emailtemplates" --save "emailtemplates.txt"

I'll get a plain text file containing each email template.

List messages

In the terminal where heapCL is installed type (on Windows, or if heapCL is in your path, you would not type the leading "./"):

./heapCL --list "messages" --save "messages.csv"

This retrieves your recent messages and saves them to a file. If I type something like:

./heapCL --list "messages John Doe" --save "messages.csv"

I'll only get a CSV containing messages where the message is associated to John Doe. If I type something like:

./heapCL --list "messages" --save "messages.txt"

I'll get a plain text file containing each message.

List events

In the terminal where heapCL is installed type (on Windows, or if heapCL is in your path, you would not type the leading "./"):

./heapCL--list "events" --save "results.csv"

This retrieves all of the uncompleted events that you own or are associated to a prospect where you are a managing user and saves them to a file. If I type something like:

./heapCL --list "events John Doe" --save "results.csv"

I'll get a CSV containing only items associated to "John Doe". If I type something like:

./heapCL --list "events" --save "results.txt"

I'll get a plain text file with each event specified as a new line, associations specified with a "+" and calendars specified with a "@". This format is commonly used when applying David Allen's Getting Things Done methodology and is compatible with programs like Todo.txt.

List activity and the pipeline

In the terminal where heapCL is installed type (on Windows, or if heapCL is in your path, you would not type the leading "./"):

./heapCL --list "pipeline expected value" --category="Clients" --mylabel="blog software"

This lists the current pipeline that is in the category "clients" and you have labeled "blog software". Activity works similarly:

./heapCL --list "activity value" --label="software" --user="John Doe" --date="1-1-2012" --range="week"

This would list the activity for the week leading up to January one where John Doe is a managing user and the prospects are labeled "sofware".

Displaying results in the terminal

Instead of saving retrieved results to a file, heapCL allows you to display them in the terminal.

./heapCL --list "events"

This information will be in JSON format, which allows you to pipe it to another command line application. However, you can also view it in plain text by adding the option "--text". For instance:

./heapCL --list "events" --text

The "--text" option can be applied to any extraction command:

Searching prospects or people ("--search", "--searchpeople")
Getting history or statistics ("--history", "--stats")
Listing events, messages, activity, the pipeline or e-mail templates ("--list")

Installation

Installing heapCL is pretty easy. Because Macs and Linux already include Python, all you need to do is download the heapCL source, decompress it, and move it wherever you want. Of course, if you use heapCL a lot you might want to add your installation location to your PATH variable.

On Windows, you need to download the heapCL executable. Once you decompress it, you can move the file anywhere you like.

Alternatively, you can install using MacPorts:

sudo port -v selfupdate
sudo port install heapcl

Configuration

HeapCL uses Heap CRM's webhook (found in Heap's help section). So before you can do anything else you will need to specify where you want to send this data.

In the terminal where heapCL is installed type (on Windows, or if heapCL is in your path, you would not type the leading "./"):

./heapCL --webhook "https://creativearc.crmondemand.biz/WEBHOOK"

If you wish to change your webhook in the future, just rerun this command with the new url.

In the terminal where heapCL is installed type (on Windows, or if heapCL is in your path, you would not type the leading "./"):

./heapCL --help

Upgrading

Sense June 2012, HeapCL has been able to detect if it is out-of-date. Just run:

./heapCL --version

If the version is out of date it will attempt to download the new version to your downloads folder (Mac and Linux) or take you to this downloads page (Windows). You can then replace your existing version simply decompressing the download and overwriting your existing copy.

Download Source (OS X and Linux)