APIs to use in custom policies

When you write custom policies, you can use several APIs. The APIs that you use depend on the assets you work with and what you want to do with those assets. For example, you use different APIs to update the asset that a policy is running on than you do to create an asset.

APIs to use with the current asset

You can create policies by using the Java client APIs.

If you are only making updates to the asset that the policy is running against, you can use the policy context methods to create a session and get the asset. To create a RAMSession and retrieve the current RAMAsset, use the following APIs:
RAMSession ramSession = getPolicyContext().getRAMSession();
RAMAsset ramAsset = getPolicyContext().getRAMAsset();

You can use several of the Rational® Asset Manager Java API classes to update the current asset. For example, you might add a relationship or set an action. You can also use the API classes to work with assets, asset attributes, and artifacts.

You can also use the Java APIs to change or create assets besides the one that the policy is running on. You must include the Java client JAR files and use a RAMSession(). For best performance when using ram.client APIs, limit asset updates to a single session.

Follow these steps in your custom policy code:
  1. Create a session using the getRAMSession method. No licenses are consumed for these sessions.
  2. Get an asset with the getRAMAsset method.
  3. Use the RAMSession and RAMAsset APIs to perform asset operations.
  4. Commit the changes as one transaction using the session.putAssets method.
For example:

RAMSession session = getPolicyContext().getRAMSession();  
RAMAsset currentAsset = this.getPolicyContext().getRAMAsset();  
  
// Use the client APIs to make changes to the asset ...

// You can also modify or create other assets:
			RAMAsset asset = session.createAsset("1.0");
			asset.setName("Test Asset");
			asset.setCommunity(session.getCommunity("Sample Application Development"));
			asset.setAssetType(session.getAssetType("Business Solution"));
			asset.setShortDescription("Test asset");
			asset.setOwners(new RAMUser[] { session.getUser("admin") });
		 	
// Commit changes to the asset repository for the current asset:
			session.putAsset(currentAsset);  

// You can use queueAssetForPut and then putAssets to queue and then 
// commit all assets you have changed in the session as one transaction:
			session.queueAssetForPut(currentAsset);  

// Commit changes to all assets you have changed in the session:
			session.putAssets(new NullProgressMonitor());  	

For the Java client APIs, see: client package and common data package.

See the Example section in this topic and Using Rational Asset Manager Java API for additional examples.

  • Get the asset:
    RAMAsset myAsset = getPolicyContext().getRAMAsset();
  • Get asset attributes examples:
    AssetAttribute myAttribute = myAsset.getAssetAttribute("Family Name");
    String[] myAttrValue = myAttribute.getValues();
    
    myAttribute = myAsset.getAssetAttribute("Work Item");
    myAttrValue = myAttribute.getValues();
    
    myAttribute = myAsset.getAssetAttribute("Requirement");
    myAttrValue = myAttribute.getValues();
  • Create a query to search for assets:
    SearchQuery query = session.createAssetQuery(queryParam);
    int offset = 0;
    int maxResults = 100;
    query.setResultsStartIndex(offset);
    query.setMaxResults(maxResults);
    SearchResult result = session.getAssets(query);
  • Create an asset:
    RAMAsset newAsset = session.createAsset("1.0");
    newAsset.setName("The new related asset");
    newAsset.setCommunity(session.getCommunity("Rational Asset Manager Development"));
    newAsset.setAssetType(session.getAssetType("Specification"));
    newAsset.setShortDescription("The Specification asset is required.");
  • Create an AssetID for the new asset:
    AssetID id = new AssetID();
    id.setGUID(newAsset.getId());
    id.setVersion(newAsset.getVersion());
  • Create a query, check the result set, and modify assets:
    public Result test() {
    		try {
    			// Create a query 
    			String queryParam = null; 
       	RAMSession session = getPolicyContext().getRAMSession();
        SearchQuery query = session.createAssetQuery(queryParam);
    			int offset = 0;
    			int maxResults = 100;
    			query.setResultsStartIndex(offset);
    			query.setMaxResults(maxResults);
    			SearchResult result = session.getAssets(query); 
    			 
    			if (result != null && result.getAssetSearchResults() != null) {
    				AssetSearchResult[] assets = result.getAssetSearchResults();
    	
    				for (AssetSearchResult asset : assets) {
    					AssetInformation assetInformation = asset.getAsset();
    				// Modify an asset here, for example,
    				// create a "DependsOn" relationship from Release and Implementation type assets to a Specification asset of the same name using the client APIs, like this:
    				// Relationship theRelationships = session.getRelationships
    				// getRelationships().add(newItem);
    				}
    			}
    		}
     
    		// Catch exceptions...
    				Result result = new Result();
    		result.setMessage("Success");
    		return result;
    		 
    	}
  • Get the folder location using the Rational Asset Manager Java APIs, to retrieve asset artifacts information and download the artifacts:
     		// Get the asset
    		RAMAsset ramAsset = getRAMAsset(); 
                
    		 		// Get the location and content of the artifacts
    		RAMFolderArtifact srcFolderArtifact = (RAMFolderArtifact)ramAsset.getArtifactsRoot();
    		Artifact[] srcArtifacts = srcFolderArtifact.computeArtifactsAsFlatList(new NullProgressMonitor());
    		 
    		for (Artifact artifact : srcArtifacts) {
            RAMArtifact ramArtifact = (RAMArtifact) artifact;
    					InputStream is = ramArtifact.downloadContents();
    					f = File.createTempFile("theArtifact", null, new File(ramSession.getLocalStorageLocation()));
    					UtilitiesCommon.copyStreams(is, new FileOutputStream(f), null, true, true);
             }

Feedback