/ 
Net-Zendesk-0.01
River stage zero No dependents
++
 / Net::Zendesk
Breno G. de Oliveira

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 - either token => 'yourtoken' or password => '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 the comment_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.