VerticalResponse.pm untested

filter: Statementstmt 0.0% 0 / 34 Branchbran 0.0% 0 / 8 Conditioncond 0.0% 0 / 2 MC/DCmcdc 0.0% 0 / 1 Subroutinesub 0.0% 0 / 7 Podpod 0.0% 0 / 1 totaltotal 0.0% 0 / 53 CC 5 SCAR 26.9
CC
5
Cov
0%
connect
30.0
BEGIN
2.0
BEGIN
2.0
CRAP 14.7
1 package Sash::Plugin::VerticalResponse;
2  
3 use strict;
4 use warnings;
5  
6 our $VERSION = '1.02';
7  
8 use Carp;
9  
10 use base qw( Sash::Plugin::Base );
11 use Sash::Plugin::VerticalResponse::Command;
12 use Sash::Plugin::VerticalResponse::Cursor;
13  
14 sub connect {
15 my $class = shift;
16 my $args = shift; # hashref
17  
18 # First make sure we have the appropriate environment variables defined.
19 $ENV{HTTPS_PKCS12_FILE} = $args->{terminal}->prompt_for( 'Certificate File' )
20 unless defined $ENV{HTTPS_PKCS12_FILE};
21
22 $ENV{HTTPS_PKCS12_PASSWORD} = $args->{terminal}->prompt_for( 'Passphrase' )
23 unless defined $ENV{HTTPS_PKCS12_PASSWORD};
24
25 $ENV{VR_API_SOAP_ENDPOINT} = $args->{endpoint};
26
27 # Confusing nomenclature here. The client specified in the CLI is
28 # really the name of the class to use to interact with the API.
29 my $client_class = $args->{client} || 'VR::API';
30  
31 eval "use $client_class";
32 croak $@ if $@;
33
34 my $client;
35  
36 eval {
37 $client = $client_class->new;
38 $client->login( $args );
39
40 $class->client( $client );
41 }; if ( $@ ) {
42 croak $class . '->connect Cannot connect to VerticalResponse API using endpoint ' . $args->{endpoint} . "\n$@";
43 }
44 }
45  
46 =head1 NAME
47  
48 Sash::Plugin::VerticalResponse
49  
50 =head1 VERSION
51  
52 This documentation refers to version 1.01.
53  
54 =head1 SYNOPSIS
55  
56 sash> set output tabular
57
58 sash> getUserByEmailAddress wes@verticalresponse.com
59
60 sash> set output vertical
61
62 sash> getCompany( { company_id = 12344 } )
63
64 sash> set output perlval
65
66 sash> $user = $client->getUserByEmailAddresss( { email_address => 'wes@verticalresponse.com' } )
67
68 sash> x $user
69  
70 =head1 DESCRIPTION
71  
72 This is a plugin for the amazing sash tool that provides a command line interface
73 to the VerticalResponse API L<http://www.verticalresponse.com/api>. It can be used
74 to invoke methods available in the API as well as a development tool to write and debug
75 applications written in perl.
76  
77 B<NOTE>: VRAPI will be used in this documentation to refer to the VerticalResponse API.
78  
79 =head1 CONNECTING
80  
81 There are a few ways to instruct sash to connect to the VRAPI. The simplest method
82 is to define the L<ENVIRONMENT VARIABLES> listed in the section below. Then you
83 can simply type sash at the command prompt and get started. The other option is
84 to use the traditional command line with the available L</FLAGS> illustrated below:.
85  
86 wes:~> sash -u wes@verticalresponse.com -e https://api.verticalresponse.com/1.0/VRAPI
87 password:
88
89 Certificate File: /a/secret/igotacertificatefile.p12
90
91 Passphrase:
92 Connection to https://api.verticalresponse.com/1.0/VRAPI established!
93
94 Welcome to sash. Commands end with the familiar ; or press 'return'.
95 Type 'help' for the complete command reference.
96
97 sash>
98  
99 You will be prompted for the certificate file and its passphrase when you use the
100 command line flags.
101  
102 =head2 Environment Variables
103  
104 =over 4
105  
106 =item *
107  
108 B<SASH_USERNAME>
109  
110 Your VR account username.
111  
112 =item *
113  
114 B<SASH_PASSWORD>
115  
116 Obvious heh?
117  
118 =item *
119  
120 B<SASH_ENDPOINT>
121  
122 Define the endpoint to be https://api.verticalresponse.com/1.0/VRAPI
123  
124 =item *
125  
126 B<SASH_CLIENT>
127  
128 This is defaulted to VR::API but partners should define it to be VR::API::Partner
129  
130 =item *
131  
132 B<HTTPS_PKCS12_FILE>
133  
134 The location of your certificate file (I<required> by VR::API).
135  
136 =item *
137  
138 B<HTTPS_PKCS12_PASSWORD>
139  
140 The password tied to your certificate file if defined.
141  
142 =back
143  
144 =head2 Flags
145  
146 =over 4
147  
148 =item *
149  
150 B<-u, -user>
151  
152 Your VR account username
153  
154 =item *
155  
156 B<-p, -password>
157  
158 You can define your password on the command line but you probably shouldn't.
159  
160 =item *
161  
162 B<-e, -endpoint>
163  
164 Define the endpoint to be https://api.verticalresponse.com/1.0/VRAPI
165  
166 =item *
167  
168 B<-client>
169  
170 This is defaulted to VR::API but partners should define it to be VR::API::Partner
171  
172 =item *
173  
174 B<-f, -filename>
175  
176 You can give sash a perl script to run on your behalf. Typically this is run in
177 conjunction with the interactive flag.
178  
179 =item *
180  
181 B<-i, -interactive>
182  
183 If you have run the plugin with the B<-f> flag then when you specify this flag
184 you are given a I<sash> command prompt with the last result of the executed
185 script available to you. See the L<Predefined Variables> section in L</PROGRAMMING>
186 for more information on taking advantage of this built in feature.
187  
188 =back
189  
190 =head1 COMMANDS
191  
192 Typically the API consists of methods that can be invoked by an external application.
193 In the case of sash it acts in that role but gives an easier to use interface to
194 provide access to those methods. Think of it like the mysql command line tool to the
195 VRAPI. You enter a I<command> and it displays a result set.
196  
197 =head2 show
198  
199 This command behaves like a standard I<sash> command.
200  
201 =head3 methods
202
203 At the present time the only available argument is I<methods>. This will display
204 a listing of the methods available in the VRAPI as illustrated below:
205  
206 sash> show methods
207 +--------------------------------------------+
208 | Methods |
209 +--------------------------------------------+
210 | addListMember |
211 | ... |
212 | validateStreetAddress |
213 +--------------------------------------------+
214  
215 43 rows in set (0.00 sec)
216  
217 Not very exciting but useful when you want to recall the exact spelling of method.
218 Sometime in a future release I would like to add support for getting the signature
219 of the method but we will have to wait for that.
220  
221 =head2 set
222  
223 The intention of this command is to allow you to configure aspects of the plugin.
224  
225 =head3 output [tabular|vertical|perlval]
226  
227 There is more detail in the L<OUTPUT FORMATS> section of this document but you can
228 configure the way results of command are displayed.
229  
230 =head2 VRAPI Methods
231  
232 All of the VRAPI methods are available as commands in this plugin. To use them
233 you have to know the signature of the method you want to use and be able to construct
234 the appropriate argument. If you are familiar with Perl then you won't have any
235 trouble understanding the example below:
236  
237 sash> getUserByEmailAddress { email_address => 'wesley_bailey@yahoo.com' }
238 +--------------------+------------------------------+
239 | Attribute | Value |
240 +--------------------+------------------------------+
241 | row | 1 |
242 +--------------------+------------------------------+
243
244 ...
245  
246 The argument to the command is in the form of a Perl anonymous hash. Hashes in
247 their simples format are a series of I<key/value> pairs. Use the I<fat comma> =>
248 to indicate the I<value> identified by I<key>. You use a standard comma to seperate
249 multiple pairs. The key does not have to be enclosed in quotes if its a single
250 word but the I<value> must be if you are enclosing a I<string>. Single or double
251 quotes are valid. The example below a call to create a list using I<sash>:
252  
253 sash> createList { name => 'sash tester 123' , type => 'email' }
254 +-----------+----------+
255 | Attribute | Value |
256 +-----------+----------+
257 | row | 1 |
258 +-----------+----------+
259 | List ID | 89000184 |
260 +-----------+----------+
261  
262 You can also use data structures as a valid I<value> in your hash. The following
263 example shows how to use anonymous arrays as well and how to code the
264 I<NVDictionary> (L<http://api.verticalresponse.com/wsdl/1.0/documentation.html>)
265 datatype:
266  
267 sash> addListMember { list_member => { \
268
269 > list_id => 89000184, member_data => [ \
270
271 > { name => 'first_name' , value => 'Wes' }, \
272
273 > { name => 'last_name', value => 'Bailey' }, \
274
275 > { name => 'email_address', value => 'wesley_bailey@nowhere.com' } \
276
277 > ] } }
278 +---------------------------+---------------------------+
279 | Attribute | Value |
280 +---------------------------+---------------------------+
281 | row | 1 |
282 +---------------------------+---------------------------+
283 | address_1 | |
284 | address_2 | |
285 | address_hash | |
286 | city | |
287 | country | |
288 | create_date | 2007-02-24 01:27:35 |
289 | email_address | wesley_bailey@nowhere.com |
290 | fax | |
291 | first_name | Wes |
292 | gender | |
293 | hash | 5cb92e2116 |
294 | home_phone | |
295 | id | 1 |
296 | ip_address | |
297 | last_name | Bailey |
298 | last_updated | 2007-02-24 01:27:35 |
299 | list_id | 89000184 |
300 | list_name | sash\ tester\ 123 |
301 | list_type | email |
302 | marital_status | |
303 | mobile_phone | |
304 | optin_status | |
305 | optin_status_last_updated | 2007-02-24 01:27:35 |
306 | postalcode | |
307 | state | |
308 | work_phone | |
309 +---------------------------+---------------------------+
310
311 1 rows in set (0.29 sec)
312  
313 The above also illustrates how you can spread your command over multiple lines
314 when the argument is quite involved.
315  
316 It is worth noting that to facilitate programming in the tool you can use
317 parenthesis to make it more like a traditional method invocation as illustrated
318 below:
319  
320 sash> deleteList( { list_id => 89000184 } )
321 +--------------+
322 | Deleted List |
323 +--------------+
324 | 89000184 |
325 +--------------+
326
327 1 rows in set (0.21 sec)
328  
329 See more in the L</PROGRAMMING> setion of this document for more information regarding
330 these features
331  
332 =head2 Simple Syntax
333  
334 If you are intimidated by all of the syntax it is good to know that some commands
335 support a much simpler syntax such that just the values can be passed as arguments
336 without the need for parenthesis or the anonymous hashes and arrays. For example
337 the I<deleteList> command can be written as:
338
339 sash> deleteList 89000184
340
341  
342 The following is a summary of the commands that support the simple syntax and what
343 the arguments are ( brackets indicate optional arguments ie [, field1, ...]:
344  
345 =over 4
346  
347 =item * calculateCampaignAudience campaign_id
348  
349 =item * createList name, type [, custom_field1, custom_field2, ...]
350  
351 =item * deleteList list_id
352  
353 =item * enumerateLists list_id
354  
355 =item * getCompany company_id [, include_users]
356  
357 =item * getListMembers list_id
358  
359 =item * getUser user_id
360  
361 =item * getUserByEmailAddress email_address
362  
363 =back
364  
365 =head1 OUTPUT FORMATS
366  
367 There are three different output formats that are available to configure the way
368 the result of a command is interpreted.
369  
370 =head2 tabular
371  
372 This is the default setting and is like the standard display by most command line
373 based database tools like mysql. It displays a list of columns accross the page
374 with the labels accross the top. An example is illustrated below:
375  
376 sash> getUserByEmailAddress wesley_bailey@yahoo.com
377 +-----------+-----------+----------------+-----------+--------------+------+------------------+
378 | address_1 | address_2 | auth_acct_mngr | auth_type | browser_type | city | company_function |
379 +-----------+-----------+----------------+-----------+--------------+------+------------------+
380 | | | | | M$ sucks 6 | | |
381 +-----------+-----------+----------------+-----------+--------------+------+------------------+
382
383 1 rows in set (0.20 sec)
384
385 Of course for the interest of having readable documentation the above is not all
386 of the columns that get displayed, but you get the point of the display style.
387  
388 =head2 vertical
389  
390 Find the result above unreadable on your small display? So do I so use vertical
391 instead and get:
392  
393 sash> set output vertical
394
395 sash> getUserByEmailAddress joe@nowhere.com
396 +--------------------+------------------------------+
397 | Attribute | Value |
398 +--------------------+------------------------------+
399 | row | 1 |
400 +--------------------+------------------------------+
401 | address_1 | |
402 | address_2 | |
403 | auth_acct_mngr | |
404 | auth_type | |
405 | browser_type | M$ sucks 6 |
406 | ... | |
407 | use_logger | |
408 +--------------------+------------------------------+
409
410 1 rows in set (0.21 sec)
411  
412 =head2 perlval
413  
414 This is an interesting option in that instead of trying to format the data for
415 output it instead just returns the perl code result. I<Sash> is written in Perl
416 so you can script this plugin to prototype your application or test a piece of
417 code that is not working. See the L</PROGRAMMING> section of this document for more
418 information on how to use this option to its fullest extent.
419  
420 =head1 PROGRAMMING
421  
422 The fun part of this VRAPI plugin for I<sash> is the builtin Perl support. This means
423 that almost anything you can do in your Perl application you can try out at the command
424 prompt and it will work as you expect it to. The following demonstrates a simple
425 example:
426  
427 sash> set output perlval
428  
429 sash> $name = "Another Sash Example List";
430  
431 sash> $type = "email";
432  
433 sash> $list = createList( { name => $name, type => $type } );
434  
435 sash> open $fh, "</tmp/list.csv";
436  
437 sash> while ( <$fh> ) { $client->addListMember( \
438  
439 > { list_member => { list_id => $list->{id}, member_data => [ \
440  
441 > { name => 'email_address', value => $_ } \
442  
443 > ] } } ) }
444  
445 sash> close $fh;
446  
447 In this simple example the file /tmp/list.csv is simply an email address on each line of
448 the file as illustrated below:
449  
450 wes@nowhere.com
451 nick@nowhere.com
452 lance@nowhere.com
453  
454 It doesn't get much more simple but come to think of it is pretty damn powerful to be able
455 to have this kind of functionality in a command line tool isn't it?
456  
457 To prove to yourself the above worked as expected you can view the results of your efforts
458 by running the following commands:
459  
460 sash> set output vertical
461  
462 sash> enumerateLists 89000199
463 +-----------------------+-----------------------+
464 | Attribute | Value |
465 +-----------------------+-----------------------+
466 | row | 1 |
467 +-----------------------+-----------------------+
468 | creation_date | 2007-02-26T06:34:55Z |
469 | displayed_fields | |
470 | fields | |
471 | form_id | |
472 | id | 89000199 |
473 | indexed_fields | |
474 | last_mailed | |
475 | mailable | 3 |
476 | mailable_last_updated | 2007-02-26T06:36:18Z |
477 | name | another wes sash test |
478 | size | 3 |
479 | status | active |
480 | type | email |
481 +-----------------------+-----------------------+
482  
483 1 rows in set (0.23 sec)
484  
485 sash> getListMembers 89000199
486 +---------------------------+---------------------------+
487 | Attribute | Value |
488 +---------------------------+---------------------------+
489 | row | 1 |
490 +---------------------------+---------------------------+
491 | address_1 | |
492 | address_2 | |
493 | address_hash | |
494 | city | |
495 | country | |
496 | create_date | 2007-02-26 06:36:18 |
497 | email_address | lance@nowhere.com |
498 | fax | |
499 ...
500  
501 3 rows in set (0.47 sec)
502
503 sash>
504  
505 The inquisitive might note that I didn't define the variable C<$client> anywhere in my
506 example. Read the next section to understand how it was defined and how you can use it
507 as well without worry.
508  
509 =head2 Predefined Variables
510  
511 There are some predefined variables that this plugin makes available to facilitate
512 Perl programming from the command line that can then be transfered into your application
513 code. The following is a summary:
514  
515 =head3 C<$client>
516  
517 In your application code you are most likely going to invoke the constructor of the
518 appropriate VR::API class that you are using in the following manner:
519  
520 $client = VR::API->new;
521  
522 Because this is a pretty standard way of writing you can also use the C<$client> syntax
523 when you invoke a command regardless of the output format you presently have set:
524  
525 sash> $client->getUserByEmailAddress( { email_address => 'wesley_bailey@nowhere.com' } );
526  
527 This is really helpful when you have the output format set to I<perlval> so that your
528 command invocation looks and behaves just like it would in Perl:
529  
530 sash> set output perlval
531  
532 sash> $user = $client->getUserByEmailAddress( { email_address => 'wesley_bailey@yahoo.com' } )
533  
534 To convince yourself that the variable C<$user> actually has the correct values see the
535 L</DEBUGGING> section below.
536  
537 =head3 C<$result>
538  
539 Any command that you execute that produces a result will have the Perl equivalent stored
540 in a variable named C<$result>. This is useful if in the next command you want to refer
541 to any of the properties of result to be its arguments as demonstrated below:
542  
543 sash> getCompany( { id => $result->{company_id} } )
544  
545 This is useful, but beware trying to result this code in your application unless you have
546 defined the VRAPI query to be a variable of the same name.
547  
548 =head1 DEBUGGING
549  
550 If you are familiar with the Perl debugger then you are used to examining the values
551 associated with variables at specific points in your program. You can do the same
552 thing in sash by using the I<x> command as illustrated below:
553  
554 sash> x $user
555 $user = bless( {
556 "offer_optin" => undef,
557 "auth_acct_mngr" => undef,
558 "address_2" => undef,
559 "state" => undef,
560 "password_question" => "America/Los_Angeles",
561 "os" => "Windows NT 5.1",
562 "url" => undef,
563 "postalcode" => undef,
564 "id" => 79734,
565 ...
566 "first_name" => "wesley"
567 }, 'User' );
568  
569 Not quite the same format as in the Perl debugger but readable and it provides useful
570 information. If you know perl you will recognize this is a format produced by L<Data::Dumper>.
571  
572 =head1 EXPIRED SESSION
573  
574 There are times when you have periods of inactivity and your session with the
575 VRAPI expires. You will suddenly get a fault that at first makes you think you
576 did something wrong illustrated below:
577  
578 =over 4
579  
580 Error while communicating with
581 https://api.verticalresponse.com/1.0/VRAPI - SOAP Fault Code:
582 SOAP-ENV:VRAPI.ExpiredSession: SOAP Fault String: The specified session_id has
583 expired - at ...
584  
585 =back
586  
587 When this happens you can use the I<reconnect> or I<refresh> commands to
588 re-establish your connection to the VRAPI and use I<sash> normally.
589  
590 =head1 AUTHOR
591  
592 Wes Bailey, <wes@verticalresponse.com>
593  
594 =head1 BUGS
595  
596 When you find a bug in this plugin please contact the author. There are some bugs
597 related to sash so please read the information regarding them.
598  
599 =head1 SEE ALSO
600  
601 L<sash>
602  
603 L<VR::API>
604  
605 L<VR::API::Partner>
606  
607 =head1 COPYRIGHT
608  
609 Copyright (C) 2007, Wes Bailey, VerticalResponse Inc.
610  
611 This sash plugin is free software; you can redistribute it and/or modify
612 it under the terms of the GNU General Public License as published by
613 the Free Software Foundation; either version 2 of the License, or
614 (at your option) any later version.
615  
616 This sash plugin is distributed in the hope that it will be useful,
617 but WITHOUT ANY WARRANTY; without even the implied warranty of
618 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
619 GNU General Public License for more details.
620  
621 You should have received a copy of the GNU General Public License
622 along with this program; if not, write to the Free Software
623 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
624  
625 =cut
626  
627 1;