Kayako REST API Client

Kayako Resolve is a comprehensive helpdesk and ticket management solution. It exposes REST API which can be used for example to create new tickets from external systems. To facilitate the use of this API I created a client written in PHP.

Prerequisities

PHP

Client requires PHP >= 5.3.0 (beacause late static binding is used) with enabled support for: libXML, cURL, hash, fileinfo and date/time.

Kayako

This version of the client is designed for Kayako version 4.01.240.

Examples

Example is also provided with source in example.php file.

Initialising the client.

require_once("kyIncludes.php");

//client initialization
kyBase::init("http://mykayako.example.com/api/index.php", "<API key>", "<Secret key>");

Setting defaults for ticket creation

This step is optional. If the client will be used to create tickets it’s recommended to set default status, priority and type of new tickets:

$default_status_id = 1;
$default_priority_id = 1;
$default_type_id = 1;
kyTicket::setDefaults($default_status_id, $default_priority_id, $default_type_id);

IMPORTANT
Status, priority and type identifiers may be different in your installation.

In order to discover right identifiers fetch and examine all objects to choose the proper ones:

print kyTicketStatus::getAll();
print kyTicketPriority::getAll();
print kyTicketType::getAll();

You can also use filtering to find status, priority and type by its title:

$default_status_id = kyTicketStatus::getAll()->filterByTitle("Open")->first()->getId();
$default_priority_id = kyTicketPriority::getAll()->filterByTitle("Normal")->first()->getId();
$default_type_id = kyTicketType::getAll()->filterByTitle("Issue")->first()->getId();

Preparing objects

Loading department

To create a ticket you will have to load a proper department providing its identifier. To find out the identifier fetch all departments and find the proper one:

print kyDeparment::getAll();

You can also use filtering to find department by its title:

$department_id = kyDepartment::getAll()->filterByTitle("General")->first()->getId();

IMPORTANT
Department should be Public and its module should be set to Tickets.

We will assume that our department has identifier = 1. Let’s fetch the object:

$department_id = 1;
$department = kyDepartment::get($department_id);

Loading ticket creator

Also you need the creator of ticket. It can be ordinary user or staff user. Let’s assume that we want to create ticket as ordinary user. So to find out the user identifier fetch all users and find the proper one:

print kyUser::getAll();

You can also use filtering to find user by email:

$user_id = kyUser::getAll()->filterByEmail("someuser@example.com")->first()->getId();

IMPORTANT
User must have the right to create tickets in department loaded in previous step.

We will assume that our user has identifier = 1. Let’s fetch the object:

$user_id = 1;
$user = kyUser::get($user_id);

Loading ticket owner

Optionally you can assign the ticket to some staff user.

var_dump(kyStaff::getAll());

We will assume that our staff user has identifier = 1. Let’s fetch the object:

$staff_id = 1;
$staff = kyStaff::get($staff_id);

Creating a ticket.

Now we are ready to create a ticket.

$new_ticket = $user->newTicket($department,
'Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Aliquam placerat cursus augue sed adipiscing. Proin viverra egestas nulla et sollicitudin.',
	'Lorem ipsum 1')->create();

The ticket should be created. The $new_ticket object holds all the information about newly created ticket. You can for example get its display identifer so you can present it to the user.

print "The ticket was created and its ID is: ".$new_ticket->getDisplayId();

Usually that’s everything what will be needed in casual cases, when you simply want to create a ticket. But we can do some more…

Changing the ticket

Assigning staff user

Let’s assign new ticket to the staff user loaded previously.

$new_ticket->setOwnerStaff($staff)->update();

Adding a ticket post (as staff).

The owner of ticket (staff user assigned) apparently doesn’t understand the rubbish we’ve sent in ticket contents so let’s ask politely for clarification;) We are adding new ticket post as ticket owner.

$new_ticket_post = $new_ticket->newPost($new_ticket->getOwnerStaff(), 'What??')->create();

Adding a ticket post with attachments (as user).

Let’s create some new post as user and attach some file to it.

IMPORTANT
Change the path of file to the existing one.

//add new post
$new_ticket_post = $new_ticket->newPost($new_ticket->getUser(), 'Sorry, I forgot the attachment...')->create();

//add attachment to the post
$new_ticket_attachment = $new_ticket_post->newAttachmentFromFile('/path/to/file.pdf')->create();

Recording the time spent

We can add a track of time spent on processing the ticket.

$new_ticket->newTimeTrack("Worked hard on this", $staff, "1:30", "00:45")->create();

Changing the ticket status

Assume we want to change the status of newly created ticket.

$new_ticket->setStatusId(2)->update();

Searching for tickets.

If you want to search for tickets you can do it two ways.

Search using getAll.

Basic search using parameters of kyTicket::getAll method.

$tickets = kyTicket::getAll(array(1), array(1, 2), array(1), array(1));

Search using query

Search using query over multiple areas.
Belowe we are searching for tickets that have “Lorem ipsum” in contents of any post or note.

$tickets = kyTicket::search("Lorem ipsum", array(kyTicket::SEARCH_CONTENTS, kyTicket::SEARCH_NOTES));

See kyTicket::SEARCH_ constants for possible search areas.

Client-side filtering, sorting and paging results.

The library supports client-side filtering, sorting and paging of results.

To print available filter methods for User objects:

print_r(kyUser::getAvailableFilterMethods());

To print available order methods for Staff objects:

print_r(kyStaff::getAvailableOrderMethods());

To find the user with email someuser@example.com:

$user = kyUser::getAll()->filterByEmail("someuser@example.com")->first();

To find ticket time tracks with billable time greater than 10 minutes and sort them ascending using time worked:

$time_tracks = $new_ticket->getTimeTracks()->filterByTimeBillable(array(">", 10 * 60))->orderByTimeWorked();

To find department with title “General”:

$general_department = kyDepartment::getAll()->filterByTitle("General")->first();

To find and print list of tickets in “General” department with word “help” in subject:

print kyTicket::getAll($general_department->getId())->filterBySubject(array("~", "help"));

To get second page from list of staff users ordered by fullname, assuming 10 items per page:

$staff_page_2 = kyStaff::getAll()->orderByFullName()->getPage(2, 10);

How to contribute

If you want to contribute an enhancement or a fix:

1. Fork the project on github.
2. Make your changes (please try to preserve used coding conventions and code formatting).
3. Test your changes.
4. Commit the changes without making changes to files that aren’t related to your enhancement or fix.
5. Send a pull request.

(Un)license

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

For more information, please refer to <http://unlicense.org/>