Version Control and Distribution System

The following terms used in this document are trademarked properties of their respective owners:

NETeXPERT and VSM are trademarks of Objective Systems Integrators. Java is a trademark of Sun Microsystems, Inc.

Windows is a trademark of Microsoft Corporation.

All other brand or product names are trademarks or registered trademarks of their respective companies or organizations.

The System Tree View panel displays all NETeXPERT systems registered with VCDS. A folder is displayed for each NETeXPERT system.

All System Tree View nodes are color coded and provide textual indication of the VCDS agent status. In addition to the “ACTIVE” state (green), the status may be “FAILED” (red) or “INACTIVE" (orange).

An “ACTIVE” state indicates that the agent is running and communicating with the VSM system. The “FAILED” state indicates that the agent was not shutdown gracefully. An “INACTIVE” state indicates the agent was shutdown gracefully, probably from a shutdown message issued from the VSM system.

Each system node can be expanded by:

In the menu, select Expand All to open the folder. This displays the objects in a hierarchical view.

Each object icon is color-coded to indicate how it compares to the most current version in the repository. There are three possible color states: green if the object contents are identical to the version in the repository, red if it differs, and magenta if it does not exist in the repository.

In the System Events Tree View, manager class folders can contain three types of event folders; Regular Event, Context Event, and XML Event.

In the example below, the vsm60 system is selected. The LSFT manager class folder is open, displaying the Regular Event folder, which contains eight events.

Selecting objects in the System Tree View displays them in the <object> Module View, discussed in Chapter 6 of this guide. For more information on the Module View, see Chapter 6, Module View.

Four tabs are located above the System Tree View, one for each supported object (events, methods, dialogs) and the repository, labeled VCS (Version Control System). Selecting a tab displays the tree view for that object type.

The Tree View drop-down menu is used to change the Tree View display. You can create new custom tree views. However, the Default Tree View configuration cannot be edited.

The folders in the Default configuration are:

To create a custom tree view:

The <object> Tree Views configuration window opens.

An Add Tree View dialog box opens.

Entries such as Class, Module Name, and Description can now be added to the View Configuration panel to define the hierarchy of the new view.

Note: Some entries are more appropriate for one view than another, depending on the available data. For example, File Name is a valid entry for the Repository Tree View, but it is not logical for the System Tree or Module Views. Other examples are:

The graphic below shows a Not Found folder as an example of an entry without a value.

VCDS does not prevent you from adding illogical or invalid entries.

Use the red minus sign (-) button to remove View Configuration entries.

You can also remove Tree Views using the minus sign (-) button below the Tree Views panel.

3.3.1. Entry Options

The View can be modified further in the Entry Options panel. Configuring this panel filters the displayed view to match the Entry Options configuration.

You can create a filter that modifies the view by using the Field: drop-down menu and the Filter Pattern: text entry field. After selecting a Field to filter on, enter a match string or regular expression.

Matching entries are included or excluded according to the selected Include or Exclude radio buttons. The From Char: and To Char: fields can also be used to filter on a range of column or character numbers.

After clicking the OK button to save, you can change the VCDS Tree View display using the Tree View drop-down menu.

NOTE: Changing the Tree View configuration can take minutes, depending on the number of objects that require sorting. While the resorting is taking place, a message appears in the lower left corner of the screen asking the user to “Please wait… applying new tree configuration”.

The Tree Operations menu is accessed by right-clicking on the tree nodes or individual objects. Selecting an item from this context menu affects all objects under the node from which the context menu was selected.

For example, if the context menu is initiated from the top level “Default” tree node, the chosen action affects every object on all systems. If the context menu is initiated from a single system tree node, the chosen action affects every object under that single system.

NOTE: It is not possible to take actions from the context menu on multiple nodes in the tree. The action only takes place on the node where the context menu was raised.

The System Tree View context menu items are:

The Repository Tree View displays all objects residing in the repository with the latest version number displayed to the right of the object icon.

The default Tree View configuration is Module & Path where Module is the name of the module in CVS, and Path is the directory path to the object in the repository. In the above example, the module name is nxidetest.

The Repository Tree View is used to view the latest version of an object. In the Repository Event tree view example below, the VCDSTestEvent event is selected. The latest version number, 1.9, is displayed beside the name.

You can add new directories to the repository to further organize the tree.

To add a new directory:

The Add Repository Directory window opens.

The directory is added to the repository.

The new directory is not displayed in the Repository Tree View until you commit an object to the directory. After committing an object to the new directory, the directory is displayed in the Repository Tree View.

You can create new directories to organize your repository of NETeXPERT objects in ways that makes sense to you. Organization categories might be by NETeXPERT manager class, geographic location, technology type, device name, vendor, or any other logical category you wish to use. Manager Class is one of the most commonly used categories.

The object type view is changed by selecting a tab above the System Tree View.

The VCS Repository tree view displays all objects in the repository - events, methods, and dialogs. The top-level folder identifies the location and name of the CVS working directory. In the example below, the CVS working directory is work, and is located on the C drive. It contains the module nxidetest.

The Repository Tree View context menu items are:

New Repository Tree Views can be created and edited as discussed in Section 3.3, “Creating a Custom Tree View”.

The VSM <object> Module View displays information about each object in your VSM systems. Selecting a node in the System Tree View displays all objects under the node in the VCDS Module View. Selecting a single icon in the Tree View displays the single object in the Module View.

Object information is displayed in columns. The Total Count: is displayed in the lower right of the panel, and the Selected Count: of objects is displayed in the lower left.

In the System Events Tree View below, the Regular Event folder is selected. It contains four event icons.

The four events are displayed and one event is selected in the Module View.

In the above example, the Selected Count: is 1 and the Total Count: is 4.

The colors in the Module View have the same meaning as those in the Tree View:

A column or field Filter panel is available in the Module View to modify the display.

The Filter functions as you create it.

The red button is used to Reset the filter to the previous setting.

The Filter example below shows the Event field specified with Da.* as the regular expression to match and the Include radio button selected. The regular expression is applied to the selected field, or Module View column, Event. All events that have a name in the Event column that matches the regular expression pattern are displayed in the Module View. The result in this example is the single event named DavidEvent.

The Repository Status buttons are another way of filtering the Module table display. From left to right, the buttons select objects that are the same as the repository (green), different from the repository (red), or do not exist in the repository (magenta).

When a button is clicked, a red ‘X’ is displayed on the button and all objects matching that state are hidden from the display.

In the example below, there are four events; two matching the repository, and two that differ.

In the next example, we see that the first button is selected and has an ‘X’ on it, and the events that are identical to the repository (colored green), CA_OpenAlert2 and OpenAlert, are hidden.

You can create a custom Module View, or Table View, using the custom configuration button next to the Table View: drop-down list. The process is the same as customizing Tree Views as described in Section 3.3, “Creating a Custom Tree View”.

Clicking the custom configuration button displays the Event Table Views window. Table Views are listed in the lower left of the window. The Default table view may not be edited.

Selecting a table view displays its Entry items in the View Configuration panel. Selecting a View Configuraton Entry item displays it in the Entry Options panel in the lower right of the window.

To add a new item, click the green plus (+) button. To remove an item, click the red minus (-) button.

You can order the sequence of the View Configuration list using the blue up and down arrow buttons.

Note: The Entry Options panel is not used when creating Table Views.

The Information View displays additional information about the selected object - event, method, or dialog. Double-clicking an item in the Module View populates the Information View with the object’s configuration.

In the example below, information about the VCDSTestEvent2 is displayed. For events, this information includes:

The event rules are displayed in tabs. The example below shows the ID Rule tab selected.

Immediately below the rule tabs is a Show Parent Rules check box. If checked, the parent event rules are displayed (if they exist).

The View Type can be displayed as Textual or Tabular by selecting the desired radio button.

When displaying object information, VCDS displays a tab containing the object name below the Information View. You can display multiple object configurations, resulting in the display of multiple tabs, allowing you to navigate among the different objects' configuraton information by selecting a tab.

The Method Information View displays:

The View Type radio buttons and displaying multiple object name tabs functionality is the same as for events as described above.

Double-clicking a dialog in the Module View displays the dialog architecture in the Information View. The dialog name TestDialog is displayed in tabs above and below the Information View in the example below.

Double clicking a dialog Command State or Response State displays its configuration details. In the graphic below, the TestDialog TestCommand1 State is displayed. A tab is displayed at the top of the panel for each Command and Response that is opened.

Here the TestDialog DialogResponse1 Response State is displayed.

Selecting Compare to… displays a Select <object> window listing other objects with the same name in other systems (if they exist).

Selecting one of these objects and clicking the OK button displays a Compare: window with differences highlighted in a color code. The names of the compared objects are displayed in the window title bar. The originally selected object is displayed to the right in the window.

In this example, Gateway Analysis rules are color-coded as having been added (blue) and Event Analysis rules as having been modified (red).

The color coding legend is displayed in the lower left of the window and is as follows:

Selecting Compare to Repository in the context menu opens the Compare: window with version differences highlighted and color-coded. The originally selected object is displayed on the right side of the window. In the example below, you can see that compared to the version in the repository, a Gateway Analysis rule comment has been removed from the selected object, as indicated by the green color coding.

VCDS tracks the version history of objects only if they are put into the repository. This is done using the Commit function. VCDS saves the system version to the repository and automatically assigns it a new version number.

The very first time an object is committed to the repository it receives the version number 1.1. Each subsequent version number is incremented by .1. This numbering is not configurable.

To commit a version to the repository:

1. Select the object in the Tree View or the Module View and right-click to open the context menu.

2. Select Commit. Upon selecting Commit, VCDS displays a Commit Log Message dialog.

3. Enter the reason for the creation and commitment of this version and click the OK button. The Please Login dialog opens. You can commit without entering a log message (which is discouraged). If you click the OK button without entering comments, the Select an Option dialog opens.

Clicking the Yes button displays the Please Login dialog.

4. Enter your CVS user id and password and click the OK button. Your user id is recorded by VCDS and displayed as part of the version history record.

If the object name does not already exist in the repository, clicking the OK button opens a Select Repository Directory window.

5. Select the directory where you wish to store the object and click the OK button.

VCDS commits the object to the selected repository directory. If the object already exists in the repository, VCDS commits it without displaying the Select Repository Directory window. When the commit process is finished, VCDS displays the final commit status in the lower left corner of the VCDS GUI.

Note: Add to Package... and Review Dependencies are discussed in Chapter 9, VCDS Packages

It is simple to deploy objects to other VSM systems using the Deploy… function.

To deploy an object to a NETeXPERT system:

The Deployments panel displays:

A successful deployment is indicated by the time stamp and (Finished) line displayed in green text.

The Auto-clear check box is not checked by default. When checked, closing the window clears the display.

A failure in the deployment is indicated by red text.

Selecting the failed object displays an error message in the Selected Status Message panel.

In the above example, an alert or event does not exist in the target system.

Errors in deployment can result for various reasons. For example, deploying an object into a system that does not contain the correct manager class causes the deployment to fail.

Selecting the Replace with… option opens a dialog box with a list of versions in other systems and the repository from which to select a replacement for the selected object version.

Upon selecting a replacement version and clicking the OK button, the Deployment Status window opens, and the replacement version is deployed to the original object’s system. A successful deployment displays the time stamp in green followed by Finished.

This selection is used when you wish to replace a version in your NETeXPERT system with the latest version from the repository.

The Deployment Status window displays the progress and result of the replacement.

Use this option to quickly locate an object in the Tree View. This example uses an event to illustrate this function.

The same functionality exists for methods and dialogs.

Package creation involves these steps:

You can later modify the contents of the package as needed. If you modify any object in the package, you must commit the modified objects to the repository, and then update and commit the package.

To create a package:

The package icon changes to green and the initial version number of 1.1 is displayed.

Packages can be modified by adding objects manually or auto-populated with updates based on specific parameters.

You can add objects to the package from the system tree view or module table view. Events, methods, and dialogs must be stored in the repository before they can be added to a package. Some non-repository objects can be added to the contents of a package as well. For example, attributes and attribute types can be added to a package. See Section 9.5, “Dependencies” for more information on this.

Only repository objects can be added to a package. If you select an object from the system tree or module view that is displayed as different from the repository (red), and add it to the package, the latest version stored in the repository is added to the package. If you wish to add an object to the package that is not in the repository, you must first commit it to the repository before you can add it to the package.

To add objects to the package:

The object is added to the package. Because it is now different from the committed version in the repository, the package icon in the VCS tab tree is red.

To view the contents of a package or any of its versions:

The Package Information view displays Name and Description panels and a Contents panel.

The Contents panel displays package contents in a hierarchical tree view. The tree is organized by Package Administration export object types.

You can simultaneously view different versions of the same package.

You can remove single nodes or objects from a package or select individual objects for removal.

To remove items from package contents:

Since it is now different from the repository, it changes to red.

Note: If you remove an object from a package and add an object without first saving the package, the following message displays:

The resulting package contents will not reflect the object removal, so use caution when removing objects from a package without saving prior to taking additional action on the package.

Only those events, methods, and dialogs stored in the repository can be added to a package. Use the Review Dependencies feature to check the repository status of objects prior to their package addition and to view object references such as attributes and alerts. Successful package deployment requires that the referenced items already exist in the systems to which you are deploying unless you can include them in the package to be deployed.

An object may contain references to other objects, such as attributes or alerts, that may not exist in the system to which you intend to deploy. This can be checked prior to deployment. This is easily done by reviewing dependencies, as these object references are included in the Review Dependencies results.

Package-specific objects are attributes and attribute types, and they can be added to a package from the Review Dependencies window even though they are not stored in the repository. This is a convenient way to assure these object references are included in a package.

The following example checks dependencies for the VCDS class. All objects defined in the class are evaluated.

To review dependencies:

This window displays objects in the selected class with the number of objects found in and missing from the repository and referenced objects that are package specific.

Package specific objects are attribute/attribute type references found in events, methods, and dialogs.

In the above example, there are 6 VCDS class objects in the repository, as indicated by Found: 6 in green text, 4 objects missing from the repository as indicated by Missing: 4 in red, and 17 Package Specific: objects in blue text.

There is also an Alerts folder containing alert references in the events, methods, and dialogs in the window. These cannot be added to a package using VCDS unless they are stored in the repository. VCDS lists them for your convenience.

To add alert definitions and types to the CVS repository, use NETeXPERT Package Administration to export these objects into the VCDS working directory. Here you can use the CVS add command to add these objects to the repository.

The Alerts, MOs and Rules folders are Package Administration export file categories. The Alerts folder contains alert definitions and alert types referenced by the selected object(s). They are not in the repository, and as such are included in the Missing count. The MOs folder contains Attributes and Attributes Types referenced in the events, methods, and dialogs as well as those of the class. The Rules folder includes events, methods, and dialogs.

You cannot add any Missing Dependencies to a package.

You can also view these objects as a color-coded list in the Review Dependencies window by opening the object folders. Right-click on a tree node to display the Dependency Tree Operations menu and select Expand All.

Below is an example showing the dependencies for the event VCDS.LSTestEvent2.

In the above example, there are 4 objects missing from the repository, and these cannot be added to a package. They are displayed here for your information. The package-specific objects, attributes and attribute types, can be added to a package, even though they are not in the repository. (Attributes and attribute types are an exception to the rule.)

The Dependency Tree Operations menu displays these functions:

9.5.1. Creating a Package with Dependencies

You can create a new package directly from the Review Dependencies window.

All found dependency objects that are in the repository and those that are package specific are automatically included in a new package if the Create Package button is clicked or if Create Package with All... is selected in the Dependencies Tree Operations menu.

1. Either action opens the Create Package dialog to enter the package name and enter a description.

2. Enter the package name and a description and click the OK button. The Select Repository Directory window opens.

3. Select a directory for the package and click the OK button.

The new package is displayed in the VCS tab in red, as it has not yet been committed to the repository.

4. Commit the new package to the repository.

9.5.2. Adding Dependency Objects

You can also add dependency objects to any existing package.

1. Click the Add to Package... button or select Add All to Package... in the Dependencies Tree Operations menu to add dependency objects in the window to a package. Either selection adds all found dependencies and package specific dependencies to the package.

This opens the Select a Package Definition dialog.

2. Select a package definition and click the OK button. The Add to Package confirmation window opens, listing the dependency objects found in the repository for package addition as well as package specific objects, such as attributes and attribute types.

3. Click the OK button to add the objects to the package.

4. Commit the newly populated package to the repository as described above.

If all objects are already contained in the package, the following Message is displayed:

9.5.3. Adding Selected Objects to a Package

You can add selected objects to a package or create a new package with selected objects using the Dependencies Tree Operations menu.

Use the Control key to select individual objects in the Dependencies tree. Select Add Selected to Package... or Create Package with Selected... to add to or create a package with selected objects.

Making a selection displays the Select a Package Definition or Add to Package dialog, and the addition or creation process is performed as described above.

Deploying a package is done in the same way as other objects are deployed in VCDS.

To deploy a package:

Selecting Deploy Package Revision... from the from the version history list enables you to deploy any package version.

If there is a failure in the deployment, the (Finished) line is diplayed in red.

Opening the folders reveals where the problem occurred. Selecting the failed item displays an error message. In this example, an alert definition did not exist in the target system.

Over a period of time, the contents of a package may become out-of-date and may not contain the most current object versions in the repository.

To update a package with the most current content versions:

The package icon turns green and its version number is incremented by .1 .

Just as you can use VCDS to compare versions of NETeXPERT events, methods, and dialogs, you can also use VCDS to compare versions of packages.

To compare different versions of a package:

This window displays the first selected package as the Target and the second selected package as the Source. The contents of each package are displayed in a hierarchical tree.

New Entries and Removed Entries are listed for the Source package, while Updated Entries and Same Entries are listed for the Target package.

In the above example, package NewPack (rev. 1.5) is selected as the Target and NewPack version (rev 1.4) is the comparison Source.

The NetExpert.TestDialog was added to version 1.4, and is listed as a New Entry. The TestDialog appears in the NewPack version (rev. 1.5), and the events appear as Same Entries.

In the example below, the VCDS.LSTestEvent (rev. 1.6) has been updated to a newer version, (rev. 1.7), which is displayed in the Target panel.

Patches are a convenient way to deploy and manage differences between package versions. These differences can be events, methods, or dialogs, or dependency differences, such as attributes. The advantage of using patches is they enable you to deploy fewer objects when updating systems, so you need not deploy an entire package.

When comparing packages, you can capture the differences between package versions in a patch. The differences are objects that have been added, removed, or updated.

This patch is committed to the repository and managed with version control just as any other object in the repository - it can be deployed and its contents can be updated.

To create a patch:

You can double-click the patch to view its contents in the Information View as shown below.

You can manage patches in a similar way that you manage packages - that is, you can deploy, update and take the same actions that you can perform on packages as described above.

The following workflow demonstrates how one may use VCDS packaging. (There is no specific workflow pattern enforced or required by VCDS.)

This ensures the objects in your development system are in sync with the currently released version of the ruleset package. You can compare objects using the VCDS diff tool to verify their configuration and/or merge any differences, or simply update the development system with the latest versions from the repository.

As development progresses, changes are reflected in the VCDS UI.

After committing, the development system objects should be the same as those in the repository. Any discrepancies may be caused by other developers, so communication among all those committing to the repository is important.

In the VCDS UI, update the package with the current versions of modified objects. At this point the package will be red in color, as it has not yet been committed to the repository. This should be a signal to any developer to NOT deploy this package, since it is not yet under version control.

After completely updating the package, deploy to the test system. During testing, bugs may be fixed and the package updated as normal (steps 2 – 5) and redeployed to the test system.

Once testing is completed and accepted the package is committed. Once committed, the package is considered to be the latest and most current release.

For deployment into production, the entire package may be deployed or the user doing the deployment may perform a patch deployment from the UI. To perform the patch deployment, the user opens the current package in the VCS tab of the VCDS UI and selects the option to compare the current package with the previous release (revision) of the same package. The UI presents the differences between the two packages and the user selects the option to deploy the differences to target systems. If deemed appropriate, a new package may be created that contains just this patch. Patch packages should be named appropriately for easy identification by users.

VCDS has an audit feature that compares the Repository with a user-selected VSM system to show objects in the Repository that do not exist in the VSM system.

To audit a system’s objects against the Repository:

1. In VCDS, select the VCS tab.

2. In the menu bar, select Version | Audit System Against Repository....

An Audit System window opens.

3. Using the System: drop-down menu, select the system to be audited.

4. Click the audit folder button to start the audit.

When the audit is completed, the Audit System window displays the number of, name, and version number of each object in the Repository that does not exist in the selected NETeXPERT system.

In the example below, the VSM 6.0 dialogs in the NetExpert class listed in the audit result screen to the left are not listed in the VSM 6.0 System Tree View on the right. As the audit shows, these dialogs exist in the Repository, but do not exist in the VSM 6.0 NETeXPERT system.

You can deploy all or selected repository objects to the audited system by right-clicking on a folder to display the Audit Operations menu.

Click on Deploy All or Deploy Selected to deploy objects to the system.

Making a deployment selection opens a Confirm Deployment window.

Clicking the OK button displays the Deployment Status window so you can monitor the deployment.

The File menu items are available with the object Information View open. The following functions are available:

With the VCS tab selected, a different File menu displays.

Menu availability is determined by the selected tab above the System Tree View.

Audit System Against Repository is a fast and convenient way to deploy as well as audit objects.

From the Audit System window, you can deploy all objects in a node or selected objects to the VSM system selected in the System: drop-down list. Selecting a node or an object(s) and right-clicking opens the Audit Operations dialog box.

Selecting Deploy All or Deploy Selected opens a Confirm Deployment dialog.

Clicking the OK button opens the Depolyment Status window allowing you to view the deployment.

The Go To Window | <Object> | <ObjectName> menu item displays the selected tear off window.

Console opens the console window on the host computer.

The Help system is a comprehensive and convenient reference on the VCDS features and functions discussed in this User Guide.

The toolbar buttons offer convenient access to VCDS functions also available in the menus.