Remote API Example with DOORS

Appendix > Installing the Remote API > Remote API Example with DOORS

Purpose

This documents describes how to use the Remote API service with Windchill Requirements Connector for DOORS.

All Java example files are part of the install package and can be used for reference and execution (Remote_API.zip)

Windchill Requirements Connector on the server

The client can communicate with the Windchill Requirements Connector service running on the server via TCP-IP. The client should know the host name and the port on which the service is running (which is configured on the server via the environment variable WRC_API_SERVICE_PORT). The Windchill Requirements Connector service provides many services such as starting and stopping a Windchill Requirements Connector instance, as well as requesting information about one or all running Windchill Requirements Connector instances. The sample programs demonstrate how to use the Remote API services for an export, import and update operation with Windchill Requirements Connector.

Start WRC Remote Client Service

You need to start WRC remote service client by the client program using the Server host and Server port that are declared in the utility class (e.g. DoorsFileUtils.java)

serviceClient =
RemoteClientFactory.createRemoteServiceClient
(DoorsFileUtils.SERVER_HOST, DoorsFileUtils.SERVER_PORT);

Access the WRC Instance

Windchill Requirements Connector instance is accessed by the application port and workspace that are declared in the utility class.

if (!serviceClient.requestNewExerptInstance("pm90_id",
DoorsFileUtils.APPLICATION_PORT,
DoorsFileUtils.WORKSPACE_PATH)) {
throw new Exception("Unable to start a new instance");
}

Status from the running Instance

You can get the running instance status from the Windchill Requirements Connector service.

IInstanceInformation info =
serviceClient.getInstanceInformation("pm90_id");
System.out.println("ID: ".concat(info.getId()));
remoteClient =
RemoteClientFactory.createRemoteClient(DoorsFileUtils.SERVER_HOST,
DoorsFileUtils.APPLICATION_PORT);
remoteClient.connect();

Create Project and Roundtrip

You can create a project and roundtrip from the client program.

// create a project
IOperationResult result =
remoteClient.createProjectWithLocalReplication(
"C:/ApiTests/TestData/Projects", projectName);
IRemoteWorkspace workspace = remoteClient.getWorkspace();

// find the project
IRemoteFile roundtripFile = null;
IRemoteProject remoteProject = null;
for (IRemoteProject project : workspace.getProjects()) {
if(project.getName().equals(projectName)){
remoteProject = project;
break;
}
}

result = remoteClient.createRoundtrip(remoteProject, roundtrip);

if (!result.getSuccessful()) {
for (IOperationMessage message : result.getMessages()) {
System.out.println(message.getSeverity() + " = "+ message.getMessage());
}
} else {
System.out.println("The roundtrip is created successfully");
}
// find the roundtrip
IRemoteResource[] children = remoteProject.getChildren();
for (IRemoteResource child : children) {
if (child instanceof IRemoteFile) {
if (child.getName().equals(roundtrip)) {
roundtripFile = (IRemoteFile) child;
break;
}
}
}

DOORS Connection

After creating a project and roundtrip successfully, you can set the connection details for DOORS.

configuration = remoteClient.getOpenConfiguration(roundtripFile);
configuration.setLocalTool("IBM DOORS");
result = remoteClient.commitRoundtripChanges(configuration);
setToolStringAttribute(configuration.getConnectionAttributes(),
"Host", hostName);
setToolStringAttribute(configuration.getConnectionAttributes(),
"User", userName);
setToolIntegerAttribute(configuration.getConnectionAttributes(),
"Port",port);
setToolStringAttribute(configuration.getConnectionAttributes(),
"Password", password);
setToolEnumerationAttribute(configuration.getConnectionAttributes(),
"Client", client);
result = remoteClient.commitRoundtripChanges(configuration);

Add document for Import

You can add the document in the configuration for the import and update operation.

result =
remoteClient.addImportDocumentsFromServerPath(configuration,
new String[] {importDocument}, true);

Define Baseline

You can define a baseline for export, import and update.

Export Baseline

// Select view & set the export baseline
setToolEnumerationAttribute(toolOptions,
"Exported baseline", "<Last Baseline>");
result = remoteClient.commitRoundtripChanges(configuration);
if(!checkResult(result)) {
System.out.print("Failed to commit the configuration");
return;
}

setToolBooleanAttribute(toolOptions, "Exported baseline", true);
// Commit the change to enable the further baseline options
result = remoteClient.commitRoundtripChanges(configuration);
if(!checkResult(result)) {
System.out.print("Failed to commit the configuration");
return;
}

setToolEnumerationAttribute(toolOptions,
"Increase baseline number", "Major");
setToolStringAttribute(toolOptions,
"Baseline suffix", "Testing");
setToolStringAttribute(toolOptions,
"Baseline description", "RemoteAPI_demo");
result = remoteClient.commitRoundtripChanges(configuration);
if(!checkResult(result)) {
System.out.print("Failed to commit the configuration");
return;
}

Import Baseline

// set the import baseline
setToolBooleanAttribute(toolOptions,
"Create baseline after operation", true);
// Commit the baseline creation option to enable the further options
result = remoteClient.commitRoundtripChanges(configuration);
if(!checkResult(result)) {
System.out.print("Failed to commit the configuration");
return;
}
setToolEnumerationAttribute(toolOptions,
"Increase baseline number after operation", "Major");
setToolStringAttribute(toolOptions,
"Baseline suffix after operation", "remoteTest");
setToolStringAttribute(toolOptions,
"Baseline description after operation", "{Major}");
result = remoteClient.commitRoundtripChanges(configuration);
if(!checkResult(result)) {
System.out.print("Failed to commit the configuration");
return;
}

Update Baseline

// Select the view & set the baseline
setToolBooleanAttribute(toolOptions,"Create baseline before operation", true);
// Commit the baseline creation option to enable the further options
result = remoteClient.commitRoundtripChanges(configuration);
if(!checkResult(result)) {
System.out.print("Failed to commit the configuration");
return;
}
setToolEnumerationAttribute(toolOptions,
"Increase baseline number before operation", "Major");

setToolStringAttribute(toolOptions,
"Baseline suffix before operation", "Baseline_1");
setToolStringAttribute(toolOptions,
"Baseline description before operation", "Baseline_Testing");
result = remoteClient.commitRoundtripChanges(configuration);
if(!checkResult(result)) {
System.out.print("Failed to commit the configuration");
return;
}

setToolBooleanAttribute(toolOptions,
"Create baseline after operation", true);
// Commit the baseline creation option to enable the further options
result = remoteClient.commitRoundtripChanges(configuration);
if(!checkResult(result)) {
System.out.print("Failed to commit the configuration");
return;
}

setToolEnumerationAttribute(toolOptions,
"Increase baseline number after operation", "Major");
setToolStringAttribute(toolOptions,
"Baseline suffix after operation", "remoteTest");
setToolStringAttribute(toolOptions,
"Baseline description after operation", "{Major}");
result = remoteClient.commitRoundtripChanges(configuration);
if(!checkResult(result)) {
System.out.print("Failed to commit the configuration");
return;
}

Define path to document and links

You need to set the target path for the importing document including links to DOORS

// check document in the configuration and set the target path
IRemoteImportDocument[] docs = configuration.getImportDocuments();
for (IRemoteImportDocument doc : docs){
doc.setTargetPath(targetPath);
doc.getRelationGroups()[0].setTargetPath(targetPath);
}

Start import/update operation

Once you have connected the roundtrip successfully, pass required parameter for the run import documents method.

result = remoteClient.runImportDocuments(configuration,
"Max Mustermann", "",
"{DATE}_{TIME}_import",progressMonitor, 100);

Start export operation

Once you connected the roundtrip successfully, pass required parameter for the run export documents method.

result = remoteClient.runExportDocuments(configuration,
"Rif 1.1a", "Max Mustermann", "",
"{DATE}_{TIME}_export", progressMonitor, 100);

Exit WRC Remote Client Service

After the finishing the operation and close the roundtrip, you must exit or kill the instance.

finally {
// remote client is closed
if(remoteClient != null) {
remoteClient.sendExit();
}
}

Utility class declaration:

Define the following constant value in a utility class (e.g. DoorsFileUtils.java)

1. Create a workspace (C:/ApiTests/TestData/Workspace) in Windows file system

2. Define the workspace path (e.g. WORKSPACE_PATH = "C:/ApiTests/TestData/Workspace")

3. Declare the sever host (e.g. SERVER_HOST = "172.31.1.77”)

4. Declare the server port (e.g. SERVER_PORT = 7654)

5. Declare the application port (e.g. APPLICATION_PORT = 5678)

Before running the client program, place the “com.atego.exchange.remote.api.jar” in the bin directory once. (e.g.:C:\RemoteAPI\com.atego.ilm.remoteapi.tool\bin\com\atego\remoteapi\doors )

Import Operation Example

Import a document (ReqIF/RIF) to DOORS through a client program. (e.g., RemoteDoorsImport.java)

Please pass the command line arguments (projectname, roundtrip, username, password, host, import document and port) to run the import operation.

An example command line with arguments:

C:\RemoteAPI\com.atego.ilm.remoteapi.tool\bin>java -cp
".;C:\RemoteAPI\com.atego.ilm.remoteapi.tool\bin\
com\atego\remoteapi\doors\com.atego.exchange.remote.api.jar"
com.atego.remoteapi.doors.RemoteDoorsImport
-project=apiImport -roundtrip=apiTest.roundtrip
-host=localhost -username=Administrator -password=Password1
-client="9.6" -port=36677 -targetpath="DOORS Database/Import"
-importdoc=C:\RemoteReqIF\remoteSample.reqifz

Update Operation Example

Update the document (ReqIF/RIF) with an existing roundtrip to DOORS through a client program (e.g., RemoteDoorsUpdate.java)

Please pass the command line arguments (roundtrip, password, update document) only to run the update operation.

An example command line with arguments:

C:\RemoteAPI\com.atego.ilm.remoteapi.tool\bin> java -cp
".;C:\RemoteAPI\com.atego.ilm.remoteapi.tool\bin
\com\atego\remoteapi\doors\com.atego.exchange.remote.api.jar"
com.atego.remoteapi.doors.RemoteDoorsUpdate
-roundtrip=apiTest.roundtrip -password=Password1
-updatedoc=C:\RemoteReqIF\remoteSample.reqifz

Export Operation Example

Export a (ReqIF/RIF) document from DOORS through a client program (e.g., RemoteDoorsExport.java)

Please pass the command line arguments (projectname, roundtrip, username, password, host, document ID and port) to run the export operation

An example command line with arguments:

C:\RemoteAPI\com.atego.ilm.remoteapi.tool\bin> java -cp
".;C:\RemoteAPI\com.atego.ilm.remoteapi.tool\bin\
com\atego\remoteapi\doors\com.atego.exchange.remote.api.jar"
com.atego.remoteapi.doors.RemoteDoorsExport
-project=apiExport -roundtrip=ExTest.roundtrip -host=localhost
-username=Administrator -password=Password1
-client="9.6" -port=”36677” -document=remoteExport

Parent topic

Installing the Remote API

Was this helpful?