Setting up the Visual Configuration Explorer SDK

 

 
Introduction

The Visual Configuration Explorer SDK is provided as an aid for developing additional content for the tool. For example, new providers could be developed to allow the tool to support additional products. This guide provides instructions for setting up an environment in which the SDK can be used.

These instructions were developed on a Windows® XP system. They use a specific set of directories. If you choose to use different directories, you must make the appropriate changes to the instructions.

 

ISA V4.0.2 Workbench Installation

  1. Download the IBM Support Assistant V4.0.2 Workbench for Windows from the IBM web site. You will need an IBM ID.
    1. Click proceed directly to the download page.
    2. Select IBM Support Assistant V4.0.2 and click Continue.
    3. Update your business contact information, check the privacy boxes as appropriate, view the license, check I agree, and click I confirm.
    4. Check IBM Support Assistant 4.0.2 Workbench for Windows and click Download now. (You may have to install a java plug-in to enable the Download Director.) The file ibmsa-v402-wb-win32.zip will be downloaded onto your machine.
  2. Extract the contents of the zip file to c:\temp\isawb402.
  3. From a Windows Command Prompt, run c:\temp\isawb402\setupwin32.exe and proceed as directed. Do not start the workbench from the icon created on your desktop.
  4. Create a new text file vcesdk.link in the C:\Program Files\IBM\IBM Support Assistant\eclipse\links directory. The content of the file should be: path=C\:/Documents and Settings/userid/IBM/ISAv4/applications

 

Eclipse 3.2.2 Installation

  1. Download the eclipse-SDK-3.2.2-win32.zip file from the Eclipse web site.
  2. Extract the contents of the zip file to the c:\eclipse32 directory.
  3. Install a suitable Java virtual machine (JVM) or Java runtime environment (JRE) if there is not one already installed on the machine. For a list of suitable platforms see the C:\eclipse32\eclipse\readme\readme_eclipse.html file. These instructions were developed using an IBM J2RE 1.5.0 installed at C:\Program Files\IBM\VCE\eclipse\jre.
  4. Open a Windows Command Prompt, and change the directory to \eclipse32\eclipse.
  5. Launch eclipse specifying the JVM or JRE using the following command: eclipse -vm "C:\Program Files\IBM\VCE\eclipse\jre\bin\javaw"
    (To enable ease in running this command, create a short cut on your desktop.)
  6. Allow the workspace folder to be set to C:\Documents and Settings\userid\workspace.
  7. Click the Workbench icon on the Eclipse Welcome page.
  8. In Eclipse's Window menu, select Preferences. Then in the resulting dialog, select Target Platform under Plug-in Developement. In the Target Platform pane, specify the Location as C:\Program Files\IBM\IBM Support Assistant\eclipse, check Group plug-ins by location, and click Reload, Apply, and OK.

 

SDK Installation

Under Eclipse's Help menu, highlight Software Updates and click Find and Install.... In the resulting dialog, select Search for new features to install and click Next>. In the next dialog, check Callisto Discovery Site and click Finish and OK. Expand the Callisto Discovery Site and select the following features:

Click Next>, specify you accept the license, click Next>, Finish, and Install All, and restart Eclipse.

Unzip the vce-dev-update-site.zip file from the alphaWorks distribution into the C:\temp\vce-dev-update-site directory; preserve the folder names within the zip file.

Under Eclipse's Help menu, highlight Software Updates and click Find and Install.... In the resulting dialog, select Search for new features to install and click Next>. In the next dialog, click New Local Site..., select the c:\temp\vce-dev-update-site directory you created in the previous step and specify the name as IBM VCE SDK Updates, and click OK and Finish. Then, expand the newly-created site, check both VCE Provider Workbench Feature and Visual Configuration Explorer SDK Feature, and click Next>. Specify you accept the license, click Next>, Finish, and Install All, and restart Eclipse.

 

Configuring Eclipse 3.2.2

  1. In Eclipse's Run menu, select Run.... In the resulting dialog, highlight Eclipse Application, and click the New launch configuration button. Then, highlight the newly created eclipse application and specify the following settings:
    1. Specify the Name as ISAv4.
    2. In the Main tab, specify the Location as C:\Documents and Settings\userid\IBM\ISAv4, check Run a product: and specify com.ibm.esupport.platform.branding.isaproduct. Then, check java, and click Installed JREs.... In the resulting dialog, click Add; then, specify JRE type as Standard VM, JRE home directory as C:\Program Files\IBM\IBM Support Assistant\rcp\eclipse\plugins\com.ibm.rcp.j2se.win32.x86_1.5.0.SR6-200802132253\jre, and JRE name as ISAv4, and click OK. Check ISAv4 and click OK. Now, back in the Main tab, specify the Runtime JRE: as ISAv4.
    3. In the Arguments tab:
      1. Click Variables... in the VM Arguments area; in the dialog click Edit Variables, and in the next dialog click New.... Finally, set the variable rcp_base to the value, C:\Program Files\IBM\IBM Support Assistant\rcp\eclipse\plugins\com.ibm.rcp.base_6.1.2.200802132253, and click OK three times.
      2. Then, specify the Program arguments as:
        -debug
        -console
      3. And specify the VM arguments as:
        -Xquickstart
        "-Xbootclasspath/a:${rcp_base}/rcpbootcp.jar"
        "-Drcp.home=c:\Program Files\IBM\IBM Support Assistant"
        -Dinstall.configuration=user
        -Dupdate.policy.managed=true
        "-Dprovisioning.manifest=file\:/c:\Program Files\IBM\IBM Support Assistant/rcp/deploy/install.xml"
        -Djvm.parent.feature.id=com.ibm.rcp.jvm.feature
        "-Drcp.base.location=c:\Program Files\IBM\IBM Support Assistant/rcp/eclipse/plugins/com.ibm.rcp.base_6.1.2.200802132253"
        -Dprovisioning.application=com.ibm.rcp.provisioning.application.ProvisioningApplication
        -Drcp.install.id=1219771944625
        -Dprovisioning=true
        -Dosgi.splashPath=platform\:/base/../shared/eclipse/plugins/com.ibm.esupport.platform.branding,platform\:/base/../shared/eclipse/plugins/com.ibm.esupport.platform.branding.nl1,platform\:/base/../shared/eclipse/plugins/com.ibm.esupport.platform.branding.nl2,platform\:/base/../shared/eclipse/plugins/com.ibm.esupport.platform.branding.nl3
        -Djvm.parent.feature.version=2.0.0.0-200802132253
        "-Drcp.data=C:\Documents and Settings\dudley\IBM\ISAv4"
        -Dprovisioning.manifest.version=1219771944625
      4. Under Working directory check Other and specify C:\Program Files\IBM\IBM Support Assistant\eclipse.
    4. In the Plug-ins tab, set Launch with to all workspace and enabled external plug-ins. Then click Validate Plug-in set; you should see a dialog indicating No problems were detected; click OK.
    5. In the Configuration tab:
      1. In the Configuration Area, uncheck use default location and set the Location to C:\Documents and Settings\userid\IBM\ISAv4\.config.
      2. For the Configuration File, check Generate a config.ini file with default content.
  2. Then in the Run Configurations dialog, click Apply and click Run. The ISA workbench should then be launched.

 

Installing Visual Configuration Explorer

In the launched ISA workbench, highlight Find new... under the Update menu and click Product add-ons. In the resulting dialog, select Visual Configuration Explorer Topology Collector under Other and click Next>. Then, select Visual Configuration Explorer ISA Feature under Configuration Tools and click Next>. Finally, check I accept the terms in the license agreements, click Next> and click Finish. Don't restart the workbench; instead, manually close the workbench.

In Eclipse's Window menu, select Preferences. Then in the resulting dialog, select Target Platform under Plug-in Developement. Click Reload, Apply, and OK. Then, restart the workbench by selecting Run... in Eclipse's Run menu; in the resulting dialog, select ISAv4 under Eclipse Application and click Run.

 

Using the Visual Configuration Explorer SDK

The SDK consists of two features that can be used to develop additional Visual Configuration Explorer providers. The Visual Configuration Explorer SDK feature provides Javadoc for the Visual Configuration Explorer APIs and utilities that are available for this task. It also provides Eclipse source code that can be useful when running the Eclipse debugger. The VCE Provider Workbench feature simplifies the creation of a new provider by creating code templates and a user interface plugin required by a working provider; it also simplifies the process of defining the topology objects associated with the provider and encorporating the images used as icons for those objects.

Development of a new provider consists of several tasks. At a high-level these tasks are as follows:

The following instructions will describe some of the process for creating a provider for "Product X". First, a new plug-in project is created; let's call this plug-in productx.provider. We will use PX as an identifier for Product X.

  1. Under the Eclipse File menu, highlight New and click Project.
  2. Then, select Plug-in Project under Plug-in Development and click Next>.
  3. Specify project name as productx.provider and click Next>.
  4. Specify the plug-in name as Visual Configuration Explorer Product X Plugin and the plug-in provider as your company name, and click Next> and Finish. If asked, agree to open the Plug-in Development perspective.

Then, create a new provider model.

  1. Create a model folder by right clicking the productx.provider project and clicking Folder under New. Specify the folder name as model and click Finish.
  2. Select the newly-created folder, right click, highlight New, and click Other....
  3. Then, select VCE Provider Model under Example EMF Model Creation Wizards and click Next>.
  4. Provide a file name with a file type of provider (e.g., PX.provider), and click Next>.
  5. Specify the Model Object as Providers and click Finish.

Next, create a provider diagram by:

  1. Right click the newly-created provider file and select Initialize provider_diagram diagram file.
  2. Specify a file name with a file type of provider_diagram (e.g., PX.provider_diagram) and click Next> and Finish.

Open the provider diagram, and use the pallate to define a provider type and the topology object types associated with the new provider. Use RelationshipMetaInfo to define the hierarchical relationships among the provider type and the topology object types. The following instructions define two topology object types: a top-level object named Top and a second-level object named SecondLevel.

  1. Double click the provider diagram to open the diagram.
  2. Right click in the diagram and click Show Properties View. In the Properties view, select the Advanced tab.
  3. Specify the following fields under EMF (type Enter after each item):
    • Model Package as "productx.provider"
    • Model Plugin Id as "productx.provider"
    • Model Plugin Name as "Visual Configuration Explorer Product X Plugin"
    • UI Directory as "/productx.provider.ui/src
    • UI Package as "productx.provider.ui"
    • UI Plugin Id as "productx.provider.ui"
    • UI Plugin Name as "Visual Configuration Explorer Product X UI Plugin"
  4. Highlight Provider Type in the pallate and then click in the editor pane to create a new provider type.
  5. Right click the new provider-type object and click Show Properties View. In the Properties view, select the Advanced tab.
  6. Specify the following fields under EMF(type Enter after each item):
    • Short Name as "Provider"
    • Type Namespace as "PX"
  7. Highlight Topology Object Type in the pallate and then click in the editor pane to create a new topology object type.
  8. Highlight RelationshipMetaInfo in the pallate and then click and hold the provider type object, move the cursor to the new topology-object-type object, and release the mouse button.
  9. Right click the new topology-object-type object and click Show Properties View. In the Properties view, select the Advanced tab.
  10. Specify the following fields under EMF(type Enter after each item):
    • Short Name as "Top"
  11. Highlight Topology Object Type in the pallate and then click in the editor pane to create a new topology object type.
  12. Highlight RelationshipMetaInfo in the pallate and then click and hold the first topology-object-type object, move the cursor to the new topology-object-type object, and release the mouse button.
  13. Right click the new topology-object-type object and click Show Properties View. In the Properties view, select the Advanced tab.
  14. Specify the following fields under EMF(type Enter after each item):
    • Short Name as "SecondLevel"
  15. Enter cntl-s.
  16. Right click inside the editor pane and click Validate. If everything is ok, no error dialog will appear.
  17. Right click PX.provider in the Package Explorer view and click Generate provider code. No error dialog should appear.

Warning! Remove the @generated comment from any method you change before running Generate provider code again; otherwise, your change will be overwritten.

The following instructions will add some sample code to the generated code:

  1. Replace the code in the isValid method of PXConfigurationHandler with the following:

    File dir = new File(location);
    if (!dir.isDirectory())
      return false;
    File[] files = dir.listFiles();
    for (int i = 0; i < files.length; i++) {
      File file = files[i];
      String fName = file.getName();
      if (fName.equals("test.xml"))
       return true;
    }
    return false;

  2. Click one of the three x's that will appear, highlight Import File (java.io), and type Enter. Save the changes.
  3. Replace the code in the initialize method of PXTopologyProvider with the following:

      String configId = providerInfo.getProperty("provider.configurationId");
      TopologyObjectType objectType = getObjectTypeByPublicType("PX.Provider");
      TopologyObjectImpl providerObject = createTopologyObject(Integer.toString(objectType.hashCode()), "PX Provider", objectType);
      PropertyList providerProperties = new PropertyList(PropertyList.DEFAULT_COMPARATOR_KEY);
      providerProperties.addProperty(new Property("testKey", "testValue"));
      providerProperties.addProperty(new Property("configurationId", configId));
      providerObject.cacheProperties(providerProperties);
      TopologyObjectImpl topObject = createTopologyObject(generateUniqueId(), "testTop", getObjectTypeByPublicType("PX.Top"));
      cacheRelatedObjects(providerObject, topObject, getCompositionRelationship(providerObject, topObject));
      PropertyList topProperties = new PropertyList(PropertyList.DEFAULT_COMPARATOR_KEY);
      topProperties.addProperty(new Property("version", "1.0"));
      topObject.cacheProperties(topProperties);

  4. Click the x that will appear next to TopologyObjectType, highlight Import TopologyObjectType (com.ibm.adt.topology.object), and type Enter.
  5. Add the following method to PX TopologyProvider

      private RelationshipMetaInfo getCompositionRelationship(TopologyObject source, TopologyObject target) throws TopologyException
      {
       String key = "relationshipType=COMPOSITION::sourceType=" + source.getType() + "::targetType=" + target.getType();
       return getRelationshipsMetaInfo(key)[0];
      }

  6. Click the x that will appear next to new method, highlight Import TopologyObject (com.ibm.adt.topology.object), and type Enter.
  7. Click the x next to new method again, highlight Import RelationshipMetaInfo (com.ibm.adt.topology.object.relationship), and type Enter.
  8. Save the changes to the file.

Create a "topology collection" for the Product X provider:

  1. Create an empty file named test.xml in a new folder at some convenient location on your file system.
  2. Launch the ISA V4 workbench from the Eclipse environment (in the Run Configurations dialog, click Run.)
  3. Launch Visual Configuration Explorer from the ISA workbench.
    • Click Analyze Problem.
    • Click the Tools tab.
    • Highlight Visual Configuration Explorer (Tech Preview) and click Launch.
  4. Add a new workspace to Visual Configuration Explorer.
    • Click New VCE Workspace... under the File menu.
    • Specify a file name of isav4.vce in a convenient directory, and click Save.
  5. Drag the folder containing test.xml (from Windows Explorer) into the Providers pane.
  6. In the resulting dialog, specify Product X as the alias prefix and click OK.

Enhancing a Provider

Validation Framework

Visual Configuration Explorer has other tools that can be used to make a provider more valuable. Visual Configuration Explorer provides a validation framework that can be used to check the validity of configurations based on user defined rules. A user may create and edit rules files with a built-in Rules Editor. Rules files are normal files on the filesystem, allowing them to be shared among a community of Visual Configuration Explorer users. With only a little effort, a user can also embed rules files into plugins which can then be deployed using eclipse update mechanisms. See the Working with the Validation Framework section of the Visual Configuration Explorer Help information under Tasks.

Templates

Templates provide an easy and quick way to populate a diagram with common patterns of topology objects and relationships.

Although VCE comes equiped with a set of templates, you can create your own and share them with others by following the steps below.

Start by constructing a diagram that contains an example of what you wish your template to produce.

Pick a starting object on your diagram and select it. It must be a Topology Object, not a Topology Relationship, and it must be the only selected object. Templates create connected subgraphs of objects. Accordingly, the template generator works with only the set of objects that are connected directly or indirectly to your start object in your diagram. Objects that are not included in the connected subgraph are ignored during template generation.

Note: If you have a cycle in your graph, the resulting template might not work as you expect. The template engine will repeatedly look for matching objects. When you apply a template, the template engine continues looking for matches until it finds no more. When the example graph (and therefore also the template) contains cycles, this may cause more objects in your workspace to be matched than you intended. If you apply your generated template to an object and get a warning that a large number of objects are about to be added to the diagram, you should examine your example graph and see if you can simplify it by removing relationships that cause cycles, and then generate a new template from your simplified graph.

From the context menu, select "Generate Template". Complete the fields in the resulting dialog.

When you hit the "OK" button, a template will be generated and is available for you to use during the remainder of your VCE session. If you saved the template to a file, you can use it again later by configuring the VCE preference page to load it on startup. Bring up the preference page by lauching the preferences editor from the Window/Preferences menu. In the editor, navigate down to Visual Configuration Explorer/Topology Templates.

Test your new template be creating a new diagram and pasting only your start object into it. Right click the object and select your new template from the "Apply Template" menu item. It should add all the connected objects from your original diagram, plus any that match the same pattern.