RIB version 2 Documentation


 

Manage Objects


The "Manage Objects" tab gives access to the part of the RIB interface that manipulates objects. An object is a collection of information pertaining to one of the classes in the repository's data model. New objects can be created or imported, and objects already in the repository can be edited, viewed, deleted, or have their approval status changed.

Click on the "Manage Objects" tab, and the list of classes in the repository's data model will be presented in a drop down menu. Choosing a class to work with will start the Object Browser. See help documentation on Manage Objects / Object Browser for more information.  

Object Browser


Clicking on the "Manage Objects" tab brings up a choice box which allows selection of the class of objects to be managed. After choosing the class, use the Object Browser to manage objects of that class. The components of the Object Browser are listed below, along with a description of how to use them.

A.) Class choice box:
Choose the class that you want to work with in the class choice box. This choice box may be used at any time to change the current class selection.

B.) Create button:
Click the "Create" button to create a new object of the current class. This will start the Object Editor (see help documentation on Manage Objects / Object Editor).

C.) Import button:
Click the "Import" button to import an object of the current class from another RIB repository. See help on Manage Objects / Importing Objects for more information.

D.) Name bar:
Left-click "Name" to see the class objects in alphabetical order; SHIFT+left-click for reverse alphabetical order.

E.) Last Modified bar:
Left-click "Last Modified" to arrange the class objects by date (& time) modified - oldest first; SHIFT+left-click for reverse order.

F.) Status bar:
Left-click "Status" to have the 'approved' class objects listed first; SHIFT+left-click to have the 'not approved' objects first.  

Creating Objects


Under the Manage Objects tab, choose the class of the object to be created, then click the "Create" button. Clicking this button will start the Object Editor.

See the help documentation on Manage Objects / Object Editor for more information.  

Importing Objects


Importing an object provides your repository with a snapshot of an object from another RIB repository. The data that you capture by importing an object is a static copy of the information maintained by the remote repository, so changes made by the other repository after you have imported the object will not be reflected in your catalog. On the other hand, interoperating with the other repository ensures that the information appearing in your catalog always stays current with the metadata in the remote repository. See help on Interoperations for more information.

To import an object, choose the "Manage Objects" tab and then choose the object's class. Next click the "Import" button. When the dialog box appears, type in the url where the object can be found on the Internet. After the object has been retrieved, it will appear in the Object Editor (see the help documentation on Manage Objects / Object Editor). At this point you can make any desired changes to the object and then save it in your repository. If the imported object is missing any attributes or relationships required by your repository's data model, then you will need to supply values for those fields before RIB will allow you to save the object. If your repository and the repository which contains the object have very different data models, then importing the object may not be possible. This often results in an error message that says that the object contained no useful information.

Note: Importing an object is not a recursive operation. That is, importing an object will not automatically import any objects pointed to by its Relationships. Those objects must be imported separately, if desired.  

Editing Objects


Under the Manage Objects tab, choose the class of the object to be edited. Select (left-click) the object to be edited. Right-click the selection, and a menu will appear. Choose edit. The object will appear in the Object Editor. Double clicking an object will also bring it up in the Object Editor.

See the help documentation on Manage Objects / Object Editor.  

Deleting Objects


Under the Manage Objects tab, choose the class of the object to be deleted. Select (left-click) the object(s) to be deleted. CTRL+left-click toggles the selection on individual objects and SHIFT+left-click allows you to select a range of objects. Right-click your selection, and a menu will appear. Choose delete.

When an object is deleted, any objects which pointed at the deleted object via a Relationship will now contain a stale pointer. RIB will automatically detect these stale pointers and will delete them from the affected objects. Note that this can cause an object to lose a Relationship which is required in your data model. Remote objects (objects not in your repository) which pointed at the deleted object via a Relationship will contain a stale pointer.  

Viewing Objects


To view an object in your repository, click the Manage Objects tab and choose the object's class. Select (left-click) the object that you wish to view. Next right-click the selection and a popup menu will appear. Choose "View" and select the format that you wish to view the object in - either HTML or XML.

Viewing the object in HTML format shows you what the object looks like in your reposiory's catalog. (Note: if the object has not been approved then it may not appear in your catalog. See help on Manage Objects / Object Status for details.) Viewing the object in XML format is only possible in browsers which support XML. As of this writing only MSIE 5.0 supports XML. The object will be displayed in a new browser window spawned by the RIB applet. If you are running the RIB applet in an non-browser appletviewer (e.g. Sun's appletviewer) then this operation will not function correctly.  

Object Status


If the object approval feature is enabled for your repository then only objects that have been explictly approved will appear in your repository's catalog, be returned from your repository's search pages, or be available for interoperation. If the object approval feature is not enabled for your repository then changing an object's status has no effect. See help on Manage Catalog / Object Approval for more information on this feature.

To approve or unapprove objects in your reposiory, click the "Manage Objects" tab and then select objects' class. Next select (left-click) the object(s) whose status you wish to change. CTRL+left-click toggles the selection on individual objects and SHIFT+left-click allows you to select a range of objects. Right-click your selection and a popup menu will appear. Choose "Set status" and select "Approved" or "Not Approved".  

Object Editor


The Object Editor allows objects of the chosen class to be created or edited. To start the object editor, click on the "Manage Objects" tab and then select the class of the object(s) to be created or edited.

To create a new object, click on the "Create" button.
To import an object, click on the "Import" button.
To edit an object, select (left-click) the object. Right-click the selection and a menu will appear. Choose edit. Double clicking an object will also load it into the Object Editor.
All of these actions start the Object Editor.

The class's Attributes and Relationships, as specified by your repository's data model, will be listed on the left side of the screen. The fields are color-coded. Required fields are shown in red. Optional fields are shown in black. Fields which have been given at least one value are shown in blue. See help documentation on Repository Properties / Data Model Editor for more information about the data model and what the fields mean.

How to use the Object Editor

Clicking on a field brings up its typein box in the workspace. Click in the box and type in the field's value, either text or a url.

What to supply for each field:
A brief description of the Attribute or Relationship should appear in the blue box at the bottom of the workspace.

 

Manage Catalog


The Manage Catalog tab allows you to change the properties of your repository's catalog and various other repository web pages. Here, the primary class and the primary attribute can be changed, and the Object approval, Joins, and The "What's New" features can be toggled on and off. Here also is where you can view the various repostitory web pages and edit your repository's templates.

Note that modifications made from the Manage Catalog area do not change the underlying data model or metadata objects maintained by your repository. They just determine how your repository looks to those who visit your repository's web site or interoperate with your repository. See help documentation on Repository Properties / Data Model Editor for information on editing the data model.  

View


To view the various web pages offered by your repository, click the "Manage Catalog" tab and then click the "View" button. Clicking this button brings up the following menu:

  Catalog
  Join
  Search
  Advanced Search
  What's New

The page that is chosen appears in a new browser window spawned by the RIB applet.  

Templates


RIB uses a template system to control the appearance of your repository's web pages. When RIB generates an HTML page, it looks for subsitution keys in your template which tell it where to place the data it generates. RIB automatically plugs in the appropriate value wherever it finds a substitution key.

The "Edit Template" button is located under the " Manage Catalog" tab. Clicking this button brings up the following menu:

  Catalog
  Join
  Search
  Advanced Search
  What's New

Clicking on one of the choices causes a new window to pop up where the template can be edited. Save the revised template by clicking the "Save" button.

At any time during editing, click the "View Substitution Keys" button to show the list of substitution keys. To dismiss the list and return to the template editor, click on the "Return to template" button.  

Primary Class


RIB uses objects from the primary class to populate your catalog. Objects from this class will be categorized by the value(s) of their primary attribute and alphabetized by their Name attribute.

The "Change" button for the primary class is located under the "Manage Catalog" tab. Note that changing the primary class will cause any remote objects currently linked into the catalog as a result of interoperation to disappear. Remote objects from the new primary class (if there are any) will be linked into the catalog the next time interoperations are updated.  

Primary Attribute


RIB uses the primary attribute to categorize object in your repository's catalog. The primary attribute must be contained in the primary class, and it must use a controlled vocabulary. It should also be a required attribute, though this is not enforced. An object without a value for this attribute will appear in the top level of the catalog. If an object has more than one value for the primary attribute, it will appear in each of the corresponding categories in your repository's catalog.

The "Change" button for the primary attribute is located under the "Manage Catalog" tab. Note that changing the primary attribute will cause any objects currently linked into the catalog as a result of interoperation to disappear. The next time that the interoperations are updated, your repository will categorize remote objects according to the new primary attribute. If the value of the primary attribute in a remote object does not appear the your primary attribute's vocabulary, RIB will use a depth first search to look for the nearest match. If a match is not found, the object will appear in the top level of your catalog.

See the help documentation on Repository Properties / Data Model Editor for information on controlled vocabularies and required attributes.  

Object Approval


When this feature is enabled, only objects which have been explicitly approved in the Object Browser will appear in the repository catalog, be returned from the repository search pages, or be available for interoperation. A practical use of this feature would be to allow one person to create objects and then let another person double check and approve them. This feature could also be used by repositories which accept input from sources of undetermined reliability.

Be aware that toggling this feature can cause the catalog to look drastically different. Double check the lists of objects under the Manage Objects tab to determine which objects will or will not be affected by toggling.

See the help documentation on Manage Objects / Object Status for instructions on how to approve/unapprove objects.  

Joins


Joins are an advanced feature of RIB. If your data model is properly configured, joins allow users to query the repository data in a special way. A class which is the intersection of two other classes can be displayed in a matrix.

For example, say there are three classes in your repository : Asset, Machine, and Deployment. Now suppose that the data model was set up in such a way that the Deployment class had a relationship to the Asset class called IsDeploymentOf and to the Machine class called IsDeployedOn. Here, the Deployment class serves as the intersection class because it has relationships to each of the other two classes. The arrangement is illustrated below:

Next an Asset object called "Software A" and a Machine object called "Machine X" are created. Software A is installed on Machine X, and then a Deployment object is created which contains relationships to the Asset and Machine objects just created. Say that the Machine class also has an attribute called Status which is given the value "Successful".

You could then go to the join creation page and enter the parameters for the join (which are described above). When the join is created, it will appear in the matrix as follows:

  Machine X
Asset A Successful

Creating more Asset, Deployment, and Machine objects could make the matrix look as follows.

  Machine X Machine Y Machine Z
Asset A Successful Incomplete Aborted
Asset B Successful Successful Incomplete

The join feature can be disabled under the Manage Catalog tab. If it is, the repository templates should also be edited to remove the reference to the join creation page. See the help documentation on Manage Catalog / Templates for information on editing templates.

If the join feature is enabled, consider replacing the default url in the template with a join that has already been constructed. Repository users might find the construction interface a little overwhelming, especially since they probably won't know the data model. To replace the default url, construct the desired join and paste the final URL from the browser into the template. If the object approval feature is enabled for the repository, objects that have not been approved will not appear in joins.  

What's New?


The What's New feature allows users to view the list of primary class objects created within the last year. Objects linked into the catalog via interoperation will also appear in the list (based on the day they were added to the catalog rather than the day they were created). The user can choose to include anywhere from 1 day to 1 year; the default is 30 days. If the object approval feature is enabled for the repository, only approved objects will appear in the What's New list.  

Interoperation


Interoperation allows repositories which use similar data models to share metadata with each other. The shared metadata objects are automatically linked into the catalog of the repository which creates the interoperation.

In the figure above, the objects maintained at Repository A are linked into the catalog of Repository B as a result of an interoperation created at Repository B. Note that the catalog links point to the *remote* objects. When someone clicks the link to view the object they retrieve that object from the repository you interoperate with, not from your repository. This ensures that the information in your catalog is always current, and also ensures that the repository which maintains the object controls its appearance and access permissions. The class of linked objects is dictated by the primary class of the repository which creates the interoperation (Repository B in the figure above).

Clicking on the Interoperation tab will show the current status of the repository's interoperations. This area is called the Interoperations browser and will be empty until an interoperation has been created. See help on Creating Interoperations for instructions on how to set up a new interoperation. The "Refresh" button contacts the RIB server and updates the list. This is especially important if more than one person administrates the repository.

The Interoperations browser shows the update interval for each interoperation. The "Last Attempt" column shows the last time an attempt was made to start the interoperation, and what the results of that attempt were. To inspect or change the properties of an interoperation, select (left-click) it and then right-click it. CTRL+left-click or SHIFT+left-click will allow selection of multiple interoperations.  

Creating Interoperations


To create a new interoperation, click the Interoperations tab and choose the "Create" button. Next choose the type of repository that will be interoperated with - local or remote. A local repository is one that is managed under the same installation of RIB. A remote repository is one that is managed by a separate installation of RIB, probably on a different server.

Interoperation with a local repository

To interoperate with a local repository, choose "Local Repository" when prompted for the repository type. RIB will then determine what other repositories currently exist under this installation of RIB. Choose one of the repositories, and pick an update interval. The update interval specifies how frequently RIB will poll the local repository to determine if its collection of objects has changed. When an object has changed, RIB will ensure that your catalog is updated. After specifying the update interval, click the "Submit" button.

Interoperation with a remote repository

To interoperate with a remote repository, choose "Remote repository" when prompted for the repository type, and then supply the repository's interoperation handle. An interoperation handle is a URL which points to the interoperation access point for a repository. The interoperation handle for the repository you want to interoperate with can be found by clicking on the "About" link at the bottom of the repository's catalog web page. Type the interoperation handle for the remote repository into the text box; type in its name, and choose the update interval. The update interval specifies how frequently RIB will poll the remote repository to determine if its collection of objects has changed. If so, RIB will mirror those changes locally. Note, unless your repository has a fast or dependable network connection to the remote repository, it is strongly recommended that a longer interval be chosen. After specifying the update interval, click the "Submit" button.

Interoperation with RIB version 1.x repositories

The interoperation handle for RIB v1.x repositories is available on the catalog table of contents page near the bottom (the link says "local Assets").  

Listing Objects


To view the list of objects that appear in the catalog as a result of an interoperation, select (left-click) the interoperation(s), and then right-click to bring up the popup menu. Choose "List objects from interoperation" from this menu. Double clicking an interoperation will also bring up its list of objects. Selecting multiple interoperations before right-clicking will show a combined list.

When browsing the list, double-click on the name of an object to open its HTML page in a new browser window.  

Interoperation Logs


Every time an interoperation runs, it saves all its diagnostic output to a log stored in RIB's database. If an interoperation appears to be having problems, check the log to determine the cause. To access this log, select (left-click) the interoperation, and then right-click the selection. Choose "View last update log" from the popup menu.  

Starting Updates


When a new interoperation is created, the chosen update interval specifies how frequently the interoperating repository will be polled. However, it is sometimes necessary to start an interoperation update manually, without waiting on RIB's interoperations scheduler to start the update. This is often the case when there is a change in the interoperating repository and waiting for the scheduled update is undesirable.

To start an interoperation update, select (left-click) the interoperation(s); then right-click the selection, and choose "Start an update". Once RIB's interoperations scheduler has been contacted and instructed to start the interoperation, the update is carried out in a background process. This allows continued use of the RIB interface while the update is in progress. Click the "Refresh" button at any time to update the interoperations list and monitor progress.  

Deleting Interoperations


When an interoperation is deleted, all objects that appear in your catalog as a result of the interoperation will disappear from the catalog. To delete an interoperation, choose (left-click) the interoperation(s) to be deleted. Then right-click the selection and a popup menu will appear. Next choose the delete option.  

Setting Update Intervals


The update interval for an interoperation specifies how frequently RIB will poll the interoperating repository to determine if its collection of objects from your primary class has changed. If so, RIB will update your catalog with the appropriate changes.

To change an interoperation update interval, select (left-click) the interoperation. You can select multiple interoperations by using CTRL+click or shift+click. Now right-click the selection and a popup menu will apper. Then choose "Set update interval", and choose a new interval. Setting the update interval to a larger value decreases network traffic between your repository and the remote repository. Setting the update interval to a smaller value generates more network traffic, but ensures that changes to the remote repository appear in your catalog sooner. Use a larger value if you expect the objects in the remote repository to change infrequently.

In order for RIB to be able to automatically perform updates, you must have set up a scheduled job on the machine where RIB is installed. On UNIX machines this is done using the "cron" system utility. Assuming that RIB is installed in the directory /usr/local/rib, simply add a line such as the following to a crontab :

0,15,30,45 * * * * /usr/local/rib/bin/updateAllInterops.pl

This will cause RIB to check the update intervals every 15 minutes.  

Repository Properties


The Repository Properties tab gives access to the part of the RIB interface that can change the name, contact, or password for the repository. This is also where the repository's data model can be modified.  

Data Model Editor


A repository's data model contains a description of the classes, attributes, and relationships that it uses. The data model editor allows the data model to be modified or viewed. To start the data model editor, click on the Repository Properties tab and then choose Data Model Editor.

The default data model for new repositories created by RIB is the Basic Interoperability Data Model (BIDM). This allows a new repository to interoperate with other repositories already using this data model. Since the BIDM has gone through the IEEE standards process and is used in other types of applications, sticking with it will most likely pay off in the long run. Unless your repository needs a specialized data model, you should try to use the default. See help documentation on Interoperation for more information on how to interoperate.

How to use the data model editor

The data model editor uses a tree structure to help visualize the repository's data model. Each class in the data model appears in its own folder. A class folder contains three subfolders : Attributes, Relationships, and Subclasses.

The topmost folder in the data model editor, RigObject, is the parent class of all classes. By default, it contains one attribute called "Name" whose properties cannot be changed because it is used internally by RIB. This attribute also cannot be overridden by a subclass - otherwise, its properties could effectively be changed in the subclass. The RigObject node cannot be deleted.

When finished editing the data model, click the "Save" button to save the changes. The data model will be saved on the server. Any objects already present in the repository will be modified if necessary to fit the new data model. For example, if a class is deleted from the data model, all objects of that class in the repository will be deleted. Also, any relationships that pointed at objects of that class will be deleted. Warning changing the status of an attribute or relationship from "optional" to "required" does not automatically create a value for that field for objects already in the repository. This means that each object would need to be manually edited to add a value for the required attribute or relationship to ensure conformance to the data model.

Vocabularies

A vocabulary is a collection of terms. A term usually contains less than ten words. A term can contain subterms, further refining its value. An attribute that uses a vocabulary can only contain values from that vocabulary. Add a vocabulary to an attribute by right-clicking on the attribute and then selecting "Add a vocabulary term". To delete a vocabulary term, or to add a subterm, right-click on the term.

If the vocabulary for an attribute is modified in any way, all objects in the repository that contain a value for that attribute will be modified as necessary to make sure that the existing value can be found in the new vocabulary. If it cannot be found in the new vocabulary, a depth first search will try to locate the closest match. If this search does not find a match, the value of the attribute will be set to null. The object will then appear in the top level of the catalog, if the attribute is the primary attribute. See help on Manage Catalog / Primary Attribute for information about the primary attribute.

Importing a data model

Import a data model from another repository by clicking on the "Import" button. You will be prompted for the URL where the data model can be downloaded. When the download has completed, the data model that you were editing will be transformed into the new data model. In some cases, you will want to import the data model from a repository that you plan to interoperate with. (See help documentation on Interoperation). The URL for a repository's data model can be found on the top page of its catalog (unless it was intentionally removed from its catalog template). See help documentation on Manage Catalog / Templates.  

Repository Name


The repository name appears in the repository web pages anywhere a template uses the REPOSITORY_NAME keyword. See help documentation on Manage Catalog / Templates for further information. To change the repository name, click on the Repository Properties tab and select Change Name.

The name can contain any characters, and should be something descriptive. When it has been typed into the dialog box, click the "Submit" button.  

Repository Contact


The repository contact is the email address where questions or comments about the repository should be sent. The contact address appears in the repository web pages anywhere a template uses the REPOSITORY_CONTACT keyword. See help documentation on Manage Catalog / Templates for further information. To change the repository contact, click on the Repository Properties tab and select Change Contact.  

Repository Password


The repository password is used to control access to the repository administration area. To change the repository password, click on the Repository Properties tab and select Change Password. The password should contain at least six characters.  

Errata