View on
MetaCPAN
Stanislav Sinyagin > SIAM > SIAM::Documentation::DataModel

Download:
SIAM-1.01.tar.gz

Annotate this POD

View/Report Bugs
Source  

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.

Each pair of objects may or may not be in contained/container relationship. Any single object may only be contained in one container.

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:

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

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:

Computables:

Attribute examples:

SIAM::Service

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

For example, a WAN connectivity service would consist of one Service object, consisting of a Service Unit object per location, and one or two Service Component objects per Unit for single and redundant physical links.

Mandatory attributes:

Attribute examples:

SIAM::ServiceUnit

Service Unit is an elementary logical entity that builds up a service. For example, for a redundant WAN connection, a Service Unit would correspond to one WAN location, and it would consist of two Service Components for each link.

A ServiceUnit consists of service options, such as access speed, hosting disk size, etc. The corresponding Service Component has 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::ServiceComponent

A Service Unit consists of one or more physical or logical components, and each component is typically associated with physical device component. For example, a WAN connection may consist of several physical links, and each link would be identified as a Service Component.

Each Service Component object represents a single management entity, such as network port on a device.

Mandatory attributes:

SIAM::Device

Device objects describe physical or virtual devices. A device is usually a single point of management, such as IP address and SNMP access credentials.

Device objects are contained in the root object.

Mandatory attributes:

Conditions:

SIAM::DeviceComponent

Device Component objects describe physical or virtual parts of a device which can be assigned to a Service Component.

Device Component objects are contained in Device objects.

Certain types of devices allow only one servcie to be associated with a device. In this case, a Device object has only one Device Component.

Mandatory attributes:

Optional attributes:

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::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::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:

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

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::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::Report

A Report object can be contained in any of other valid objects, except for another SIAM::Report. The correspondinig container should return true value for the siam.object.has_reports attribute.

A Report object does not contain any objects. The contents of the report are retrieved via the siam.report.content computable.

The SIAM driver acts as a storage for report contents, and also it defines the list of reports for particular inventory objects. An external report generation program, such as Torrus SIAM plugin, generates the reports and pushes them back to the driver by setting the corresponding conditions.

Mandatory attributes:

Additional attributes depend on the report type, and are specific to that type. The report generation program should document all relevant attributes.

The following conditions are defined for the reports. They are used by the report generation program to store the results in the driver:

The computable siam.report.content returns a JSON array that is comprised of the report items as specified in siam.report.set_items condition.

LICENSE AND COPYRIGHT ^

Copyright 2011-2013 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: