The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
SIAM-1.01
River stage zero No dependents
++
/ SIAM

NAME

SIAM - Service Inventory Abstraction Model

SYNOPSIS

  use SIAM;

  # Example of a SIAM configuration in a YAML file
  ---
  Driver:
    Class: XYZ::SIAM::Driver
    Options:
      Dblink:
        dsn: "DBI:mysql:database=xyz_inventory;host=dbhost"
        username: siam
        password: Lu9iifoo
  Client:
    Frontend:
      enterprise.name: XYZ, Inc.
      enterprise.url: http://example.com
      enterprise.logo: http://example.com/logo.png


  # Load the configuration from a YAML file
  use YAML;
  my $siamcfg = eval { YAML::LoadFile($filename) };
  if( $@ ){
    die("Cannot load YAML data from $filename : $@"); 
  }

  # Specify your own logger object instead of the standard Log::Handler
  $siamcfg->{'Logger'} = $logger;

  my $siam = new SIAM($siamcfg) 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}) {
    next unless $contract->is_complete();
    my $services = $contract->get_services();
    foreach my $service (@{$services}) {
      next unless $service->is_complete();
      my $units = $service->get_service_units();
      foreach my $unit (@{$units}) {
        next unless $unit->is_complete();

        # statistics associated with the service unit
        my $components = $unit->get_components();
        foreach my $c (@{$components}) {
          next unless $c->is_complete();

          # some useful attributes for the physical unit
          my $host = $c->attr('access.node.name');
          my $port = $c->attr('access.port.name');

          # 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::ServiceComponent', $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. Normally the calling application would load the driver configuration from some data file (YAML or JSON), and optionally supply its own logger object.

The following entries are supported in the configuration:

  • Driver

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

  • Logger

    Optional object reference that is to be used for all logging inside SIAM and in the driver. The default logger is an instance of Log::Handler with STDERR output of warnings and errors. The logger object must implement the following methods: debug, info, warn, and error.

  • Client

    Optional hash that defines some configuration information for SIAM clients. The keys define categories, and values point to configuration hashes within each category.

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.

get_all_devices

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

get_device

Takes the device inventory ID and returns an SIAM::Device object.

get_client_config

Takes the category name and returns a hashref with Client configuration for the specified category. Returns an empty hashref if the configuration is not available.

manifest_attributes

The method returns an arrayref with all known attrubute names that are supported by SIAM internal modules and the driver.

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.