A Oracle Test Manager API

This appendix provides a basic reference for the methods in the Oracle Test Manager Application Programming Interface (API).

A.1 Introduction

The Oracle Test Manager Application Programming Interface provides two methods for accessing Oracle Test Manager programmatically:

through a Java API that is built on top of the web service
directly through a web service

The Java API resides in the otm_external_api.jar and exposes the necessary classes for interacting with Oracle Test Manager through the oracle.oats.otm.external.api package.

The otm_external_api.jar is installed to the <installDir>\openScript\otm folder.

This guide provides basic instructions for using the Java API and the web service. See also the Oracle Test Manager API Javadoc reference pages installed in

<installDir>/openScript/otm/docs/api/index.html

for additional information and examples.

A.2 Sample Oracle Test Manager API Usage

This section provides basic examples of using the Oracle Test Manager API to work with Oracle Test Manager Assets.

A.2.1 Using the Oracle Test Manager API with OpenScript

The otm_external_api.jar can be used with any Java development environment. The examples in this Appendix show how to use otm_external_api.jar in the OpenScript application of the Oracle Application Testing Suite.

Copy the otm_external_api.jar file from the <installDir>\openScript\otm folder to your OpenScript repository directory (the default is C:\OracleATS\OFT).
Start OpenScript.
Select New from the File menu.
Expand the General folder and select Java Code Script.
Click Next.
Specify a name for the script and click Finish.
Click the Assets tab in the Script view.
Select JAR Files and click Add.
Navigate the repository and select the otm_external_api.jar file and click OK.
Select the Java Code tab in the Script View.
Expand the import section at the top of the script and add:
```
import oracle.oats.otm.external.api.*;
```
Add your OTM API code to the Run section of the script in the Java Code view.

A.2.2 Connecting to Oracle Test Manager and Getting the Project

To connect to Oracle Test Manager using the API, create an instance of TestManager and call the authenticate(username, password, project, dataSource) method. For example:

import oracle.oats.otm.external.api.*;
//[...]
String url="http://localhost:8088";

String dataSource="OATS_otm_DS";
String projectName="Empty Project";
String username="administrator";
String password="password"; //OTM login password

TestManager otm = new TestManager(url);
otm.authenticate(username, password, projectName, dataSource);

After user authentication, get the project, as follows:

Project proj = otm.getProject();
String prjName = proj.getName();

A.2.3 Getting Asset Managers

Use the Asset Managers to obtain an asset in order to do any actions. Use the get[AssetName]Manager() methods to get the managers:

IssueManager issueMgr = proj.getIssueManager();
RequirementManager reqMgr = proj.getRequirementManager();
TestCaseManager tcMgr = proj.getTestCaseManager();
TestManager tstMgr = proj.getTestManager();
TestPlanManager tpMgr = proj.getTestPlanManager();
TestRunManager trMgr = proj.getTestRunManager();
TestSetManager tsMgr = proj.getTestSetManager();

A.2.4 Setting the Asset Path

The Oracle Test Manager API refers to Test Plans, Requirements, Test Cases, Test Sets, and Issues as "Assets". The Asset path specifies the type of Asset to work with and the path in the Asset tree. The Asset type and path is set using the resolve method of the Test Manager. The following examples show how to use the resolve method to set asset paths.

TestManager otm = new TestManager(url);

Test Plans (levels root through n):

TestPlan tpRoot = (TestPlan)otm.resolve("Test Plans/" );
TestPlan tpL2 = (TestPlan)otm.resolve("Test Plans/" + tpRoot);
TestPlan tpL3 = (TestPlan)otm.resolve("Test Plans/" + tpRoot + "/" + tpL2);

Requirements (levels root through n):

Requirement reqRoot = (Requirement)otm.resolve("Requirements/");
Requirement rqL2 = (Requirement)otm.resolve("Requirements/" + reqRoot);
Requirement rqL3 = (Requirement)otm.resolve("Requirements/" + reqRoot + "/" + rqL2);

Test Cases (levels root through n):

TestCase tcRoot = (TestCase)otm.resolve("Test Cases/");
TestCase tsL2 = (TestCase)otm.resolve("Test Cases/" + tcRoot);
TestCase tsL3 = (TestCase)otm.resolve("Test Cases/" + tcRoot + "/" + tsL2);

Test Sets (levels root through n):

TestSet tsRoot = (TestSet)otm.resolve("Test Sets/");
TestSet tsL2 = (TestSet)otm.resolve("Test Sets/" + tsRoot);
TestSet tsL3 = (TestSet)otm.resolve("Test Sets/" + tsRoot+ "/" + tsL2);

Issues (only 1 level):

Issue isRoot = (Issue)otm.resolve("Issues/")

A.2.5 Working with Assets

Assets are a core concept of the OTM API. All manipulation of data happens through assets. Every asset derives from the Asset class. Each asset has some common methods:

Method	Description
`associate(asset)`	Associates this asset with another asset (for example associating an issue with a requirement).
`attach(file)`	Attaches a file to this asset.
`delete()`	Deletes this asset.
`getAttachments()`	Returns a list of attachments associated with this asset.
`getChildNodes()`	If the asset supports child assets, returns the children of the asset.
`getChildNodes(queryFilter,` `sortFilter)`	If the asset supports child assets, returns the children of the asset that match the `queryFilter` and then sorts the results according to `sortFilter`. See FilterCriteria for description of `queryFilter` and `sortFilter` format).
`getField(field)`	Gets the specified data field.
`getFields()`	Gets all fields associated with the asset.
`getId()`	Gets the unique OTM ID associated with the asset.
`getLabel()`	Gets the name of the asset.
`getProject()`	Gets the project that the asset is in.
`save()`	Persists any modifications to this asset in OTM (usually called after modifying fields).

In order to limit the amount of data being transferred, most of the methods that return collections of objects will return iterators that you will need to use to visit the collections. For example:

AssetIterator<Issue> issues = issueMgr.getIssues();
while (issues.hasNext()) {
    Issue issue = issues.next();
    info("issue name: " + issue.getId() + " " + issue.getLabel());
}

For multi-level assets (Test Plans, Requirements, Test Cases, and Test Sets, you can use the getChildNodes() method to retrieve the children of the specified level then iterate through the child nodes. For example:

//Get All Test Plan Names as Assets
//Set the Root level
TestPlan testPlanFolder = (TestPlan)otm.resolve("Test Plans/" );

//Iterate Through Test Plan Tree and Get Test Plan Names
AssetIterator<Asset> L1iterator = testPlanFolder.getChildNodes();
while (L1iterator.hasNext()) {
  //Get Root Level Test Plan Names/Labels
  Asset L1asset = L1iterator.next();
  info("L1 TP Asset: " + L1asset.getId() + " " + L1asset.getLabel());

    //Get Second Level Test Plan Names/Labels
    AssetIterator<Asset> L2iterator = L1asset.getChildNodes();
    while (L2iterator.hasNext()) {
      Asset L2asset = L2iterator.next();
      info("L2 TP Asset Child: " + L2asset.getId() + " " + L2asset.getLabel());

       //Get Third Level Test Plan Names/Labels
       AssetIterator<Asset> L3iterator = L2asset.getChildNodes();
       while (L3iterator.hasNext()) {
         Asset L3asset = L3iterator.next();
         info("L3 TP Asset Grandchild: " + L3asset.getId() + " " + 
            L3asset.getLabel());
       }
    }
}

A.2.6 Working with Fields

Fields correspond to OTM DataField object metadata that can be associated with an asset. Usually these are things like Priority, Severity, Description, and Platform fields that are visible through the UI. You can get the value of a field by calling getValue() or set its value by calling setValue(value). You must persist the field through a call to save(). When creating or working with Asset fields, you specify the data to include in the fields using the List<DataFieldObject> object. See the example below of changing the platform field on a newly created issue:

String name = "Issue " + System.currentTimeMillis();
List<DataFieldObject> fields = new ArrayList<DataFieldObject>();
fields.add(new DataFieldObject("Priority", "Low"));
fields.add(new DataFieldObject("Summary", name));
fields.add(new DataFieldObject("Component", "Application"));
fields.add(new DataFieldObject("AssignedTo", "Administrator User"));
fields.add(new DataFieldObject("Status", "1 - Created"));
fields.add(new DataFieldObject("Severity", "Low"));
Issue issue1 = issueMgr.newIssue(name, fields);

You can use a ListIterator<Field> to get the field names for each asset type. The following example shows how to get the field names for issues:

List<Field> issuefields = issue1.getFields();
ListIterator<Field> issuefielditerator1 = issuefields.listIterator();
while (issuefielditerator1.hasNext()){
  Field fieldname = issuefielditerator1.next();
  info("Issue Field Name "  + fieldname.getName());
}

A.2.6.1 Test Plan Fields

The Test Plan fields and valid values are as follows:

Table A-1 Test Plan Field Names and Valid Values

Field Name

Valid Values

Owner

Administrator User

Default User

Any valid user name as defined in the Oracle Test Manager Administrator.

Priority

N/A

Low

Medium

High

Any valid priority as defined in the Priority option list of the Oracle Test Manager Add Test Plan dialog box. (Priority options are defined in the Priority field Option List in the Oracle Test Manager Administrator Fields tab).

Description

Any text string.