forked from extern/django-helpdesk
293 lines
12 KiB
HTML
293 lines
12 KiB
HTML
|
<html>
|
||
|
|
<head>
|
||
|
|
<style type='text/css'>
|
||
|
|
body {
|
||
|
|
background-color: #fff;
|
||
|
|
color: #333;
|
||
|
|
font: 10pt "Trebuchet MS", Arial, sans-serif;
|
||
|
|
}
|
||
|
|
|
||
|
|
h1 {
|
||
|
|
color: #00c;
|
||
|
|
}
|
||
|
|
|
||
|
|
h1, h2, h3, h4 {
|
||
|
|
font-family: Garamond, Times, serif;
|
||
|
|
}
|
||
|
|
|
||
|
|
h2 {
|
||
|
|
color: #c00;
|
||
|
|
}
|
||
|
|
</style>
|
||
|
|
<title>Jutda Helpdesk API Documentation</title>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<h1>Jutda Helpdesk API Documentation</h1>
|
||
|
|
|
||
|
|
<h2>Contents</h2>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><a href='#introduction'>Introduction</a></li>
|
||
|
|
<li><a href='#request'>Request Basics & Authentication</a></li>
|
||
|
|
<li><a href='#response'>Responses</a></li>
|
||
|
|
<li><a href='#methods'>Method Documentation</a>
|
||
|
|
<ul>
|
||
|
|
<li><a href='#method_create_ticket'>create_ticket</a></li>
|
||
|
|
<li><a href='#method_delete_ticket'>delete_ticket</a></li>
|
||
|
|
<li><a href='#method_hold_ticket'>hold_ticket</a></li>
|
||
|
|
<li><a href='#method_unhold_ticket'>unhold_ticket</a></li>
|
||
|
|
<li><a href='#method_add_followup'>add_followup</a></li>
|
||
|
|
<li><a href='#method_resolve'>resolve</a></li>
|
||
|
|
<li><a href='#method_list_queues'>list_queues</a></li>
|
||
|
|
<li><a href='#method_find_user'>find_user</a></li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h2 name='introduction'>Introduction</h2>
|
||
|
|
|
||
|
|
<p>Jutda Helpdesk provides a powerful <acronym title='Application Programming Interface'>API</acroynm> to allow you to interact with your helpdesk tickets by a means not otherwise provided by the helpdesk.</p>
|
||
|
|
|
||
|
|
<p>For example, you may use this API to implement a system to automatically open a ticket when an invoice is raised in your invoicing system, or to automatically close a ticket from an instant messenger application.</p>
|
||
|
|
|
||
|
|
<p>Your use of this system is open-ended: most business cases should be addressible with a little bit of coding to allow you to interact nicely with your helpdesk.</p>
|
||
|
|
|
||
|
|
<h2 name='request'>Request Basics & Authentication</h2>
|
||
|
|
|
||
|
|
<p>All requests to the API must be made using <acroynm title='HyperText Transfer Protocol'>HTTP</acronym> POST requests. Any request that is not made using POST will raise an error.</p>
|
||
|
|
|
||
|
|
<p>Your requests must be made up of the following elements:</p>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>A <em>method</em>, or action. This tells the API what core functionality to execute.</li>
|
||
|
|
<li>A <em>username</em> and <em>password</em> which are valid and active within your helpdesk system. You may wish to create a specific API user just for API usage.</li>
|
||
|
|
<li>A set of <em>data</em> to be saved into the database. This data will vary from request to request, and is outlined in <a href='#methods'>Methods</a> below.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<p>To build your request, send a HTTP POST request to <em>{% url helpdesk_api "method" %}</em>, where <em>method</em> is the name of a <a href='#methods'>valid method</a> from the list below.</p>
|
||
|
|
|
||
|
|
<p>Your POST must include both <em>user</em> and <em>password</em> parameters.</p>
|
||
|
|
|
||
|
|
<p>A sample request for the method <em>hold_ticket</em> may look like this:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>A HTTP POST to <em>{% url helpdesk_api "hold_ticket" %}</em></li>
|
||
|
|
<li>A set of POST data containing:<ul>
|
||
|
|
<li>username=susan</li>
|
||
|
|
<li>password=fido</li>
|
||
|
|
<li>ticket=31794</li>
|
||
|
|
</ul></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>To complete this from a command-line using the <a href='http://curl.haxx.se/'>cURL</a> application, you may use a command such as this:</p>
|
||
|
|
|
||
|
|
<pre>/usr/bin/curl {% url helpdesk_api "hold_ticket" %} --data "user=susan&password=fido&ticket=31794"</pre>
|
||
|
|
|
||
|
|
<p>In <a href='http://www.php.net/'>PHP</a>, providing you have access to the <a href='http://www.php.net/curl'>cURL libraries</a>, you may use code such as this:</p>
|
||
|
|
|
||
|
|
<pre><?php
|
||
|
|
$api = curl_init();
|
||
|
|
curl_setopt($api, CURLOPT_URL, "{% url helpdesk_api "hold_ticket" %}");
|
||
|
|
curl_setopt($api, CURLOPT_POST, 1);
|
||
|
|
curl_setopt($api, CURLOPT_POSTFIELDS, "user=susan&password=fido&ticket=31794");
|
||
|
|
$result = curl_exec($api);
|
||
|
|
curl_close($api);
|
||
|
|
echo $result;
|
||
|
|
?<</pre>
|
||
|
|
|
||
|
|
<p>Note that cURL expects all data to be urlencoded, this is left as an exercise for the reader.</p>
|
||
|
|
|
||
|
|
<h2 name='#response'>Responses</h2>
|
||
|
|
|
||
|
|
<p>The API system makes proper use of the following HTTP response codes:</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt>200</dt>
|
||
|
|
<dd>OK - Data updated successfully</dd>
|
||
|
|
|
||
|
|
<dt>400</dt>
|
||
|
|
<dd>ERROR - Generic error. See returned text for details</dd>
|
||
|
|
|
||
|
|
<dt>404</dt>
|
||
|
|
<dd>ERROR - Data not found (eg, incorrect ticket). See returned text for details</dd>
|
||
|
|
|
||
|
|
<dt>403</dt>
|
||
|
|
<dd>ERROR - Invalid permissions (eg, incorrect username and/or password)</dd>
|
||
|
|
|
||
|
|
<dt>405</dt>
|
||
|
|
<dd>ERROR - Invalid method. You probably tried using GET, PUT or DELETE however we require POST.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>Responses will have one of two content-types:</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt>text/plain</dt>
|
||
|
|
<dd>Any error messages, or simple responses (eg a ticket ID)</dd>
|
||
|
|
|
||
|
|
<dt>text/json</dt>
|
||
|
|
<dd>Any complex responses, such as a list of data.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<h2 name='methods'>Method Documentation</h2>
|
||
|
|
|
||
|
|
<p>The following public methods are available for use via the API. Each of them requires <a href='#request'>a valid request and authentication</a>, and each has it's own parameters as described below.</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><a href='#method_create_ticket'>create_ticket</a></li>
|
||
|
|
<li><a href='#method_delete_ticket'>delete_ticket</a></li>
|
||
|
|
<li><a href='#method_hold_ticket'>hold_ticket</a></li>
|
||
|
|
<li><a href='#method_unhold_ticket'>unhold_ticket</a></li>
|
||
|
|
<li><a href='#method_add_followup'>add_followup</a></li>
|
||
|
|
<li><a href='#method_resolve'>resolve</a></li>
|
||
|
|
<li><a href='#method_list_queues'>list_queues</a></li>
|
||
|
|
<li><a href='#method_find_user'>find_user</a></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3 name='method_create_ticket'>create_ticket</h3>
|
||
|
|
|
||
|
|
<p>This method creates a new helpdesk ticket.</p>
|
||
|
|
|
||
|
|
<h4>Parameters</h4>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt>queue</dt>
|
||
|
|
<dd>Queue ID (use <a href='#method_list_queues'>list_queues</a> to get queue ID's) - this is an integer field.</dd>
|
||
|
|
|
||
|
|
<dt>title</dt>
|
||
|
|
<dd>Title or header of this ticket. Character field, maximum 100 characters.</dd>
|
||
|
|
|
||
|
|
<dt>submitter_email</dt>
|
||
|
|
<dd>(Optional) e-mail address of the person submitting this ticket. This e-mail address will receive copies of all public updates to this ticket, and will receive a notification when the ticket is created.</dd>
|
||
|
|
|
||
|
|
<dt>assigned_to</dt>
|
||
|
|
<dd>(Optional) Integer ID of the user to which this ticket should be assigned. Use <a href='#method_find_user'>find_user</a> to find a user ID from a username.</dd>
|
||
|
|
|
||
|
|
<dt>priority</dt>
|
||
|
|
<dd>(Optional) Priority as an integer from 1 (high) to 5 (low). Defaults to 3 if no priority given.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<h4>Response</h4>
|
||
|
|
|
||
|
|
<p>This method responds with <strong>plain-text</strong>.</p>
|
||
|
|
|
||
|
|
<p>If you receive a 200 OK <a href='#response'>response</a>, then the content of the response will be the ticket ID.</p>
|
||
|
|
|
||
|
|
<h3 name='method_delete_ticket'>delete_ticket</h3>
|
||
|
|
|
||
|
|
<p>When given a ticket ID and confirmation, this method will delete a ticket entirely. This also deletes any followups, attachments, and other details.</p>
|
||
|
|
|
||
|
|
<h4>Parameters</h4>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt>ticket</dt>
|
||
|
|
<dd>The numeric ticket ID to be deleted</dd>
|
||
|
|
|
||
|
|
<dt>confirm</dt>
|
||
|
|
<dd>You must provide this field, with any value, to enable deletion to continue</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<h4>Response</h4>
|
||
|
|
|
||
|
|
<p>A standard <a href='#response'>200 OK response</a> is given on success, or an error message on failure.</p>
|
||
|
|
|
||
|
|
<h3 name='method_hold_ticket'>hold_ticket</h3>
|
||
|
|
|
||
|
|
<p>If a ticket needs to be placed on hold, preventing it from being escalated, use this method.</p>
|
||
|
|
|
||
|
|
<h4>Parameters</h4>
|
||
|
|
<dl>
|
||
|
|
<dt>ticket</dt>
|
||
|
|
<dd>The numeric ticket ID to be placed on hold</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<h4>Response</h4>
|
||
|
|
|
||
|
|
<p>A standard <a href='#response'>200 OK response</a> is given on success, or an error message on failure.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h3 name='method_unhold_ticket'>unhold_ticket</h3>
|
||
|
|
|
||
|
|
<p>If a ticket is currently on hold and you wish to remove that hold, use this method.</p>
|
||
|
|
|
||
|
|
<h4>Parameters</h4>
|
||
|
|
<dl>
|
||
|
|
<dt>ticket</dt>
|
||
|
|
<dd>The numeric ticket ID to be taken off hold</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<h4>Response</h4>
|
||
|
|
|
||
|
|
<p>A standard <a href='#response'>200 OK response</a> is given on success, or an error message on failure.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h3 name='method_add_followup'>add_followup</h3>
|
||
|
|
|
||
|
|
<p>This method adds a comment / followup to a ticket. The followup can be public, in which case it is e-mailed to the submitter, or private. The followup will also be sent to others involved in the ticket: The owner and the queue notification / CC address.</p>
|
||
|
|
|
||
|
|
<h4>Parameters</h4>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt>ticket</dt>
|
||
|
|
<dd>The numeric ticket ID to which this followup should be added</dd>
|
||
|
|
|
||
|
|
<dt>message</dt>
|
||
|
|
<dd>Text of 'unlimited' length - optionally formatted with HTML - to add to the message.</dd>
|
||
|
|
|
||
|
|
<dt>public</dt>
|
||
|
|
<dd>Either 'y' for public, or 'n' for private. This is optional, and it is assumed that followups are private if it is not provided. Private tickets are <strong>not</strong> e-mailed to the ticket submitter.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<h4>Response</h4>
|
||
|
|
|
||
|
|
<p>A standard <a href='#response'>200 OK response</a> is given on success, or an error message on failure.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h3 name='method_resolve'>resolve</h3>
|
||
|
|
|
||
|
|
<p>This method adds a resolution to a ticket and marks it as resolved. The resolution will be e-mailed to everybody involved with the ticket, including the submitter.</p>
|
||
|
|
|
||
|
|
<h4>Parameters</h4>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt>ticket</dt>
|
||
|
|
<dd>The numeric ticket ID to which this followup should be added</dd>
|
||
|
|
|
||
|
|
<dt>resolution</dt>
|
||
|
|
<dd>Text of 'unlimited' length - optionally formatted with HTML. This is the resolution for this ticket.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<h4>Response</h4>
|
||
|
|
|
||
|
|
<p>A standard <a href='#response'>200 OK response</a> is given on success, or an error message on failure.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h3 name='method_list_queues'>list_queues</h3>
|
||
|
|
|
||
|
|
<p>This method provides a JSON-parsable list of queues, letting you access the individual queue ID in order to create tickets.</p>
|
||
|
|
|
||
|
|
<h4>Response</h4>
|
||
|
|
|
||
|
|
<p>This method responds with <strong>json</strong>.</p>
|
||
|
|
|
||
|
|
<p>It provides a list of queues in JSON format. The fields provided are ID and Title.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h3 name='method_find_user'>find_user</h3>
|
||
|
|
|
||
|
|
<p>When given a username, this method provides the related numeric user ID - commonly used when creating or reassigning tickets.</p>
|
||
|
|
|
||
|
|
<h4>Parameters</h4>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt>username</dt>
|
||
|
|
<dd>The case-sensitive username of the user for which you require the user ID</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<h4>Response</h4>
|
||
|
|
|
||
|
|
<p>This method responds with <strong>plain-text</strong>.</p>
|
||
|
|
|
||
|
|
<p>If you receive a 200 OK <a href='#response'>response</a>, then the content of the response will be the users ID.</p>
|
||
|
|
</body>
|
||
|
|
</html>
|