The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WebService-E4SE-0.01
River stage zero No dependents
++
/ WebService::E4SE

NAME

WebService::E4SE - Communicate with the various Epicor E4SE web services.

VERSION

Version 0.01

SYNOPSIS

Epicor's http://www.epicor.com/Products/Pages/E4SE.aspx E4SE software uses a clunky, IE-only interface (just try to fill in your timesheet with a non-windows machine! I dare ya!).

Each action on the software calls a SOAP-based web service API method. However, the APIs are not neatly packaged in one place (a la Salesforce, etc.). Also, there aren't any sessions. So, each call to the API must send username and password credentials all over again (using NTLM).

There are more than 100 web service files you could work with (.asmx extensions) each having their own set of methods. Some of these are grouped somewhat logically, some are not. On your installation of E4SE, you can get a listing of method calls available by visiting one of those files directly (http://epicor/e4se/Resource.asmx for example).

The purpose of this module is to somewhat abstract out the tedium of dealing with all of this stuff.

The module will grab the WSDL from the file you're trying to deal with. It will make use of that WSDL with XML::Compile::WSDL11. You can force a reload of the WSDL at any time. So, we build the XML::Compile::WSDL11 object and hold onto it for any further calls to that file. These are generated by the calls you make, so hopefully we don't kill you with too many objects. You can work directly with the new XML::Compile::WSDL11 object if you like, or use the abstracted out methods listed below.

For transportation, we're using XML::Compile::Transport::SOAPHTTP using LWP::UserAgent with Authen::NTLM.

Here's some sample code:

  use WebService::E4SE;

  # create a new object
  my $ws = WebService::E4SE->new(
    username => 'AD\username',                  # NTLM authentication
    password => 'A password',                   # NTLM authentication
    realm => '',                                # LWP::UserAgent and Authen::NTLM
    site => 'epicor:80',                        # LWP::UserAgent and Authen::NTLM
    base_url => URL->new('http://epicor/e4se'), # LWP::UserAgent and Authen::NTLM
    timeout => 30,                              # LWP::UserAgent
  );

  # get an array ref of web service APIs to communicate with
  my $res = $ws->files();
  say Dumper $res;

  # returns a list of method names for the file you wanted to know about.
  my @operations = $ws->operations('Resource.asmx');
  say Dumper @operations;

  # call a method and pass some named parameters to it
  my ($res,$trace) = $ws->call('Resource.asmx','GetResourceForUserID', userID=>'someuser');

  # give me the XML::Compile::WSDL11 object
  my $wsdl = $ws->get_object('Resource.asmx'); #returns the usable XML::Compile::WSDL11 object

METHODS

new( %params )

The constructor will give you a new WebService::E4SE object. The parameters passed to it are all listed below. They have defaults and since this is a Moose object, you can set each one individually as well with $ws->param_name($foo).

parameters

username

Default is an empty string. Usually, you need to prefix this with the domain your E4SE installation is using. 'AD\myusername'

password

Default is an empty string. This will be your domain password. No attempt to hide this is made as E4SE cannot function over SSL anyway, why should I bother trying to make you feel secure when you're not.

realm

Default is an empty string. Again, this is for the Authen::NTLM module and can generally be left blank.

site

Default is 'epicor:80'. This is for the Authen::NTLM module. Set this accordingly

base_url

Type is URL. Default is URL->new('http://epicor/e4se'). This should be the base installation path to your E4SE installation.

timeout

Default is 30. This is passed to LWP::UserAgent to handle how long you want to wait on responses.

files()

This method will return a reference to an array file names that this web service has knowledge of for an E4SE installation.

  my $files = $ws->files;  # 'ActionCall.asmx', 'Company.asmx', 'Resource.asmx', etc....

call( $file, $function, %parameters )

This method will call an API method for the file you want. It will return 0 and warn on errors outside of XML::Compile::WSDL11's knowledge, otherwise it's just a little wrapper around XML::Compile::WSDL11->call();

Another way to do this would be $ws->get_object('Reource.asmx')->call( $function, %params );

$file

This is the string name of the file (also the WSDL11 object) you wish to deal with. 'Resource.asmx' for example.

$function

This is the string name of the function you want to call in the file's API. 'GetResourceForUserID' for xample.

%parameters

This is a hash of name => value pairs to be passed in for the function call. This is XML escaped properly by XML::Compile::WSDL11.

get_object( $file )

This method will return an XML::Compile::WSDL11 object for the string file name you supply. This handles going to the file's WSDL URL, grabbing that URL with LWP::UserAgent and Authen::NTLM, and using that WSDL response to setup a new XML::Compile::WSDL11 object. Note that if you have previously setup a XML::Compile::WSDL object for that file name, it will just return that object rather than going to the server and requesting a new WSDL.

force_wsdl_reload(0)

This property is defaulted to false (0). If set to true, the next call to a method that would require a XML::Compile::WSDL11 object will go out to the server and re-grab the WSDL and re-setup that WSDL object no matter if we have already generated it or not. The property will be reset to false directly after the next WSDL object setup.

AUTHOR

Chase Whitener << <cwhitener at gmail.com> >>

BUGS

Please report any bugs or feature requests to bug-webservice-e4se at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WebService-E4SE. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

        perldoc WebService::E4SE

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2013 Chase Whitener.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.