Net::Zendesk - Thin and lightweight interface for Zendesk's API
use Net::Zendesk; my $zen = Net::Zendesk->new( domain => 'obscura.zendesk.com', email => 'yourvaliduser@example.com', token => 'your_valid_zendesk_api_token', ); $zen->create_ticket( { requester => { name => 'The Customer', email => 'thecustomer@example.com', }, subject => 'My printer is on fire!', comment => { body => 'The smoke is very colorful.' }, }, async => 'true', ); my $result = $zen->search({ status => 'open', priority => { '>=' => 'normal' }, created => { '>' => '2017-01-23', '<' => '2017-03-01' }, subject => 'photo*', assignee => undef, -tags => 'invoice', }); use JSON::Maybe::XS; my $data = decode_json( $result->decoded_content );
This module provides a very simple 1:1 interface to Zendesk's REST API.
While it currently provides very few methods (patches welcome!) it comes with a make_request method that hopefully will let you do pretty much anything you want with the API.
make_request
To use Zendesk's API, you must of course have a valid zendesk account, and activate the API via your account's "Admin" settings. Once you do that, you may chose between 'token' or 'password' authentication. Oauth is not currently supported by Net::Zendesk.
my $zen = Net::Zendesk->new( domain => 'obscura.zendesk.com', email => 'yourvaliduser@example.com', token => 'your_valid_zendesk_api_token', );
To instantiate Net::Zendesk objects You must specify your zendesk domain name. This is usually somename.zendesk.com. You must also specify the email you use to connect to the account that is going to use the API and the authentication method - either token => 'yourtoken' or password => 'yourpassword'. We recommend creating a token for the user in your Zendesk's API settings.
somename.zendesk.com
token => 'yourtoken'
password => 'yourpassword'
$zen->create_ticket( { requester => { name => 'The Customer', email => 'thecustomer@example.com', }, subject => 'My printer is on fire!', comment => { body => 'The smoke is very colorful.' }, }, async => 'true', );
Use this method to create a single ticket. The example above includes all required fields. Please refer to Zendesk's documentation for a comprehensive list of all accepted fields.
DO NOT PASS the ticket root argument, just its contents, like in the provided example above.
ticket
If you provide the extra option async => 'true', Zendesk's API will give the response back quickly and queue a background job to do the actual work. This might be an important speedup because ticket creation sometimes takes a while.
async => 'true'
Finally, you may also set other extra options like include => 'comment_count' to include the comment_count property in the returned json data.
include => 'comment_count'
comment_count
my $result = $zen->search({ type => 'ticket', status => ['new', 'open'], priority => { '>=' => 'normal' }, created => { '>' => '2017-01-23', '<' => '2017-03-01' }, subject => 'photo*', assignee => undef, -tags => 'invoice', sort => 'asc', order_by => 'ticket_type', });
Use this method to search for tickets, users and organizations. Zendesk's search queries have their own unique syntax, so hopefully this method will provide a good enough abstraction that you won't have to learn it :)
The example above illustrates all possible keyword manipulations. Let's get into more detail:
filter by equality:
status => 'open' status => { '=' => 'open' } # same thing status => ['new', 'open'], # new OR open status => { '=' => ['open', 'new'] } # same status => { 'or' => ['open', 'new'] } # same tags => { 'and' => ['foo', 'bar'] } # foo AND bar
filter by inequality:
priority => { '>' => 'normal' } created => { '>=' => '2017-01-01', '<' => DateTime->today->ymd }
Note: when searching by date and time, use YYYY-MM-DD or ISO8601 syntax (YYYY-MM-DDThh:mm:ss+hh:mm). You can also specify times relative to the present moment using hours, minutes, days, weeks, months or years, e.g. created { '>' => '4hours' }.
YYYY-MM-DD
YYYY-MM-DDThh:mm:ss+hh:mm
created { '>' => '4hours' }
filter by properties that contain no data:
assignee => undef assignee => 'none' # same
filter by wildcard:
subject => 'photo*' # photo, photograph, photography, etc.
Note: not all fields are searcheable with wildcards. Please refer to Zendesk's reference documentation for the updated list of fields.
excluding items:
-tags => 'invoice' tags => { '!=' => 'invoice' } # same
Just prepend the keyword with "-".
-
sorting and ordering:
order_by => 'created' sort => 'desc' # 'asc' or 'desc'
At the time of this writing you could sort ONLY by created, commented, priority, status and ticket_type. Please refer to Zendesk's documentation for the updated list.
If you need to make a request that is not covered by a method above, you may use this one. It takes 3 arguments:
$type - either 'GET', 'POST', 'PUT' or 'DELETE'.
$path - the ENDING of the route to access. For example: tickets/create_many.json instead of /api/v2/tickets/create_many.json.
tickets/create_many.json
/api/v2/tickets/create_many.json
\%params - hashref containing the complete structure to be converted to JSON and sent with the request.
The response is a regular HTTP::Response which you can check for is_success, decoded_content, etc.
is_success
decoded_content
NOTE: If you think other people might benefit from a named method wrapping your request, please consider providing a patch to this module. Thank you! :)
Breno G. de Oliveira <garu at cpan.org>
<garu at cpan.org>
Copyright 2017 Breno G. de Oliveira <garu at cpan.org>. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
To install Net::Zendesk, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Zendesk
CPAN shell
perl -MCPAN -e shell install Net::Zendesk
For more information on module installation, please visit the detailed CPAN module installation guide.