mirror of
https://github.com/django-helpdesk/django-helpdesk.git
synced 2024-12-13 10:21:05 +01:00
a162d77d70
( see /help/context/; also linked from comment form)
* Refactor API help page to share template with context help
* Allow a limited number of Ticket & Queue model fields to be
accessible in comments, as per 'Help' page.
* New function in lib.py to build a dict of 'safe' fields from
ticket & queue, to prevent the power of the Django model API
from exposing things like passwords (imagine if a user typed
a comment containing {{ ticket.queue.email_box_password }} !!!!
* When accessing the ticket list with no filter params (eg by
clicking on the "Tickets" button in the menu), the default
search is for tickets that aren't closed, rather than showing
all tickets.
* Updated English locale with changed message strings.
272 lines
12 KiB
HTML
272 lines
12 KiB
HTML
{% extends "helpdesk/help_base.html" %}
|
|
|
|
{% block title %}Jutda Helpdesk API Documentation{% endblock %}
|
|
{% block heading %}Jutda Helpdesk API Documentation{% endblock %}
|
|
|
|
{% block content %}
|
|
<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 id='introduction'>Introduction</h2>
|
|
|
|
<p>Jutda Helpdesk provides a powerful <acronym title='Application Programming Interface'>API</acronym> 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 id='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 id='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 id='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 id='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 id='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 id='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 id='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 id='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 id='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 id='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 id='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>
|
|
{% endblock %}
|