Heap JavaScript API

The JavaScript Add-On API for Heap CRM allows any developer to add features, functionality and integration into Heap CRM.

An Add-On involves four different types of files:

  1. One XML manifest
  2. One HTML file that sets up the initial display
  3. Zero or more CSS files
  4. Zero or more JavaScript files

The XML Manifest

Here is a sample manifest file:


<?xml version="1.0"?>

While in most cases you will have your JavaScript and CSS files on the same server as your HTML content, the only requirement is that each is a valid URL (relative paths are not allowed). You can have as many CSS and JavaScript files as you want; you must have only one HTML file.

From the general user’s perspective your XML manifest “is” your program. It’s the URL they provide to Heap when they install the Add-On.

The HTML File

The HTML file sets up the basic structure within the “api” divs within Heap (the white content area). You should not, therefore, include a header, body or other wrapper tags.

What you can do in the HTML section is entirely up to you. However, to avoid confusion, you should only use names, ids and classes that start with “api_”. This is a reserved space within Heap and will guarantee that there is no conflicts now or in the future.

The JavaScript Files

The JavaScript files are all included in the header. The only other files included are related to the JS API (discussed in the next section). There is no frameworks installed, so if your code is dependent on prototype or dojo you must include it in the XML manifest.

When doing an AJAX call: Because of security reasons, browsers don’t allow you to directly access files from a different domain. Instead you must use the following function.

YData_GetURL(url, Callback Function) 

YData_GetURL will use the content type sent by your server to either provide it as plain text or XML to the callback function. Please note, YData_GetURL will timeout after 10 seconds.

JavaScript API Calls - Persistent Storage

To save something for later use (either in the same session or at a later date or even from a different user) you need persistent storage. The Heap API provides four functions for this purpose:

HData_PutData(key, value, Callback Function)
HData_PutUserData(key, value, Callback Function)
HData_GetData(key, Callback Function)
HData_GetUserData(key, Callback Function)

The “key” is a case-insensitive string (up to 254 characters long). When you wish to save data you “Put” it. If successful, your callback function will be sent a “true” otherwise it will receive “false.” If you “Put” a key that already exists, the existing data will be overwritten by the data you supplied.

When you are retrieving data you “Get” it. If successful your callback function will receive the data (otherwise it will receive an empty string).

The difference between the “User” data and the standard functions is scope. HData_PutData and HData_GetData apply to the entire sub-domain (i.e. the data can be set by one user and retrieved by another). HData_PutUserData and HData_GetUserData apply only to the logged in user.

JavaScript API Calls - Interacting with Heap Data: Searching

When you wish to receive a list of items your “List” them. These four functions will provide a a multidimensional array where each row is a result and within each row there is an associative array with a “key” and a “title” (provided to the callback function).

HData_ListMessages('Search Term', Callback Function)
HData_ListPeople('Search Term', Callback Function)
HData_ListEvents('Search Term', Callback Function)
HData_ListLOCA('Search Term', Callback Function)

You can do exactly the same advanced searches here as you can within Heap. For information on operators, bucket selectors and more, please refer to http://heap.wbpsystems.com/find.php.

JavaScript API Calls - Interacting with Heap Data: Getting a Record

Once you have found the record you wish to inspect you can use the “key” to retrieve it.

HData_GetMessage(key, Callback Function)
HData_GetPerson(key, Callback Function)
HData_GetEvent(key, Callback Function)
HData_GetLOCA(key, Callback Function)

The callback function will receive an associative array with key names appropriate to each record (you can use Firebug to dump an array, which is very helpful when developing).

JavaScript API Calls - Interacting with Heap Data: Creating a Record

When you want to create a record, you use the following functions:

HData_CreateMessage(Associative Array, Callback Function)
HData_CreatePerson(Associative Array, Callback Function)
HData_CreateEvent(Associative Array, Callback Function)
HData_CreateLOCA(Associative Array, Callback Function)

These functions are the exact inverse of the HData_Get* functions. The array you provide the HData_Create* function should have identical keys to the one provided to you by HData_Get*.

JavaScript API Calls - Interacting with Heap Data: Updating a Record

The following functions are used to update a record:

HData_UpdateMessage(key, Associative Array, Callback Function)
HData_UpdatePerson(key, Associative Array, Callback Function)
HData_UpdateEvent(key, Associative Array, Callback Function)
HData_UpdateLOCA(key, Associative Array, Callback Function)

These functions are identical to HData_Create*, except you must also provide the key of the record you wish to update.

JavaScript API Calls - Interacting with Heap Data: Deleting a Record

The following functions are used to delete a record:

HData_DeleteMessage(key, Callback Function)
HData_DeletePerson(key, Callback Function)
HData_DeleteEvent(key, Callback Function)
HData_DeleteLOCA(key, Callback Function)

JavaScript API Calls - Interacting with Heap Data: Other Functions

HData_ListMessageCategories(Callback Function)
HData_ListPeopleCategories(Callback Function)
HData_ListCalendars(Callback Function)

Special Note:

In some of these functions you are interacting with dates and times. Whenever you send or receive a date and time you must provide/receive it as an integer. Please note, JavaScript specifies times in terms of microseconds (instead of the more traditional seconds). To get the current time as an integer, you can use the “getTime” method on a “Date” object.