-
-
03 Sep 2018 18:11:55 UTC
- Distribution: Net-Zendesk
- Module version: 0.02
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Repository
- Issues (1)
- Testers (697 / 0 / 0)
- Kwalitee
Bus factor: 1- 55.80% Coverage
- License: perl_5
- Activity
24 month- Tools
- Download (6.58KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
++ed by:1 non-PAUSE user- Dependencies
- Furl
- IO::Socket::SSL
- JSON::MaybeXS
- MIME::Base64
- Test::More
- URI::Escape
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
NAME
Net::Zendesk - Thin and lightweight interface for Zendesk's API
SYNOPSIS
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 );
DESCRIPTION
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.API ACTIVATION
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.
CONSTRUCTION
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 - eithertoken => 'yourtoken'
orpassword => 'yourpassword'
. We recommend creating a token for the user in your Zendesk's API settings.METHODS
create_ticket( \%ticket_data, %extra_options )
$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.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.Finally, you may also set other extra options like
include => 'comment_count'
to include thecomment_count
property in the returned json data.search( \%params )
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' }
.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.
make_request( $type, $path, \%params )
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
.\%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.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! :)
AUTHOR
Breno G. de Oliveira
<garu at cpan.org>
COPYRIGHT AND LICENSE
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.
Module Install Instructions
To install Net::Zendesk, copy and paste the appropriate command in to your terminal.
cpanm Net::Zendesk
perl -MCPAN -e shell install Net::Zendesk
For more information on module installation, please visit the detailed CPAN module installation guide.