NAME

Net::ThirtySevenSignals::Highrise - Perl extension for talking 37Signals' Highrise API

SYNOPSIS

use Net::ThirtySevenSignals::Highrise;

my $hr = Net::ThirtySevenSignals::Highrise(
                       user  => $your_highrise_url_prefix,
                       token => $your_highrise_api_token,
                       ssl   => $use_ssl);

# Fill out a Perl data structure with information about
my $people = $hr->list_all_people;

# return a hashref of people
my $people = $hr->people_list_by_criteria(email => 'danny@example.com');

DESCRIPTION

Net::ThirtySevenSignals::Highrise provides a thin Perl wrapper around the Highrise API (http://developer.37signals.com/highrise/). Currently it only implements a very few API points.

The API is unstable at this time.

Getting Started

In order to use the Highrise API, you'll need to have a Highrise API token. And in order to get one of those, you'll need a Highrise account. But then again, the API will be pretty useless to you if you don't have a Highrise account to manipulate with it.

You can get a Highrise account from http://highrisehq.com.

Highrise API

The Highrise API is based on XML over HTTP. You send an XML message over HTTP to the Highrise server and the server sends a response to you which is also in XML. The format of the various XML requests and responses are defined at http://developer.37signals.com/highrise/

This module removes the need to deal with any XML. You create an object to talk to the Highrise server and call methods on that object to manipulate your data. The values returned from Highrise are converted to Perl data structures before being handed back to you (although it is also possible to get back the raw XML).

XML

To get the XML back from the API, you can pass the parameter forcearray => 0 to the new function.

METHODS

$hr = Net::ThirtySevenSignals::Highrise->new(token => $token, user => $user, [forcearray => 0], ssl => 0);

Creates a new Net::ThirtySevenSignals::Highrise object. All communication with the Highrise server is made through this object.

Takes two mandatory arguments, your Highrise API token and your Highrise username. Returns the new Net:Highrise object.

There is also an optional parameter, forcearray. This controls the value of the ForceArray parameter that is used by XML::Simple. The default value is 1.

If the ssl parameter is provided, then communication will take place over SSL. This is required for Plus and Premium accounts.

$pages = $hr->people_list_all([xml => 1]);

Get a list of all of your Highrise people. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$people = $hr->people_list_by_criteria([xml => 1], city => 'Oakland',country=>'US'...);

Returns a collection of people that match the criteria passed in. Available criteria are:

city state country zip phone email

Returns an arrayref or undef unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$tags = $hr->tags_list_all([xml => 1]);

Get a list of all of your Highrise tags. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$tags = $hr->tags_list_for_subject([xml => 1]);

Get a list of all of your Highrise tags. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$pages = $hr->person_get(id=> 123455, [xml => 1]);

Get a list of all of your Highrise people. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

returns a $person hashref or die()s if the person does not exist;

$pages = $hr->person_create( [xml => 1]);

Create a person unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server. Pass in parameters with keys: firstName lastName companyName emailAddress emailAddress

$pages = $hr->tag_add( $subject, $subjectType, $tagName );

add a tag to an item. $subject should be a perl structure returned from one of person_get, company_get etc. $subjectType should be one of people

$pages = $hr->person_destroy();

Destroy a person. either returns undef or die()s.

Pass in parameters with keys: id => the personid to be destroyed

$page = $hr->create_page(title => $title, [description => $desc, xml => 1]);

Create a new Highrise page with the given title and (optional) description. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$url = $hr->person_url($personHash);

Create an URL pointing at a person page.

TO DO

Improve documentation (I know, it's shameful)
More tests

AUTHOR

Danny Sadinoff <danny@sadinoff.com>

derived directly from Dave Cross's Net::Backpack

Please feel free to email me to tell me how you are using the module.

BUGS

the API is incomplete, to say the least.

Please report bugs by email to danny@sadinoff.com

LICENSE AND COPYRIGHT

This script is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Modifies the location in the list of a Highrise checklist item. Requires a page id, a direction and an item id. Valid values for direction are "move_lower", "move_higher", "move_to_top", and "move_to_bottom". Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$notes = $hr->list_all_notes(page_id => $page_id, [xml => 1]);

Get a list of all of your Highrise notes. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$note = $hr->create_note(page_id => $page_id, title => $title, body => $body, [xml => 1]);

Create a Highrise note given a page id and some content. Title is required, body is optional. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$note = $hr->update_note(page_id => $page_id, id => $note_id, [xml => 1] title => $title, body => $body);

Updates a Highrise note given a page id, note id, and new content. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$response = $hr->destroy_note(page_id => $page_id, id => $note_id, [xml => 1]);

Destroys a Highrise note given a page id and an note id. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$pages = $hr->get_tag_pages(page_id => $id, [ xml => 1 ]);

Retrieve all the pages associated with a particular tag id. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$response = $hr->set_page_tags(page_id => $id, tags => \@tags, [ xml => 1 ]);

Set the tags for a given Highrise page. This method overwrites all tags for the page. An empty set of tags serves to remove all the tags for the page. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

This is currently returning true, and though it seems to create and submit a valid request, the tags are not being updated.

$reminders = $hr->upcoming_reminders([ xml => 1 ]);

Gets the upcoming Highrise reminders for an account, in the time zone specified per the account's settings. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$reminder = $hr->create_reminder(content => $reminder, [xml => 1], [remind_at => $remind_at]);

Create a Highrise reminder given some reminder content. The content takes fuzzy date/times like "+30 Do foo and bar" to set the reminder for 30 minutes from now. Optionally, specify a date in a relatively parseable date format and use the remind_at parameter instead. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$reminder = $hr->update_reminder(id => $reminder_id, [content => $reminder], [xml => 1], [remind_at => $remind_at);

Update a Highrise reminder given a reminder id. The content takes fuzzy date/times like "+30 Do foo and bar" to set the reminder for 30 minutes from now. Optionally, specify a date in a relatively parseable date format and use the remind_at parameter instead. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$response = $hr->destroy_reminder( id => $reminder_id, [xml => 1]);

Destroys a Highrise reminder given a reminder id. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$emails = $hr->list_all_emails(page_id => $page_id, [xml => 1]);

Get a list of all of your Highrise email items for a page. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$email = $hr->show_email(page_id => $page_id, id => $reminder_id, [xml => 1]);

Returns a Highrise email item given a page id and an email id. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$response = $hr->destroy_email(page_id => $page_id, id => $reminder_id, [xml => 1]);

Destroys a Highrise email item for a page given a page id and an email id. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$exported_bp = $hr->export([xml => 1]);

Exports an account's entire Highrise. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$lists = $hr->list_all_lists(page_id => $page_id, [xml => 1]);

Get a list of *all* of your Highrise checklists for a specific page. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$list = $hr->list_this_list(page_id => $page_id, list_id => $list_id, [xml => 1]);

Get details of a specific list with the given list_id on a specific Highrise page with the given page_id. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$list = $hr->create_list(page_id => $page_id, title => $title, [xml => 1]);

Create a new Highrise checklist given a page id and a list title. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$list = $hr->update_list(page_id => $page_id, list_id => $list_id, title => $title, [xml => 1]);

Update the title of a specific list with the given list_id on a specific Highrise page with the given page_id. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$list = $hr->destroy_list(page_id => $page_id, list_id => $list_id, [xml => 1]);

Destroy a specific list with the given list_id on a specific Highrise page with the given page_id. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

$list = $hr->create_list_item(page_id => $page_id, list_id => $list_id, item = $item, [xml => 1]);

Create an item on a specific list with the given list_id on a specific Highrise page with the given page_id. This differs from the usual "create_item" function in that you can specify which list on a page you want to add the item to. Returns a Perl data structure unless the xml parameter is true, in which case it returns the raw XML as returned by the Highrise server.

To install Net::ThirtySevenSignals::Highrise, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::ThirtySevenSignals::Highrise

CPAN shell

perl -MCPAN -e shell
install Net::ThirtySevenSignals::Highrise

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Getting Started

Highrise API

XML

METHODS

$hr = Net::ThirtySevenSignals::Highrise->new(token => $token, user => $user, [forcearray => 0], ssl => 0);

$pages = $hr->people_list_all([xml => 1]);

$people = $hr->people_list_by_criteria([xml => 1], city => 'Oakland',country=>'US'...);

$tags = $hr->tags_list_all([xml => 1]);

$tags = $hr->tags_list_for_subject([xml => 1]);

$pages = $hr->person_get(id=> 123455, [xml => 1]);

$pages = $hr->person_create( [xml => 1]);

$pages = $hr->tag_add( $subject, $subjectType, $tagName );

$pages = $hr->person_destroy();

$page = $hr->create_page(title => $title, [description => $desc, xml => 1]);

$url = $hr->person_url($personHash);

TO DO

AUTHOR

BUGS

LICENSE AND COPYRIGHT

SEE ALSO

$rc = $hr->show_page(id => $id, [xml => 1]);

$rc = $hr->destroy_page(id => $id, [xml => 1]);

$rc = $hr->update_title(id => $id, title => $title, [xml => 1]);

$rc = $hr->update_body(id => $id, description => $desc, [xml => 1]);

$page = $hr->duplicate_page(id => $id, [xml => 1]);

$rc = $hr->link_page(link_page => $id1, to_page => $id2, [xml => 1]);

$rc = $hr->unlink_page(link_page => $id1, from_page => $id2, [xml => 1]);

$rc = $hr->share_page(id => $id, people => \@people, [ xml => 1 ]);

$rc = $hr->make_page_public(id => $id, public => $public, [ xml => 1 ]);

$rc = $hr->unshare_friend_page(id => $id, [ xml => 1 ]);

$rc = $hr->email_page(id => $id, [ xml => 1 ]);

$items = $hr->list_all_items(page_id => $page_id, [xml => 1]);

$item = $hr->create_item(page_id => $page_id, item => $item, [xml => 1]);

$item = $hr->update_item(page_id => $page_id, item => $item, [xml => 1] id => $item_id);

$response = $hr->toggle_item(page_id => $page_id, id => $item_id, [xml => 1]);

$response = $hr->destroy_item(page_id => $page_id, id => $item_id, [xml => 1]);

$response = $hr->move_item(page_id => $page_id, id => $item_id, direction => $direction, [xml => 1]);