Features Developers Twitter Support Pricing / Sign up Login

Create a Custom Help Desk Form - Tutorial

In this tutorial you will create a form and post to your Zavanda account

Your Situation

If you have just created a new Zavanda account and you can now start creating support or help desk tickets. Without the use of an API you must manually create each ticket.

The Solution

By implementing an API, as a Zavanda customer you can easily create your own custom help desk form on your website. Please note, that this tutorial is using a PHP / Mysql implementation, but you can easily create the same form with .NET, Java, Perl, Python or Ruby.

Getting Started

The first thing you'll need of course is to create a Zavanda account. Once you have your account created, you'll need to obtain your Token API. You can retrieve your token by clicking on Account Settings where you will need to enable the API option. Once you save your settings, you can then Copy and Paste the Token into your code (See code below).

Note: You must be logged in as the Account Owner in order to retreive your API Token.

API Client Library

I have created a small php library that will allow you to program your code as simple as possible. You can download a copy of the entire tutorial code here. I am using SimpleXML extension in this tutorial which states in the documentation that it requires PHP v5 at least. The server I'm using is PHP v5 and greater so I'm not sure if you can get it working with PHP v4.

Creating the HTML Form

The form itself is the heart and soul of your help desk application. Being an agile developer, we'll start creating our form strictly using HTML (index.php)

			

				
			

			
Personal information
	    

	      Full name:
	      
	    
	    

	      Email address:
	      
	    
			
			
			

			
Support information
	    

	      Type of Support:
	      [dynamically driven data - select dropdown]
	    
	    

	      Priority:
				
					Severe
					High
					Medium
					Low
				
	    
	    

	      Reason for Support:
	      
	    
	    

	      Specific Details:
	      <textarea name="issue_notes" id="issue_notes" type="text" rows="5" cols="30" /></textarea>
	    
			
	
			

	     
	    
			
			
			
		

The important work will be done by the file post_new_ticket.php which is the action link for your form. Also note, that the form must be an HTTP POST method. An HTTP GET method will not work! It may also be important to note that you typically will never want to display your API Token as a hidden form field. It's better to submit that into an array in your action file. We'll talk more about that later. I have also stripped out the

tags to save space. But it's assumed you will be okay to add them yourself. The entire file contents are also available in the source download file.

It may also be important to note that this form only contains the absolute minimum neccessary fields that the Zavanda API expects when POSTING your data. You are by all means welcome to create additional fields for your specific needs.

You may also note that on line 19, there will be a data driven dropdown. This will be explained in detail below.

API Library Base Class

Let's begin by looking at the Base Class file ZBase.php

class ZBase
{
	/*@ protected */
	var $api = '';
	
	/*@ public */
	var $curl_enabled = TRUE;
	
	function ZBase($api = NULL)
	{
		$this->api = $api;
		
		// Verify if cURL exists or not 
		$this->curl_enabled = function_exists('curl_init') && function_exists('curl_setopt');
	}
	
	/**
	 * Posts a new ticket to the Zavanda system
	 *
	 * @param string $url In case future editions of the api is a separate URL path
	 * @param array $post_data  
	 * @return mixed An HTTP Response or FALSE
	 */
	function post_ticket($url = NULL, $post_data = NULL)
	{
		// Preferred Method using cURL
		if($this->curl_enabled) {
			
			// Send the POST request (with cURL)
			$c = curl_init($url);
			
			curl_setopt($c, CURLOPT_POST, true);
			curl_setopt($c, CURLOPT_POSTFIELDS, $post_data);
			
			curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
			$result = curl_exec($c);
			$status = curl_getinfo($c, CURLINFO_HTTP_CODE);
			curl_close($c);
			
			return $status; // HEADERS
			
		} else 
		{
			return FALSE;
		}
	}
	
	/**
	 * Returns an XML Object of Ticket Types (id, name)
	 *
	 * Note: This function may require PHP V.5.0 > because of the simplexml_load_string variable.
	 * @param string $url Zavanda url string
	 * @return xml Object 
	 */
	function get_ticket_types($url = NULL)
	{
		// Append the url with the key
		$ticket_type_url = $url.$this->api;
		
		$c = curl_init($ticket_type_url);
		curl_setopt($c, CURLOPT_RETURNTRANSFER, 1);
		$response = curl_exec($c);
		curl_close($c);
		$xml = simplexml_load_string($response);
		
		return $xml;
	}
}
		

One of the first things to note, is the use of PHP's built in cURL function calls. Secondly, it is worth mentioning that during this writing, the API only allows for 2 API calls: 1) Post a New Ticket and 2) Retrieve Ticket Support Group Types. More functionality will be added in future releases.
Note, I managed to come across this tutorial HTTP Request without CURL here in case it's needed for some of you.

The Work Horse Files

Before we can really start programming, we need to setup our api_config.php file:

define('ZAVANDA_API_KEY', 'hereisyoursecretcut&pastedkey');
define('ZAVANDA_GROUPS_URL', 'http://app.zavanda.com/api/group/read_ticket_types.php?key=');
define('ZAVANDA_ADD_TICKET_URL', 'http://app.zavanda.com/api/ticket/add.php');
		

After you copied your API Token, you need to paste it into line 1 ZAVANDA_API_KEY constant. Both lines 2 and 3 do not need to be altered as these are the URL's that Zavanda is expecting you to POST your data to.

We now need to go back and edit our index.php file from above. At this point, the file only contains the HTML. We need to start adding the php code at the very top of the file:

require_once('api_config.php');
require_once('ZBase.php');

// The ticket types web service url (from config file)
$url = ZAVANDA_GROUPS_URL;
// Create a new ZBase Object
$zavanda = new ZBase(ZAVANDA_API_KEY);

// Get the ticket types for your account
$xml = $zavanda->get_ticket_types($url);
		

We only added several lines here, but all 5 are required in order for the code to work. The above code does several things, a) it calls our constant variables and most importantly, our API Key. b) The code includes the ZBase.php file that created earlier in order to create our Base object, and lastly, we retried all of our ticket support groups. Because of the simplicity of the Base class, all that work was done for you in 5 simple lines of code.

If you remember in the above HTML form, there was a line that stated, "[dynamically driven data - select dropdown]". Below is the code that we are going to use to create that dropdown select option.

// We're going to assign the entire xml records into a
// <select> html tag for the view
$xml_select = '' ;
foreach($xml->type as $type) 
{
	$xml_select .= ''.$type->name.'' ;
}
$xml_select .= '' ;
		

Then all you need to edit in your index.php form (lines 17 - 20) is the following:

    

      Type of Support:
      <?php echo $xml_select; ?>
    
		

Looking closely at the index.php file, you will notice that the form does a POST directly to post_new_ticket.php file. Let's take a look at that file below:

require_once('api_config.php');
require_once('ZBase.php');

if(array_key_exists('_submit',$_POST)) 
{

	// Let's do some very simple data validation
	if( empty($_POST['subject']) || 
			empty($_POST['issue_notes']) ||
			empty($_POST['full_name']) ||
			empty($_POST['email'])) {
		header('location: /index.php?error=Invalid');   // Note: this is not production quality
		exit();
	}

	// --- DEBUG ONLY ----
	// print_r($_POST);exit();

	// Prepare POST data for cURL
	$post_data = http_build_query(
	    array(
	        'api_key'    		=> ZAVANDA_API_KEY,
	        'subject'	  		=> $_POST['subject'],
	        'issue_notes'   	=> $_POST['issue_notes'],
	        'activity_type'		=> $_POST['activity_type'],
	        'priority'			=> $_POST['priority'],
	        'name'				=> $_POST['full_name'],
	        'email'				=> $_POST['email']
	    )
	);
	
	$zavanda = new ZBase(ZAVANDA_API_KEY);
	$response = $zavanda->post_ticket(ZAVANDA_ADD_TICKET_URL, $post_data);
	
	// Check cURL Returned Value
	if ($response == 200) 
	{
		header('location: /index.php?action=success');  		// Note: this is not production quality
		exit();
	} else if ($response == 403) 
	{
		header('location: /index.php?action=invalidkey');   // Note: this is not production quality
		exit();
	} else 
	{
		header('location: /index.php?action=dataerror');    // Note: this is not production quality
		exit();
	}
}
		

It should be stated that most of this code is not meant for production, and only for demonstration purposes. In the above code, it's important to pay strict attention to the $post_data array on lines 20 - 30. The Zavanda API expects your array to be named exactly like so. For instance, in your form, you could have called the ticket subject, "title" but you must call the array key "subject" and the same goes for "issue_notes" and so on and so on.

Response Codes

It is also important to check the value the $response code returned from the API:

• 200 - Successful Post was completed!
• 403 - Invalid API Key was detected
• Anything else - Your Key was Valid, but there was a Data Error.