view release on metacpan or  search on metacpan

lib/Business/SiteCatalyst.pm  view on Meta::CPAN

package Business::SiteCatalyst;

use strict;
use warnings;

use Data::Dumper;
use Carp;
use LWP::UserAgent qw();
use HTTP::Request qw();
use JSON qw();
use Digest::MD5 qw();
use POSIX qw();
use Digest::SHA1 qw();
use MIME::Base64 qw();

use Business::SiteCatalyst::Company;
use Business::SiteCatalyst::Report;


# Some API methods return strings or numbers rather than valid JSON.
# This list is used to return the raw response to the caller instead of decoding output as JSON
my %METHODS_RETURNING_INVALID_JSON = 
(
	'Company.GetEndpoint'   => 1,  # Returns string
	'Company.GetTokenCount' => 1,  # Returns number
	'Report.CancelReport'   => 1,  # Returns number
);


=head1 NAME

Business::SiteCatalyst - Interface to Adobe Omniture SiteCatalyst's REST API.


=head1 VERSION

Version 1.2.2

=cut

our $VERSION = '1.2.2';


=head1 SYNOPSIS

This module allows you to interact with Adobe (formerly Omniture) SiteCatalyst,
a web analytics service. It encapsulates all the communications with the API 
provided by Adobe SiteCatalyst to offer a Perl interface for managing reports,
pulling company-specific SiteCatalyst data (ex: token usage), uploading SAINT 
data (feature not implemented yet), etc.

Please note that you will need to have purchased the Adobe SiteCatalyst product,
and have web services enabled within your account first in order to obtain a web
services shared secret, as well as agree with the Terms and Conditions for using 
the API.

NOTE: the 'api_subdomain' option/config variable is utilized for the api url.
To determine your specific API URL/Endpoint, please visit
https://developer.omniture.com/en_US/get-started/api-explorer
Most users won't need to set this variable unless the default causes errors.

API URL: 'https://' . $api_subdomain . '.omniture.com/admin/1.3/rest/?'


	use Business::SiteCatalyst;
	
	# Create an object to communicate with Adobe SiteCatalyst
	my $site_catalyst = Business::SiteCatalyst->new(
		username        => 'dummyusername',

lib/Business/SiteCatalyst.pm  view on Meta::CPAN

will allow retrieval of company-specific SiteCatalyst data.

	my $company = $site_catalyst->instantiate_company();

	
Parameters: none

=cut

sub instantiate_company
{
	my ( $self, %args ) = @_;
	
	return Business::SiteCatalyst::Company->new( $self, %args );
}


=head1 INTERNAL METHODS

=head2 send_request()

Internal, formats the JSON call with the arguments provided and checks the
reply.

	my ( $error, $response_data ) = $site_catalyst->send_request(
		method => $method,
		data   => $data,
	);

=cut

sub send_request
{
	my ( $self, %args ) = @_;
	
	my $verbose = $self->verbose();
	my $url = $self->{'webservice_url'} .  $args{'method'};
	
	# Check for mandatory parameters
	foreach my $arg ( qw( method data ) )
	{
		croak "Argument '$arg' is needed to send a request with the Business::SiteCatalyst object"
			if !defined( $args{$arg} ) || ( $args{$arg} eq '' );
	}
	
	my $json_in = JSON::encode_json( $args{'data'} );
	carp "Sending JSON request >" . ( defined( $json_in ) ? $json_in : '' ) . "<"
		if $verbose;
	
	# Authentication information for header.
	my $username = $self->{'username'};
	my $nonce = Digest::MD5::md5_hex( rand() * time() );
	chomp($nonce);
	
	my $created = POSIX::strftime("%Y-%m-%dT%H:%M:%S", gmtime());
	my $password_digest = MIME::Base64::encode_base64(
		Digest::SHA1::sha1_hex( $nonce . $created . $self->{'shared_secret'} ) 
	);
	chomp($password_digest);
	
	my $request = HTTP::Request->new(POST => $url);
	carp "POSTing request to URL >" . ( defined( $url ) ? $url : '' ) . "<"
		if $verbose;
	my $auth_header = qq|UsernameToken Username="$username", PasswordDigest="$password_digest", Nonce="$nonce", Created="$created"|;
	carp "Auth header: >$auth_header<" if $verbose;
	
	$request->header('X-WSSE', $auth_header);
	
	$request->content_type('application/json');
	$request->content( $json_in );
	
	my $user_agent = LWP::UserAgent->new();
	my $response = $user_agent->request($request);
	
	croak "Request failed:" . $response->status_line()
		if !$response->is_success();

	carp "Response >" . ( defined( $response ) ? $response->content() : '' ) . "<"
		if $verbose;

	my $json_out;
	
	if ( exists( $METHODS_RETURNING_INVALID_JSON{ $args{'method'} } ) )
	{
		$json_out = $response->content();
	}
	else
	{
		$json_out = JSON::decode_json( $response->content() );
	}
	
	carp "JSON Response >" . ( defined( $json_out ) ? Dumper($json_out) : '' ) . "<"
		if $verbose;
	
	return $json_out;
}


=head2 verbose()

Control the verbosity of the debugging output.

$site_catalyst->verbose( 1 ); # turn on verbose information

$site_catalyst->verbose( 0 ); # quiet!

warn 'Verbose' if $site_catalyst->verbose(); # getter-style

=cut

sub verbose
{
	my ( $self, $verbose ) = @_;
	
	$self->{'verbose'} = ( $verbose || 0 )
		if defined( $verbose );
	
	return $self->{'verbose'};
}