NAME
StoredHash::ARS - Remedy/ARS adapter for StoredHash
DESCRIPTION
StoredHash::ARS allows the normal persistence methods of StoredHash to be used with Remedy ARS database backend (with few exceptions where certain method would not make sense).
ARS is much more constrained about DB side conventions than traditional relational databases. ID numbering is always automatic and primary key is always field called (actually numbered as ARS uses numbers for attribute names) '1'.
To learn to use StoredHash::ARS, read "perldoc StoredHash". The documentation here focuses only on ARS / Remedy specific quirks.
NOTE: This module is still experimental.
SYNOPSIS
use StoredHash::ARS;
use ARS;
# ARS Connection
my $ctrl = ars_Login($ENV{'ARS_SERVER'}, $ENV{'ARS_USER'}, $ENV{'ARS_PASS'});
# StoredHash persister configuration ('pkey' intentionally missing for ARS)
my $shpc = {'table' => 'HPD::Helpdesk', 'dbh' => $ctrl, 'debug' => 0};
my $shp = StoredHash::ARS->new(%$shpc);
# Load
my hdent = $shp->load(['HD...']);
# Insert, Update, Delete ... as usual
METHODS
Method documentation focuses only on ASR specific differences. Be sure to read StoredHash documentation for an overview.
General notes:
The hash to store must be keyed by Remedy field numbers (not descriptibve names ...)
On update, delete ... ops that require entry id to be passed, use the value assigned to Remedy field '1' (reserved for id of an entry by Remedy conventions).
StoredHash basic / DBI backend will tolerate calling methods via persister that does not have the connection ('dbh') set. StoredHash::ARS will not.
Because of no composite keys in ARS, the StoredHash::ARS persistnce methods will tolarate a loose / forging way of passing id:s as plain scalars, with "wrapping" array being optional. However using array(ref) is still the recommended, future-proof way of passing the id.
Remedy schemas usually host a huge amount of attributes. For this reason you should focus on using parameter 'attrs' in your persistence operations for optimal performance.
StoredHash::ARS->new(%opts)
StoredHash::ARS constructor. Notes on keyword parameters (in %opts).
'dbh' - The connection passed should be ARS Connection (use ARS API idiomatic handle $ctrl as value).
'table' - use ARS Schema name (e.g. 'table' => 'HPD:HelpDesk')
Because Remedy always uses the same numeric name for primary key and auto-allocates id, the parameters 'pkeys' and 'autoid' are not relevant for Remedy.
$shp->insert($e);
Insert an entry into ARS database. Pass ARS Entry instance ($e) with NUMERIC Field IDs (i.e. not descriptive field names).
$e = {'240000005' => 'mrjohnsmith', '260000002' => 'mrjohnsmith@corp.com'};
my $eid = $sp->insert($e);Return Remedy entry ID for the new entry (usable in further persistence ops).
$shp->update($e, [$eid], %opts)
Update entry in ARS database schema. Keyword params in %opts:
'attrs' - Allow only a subset of attributes from entry ($e) to be updated.
$shp->delete([$eid])
Delete an Entry by id ($eid) permanently from ARS database.
Return true value for successesful deletion.
$shp->exists([$eid])
Test presence of entry by ID ($eid) in ARS database. Return true for present in DB, false for not present.
$shp->load([$eid], %opts)
Load an entry from Remedy database schema by its id ($eid). Keyword params in %opts:
'attrs' - Load only attributes listed (arrayref, pass numeric field IDs)
$shp->loadset($filter, $sortby, %opts)
Keyword parameters (in %opts):
'attrs' - if set to true scalar value, the entries are fetched brute force with all entry attributes (in Remedy this usually is a LOT of data).
$shp->cols()
Query columns for ARS Schema (given by persister internal field 'table' passed at construction time). Return numeric fieldnames sorted alphabetically (as ARS does not have deterministic order for fields).