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 $userDESCRIPTION
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
SASH_USERNAME
Your VR account username.
SASH_PASSWORD
Obvious heh?
SASH_ENDPOINT
Define the endpoint to be https://api.verticalresponse.com/1.0/VRAPI
SASH_CLIENT
This is defaulted to VR::API but partners should define it to be VR::API::Partner
HTTPS_PKCS12_FILE
The location of your certificate file (required by VR::API).
HTTPS_PKCS12_PASSWORD
The password tied to your certificate file if defined.
Flags
-u, -user
Your VR account username
-p, -password
You can define your password on the command line but you probably shouldn't.
-e, -endpoint
Define the endpoint to be https://api.verticalresponse.com/1.0/VRAPI
-client
This is defaulted to VR::API but partners should define it to be VR::API::Partner
-f, -filename
You can give sash a perl script to run on your behalf. Typically this is run in conjunction with the interactive flag.
-i, -interactive
If you have run the plugin with the -f flag then when you specify this flag you are given a sash command prompt with the last result of the executed script available to you. See the "Predefined Variables" section in "PROGRAMMING" for more information on taking advantage of this built in feature.
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 89000184The following is a summary of the commands that support the simple syntax and what the arguments are ( brackets indicate optional arguments ie [, field1, ...]:
calculateCampaignAudience campaign_id
createList name, type [, custom_field1, custom_field2, ...]
deleteList list_id
enumerateLists list_id
getCompany company_id [, include_users]
getListMembers list_id
getUser user_id
getUserByEmailAddress email_address
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.comIt 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
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