view release on metacpan or  search on metacpan

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

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

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({
     sql => q{select Login_name, Full_Name from User_X where Login_name like 'g%' order by Login_name},
     max_returns => 0,
     });

The return is a hash reference with two keys, numMatches and rows, example:

 $data = {
     numMatches = > 2,
     rows => [
        'greg', 'Greg George',
        'geoff', 'Geoffery Wallace',
     ]
 };

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

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

=head1 PRIVATE METHODS

=head2 _init

Initialisation for new and handling of cache

=head2 _load_qualifier