view release on metacpan or  search on metacpan

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

{
    my $self = shift;
    my $msg = join('', @_);

    carp $msg;
    $self->{log}->exp($msg) if ($self->{log});
}

sub _init
{
    my ($self, $args) = @_;

    # Did we have any of the persistant variables passed
    my $k = '5Jv@sI9^bl@D*j5H3@:7g4H[2]d%Ks314aNuGeX;';
    if ($args->{user})
    {
        $self->{persistant}{user} = $args->{user};
    }
    else
    {
        if (defined $config{user})
        {
            my $s = pack('H*', $config{user});
            my $x = substr($k, 0, length($s));
            my $u = $s ^ $x;
            $self->{persistant}{user} = $u;
        }
        else
        {
            croak "No user defined, quitting\n";
        }
    }

    if ($args->{password})
    {
        $self->{persistant}{password} = $args->{password};
    }
    else
    {
        if (defined $config{password})
        {
            my $s = pack('H*', $config{password});
            my $x = substr($k, 0, length($s));
            my $u = $s ^ $x;
            $self->{persistant}{password} = $u;
        }
        else
        {
            croak "No password defined, quitting\n";
        }
    }
    $user  = $self->{persistant}{user};
    $pword = $self->{persistant}{password};

    # Handle the other passed arguments
    $self->{server}      = $args->{server}      if $args->{server};
    $self->{log}         = $args->{log}         if $args->{log};
    $self->{max_returns} = $args->{max_returns} if defined $args->{max_returns};
    $self->{reset_limit} = $args->{reset_limit} if defined $args->{reset_limit};

    if ($args->{ars_debug})
    {
        $ARS::DEBUGGING = 1;
    }
    $self->{debug} = $args->{debug} ? 1 : 0;

    ## Now connect to Remedy
    if ($self->{server} && $user && $pword)
    {
        my $ctl = ars_Login($self->{server}, $user, $pword);
        if ($ctl)
        {
            $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);


1; # End of ARS::Simple


__END__

=head1 NAME

ARS::Simple - A simplified interface to Remedy ARSystem

=head1 SYNOPSIS

A simple interface to Remedy ARSystem utilising the ARSperl API interface.
Keeps your code more readable and by use of the cache avoids your credentials
being spread through all your scripts.

 use ARS::Simple;

 my $ar = ARS::Simple->new({
     server   => 'my_remedy_server',
     user     => 'admin',
     password => 'admin',
     });

 ### Get the Entry-ID/Request-ID for all User's with Login starting with 'g'
 # Here $eid is any array reference of entry-id/request-id values
 my $data = $ar->get_list({
     form  => 'User',
     query => qq{'Login' LIKE "g%"},
     });
 print Data::Dumper->Dump([$data], ['data']), "\n";
 # Resulting data dump:
 # $data = {
 #   'eids' => [

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

There are a number of optional arguments, they are:

=over 4

=item max_returns

Set a limit on how many items may be returned from certain calls.
Setting this value to 0 sets unlimited returns.  This parameter
can also be set on individual calls. B<Note:> This is a system wide
configuration change and requires administrator privilages on user.

B<Note: You should not use a value less than the default system value
for this field or you may impact normal operation of your system>

Example usage:

 reset_limit => 0, # unlimited returns

=item reset_limit

Once max_returns is used, reset_limit, if set will return the server
to nominated max_returns limit (eg 3000), thereby limiting the possible
impact on the system of having max_returns set to a high value (eg 0).

Example usage:

 reset_limit => 3000, # max returns back to a suitable maximum of 3000

=item ars_debug

Turn on, if true (1), the ARSperl debugging output.
Not something you would normally use.

=item log

Pass a object to use to log erros/information to a log file.
The log object is expected to have methods I<exp> and I<msg>
as per the File::Log object.

=back

Sample invocation with ALL parameters:

 use ARS::Simple;
 use File::Log;
 my $log = File::Log->new();
 my $ars = ARS::Simple->new({
     server      => 'my_server',
     user        => 'some_admin',
     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 );

the a query could be something like

 my $query = qq{ '$user{UserID}' LIKE "g%" };
 my $eids = $ars->get_list({ form => 'User', query => $query });

=head2 get_data_by_label

Query a form and get the data back as a hash reference where the
keys are the Entry-Id's for the records matched by the query and
the value is a hash reference to the fields you requested where
the keys are the field names you used and the value are the values.

 my $form  = 'form';
 my $query = qq('FID' = "value");
 my $data = $ar->get_data_by_label({
     form  => $form,
     query => $query,
     lfid  => { label1, fid1, label2, fid2, ...},
     });

 $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