required results from the CPAN

ARS-Simple

view release on metacpan or search on metacpan

    $password =~ s/\s+$//;

    print "\nSaving config file, using the following:\n";
}

if (! $configfile)
{
    $configfile = 'blib/lib/ARS/Simple.cfg';
}
open $fh, '>', $configfile || die "failed to open $configfile: $!";
print $fh "# Config file for ARS::Simple\n# generated by Config.PL (".scalar(localtime).")\n# This file MUST be valid perl (as it is 'required')\n# Note user and password are obfuscated, NOT encrypted.\n\n";
print $fh q{%config = (} . "\n";

# Doing simple obfuscation of user and password
my $k = '5Jv@sI9^bl@D*j5H3@:7g4H[2]d%Ks314aNuGeX;';
my $x = substr($k, 0, length($user));
my $u = $user ^ $x;
my $up = unpack('H*', $u);
print $fh "\tuser     => '$up',\n";

$x = substr($k, 0, length($password));

README view on Meta::CPAN

copy of the full license at:

L<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

html/Simple.html view on Meta::CPAN

 <span class="string">form</span>  <span class="operator">=&gt;</span> <span class="variable">$form</span><span class="operator">,</span>
 <span class="string">query</span> <span class="operator">=&gt;</span> <span class="variable">$query</span><span class="operator">,</span>
 <span class="string">lfid</span>  <span class="operator">=&gt;</span> <span class="operator">{</span> <span class="variable">label1</span><span class="operator">,</span> <span class="variable">fid1</span><span class="operator">,</span> <span class="...
 <span class="operator">}</span><span class="operator">);</span>
</code></pre>

<h1 id="METHODS">METHODS</h1>

<h2 id="new">new</h2>

<p>Constructor for ARS::Simple. There are three required arguments:</p>

<dl>

<dt id="server">server</dt>
<dd>

<p>The name (or possibly IP Address) of the Remedy ARSystem server you wish to connect to.</p>

</dd>
<dt id="user">user</dt>
<dd>

<p>The user you wish to connect as (this is often a user with administrator privilages). Note that while this is a required argument, it may be supplied via the configuration file to avoid lots of scripts with the user (and password) in them (less to...

</dd>
<dt id="password">password</dt>
<dd>

<p>The password to the user you wish to connect as. This may come from the configuration file if set.</p>

</dd>
</dl>

html/Simple.html view on Meta::CPAN

     <span class="string">password</span>    <span class="operator">=&gt;</span> <span class="string">'password_for_some_admin'</span><span class="operator">,</span>
     <span class="string">log</span>         <span class="operator">=&gt;</span> <span class="variable">$log</span><span class="operator">,</span>
     <span class="string">max_returns</span> <span class="operator">=&gt;</span> <span class="number">0</span><span class="operator">,</span>    <span class="comment"># allow unlimited returns</span>
     <span class="string">reset_limit</span> <span class="operator">=&gt;</span> <span class="number">3000</span><span class="operator">,</span> <span class="comment"># reset to a suitable limit after each call using max_returns</span>
     <span class="string">ars_debug</span>   <span class="operator">=&gt;</span> <span class="number">1</span><span class="operator">,</span>    <span class="comment"># get a whole lot of debugging information (you real should not need)</span>
     <span class="operator">}</span><span class="operator">);</span>
</code></pre>

<h2 id="get_list">get_list</h2>

<p>Method to return an array reference of Entry-Id values for a form. Arguments are passed as an hash reference, with two required parameters, eg:</p>

<pre><code> <span class="comment"># Get theEntry-Id's for all records in the 'User' form.</span>
 <span class="keyword">my</span> <span class="variable">$eids</span> <span class="operator">=</span> <span class="variable">$ars</span><span class="operator">-&gt;</span><span class="variable">get_list</span><span class="operator">(</span><span class...
</code></pre>

<p>The query parameter can be the same format as you would use in the &#39;User Tool&#39; to query a form, however we recommend the use of field ID&#39;s (FID) rather than the default field name as they may change. I prefer to define a hash of the fo...

<pre><code> <span class="keyword">my</span> <span class="variable">%user</span> <span class="operator">=</span> <span class="operator">(</span> <span class="string">UserID</span> <span class="operator">=&gt;</span> <span class="number">101</span><spa...
</code></pre>

<p>the a query could be something like</p>

<pre><code> <span class="keyword">my</span> <span class="variable">$query</span> <span class="operator">=</span> <span class="string">qq{ '</span><span class="variable">$user</span><span class="string">{UserID}' LIKE "g%" }</span><span class="operato...
 <span class="keyword">my</span> <span class="variable">$eids</span> <span class="operator">=</span> <span class="variable">$ars</span><span class="operator">-&gt;</span><span class="variable">get_list</span><span class="operator">(</span><span class...
</code></pre>

<h2 id="get_SQL">get_SQL</h2>

<p>Run direct SQL on your server, there is only one required argument, the sql, you may optionally set the max_returns value.</p>

<p>The names of the fields can be found from the Admin Tool, under the database tab for a form. This will be the name of the field used in the database view of the Remedy form. <b>Note</b> you do need to replace spaces with and underscore &#39;_&#39;...

<p>Example method call:</p>

<pre><code> <span class="keyword">my</span> <span class="variable">$data</span> <span class="operator">=</span> <span class="variable">$ars</span><span class="operator">-&gt;</span><span class="variable">get_SQL</span><span class="operator">(</span><...
     <span class="string">sql</span> <span class="operator">=&gt;</span> <span class="string">q{select Login_name, Full_Name from User_X where Login_name like 'g%' order by Login_name}</span><span class="operator">,</span>
     <span class="string">max_returns</span> <span class="operator">=&gt;</span> <span class="number">0</span><span class="operator">,</span>
     <span class="operator">}</span><span class="operator">);</span>
</code></pre>

html/Simple.html view on Meta::CPAN

 
 <span class="variable">$data</span> <span class="operator">=</span> <span class="operator">{</span>
     <span class="variable">eID1</span><span class="operator">,</span> <span class="operator">{</span><span class="string">Label1</span> <span class="operator">=&gt;</span> <span class="variable">value1</span><span class="operator">,</span> <span cla...
     <span class="variable">eID2</span><span class="operator">,</span> <span class="operator">{</span><span class="string">Label1</span> <span class="operator">=&gt;</span> <span class="variable">value1</span><span class="operator">,</span> <span cla...
     <span class="operator">...</span>
     <span class="operator">}</span><span class="operator">;</span>
</code></pre>

<h2 id="get_fields">get_fields</h2>

<p>get_fields has a required argument, the form you require the field details for. The returned hash reference is the result of a call to ars_GetFieldTable, the keys are the field names and the values are the field ids (fid).</p>

<h2 id="set_max_entries">set_max_entries</h2>

<p>This requires that the &#39;user&#39; has administrator access. This allows the overriding of the <b>system wide</b> maximum rows returned setting AR_SERVER_INFO_MAX_ENTRIES, setting this to zero (0) will allow unlimited returns.</p>

<p><b>Beware of setting this to a small value, it is system wide and could have a major impact on your system</b></p>

<h1 id="PRIVATE-METHODS">PRIVATE METHODS</h1>

<h2 id="init">_init</h2>

html/Simple.html view on Meta::CPAN

<h2 id="DESTROY">DESTROY</h2>

<p>Log out from ARSystem</p>

<h2 id="check_initialised">_check_initialised</h2>

<p>Check to insure that there is a connection to Remedy ARSystem. Returns true if connected.</p>

<h2 id="reset_max_entries">_reset_max_entries</h2>

<p>If set, returns the the system wide AR_SERVER_INFO_MAX_ENTRIES back to a suitable value (eg 3000). This required the &#39;user&#39; has administrator access</p>

<h1 id="TODO">TODO</h1>

<p>Add in the tools below.</p>

<p>Add in further methods to make life easier and your code more readable</p>

<h1 id="TOOLS">TOOLS</h1>

<p><b>NOT DONE YET</b></p>

<p>The lfid array used by the get_data_by_label() method required that a hash is defined which describes the field lables (names) you want to use mapped to the field ID (FID). The encluded script will construct such a hash for all relavent fields. Yo...

<p>There is a win32 version of this which copies the data to your clipboard, to make your life easier.</p>

<h1 id="AUTHOR">AUTHOR</h1>

<p>Greg George, <code>&lt;gng at cpan.org&gt;</code></p>

<h1 id="BUGS">BUGS</h1>

<p>Please report any bugs or feature requests to <code>bug-ars-simple at rt.cpan.org</code>, or through the web interface at <a href="http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ARS-Simple">http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ARS-Simple...

html/Simple.html view on Meta::CPAN

<h1 id="LICENSE-AND-COPYRIGHT">LICENSE AND COPYRIGHT</h1>

<p>Copyright 2013 Greg George.</p>

<p>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:</p>

<p><a href="http://www.perlfoundation.org/artistic_license_2_0">http://www.perlfoundation.org/artistic_license_2_0</a></p>

<p>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 n...

<p>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.</p>

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

<p>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...

<p>Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS &quot;AS IS&#39; AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEME...


</body>

lib/ARS/Simple.pm view on Meta::CPAN

    return 1;
}

sub get_list
{
    my ($self, $args) = @_;  # Expect args keys of 'form', 'query', optionally 'max_returns'

    # Check ARSystem initailised
    return unless $self->_check_initialised();

    # Check required args
    unless ($args->{form} && $args->{query})
    {
        $self->_carp("get_list() requires 'form' and 'query' arguments\n");
        return;
    }


    # Create a qualifier struct
    my $qual = $self->_load_qualifier($args);
    return unless $qual;

lib/ARS/Simple.pm view on Meta::CPAN

    my ($self, $args) = @_;

    my $form    = $args->{form};
    my $query   = $args->{query};
    my $lfid_hr = $args->{lfid};
    my @fid     = values %$lfid_hr;

    # Check ARSystem initailised
    return unless $self->_check_initialised();

    # Check required args
    unless ($args->{form} && $args->{query})
    {
        $self->_carp("get_data_by_label() requires 'form' and 'query' arguments\n");
        return;
    }

    #-- Create a qualifier struct
    my $qual = $self->_load_qualifier($args);
    return unless $qual;

lib/ARS/Simple.pm view on Meta::CPAN

    if (defined $self->{reset_limit})
    {
        $self->set_max_entries($self->{reset_limit});
    }
}

sub get_fields
{
    my ($self, $form) = @_;

    # Check required args
    unless ($form)
    {
        $self->_carp("get_fields() requires the 'form' as a argument\n");
        return;
    }

    my %fids = ars_GetFieldTable($self->{ctl}, $form);
    $self->_carp("get_fields() error: $ars_errstr\n") unless (%fids);

    return \%fids;

lib/ARS/Simple.pm view on Meta::CPAN

        {
            $self->{ctl} = $ctl;
        }
        else
        {
            croak(__PACKAGE__ . " object initialisation failed.\nFailed to log into Remedy server=" . $self->{server} . " as user '$user' with supplied password: $ars_errstr\n");
        }
    }
    else
    {
        croak(__PACKAGE__ . " object initialisation failed, server, user and password are required\n");
    }
}


    # GG test - need to find and store the current value of AR_SERVER_INFO_MAX_ENTRIES
    #           so we can set reset_limit if not defined
    #my %s = ars_GetServerInfo($self->{ctl});
    #print  Dumper(\%s);

lib/ARS/Simple.pm view on Meta::CPAN


Provide a perlish interface to ARSperl which makes your code
more readable

=back

=head1 METHODS

=head2 new

Constructor for ARS::Simple.  There are three required arguments:

=over 4

=item server

The name (or possibly IP Address) of the Remedy ARSystem server you
wish to connect to.

=item user

The user you wish to connect as (this is often a user with administrator
privilages).  Note that while this is a required argument, it may be supplied
via the configuration file to avoid lots of scripts with the user (and password)
in them (less to change, not on display so safer).

=item password

The password to the user you wish to connect as.  This may come from the configuration
file if set.

=back

lib/ARS/Simple.pm view on Meta::CPAN

     password    => 'password_for_some_admin',
     log         => $log,
     max_returns => 0,    # allow unlimited returns
     reset_limit => 3000, # reset to a suitable limit after each call using max_returns
     ars_debug   => 1,    # get a whole lot of debugging information (you real should not need)
     });

=head2 get_list

Method to return an array reference of Entry-Id values for a form.
Arguments are passed as an hash reference, with two required parameters, eg:

 # Get theEntry-Id's for all records in the 'User' form.
 my $eids = $ars->get_list({ form => 'User', query => '1 = 1' });

The query parameter can be the same format as you would use in the 'User Tool'
to query a form, however we recommend the use of field ID's (FID) rather than the
default field name as they may change.  I prefer to define a hash of the
forms lables and FID's so that can be used to better document your code, eg

 my %user = ( UserID => 101, UserName => 102 );

lib/ARS/Simple.pm view on Meta::CPAN

 $data = {
     eID1, {Label1 => value1, Label2 => value2, ...},
     eID2, {Label1 => value1, Label2 => value2, ...},
     ...
     };

=head2 update_record

Update a record on a form based on the Entry-Id (eid).  The
data to update is defined in the lvp (label value pair) hash reference.
The other required argument is the lfid (label FID) hash reference which
is used to map the labels to field Ids (FID).

The method returns true on success and carps on error.

update_record({
    eid  => $eID,           # The Entry-Id/Request-Id to update
    form => $form,          # The form to update
    lvp  => \%lvp,          # The data to be updated as a label => value hash ref
    lfid => \%labelFIDhash  # The label FID hash reference
    });

=head2 get_SQL

Run direct SQL on your server, there is only one required argument,
the sql, you may optionally set the max_returns value.

The names of the fields can be found from the Admin Tool, under
the database tab for a form.  This will be the name of the field
used in the database view of the Remedy form. B<Note> you do need
to replace spaces with and underscore '_' character.

Example method call:

 my $data = $ars->get_SQL({

lib/ARS/Simple.pm view on Meta::CPAN

     ]
 };

=head2 get_ctl

Returns the ARSystem control structure, so you can use it in other
ARSperl calls.

=head2 get_fields

get_fields has a required argument, the form you require the
field details for.  The returned hash reference is the result
of a call to ars_GetFieldTable, the keys are the field names
and the values are the field ids (fid).

=head2 set_max_entries

This requires that the 'user' has administrator access.  This
allows the overriding of the B<system wide> maximum rows returned
setting AR_SERVER_INFO_MAX_ENTRIES, setting this to zero (0) will
allow unlimited returns.

lib/ARS/Simple.pm view on Meta::CPAN

Convert a query to a qualifier structure

=head2 _check_initialised

Check to insure that there is a connection to Remedy ARSystem.
Returns true if connected.

=head2 _reset_max_entries

If set, returns the the system wide AR_SERVER_INFO_MAX_ENTRIES back
to a suitable value (eg 3000).  This required the 'user' has administrator
access

=head2 _carp

Complain if something went wrong & possible add to the log file

=head2 DESTROY

Log out from ARSystem

lib/ARS/Simple.pm view on Meta::CPAN


Add in the tools below.

Add in further methods to make life easier and your code more readable

=head1 TOOLS

B<NOT DONE YET>

The lfid array used by the get_data_by_label() method
required that a hash is defined which describes the
field lables (names) you want to use mapped to the
field ID (FID).  The encluded script will construct
such a hash for all relavent fields.  You might like
to edit this down to only those fields you really need
thereby reducing the amount of data returned.

There is a win32 version of this which copies the data
to your clipboard, to make your life easier.

=head1 AUTHOR

lib/ARS/Simple.pm view on Meta::CPAN

copy of the full license at:

L<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

t/manifest.t view on Meta::CPAN

#!perl -T
use 5.006;
use strict;
use warnings FATAL => 'all';
use Test::More;

unless ( $ENV{RELEASE_TESTING} ) {
    plan( skip_all => "Author tests not required for installation" );
}

my $min_tcm = 0.9;
eval "use Test::CheckManifest $min_tcm";
plan skip_all => "Test::CheckManifest $min_tcm required" if $@;

ok_manifest();

t/pod-coverage.t view on Meta::CPAN

#!perl -T
use 5.006;
use strict;
use warnings FATAL => 'all';
use Test::More;

# Ensure a recent version of Test::Pod::Coverage
my $min_tpc = 1.08;
eval "use Test::Pod::Coverage $min_tpc";
plan skip_all => "Test::Pod::Coverage $min_tpc required for testing POD coverage"
    if $@;

# Test::Pod::Coverage doesn't require a minimum Pod::Coverage version,
# but older versions don't recognize some common documentation styles
my $min_pc = 0.18;
eval "use Pod::Coverage $min_pc";
plan skip_all => "Pod::Coverage $min_pc required for testing POD coverage"
    if $@;

all_pod_coverage_ok();

t/pod.t view on Meta::CPAN

#!perl -T
use 5.006;
use strict;
use warnings FATAL => 'all';
use Test::More;

# Ensure a recent version of Test::Pod
my $min_tp = 1.22;
eval "use Test::Pod $min_tp";
plan skip_all => "Test::Pod $min_tp required for testing POD" if $@;

all_pod_files_ok();

( run in 0.553 second using v1.01-cache-2.11-cpan-0a6323c29d9 )