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:
- Determine which data is moving into Rational Asset Manager.
- Prepare the data for uploading.
- Create an Eclipse plug-in that extends the Rational Asset Manager batch update task
classes.
- 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:
- From the Eclipse menu, click .
- Expand
- Type a name for the project.
- Click Next.
- Click Finish. The MANIFEST.MF file
opens.
- Open the Dependencies editor tab.
- In the Required Plug-ins section, click Add.
- Select the com.ibm.ram.rich.ui.extension plug-in and click OK.
- Click Finish.
- In the Required Plug-ins section, click Add.
- Select the com.ibm.ram.rich.ui.extension.batchDataSourceUI extension
point.
- Click Finish.
- 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:
- Click .
- Select the Excel data source and choose the Excel file. The Rational Asset Manager batch
update editor is displayed.
- 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.
- Select the Rational Asset
Manager repository connection that is defined in your Eclipse workspace.
- 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.
- 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.
- 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.