updateRequirementsByExtId Interface

The updateRequirementsByExtId interface is used to update requirements with existing root nodes from XML files. The requirements are identified by external IDs. The requirement tree node and all of the node's children are updated. New nodes are added, missing nodes are set to obsolete, and moved nodes are similarly moved in Silk Central. The HTTP response of the call contains the XML structure of the changed requirements. You can obtain the identifiers of the new nodes from the updated XML requirement structure.

The following table shows the parameters of the updateRequirementsByExtId interface.

Interface URL Parameter Descriptions

http://<front-end URL>/servicesExchange?hid=updateRequirementsByExtId

sid Web-service token or session identifier for user authentication. You can generate the web-service token in the Settings Page of the Silk Central UI. To access this page, hover the mouse cursor over the user name in the Silk Central menu and select User Settings. You can retrieve the session identifier by invoking the logonUser method of one of the Available Web Services.
  nodeID ID of the node in the requirement tree to be updated.

Example: http://<front-end URL>/servicesExchange?hid=updateRequirementsByExtId&nodeID=<id>&sid=<webServiceToken>

The XML schema definition file that is used to validate requirements can be downloaded by using the front-end server URL http://<front-end URL>/silkroot/xsl/requirements.xsd or copied from the front-end server installation folder <Silk Central installation folder>/wwwroot/silkroot/xsl/requirements.xsd.

updateRequirementsByExtId Web Service Example

The following code uses Apache HttpClient to update requirements.

import org.apache.commons.httpclient.*; // Apache HttpClient
		
String webServiceToken = "e39a0b5b-45db-42db-84b2-b85028d954d5";
URL service = new URL("http", mWebServiceHelper.getHost(),
  mWebServiceHelper.getPort(), 
  String.format("/servicesExchange?hid=%s&sid=%s",&nodeID=%s",
    "updateRequirementsByExtId",
    webServiceToken, rootNodeId));

HttpClient client = new HttpClient();
PostMethod filePost = new PostMethod(service.toExternalForm());
string xmlFile = loadRequirementsUtf8(fileName);
StringPart xmlFileItem = new StringPart("requirements", xmlFile,
  "UTF-8");
xmlFileItem.setContentType("text/xml");
Part[] parts = {xmlFileItem};

filePost.setRequestEntity(new MultipartRequestEntity(parts,
  filePost.getParams()));
client.getHttpConnectionManager().getParams().setConnectionTimeout(60000);
int status = client.executeMethod(filePost);
System.out.println(filePost.getStatusLine());

String responseXml = filePost.getResponseBodyAsString();

Only one attachment can be uploaded per request. To download Apache HttpComponents, visit http://hc.apache.org/downloads.cgi. Refer to the documentation of the component for the required libraries.

Requirements Example

The following code shows an example requirement that can be uploaded to Silk Central by using the createRequirements, updateRequirements and updateRequirementsByExtId service.

<?xml version="1.0" encoding="UTF-8"?>
<Requirement id="0" name="name" xmlns="http://www.borland.com/RequirementsSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://<front-end URL>/silkroot/xsl/requirements.xsd">
	<ExternalId>myExtId1</ExternalId>
	<Description>Description</Description>
	<Priority value="Low" inherited="false"/>
	<Risk value="Critical" inherited="false"/>
	<Reviewed value="true" inherited="false"/>
	<Property inherited="false" name="Document" type="string">MyDocument1.doc</Property>
	<Requirement id="1" name="name" />
	<Requirement id="2" name="name1">
		<Requirement id="3" name="name" />
		<Requirement id="4" name="name1">
			<Requirement id="5" name="name" />
      <Requirement id="6" name="name1">
        <ExternalId>myExtId2</ExternalId>
        <Description>Another Description</Description>
        <Priority value="Medium" inherited="false"/>
        <Risk value="Critical" inherited="false"/>
        <Reviewed value="true" inherited="false"/>
        <Property inherited="false" name="Document" type="string">MyDocument2.doc</Property>
			</Requirement>
		</Requirement>
	</Requirement>
</Requirement>