Rational Asset Manager (RAM) is an application that manages images, software, documents, and other assets. In the context of the IBM SmartCloud Enterprise, RAM provides a framework to enable asset providers to publish assets and support a community of users of those assets. The IBM SmartCloud Enterprise also uses RAM to manage images, software, and document meta- data. When image providers prepare an image, they can use RAM to store information in a man- ner similar to a “Getting Started” guide and to host a support forum for the users of the image; they can also take advantage of Web 2.0 capabilities, such as user ratings and tags. This is valu- able to users, who can select well-used and well-supported images. RAM also enables users to browse and query assets and to personalize their user account. In addition to the RAM server hosted by IBM SmartCloud Enterprise, the catalog has a RAM image that you can use for your own projects.
You can programmatically download and manage assets in RAM using either the RAM client API or the RAM Eclipse client. Download the required libraries from the asset catalog. In the image catalog, click Help, Extensions, as in Figure 3.13.
146 Chapter 3 Developing with IBM SmartCloud Enterprise APIs
Figure 3.13 Location for downloading RAM client
Under Client API Jars, download the ramclient.zip, as shown in Figure 3.14. This includes all the JARs you need to support a remote client to the asset catalog.
ptg8286219
Rational Asset Manager 147
Figure 3.14 RAM extensions page
The Eclipse Client plug-in and Web Services are options as well.
Following is a simple program that uses the RAM API to retrieve an image asset based on the GUID. Notice that the image ID used in the SCE APIs is a parameter that you can access in the asset catalog.
package com.ibm.cloud.example.ram; import java.util.logging.Level; import java.util.logging.Logger; import com.ibm.ram.client.RAMAsset; import com.ibm.ram.client.RAMSession; import com.ibm.ram.common.data.AssetAttribute; import com.ibm.ram.common.data.AssetIdentification;
public class RAMClient {
private static final String USER = “[email protected]”;
private static final String PASSWORD = “***”;
ptg8286219
www-147.ibm.com/cloud/enterprise/ram.ws”;
private RAMSession session;
private static Logger logger =
Logger.getLogger(“com.ibm.cloud.example.ram”);
private static final String LS = System.getProperty(“line.separator”);
public void connect() {
try {
session = new RAMSession(URL, USER, PASSWORD);
} catch(Exception e) {
logger.log(Level.SEVERE, “Error connecting”, e); }
}
/**
* Prints out information about an image asset
* @param guid The RAM Asset globally unique identifier */
public void getAsset(String guid) {
try {
AssetIdentification assetID = new
AssetIdentification();
assetID.setGUID(guid);
RAMAsset asset = session.getAsset(assetID);
logger.log(Level.INFO, “Got asset “ + asset.getName() +
“ with ID “ + asset.getAssetAttribute(“Image Id”));
AssetAttribute[] assetAttributes = asset.getAssetAttributes();
StringBuilder sb = new StringBuilder();
for (int i=0; i<assetAttributes.length; i++) { StringBuilder valueString = new
StringBuilder();
String[] values = assetAttributes[i].getValues();
if (values != null) {
for (int j=0; j<values.length; j++) { valueString.append(values[j] + “ “); } } sb.append(assetAttributes[i].getName() + “ : “ + valueString + LS); }
ptg8286219
logger.log(Level.INFO, “Attributes: “ + sb); } catch(Exception e) {
logger.log(Level.SEVERE, “Error getting asset”, e); }
}
/**
* Example usage: java com.ibm.cloud.example.ram.RAMClient Guid */
public static void main(String[] args) { RAMClient client = new RAMClient(); client.connect();
String guid = args[0]; client.getAsset(guid); }
}
You can invoke the program by passing in an example GUID:
Java -cp $CP com.ibm.cloud.example.ram.RAMClient {6D6FF958-0EBA-7A7E- CEC8-BE737E9ACA94}
Here, $CPis a system variable containing the classpath of the RAM and dependent libraries downloaded earlier, and the program argument is the GUID for an image in the SmartCloud Enterprise catalog. When invoked, the program gives output similar to this:
INFO: Got asset Microsoft Windows Server 2008 R2 (64-bit) with ID Image Id = 20012053
INFO: Attributes: Primary Artifact : Request Image URL : <a href=”https://www-
147.ibm.com/cloud/enterprise/user/control.jsp?autocreate={id:’20012053 ’}” target=”_blank”>Start an instance of this image</a>
Terms and Conditions : <a href=”https://www-
147.ibm.com/cloud/enterprise/ram/artifact/%7B6D6FF958-0EBA-7A7E-CEC8- BE737E9ACA94%7D/1.0/Terms.pdf” target=”_blank”>Link to Terms.pdf</a> Image Id : 20012053
Operating System : Windows Server 2008 Product Name :
Support Information : Installed Software :
Offering Deployment Automation Model : Offering Deployment Model :
Offering Documentation :
Operating System Details : /win2k8dc-r2-
x64.topology#capability.windowsOperatingSystem[displayName=’win2k8dc- r2-x64’ and name=’WindowsOperatingSystem_3369’ and linkType=’any’ and kernelWidth=’64-bit’ and os.type=’Windows’ and os.version=’2008 R2’]
ptg8286219 We have deleted some of the log trace information here. The image ID 20012053is the
important link to the SmartCloud Enterprise REST API.
You can extend the program with the following method to perform a generic search:
public void search(String queryText) {
SearchQuery query = session.createAssetQuery(queryText); SearchResult searchResult = session.getAssets(query); RAMAssetSearchResult[] results =
(RAMAssetSearchResult[])searchResult.getAssetSearchResults();
logger.log(Level.INFO, results.length + “ results found.”);
for (int i=0; i<results.length; i++) {
RAMAsset asset = (RAMAsset)results[i].getAsset(); String guid = assetInfo.getIdentification().getGUID(); String name = assetInfo.getName();
AssetAttribute imageID = asset.getAssetAttribute(“Image Id”);
logger.log(Level.INFO, “Asset “ + name + “ “ + imageID + “ “ + guid);
} }
The method creates a SearchQueryobject that allows a web-style search to be executed. You invoke this method with the query text Windows. The output is shown here:
INFO: 93 results found.
INFO: Asset Microsoft Windows Server 2008 R2 (64-bit) (EHN) Image Id = 20012054 {16AD9067-E16E-6C83-A2E3-80512F3AD815}
INFO: Asset Microsoft Windows Server 2008 R2 (64-bit) Image Id = 20012053 {6D6FF958-0EBA-7A7E-CEC8-BE737E9ACA94}
INFO: Asset Microsoft Windows Server 2008 R1 (32-bit) (EHN) Image Id = 20012835 {2E49860A-930F-6052-88EF-B2212B9DB95A}
INFO: Asset Microsoft Windows Server 2003 R2 (32-bit) (EHN) Image Id = {015B829A-5586-0775-85DB-5AAB432A5587}
...
These examples return all the data in the asset catalog that the user whose credentials you use has the authority to browse. This is slightly different from the GET /offerings/imagecall in the SmartCloud Enterprise REST API, listing the images the user is entitled to, considering the enterprise’s onboarding contract. That is a subset of the full list of public images in the catalog.
Three levels of visibility in RAM—public, enterprise, and private—relate to three respec- tive communities. Publicly visible assets are visible to all the users on the cloud. Shared visibility assets are visible by the enterprise communities, including all the users in each respective enter- prise. A privately visible asset is visible only to the user who created it. The previous examples returned images from all levels of visibility. The example method that follows shows how to find the name of the community associated with an asset.
ptg8286219
public void getAssetCommunityInfo(String guid) {
try {
AssetIdentification assetID = new AssetIdentification(); assetID.setGUID(guid);
RAMAsset asset = session.getAsset(assetID);
logger.log(Level.INFO, “Got asset “ + asset.getName() +
“ with ID “ + asset.getAssetAttribute(“Image Id”));
CommunityInformation community = asset.getCommunity(); String communityName = community.getName();
int communityID = community.getId();
logger.log(Level.INFO, “Attributes: “ + communityName +
“, community id: “ + communityID);
} catch(Exception e) {
logger.log(Level.SEVERE, “Error getting asset”, e); }
}
This results in output similar to the following:
INFO: Getting asset with guid {6D6FF958-0EBA-7A7E-CEC8-BE737E9ACA94} INFO: Got asset Microsoft Windows Server 2008 R2 (64-bit) with ID Image Id = 20012053
INFO: Attributes: Cloud Computing Core Community, community id: 1000
The asset belongs to the Cloud Computing Core Community—that is, it is publicly visible. The ID of this community is 1000.
With the RAM search APIs, you can find all assets matching a generic search term. The RAM API also helps you be more precise in matching specific attributes and either OR’ing or
AND’ing different terms together, paging results, and so on. In addition, you can filter searches based on communities. Consider an example:
public void search(String queryText, String communityName) { RAMAssetQueryBuilder queryBuilder = new
RAMAssetQueryBuilder(session);
CommunityInformation community = new CommunityInformation(); community.setName(communityName);
queryBuilder.addSearchFilter(community);
queryBuilder.addQueryTextField(“*” + queryText + “*”); SearchResult searchResult = session.getAssets(queryBuilder); RAMAssetSearchResult[] results =
(RAMAssetSearchResult[])searchResult.getAssetSearchResults();
logger.log(Level.INFO, results.length + “ results found.”);
for (int i=0; i<results.length; i++) {
RAMAsset asset = (RAMAsset)results[i].getAsset(); String guid = asset.getIdentification().getGUID(); String name = asset.getName();
ptg8286219
AssetAttribute imageID = asset.getAssetAttribute(“Image Id”);
logger.log(Level.INFO, “Asset “ + name + “ “ + imageID + “ “ + guid);
} }
The example uses a RAMAssetQueryBuilderobject to construct a query with two condi- tions: a query with the input text and a filter based on the community. The output based on invok- ing the method with the query text of Windowsand a community name of Cloud Computing Core Communityis shown here:
INFO: Getting asset with search text Windows, community: Cloud Computing Core Community
INFO: 79 results found.
INFO: Asset Microsoft Windows Server 2008 R2 (64-bit) (EHN) Image Id = 20012054 {16AD9067-E16E-6C83-A2E3-80512F3AD815}
INFO: Asset Microsoft Windows Server 2008 R2 (64-bit) Image Id = 20012053 {6D6FF958-0EBA-7A7E-CEC8-BE737E9ACA94}
...
Notice that the number of results returned is now 79, which is a subset of the total before: 93 total.