Extending the batch update task

The batch update task helps you to migrate data and move assets into an IBM® Rational® Asset Manager server. You can use the file system option to extend the batch update task and can extend the task to read any kind of source data and map it to assets.

About this task

Extending the batch update task

You can extend the batch update task to read any kind of source data and to map to assets in Rational Asset Manager.

The Rational Asset Manager batch update task performs intelligent mapping by finding assets and performing merges, rather than creating assets every time.

The com.ibm.ram.rich.ui.extension plugin contains the source for the file system extension and it is included as part of the installed Rational Asset Manager Eclipse client, in the /plugins folder. You can find the JAR file in your Eclipse client installation at /eclipse/plugins/com.ibm.ram.rich.ui.extension_7.5.1.v.jar. When you extract it, you can find the Java files in the /src directory.

The filesys extension code is located under these two directories: src\com\ibm\ram\internal\batch\filesystem\ and src\com\ibm\ram\internal\batch\filesystem\ui\

Preparing the extension and the data source

For all data sources, to prepare the extension and the data:
  1. Determine which data is moving into Rational Asset Manager.
  2. Prepare the data for uploading.
  3. Create an Eclipse plug-in that extends the Rational Asset Manager batch update task classes.
  4. Build and deploy the Eclipse plug-in.
In the Example section, Microsoft Excel is the data source. You address steps 1 and 2 by working with the Excel spreadsheet.

To extend to the batch update task by using the file system option, you must create a new plug-in project and implement the extensions for the extension points.

The batch update task provides two extension points for you to implement: batchDataSource and batchDataSourceUI.

You can implement a batch update task through two extension points:
  • batchDataSource: the com.ibm.ram.rich.core plug-in provides the batchDataSource extension point. This extension point helps you to define a Data Source extension to the Rational Asset Manager Batch Client. In a batch update, the batchDataSource extension point pulls data from your repository and migrates the data to a Rational Asset Manager server.
  • batchDataSourceUI: The com.ibm.ram.rich.ui.extension plug-in provides the batchDataSourceUI extension point. This extension point helps you to contribute user interface elements to the Rational Asset Manager Batch Update Editor.

Simplified file system extension

Here is a simplified version of the file system extension that you could export as a deployable plugin. This file system extension creates assets from folders and .zip files in a given root folder. The example takes a root folder and any subfolders or .zip files become assets. The name of the subfolders or archive files will be the name of the asset. The contents of the subfolder/file will be the artifacts, except for a required .asset_info file.

There are two Java classes that extend the Rational Asset Manager batch API classes:
  • FileSystemBatchDataSource.java - extends BatchDataSource.
  • FileSystemBatchUIContributor.java - extends AbstractBatchUIContributor.

The FileSystemBatchDataSource class creates and returns the assets based on the root path. In this file, you specify the data source for the batch client extension to create assets from folders and .zip files in a given root folder. Those folders and .zip files must contain a file named .asset_info.

The .asset_info file content must be in the format of a .properties file (commonly, one key=value pair per line) and contain specific properties for the asset, as listed in the FileSystemBatchDataSource.java file:
  • name (Optional. If omitted, the file/folder name will be used.)
  • version (Optional. If omitted, 1.0 will be used.)
  • community (Required)
  • asset_type (Required)
  • short_description (Optional. If omitted, the file/folder name will be used.)
  • description (Optional)

The FileSystemBatchUIContributor class creates a new data source by opening a directory selection dialog from which a user can select the root directory and then using the selection to create assets. See the FileSystemBatchDataSource java file for the required structure of the root directory.

The extension points that the simple file system example uses to hook into the batch client are defined in the plugin.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
   <extension point="com.ibm.ram.rich.core.batchDataSource">
      <dataSourceType
            class="com.ibm.ram.batch.example.FileSystemBatchDataSource"
            id="com.ibm.ram.batch.example.filesystem">
      </dataSourceType>
   </extension>
   <extension point="com.ibm.ram.rich.ui.extension.batchDataSourceUI">
      <batchDataSourceUI
            class="com.ibm.ram.batch.example.FileSystemBatchUIContributor"
            dataSourceID="com.ibm.ram.batch.example.filesystem"
            icon="icon.gif"
            name="File System Example">
      </batchDataSourceUI>
   </extension>
</plugin>

The code examples for these extensions are here Use the batch upload file system extensions.

You can also use the Rational Asset Manager Java APIs to run a batch upload operation and upload multiple assets. See Perform a batch upload

Example

This example describes how to create extensions for Microsoft Excel files. In this example, a Microsoft Excel file is the data source, and the batch update task extensions are built as an Eclipse plug-in. The batch update task reads the formatted Excel files and maps the Excel rows into assets in Rational Asset Manager. Users can then modify the data before they submit it to Rational Asset Manager. See also Batch upload example.

Preparing the data source

Before you upload the Excel spreadsheet, you must format the spreadsheet. In this example, the spreadsheet is formatted as follows:
Table 1.
  A B C D E F
1 AssetType: Compiler Community: Technical Infrastructure        
2 Asset:GUID Asset:Version Asset:Name Asset Attribute: Author Category Schema: Licenses Ignore: IDE
  • The first two rows in the spreadsheet describe the information model to map into Rational Asset Manager.
    • The first row addresses asset type and community. Use the cell format in the sample; for example "Asset Type: Compiler."
    • The second row addresses asset-level mapping, such as:
      • Asset: GUID
      • Asset: Version
      • Asset: Name
      • Asset Attribute: <attribute name>
      • Category Schema: <category schema name> Rows contain values in the schema using the format “a/b/c”
      • Ignore: <name> This column will be ignored for the uploading.
      If the rows for the assets have no values then an asset is created in Rational Asset Manager; otherwise, it performs a merge.
  • The rows that follow Rows 1 and 2 are mapped as assets.

The column headings use a special formatting that the parser in this asset uses. Row 1 and Row 2 are reserved. Row 1 contains the asset type and community declaration. Row 2 contains a description of the asset columns such as GUID, Version, Name, and asset attributes. To view the expected formats, examine the sample spreadsheet.

Creating the Eclipse plug-in

The code is structured as a regular Eclipse plug-in; you define the extension points.

When creating an Eclipse plug-in that extends the Rational Asset Manager batch update task classes, follow these guidelines:
  • Use the Eclipse plug-in wizard to create the Activator class.
  • Write at least two classes, in this case: ExcelBatchDataSource and ExcelBatchUIContributor. Place your parsing logic in the data source class.
  • When you run the batch update task in Eclipse, select a data source and then select a connection to Rational Asset Manager.
  • When you select the connection to Rational Asset Manager in the client, the fetchAssets method is called in the data source class. Use the ExcelBatchDataSource.fetchAssets() method; this is where most of the parsing code happens. Note: You do not need a Rational Asset Manager session object in your code.
  • To obtain a worksheet, invoke createSpreadsheetAssets and open an Excel workbook object.
  • To handle the GUID, create a new one. However, if you find an Asset: GUID column, set the asset to that so the batch update task will perform an update instead of creating an asset.
  • On each row, select the columns to be uploaded and map them to the asset.
To create a new plug-in project:
  1. From the Eclipse menu, click File > New > Project.
  2. Expand Plug-in Development > Plug-in Project
  3. Type a name for the project.
  4. Click Next.
  5. Click Finish. The MANIFEST.MF file opens.
  6. Open the Dependencies editor tab.
  7. In the Required Plug-ins section, click Add.
  8. Select the com.ibm.ram.rich.ui.extension plug-in and click OK.
  9. Click Finish.
  10. In the Required Plug-ins section, click Add.
  11. Select the com.ibm.ram.rich.ui.extension.batchDataSourceUI extension point.
  12. Click Finish.
  13. Save the MANIFEST file.

The batch update task performs the asset submission to Rational Asset Manager.

Using the batch update task

In the example, the Eclipse plug-in is deployed on your machine.

To run the Rational Asset Manager Excel batch update extension to use an Excel file to create and submit new assets as a batch upload operation, follow these steps:
  1. Click File > New > Batch Update Task.
  2. Select the Excel data source and choose the Excel file. The Rational Asset Manager batch update editor is displayed.
  3. Click the icon for the data source to map into Rational Asset Manager. This icon contains the Excel icon. A file explorer, which was used to navigate to a prepared Excel file, is displayed.
  4. Select the Rational Asset Manager repository connection that is defined in your Eclipse workspace.
  5. Select the target Rational Asset Manager repository into which the assets will upload. In this example, the assets upload into a Rational Asset Manager instance on the local machine.
  6. To complete the mapping to Rational Asset Manager, add configuration items, such as communities, and map the categorizations.

    After you select the target Rational Asset Manager repository, the Batch Editor reads the Excel file and maps it to the target Rational Asset Manager instance. At this point, no assets are uploaded. The Rational Asset Manager Batch Editor provides a summary of the initial mapping. In this example, the assets in the Excel file targeted a specific Rational Asset Manager community, which the Batch Editor did not find in Rational Asset Manager. Users who have access rights can create the community immediately, as shown in this example.

    The mapping activity continues to examine asset types, asset version information, relationship types, and so forth. In each case, users can map to existing configuration information in Rational Asset Manager or, if they have access rights, they can add that information.

  7. When the mapping is complete, click the Update All Assets button. The assets are uploaded to Rational Asset Manager. In the Batch Editor, the results of the upload are displayed.

Class structures and objects

The Rational Asset Manager API has two major class structures for assets:
  • Classes with names that start with “RAM” (such as the RAMAsset class).
  • Classes with names that do not start with “RAM” (such as the Asset class).
The objects of RAM classes are retrieved from a Rational Asset Manager server, which requires a Rational Asset Manager session object; session objects are not used in this example. Objects from classes, such as Asset, are created without a known Rational Asset Manager session, then they are provided to the batch update task, and then submitted or updated to Rational Asset Manager.

Feedback