A Oracle Test Manager API Reference

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 Oracle Test Manager API Reference

The following section provides an alphabetical listing of the classes in the Oracle Test Manager API.

A.2.1 Alphabetical OTM API Class Listing

The following table lists the Oracle Test Manager API classes in alphabetical order.

Table A-1 List of Oracle Test Manager External API Classes

Method Description

AbstractManager.java

The abstract class for all Manager classes.

Asset.java

Provides the basic object that OTM uses to work with Issues, Requirements, TestCases, TestPlans, and TestSets.

AssetIterator.java

An Iterator implementation that retrieves the asset by its queryFilter and sorted by sortFilter in the page size as the "fetch_size" property in the Configuration. defined.

AssociationList.java

A list that encapsulated Asset associations with get/size methods and internal cache mechanism.

Attachment.java

Provides methods to get Assets. An Attachment is either a binary file that an asset has or an URL/Link that an Asset contains.

config.properties

Stores the Property setting(s).

Configuration.java

An encapsulated Properties class that loads properties from "config.properties" file.

ExternalAPIUtil.java

Used for sharing session across the WS-API calls.

Field.java

Provides methods for getting Field properties. Field is used as a meta data for an Asset.

fields.properties

Stores the Field setting(s).

FilterCriteria.java

The Filter Criteria is an abstraction of querying the Asset by A Field.

Folder.java

A Folder is a type of Asset and Test Case that usually presents a Test Case parent when creating the children TestCases.

IManagedObject.java

ManagedObject Interface is an interface that describes the object that can be managed with Create, Read, Update, Delete operations.

Issue.java

Provides methods for saving, deleting, and getting associated test cases and issues. An Issue is a type of Asset that can be used to track the problems during development.

IssueManager.java

The manager that does the Create, Read, Update, Delete operations for Issue asset.

package-info.java

Provides the JAX-WS API for Oracle Test Manager.

Project.java

A project is a collection of its Assets and reference of initialized TestManager. Users can centralize the usage of {AbstractManager then use those Managers to retrieve the Asset.

Requirement.java

Provides methods saving, deleting, and getting associated test cases for Requirements. Requirement is a type of Asset that can be used to track the specifications of software development.

RequirementManager.java

The manager that does the Create, Read, Update, Delete operations for Requirement assets.

TestCase.java

TestCase is a type of Asset that Oracle Test Manager maintains. Test cases can include multiple TestSteps and can execute TestRuns..

TestCaseManager.java

The manager that does the Create, Read, Update, Delete operations for TestCase assets.

TestManager.java

TestManager is used when initializing the testing session. It provides for authentication, field manipulation, and general Asset resolution.

TestPlan.java

The TestPlan is a type of Asset that can be used to track TestCase usage and TestSet execution.

TestPlanManager.java

The AbstractManager of that presents the Create, Read, Update, Delete operations for TestPlans.

TestRun.java

TestRun} represents an action to execute TestCases.

TestRunIterator.java

Iterator for TestRuns.

TestRunManager.java

The manager that does the Create, Read, Update, Delete operations for TestRun assets..

TestSet.java

A TestSet Asset is a type of asset that may contains multiple TestCases.

TestSetManager.java

The manager that does the Create, Read, Update, Delete operations for TestSteps.

TestStep.java

The TestStep represents the steps when executing the TestCase.

TestStepIterator.java

Iterator for TestSteps.

The following table lists the Oracle Test Manager WebServices API classes in alphabetical order.

Table A-2 List of Oracle Test Manager WebServices API Classes

Method Description

AssetDescriptor.java

Java class for assetDescriptor complex type.

AssetObject.java

Java class for assetObject complex type.

Associate.java

Java class for associate complex type.

AssociateResponse.java

Java class for associateResponse complex type.

AttachFile.java

Java class for attachFile complex type.

AttachFileResponse.java

Java class for attachFileResponse complex type.

AttachmentManager.java

Java class for AttachmentManager.

AttachmentManager_Service.java

Java class for AttachmentManager_Service.

AttachmentObject.java

Java class for attachmentObject complex type.

AttachUrl.java

Java class for attachUrl complex type.

AttachUrlResponse.java

Java class for attachUrlResponse complex type.

Authenticate.java

Java class for authenticate complex type.

AuthenticateResponse.java

Java class for authenticateResponse complex type.

DataFieldObject.java

Java class for dataFieldObject complex type.

DeleteAttachment.java

Java class for deleteAttachment complex type.

DeleteAttachmentResponse.java

Java class for deleteAttachmentResponse complex type.

DeleteIssue.java

Java class for deleteIssue complex type.

DeleteIssueResponse.java

Java class for deleteIssueResponse complex type.

DeleteRequirement.java

Java class for deleteRequirement complex type.

DeleteRequirementResponse.java

Java class for deleteRequirementResponse complex type.

DeleteTestCase.java

Java class for deleteTestCase complex type.

DeleteTestCaseResponse.java

Java class for deleteTestCaseResponse complex type.

DeleteTestPlan.java

Java class for deleteTestPlan complex type.

DeleteTestPlanResponse.java

Java class for deleteTestPlanResponse complex type.

DeleteTestRun.java

Java class for deleteTestRun complex type.

DeleteTestRunResponse.java

Java class for deleteTestRunResponse complex type.

DeleteTestSet.java

Java class for deleteTestSet complex type.

DeleteTestSetResponse.java

Java class for deleteTestSetResponse complex type.

DeleteTestStep.java

Java class for deleteTestStep complex type.

DeleteTestStepResponse.java

Java class for deleteTestStepResponse complex type.

Exception.java

Java class for Exception complex type.

Exception_Exception.java

Java class for Exception_Exception.

ExecuteTestCase.java

Java class for executeTestCase complex type.

ExecuteTestCaseResponse.java

Java class for executeTestCaseResponse complex type.

ExecuteTestSetRun.java

Java class for executeTestSetRun complex type.

ExecuteTestSetRunResponse.java

Java class for executeTestSetRunResponse complex type.

FilterCriteriaObject.java

Java class for filterCriteriaObject complex type.

FolderObject.java

Java class for folderObject complex type.

GetAssociations.java

Java class for getAssociations complex type.

GetAssociationsResponse.java

Java class for getAssociationsResponse complex type.

GetAttachments.java

Java class for getAttachments complex type.

GetAttachmentsResponse.java

Java class for getAttachmentsResponse complex type.

GetField.java

Java class for getField complex type.

GetFieldResponse.java

Java class for getFieldResponse complex type.

GetFields.java

Java class for getFields complex type.

GetFieldsResponse.java

Java class for getFieldsResponse complex type.

GetFile.java

Java class for getFile complex type.

GetFileResponse.java

Java class for getFileResponse complex type.

GetIssue.java

Java class for getIssue complex type.

GetIssueResponse.java

Java class for getIssueResponse complex type.

GetRequirement.java

Java class for getRequirement complex type.

GetRequirementResponse.java

Java class for getRequirementResponse complex type.

GetRoot.java

Java class for getRoot complex type.

GetRootResponse.java

Java class for getRootResponse complex type.

GetTestCase.java

Java class for getTestCase complex type.

GetTestCaseResponse.java

Java class for getTestCaseResponse complex type.

GetTestPlan.java

Java class for getTestPlan complex type.

GetTestPlanResponse.java

Java class for getTestPlanResponse complex type.

GetTestRun.java

Java class for getTestRun complex type.

GetTestRunResponse.java

Java class for getTestRunResponse complex type.

GetTestSet.java

Java class for getTestSet complex type.

GetTestSetResponse.java

Java class for getTestSetResponse complex type.

GetTestSteps.java

Java class for getTestSteps complex type.

GetTestStepsResponse.java

Java class for getTestStepsResponse complex type.

HierarchicalAssetObject.java

Java class for hierarchicalAssetObject complex type.

IssueManager.java

Java class for issueManager.

IssueManager_Service.java

Java class for issueManager_Service.

IssueObject.java

Java class for issueObject complex type.

LabelValueObject.java

Java class for labelValueObject complex type.

List.java

Java class for list complex type.

ListResponse.java

Java class for listResponse complex type.

ListTestRuns.java

Java class for listTestRuns complex type.

ListTestRunsResponse.java

Java class for listTestRunsResponse complex type.

ListTestStepResults.java

Java class for listTestStepResults complex type.

ListTestStepResultsResponse.java

Java class for listTestStepResultsResponse complex type.

Manager.java

Java class for manger.

Manager_Service.java

Java class for manager_Service.

NewFolder.java

Java class for newFolder complex type.

NewFolderResponse.java

Java class for newFolderResponse complex type.

NewIssue.java

Java class for newIssue complex type.

NewIssueResponse.java

Java class for newIssueResponse complex type.

NewRequirement.java

Java class for newRequirement complex type.

NewRequirementResponse.java

Java class for newRequirementResponse complex type.

NewTestCase.java

Java class for newTestCase complex type.

NewTestCaseResponse.java

Java class for newTestCaseResponse complex type.

NewTestPlan.java

Java class for newTestPlan complex type.

NewTestPlanResponse.java

Java class for newTestPlanResponse complex type.

NewTestRun.java

Java class for newTestRun complex type.

NewTestRunResponse.java

Java class for newTestRunResponse complex type.

NewTestSet.java

Java class for newTestSet complex type.

NewTestSetResponse.java

Java class for newTestSetResponse complex type.

NewTestStep.java

Java class for newTestStep complex type.

NewTestStepResponse.java

Java class for newTestStepResponse complex type.

ObjectFactory.java

Contains factory methods for each Java content interface and Java element interface generated in the oracle.oats.otm.webservices package.

package-info.java

Contains package information.

RequirementManager.java

Java class for requirementManager.

RequirementManager_Service.java

Java class for requirementManager_Service.

RequirementObject.java

Java class for requirementObject complex type.

SetField.java

Java class for setField complex type.

SetFieldResponse.java

Java class for setFieldResponse complex type.

StoreTestCase.java

Java class for storeTestCase complex type.

StoreTestCaseResponse.java

Java class for storeTestCaseResponse complex type.

StoreTestStep.java

Java class for storeTestStep complex type.

StoreTestStepResponse.java

Java class for storeTestStepResponse complex type.

TestCaseManager.java

Java class for testCaseManager.

TestCaseManager_Service.java

Java class for testCaseManager_Service.

TestCaseObject.java

Java class for testCaseObject complex type.

TestExecutor.java

Java class for testExecutor.

TestExecutor_Service.java

Java class for testExecutor_Service.

TestPlanManager.java

Java class for testPlanManager.

TestPlanManager_Service.java

Java class for testPlanManager_Service.

TestPlanObject.java

Java class for testPlanObject complex type.

TestRunObject.java

Java class for testRunObject complex type.

TestSetManager.java

Java class for testSetManager.

TestSetManager_Service.java

Java class for testSetManager_Service.

TestSetObject.java

Java class for testSetObject complex type.

TestStepObject.java

Java class for testStepObject complex type.

TestStepResultObject.java

Java class for testStepResultObject complex type.

User.java

Java class for user complex type.

A.3 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.3.1 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="Password01";

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.3.2 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.3.3 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();
    print(issue.getLabel());
}

A.3.4 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, 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(). 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("Owner", "Administrator User"));
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"));
issueMgr.newIssue(name, fields);

A.3.5 Working with Filters

Filters are used to specifically query for data and/or sort the data. Filters operate on a field, take an operator (equal, not equal, contains, greater than, less than or null) and a value and can be chained together with an AND or an OR. Filters can also be case sensitive. Please see the FilterCriteria class for more details. An example of using a filter is provided below:

TestCase tc = tcMgr.getRoot();

FilterCriteria c2 = new FilterCriteria();
c2.setField("TestCaseId");
c2.setOperator(Operator.equal);
c2.setValue(String.valueOf(tc.getId()));


List<FilterCriteria> filter = new ArrayList<FilterCriteria>();
filter.add(c2);

A.3.6 Working with Attachments

Attachments can be created using the attach(file) method of any asset that supports attachments. Attachments can be retrieved by simply calling getAttachments() on any asset that supports attachments. An attachment can be deleted by calling the delete() method on the attachment itself.

The following example creates a few files with random data then does various attachment related operations:

File[] files = new File[10];
StringBuilder[] fileContents = new StringBuilder[files.length];

for (int i = 0; i < files.length; i++) {
   files[i] = File.createTempFile("otm_" + i, ".txt");

   / generate file contents
   fileContents[i] = new StringBuilder();
   for (int j = 0; j < Math.random() * 1000; j++) {
      fileContents[i].append(UUID.randomUUID().toString());
   }
   FileWriter writer = new FileWriter(files[i]);
   writer.write(fileContents[i].toString());
   writer.close();
}

TestCase t = project.getTestCaseManager().newTestCase(testFolder, "Attach Test");

for (int i = 0; i < files.length; i++) {

   t.attach(files[i]);
}

assertEquals(t.getAttachments().size(), files.length);

List<Attachment> attachments = t.getAttachments();
for (int i = 0; i < attachments.size(); i++) {
   Attachment attachment = attachments.get(i);
   logger.debug(attachment.getName());
   File f = attachment.getFile();
   FileReader reader = new FileReader(f);
   char[] contents = new char[(int)f.length()];
   reader.read(contents, 0, contents.length);
   reader.close();
   assertEquals(fileContents[i].toString(), new String(contents));
}

for (int i = 0; i < attachments.size(); i++) {
   Attachment attachment = attachments.get(i);
   attachment.delete();
   assertEquals(t.getAttachments().size(), attachments.size() - (i + 1));
}

A.3.7 Accessing Web Services Directly

Pre-generated raw web service Java classes are available in the oracle.oats.otm.webservices package. These will allow you to make raw web service calls. You will need to refer to the WSDL definitions for each of the various asset manager services for the exact message formats. The web services that are exposed are:

/AttachmentManager (generic attachment service)

/IssueManager

/Manager (generic manager service – can handle any asset type)

/RequirementManager

/TestCaseManager

/TestPlanManager

/TestSetManager

/TestExecutor

Note that when you connect to a manager and authenticate, you can maintain that session when connecting to other managers using the SESSION_MAINTAIN_PROPERTY property of the binding provider as follows:

TestCaseManager_Service service = new TestCaseManager_Service();
TestCaseManager manager = service.getTestCaseManagerPort();
((BindingProvider)manager).getRequestContext().put(BindingProvider.SESSION_MAINTAIN_PROPERTY, true);

manager.authenticate("administrator", "Password01", "Empty Project", "OATS_otm_DS");

TestExecutor_Service tes = new TestExecutor_Service();
TestExecutor te = tes.getTestExecutorPort();

// don't have to authenticate, can just immediately call any method
List<TestRunObject> runs = te.listTestRuns(6, "testCase", 0, 0);