Wesley Bailey > Sash-Plugin-VerticalResponse > Sash::Plugin::VerticalResponse

Download:
Sash-Plugin-VerticalResponse-1.02.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 1.02   Source  

NAME ^

Sash::Plugin::VerticalResponse

VERSION ^

This documentation refers to version 1.01.

SYNOPSIS ^

    sash> set output tabular
    
    sash> getUserByEmailAddress wes@verticalresponse.com
    
    sash> set output vertical
    
    sash> getCompany( { company_id = 12344 } )
    
    sash> set output perlval
    
    sash> $user = $client->getUserByEmailAddresss( { email_address => 'wes@verticalresponse.com' } )
    
    sash> x $user

DESCRIPTION ^

This is a plugin for the amazing sash tool that provides a command line interface to the VerticalResponse API http://www.verticalresponse.com/api. It can be used to invoke methods available in the API as well as a development tool to write and debug applications written in perl.

NOTE: VRAPI will be used in this documentation to refer to the VerticalResponse API.

CONNECTING ^

There are a few ways to instruct sash to connect to the VRAPI. The simplest method is to define the "ENVIRONMENT VARIABLES" listed in the section below. Then you can simply type sash at the command prompt and get started. The other option is to use the traditional command line with the available "FLAGS" illustrated below:.

    wes:~> sash -u wes@verticalresponse.com -e https://api.verticalresponse.com/1.0/VRAPI
    password:
    
    Certificate File: /a/secret/igotacertificatefile.p12
    
    Passphrase:
    Connection to https://api.verticalresponse.com/1.0/VRAPI established!
    
    Welcome to sash.  Commands end with the familiar ; or press 'return'.
    Type 'help' for the complete command reference.
    
    sash>

You will be prompted for the certificate file and its passphrase when you use the command line flags.

Environment Variables

Flags

COMMANDS ^

Typically the API consists of methods that can be invoked by an external application. In the case of sash it acts in that role but gives an easier to use interface to provide access to those methods. Think of it like the mysql command line tool to the VRAPI. You enter a command and it displays a result set.

show

This command behaves like a standard sash command.

methods

At the present time the only available argument is methods. This will display a listing of the methods available in the VRAPI as illustrated below:

    sash> show methods
    +--------------------------------------------+
    | Methods                                    |
    +--------------------------------------------+
    | addListMember                              |
    | ...                                        |
    | validateStreetAddress                      |
    +--------------------------------------------+

    43 rows in set (0.00 sec)

Not very exciting but useful when you want to recall the exact spelling of method. Sometime in a future release I would like to add support for getting the signature of the method but we will have to wait for that.

set

The intention of this command is to allow you to configure aspects of the plugin.

output [tabular|vertical|perlval]

There is more detail in the "OUTPUT FORMATS" section of this document but you can configure the way results of command are displayed.

VRAPI Methods

All of the VRAPI methods are available as commands in this plugin. To use them you have to know the signature of the method you want to use and be able to construct the appropriate argument. If you are familiar with Perl then you won't have any trouble understanding the example below:

    sash> getUserByEmailAddress { email_address => 'wesley_bailey@yahoo.com' }
    +--------------------+------------------------------+
    | Attribute          | Value                        |
    +--------------------+------------------------------+
    | row                |                            1 |
    +--------------------+------------------------------+
    
    ...

The argument to the command is in the form of a Perl anonymous hash. Hashes in their simples format are a series of key/value pairs. Use the fat comma => to indicate the value identified by key. You use a standard comma to seperate multiple pairs. The key does not have to be enclosed in quotes if its a single word but the value must be if you are enclosing a string. Single or double quotes are valid. The example below a call to create a list using sash:

    sash> createList { name => 'sash tester 123' , type => 'email' }
    +-----------+----------+
    | Attribute | Value    |
    +-----------+----------+
    | row       |        1 |
    +-----------+----------+
    | List ID   | 89000184 |
    +-----------+----------+

You can also use data structures as a valid value in your hash. The following example shows how to use anonymous arrays as well and how to code the NVDictionary (http://api.verticalresponse.com/wsdl/1.0/documentation.html) datatype:

    sash> addListMember { list_member => { \
    
    > list_id => 89000184, member_data => [ \
    
    > { name => 'first_name' , value => 'Wes' }, \
    
    > { name => 'last_name', value => 'Bailey' }, \
    
    > { name => 'email_address', value => 'wesley_bailey@nowhere.com' } \
    
    > ] } }
    +---------------------------+---------------------------+
    | Attribute                 | Value                     |
    +---------------------------+---------------------------+
    | row                       |                         1 |
    +---------------------------+---------------------------+
    | address_1                 |                           |
    | address_2                 |                           |
    | address_hash              |                           |
    | city                      |                           |
    | country                   |                           |
    | create_date               | 2007-02-24 01:27:35       |
    | email_address             | wesley_bailey@nowhere.com |
    | fax                       |                           |
    | first_name                | Wes                       |
    | gender                    |                           |
    | hash                      | 5cb92e2116                |
    | home_phone                |                           |
    | id                        |                         1 |
    | ip_address                |                           |
    | last_name                 | Bailey                    |
    | last_updated              | 2007-02-24 01:27:35       |
    | list_id                   |                  89000184 |
    | list_name                 | sash\ tester\ 123         |
    | list_type                 | email                     |
    | marital_status            |                           |
    | mobile_phone              |                           |
    | optin_status              |                           |
    | optin_status_last_updated | 2007-02-24 01:27:35       |
    | postalcode                |                           |
    | state                     |                           |
    | work_phone                |                           |
    +---------------------------+---------------------------+
    
    1 rows in set (0.29 sec)

The above also illustrates how you can spread your command over multiple lines when the argument is quite involved.

It is worth noting that to facilitate programming in the tool you can use parenthesis to make it more like a traditional method invocation as illustrated below:

    sash> deleteList( { list_id => 89000184 } )
    +--------------+
    | Deleted List |
    +--------------+
    |     89000184 |
    +--------------+
    
    1 rows in set (0.21 sec)

See more in the "PROGRAMMING" setion of this document for more information regarding these features

Simple Syntax

If you are intimidated by all of the syntax it is good to know that some commands support a much simpler syntax such that just the values can be passed as arguments without the need for parenthesis or the anonymous hashes and arrays. For example the deleteList command can be written as:

    sash> deleteList 89000184

The following is a summary of the commands that support the simple syntax and what the arguments are ( brackets indicate optional arguments ie [, field1, ...]:

OUTPUT FORMATS ^

There are three different output formats that are available to configure the way the result of a command is interpreted.

tabular

This is the default setting and is like the standard display by most command line based database tools like mysql. It displays a list of columns accross the page with the labels accross the top. An example is illustrated below:

    sash> getUserByEmailAddress wesley_bailey@yahoo.com
    +-----------+-----------+----------------+-----------+--------------+------+------------------+
    | address_1 | address_2 | auth_acct_mngr | auth_type | browser_type | city | company_function |
    +-----------+-----------+----------------+-----------+--------------+------+------------------+
    |           |           |                |           | M$ sucks 6   |      |                  |
    +-----------+-----------+----------------+-----------+--------------+------+------------------+
    
    1 rows in set (0.20 sec)

Of course for the interest of having readable documentation the above is not all of the columns that get displayed, but you get the point of the display style.

vertical

Find the result above unreadable on your small display? So do I so use vertical instead and get:

    sash> set output vertical
    
    sash> getUserByEmailAddress joe@nowhere.com
    +--------------------+------------------------------+
    | Attribute          | Value                        |
    +--------------------+------------------------------+
    | row                |                            1 |
    +--------------------+------------------------------+
    | address_1          |                              |
    | address_2          |                              |
    | auth_acct_mngr     |                              |
    | auth_type          |                              |
    | browser_type       | M$ sucks 6                   |
    | ...                |                              |
    | use_logger         |                              |
    +--------------------+------------------------------+
    
    1 rows in set (0.21 sec)

perlval

This is an interesting option in that instead of trying to format the data for output it instead just returns the perl code result. Sash is written in Perl so you can script this plugin to prototype your application or test a piece of code that is not working. See the "PROGRAMMING" section of this document for more information on how to use this option to its fullest extent.

PROGRAMMING ^

The fun part of this VRAPI plugin for sash is the builtin Perl support. This means that almost anything you can do in your Perl application you can try out at the command prompt and it will work as you expect it to. The following demonstrates a simple example:

    sash> set output perlval

    sash> $name = "Another Sash Example List";

    sash> $type = "email";

    sash> $list = createList( { name => $name, type => $type } );

    sash> open $fh, "</tmp/list.csv";

    sash> while ( <$fh> ) { $client->addListMember( \

        > { list_member => { list_id => $list->{id}, member_data => [ \

        > { name => 'email_address', value => $_ } \

        > ] } } ) }

    sash> close $fh;

In this simple example the file /tmp/list.csv is simply an email address on each line of the file as illustrated below:

    wes@nowhere.com
    nick@nowhere.com
    lance@nowhere.com

It doesn't get much more simple but come to think of it is pretty damn powerful to be able to have this kind of functionality in a command line tool isn't it?

To prove to yourself the above worked as expected you can view the results of your efforts by running the following commands:

    sash> set output vertical

    sash> enumerateLists 89000199
    +-----------------------+-----------------------+
    | Attribute             | Value                 |
    +-----------------------+-----------------------+
    | row                   |                     1 |
    +-----------------------+-----------------------+
    | creation_date         | 2007-02-26T06:34:55Z  |
    | displayed_fields      |                       |
    | fields                |                       |
    | form_id               |                       |
    | id                    |              89000199 |
    | indexed_fields        |                       |
    | last_mailed           |                       |
    | mailable              |                     3 |
    | mailable_last_updated | 2007-02-26T06:36:18Z  |
    | name                  | another wes sash test |
    | size                  |                     3 |
    | status                | active                |
    | type                  | email                 |
    +-----------------------+-----------------------+

    1 rows in set (0.23 sec)

    sash> getListMembers 89000199
    +---------------------------+---------------------------+
    | Attribute                 | Value                     |
    +---------------------------+---------------------------+
    | row                       |                         1 |
    +---------------------------+---------------------------+
    | address_1                 |                           |
    | address_2                 |                           |
    | address_hash              |                           |
    | city                      |                           |
    | country                   |                           |
    | create_date               | 2007-02-26 06:36:18       |
    | email_address             | lance@nowhere.com |
    | fax                       |                           |
    ...

    3 rows in set (0.47 sec)
    
    sash> 

The inquisitive might note that I didn't define the variable $client anywhere in my example. Read the next section to understand how it was defined and how you can use it as well without worry.

Predefined Variables

There are some predefined variables that this plugin makes available to facilitate Perl programming from the command line that can then be transfered into your application code. The following is a summary:

$client

In your application code you are most likely going to invoke the constructor of the appropriate VR::API class that you are using in the following manner:

    $client = VR::API->new; 

Because this is a pretty standard way of writing you can also use the $client syntax when you invoke a command regardless of the output format you presently have set:

    sash> $client->getUserByEmailAddress( { email_address => 'wesley_bailey@nowhere.com' } );

This is really helpful when you have the output format set to perlval so that your command invocation looks and behaves just like it would in Perl:

    sash> set output perlval

    sash> $user = $client->getUserByEmailAddress( { email_address => 'wesley_bailey@yahoo.com' } )

To convince yourself that the variable $user actually has the correct values see the "DEBUGGING" section below.

$result

Any command that you execute that produces a result will have the Perl equivalent stored in a variable named $result. This is useful if in the next command you want to refer to any of the properties of result to be its arguments as demonstrated below:

    sash> getCompany( { id => $result->{company_id} } )

This is useful, but beware trying to result this code in your application unless you have defined the VRAPI query to be a variable of the same name.

DEBUGGING ^

If you are familiar with the Perl debugger then you are used to examining the values associated with variables at specific points in your program. You can do the same thing in sash by using the x command as illustrated below:

    sash> x $user
    $user = bless( {
      "offer_optin" => undef,
      "auth_acct_mngr" => undef,
      "address_2" => undef,
      "state" => undef,
      "password_question" => "America/Los_Angeles",
      "os" => "Windows NT 5.1",
      "url" => undef,
      "postalcode" => undef,
      "id" => 79734,
    ...
      "first_name" => "wesley"
    }, 'User' );

Not quite the same format as in the Perl debugger but readable and it provides useful information. If you know perl you will recognize this is a format produced by Data::Dumper.

EXPIRED SESSION ^

There are times when you have periods of inactivity and your session with the VRAPI expires. You will suddenly get a fault that at first makes you think you did something wrong illustrated below:

Error while communicating with https://api.verticalresponse.com/1.0/VRAPI - SOAP Fault Code: SOAP-ENV:VRAPI.ExpiredSession: SOAP Fault String: The specified session_id has expired - at ...

When this happens you can use the reconnect or refresh commands to re-establish your connection to the VRAPI and use sash normally.

AUTHOR ^

Wes Bailey, <wes@verticalresponse.com>

BUGS ^

When you find a bug in this plugin please contact the author. There are some bugs related to sash so please read the information regarding them.

SEE ALSO ^

sash

VR::API

VR::API::Partner

COPYRIGHT ^

Copyright (C) 2007, Wes Bailey, VerticalResponse Inc.

This sash plugin is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This sash plugin is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

syntax highlighting: