Introduction

This documentation applies to version 2.1.1

Kuwaiba sees an inventory system as a living entity, not growing only in terms of size, but also in structure and intelligence. The main reason being that business requirements change constantly and therefore, the application must be ready to respond to new scenarios. One of the key concepts that can help you unlock the potential of Kuwaiba is the data model. It provides a simplified representation of the network and the business from an operational point of view. It can be seen as the skeleton that supports the application, but a skeleton from which you can add, remove and change elements as you go. Later in this document you will be able to see what tools you can use to manage it. For now, just keep in mind that the better you design your data model and the more you get to know it, the more you will take advantage of the application.

Having said that, you will find four types of resources in a typical data model:

• Physical: Equipment, pipes, cables, fiber optics, facilities, parts and in general every physical asset from a port to a building.

• Logical: These are all the resources related to non-tangible technology assets. In this group fit timeslots, virtual circuits, VLANs, disk space, available bandwidth, etc. Other Non-physical: mostly software-related assets, such as licenses or virtual machines.

• Administrative: These are all those related to administrative tasks, human resources or commercial management. Customers, their services SLAs (and related parameters like availability or throughput), sales and technical staff assigned to those services, vendors and states belong to this category.

The Kuwaiba web client is a set of views (trees, topologies, editors) that allows to put together these elements based on business rules and user-defined models. Kuwaiba extends the concept of CMDB (Configuration Management Database, a place where you store objects that can hold configuration information or be subject to configuration themselves - so called Configuration Items- and their relationships) and enables you to perform network design tasks, support capacity management and provisioning workflows and assist field and customer service teams to improve response times.

Kuwaiba helps you model your network according to your needs, no matter if you’re an ISP, a carrier or just a guy with a large (or small!) IT infrastructure to manage. It’s open source, under active development and new models are added every release. You can contribute to the project by providing technical insight on a particular technology, testing, translating or just sending your feedback through forums¹ and mailing lists².

Getting Started

The login is the first view you have of the system Figure 1.

Figure 1. Login

Information Use the user admin and password kuwaiba.

Once the login is done, the system will be redirected to home Figure 2.

Figure 2. Home

1. It shows the company logo¹ and is also used to return to home.
2. Menu Items.
3. Shows Kuwaiba information such as version, licenses, etc.
4. Show user information and logout.
5. Home dashboard² shows a map with all the GenericLocation that has a geographic location set.

Menu Items

In kuwaiba, a module defines or groups system features, and the modules are grouped into categories.

Icon	Category	Description
	Administration	Modules to manage the data model.
	Navigation	Modules that are used to explore, navigate and search inventory assets.
	Physical	Modules that allow to manipulate L1 assets, such as physical connections and outside plant infrastructure.
	Logical	Modules to manipulate L2/L3 assets, like MPLS, SDH, IP, ISDN, etc.
	Services	Modules to manage administrative aspects of the inventory such as services (as in billed services), customers, contracts. etc.
	Planning	Modules dedicated to network planning.
	Other	General system settings such as validators and configuration variables.
	Settings	Any module not fitting the categories above.

Essential Modules

The recommended order to start exploring the inventory system is shown in Figure 3, follow the links to get started.

Figure 3. Essential modules

1. Data Model Manager.
2. List Type Manager.
3. Containment Manager.
4. Navigation.
5. Template Manager.

Note Depending on the restrictions that the system administrator has defined for the users in the User Manager, the options in each menu will change.

Data Model Manager

Kuwaiba is a powerful modeling tool (understanding a model as a simplified representation of the real world, in this case a telecommunications network and all its business aspects). One of the key features of Kuwaiba is its completely object-oriented dynamic data model. Each inventory asset (router, city, port) is called an Object, and these objects are in turn, a product of an abstraction of reality called Class.

Likewise, each attribute is a Field in a class. The set of classes, attributes and relationships between them is called Data Model. Kuwaiba comes with a default data model that contains support for the most popular technologies and business models, but you can customize it depending on your needs by adding, removing, and modifying classes. To achieve this, use the Data Model Manager module.

To open the Data Model Manager module, select Administration -> Data Model Manager from the options menu.

Figure 1. Data Model Manager module selection in the general menu

The Class Tree

Kuwaiba's data model has a tree-like structure due to its hierarchical nature. Technically, this is known as a class hierarchy. At the top of this hierarchy is InventoryObject, the most general item type in the data model, its highest level of abstraction. Its subclasses represent all possible items that will be considered inventory assets.

Figure 2. Inventory object tree

As you go deeper into the tree, classes become increasingly specialized and each level inherits the attributes of the classes above it (called superclasses). This structure serves two main purposes: first, it helps organize classes based on their common characteristics. Second, as will be seen later in this manual, it allows operations to be applied to top-level classes, which will be propagated to all subclasses.

Figure 3. Expanded class tree

In this hierarchy, the most relevant and commonly used classes are:

• InventoryObject: It is the root of the hierarchy.
• ViewableObject: This is the superclass of all objects that can have views, that is, graphical representations of a selected object that can be launched from the Views section of the object panel (the concept will be explained later, in the Navigation module).
• GenericCommunicationsElement: The superclass of all active communication devices, from multiplexers to routers or servers and workstations.
• GenericLocation: The superclass of all geolocated locations such as buildings, facilities, houses, poles or manholes.
• GenericPhysicalLink: It is the superclass of links (connections between ports) and allows subclasses to be created to expand the type of existing connections.
• GenericSplicingDevice: This is the superclass of objects used for splicing operations, such as splice boxes and fiber splitters.
• GenericDistributionFrame: It is the superclass of distribution frames, such as DDFs, ODFs or even AC/DC distribution panels.

Creating a New Class

When selecting an item from the Class Tree, on the right side you can see two tabs. This section also allows you to Create a New Class that inherits from the selected class, through the action of the button , which will launch the following dialog . In this example, GenericCommunicationsElement has been selected in the Class Tree.

Figure 5. Creating a new class

The tabs that can be seen are:

• Properties: The Properties window contains the intrinsic properties of the class, such as name, description, etc. These can contain any type of UTF-8 character without special characters or whitespace. In addition, it allows you to assign a specific icon that will be displayed in the inventory for said object. If the class is abstract (instances of abstract classes cannot be created, they are only used to provide consistency to the data model). The countable attribute is not currently used, but should be used to mark classes whose instances may have graphical representations, but are not actually part of the inventory, such as Slots. inDesign is just a way to mark a class as part of an ongoing data model intervention, and therefore classes with that attribute marked true cannot be instantiated. The color is the color of the default square icon used to display the object in a tree or view. This icon will be used whenever the smallIcon attribute is null. smallIcon is the icon that will be used on the trees and its size cannot exceed 16x16 pixels. icon is the icon used in views and has a maximum size of 32x32 pixels. The breadcrumbs on top of the Properties tab allow you to explore the class hierarchy for the selected class.

  Figure 6. Properties of the selected object

  Important

  • All user-created classes have inDesign status set to true by default. Objects cannot be created from these classes until they are changed to false. This is a preventive measure to facilitate testing of changes when creating multiple classes before moving to production.
  • As a convention, all abstract classes are prefixed with Generic. However, some core classes (such as InventoryObject or AdministratorItem) are abstract and do not follow this convention. It is recommended to adhere to this rule whenever possible. Unless you have deep knowledge of the system, avoid renaming or deleting parent classes, especially abstract ones.
  • To name the classes and attributes, we follow the camel case convention. For class names, the first letter is capitalized, as in MyNewClass. On the other hand, for attributes, the first letter is written in lowercase, as in myNewAttribute. This practice helps improve the readability of the code and maintain a consistent structure in the naming of elements within our program.

• Class Attributes: This section contains the class fields (attributes). In the figure below, the GenericCommunicationsElement class includes common attributes, such as creationDate and name, as well as other attributes specific to the selected class.

  Figure 7. Attributes of the selected class

  Click the button next to the attribute name to customize it as shown in the figure below.

  Figure 8. Properties of the selected attribute

  In this window, you can modify both common and specific class attributes. The most relevant common attributes are:

  • name: Change the name of the attribute.
  • displayName: Change how the name is displayed.
  • description: Provide a description for the attribute.
  • type: Select the type of the attribute (the drop-down list will show primitive types such as String, Integer, Float, Long, etc., and all available non-abstract list types). When the type of an attribute changes, all existing instances will be updated to reflect the change. This means that the values ​​of the modified attribute will be converted to the new type if possible (for example, from integers to strings). If the conversion is not possible, the new value will be set to null.

  You can also manage the following options for the attribute:

  • mandatory: If you select this option, each object of this class must have a value for this attribute. If you enable this option and there are already created objects of this class without a non-null value for this attribute, an error will occur.
  • unique: If checked, the value of this attribute cannot be repeated in all objects created of this class or its subclasses. Before you can set a class attribute as unique, you must verify that the value of this attribute on each object created from this class or its subclasses is unique.
  • isVisible: Enables or disables the visibility of the attribute. If unchecked, the attribute will not be displayed in the property sheets of objects created from this class.
  • administrative: Attributes marked "Administrative" will be displayed in a separate tab on the object's property sheet. This is useful for attributes that are used only for administrative purposes and that could confuse the end user if mixed with normal attributes.
  • noCopy: You can choose which attributes should not be transferred from one object to another in a copy operation.
  • order: Refers to the order in which this attribute will appear in the property sheet.

  Important

  • You may lose information when changing the type of an attribute. Make sure that conversion to the new type is possible before making the change.
  • If attributes are added, removed, or renamed, the changes will only be reflected in the property sheets of previously opened inventory items once the page displaying the item is reloaded.
  • It is strongly recommended to not rename core abstract classes, as some of them are used internally to support many functions. Renaming them can destabilize the system.

  You can also create and delete attributes by clicking the corresponding buttons. When creating a new attribute, a dialog box like the one shown below will be displayed, where the attributes name, displayName and type will be requested.

  Figure 9. New attribute of the selected class

List Types

List types are attribute type whose value is an element within a list of items. Unlike most attributes, which are of primitive types such as String, Integer or Boolean, some are more complex, being separate objects in the database. For example the value of the attribute vendor in a device, can only be chosen from a predefined list of options (Huawei, Cisco, Nokia, etc), and each one of those entries contains more information (support lines, account managers, etc). Another example is state, which describes the current operational state of a given device (Working, Not Working, Stored, Planned, Reserved, etc). The state itself is an object since and can contain information about the next allowed states or about itself.

Many objects in the database will share the same provider, just as many others will share the same state. In relational database terms, this can be thought of as a many-to-one relationship.

Please note that this section shows how to create attribute types of the list kind, not their lists themselves, for that see the List Type Manager.

Figure 10. Class hierarchy for list types

Creating a List Type

List types are subclasses of GenericObjectList or one of its utility subclasses. In most cases, your new list types will fit into one of the existing branches, so avoid creating abstract subclasses unless you know very well what you are doing, so you don't pollute the data model unnecessarily. List type creation works exactly like for any other class seen in the past sections. Just make sure you uncheck the inDesign option once you are ready to create list type items in the List Type Manager.

Figure 11. Creating new list type

Using a List Type

Once the new list type is created, you can tell other classes to use it by creating attributes of the new type. In the example below, we are making the class Router to have a new attribute called newListTypeAttribute of type FancyNewType.

Figure 12. Using the new list type

Now our routers will have a new list type attribute whose value can be chosen from a list created in the List Type Manager

Important

List types support single or multiple selection. You will learn more about it in the List Type Manager.

List Type Manager

Most of the attributes are primitive types (String, Integer, Booleans, etc), however, there are some more complex that are actually another object in the database. This is the case of attributes such as vendor, which points to an object holding the information about the vendor of that equipment (support lines, account manager, etc) or state, that refers to the current operational state of the equipment (Working, Not Working, Stored, etc) and the state itself is an object, because it may hold information about what are the next allowed states.

Many objects in the database will have the same vendor, and many other will have the same state. In short, list types are those kind of attributes that point to an element in a limited set of objects. In terms of relational databases, you can see it as a many-to-one kind of relationship.

To manage the existing list types and its instances, use the Data Model Manager and the List Type Manager.

To access the module, click on the administration category and select the List Type Manager Figure 1.

Figure 1. List Type Manager Module

There are two relevant concepts in this module List Type and List Type Item in the following sections we will address each of them.

List Type

A list type is a subclass of GenericObjectList or its subclasses and is managed using the Data Model Manager.

List Type Example

• Using the Data Model Manager create list type MyOwnListType Figure 2. The inDesign property is changed to false and the other properties and attributes are kept by default.

Figure 2. MyOwnListType

• Create the class MyOwnClass and create an attribute with name newListTypeAttribute of type MyOwnListType Figure 3.

Figure 3. newListTypeAttribute

1. Select the Classes tab.
2. Create the class MyOwnClass as a subclass of InventoryObject.
3. Click on the new attribute button.
4. Set the name and type of the attribute and click the OK button.

List Type Item

A list type item is one of the possible values ​​that can be selected from the defined set, for example a list of models of a device, in terms of inventory is an instance of a class of list type.

List Type Item Example

In the previous section, the list type MyOwnListType was created; this class will be used to show how this module works.

• Enter the List Type Manager module Figure 1.

• Create a list type item Figure 4.

Figure 4. New List Type Item Window

1. Click on the New List Type Item Button.
2. Select the List Type.
3. Set the name of the List Type Item.
4. Click on the OK button.

• Select List Type Item.

Figure 4. Select List Type Item

1. Search List Type.
2. Select the List Type.
3. Select the List Type Item.
4. Button to show more information Figure 5.
5. Button to show the uses of the selected list type item.
6. Button to delete the selected list type item.
7. Manage properties of the selected list type item.
8. Manage Attachments of the selected list type item.

Figure 5. More Information Window

Uses

All objects that have a List Type attribute set use a List Type Item.

List Type Item Uses Example

• Using the pools module create a pool Figure 6.

Figure 6. New Pool Window

1. Click on the new pool button.
2. Set the name.
3. Set the class name.
4. Click on the OK button

• Using the pools module create a pool item Figure 7.

Figure 7. New Pool Item Window

1. Click on the new pool item button.
2. Set the class name.
3. Set the name.
4. Click on the OK button.

• Using the pools module set the list type attribute to the pool item Figure 8.

Figure 8. Set attribute newListTypeAttribute

1. Select pool.
2. Select pool item.
3. Double click on the property.
4. Select the list type item.
5. Click on the Accept button.

• Return to the List Type Manager module.

• Find the list type item that was set in the attribute and click on the uses button.

Figure 9 shows all the uses or objects that have the selected list type item as the attribute value.

Figure 9. List Type Item Uses

Warning: The Release all Usages button sets the attribute of all objects that use the list type item to null, is used when you want to delete a list type item.

Attachments

For some list type items it may be necessary add attachments for example for EquipmentModels to manage manuals, Figure 10 shows in more detail how it works.

Figure 10. Manage Attachments

1. Upload File button.
2. Drag and drop file section.
3. Delete attachment button.
4. Download attachment button.

Containment Manager

Another key concept in Kuwaiba is containment. It consists of the ability to define what kind of objects can be created within others. For example, a Country can be inside a Continent, but can not be inside a Rack. A Port is usually within a Board, and not inside a City. These business rules can be defined using the Containment Manager.

To access the module, click on the administration category and select the Containment Manager Figure 1.

Figure 1. Containment Manager

There are two relevant concepts in this module Standard Containment Hierarchy and Special Containment Hierarchy in the following sections we will address each of them.

Standard Containment Hierarchy

This hierarchy is used to model physical containment, for example, OLTs contain OLT boards Figure 2.

Figure 2. OLT Standard Containment Hierarchy

Figure 3 shows the workflow for configuring the containment hierarchy.

Figure 3. Dummy Root Standard Containment Hierarchy

Note: Figure 3 shows in the field to choose a class the DummyRoot that is not a class but is used as the root of the entire standard containment hierarchy.

Workflow

1. Choose a class.
2. List of current possible children.
3. The search field is used to find classes to be possible children of the chosen class.
4. To add a class as a possible child, only check the class.
5. To delete a class as a possible child, simply uncheck the class.
6. It is also possible to delete a class from the possible children by clicking on the x button.

Note: To avoid adding one by one many classes to a parent, you can use the flexibility of the data model as a hierarchical structure. For example, a Rack may contain within many types of equipment (routers, DDFs, switches, battery banks, etc). Instead of adding each of these classes one by one, you can add a common super class and all of them will be added automatically. For this example a common super class for most of those classes could be GenericCommunicationsElement Figure 4.

Figure 4. Rack possible children

Special Containment Hierarchy

This hierarchy is used to model non-physical containment, for example the VLANs of an OLT. VLANs are not physical elements like the OLT boards, but they are part of it and it is for these scenarios that the special containment hierarchy exists Figure 5.

Figure 5. OLT Special Containment Hierarchy

The flow to configure the special containment hierarchy is the same as shown in Figure 3.

Template Manager

In many scenarios, there are containment structures (see Containment Manager for details) that are created repeatedly, such as Building → Floor → Room → Rack, or ODF/DDF with the same number of ports (24/12/36/48/72/96/144), or simply equipment with the same set of attributes. For example, all routers of a certain model: the provider, slots, etc., will always be the same. Creating these elements from scratch each time would be a tedious task. For this reason, Kuwaiba provides the template manager module, which allows the creation of object templates from real inventory elements.

Figure 1 shows the structure of the module. In this example, a template is used to create cities that contain buildings, which in turn include rooms. For simplicity, only one city, building and one room are shown. When creating a template for a class, as demonstrated in the example with the A Sample City template, its association with the class is established through the HAS_TEMPLATE relationship. Additionally, the INSTANCE_OF_SPECIAL relationship is created to indicate that the template is a special instance of the class, since A Sample City will generate an instance of City.

Templates can contain other templates; in our example, we want a city to contain buildings. To achieve this, the CHILD_OF relationship is used to indicate that the A Sample Building template is a child, or is contained within, A Sample City. Similarly to the relationship between City and Building, the A Sample Room template is created to represent rooms within buildings. Thus, by using this template, this hierarchical structure will be generated in the inventory.

Figure 1. Template manager structure

The template manager module, shown in Figure 2, belongs to the Administration category.

Figure 2. Template manager module

Creating a Template

Once the module is open, to create a template, select the class for which you want to create the template in the selector located at the top left of the module's main window, as shown in Figure 3.

Figure 3. Template manager selecting class

You can select any of the classes available in the application, except for abstract and list-type classes, as elements of these classes cannot be created.

Once the class is chosen, proceed to create the template using the button The template creation window shown in Figure 4 will open. You must select the class if you have not already done so and assign a name to the template. Use a descriptive name, as this will be the one you see in the list of available templates.

Figure 4. Template creation window

Once the template is created, it will appear in the list of templates created for the selected class along with its actions, as shown in Figure 5.

Figure 5. Template list

Template Actions

Deleting a Template

It is possible to delete templates created for a class. To do so, use the button in the template actions shown in Figure 5. This will open the template deletion window shown in Figure 6. Click OK to delete it or CANCEL if you do not wish to proceed.

Figure 6. Template delete window

Adding Elements

You can add elements or special elements to templates. The elements that can be added are determined by the containment configuration of the class see Containment Manager for more details.

To add elements to the template, use the button in the template actions shown in Figure 5. If you want to add special elements, use the button. This will display the menu shown in Figure 7, where you must select whether you want to create a single element or multiple elements. If the class does not have any elements or special elements assigned in its containment, you will not be able to add elements of this type to the template.

Figure 7. Elements options menu

Creating a Single Element

If you select to create a single element from the menu in Figure 7, the single element creation window shown in Figure 8 will open. Here, you will need to assign a name to the element and choose the class of the element to add. The available classes depend on the containment configuration of the class to which you are creating the element.

Figure 8. Single element creation window

Creating Multiple Elements

If you select to create multiple elements from the menu in Figure 7, the multiple elements creation window shown in Figure 9 will open.

Figure 9. Multiple elements creation window

Where you must choose the class of the element to add. The available classes depend on the containment configuration of the class to which you are creating the element (see Containment Manager to more details about containment) and enter the naming pattern as detailed in Appendix A.

The result of using the naming pattern [sequence(a,c)], useful for creating multiple elements like buildings in the City class,[multiple-mirror(1,3)], useful for creating ports in the SpliceBox class and [mirror(1,3)]useful to create mirror ports in ODF,SpliceBox ** can be seen in Figures 10, 11 and 12 respectively.

Figure 10. Result of [sequence(a,c)]

Figure 11. Result of [multiple-mirror(1,3)]

Figure 12. Result of [mirror(1,3)]

Template Element Management

Once the template elements are created, they will be added to the template structure section of the main module window, as shown in Figure 13.

Figure 13. List of elements

In this section, you can not only view the elements and the containment tree of the multiple elements, but also create new elements or special elements on existing ones or delete them using the button of the desired element, which will display the menu shown in Figure 14.

Figure 14. Manage elements menu

This allows you to create containment structures as complex as needed, following the containment configuration of the class for which the template is created, as shown in Figure 15.

Figure 15. Template Example

Editing Properties of a Template or Elements

It is possible to edit the properties or elements of a template once they have been created. To do this, select the template or an element of the template you wish to edit. The properties sheet of the template, shown in Figure 16, or the properties of the template elements, shown in Figure 17, will appear on the right side of the main module window. Use this to edit the desired properties.

Figure 16. Example of template property sheet

Figure 17. Example of element property sheet

Using the Template

You can create objects using the templates created in the template manager from any Kuwaiba module that has the object options panel as shown in Figure 18, explained in detail in the section Object Options Panel in Navigation module. This functionality is available in modules such as navigation, pools, etc.

Figure 18. Object options panel

In the Basic Options section of the Object Options Panel you will find the options New Object from Template and New Special Object from Template as shown in Figure 19.

Figure 19. Options to create objects from template

When using them, the window for creating objects from a template, shown in Figure 20, will appear. The available classes depend on the containment configuration of the selected class.

Figure 20. Object creation window from template

For example, we use the City class and the previously created template A sample city. As a result, we create an object following the template, as observed in Figure 21.

Figure 21. Sample object created from template

Audit Trail

The audit trail module is capable of tracking changes made by users for audit purposes. Each time you make modifications to the application, including creating, modifying, deleting objects, and their relationships, entries will be created to store such changes.

Figure 1 illustrates the module’s structure. As shown in the example, changes are stored as generalActivityLogs, which are associated with the user who made them through the PERFORMED_BY relationship. If the changes were made to inventory objects, the object will be linked to its changes via the HAS_HISTORY_ENTRY relationship, allowing you to view them from the Object-related events option, described in detail later in the Object-related events section.

Figure 1. Audit trail module structure

The Audit trail module in Figure 2 belongs to the Administration category and is capable of tracking the changes performed by the users in the database for audit purposes.

Figure 2. Audit trail module

These changes can be made to inventory objects (equipment, locations, etc) or application objects (pools, tasks, user properties). There are two types of events that are logged: General events, that is, those that are not related to any object in particular, like new logins or creation of application objects. Object-related events, like property changes or move operations.

General events

Once the module is open, we can see the main window of General events as shown in Figure 3.

Figure 3. General events main window

To refresh the changes made in the application since entering the module, you can use the refresh button located in the main window of the module, as shown in Figure 4.

Figure 4. Refresh button

The module presents us with information divided into several columns, among which we find:

• Timestamp Field that contains the date when the record was made.
• Type Field that contains the type of action performed.
• User Field that contains the user who performed the action.
• Property When the event type is Object-related events, this field presents the name of the modified property of the object. Otherwise, it will be empty.
• Old Value When the event type is Object-related events, this field presents the old value previously set in the modified property of the object. Otherwise, it will be empty.
• New Value When the event type is Object-related events, this field presents the new value assigned to the modified property of the object. Otherwise, it will be empty.
• Notes Field that contains additional notes about the action, if any.

Filters

The module offers filters to facilitate the search for information. These filters can be found as indicated in Figure 5. If no filter is selected, the default behavior is to show all records

Figure 5. Audit trail filters

The types of filters are:

• Type Filter: Allows you to obtain records based on the type of action performed, such as the creation, updating, or deletion of objects, session start or end, among others.
• User Filter: Allows you to view only the records associated with actions performed by a user.

Pagination

The module presents the records in a paginated format, allowing you to navigate through the available records. The navigation controls are located at the bottom of the records, as shown in Figure 6.

Figure 6. Pagination

Object-related events

The Object-related events can be found in any Kuwaiba module that has the object options panel as shown in Figure 7, explained in detail in the section Object Options Panel in Navigation module. This functionality is available in modules such as navigation, pool, etc.

Figure 7. Object options panel

In the Explorers option section of the Object Options Panel you will find the options Audit Trail as shown in Figure 8.

Figure 8. Audit trail option

When using, the Object-related window, shown in Figure 9, will appear.

Figure 9. Object-related window

The information presented is the same as in General events except for the absence of the Notes field. Additionally, it includes the button, not present in General events which allows viewing more information about the selected object, as shown in Figure 10.

Figure 10. Information window

Users Manager

The User Manager is a module designed for managing users and groups within the application. Its features include creating new users and groups, associating or disassociating users with groups, and managing permissions for the different modules of the application.

Figure 1 illustrates the module's structure. In the application, users are organized into Groups through the BELONGS_TO_GROUP relationship, the Groups are used to simplify the management and administration of users y can contain one or more users. Each user is assigned privileges for each module individually through the HAS_PRIVILEGE relationship, this relationship represents the permissions a user has for a module.

Figure 1. User manager structure

This module is part of the Administration category, as shown in Figure 2.

Figure 2. User manager module

Once opened, we will see the main window of the module, as shown in Figure 3. From here, we can view the groups currently created in the application.

Figure 3. User manager main window

Groups

Groups allow for the aggregation of users to simplify their management and administration.

Groups Actions

Creating new groups

To create a new group, use thebutton in the main window of the module. This will open the group creation window, as shown in Figure 4. Here, you will need to enter the name and description of the group. It is advisable to use a descriptive name, as this will be the name displayed in the list of available groups.

Figure 4. Create group window

Once created, the group will appear in the list of available groups within the application, as shown in Figure 5. From here, you can also view the users assigned to each group by clicking on it, in addition to accessing group actions.

Figure 5. Group list

Deleting groups

To delete a group, use thebutton found in the group actions as shown in Figure 4. This will open the group deletion window in Figure 6. Click OK to proceed with deletion or Cancel to abort.

Note Users assigned exclusively to the group being deleted will also be removed unless they are assigned to other groups.

Figure 6. Groups delete window

Updating Groups

To edit the properties of a group, use thebutton found in the group actions as shown in Figure 5. This will open the edit window in Figure 7, where you can enter the new values. Click OK to update the group or Cancel if you decide not to proceed.

Figure 7. Groups update window

Users

Users Actions

Creating Users

A user consists of the following properties:

User Types

• GUI User: Users that will access the system via desktop client or web interface.
• Web Service Interface User: Users that will access the system via web service.
• Southbound Interface User: Users that will access the system via automated interfaces, such as southbound interfaces or scheduled tasks.
• System: users used by application modules to automate tasks.
• External application: Users that will make process in externals applications.

To create a new user, they must be assigned to a group. Use thebutton to create and assign the user to the desired group. This will open the user creation window shown in Figure 8. Fill in the fields and click OK to proceed or Cancel to abort.

Figure 8. Create user window

Once created, the user will be visible in the assigned users section of the group where they were created, as shown in Figure 9.

Figure 9. Example new user

When selecting a user, the main module window will display the information, actions, and privileges related to the user, as shown in Figure 10.

Figure 10. User information

Updating Users

To update user properties, modify them using the fields shown in Figure 10. Once the desired properties have been updated, use thebutton to save the changes.

Related User To Group

It is possible to relate a user with multiple groups simultaneously. To do this, use thebutton seen in Figure 10. This will open the user relate window shown in Figure 11. In this window, select the group you wish to relate with the user and click OK. If you do not wish to proceed, click Cancel.

Figure 11. Related user window

Once this action is completed, the user will be visible among the assigned users of the group, as seen in Figure 12.

Figure 12. User related to new group

Remove User From Group

To remove users from a group, the user must be assigned to at least two groups, as users cannot exist without a group in the application. To perform this action, use thebutton seen in Figure 10. This will open the window to remove users from a group, as shown in Figure 13. In this window, you will see the groups to which the user is assigned. Select the group from which you want to remove the user and click OK. If you do not wish to proceed, click Cancel.

Figure 13. Remove user to group window

Privileges

Privileges for each module assigned to the user can be viewed and managed on the right-hand side of the user information, as shown in Figure 10. When creating a new user, no privileges are assigned by default. To assign or remove privileges, check or uncheck the privilege type in the desired module. Note that the write privilege automatically includes the read privilege. Changes take effect immediately, as show in Figure 14.

Figure 14. Privileges

To quickly assign write privileges to a user across all modules, check the All Write checkbox in Figure 15.

Figure 15. All privileges

Warning When assigning permissions to inexperienced users, exercise caution with the modules to which you grant privileges; improper use can potentially corrupt the database.

Deleting Users

To delete a user, use thebutton shown in Figure 10. This will open the confirmation window in Figure 16. In this window, click OK to delete the user. If you do not wish to proceed, click Cancel.

Note Deleting a user will also remove them from all assigned groups, so proceed with caution.

***Figure 16.*Delete user confirm window

Tasks Manager

At times, it will be necessary to carry out certain repetitive procedures in the application, such as checking rack usage in the inventory or retrieving users from an OLT. To facilitate the execution of these recurring tasks, the application includes a Task Manager module. This module allows for the flexible creation and execution of tasks by defining scripts that can run under various conditions. Additionally, tasks created in this module can be scheduled for execution as needed by the user, using the Job Scheduler Module.

Figure 1 illustrates the module's structure. In the application, when creating a task, it can be linked to a Job through the HAS_TASK relationship, indicating that the task will be executed according to the schedule defined in the Job using the Job Scheduler module. Similarly, users can be assigned to the task, represented by the SUBSCRIBED_TO relationship. In the current version of the application, these users are for informational purposes only; however, their functionalities will be implemented in future versions of the application.

Figure 1. Task manager module

This module is part of the Administration category, as shown in Figure 2.

Figure 2. Task manager module

Once opened, we will see the main window of the module, as shown in Figure 3. From here, we can view the tasks currently created in the application.

Figure 3. Tasks manager main window

Task

A task consists of the following properties:

Tasks Action

Create Tasks

To create a task, use thebutton in the main window of the module. The task creation window shown in Figure 4 will open. You will need to enter the name and description of the task. It is advisable to use a descriptive name, as this will be the name displayed in the list of available task. Click OK to create the task or CANCEL if you do not wish to proceed.

Figure 4. Create task window

Once created, the task will appear in the list of available tasks within the application, here you can also search task by name as shown in Figure 5.

Figure 5. Group list

When selecting a task the main module window will display the information and buttons actions as shown in Figure 6.

Figure 6. Task information

Script

In the script section shown in Figure 6, you can define your own scripts, which can range from custom inventory queries to the perform complex actions.

Information It is out of the scope of this document to teach how to code scripts, however, you can find more detail and examples in the scripts available in this repository.

Script Parameters

It is important to note that most scripts will require input parameters. These parameters can be easily added to the task so that the user can fill them in before executing the task. To manage the parameters, click on thebutton. The parameter management window shown in Figure 7 will open, allowing you to create, edit, and delete parameters.

Figure 7. Manage parameters window

To create a parameter, use thebutton in the main parameter management window. The window to add a new parameter, shown in Figure 8, will open. Enter the name of the parameter to be used in the script and its value. Click OK to create it or Cancel if you decide not to proceed.

Figure 8. New parameters window

Once created, the parameter will be visible in the parameter management window, as shown in the example in Figure 8. You can edit its properties using thebutton or delete it with thebutton seen in Figure 9.

Figure 9. Parameter example

Save And Execute Script

Once the script and its parameters have been created, as shown in the example in Figure 10, you can save the script changes using thebutton seen in Figure 5.

Figure 10. Basic example of script and parameters

Or use thebutton seen in Figure 5 to save the script changes and execute your script.The execution result will be displayed in the popup window, si la ejecución fue exitosa el resaltado sera resaltado en color verde como se muestra en la Figura 11.

Figure 11. Script execution

If errors occur during the script execution, the result will be highlighted in red, as shown in Figure 12.

Figure 12. Failed script execution

Commit On Execute

If you want the changes made by the script to be saved in the database after it is executed, enable CommitOnExecute by toggling the switch seen in Figure 6. from disabledto enabled

Warning The changes made by tasks in the database can break things if your code is wrong. Ensure that the script execution was successful before enabling this feature. By default, CommitOnExecute is set to false.

Update Task Properties

To edit the properties of a task, use thebutton seen in Figure 6. The task update window shown in Figure 13 will open. Edit the desired properties and click OK to update them or CANCEL if you do not wish to proceed.

Figure 13. Update task properties window

Delete Task

To delete a task, use thebutton seen in Figure 6. The confirmation window shown in Figure 14 will open. Click OK to delete it or Cancel if you decide not to proceed.

Figure 14. Delete task confirmation window

Schedule Task

It is possible to schedule task execution using the scheduling module, explained in detail in the Scheduling module section.

Session Manager

Provides users with the ability to view and manage active sessions in the application. To access this module, go to the top menu of the screen and click on the icon . This will display a vertical menu where you can select the Session Manager option.

Warning This functionality is essential for administrators to monitor and control active sessions, thus ensuring security and efficiency in the use of the application. Therefore, it is recommended that access to this module be restricted to users with administrative permissions only.

Figure 1. Access to the session manager module.

Figure 2. Session manager module.

When accessing the module, an interface like the one shown in Figure 2 appears, with a list of all active sessions. The columns and actions available in this interface are described below:

• User. This column shows the user's name.
• Email. This column shows the e-mail address associated with each user if it has been defined by the user.
• Session Type. Indicates the type of session started.
• Login Time. Displays the date and time the session was started.
• Actions. This column provides options for managing the session. In the image, a button labeled Terminate Session is shown, which allows the administrator to terminate the active session of the corresponding user.

It is not possible for a user to end his own session using the Session Manager module. Instead, the user must logout by clicking the Logout button.

Job Scheduler

The scheduling module allows users to schedule tasks that have been previously registered in Kuwaiba through the Task Manager module (refer to the Task manager documentation). Scheduling module allows you to schedule tasks precisely using cron expressions. You can configure tasks to run every n seconds, minutes, or hours, or at a specific day and time. For example, you can execute a task every 2 hours. It's also possible to schedule tasks to run on a specific day and time, such as August 15th at 12:00 PM, or on the 1st of every month at 6:00 AM. Additionally, you can set tasks to execute on a specific day of the week, like every Monday at 8:00 AM. This module offers flexibility in scheduling tasks as needed.

Figure 1 shows the structure of the module, where all jobs are organized into a pool. Pools are groupings of similar objects in this case, jobs and can contain one or more elements. The jobs are related to one or more users using the HAS_USER relationship. Similarly, a job can only be related to a single task through the HAS_TASK relationship, which indicates the task that the job will execute when its schedule is met.

Figure 1. Scheduling module structure

The scheduling module belongs to the Administration category as shown in Figure 2.

Figure 2. Scheduling module

Scheduled Job Pool

Once the scheduling module is open, you need to create a job pool, which will allow you to create and manage jobs in an organized manner. To do this, locate the pool management button represented by a gear iconas shown in Figure 3.

Figure 3. Manage pools button

Once clicked, the pool management window will open, as shown in Figure 4.

Figure 4. Manage pools window

In this window, you can search, create, and delete job pools. Next, create a new job pool using the button seen in Figure 4. The pool creation window shown in Figure 5 will open, where you must enter the name and description and click the OK button.

Figure 5. Pool creation window

Al crear el pool de job, se pueden visualizar las jobs que tiene asignados, eliminar el pool usando el botón y editar sus propiedades utilizando la hoja de propiedades de la Figura 5.

When creating the job pool, you can view the jobs assigned to it, delete the pool using the buttonand edit its properties using the properties sheet shown in Figure 6.

Figure 6. Pool property sheet

Scheduled Job

A job consists of the following properties:

Once the job pool is created, the button to add jobswill be enabled in the main menu of the module, as seen in Figure 7.

Figure 7. Create jobs button

Pressing it will open the job creation window shown in Figure 8.

Figure 8. Jobs creation window

To create the job, follow these instructions:

• Select a pool in Jobs Pool combo box allows you to assign the new job to the desired pool.

• Fill in the text fields for Name and Description.

• Select a tasks in Select Task combo box allows you to assign the task to be executed by the job. This task must have been previously registered in Kuwaiba through the Task Manager module.

• Use the buttonallows you to assign users available in Kuwaiba to the job. These users will be notified of the task execution result (this feature will be added in the future and is not yet available).

• Fill Execute, this combo box allows you to select the job execution (CronExpression). The scheduling options include the following:

• Every: Enables the execution of the job at short intervals, ranging from seconds to hours.
• Daily: Allows daily execution of the job at the selected time of day.
• Weekly: Enables weekly execution of the job. You must select the desired day of the week and time.
• Monthly: Enables monthly execution of the job. You must select the desired day of the month and time. (If you select the 30th of each month, execution will be skipped in months with fewer than 30 days).

If all mandatory properties marked with * are filled in correctly, the OK button in the job creation window from Figure 8 will be enabled.

Note Before creating or scheduling a job, ensure that the scheduler user is created in the application. If not, create it in group system with the name scheduler and type System. For more details on how to create users, refer to the User Manger, which explains this in detail.

When a new job is created, it will be scheduled and queued to be executed according to the assigned execution interval. It can be viewed in the main window of the module as seen in Figure 9. Upon creating a job, it will automatically be scheduled every time the application starts. If for any reason you do not want it to be executed, you can disable its execution by setting the Enable property to False or by deleting the job.

Once the job is executed, the result of its execution will be logged in the general events of the AuditTrail using the user scheduler. You can refer to AuditTrail for more details.

Figure 9. Jobs scheduled

When left-clicking on a job, the property sheet shown in Figure 10 will appear. This property sheet allows you to edit the properties of the job after it has been created.

Figure 10. Job property sheet

All properties of a job seen previously can be edited by double-clicking the desired property on the property sheet.

To edit the cronExpression property, double-click on it. This will prompt the cronExpression editing popup window shown in Figure 11, which behaves similarly to when creating and assigning the execution of a new job. Once you've chosen the new job execution, click OK to edit, or Cancel if you don't wish to edit this property.

Figure 11. Edit cronExpression property window

Similarly, to edit the users assigned to the job, double-click on the users property. This will display the selection list of available users in Kuwaiba, as shown in Figure 12. Add or remove the users you want to assign or unassign from the job, then click OK to edit or Cancel if you don't wish to edit this property.

Figure 12. Edit users property window

Finally, to edit the task that the job should execute, double-click on the tasks property. This will open the task editing window shown in Figure 13, where you can choose any task registered in the Task Manager. Once you've selected the task, click OK to edit or Cancel if you don't wish to edit this property.

Figure 13. Edit tasks property window

Jobs have four possible states, which inform the user about the execution status of the jobs that have been scheduled. The status can be viewed in the central part of the main window of the module. The available states are:

• Scheduled: Indicates that the job has been scheduled correctly and is waiting to be executed.
• Running: Indicates that the job is currently running (it cannot be edited during this time).
• Executed: Indicates that the job executed successfully in its last execution.
• Error: Indicates that an error occurred in the last execution of the job.

Finally, it's possible to view the list of jobs associated with a pool or all created jobs using the pool selector located on the left side of the main window. It's also possible to filter the results by job name. Additionally, this list allows you to delete a job using the buttonas shown in Figure 14.

Figure 14. List of jobs

Navigation

This module is the main navigation tool of the application, as it presents the physical objects of the inventory organized in a hierarchical containment structure explained in the Containment Manager chapter.

To access the navigation module in the top bar of the screen, locate the compass symbol shown in Figure 1. Then go to the Navigation section.

Figure 1. Navigation module.

All physical layer objects created start from the same root called Dummy Root which is the first level of containment. The image below shows the main view of the navigation module. The objects observed when clicking on the Go To Root button are the direct children of Root. That is, the objects created at the top of the hierarchy.

Figure 2. Navigation module interface.

Clicking on the Root Actions button displays a menu with the available options for object creation. As shown below. These options are explained in detail in the Object Options Panel section.

Figure 3. Root actions.

The top bar that appears in the Navigation module allows you to perform a search to find inventory objects more easily. You can search for an object by its name, displayName or by the class it belongs to. For example, to search for a Rack, you can search by the Rack class or by the Rack name. Before clicking to return the complete search results, the application provides 5 suggestions grouped by type of item to facilitate the search. Search results are paginated, with a maximum of 20 results per page.

Figure 4. Search objects by className.

Next to each object that appears as a search result, the button is displayed, allowing quick access to the most frequently used actions in the inventory. After performing the search, a second search bar appears with which you can filter according to the results found, as shown below.

Figure 5. Filter.

By accessing any physical object in the inventory, you can view information specific to the selected object. As shown in Figure 6.

Figure 6. Inventory object navigation.

In Figure 6, the section marked in red corresponds to the Object Options Panel, explained in detail in the section Object Options Panel.

In the upper part of Figure 6 (detailed in Figure 7) the path or containment hierarchy of the selected object is shown. This means that the New Zeland object contains the Wellington object, which in turn contains the WEL-FAC-02 object, which contains the object of interest: the selected Rack (WEL-RCK-03). The hierarchy shown in Figure 7 is interactive. By selecting any of the elements within the containment hierarchy, you will be redirected to the detailed information of that object.

Figure 7. Object containment hierarchy.

Clicking on the Show More Information button shown at the top of Figure 8 opens a pop-up window like the one shown in Figure 9, which contains basic information about the selected inventory object.

• Object Id. It is the identifier of the object in the database. It is useful for troubleshooting. It is often used in the Query Manager to create queries.
• Class Name. The class to which the inventory object belongs.
• Containment Path. Indicates the complete containment structure of the object.

Figure 8. Object Information.

Figure 9. Object Information.

On the right side of Figure 6, shown in more detail in Figure 10, there is a filter bar at the top. This bar is used if the Rack has filters associated with it. Filters, as the name implies, filter the children of an object according to the conditions evaluated in the filter. For more information, see the Filters section. Below the filter field, the descending hierarchy of the class of interest is displayed, i.e. the inventory objects contained in the selected Rack. When selecting any of the objects in Figure 10, the interface will display similar content as in Figure 6, but with the information of the newly selected object. Next to some objects shown in Figure 8, some percentages are observed. These represent the results of the validators associated with the object class. For more information, see chapter Validator Definition.

Figure 10. Children of the selected object.

Object Options Panel

The Object Options Panel is a central component that manages the functionality of the objects in the inventory. It can be accessed from several areas such as the navigation module, pools and when executing queries, among other access points, as opposed to being limited to a specific module.

Figure 11. Object Options Panel.

Figure 11 shows the components that make up the Object Options Panel. Each of them will be explained in detail below.

Object Properties

Displays the values of the attributes of an inventory object. These attributes match the visible attributes defined in the Containment Manager. All changes are automatically entered into the database when the Enter key is pressed.

The F2 key on your keyboard allows you to quickly change the name of the selected object.

Figure 12. Object Properties.

There are different types of attributes.

• Read Only. These are attributes that cannot be modified. In Figure 12, you can see that the creationDate attribute is grayed out, indicating that its value is not modifiable.

• Unique. These are attributes whose value must be unique in the inventory and are indicated with purple color.

  Figure 13. Unique attribute.

• Mandatory. These are attributes whose value must be defined as mandatory. Mandatory attributes are indicated in red, as shown in the figure below.

  Figure 14. Mandatory attribute.

• List Type Items. These are attributes whose value must be selected from a specific list of particular object types. For more details see chapter List Type Manager. In Figure 15 you can see, when you select an attribute of a specific list type, it opens an editor containing the list of possible values that can be defined. If you do not want to select any, use the first option from the list (None).

  Figure 15. List type items.

Basic Actions

The basic actions of each inventory object are shown in Figure 16 and are described below.

Figure 16. Basic Actions.

New Object

Creates a single object as a child of Root using the standard containment hierarchy.

Figure 17. Create Object.

New Multiple Objects

Creates a defined number of objects at a time using a given naming pattern.

Figure 18. Create Multiple Objects.

New Object from Template

Creates an object (and possibly a complex containment structure under it) from a previously defined template. See more details in chapter Template Manager.

New Special Object

Creates an object in the Special Containment Hierarchy (see Containment Manager).

Figure 19. Create Special Object.

New Multiple Special Objects

Creates several objects of the special containment hierarchy using a pattern.

Figure 20. Create multiple special objects.

New Special Object from Template

Creates a special containment hierarchy object from a Template defined in the Template Manager.

Copy to

A plain copy operation.

Figure 21. Copy object to another object.

Move to

Moves the object respecting the containment hierarchy.

Figure 22. Move object to another object.

Copy as Special to

Copies the object respecting the special containment hierarchy.

Figure 23. Copy as special object to another object.

Move as Special to

Moves the object respecting the special containment hierarchy.

Figure 24. Move as special object to another object.

Manage Attachments

Handles attachments directly related to the object, as well as attachments associated with list-type items linked to the object. Figure 25 shows how attachments directly related to the object can be viewed, added, deleted or downloaded. In this case, an MPLS Router has an attachment directly related to the object.

Figure 25. Manage direct attachments.

On the other hand, in Figure 26, it is observed that the attachments indirectly related to the object can only be viewed and downloaded, but not modified. In this case, the MPLS Router has an attachment indirectly related to the object.

Figure 26. Manage other attachments.

Manage Special Relationships

Allows you to create arbitrary relationships between objects.

Warning This action should be handled with extreme caution, as it may cause damage to the model.

Figure 27 shows the pop-up window that displays the special relationships that an object has. The button allows you to delete a relationship.

Figure 27. Manage special relationships.

To create a new special relationship, select the New Special Relationship button. This will open a new window where you can define the name of the relationship and specify the object with which this special relationship will be established.

Figure 28. Manage special relationships.

Reports

Displays the reports associated to the objects of this class. In this case, Rack has three associated reports, as shown in Figure 29. Selecting a specific report opens a new HTML window with the result of the report execution. This section is explained in detail in the Reports chapter.

Note: It is necessary to enable popups in the browser so that the report can be executed.

Figure 29. Reports.

Copy to Pool

Copy the inventory object to a pool containing elements of the same type as the object to be copied. See more details in Pools.

Move to Pool

Move the inventory object to a pool containing elements of the same type as the object of interest. For more details see Pools chapter.

Add to Folder

All inventory objects can be added to an existing Favorites Folder. See more details in Favorites chapter.

Delete Object

Deletes the object. This will fail if the object has an incoming relationship, for example, a Port connected to a cable.

Advanced Actions

The advanced actions of the inventory objects differ from the type of object of interest. They are injected by other modules where they will be detailed.

Figure 30. Advanced actions.

Views

A view is a graphical representation of a selected object that can be displayed from different perspectives by different modules.

Figure 31. Views.

Object View

Applies to objects of the ViewableObject subclasses

A view is a graphical representation of what is inside an object. All instances (objects) of subclasses of ViewableObject have an ObjectView that shows the direct children of the selected node. Most objects, except for logical and administrative assets and a few physical ones such as slots and ports, are subclasses of ViewableObject. An example of the object view is shown in Figure 32, where the selected object is a country and in the object view are the cities and states that are direct children of the selected country.

Figure 32. Object view.

Figure 33 shows the toolbar at the top of Figure 32.

Figure 33. Object view toolbar.

In the upper left part of Figure 33 a search box appears, where you can search for a specific object that is a direct child of the selected object.

Icon	Description
	Save view
	Update view
	Connect two nodes (See Physical Connections for more details on how to use it)
	Add a background image
	Hide/show the labels next to the connections
	Change labels color
	Export as image

Rack View

Applies to objects of class or subclass Rack

This view only works with objects of the Rack class or its subclasses. It shows how the elements contained in the selected object are organized, according to their position and the number of rack units used.

Figure 34. Rack view.

To build this view correctly, three conditions must be met:

• The rack must have its rackUnits attribute set to a valid integer value. This attribute stores the total number of rack units supported by the rack. Typical values are 20, 28, 34, 40 or 45.
• The rackUnitsNumberingDescending attribute must exist, if the order of the rack units has not been set, ascending numbering is assumed. This attribute instructs the view to display the rack units in ascending (if false) or descending (if true) order.
• The rackUnits and position attributes must exist and have valid values on the contained elements within the rack. rackUnits in this case, refers to the number of rack units occupied by the contained element, while position is the starting position of the contained element, based on 1, numbered from top to bottom. This value is usually provided by your equipment supplier. If the value of rackUnits is 0, the element will not be displayed in the view.

Figure 35. Rack properties.

Figure 36. Rack children properties.

A menu is shown at the top of Figure 34.

Figure 37. Rack view menu.

• The Show/Hide Help button provides the user with a short guide to the use of the tool, as shown in Figure 38.

  Figure 38. Rack view help.

• The tool offers a more detailed view of the rack and its components, by clicking on the Show Detailed View option as shown below.

  Figure 39. Detailed rack view.

• The icon opens a new window with the connected devices and their status, as shown in Figure 40.

  Figure 40. Device summary.

• The icon opens a window with the connections between the devices, as shown in Figure 41.

  Figure 41. Connection list.

• The icon is used to edit the attributes of the selected rack, as shown in Figure 42.

  Figure 42. Rack properties.

Finally, in Figure 34, on the left side of the view, there are two options that appear next to each of the devices:

• The icon opens a new window with the port information for each device, as shown in Figure 43.

  Figure 43. Port summary by device.

• The icon allows you to move the device to a different position within the rack.

  Figure 44. Move device in the rack.

Splice Box View

Applies to objects of class or subclass SpliceBox

This view represents the splices made by a splice box, using the mirror, endpointA and endpointB relationships. In the example in Figure 45, a splice box with 4 input ports (IN-001, IN-002, IN-003 and IN-004) and 4 output ports (OUT-001, OUT-002, OUT-003 and OUT-004) is shown, where each input port is connected to a corresponding output port using a mirror relationship. Also visible is a fiber path labeled 001 (related to the splice box ports via the endpointA and endpointB relationships), which enters the splice box through port IN-001 and exits through output port OUT-001. The figure also shows the organization of the connections and the internal structure of the splice box, highlighting the splices currently in use (marked in blue) versus those available (marked in gray).

Figure 45. Splice box view.

Fiber Splitter View

Applies to objects of class or subclass FiberSplitter

It shows the operation of a fiber splitter, illustrating how a single fiber signal is distributed to multiple outputs. The fiber splitter view is based on the multipleMirror, endpointA and endpointB relationships. The endpointA and endpointB relationships identify the ports where the fiber path enters and exits, while the multipleMirror relationship is the relationship between the single fiber splitter input port and the N output ports.

In the view presented in Figure 46, a fiber splitter called 1x16 Secondary Splitter was selected, which has 16 output ports (001-OUT to 016-OUT) connected to the splitter's input port (IN-001) where the fiber optic cable enters.

The splitter has only one of the occupied outputs (001-OUT), which connects to another device. In the figure, this connected output is shown in blue, while the other 15 output ports, which are not yet in use, are shown in gray.

Figure 46. Fiber splitter view.

Physical Path View

Applies to objects of the GenericPort subclasses

Calculates and plots the longest path from a source port to another port, considering mirror, mirrorMultiple, endpointA and endpointB relationships. This view represents hierarchically the components that are part of the route, showing clearly their interconnections and the order in which they are arranged. See more in Outside Plant Management.

Figure 47. Physical path view.

The example in Figure 47 shows the connection of an optical fiber from a port of a selected ONT to an OLT, passing through two intermediate fiber splitters. The port of the selected ONT is IN-01, and the OLT port where the connection terminates is PON-001. This representation allows to visualize and understand the exact path of the optical signal, facilitating the tasks of diagnosis, maintenance and network planning.

Figure 48 illustrates clearly the options presented by this view, shown in Figure 47 in the red box.

Figure 48. Physical path options.

Selecting the option Relate Segments/Devices to Service, as shown in Figure 47, opens a new pop-up window as seen in Figure 49. In this window, the user can relate a service to the elements that are part of the selected network. At the top of Figure 49, there is a search box that allows the user to select the service to which the device or network segment is to be associated. To finalize the process and create the relationship, choose the Relate Selection to Service option.

Figure 49. Relate device to service.

The view can be downloaded as a jpg image by selecting the Export as Image option listed in Figure 48. The box at the bottom of Figure 48 allows the user to move more easily through the view in case its size is considerably large.

Physical Tree View

Applies to objects of the GenericPort subclasses.

Using the endpointA, endpointB, mirror and mirrorMultiple relationships from a source port, all paths to other ports are calculated and plotted in the view. In the example illustrated in Figure 50, port PON-001 of an OLT has been selected. The view shows all physical connections associated with this port (in this case, a single connection) and the devices that are part of these routes. See more in Outside Plant Management.

Figure 50. Physical tree view.

The red box shown in Figure 50 allows the user to adjust the size of the graph in case the diagram is too large.

Explorers

This component, as its name suggests, explores the structures of a model, including relationships, attachments and containment hierarchies. In the navigation module, there are three subcomponents, which are explained below.

Figure 51. Explorers.

Special Children

Special children are elements that, while following the concept of containment hierarchy, are used in domain-specific models. This gives them a particular behavior depending on the situation. They cannot be treated as simple objects in the navigation tree since, for example, their removal may require additional tasks beyond simply deleting them from the database, because they are part of a complex workflow. These children respect the special containment hierarchy detailed in the Special Containment Hierarchy chapter. As shown in Figure 52, selecting an object displays a pop-up window with its special children. If any of these special children are selected, its own special children, if any, will be displayed. When selecting any special child, the corresponding object information appears in the Object Options Panel on the right side of the screen.

Figure 52. Special children explorer.

Relationships

Allows you to view the special relationships of the selected object. When an object is part of a specific domain model (such as SDH, Physical Connections, MPLS, Services, etc.), there are special links to other objects called relationships. These relationships, with documented names according to the model, can be displayed using this explorer. Figure 53 shows the relationships of an Optical Link, where three types of relationships are observed. The parent relationship, which is common to all inventory objects and is used to navigate upwards in the containment structure, and the endpointA and endpointB relationships, which are used in the Physical Connections model. Selecting either of the latter two relationships expands the displayed tree, indicating the object with which the relationship exists and, in turn, displaying the relationships of that object. On the right side of Figure 53 is the Object Options Panel, which displays information and actions related to the specific object selected.

Figure 53. Relationships explorer.

Audit Trail

It is a sequence of records that documents changes in inventory objects. For more details, see chapter Audit Trail.

Queries Manager

The Query Manager is a module designed for performing advanced searches based on nodes using the graphical interface. The search criteria can range from properties to relationships.

Figure 1 illustrates the module's structure. In the application, queries are stored and organized into Pools through the CHILD_OF_SPECIAL relationship, the Pools are groups of similar objects in this case, queries and can contain one or more elements. These queries, written as Groovy scripts, facilitate low-level queries within the application. Each query may include parameters that allow necessary values to be sent in the queries. The parameters are associated with the query through the HAS_PARAMETER relationship, indicating that the query has been assigned a parameter and will require it at the time of execution.

Figure 1. Queries manager Structure

This module is part of the Navigation category, as shown in Figure 2.

Figure 2. Queries manager module

Once opened, we will see the main window of the module, as shown in Figure 3. From here you can create your queries and scripts to make queries.

Figure 3. Queries manager main window

The module allows us to perform queries in two ways: by creating a query through the graphical interface in Query Builder or through scripts in Scripted Queries.

Using Query builder

This option allows us to create queries using the module's graphical interface. To start, locate Query Builder in the main window of the module, as shown in Figure 4. This option is selected by default when entering the module.

Figure 4. Query builder

To create a query, search for and select the class of the element you want to find, as shown in Figure 5. Abstract classes are supported.

Figure 5. Select class

Once the class is chosen, a graphical representation of it will be placed on the canvas, as seen in Figure 6. This search box is a representation of the class node and contains each attribute of the selected class.

Figure 6. Class selected

You can search for a wider range of elements by selecting an abstract class (often called GenericSomething). In the previous example, it will search for all Racks in the database, but if you choose GenericPhysicalNode, it will search for all physical nodes, that is, all objects that can be connected via a container (see the Physical Connections chapter for more information about containers). This includes: buildings, rooms, floors, towers, shelters, and facilities.

Important

• If you want to see all objects in the database (at least all relevant to the inventory) search for InventoryObject, which is the root of all classes related to the inventory. To see the complete hierarchy see related chapter Data Model Manager

When you select a class, the Execute Query button will be enabled, allowing you to run the query. If you run it at this moment, the system will return all elements of the selected class, paginated in sets of 10 results, showing only the object's name, as seen in Figure 7.

Figure 7. Executed query

Pressing the Explore Object button will open a pop-up with the object's basic data as seen in Figure 8.

Figure 8. Object properties

Setting other attributes in the search box as visible will result in those fields being displayed in the results window, as shown in Figure 9.

Figure 9. Visible properties

Adding conditions

To perform more complex queries, you can add search conditions for any of the class attributes using the button. There are two types of attributes: those stored directly in the class node, such as name, id, creationDate, etc. Called simple attributes, and attributes whose information is stored in a separate node, called list type attributes (See list type attributes for details).

Clicking on the button for a class attribute will open the window shown in Figure 10. Enter a filter type and the desired value, then click OK.

Figure 10. Window to add attribute

The available filter types depend on the data type of the attribute (String, Integer, etc.), as seen in the example in Figure 11 for String type attributes like name, or in Figure 12 for Integer type attributes like rackUnits.

Figure 11. Available string filters

Figure 12. Available int filters

For our example, we will search for Racks in the inventory that contain "01" in their name using the Contains filter from Figure 11 on the name attribute, and that have a capacity of 24 units using the Equals to filter from Figure 12 on the rackUnits attribute. By setting these conditions for the query, you can see their graphical representation next to the corresponding attribute in the search box, as shown in Figure 13. You can edit the filters using or remove them using .

Figure 13. Filters selected

If we execute the query at this moment, we will not get the desired result as shown in Figure 14 because we need to consider how filters are applied in queries. This is similar to how it's handled in a conventional SQL statement. When we have more than two filters, we must select how they will be used in the query. We have logical operators OR and AND, which are equivalent to those used in SQL.

Figure 14. Query incomplete result

To adjust the behavior of the filters, we have the tools shown in Figure 15. From here, you can adjust the logical operator to use in the filters and the number of results the query will display.

Figure 15. Query filters

By default, the selected logical operator is OR, and the record limit is 10. In the case of our example, we select the logical operator AND and execute the query. The expected result can be seen in Figure 16.

Figure 16. Result filters

For list type attributes, when you click on the button, the window shown in Figure 17 will open. For this example, we will use the Router class, which has list attributes such as software version, model, state,vendor. We will search for routers with the vendor Huawei.

Figure 17. List type attribute filter

For list type attributes, we have two filter options, Select List Type Item and Advanced Search. By default, Select List Type Item is selected. In this filter, we need to choose from the attribute's list types, as shown in Figure 18. For the vendor attribute, we select Huawei, and its result can be seen in Figure 19.

Figure 18. Available list types

Figure 19. List type Search result

If we select the Advanced Search filter, it will not be possible to select from the attribute's list types, as shown in Figure 20. Instead, we click the OK button.

Figure 20. Advanced search window

We will see that a graphical representation is immediately placed on the canvas, as shown in Figure 21. This search box represents the list type node and contains each of its attributes, similar to the search box for the selected class. As with the class, it is possible to add additional filters to the list type attributes, allowing for the creation of complex queries tailored to different scenarios.

Figure 21. Advanced search filter

Finally, when using the button for the parent attribute, the window shown in Figure 22 will appear. This allows for a search considering the containment of the class. Refer to the containment manager for more details.

Figure 22. Select parent filter window

As an example, we will search for all Routers contained in the ANZ Center building, with the vendor Cisco, and whose serial number matches NZV06. To start, in the Router class, the containment classes Building, Facility, Floor, Room, and Zone are available according to its containment configuration. We choose the Building class as shown in Figure 23.

Figure 23. Select parent filter

We set the filters to Contains for both the building name and serial number, with the values ANZ Center and NZV06, respectively. For the vendor, we select Cisco and choose AND as the logical connector, as shown in Figure 24.

Figure 24. Advance query

When we execute the query, we obtain the desired routers as shown in Figure 25.

Figure 25. Advance query result

Using Scripted Queries

This option allows us to create queries using Groovy scripts. The queries created with these scripts have low-level access to the application's database. Thanks to the use of scripts, it is possible to reuse these scripted queries in other modules of the application outside the queries module, allowing precise data retrieval and manipulation.

For example, the queries created in the ospman.geo pool as seen in Figure 26 are used to perform geographical queries. Refer to the Outside Plant Management for more details.

Warning The changes made by scripted queries in the database can break things if your code is wrong. Proceed with caution.

To start, locate Scripted Builder in the main window of the module, as shown in Figure 26.

Figure 26. Query builder

Manage scripted query pools

Upon entering this option, you will see the available scripts grouped into pools. To begin, create a pool using thebutton. The window shown in Figure 27 will open; enter a name, description, and click OK.

Figure 27. Add pool window

Once the pool is created, it will appear in the list of available pools, as shown in Figure 28. Conversely, if you wish to delete a pool, select it and use thebutton to delete it.

Figure 28. Pool lists

To edit the properties of a pool, use thebutton. The window shown in Figure 29 will appear, where you can edit the properties by double-clicking on the desired property.

Figure 29. Edit pool properties window

Manage scripted query

To add a script, locate the desired pool and use thebutton. This will open the window shown in Figure 30. Enter a name, description, and click OK.

Figure 30. Add script window

Once the script is created, use thebutton to display the scripts associated with a pool, as shown in Figure 31.

Figure 31. Scripts in pool

Clicking on the script will display the editor and actions associated with the script, as shown in Figure 32.

Figure 32. Script editor

Information the creation of scripted query is beyond the scope of this document; however, you can find more detail and examples in the scripts available in this repository.

once the script is created you can save the changes using the button seen in Figure 33.

Figure 33. Script example

Similarly, use thebutton to save the changes to the script and open the script execution window, as shown in Figure 34.

Figure 34. Execute scripted query window

It's important to note that most scripts will require input parameters. As seen in Figure 34, you can add parameters before executing the script. To do this, enter the parameter name and value, then click . Once you've added the necessary parameters, click OK to execute the script, as shown in Figure 35.

Figure 35. Execute script

The result of the script execution will appear in the pop-up window as seen in Figure 36.

Figure 36. Script result

To edit the properties of a script after it has been created, use thebutton seen in Figure 33. This will open the window shown in Figure 37, where you can edit the properties by double-clicking on the desired property.

Figure 37. Edit script properties window

To delete a script, use thebutton. This will open the confirmation window shown in Figure 38. Click OK to proceed with the deletion or Cancel if you do not wish to delete it.

Figure 38. Delete script confirmation window

Pools

The Pools module refers to a group of resources managed collectively to optimize their use and availability. In simple terms, a "pool" is a shared repository of similar resources that can be used by different parties or processes within a system and that cannot be placed in the standard navigation tree. Most of these resources are logical or administrative elements, such as VLANs or VPNs. You can imagine a pool as a bag where resources that do not have a specific place in the inventory structure are placed.

To open the Pools module, I selected Options -> Pools in the options menu.

Figure 1. Pools module selection in the general menu

Once the Pools module is opened, a new pool can be added. To do so, locate the New Pool button represented by the add symbol , as shown in the figure below.

Figure 2. Creation of a new pool

Once activated, the window will open to create a new pool. In the dialog box, you will be asked to enter the name of the new pool, its description, and the type of objects you want to store inside it. If you choose, for example, "Router", you can only store Router instances. However, if you select an abstract class (anything that begins with "Generic" or one of the parent classes such as InventoryObject or ViewableObject), you will be able to place instances of any of its subclasses.

Figure 3. Dialog for creating a new pool

Once created, you can edit the name and description of the pool attributes in the property sheet.

Figure 4. Pool attributes

To manage the new pool, use the buttons next to the pool name. You can delete it with the button or add a new item by clicking the add icon , as shown in the figure next.

Figure 5. Creating a new element within a pool

Once activated, the window will open to create a new item in a pool. In the dialog box, you will be asked to enter the name of the new item and select the type of object it represents.

Figure 6. Dialog for creating a new pool item

The new created item will appear on the right side of the screen as shown in the figure below

Figure 7. New item created

To modify the properties of the new item, click on its name. Its attributes will be displayed, as well as the associated actions and explorers, as shown in the figure below.

Figure 8. New item properties

Basic actions, such as delete to delete the selected item, advanced and explorers are described in the chapter Object Options Panel. However, the actions shown in the image below are specific to this module and are described below.

Figure 9. New item created

Favorites

The Favorites module allows you to easily organize frequently accessed items without having to navigate deeply between objects. To access this module, go to the Navigation section, identified by the symbol at the top of the screen, and then select the Favorites option.

Figure 1. Access to favorites module.

A pop-up window as shown in Figure 2 appears.

Figure 2. Favorites module.

You can select an existing folder or create a new one. To select an existing one, use the search bar marked Filter by Folder Name, where you can enter the desired folder name. Alternatively, you can click on the icon to display a list of existing folders, as illustrated in Figure 3.

Figure 3. Folder search.

When you select an existing folder, the objects belonging to that folder are displayed along with their hierarchical structure, as indicated in Figure 4. When you click on a specific object, the Object Options Panel appears with the object's information, located on the right side of the screen and explained in detail in the Navigation chapter. In addition, you will find the Release From Folder option, which allows you to delete the object from the selected folder.

Figure 4. Selected folder display.

You can create a new folder by selecting the button where a new window appears requesting the name of the new Folder, as shown below.

Figure 5. Create new folder.

You can edit the name of a folder by selecting it from the filter shown in Figure 3 and then clicking on the icon . This will display a window similar to the one shown in Figure 6, where you can enter the new folder name. Similarly, you can delete a folder by selecting the icon . It is important to note that these buttons to edit and delete a folder will only be available after selecting a specific folder; otherwise, they will remain disabled.

Figure 6. Edit folder.

To add an object to a favorite folder, go to the Object Options Panel (explained in the Navigation chapter) and find the Add to Folder option under Basic Actions. Then, select the folder where you want to add the object, as shown in Figure 8.

Figure 7. Option to add to favorites.

Figure 8. Add object to favorites.

Warehouse Manager

The warehouse module allows for the management and organization of equipment and items that are not currently in use within the network. This module not only enables the representation of physical inventory objects but also their states, such as equipment under maintenance, awaiting installation, or in transit.

Figure 1 shows the structure of the module, where all warehouses are organized into a pool. Pools are groupings of similar objects in this case, warehouses and can contain one or more elements. The warehouses, which are inventory objects, are related to one or more pools using the CHILD_OF_SPECIAL relationship. This allows for the grouping of similar items within the warehouse, such as bags of screws, loose screws, etc. The creation of pools facilitates the organization and management of inventory by allowing items to be grouped and sorted according to specific criteria, such as brand, type, or any other relevant attribute.

Figure 1. Warehouse manager structure

This module is part of the Navigation category, as shown in Figure 2.

Figure 2. Warehouse manager

Once opened we will see the main window of the module, as shown in Figure 3. From here we can see the warehouses currently created in the application.

Figure 3. Warehouse manager main window

Physical Warehouses

Physical warehouses are mechanisms for representing inventory objects that are not currently in use within the network, such as equipment awaiting installation, tools, etc. To create a physical warehouse, select its tab; your selection will be indicated by a horizontal blue line, as shown in Figure 4.

Figure 4. Physical warehouse

Once the tab is selected, use thebutton. The window to create physical warehouses will open, as shown in Figure 5. Enter a name and click OK.

Figure 5. New physical warehouse window

When a new warehouse is created, it will appear in the list of physical warehouses currently created in the application, as highlighted in Figure 6.

Figure 6. List physical warehouses

As mentioned in the module's structure, warehouses can contain various types of inventory items, which are organized into pools to facilitate their management. This organization allows for the simulation of drawers, shelves, etc, in a real warehouse, accurately reflecting the state of the inventory. To create pools within a warehouse, select it, and you will see the warehouse's property sheet, where you can edit its properties by double-clicking on the property to update and pressing enter. You will also see the pool search bar and the actions to manage pools, as shown in Figure 7.

Figure 7. Warehouses pools actions

Next, use thebutton, which will open the window to create pools, as seen in Figure 8. In this window, you must select the inventory class from which you want to create objects to be stored in the pool. Note that you can only store objects of that type; for our example, we'll use Rack. Enter the name and description, ensuring that the name is descriptive, which will help you quickly identify the type of objects stored in the pool. Click OK to create the pool or Cancel if you do not wish to proceed.

Note If you wish to create multiple types of objects in a pool to represent a specific situation in your warehouses, use the available superclasses. Refer to the Containment section for more details on superclasses.

Figure 8. Add pools window

Once the pool is created, it can be selected in the pool search bar, as shown in Figure 9. When a pool is selected, the options to update its information and delete it, as well as the option to add objects to the pool, will be enabled, as shown in Figure 10.

Figure 9. Select pool

Figure 10. Pool options

To update the information of a pool, use thebutton, which will open the window to update pools, as shown in Figure 11. Edit the properties and click OK or Cancel if you do not wish to continue. Note that it is not possible to change the type of objects stored in the pool. For example, if you have a pool with 100 objects of the type Router and you change the pool type, these objects cannot be stored in the new pool. If you need to change the pool type for any reason, create a new pool with the desired type and move the objects to it; this action is detailed in the Move Objects section.

Figure 11. Update pool window

Similarly, you can delete the pool using thebutton or delete the warehouse by selecting it and clicking thebutton. In both cases, a confirmation window will open, as shown in Figure 12.

Figure 12. Delete pool window

Note Proceed with caution when removing a warehouse or pool, as the items inside will also be removed from inventory. This action is irreversible.

To add objects to the pool use thebutton which will open the window to add objects in the pool seen in Figure 13, enter name and description and press OK.

Figure 13. Add parts window

By doing so, an object of the type assigned to the pool will be created in the application's inventory and assigned to the pool. For our example, this will be a pool representing the storage room for racks awaiting installation. Once the object is created, it will appear in the list of objects in the pool, as shown in Figure 14.

Figure 14. New object

When selecting the rack, the Object Options Panel will appear, as shown in Figure 15. All its options and menus are explained in detail in the Object Options Panel section of the Navigation module.

Figure 15. Object available actions

Suppose one of the racks you have stored contains a battery in one of its slots. You can represent these situations by creating such objects in the rack. To do this, use the New Object option from the Basic Actions menu. After creating these objects, you can view them by clicking thebutton. This will display all the objects created in the rack, as shown in Figure 16. This way, you can detail the situation of your warehouses.

Figure 16. Rack child

Logical Warehouses

As mentioned earlier, warehouses not only represent physical inventory objects but also their states. Virtual warehouses represent the states or stages of equipment. For example, a batch of equipment purchased but currently in transit can be represented by a virtual warehouse. These warehouses allow you to model the flow of objects within a process, such as the purchase, maintenance, or installation of equipment.

The steps to create warehouses, pools, and objects are the same as those previously described for physical warehouses. However, in this case, select the tab corresponding to Virtual Warehouses, as shown in Figure 17.

Figure 17. Virtual warehouse

Repeat the previous steps to create a warehouse that will contain the elements of your inventory waiting for some process. For the example, we will create a pool for items undergoing maintenance within that warehouse, as shown in Figure 18.

Figure 18. New pool

As previously mentioned, we will use the superclass GenericCommunicationElement, which will allow us to store objects from its hierarchy in the pool. This enables us to represent multiple types of communication objects, such as UPS, printers, etc, as shown in Figure 19. The containment and hierarchy are explained in detail in the Containment section.

Figure 19. Objects example

Warehouses Operations

Move Objects

Suppose one of the items has completed the maintenance process and is being transported back to its operational site. You can move objects housed in one pool to another pool in any warehouse that accepts the same type of items. For this example, we will move the printer that has completed its maintenance and is in transport to its usage location, to the default In Transport warehouse available in the application. To do this, select the object and in the Object Options Panel, use the Move To Warehouse option from the Advanced Actions menu. This will open the window for moving objects, as shown in Figure 20.

Figure 20. Move object window

When selecting a warehouse, the field to choose the destination pool will appear, as shown in Figure 21. By clicking OK, the object will be moved to the selected warehouse and pool. If you attempt to move the object to a warehouse that does not have a pool with the type of object you want to move, you will be notified, as shown in Figure 22.

Figure 21. Select pool to move object

Figure 22. Invalid pools to move object

You can move objects from the warehouses to any other object in the application where they can be contained, repeat the previous steps in order to represent the removal of an object from your inventory.

Delete Objects

If you want to delete an object from the warehouse, you can do so from the Object Options Panel by using the Delete Object option located in the Basic Actions menu. A confirmation window will appear; click OK to proceed or Cancel if you do not wish to continue.

Explore Objects

As mentioned earlier, when creating an object, it can also be accessed through the application’s inventory. To do this, go to the Navigation module and search by name or class, in this case Rack, as shown in Figure 23.

Figure 23. New rack

From here, and through the Object Options Panel, you can perform any of the available options explained in detail in the Object Options Panel section of the Navigation module.

Integration with External Tools

The previously mentioned steps can be tedious when you need to register a large number of items in your warehouses. To simplify this process, the warehouse module can be integrated with external tools and leverage the Kuwaiba API, allowing for task automation. Thanks to this orchestration capability with other systems built on top of Kuwaiba, warehouse movements can be recorded without manual intervention. This not only optimizes inventory management but also facilitates information flow and record updating, acting as an efficient and accurate data repository for your purposes.

Physical Connections Module

The physical connections module registers basic actions, advanced actions and views that allow the creation of physical connections (optical, wireless, electrical and power-related) using the Object Options Panel. In this chapter the following topics will be addressed:

• Physical Connections
• Basic Actions
  • Delete Physical Container
  • Delete Physical Link
• Advanced Actions
  • Manage Port Mirroring
  • Port Summary
  • Edit Connections
  • Connect Using a Link
  • Connect Using a Container
• Views

Physical Connections

The Physical Connections toolkit is tightly integrated to the Physical Connections module. With Kuwaiba you can create physical layer connections using cables, fiber optics or radio links very easily, navigate through the connections and inspect the resources in use.

Before presenting the tools provided by the application, let’s first clarify and introduce some concepts. This module deals solely with L1 topologies. It’s only about cables, ports, etc. The data model provides four types of entities to represent physical layer elements:

• Links: These are all physical connections that connect two ports. In the current data model, there are three types of connections: ElectricalLink (for electrical connections like coaxial, twisted pairs and the like), OpticalLink (for fiber optics), RadioLink (for radio links -Microwave links, mostly-) and PowerLink (for electrical power connections AC/DC). You can create new types by adding subclasses to the abstract class GenericPhysicalLink Figure 1. See Data Model Manager.

Figure 1. Links in data model

• Containers: All objects that can be used to contain, wrap and protect links (understanding Link as defined above). There are two types of containers: WireContainer (used to contain all kind of cables -wires and fibers-, like pipes, conduits, ditches, etc) and WirelessContainer (used to contain radio channels or carriers). You can create new types by adding subclasses to the abstract class GenericPhysicalContainer Figure 2.

Figure 2. Containers in data model

• Nodes: These objects are endpoints to Containers. In the default data model you will find classes like: Tower, Facility, Shelter, Building, Floor and Room, but in general, any inventory object can be a Node Figure 3.

Note: In versions prior to 1.5, only subclasses of GenericPhysicalNode could be nodes.

Figure 3. Nodes in data model

• Endpoints: These objects are endpoints to Links. In practice, they’re always some kind of Port (in the data model context, this means all subclasses of GenericPort) Figure 4.

Figure 4. Endpoints in data model

In summary, you can only connect Nodes using Containers and Endpoints using Links. To create new connections, open the Object View of an element and try to connect the desired nodes. For example, Figure 5 shows two nodes objects of the class Manhole and a container object of the class WireContainer.

Figure 5. Manholes connected by a pipe

On the left side of Figure 6 shows the interior of the pipe from Figure 5 that contains containers and links where the orange containers are tube bundle, the red containers the tubes and inside the tubes the cables. The right side of Figure 6 shows an enlarged view of the cable that contains the loose tubes that in turn contain the fibers.

Figure 6. Pipe

Figure 5 and Figure 6 show three of the four elements of a physical connection.

There are three options to create physical connections in the inventory:

• Outside Plant module
• Connectivity Manager module
• Using the basic actions, advanced actions and views that allow the creation of physical connections (optical, electrical and power-related) using the Object Options Panel.

For this example, the tools enabled by this module will be used. Using the navigation module, a city and two manholes are created, which will store splice box each.

Figure 7. New city

Using the object view the pipe will be created between the two manholes using the connect tool .

Figure 8. New pipe

Select the pipe in the object view, using the object options panel create a tube bundle as a special child, open the special children explorer and create the necessary containers and fibers Figure 9.

Figure 9. New pipe special children

Select the pipe in the object view and use the edit connections action in the object options panel to connect fibers to endpoints Figure 10.

Figure 10. Connecting endpoints

Using the navigation module will mirror the ports in the splice box Figure 11 using the manage port mirroring action.

Figure 11. Mirroring

Using the splice box view we can see the connected fibers Figure 12

Figure 12. Splice box view

To view more details of the connection, select one of the splice box ports in the navigation module and open the physical path view Figure 13.

Figure 13. Physical path view

Once the port connections are made, we have all the elements of a physical connection: the links (OpticalLinks), containers (WireContainers -pipes, tube bundle, tubes, cables, loose tubes-), the endpoints (OpticalPorts) and the nodes (Manholes).

Basic Actions

Delete Physical Container

Applies to objects of class or subclass GenericPhysicalContainer

A physical container from the perspective of an FTTH network could be an indoor, outdoor or drop cable, in the Data Model Manager Figure 14 it is represented as a WireContainer, for a wireless network a WirelessContainer contains a set of radio links.

Figure 14. Subclasses GenericPhysicalContainer

The delete physical containers action is only available for subclass instances of GenericPhysicalContainer as shown in Figure 15.

Figure 15. Delete physical container action

To delete a physical container click on the action and click on the OK button Figure 16.

Figure 16. Delete physical container

Delete Physical Link

Applies to objects of class or subclass GenericPhysicalLink

A physical link from an FTTH perspective is the fiber in the Data Model Manager is represented by the OpticalLink class Figure 17, for wireless networks the RadioLink class is used.

Figure 17. Subclasses GenericPhysicalLink

The delete physical link action is only available for subclass instances of GenericPhysicalLink as shown in Figure 18.

Figure 18. Delete physical link action

To delete a physical link click on the action and click on the OK button Figure 19.

Figure 19. Delete physical link

Advanced Actions

Manage Port Mirroring

Applies to objects of class or subclass GenericPort, GenericDistributionFrame, GenericSplicingDevice, Antenna

Mirroring in Kuwaiba means creating mirror or mirrorMultiple relationships between ports, below are some uses of this action for different classes:

• When we execute this action from one of the subclasses of GenericPort Figure 20 only a mirror or mirrorMultiple relationship will be created from one port to another port.

Figure 20. Subclasses GenericPort

Figure 21 shows the flow to mirror an OpticalPort

Figure 21. Manage port mirroring OpticalPort

1. Select the type of single mirror or multiple mirror.
2. Select the other port.
3. Once the other port is selected it should appear in the mirrors.
4. Used to remove the mirror.

• When we execute this action from one of the subclasses of GenericDistributionFrame Figure 22 create mirror or mirrorMultiple relationships.

Figure 22. Subclasses GenericDistributionFrame

Figure 23 shows the flow to mirror an ODF

Figure 23. Manage port mirroring ODF

1. Select the type of mirror.
2. Drag a port.
3. Drop on source ports.
4. Drag other port and drop on target ports.
5. Select a source port.
6. Select a target port.
7. Click on existing mirror Figure 24.
8. Automatic mirror matching Figure 25.

Figure 24. Existing mirrors ODF

Figure 25. Automatic mirror matching ODF

Port Summary

Applies to objects of class or subclass GenericCommunicationsElement, GenericDistributionFrame, GenericSplicingDevice

Shows how the ports are connected within the device, the IP address and assigned services if they exist. Figure 26 shows the flow to execute the action.

Figure 26. Port summary ONT

1. Search for an OpticalLineTerminal or any of the classes in which this action can be applied.
2. Click on the Port Summary action.
3. Physical Path ONT port Figure 27.
4. Object dashboard ONT port service Figure 28.

Figure 27. Physical path ONT port

Figure 28. Object dashboard ONT port service

Edit Connections

Applies to objects of class or subclass GenericPhysicalConnection Figure 29

Figure 29. Subclasses GenericPhysicalConnection

To execute the action, look for an object that is a subclass GenericPhysicalConnection select it and click on the action Edit Connections Figure 30.

Figure 30. Edit connections action

A window appears, the flow to edit a connection is shown in Figure 31.

Figure 31. Edit connections window

1. Select the endpoint A.
2. Select a link.
3. Select the endpoint B.
4. Click on the button Connect Selected Endpoints to the link.
5. Disconnect only the endpoint A of the link.
6. Disconnect only the endpoint B of the link.
7. Disconnect the endpoint A and the endpoint B of the link.

Connect Using a Link

Applies to objects of class or subclass GenericPort Figure 32.

Figure 32. Subclasses GenericPort

To execute the action, look for an object that is a subclass GenericPort select it and click on the action Connect to... Figure 33.

Figure 33. Connect using link action

In this example we will connect the port of an ODF with a port of an OLT, for this we must select the target port Figure 34.

Figure 34. Connect using link new window

Figure 35 shows the steps to find the OLT port to connect.

Figure 35. Select connection target port window

Once the target port is selected, we use the suggested connection name and click on the Connect button.

Figure 36. Connect using link window

1. Suggested connection name.

Figure 37 shows the new link using the physical path view for the ODF port.

Figure 37. New link in physical path

Connect Using a Container

Applies to objects of class or subclass GenericLocation Figure 38, GenericDistributionFrame or GenericSplicingDevice

Figure 38. Subclasses GenericLocation

To execute the action, look for an object that is a subclass GenericLocation, GenericDistributionFrame orGenericSplicingDevice select it and click on the action Connect to... Figure 39.

Figure 39. Connect using container action

1. Select an object.
2. Click on the Connect to... action.
3. Select connection type.
4. Optional select a template for the connection.
5. Select the other end of the connection.
6. Suggested connection name.
7. Click on the Connect button that will create the connection and open the window in Figure 40.

Figure 40. Edit connections new container window

If you click on the OK button, the window to edit connections will open Figure 41.

Figure 41. New container in edit connection window

Views

All views registered by this module were detailed in the navigation module:

• Object View
• Rack View
• Fiber Splitter View
• Splice Box View
• Physical Path View
• Physical Tree View

Connectivity Manager

The connectivity manager module helps with the creation of physical and logical circuits. The access method is shown in Figure 1.

Figure 1. Connectivity manager module

Clicking on the module will open a window Figure 2.

Figure 2. Connectivity manager window

1. Link to create a New Object Figure 3.
2. Link to Template Manager module.
3. Link to Navigation module

Figure 3. Select new object parent

Figure 3 shows the window that appears after clicking on the New Object link, in which a parent is selected for the new object and then an action is chosen for the creation Figure 4.

Figure 4. New object window

Figure 4 shows the basic actions to create an object:

1. New Object
2. New Object from Template
3. New Multiple Objects

Creating a Physical Circuit

The goal of this section is to create a physical circuit between two routers that are located in two data centers (DC) Figure 5.

Figure 5. Initial object view

The Building objects are within a City object and each one has a Rack object Figure 6, Figure 7 and Figure 8.

Figure 6. Parents of Rack in Data Center 001

Figure 7. Parents of Rack in Building 001

Figure 8. Parents of Rack in Data Center 002

Each Rack object inside the Building object contains the equipment to be connected. Below are simple rack views of the racks that will be used:

• The Rack object in data center 001 contains an ODF object and a MPLSRouter object of which one of its ports will be used as the start of the physical circuit Figure 9.

Figure 9. Simple Rack View of Rack in Data Center 001

• The Rack object in building 001 contains two ODF objects used simply to reach data center 002 Figure 10.

Figure 10. Simple Rack View of Rack in Building 001

• The Rack object in data center 002 contains a ODF object and a MPLSRouter object of which one of the ports will be used as the end of the physical circuit Figure 11.

Figure 11. Simple Rack View of Rack in Data Center 002

New Connection

Before creating the physical circuit using the object view, a connection will be created between data center 001 and building 001.

Figure 12 shows how the creation starts.

Figure 12. New connection window

1. Click on the Connect button.
2. Select side A of the connection.
3. Select side B of the connection.
4. Click on the Next button.

Figure 13 shows the definition of the characteristics of the new connection.

Figure 13. Details of new connection

1. Set connection name ¹.
2. A cable will be used to connect the two buildings.
3. Set the connection class.
4. Check to use a cable template. See the Template Manager module.
5. Select a template.
6. Click on the Next button.

Figure 14 shows the selection of the connection endpoints.

Figure 14. New connection endpoints

1. Select the endpoint A of the connection.
2. Select the endpoint B of the connection.
3. Click on the Finish button.

Figure 15 shows the new connection.

Figure 15. Object view with new connection

Connectivity Manager Window

Once the initial state of the network that will be used is known, we begin with the creation of the physical circuit Figure 16.

Figure 16. Connectivity Manager window

1. Button to select the source port Figure 17.
2. Button to select the source port Figure 18.
3. Type of action to execute between ports Figure 19 and Figure 20.

• Figure 17 shows the selection of the port from where the physical circuit starts.

Figure 17. Select source port

1. The MPLSRouter object is searched using its name.
2. Using filters, all ports within the Router are listed. See Filters module.
3. Select one of the ports.
4. Click the button.

• Figure 18 shows the selection of the target port.

Figure 18. Select target port

1. The ODF object is searched using its name.
2. Select one of the ports.
3. Click the button.

• Figure 19 shows the actions that will be taken between the ports.

Figure 19. Connectivity manager actions

Actions

New Cable/Fiber

• Figure 20 shows the action that will be taken between the ports.

Figure 20. New fiber window

1. Automatically generated name¹.
2. Select link type.
3. Click the button.

Figure 21 shows the first connection.

Figure 21. First connection

New Mirror

Figure 22 shows the steps to execute the action of a new mirror between two ports of a ODF.

Figure 22. New mirror

1. Select target port.
2. Select New Mirror action.
3. Choose mirror type.
4. Click the button.

Select Existing Cable/Fiber

Figure 23. Select existing cable action

1. Select target port.
2. Select Existing Cable/Fiber action.

Figure 24 shows the action to use an existing cable, the cable that was created in the New Connection section will be used.

Figure 24. Select existing cable window

1. Select the cable.
2. Select the tube.
3. Select fiber.
4. Click the button.

Select a Cable/Fiber in a Container Template

Before creating a cable using templates, some mirrors and links were created Figure 25.

Figure 25. Select a Cable/Fiber in a Container Template action

1. New mirrors and links added. See New Mirror and New Cable/Fiber actions.
2. Select target port.
3. Select a Cable/Fiber in a Container Template action.

Figure 26 shows the creation of a cable between building 001 and data center 002 using templates. See Template Manager

Figure 26. Select a Cable/Fiber in a Container Template window

1. Select endpoint A of the cable.
2. Select endpoint B of the cable.
3. Select the class.
4. Set the cable name¹.
5. Select cable template.
6. Select a tube.
7. Select a fiber.
8. Click the button.

Physical Circuit

Figure 27 shows the physical circuit from one port of a MPLSRouter in data center 001 to the other port in a MPLSRouter in data center 002.

Figure 27. Physical circuit

Once the physical circuit has been created, you can see the physical path of the MPLSRouter port in the data center 001 Figure 28.

Figure 28. Physical circuit

Note The numbering in Figures 27 and 28 is used to show different perspectives of the same physical circuit. For example (1) is the fiber connected from a MPLSRouter port to an ODF port.

Creating a Logical Circuit

A logical circuit is a point-to-point connection and is used to represent last mile OSP circuits.

Note To create other types of logic circuits see the New Logic Circuit module.

New Service

Before creating the logical circuit, the service to which it will be associated will be created. Figure 29 shows the step by step to create a service using the Service Manager module.

Figure 29. New Service

1. Select the customer pool.
2. Select the customer.
3. Select the service pool.
4. Click on the New Service button.
5. Choose the type of service.
6. Set the service name¹.
7. Click on the OK button.

Create Logical Connection

Logical connection are used to represent point-to-point connections like those used in modules SDH and MPLS.

The logical connection created in this module are similar to MPLS Figure 30.

Figure 30. MPLS relationships

The difference with MPS is the objects and relationships used Figure 31.

Figure 31. Last mile circuit relationships

The types of logical connections are the subclasses of GenericLastMileCircuit to add more options that adapt to your needs, just create subclasses using the Data Model Manager, for example MetroEthernet.

Figure 32. Custom GenericLastMileCircuit subclasses

Notes

• Logical connections were designed for last mile services, however currently they are used interchangeably to represent logical circuits.
• It is possible that the model will be simplified in the future, it is recommended to use Circuit to facilitate the migration.

Figure 33 shows the step by step to create a logical connection.

Figure 33. Create Logical Connection

1. Select source port.
2. Select target port.
3. Automatically generated name¹.
4. Select logical connection class.
5. Search service by name or class.
6. Click on the Create Logical Connection button.

Using the Navigation module you can search for the new logical connection the Figure 34 shows the relationships explorer for the created logical connection.

Figure 34. Logical connection relationships

Outside Plant Management

The outside plant module manages the OSP views which are composed of nodes and connections and are used to represent a network.

Figure 1. Outside plant module

In this chapter the following topics will be addressed:

• Creating an FTTH OSP view
  • Adding Nodes
  • Adding Connections
• Node Tools
• Connection Tools
• Map Tools
• OSP View Tools
• Geographical Queries
• View Content Tool
  • Filters
• Splicing Tool
• Customize the Map
  • Map Provider
  • Map Center and Zoom
  • Map Labels

Creating an FTTH OSP view

To build the osp view we are going to use as a reference the diagram in Figure 2 in which we have a central office where the OLT will be located, a primary splitter and a secondary splitter, to which the client's ONT will be connected.

Figure 2. FTTH Diagram

• Click on the create an osp view button , in the window Figure 3 enter the name and description and click on the OK button.

Figure 3. Create OSP view window

• Click on the open properties panel button to see the view properties Figure 4.

Figure 4. View properties

• Center the map where the network will be located. Figure 5 shows the updated map properties.

Figure 5. Map Properties

Adding Nodes

• Select the new panel node as shown in Figure 6.

Figure 6. New Node Panel

• Drag and drop to map the Test Central Office building template then the window shown in Figure 7 will appear, select the parent of the node and click the next button.

Figure 7. New Building

• Using the object properties rename Test Central Office as POP Central Office Figure 8.

Figure 8. Navigation Central Office

• The two previous steps are repeated to add the first and second level splitters Figure 9, and to add a house Figure 10.

Figure 9. New splitters

Figure 10. New house

The OSP view should be similar to that shown in Figure 11.

Figure 11. OSP view nodes only

Adding Connections

Once the view nodes are created, they are connected using the connection tools.

• Selecting the connection tool creates a cable between the POP Central Office and the manhole that contains the 1x4 Primary Splitter Figure 12. Then a window will appear to define the name and type of the new cable Figure 13. Click on the OK button

Figure 12. New cable

Figure 13. New container window

• In the window that asks whether to edit connections, click the Yes button Figure 14.

Figure 14. Do you want edit connections? window

• A window will appear to edit the connections, it will be used to create the connection between the OLT port and the primary splitter as shown in Figure 15.

Figure 15. Edit connections window

1. Select OLT port.
2. Select fiber.
3. Select IN port in primary splitter.
4. Click the button Connect Selected Endpoints.
5. Close edit connection window.

• Once the connections have been edited the OSP view looks as shown in Figure 16

Figure 16. OSP view with one connection

• Repeat the steps to create the connection between the primary splitter and the secondary splitter, and between the secondary splitter and the house Figure 17.

Figure 17. Simple OSP View

For more details on the connections edition see Edit Connections.

Node Tools

Figure 19. Node tools

Figure 19 shows the node tools window that appears when you right click on a node.

Tool	Description
	This tool is used to do fiber optic splicing of the cables that reach the selected node. See splicing tool
	Used to view the devices within the node, you can list all or use filters. See view content tool
	Using the node coordinates, geographical queries filter the network elements within a search radius.
	Remove the node from the view only, to remove the node from the inventory it is necessary to do so from the navigation module

Connection Tools

Figure 20. Connections tools

Figure 20 shows the connection tools window that appears when you right click on a connection.

Tool	Description
	The edit connection tool was covered in the adding connections section Figure 15.
	Remove the node from the view only, to remove the node from the inventory it is necessary to do so through the navigation module

Map Tools

Figure 18. Map tools

Figure 18 shows the map tools window that appears when you right click on map.

Tool	Description
	Using the coordinates where you right clicked on the map, geographical queries filter the network elements within a search radius.

OSP View Tools

Figure 19. Osp View tools

Figure 19 shows the tools to manage the OSP views.

Tool	Description	Keyboard Shortcut
	Open properties panel
	Open an existing OSP View	Alt-O
	Create an OSP View	Alt-N
	Delete OSP View	Alt-D
	Save OSP View	Alt-U
	Select a node or connection	Alt-H
	Add node	Alt-M
	Add connections between two nodes using the existing containers
	Connect two nodes using a container	Alt-E
	Run a container through a single or multiple containers	Alt-C
	Run a link through a single or multiple containers	Alt-L
	Searches for a node or connection within the view	Alt-S
	Filter the nodes by class	Alt-F
	Measure distance

Geographical Queries

A geographic query is a scripted query from the ospman.geo pool Figure 20, this query must have the parameters latitude, longitude, viewNodes and radius plus other additional parameters that the query may require.

Figure 20. Geographical Query Pool

The latitude, longitude and viewNodes parameters are set when the query is selected Figure 21. If the action was launched from a node (see Node Tools) the latitude and longitude will be equal to that of the node. But if the action is launched from the map (see Map Tools) the values ​​are set by calculating the latitude and longitude where the right click was made. The viewNodes parameter is the list of nodes in the view.

Figure 21. Geographical Queries

The radius parameter is a positive number in meters of a circle with center in latitude and longitude, and must be set by the user before executing the query Figure 22 as well as the additional parameters to those already mentioned.

Note

The Outside Plant module lists and executes the scripted queries Figure 21 created in the Queries module Figure 20

Figure 22. Geographical Query

Figure 22 shows the flow to execute a geographic query:

1. Set the radius in meters and other parameters if they exist.
2. Click on the Execute button.
3. Filter nodes by name or class name.
4. Select the node.
5. Click on the Locate on Map button to center the view on the selected node.
6. Check nodes to create a heat map.
7. Click the Details... button to open an Object Options Panel Figure 23.
8. Click on the View Content button.
9. Click the Close button.

Figure 23. 1x16 Secondary Splitter details

View Content Tool

The view content tool helps you navigate the children of devices and physical connections Figure 24.

Figure 24. View content window

1. Select filter. See Filters.
2. Select device.
3. Select any of the children of the device that contains ports.
4. Search for a port.
5. Click the Physical Path button Figure 25.
6. Click the Physical Tree button Figure 26.
7. Click the Close button.

Figure 25. Physical path view

For more details on the physical path view see the navigation module.

Figure 26. Physical tree view

For more details on the physical tree view see the navigation module.

Filters

Note This is a brief introduction to filters, for more details see the Filters module.

Figure 24 shows the content of a building. The filters that appear in the filter selector are the filters defined for the Building class. Figure 27 shows the extensions for the Building class. See the data model manager.

Figure 27. Extensions for the Building class

Figure 28 shows all the filters that apply to the Building class. In general, the filters of a class are the filters of the same class and the classes that it extends.

Figure 28. Filters

Splicing Tool

For Kuwaiba, splicing a fiber is creating the relationship endpointA or endpointB. For example using manholes that contain the primary splitter, splicing of the fibers that are not yet connected to the splitter will be done.

In Figure 29 there are three fields that must be set: the location, the cable, and a device. In the field to select the location, all the nodes in the view are listed; the value that appears by default is that of the node that opened the tool.

Figure 29. Splicing window

Click on the Select Cable button, Figure 29, a window will open that lists the cables that enter and leave the node, select the cable and then one of the tubes on which the splice will be made Figure 30.

Figure 30. Select cable

Click on the Select Device button, Figure 29, a window appears and will list the devices in the node, select the device on which the splice will be made Figure 31.

Figure 31. Select device

Once the cable and device are selected, the location view is loaded Figure 32.

Figure 32. Location view

The location of the device can be changed using the button Figure 33

Figure 33. Changed location view

The location view have some tools for management to access them, right click on the port or fiber.

Figure 34 shows the port tools, most of them have already been explained in other chapters, the links are listed below:

Figure 34. Port tools

1. Property Sheet.
2. Manage Port Mirroring.
3. Show Physical Path.
4. Show Physical Tree.

Figure 35 shows the fiber tools, all have been covered in other chapters, the list of links is shown below:

Figure 35. Fiber tools

1. Property Sheet.
2. Show Physical Path Endpoint A/B.
3. Show Physical Tree Endpoint A/B.

Figure 36 shows an example of using the fiber property sheet tool to set its color.

Figure 36. Set fiber color

1. Right click on the fiber, click on the property sheet tool.
2. Double click on the value of the color property.
3. Select fiber color.
4. Click on the Accept button.
5. Click on the Close button.

To update the fiber color in the location view click the refresh button Figure 37.

Note: following fiber optic cable color codes¹ define the colors for the other fibers.

Figure 37. Location view refreshed

There are two ways to splice from a port to fiber Figure 38 or from fiber to port Figure 39.

Figure 38. Splicing from port to fiber

Figure 39. Splicing from fiber to port

Figure 40 shows the splicing of fibers 2, 3 and 4.

Figure 40. Fiber splicing

Figure 41 shows the relationships explorer for fiber 2.

Figure 41. Fiber relationships

Customize the Map

Some characteristics of the map can be changed using the configuration variables below are the changes enabled for the user.

Note: the default values ​​are listed in the configuration variables module.

Map Provider

By default the map is displayed using OpenLayers and the Open Street Map (OSM) tiled layer, to use a different map provider you must update the value of the configuration variable general.maps.provider to one of the following allowed values:

• com.neotropic.kuwaiba.modules.commercial.ospman.providers.ol.osm.OsmProvider
• com.neotropic.kuwaiba.modules.commercial.ospman.providers.ol.bmaps.BmapsProvider
• com.neotropic.kuwaiba.modules.commercial.ospman.providers.google.GoogleMapsMapProvider

Notes

• com.neotropic.kuwaiba.modules.commercial.ospman.providers.google.GoogleMapsMapProvider require the value of the configuration variable general.maps.apiKey to be set.
• com.neotropic.kuwaiba.modules.commercial.ospman.providers.ol.bmaps.BmapsProvider require the value of the configuration variables general.maps.apiKey and general.maps.provider.bmaps.imagerySet the possible values ​​of the last one are:
  • Aerial
  • AerialWithLabels
  • AerialWithLabelsOnDemand
  • Streetside
  • BirdsEye
  • BirdsEyeWithLabels
  • Road
  • CanvasDark
  • CanvasLight
  • CanvasGray

In addition to the listed providers, it is possible to extend the functionality of this module to use other providers such as Leaflet.

Map Center and Zoom

When you enter the module, the map has a center and zoom by default, this behavior can be changed by updating the configuration variables:

• widgets.simplemap.centerLatitude The default center latitude.
• widgets.simplemap.centerLongitude The default center longitude.
• widgets.simplemap.zoom The default map zoom.

Map Labels

To change the color or fill color of the labels of the nodes or edges, the following configuration variables are used:

• module.ospman.colorForLabels The color for the map labels.
• module.ospman.fillColorForEdgeLabels The fill color for the map edge labels.
• module.ospman.fillColorForNodeLabels The fill color for the map node labels.
• module.ospman.fillColorForSelectedEdgeLabels The fill color for the map selected edge labels.
• module.ospman.fillColorForSelectedNodeLabels The fill color for the map selected node labels.
• module.ospman.fontSizeForLabels The font size for the map labels.
• module.ospman.minZoomForLabels The minimum zoom level for the map when displaying.

IP Address Manager

The IP Address Manager is a tool designed to manage IP addresses efficiently. It allows storing both individual IP addresses and entire subnets along with their associated IP addresses. Through this tool, users can easily view which IP addresses are busy and which are available on a given network. In summary, the IP Address Manager facilitates the organization and control of the assignment of IP addresses, contributing to more effective management of the network infrastructure.

To open the IP Address Manager module, select Options -> IP Address Manager from the options menu.

Figure 1. IP Address Manager module selection in the general menu

Once the IP Address Manager module is opened you can distinguish:

Figure 2. Overview of the IP Address Manager

• Explore from IPv4 Root: Explorer for IPv4 address management.

Figure 3. Explorer button for IPv4 address management

• Explore from IPv6 Root: Explorer for IPv6 address management.

Figure 4. Explorer button for IPv6 address management

• Search Bar: In the central part of the screen, there is a search bar that allows you to search for a specific IP address or folder within the IPv4 and IPv6 collections.

Figure 5. Search Bar

• IP Address Management: Allows you to create new subnets or collections of subnets.

Figure 6. IP Address Management

• IP Address Explorer: Allows you to view the elements related to a collection of IP addresses, including subnets and other collections of subnets.

Figure 7. IP Address Explorer

• Properties of the Selected Element: Allows you to view the properties or characteristics of the selected element. By default, the image below is displayed.

Figure 8. Selected Element Properties

Create a New Folder of Subnets

In the IP Address Management section, select the button shown in the image below to add a new folder of subnets.

Figure 9. IP Address Management

This action will open the dialog box shown below, where the name of the new folder (collection) and a description of it are requested. The new added item will appear in the IP Address Explorer section.

Figure 10. Dialog for Creating a New Folder of Subnets

Create a New Subnet

In the IP Address Management section, select the button shown in the image below to add a new subnet.

Figure 11. IP Address Management

This action will open the dialog box shown below, where the subnet base address and subnet prefix in CIDR format will be requested, along with a brief description. The same dialog will provide a description of the items to be configured, including the broadcast address, network address, number of hosts, and subnet mask, as shown in the dialog below. The new added item will appear in the IP Address Explorer section.

Figure 12. Dialog for Creating a New Subnet

IP Address Explorer

In this section we can manipulate both the collections of subnets and the added subnets. The available options are described below:

• Options for Subnet Folder :

  • Add a New Subnet Folder : Creates a new subnet folder within the current folder.
  • Remove Subnet Folder : Remove the folder.
  • Add a New Subnet Folder : Creates a new subnet within the folder.
  • Add a New IP Address : Create an IP address within a subnet. This will open a dialog like the one shown in the figure below, where the IP address to enter and a description are requested.

    Figure 13. New IP Address

  • Add to Favorites :This functionality will be available in future versions.

• Options for Subnet :

  • Add a New Subnet : Create a new subnet within the current subnet, example shown in Figure 12.
  • Delete Subnet : Delete the subnet.
  • Split a Subnet : Split a subnet based on the network prefix as shown below.

    Figure 14. Split a Subnet

  • Add a New IP Address : Create an IP address within a subnet. This will open a dialog like the one shown in Figure 15, where the IP address to enter and a description are requested.

    Figure 15. Create non-reserved IP address

  • Create Non-reserved IP Address: As shown below, an IP address is created and it will be not reserved. After running this command successfully, the Divide a Subnet option will be disabled.
  • Create All IP Addresses: As shown in Figure 16 the possible IP addresses are created for the selected subnet, all the IP addresses created will be not reserved.

    Figure 16. Create All IP Addresses

  • Create Reserved IP address: As shown below, an IP address is created and it will be reserved. After executing this command successfully, the Divide a Subnet option will be disabled.

    Figure 17. Create Reserved IP address

  • Add to Favorites : This functionality will be available in future versions.

Properties of the Selected Element

The default image changes depending on the selected element, providing detailed information about it.

• Selected Subnet Collection: The figure below shows the subnets and IP addresses created in the collection. You can also see if these addresses are free, indicated with the icon , and the reserved ones with . Basic information such as name and description is presented.

  Figure 18. Properties of a Collection of Subnets

• Selected Subnet: The figure below shows the subnet with the created IP addresses. You can also see if these addresses are linked to any network element, indicated with the icon. Free IP addresses are distinguished with the icon , and reserved ones with . Other icons correspond to the validator logic used for the module. In addition, basic information is presented such as the name, creation date and quantitative data, such as the percentage of occupancy of the subnet.

  Figure 19. Properties of a subnets

Relate a Network Interface to an IP

In the IP Address Manager module, it is possible to relate a network interface to a specific IP address. This functionality is found in the action available for the ports of the Navigation Tree module (Navigation Tree).

Figure 20. Optical Port Navigation Tree

To map a network interface to an IP address, navigate to the desired port in the navigation tree. In the Advanced Actions menu, select the Relate to IP Address action.

Figure 21. Action in the Navigation Tree to Relate Network Interface to IP Address

In the dialog box, select the IP address you want to associate.

Figure 22. Relate Network Interface to IP Dialog

Colors and Icons

The colors and icons used in the IP Address Manager come from a validator in the configuration module. These help to quickly view the status of IP addresses.

Figure 23. Validation Colors and Icons

Icons

• Free IP icon: Indicates that the IP is free.
• Reserved IP icon: Indicates that the IP is reserved.
• IP Related Icon: Indicates that the IP is associated with a network element.

Colors

The colors shown in the IP addresses will be similar to those presented in the graph. In this example, green is used for free addresses, blue for used addresses, and gray for reserved addresses.

Figure 24. IP Address Colors

Relationship between Network Element and IP Addresses

Each IP address can be associated with different services on the network. By viewing the properties of an IP, you can see the associated services and their statuses.

Figure 25. Relationship between Network Element and IP Addresses

• IP Address: IP Address.
• Service (Service): Related service.
• Network Interface (Network): Network interface related to the IP address. Clicking the icon will immediately unlink the IP from the item.
• Device/Location: Indicates that the IP address is associated with a network element.

isManagementInterface

The isManagementInterface field indicates whether a port is a management interface for a device (such as a router). This designation is crucial to identify the port through which the device is managed, rather than used for regular communications traffic.

Figure 26. isManagementInterface attribute

• Purpose: Indicate that this is the router's management port and not a communications port.
• Importance: Ensures that an IP address is always assigned to the management interface in order to access and manage the device.

New Logical Circuit

Creates new logic circuits given the type and the endpoints. The access method is shown in Figure 1.

Figure 1. New Logical Circuit module

Figure 2 shows the step by step to configure the new logical circuit. For this example, the physical circuit Figure 3 built in the chapter of the Connectivity Manager module will be used.

Figure 2. New logical circuit window

1. Select source port Figure 4.
2. Select target port Figure 5.
3. Select logical circuit type Figure 6.
4. Automatically generated name Figure 6.
5. Click on the OK button.

Using the Navigation module you can search for the new logical circuit the Figure 7 shows the relationships explorer.

Figure 3. Physical circuit

Figure 4. Select source port

Figure 5. Select target port

Figure 6. Configuration of the new logical circuit

Figure 7. New logical circuit relationships

MPLS Networks

Create MPLS (Multiprotocol Label Switching) topologies and create virtual circuits between network interfaces.

Figure 1. MPLS Module

Figure 2 shows an example MPLS view.

Figure 2. Example MPLS View

1. Tools.
2. Canvas.
3. View Options Panel and Object Options Panel.

Tools

Figure 3. Tools

Figure 3 shows the tools to manage the MPLS views.

Tool	Description
	Open view
	New view
	Remove view
	Add existing devices and MPLS links to the view
	New MPLS link
	Detect MPLS link between nodes
	Remove from database and view
	Remove from view
	Export as image

Creating a View

To create a new view click on the New MPLS view tool Figure 4.

Figure 4. New MPLS view window

Once the view is created, two routers will be added Figure 5, these are the ones that were used in the physical circuit that was built in the connectivity manager chapter.

Figure 5. Add existing devices

Figure 6 shows the view with the two MPLS routers.

Figure 6. View with two MPLSRouters

In the chapter about New Logical Circuit, an MPLS Link Figure 7 was created that we will add to this view.

Figure 7. Existing MPLS Link

Using the MPLS link detection tool between nodes Figure 8.

Figure 8. View with MPLSLink

Module Actions

Delete MPLS Link

Applies to object instances of MPLSLink subclasses.

Figure 9. Delete MPLS Link

Relate to VLAN

Applies to object instances of GenericPort subclasses.

Figure 10. Relate to VLAN

SDH Networks

This module allows to create end-to-end virtual circuits and all other logical entities required by the SDH protocol¹. Let’s introduce some concepts first. See Figure 1 for sample connection that illustrate the following terms.

1. TransportLink A point-to-point logical connection that represents a single STMX. By default, the TransportLinks included in Kuwaiba are SMT1, STM4, STM16, STM64 and STM256.
2. ContainerLink It’s a logical connection that may or may not have multiple hops and connects ports within the boundaries of the transport network. A ContainerLink ends where at least one TransportLinks ends, but in its path, the ContainerLink may have used many TransportLinks. In simple terms, a ContainerLink is an SDH virtual circuit. By default there are 5 types of ContainerLinks defined: VC12, VC3, VC4, VC4-04 and VC4-16. The latter two provide support for concatenation.
3. TributaryLink Objects of this type are not circuits themselves, they rather use actual virtual circuits (ContainerLinks) and end in the ports where the SDH service is delivered to the customer (usually tributary ports).

Figure 1. Sample multi-hop SDH circuit and its relationships with services, customers and physical resources

In short, Transport and ContainerLinks provide the foundations for the hierarchy, while the TributaryLinks provide information about where the circuits are delivered (that is, what are the endpoints of the connections).

Creating an SDH view

To create an SDH topology, go to the menu option Figure 2.

Figure 2. SDH Module

This will open an empty canvas similar to the Topology Designer.

Figure 3. SDH canvas

The table below lists the tools and their description:

Tool	Description
	Open SDH view
	New SDH view
	Remove view
	Add devices
	Remove from database and view
	Remove from view
	Export as image
	Connect

Using the tool to add devices add the equipment you need Figure 4.

Figure 4. Add devices window

Let’s consider this 4 equipment topology Figure 5.

Figure 5. Some routers and multiplexers in an SDH topology

What we are going to do is to create a ring using STM-4 on one branch and SMT-1 on the other. We will create a VC12 between SDH-87 and Router 1. Each equipment has the same board/port layout: Two boards Figure 6, a tributary and an aggregate one, with two ports each Figure 7.

Figure 6. Board layout

Figure 7. Port layout

Creating TransportLinks

First, we have to create the most basic support, that is the TransportLinks (STMX). Use the connect tool and drag a line from one equipment to the other. That will start a wizard Figure 8.

Figure 8. Select connection type window

The first step of the wizard will request for the basic information: name and type Figure 9

Figure 9. Creating a TransporLink, step 1

The second will request the connection endpoints, which will always be aggregate ports.

Figure 10. Creating a TransporLink, step 2

After repeating the procedure three more times, the ring will be finished. In the Figure 11

Figure 11. SDH ring

Creating ContainerLinks

The next level in the hierarchy is the set of structured high-order circuits (VC4) that will contain the E1s that we will add later. We will create three VC4: A long one, from SDH-87 to Router 1, a short one, from SDH-87 to Router 2, and finally another short one between Router 2 and Router 1. This will provide two paths to route the E1s later on. To create the VC4 connections (a.k.a. ContainerLinks). To create the first ContainerLink using the Connection tool , let’s drag a line between the SDH-87 and the Router 1. That will start a wizard.

Figure 12. New ContainerLink, step 1

Again, the first step is about basic information: Container name and type. We will create a simple VC4. The next step is about routes. You will find two routes. In the center panel, the detail of the chosen route will be displayed.

Figure 13. New ContainerLink, step 2

The next step will ask you to define what timeslots you will use from each TransportLink in the route Figure 14. To select the timeslot from the list. This list will be populated with the available timeslots, but it will also inform you what timelots are already in use and who’s using them.

Figure 14. New ContainerLink, step 3

It’s not necessary to select any endpoint ports, since they’re taken from the underlying TransportLinks. Once created, you won’t see anything different in the view, since the only connections to be displayed are the TransportLinks.

Creating TributaryLinks

The last step is to create a TributaryLink, that is, the actual E1 to be delivered. For that, we have to press the connection tool . As usual, drag a line between the end equipment, in this case, SDH-87 and Router 1. This will open another wizard.

Figure 15. New TributaryLink, step 1

In the next step, you will be requested to pick a route. Note that the STM4-based route won’t be offered, as it doesn’t have ContainerLinks to transport the TributaryLink.

Figure 16. New TributaryLink, step 2

The third step consists of choosing the timeslot in the ContainerLink (VC4)

Figure 17. New TributaryLink, step 3

The next step is choosing the endpoints. For this example, we’re going to end the SDH connection in a tributary port of a PDHBoard. It could, of course, end in any port of any board, however this is the most common scenario.

Figure 18. Choosing the endpoints

Finally, as an option, you can associate the newly created TributaryLink to a service instance. Note that this list will be populated only with objects of subclasses of GenericSDHService previously created in the Service Manager, as seen in the Figure 19.

Figure 19. Optionally, relating the circuit to a service

Important

As an exercise for the reader, create Container and TributaryLinks using the alternate STM4-based route.

Module Actions

Delete Transport Link

Applies to object instances of GenericSDHTransportLink subclasses.

Figure 20. Delete Transport Link

Delete Container Link

Applies to object instances of GenericSDHContainerLink subclasses.

Figure 21. Delete Container Link

Delete Tributary Link

Applies to object instances of GenericSDHTributaryLink subclasses.

Figure 22. Delete Tributary Link

Software Manager

This module manages software licenses and associates them to existing inventory objects or keeps them in a temporary location until they are actually used. A software license can only be associated with instances of subclasses of the GenericApplicationElement class.

Figure 1. Software manager structure.

The graph in Figure 1 shows the structure of this module. First, licenses are grouped into license pools. That is, a pool stores or groups licenses. The licenses belonging to such a pool have a special relationship (RELATED_TO_SPECIAL) called licenseHas with inventory objects.

To access this module locate in the menu at the top the logic section, marked with the icon , when you select it a vertical menu is displayed, where you must select the Software Manager option.

Figure 2. Access to the module.

Subsequently, the selected module will open in a window, as illustrated in Figure 3.

Figure 3. Software manager module.

Figure 3 presents a Manage Licenses button and a search engine.

• By selecting the Manage Licenses button, a pop-up window similar to the one displayed in Figure 4 opens, in which the existing license pools can be viewed. In addition, it is possible to add new pools by selecting the New License Pool button, which will open a new window requesting the necessary information for the creation of the new license pool (see Figure 5).

  Figure 4. Manage licenses.

  Figure 5. Create license pool.

  The data requested for pool creation includes the pool name, a description and the type of pool to create, which can be: SoftwareLicense, USBTokenLicense or a third type called GenericSoftwareAsset which encompasses the two types mentioned above.

  The list of pools in Figure 6 contains the pool created earlier and a default pool called default license pool, the latter belonging to the GenericSoftwareAsset type.

  Figure 6. List of pools.

  The two options shown in Figure 6 will be available in front of each pool created. The button deletes the selected pool, while the button allows you to create a license within the pool, as shown in Figures 7 and 8.

  If the license pool where a new license is going to be created is of the GenericSoftwareAsset type, the license creation will allow to choose between the SoftwareLicense and USBTokenLicense license types (see Figure 7). On the other hand, if the pool type is not generic, the license type will already be defined and cannot be modified (see Figure 8).

  Figure 7. Creation of license in pool of type GenericSoftwareAsset.

  Figure 8. Creation of license in pool of non-generic type.

  If in Figure 6 you select a pool of interest, all the licenses contained in that pool will be displayed, along with detailed information about the pool, as indicated in Figure 9.

  Figure 9. Licenses contained in the selected pool.

  Note The licenses shown in different colors, as well as the prefixes observed in each, as indicated in the blue box in Figure 9, are validators associated with the licenses. For more information, please refer to the Validators chapter.

  To obtain more information about each license, select one of interest in Figure 9. On the right side of the screen, information related to the selected license will appear, as shown in Figure 10. These properties can be modified by double-clicking on the value of the property you wish to change; then, enter the new value and press the Enter key.

  Figure 10. Selected license information.

  Below is a brief explanation of the license attributes:

  • name. License name.

  • state License status. ListType attribute (for more information, see chapter List Type Manager).

  • licensedDevices. Number of devices that can be licensed.

  • serial. license serial.

  • type. Type of license.

  • version. License version.

  • purchaseDate. Date of license purchase.

  • expirationDate. Expiration date of the license.

  • creationDate. Date of creation of the license in the inventory.

  • active. Indicates if the license is active or not.

  • vendor. License provider.

  • price. Cost of the license.

  • constraints. Restrictions.

    In front of each license is the button that deletes the license and the button that deletes the relationship between the license and all inventory objects that use the license.

• In the search engine shown in Figure 3, you can search for licenses by product name, by object or by license name, as shown in Figure 11.

  Figure 11. Search for license.

  To get more details on a specific license, select it. In the central part of the screen, the inventory objects that use the license will appear, along with some options that will be explained below.

  Figure 12. Inventory objects related to a license.

  • If you select one of the inventory objects listed in the figure above, the licenses to which the selected object is related will be displayed.

    Figure 13. Licenses related to an inventory object.

    The options presented in Figure 13 are detailed below:

    Figure 14. License options related to an inventory object.

    • To view the Object Options Panel of a specific license, select , this will open a new tab with the Object Options Panel of the selected license. For more information, see the Navigation chapter.

    • The button displays additional license information.

      Figure 15. Additional license information.

    • To remove the existing relationship between the inventory object and the license, I selected the button .

    • You can view existing reports related to a license through the icon (See more in Reports chapter).

  • You can open the Object Options Panel of the selected inventory object, through the button presented in Figure 12.

  • To view additional information about the inventory object, select , which opens a window similar to the one shown in Figure 15, indicating the object's identifier, the class it belongs to and the path to its containment.

  • The button removes the existing relationship between the inventory object and the license selected in Figure 11.

To relate an inventory object to an existing license, locate the Object Options Panel of the inventory object (you can access it through the Navigation module) and go to the advanced actions of the object, where you will find an action named Relate to License.

Figure 16. Advanced object actions.

Subsequently, a window will open where you can select the license pool to which the license you are interested in belongs and then choose the specific license. When you click on the OK button, the license will be linked to the object.

Figure 17. Related license to inventory object.

Service Manager

The Service Manager allows you to organize all the services in pools. These pools of services belong to customers, these customers are at the same time organized in pools. To open the Services Manager look at the menu Figure 1.

Figure 1. Service manager module

To start using the Service Manager you must create a pool of customers Figure 2; depending on the loaded data model you can create pools of any subclass of GenericCustomer (see Data Model Manager if you need to create a different kind of customers).

Figure 2. New customer pool

1. Click the Manage Customer Pools button.
2. Click the New Customer Pool button.
3. Set the name.
4. Click the OK button.
5. Click the Close button.

Once you create your pool of customers you can create new customers, delete the created pool or show its id or search; as you can see in the Figure 3 you are able to create new customers with type any subclass of GenericCustomer.

Figure 3. New customer

1. Click the New Customer button.
2. Set the type.
3. Set the name.
4. Click the OK button.

Why can we create new customers of the class TelecomunicationsOperator if the class of objects of the pool we created was GenericCustomer? Well, we can create customers of that class because TelecomunicationsOperator is a subclass of GenericCorporateCustomer and GenericCorporateCustomer is a subclass of GenericCustomer - this is defined in the data model Figure 4, (see Data Model Manager if you need to adjust the model to your needs).

Figure 4. GenericCustomer subclasses

Now you can create a pool of services inside a customer Figure 5 or delete the customer or show its id or search.

Figure 5. New service pool

1. Select customer.
2. Click the Manage Service Pools button.
3. Click the New Service Pool button.
4. Set the name.
5. Click the OK button.
6. Click the Close button.

Every pool of service has a name and a description, these properties could be changed later in the property sheet Figure 6, just selecting the pool of services and editing the values of its attributes.