Home → API Manual → Request Push API → Request Push Implementation Guide

2.2. Request Push Implementation Guide

Implementing the Request Push API requires 4 steps.

1. Copy the /custom_code/RequestPush-base.php file to a new name
2. Rename class
3. Write the code for the push method of the PHP class
4. Write the code for the details method of the PHP class (optional)

Creating the Push File

HelpSpot determines the available request push destinations by the files and names of the files in the /custom_code directory in HelpSpot. To create a new push destination you must first copy the /custom_code/RequestPush-base.php file to /custom_code/RequestPush-YOURNAME.php (where YOURNAME is the name of your destination). The name should only contain letters, numbers, underscores and dashes. No spaces.

Valid file name: RequestPush-Mantis.php

Invalid name: RequestPush-Mantis Bug Tracker.php

Rename the Class

Once the new push file is created, open in a text editor. Near the top of the file you'll see a line that looks as follows:

class RequestPush_base{

You should rename the class and replace 'base' with the name you used in the file. So from the above example our class should now look like this:

class RequestPush_Mantis{

Be sure capitalization, dashes and/or underscores are consistent.

Writing the Push Method

The class has 2 methods. The first is the push method, this is the method that accepts the request information and processes it. Processing can be anything required by the system you're integrate with. Normally this will be an API call, a database insert, sending an email, or even a combination of actions.

There's a few important items to cover before you can write your push code:

Request Data Format

The request data is passed into the push method as an associative array. The array contains these keys:

Array(
    [xRequest] => 12400
    [fOpenedVia] => 7
    [xOpenedViaId] => 0
    [xPersonOpenedBy] => 0
    [xPersonAssignedTo] => 1
    [fOpen] => 1
    [xStatus] => 1
    [fUrgent] => 1
    [xCategory] => 4
    [dtGMTOpened] => 1183214861
    [dtGMTClosed] => 0
    [iLastReplyBy] => 1
    [iLastReadCount] => 21
    [fTrash] => 0
    [dtGMTTrashed] => 0
    [sRequestPassword] => "hckzke"
    [sTitle] => ""
    [sUserId] => ""
    [sFirstName] => "Bob"
    [sLastName] => "Jones"
    [sEmail] => "bobjones@gmail.com"
    [sPhone] => ""
    [sRequestHash] => 9582c31acbac5f8556df01f84817cf4c
    [Custom##] => ""
    [fullname] => "Bob Jones"
    [staff_comment] => ""
    [assigned_person_fname] => "Tom"
    [assigned_person_lname] => "Landers"
    [assigned_person_email] => "tlanders@company.com"
    [acting_person_xperson] => 7
    [acting_person_fusertype] => 1
    [acting_person_fname] => "Tina"
    [acting_person_lname] => "Jones"
    [acting_person_email] => "tjones@company.com"
    [request_history] => Array(
            [236] => Array(
                    [xRequestHistory] => 236
                    [xRequest] => 12403
                    [xPerson] => 1
                    [dtGMTChange] => 1184021870
                    [fPublic] => 0
                    [fInitial] => 0
                    [fNoteIsHTML] => 0
                    [fMergedFromRequest] => 0
                    [tLog] => ""
                    [tNote] => "Request history note"
                    [tEmailHeaders] => ""
                    [file] => Array(
                         [0] => Array(
                             [sFileMimeType] => image/jpeg
                             [sFilename] => icon.jpg
                             [xDocumentId] => 59
                             [public_url] => http://www.site.com/index.php?...
                             [private_url] => http://www.site.com/admin.php?...
                            )
                      )
                )
        )
)

You can read about each field on the API field definition page.

Return Unique ID

After you've pushed the request to your other system you may optionally return a unique ID. If you do return a unique ID, HelpSpot will retain this ID to allow staff to retrieve updates about this push. It's important that the ID be unique, it will be the only parameter passed to the "details" method of the Request Push class you're implementing. You'll need to use that ID to retrieve the update information.

The returned ID may contain any characters and be up to 255 characters long. You return the ID by adding a return statement to the push method as shown below:

function push($request){
    /* Perform actions with request data here */
    
    return "UNIQUE ID";
}

Error Handling

Error messaging in the classes $errorMsg property must be set to address situations when a push cannot be completed. If set, HelpSpot will detect this and display the error to the staff member attempting the push. Errors are not logged at this time.

function push($request){
    //Something has gone wrong
    $this->errorMsg = "Couldn't connect to database";
}

Writing the Details Method

If you opt to return unique ID's in the push method, you should also implement the details method so those ID's return information about a push.

The details method is passed only one argument, the unique ID of a previous Request Push. The details method should use that ID to query the system being pushed to and find out whatever information there is about the status of the pushed request. You can then format those details into HTML and return the HTML. Here's a short example:

function details($id){
    /* Go get details using ID here */
    
    //Format details into HTML
    $html = '<b>'.$status.'</b>';
    
    return $html;
}

Note in this very simple example we're returning a status code in bold. You could do much more with this. For instance you could build out a full HTML table to display the details. Also note, you don't have to build the HTML within the details method. You can have an external script which builds the HTML. In the details method you simply call that script with the ID and return the completed HTML.

Knowledge Tags

Request Push  /  API  /