angphc
28-03-2015 19:25:40
Background:[UPDATE]
Now API Examples includes attachments example
NOTICE: WHEN USING ATTACHMENTS via API you may need to change your php settings to higher execution times
I think API is one of the most underrated and most useful features of the system.
Even when documentation is clear and simple on how to use this awesome feature I want to help another people to make it easier to make use of it. Since it seems that many people doesn't use it. (In the whole forum is mentioned only once) JSON and CURL php extensions are recquired for this mini-how-to We're taking advantage of php JSON extension to easily create JSON strings from arrays. Each level in the array will create a JSON object within the JSON object that API will be able to understand If the email is not registered in Maian Support it'll create a new account before creating the ticket.
Let's go straight to the stuff[list=1]
[*]Copy and paste the code in the bottom of this post to a new php file[/*]
[*]Modify what is recquired in the code's comments [/*]
[*]Place this php file in your web server and open it in your browser[/*]
[*]Log in to your Maian Support control panel. Now you should be able to see a new Ticket Created[/*]
[*]Replace the hardcoded values in the array with your $_POST data references[/*]
[*]Make your web form to send values to this file via POST[/*]
[*]Enjoy![/*]
[/list] Tips and tricks:[list=*]
[*]Validate all your data in your form managing before submitting it to MaianSupport API. It would be easier to troubleshoot later and you may not even need to add code to manage errors here.[/*]
[*]While developing and testing your API interactions enable (and clear often) internal log files (you may not even need to look to your server's logs[/*]
[*]Make liberal use of break points and comments all around your code while debugging (I personally prefer ye olde var_dump and die() functions)[/*]
[*]Notice that if you want some formatted text in your tickets (In coments section obviously) You may send data already formatted using BBcode. To know which BBcode tags are available read Maian Support documentation.[/*]
[*]DO NOT use html tags in your comments section. HTML will not be parsed. HTML tags will be shown literally[/*]
[*]Make sure all your files are encoded using UTF-8 without BOM if not some weird errors may appear that are very difficult to track down[/*]
[*]If you're using your own method to generate JSON data you can have a great help to troubleshoot your data structure with this awesome tool http://codebeautify.org/jsonviewer . It doesn't only beautify your json data to make it more human readable. It can also help you to validate it[/*]
[/list]
<?php
/*********************************************
Create new ticket and account if does not exist using API and JSON
ASSUMPTIONS FOR THIS TUTORIAL
1.-Let's assume your Maian Support is installed in www.yourdomain.com/helpdesk. Change this script accordingly
2.- You have a Department which ID is 01. **READ API DOCUMENTATION ABOUT WHAT DATA YOU MUST PUT IN THERE**
3.- Your server supports CURL
4.- You have generated a valid API key in Maian Support settings
5.- You have enabled API access on your Maian Support Control Panel
6.- You are going to put a valid email address in EMAIL field below so you can check the functionality
**********************************************/
#replace www.yourdomain.com with your real domain.
$url="http://www.yourdomain.com/helpdesk/index.php?api=yes";
#Replace your_api_key with your real API. Check your api settings
$api_key="your_api_key";
#Setup the values that the ticket will receive
##example data assuming your Form is instructed to POST results to this file.
/*
$Incoming_Data = $_POST
$params['name'] = $Incoming_Data['$YOUR_FORM_NAME_FIELD_VALUE'];
$params['email'] = $Incoming_Data['$YOUR_FORM_EMAIL_FIELD_VALUE'];
$params['dept'] = $Incoming_Data['$YOUR_FORM_DEPT_FIELD_VALUE']; //THIS CAN BE HARDCODED BUT MUST BE A VALID VALUE FOR THE API
$params['subject'] = $Incoming_Data['$YOUR_FORM_SUBJECT_FIELD_VALUE'];//THIS CAN BE HARDCODED BUT MUST BE A VALID VALUE FOR THE API
$params['comments'] = $Incoming_Data['$YOUR_FORM_COMMENTS_FIELD_VALUE'];
$params['priority'] = $Incoming_Data['$YOUR_FORM_PRIORITY_FIELD_VALUE'];//THIS CAN BE HARDCODED BUT MUST BE A VALID VALUE FOR THE API
$params['Cust_Field1'] = $Incoming_Data['$YOUR_FORM_**_FIELD_VALUE'];//NOT MANDATORY CAN BE EMPTY OR NOT DECLARED AND TICKET WILL BE CREATED
$params['Cust_Field2'] = $Incoming_Data['$YOUR_FORM_**_FIELD_VALUE'];//NOT MANDATORY CAN BE EMPTY OR NOT DECLARED AND TICKET WILL BE CREATED
$params['attachment1'] = $Incoming_Data['$YOUR_FORM_ATTACHMENT1']; // NOT MANDATORY, MUST BE BASE-64 ENCODED
$params['attachment2'] = $Incoming_Data['$YOUR_FORM_ATTACHMENT2']; // NOT MANDATORY, MUST BE BASE-64 ENCODED
*/
## Hard Coded Values For instructive purposes.
# Mandatory fields
$params['name'] = 'Joe Bloggs';
$params['email'] = 'guest@somesite.com';//CHANGE FOR A VALID *REAL* EMAIL ADDRESS
$params['dept'] = '01'; //MUST BE A VALID DEPARTMENT ID FOR YOUR MAIAN SUPPORT INSTALLATION
$params['subject'] = 'Hello; can you help please?';
$params['comments'] = 'Lorem ipsum dolor sit amet consectetuer tristique leo lacinia orci lorem. Id tempor vitae et congue Nulla vitae gravida ac ipsum odio. Laoreet a euismod et Nunc laoreet Lorem et pellentesque cursus augue. Nec ipsum leo facilisis Morbi wisi Cras dictumst quis diam Cum. Porta Nam Nunc fames nunc sed.';
$params['priority'] = 'high';//MUST BE A VALID PRIORITY ID FOR YOUR MAIAN SUPPORT INSTALLATION
# Optional Fields
$params['Cust_Field1'] = 'Custom field ID 1 data';
$params['Cust_Field2'] = 'Custom field ID 2 data';
#Attachments
$params['file1']['data'] = base64_encode("This file is an uploaded attachment using the Maian Support API");
$params['file1']['ext'] = "txt";
$params['file2']['data'] ="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";
$params['file2']['ext']= "png";
#Let's Prepare the data for JSON encoding.
#Each level on the array will generate a json object within the json object
#READ API USAGE DOCUMENTATION to understand this.
#*DO NOT CHANGE ANYTHING IN ARRAY KEYS* (EVERYTHING BEFORE THE => )
#Array keys are case sensitive for the API to parse the ticket correctly
#*DO NOT CHANGE* case in api keys.
#**********************DO NOT MODIFY ANYTHING BELOW UNTIL NEW NOTICE ****************************
$ticket_array= array
(
"api" => $api_key,
"op" => "ticket",
"tickets"=> array
(
"ticket" => array
(
"name" => $params['name'],
"email" => $params['email'],
"dept" => $params['dept'],
"subject" => $params['subject'],
"comments" => $params['comments'],
"priority" => $params['priority'],
"customfields" => array
(
"f1" => $params['Cust_Field1'],
"f2" => $params['Cust_Field2']
),
"attachments" => array
(
"file" => array
(
array
(
"ext" => $params['file1']['ext'],
"data" => $params['file1']['data']
),
array
(
"ext" => $params['file2']['ext'],
"data" => $params['file2']['data']
)
)
)
)
)
);
#pre-checks. CURLS and JSON extensions which are recquired for this example to work
function_exists('curl_version') or die('CURL support required');
function_exists('json_encode') or die('JSON support required');
#Very important to json_encode the array
#since Maian Support API receives only JSON or XML
#In this tutorial we're using JSON
$ticket_string=json_encode($ticket_array);
#set timeout
set_time_limit(30);
#CURL's Magic
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $ticket_string);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, FALSE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
$result=curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$res = json_decode($result,true);
#**********************THE FOLLOWING CODE MUST BE MODIFIED TO PROCESS ERRORS ACCORDINGLY ****************************
#Manage the results from here
/*some code to manage
your results */
/* DEBUG ONLY REMOVE FOR PRODUCTION */
echo "This is the result of API call \n<pre>";
print_r($res);
echo "</pre>\n\n";
echo "If there was an error check your API debug log. Stablish actions according to results";
/**/
#We're done, verify your control panel and you will see a new ticket created via API
?>
|