NAME

SIAM::Documentation::DataModel - SIAM data model in details

INTRODUCTION

SIAM (Service Inventory Abstraction Model) 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.

DATA MODEL

Conventions

Each object is defined by a set of attributes. Some attributes are mandatory for a particular object class.

Visibility of attributes and their values is defined by Access Scope associated with a particular client user.

Attribute names starting with the prefix siam.* are reserved solely for SIAM use.

In boolean attributes, numerical zero is interpreted as "false", and numerical nonzero is treated as "true". Usually numerical 1 indicates a true value.

Some attributes contain identifiers of other objects. The string value NIL is reserved to indicate an undefined identifier.

Attribute values are strings in UTF-8 encoding. The client software should treat UTF-8 correctly, especially where it deals with names and addresses.

Some objects may also define computables. A computable is a special attribute which requires substantial CPU time to derive its value. Computables are not retrieved automatically among other attributes, and are only delivered via explicit method calls. In case if the underlying driver does not support a particular computable, it should return an empty string.

The driver may define conditions for some objects. A condition is a (key, value) pair that the SIAM client application sends towards the driver. This is a one-way communication: there is no direct access to the condition value, and the driver is free to do anything with it or ignore it. Usually drivers update some internal state databases upin receiveing a new condition.

In this document, XYZ refers to the enterprise name.

SIAM::Object

All SIAM object classes (including the root-level SIAM class) are derived from SIAM::Object class. The following attributes are mandatory for every object:

• siam.object.id

  The attribute defines a unique identifier for the object. Client applications must not set any assumptions on the ID values or their structure. The back-end drivers generate the ID values, and these values are only meaningful within the driver data model. Maximum length: 1024 bytes. The identifiers starting with the string SIAM. are reserved to the SIAM internals and must not be used by the drivers.

• siam.object.class

  The full Perl package name of the object, such as SIAM::ServiceUnit. The back-end drivers should rely on these values in their internal logics. The drivers should be flexible enough to accept new object classes without breaking the logics.

• siam.object.complete

  The attribute should return true value when it's completely ready to use. For example, a Service Data Element object may not be ready to deliver the data because the underlying system has not yet prepared it. In this case, this attribute would return false value.

  If the driver does not deliver a value for this attribute, SIAM::Object sets it to true.

The following object IDs are predefined by SIAM and are not queried via the driver:

• SIAM.ROOT

  The root-level object.

• SIAM.SCOPE.ALL.CONTRACTS

  The access scope with the name AllContracts. All contract objects are implicitly included in it.

• SIAM.SCOPE.ALL.ATTRIBUTES

  The access scope with the name AllAttributes. All attribute names are implicitly in it.

Root object

The root object of class SIAM is the only object in the hierarchy that is not retrieved from the back-end driver. The root object has no attributes.

SIAM::Contract

The enterprise billing system would usually work with contracts. Contracts consist of services.

Mandatory attributes:

• siam.contract.inventory_id

  Contract identifier in external inventory. This should refer to the contract number as seen in the enterprise billing system.

• siam.contract.customer_name

  String identifying the contract holder name

• siam.contract.last_modified

  UNIX timestamp of last change in any contract details. This attribute may be set to zero if the underlying system is unable to deliver the last modification time.

Computables:

• siam.contract.content_md5hash

  Returns a hex string representing the MD5 hash of all the objects related to this contract. The client application may use this value as an indicator if it has to refresh its internal cache.

Attribute examples:

• xyz.is_suspended, xyz.billing_ok, xyz.reseller_id

  These define the internal logic which is specific to particular SIAM use.

SIAM::Service

A Service is a billing unit within the enterprise. It consists of Service Units.

Mandatory attributes:

• siam.svc.procuct_name

  A name from the enterprise's product catalog.

• siam.svc.type

  A string from a limited dictionary of predefined service types. It refers to a service template which identifies the attributes which are required for each service type.

• siam.svc.inventory_id

  Service ID in external inventory, such as the billing system.

SIAM::ServiceUnit

Service Unit is an elementary physical or logical entity comprising a service. For example, a WAN connection may consist of several physical links, and each link would be identified as a Unit.

In many SP environments each Service would only consist of one Unit. This assignment depends on the internal SP service definitions.

A ServiceUnit consists of Service Options, such as access speed, hosting disk size, etc, and Implementation Attributes, such as link identifier, access port, rack number, etc.

Service Options are usually visible to the customer and are defined in their contract.

Implementation Attributes are internal Service Provider's properties that document the technical details of the installation.

Mandatory attributes:

• siam.svcunit.name

  Service Unit name as displayed to the user.

• siam.svcunit.type

  A string from a limited dictionary of predefined service unit types. It refers to a service template which identifies the attributes which are required for each unit type.

• siam.svcunit.inventory_id

  Service Unit ID in external inventory. If it's a strict one-to-one relation between Services and their Units, this attribute is equal to siam.svc.inventory_id.

• siam.svcunit.device_id

  Identifier of an associated SIAM::Device object or NIL.

• siam.svcunit.location

  Free-form location string for the point of service hand-over.

Attribute examples:

• access.speed.downstream, vm.ram.size

  Examples of Service Options.

• access.port.name, rack.number

  Examples of Implementation Attributes.

SIAM::ServiceDataElement

Service Units define the physical entities, whereas Data Elements refer to associated data, such as statistics.

Each instance of a Service Unit is usually associated with several data elements. For example, a physical link is associated with TrafficStats, ErrorStats, MonthlyUsage.

Each Data Element represents a connection to some back-end system that actually delivers the data. SIAM provides all attributes necessary for accessing the data. It is up to the client application to retrieve the data from the back-end system.

Mandatory attributes:

• siam.svcdata.name

  Data Element name as displayed to the user. SIAM clients should only use it for displaying, and should not build any logic on its value.

• siam.svcdata.type

  A string from a limited dictionary. SIAM clients may build the data representation based on the value of this attribute. Example: “TrafficStats”.

• siam.svcdata.driver_class

  Name of the data driver. Examples: Torrus::SIAM::TimeSeries, Torrus::SIAM::MonthlyUsage

Attribute examples:

• torrus.tree-url, torrus.nodeid

  Example of a reference to a Torrus data element.

• monthly_usage.dsn, monthly_usage.username, monthly_usage.password, monthly_usage.svcid

  Example of a reference to Torrus monthly traffic statistics, such as 95th Percentile bandwidth utilization.

• vmstats.dsn, vmstats.username, vmstats.password, vmstats.vm_server, vmstats.vm_entity, ...

  Example of a reference to VmWare server statistics in an SQL database.

SIAM::Device

Device objects describe the physical or virtual devices which are associated with Service Units. One Unit can be associated with zero or one Device.

Device objects are contained in the root object.

Mandatory attributes:

• siam.device.inventory_id

  Reference to the device identifier in an external inventory system. This may or may not be the same as hostname.

Attribute examples:

• snmp.managed, snmp.host, snmp.version, snmp.community, ...

  Attributes that define SNMP access to the device.

• asset.owner

  Attribute that allows to distinguish between ISP's own and foreign devices.

SIAM::AccessScope

Access Scope determines the subset of contracts and other objects that are visible to particular users. The default security model provides the means for limiting access to Contracts and individual attribute names.

Two scope names are reserved, and corresponding objects always belong to them: AllContracts, AllAttributes.

Access Scope objects are contained within the root SIAM object. Each Access Scope object contains one or more Scope Member objects.

Mandatory attributes:

• siam.scope.name

  Unique name of Access Scope. It has usually a mnemonic value, such as AllContracts, Contract.123456, Wholesale.654321.

• siam.scope.applies_to

  Class of objects that this scope covers. Known values: SIAM::Contract, SIAM::Attribute.

SIAM::ScopeMember

Scope Member object points to the object at which the corresponding privileges apply.

Scope Members are contained within Access Scope objects.

Mandatory attribute:

• siam.scmember.object_id

  ID of a corresponding Contract or Attribute object which comprises the given Scope.

SIAM::User

User is usually associated with a physical person that accesses the system. SIAM is not responsible for authenticating the users, although it may carry the information required for authentication.

User objects may contain any of the RFC4519 (LDAP User Schema) attributes. It depends on the local interpretation which of them are available, and also the meaning of these attributes.

User objects are contained within the root SIAM object.

Mandatory attributes:

• siam.user.uid

  Unique user ID that is known through some authentication mechanism.

Optional attributes which may be supported by the driver and the front-end application:

• user.cn

  Common Name attribute in an LDAP database.

• user.auth.method

  One of two values are expected: inline, ldap

• user.auth.password

  If method is set to "inline", this attributes delivers the password as specified in LDAP standards. Example: {SHA}NWE5MDg0MWU0ODY3Y2VjMTQ2NzU0NjNhOWEzZDFmMjI4MTFiZDQ2YnNhbHQ=

• user.ldap.host

  LDAP hostname or URL

• user.ldap.binddn

  Bind DN

SIAM::Privilege

Privilege is a binding object between Users and Access Scopes. The relation between users and their privileges is maintained by enterprise-specific SIAM drivers, and may be based, for example, on LDAP group membership.

Privilege objects are contained in SIAM::User objects.

Mandatory attributes:

• siam.privilege.access_scope_id

  Reference to the corresponding SIAM::AccessScope object ID.

• siam.privilege.type

  String from a limited dictionary of known privilege types. Examples: ViewContract, ViewAttribute, SuspendContract

SIAM::Attribute

Attribute objects are only used for their relation to Access Scopes. This relation is usually static and stored directly in SIAM configuration.

For example, some Implementation Attributes, such as access.port.name, rack.number, would be associated with the scope ImplementarionAttributes, and only the ISP personnel users would be able to see their values.

SIAM::Attribute objects are contained within the root object.

Mandatory attributes:

• siam.attribute.name

  Name of the attribute.

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.

cpanm SIAM

perl -MCPAN -e shell
install SIAM