view release on metacpan or  search on metacpan

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

sub _reset_max_entries
{
    my $self = shift;

    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;
}

sub update_record
{
    my ($self, $args) = @_;
    my $eID  = $args->{eid};
    my $form = $args->{form};
    my %lvp  = %{$args->{lvp}};


    # Map lvp to use FID rather than label
    foreach my $label (keys %lvp)
    {
        if (defined $args->{lvp}{$label})
        {
            $lvp{$args->{lfid}{$label}} = $lvp{$label};
            delete $lvp{$label};
        }
        else
        {
            carp("update_record - label '$label' not found in lfid hash");
        }
    }


    my $rv = ars_SetEntry($self->{ctl}, $form, $eID, 0, %lvp);

    # Check for errors
    unless (defined $rv && $rv == 1)
    {
        # Update failed
        my $msg = "update_record(eid=$eID, form=$form, ...) failed:\nars_errstr=$ars_errstr\nlvp data was:\n";
        foreach my $label (sort keys %{$args->{lvp}})
        {
            $msg .= sprintf("%30s (%10d) ---> %s\n", $label, $args->{lfid}{$label}, defined($lvp{$args->{lfid}{$label}}) ? $lvp{$args->{lfid}{$label}} : '<undefined>');
        }
        carp($msg);
    }
    return $rv;
}

sub get_ctl
{
    my $self = shift;

    return $self->{ctl};
}

sub _carp
{
    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' => [
 #     '000000000004467',
 #     '000000000004469',
 #     '000000000004470',
 #   ],
 #   'numMatches' => 3
 #};

 ### Get data from a form, based on a query (as you would use in the User Tool)
 my $form  = 'User';
 my $entryListLabel = $ar->get_data_by_label({
     form  => $form,
     query => qq{'Login Name' LIKE "ge%"},  # Login Name = FID 101
     lfid  => { 'LoginName', 101, 'FullName', 8, 'LicenseType', 109, },
     });
 print Data::Dumper->Dump([$entryListLabel], ['entryListLabel']), "\n";
 # Resulting data dump:
 # $entryListLabel = {
 #  '000000000014467' => {
 #    'FullName' => 'Geoff Batty',
 #    'LicenseType' => 0,
 #    'LoginName' => 'gbatty'
 #  },
 #  '000000000014469' => {
 #    'FullName' => 'Greg George',
 #    'LicenseType' => 2,
 #    'LoginName' => 'gregg'
 #  },
 #  '000000000024470' => {
 #    'FullName' => 'Gabrielle Gustoff',
 #    'LicenseType' => 0,
 #    'LoginName' => 'ggustoff'
 #  },

 # Update a record, change the Login Name to 'greg'
 my %lvp = ( LoginName => 'greg' );
 $ar->update_record({
     eid  => '000000000014469',
     form => 'User',
     lvp  => \%lvp,
     lfid => { 'LoginName', 101, 'FullName', 8, 'LicenseType', 109, },
     });

=head1 VERSION

Version 0.01

=head2 FEATURES

=over 4

=item *

Provides obfuscated storage for default user and password so they are
not scattered throuhout all your scripts

=item *

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.