/ 
SIAM-0.04
River stage zero No dependents
/ SIAM

NAME

SIAM - Service Inventory Abstraction Model

VERSION

Version 0.04

SYNOPSIS

use SIAM;

# Example SIAM configuration. You would normally load it
# from a YAML file instead of inline Perl
my $config = {
  'Driver' => {
    'Class' => 'XYZ::SIAM::Driver',
    'Options' => {
      'dblink' => {
        'dsn' => 'DBI:mysql:database=xyz_inventory;host=dbhost',
        'username' => 'siam',
        'password' => 'Lu9iifoo',
      },
      'logger' => {
        'screen' => {
          'log_to'   => 'STDERR',
          'maxlevel' => 'warning',
          'minlevel' => 'emergency',
      },
    },
  },
  'Root' => {
    'Attributes' => {
      'siam.enterprise_name' => 'XYZ Inc.',
      'siam.enterprise_url' => 'http://www.example.com',
      'siam.enterprise_logo_url' => 'http://www.example.com/l.png',
    },
  },
};

my $siam = new SIAM($config) or die('Failed loading SIAM');
$siam->connect() or die('Failed connecting to SIAM');

# The monitoring system would normally need all the contracts.
# Walk down the hierarchy and retrieve the data for the
# monitoring software configuration

my $all_contracts = $siam->get_all_contracts();
foreach my $contract (@{$all_contracts}) {
  my $services = $contract->get_services();
  foreach my $service (@{$services}) {
    my $units = $service->get_service_units();
    foreach my $unit (@{$units}) {
      # some useful attributes for the physical unit
      my $host = $unit->attr('access.node.name');
      my $port = $unit->attr('access.port.name');

      # statistics associated with the service unit
      my $dataelements = $unit->get_data_elements();
      foreach my $element (@{$dataelements}) {
        # do something with the element attributes            
      }
    }
  }
}
                                 
# The front-end system deals with privileges
my $user = $siam->get_user($uid) or return([0, 'User not found']);

# All the contracts this user is allowed to see
my $contracts =
  $siam->get_contracts_by_user_privilege($user, 'ViewContract');

# ... walk down the hierarchy as shown above ...

# Prepare the unit attributes for display
my $attrs =
  $siam->filter_visible_attributes($user, $unit->attributes());
    
# Random access to an object
my $el =
  $siam->instantiate_object('SIAM::ServiceDataElement', $id);

# Check privileges on a contract
if( $user->has_privilege('ViewContract', $contract) ) {
  ...
}

# close the database connections
$siam->disconnect()

INTRODUCTION

Many Service Provider companies (ISP, Hosting, Carriers, ...) have their own, historically developed, databases for customer service inventory. Therefore any system that would require access to such data should be adapted to the local environment.

SIAM is intended as a common API that would connect to enterprise-specific service inventory systems and present the inventory data in a uniform format. The purpose of this universal API is to reduce the integration costs for such software systems as network monitoring, CRM, Customer self-service portals, etc.

We assume that monitoring systems (such as: Torrus, ...) and front-end systems (such as: Customer portal, Extopus, ...) would connect to SIAM to retrieve any service-specific information, and SIAM would deliver a complete set of data required for those client applications.

SIAM does not include any database of its own: all data is retrieved directly from the enterprise systems and databases. The SIAM library communicates with the enterprise-specific driver and presents the data in an abstracted way.

SIAM takes its configuration data from a single hierarchical data structure. This data is usually read from a YAML file. The configuration describes all data connections, driver configuration, enterprise-specific modules, etc.

The SIAM core modules are distributed as an open-source Perl package available at CPAN. Enterprise-specific modules are integrated in a way that the core can be upgraded without breaking any local setup.

METHODS

new

Expects a hashref with SIAM configuration.

Configuration

  • Driver

    A hash with two entries: Class identifying the driver module class which is going to be require'd; and Options, a hash which is supplied to the driver's new method.

  • Root

    A hash that sets properties for the root object. The key Attributes is expected, pointing to the following mandatory attributes:

    • siam.enterprise_name

    • siam.enterprise_url

    • siam.enterprise_logo_url

connect

Connects the driver to its databases. Returns false in case of problems.

disconnect

Disconnects the driver from its underlying databases.

get_user

Expects a UID string as an argument. Returns a SIAM::User object or undef.

get_all_contracts

Returns an arrayref with all available SIAM::Contract objects.

get_contracts_by_user_privilege

my $user_contracts =
    $siam->get_contracts_by_user_privilege($user, 'ViewContract');

Arguments: SIAM::User object and a privilege string. Returns arrayref with all available SIAM::Contract objects that match the privilege.

filter_visible_attributes

my $visible_attrs =
    $siam->filter_visible_attributes($user, $object_attrs);

Arguments: SIAM::User object and a hashref with object attributes. Returns a new hashref with copies of attributes which are allowed to be shown to the user as specified by ViewAttribute privileges.

SEE ALSO

SIAM::Documentation::DataModel, SIAM::Documentation::DriverSpec

AUTHOR

Stanislav Sinyagin, <ssinyagin at k-open.com>

BUGS

Please report any bugs or feature requests to bug-siam at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=SIAM. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc SIAM

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2011 Stanislav Sinyagin.

This program is distributed under the MIT (X11) License: http://www.opensource.org/licenses/mit-license.php

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.