Stanislav Sinyagin > SIAM-0.10 > SIAM

Download:
SIAM-0.10.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.10   Source   Latest Release: SIAM-1.01

NAME ^

SIAM - Service Inventory Abstraction Model

VERSION ^

Version 0.10

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();
        # 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}) {
          next unless $element->is_complete();
          # 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. 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:

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.

syntax highlighting: