QmExecutionAdapter < Main

This wiki is locked. Future workgroup activity and specification development must take place at our new wiki. For more information, see this blog post about the new governance model and this post about changes to the website.
TWiki>
Main Web>QmHome>QmExecutionAdapter (07 Dec 2010, PaulMcMahan) (raw view)
<h1 id="titleL2-community">Quality Management-Execution Framework Resource Specification </h1>

_EARLY DRAFT: This is a draft for discussion_

---++ Introduction

Quality Management-Execution Framework resources document the execution framework artifacts of the test phase of the software delivery lifecycle. They represent individual external test execution software connected to Quality Manager, the tasks assigned to them and the execution result logs.

*Referenced Namespaces:*
   * *http://example.org/xmlns/alm/qm/v0.1/* - The Open Services for Lifecycle Collaboration Quality Management Namespace (default -- unless otherwise specified, the elements and attributes defined in this specification are from this namespace).
   * *http://jazz.net/xmlns/alm/v0.1/* - The Open Services for Lifecycle Collaboration ALM Namespace
   * *http://purl.org/dc/elements/1.1/* - The "simple" Dublin Core Metadata Element Set Version 1.1
   * *http://example.org/xmlns/alm/qm/qmadapter/v0.1/* - The Open Services for Lifecycle Collaboration Quality Management Adapters Namespace.
   * *http://example.org/xmlns/alm/qm/qmadapter/task/v0.1/* - The Open Services for Lifecycle Collaboration Quality Management Adapter task Namespace.

*Summary of Resources:*
   * *adapter* - An adapter to RQM to adapt to an external test execution software
   * *task* - A Task: A piece of work that is created and handed over to an adapter to execute. This task may typically be to execute a test script that is understood by that adapter.
   * *executionresult* - Contains the result of a test execution.

*Ancillary/Related Resources:*
   * *executionworkitem* - The task (in a work item system) to execute a test case.
   * *remotescript* - A type of test script that references an external tool based script.
   * *testplan* - A collection of various aspects of planning for a test.
   * *configuration* - Information about the configuration of the system under test
---++ Resource Descriptions
---+++ XML Representation of an Adapter Resource

An adapter is a resource that maps to a capability that helps integrate RQM to an external test tool, for example RFT, RPT etc. This allows RQM to be able to execute tasks (scripts) using these external tools. It is used by test management tools to be able to deploy executable tasks to a test tool that can handle them. The adapter may also report back status/progress of the execution back to the test management system. The adapter's role is to obtain the task and invoke the test tool to execute it.
---++++ Example
<verbatim>
<?xml version="1.0" encoding="utf-8"?>
<tooladapter xmlns:jzalm="http://jazz.net/xmlns/alm/v0.1/"
             xmlns:qmadapter="http://jazz.net/xmlns/alm/qm/qmadapter/v0.1"
             xmlns:dc="http://purl.org/dc/elements/1.1/">
  <dc:identifier>MyCommandLineAdapter</dc:identifier>
  <dc:title> Command Line Adapter </dc:title>
  <dc:description>This adapter can run a command or executable</dc:description>
  <jzalm:owner>
    <jzalm:name>Laura Lyons</jzalm:name>
    <jzalm:userid>llyons</jzalm:userid>
  </jzalm:owner>
  <qmadapter:type>com.ibm.rqm.adapter.commandline</qmadapter:type>
  <qmadapter:pollinginterval>3000</qmadapter:pollinginterval>
  <qmadapter:state>AVAILABLE</qmadapter:state>
  <qmadapter:hostname>akmathur</qmadapter:hostname>
  <qmadapter:ipaddress>192.168.1.100</qmadapter:ipaddress>
  <qmadapter:macaddress> 00-16-CF-F2-82-37</qmadapter:macaddress>
  <qmadapter:fqdn>akmathur.rationalnt.ibm.com</qmadapter:fqdn>
  <qmadapter:capability>EXECUTE</qmadapter:capability>
  <qmadapter:instructions
   href="https://qmserver:9443/jazz/server/secure/com.ibm.rqm.integration.service.IIntegrationService/adapter/MyCommandLineAdapter/instructions"/>
  <qmadapter:tasks
   href="https://qmserver:9443/jazz/server/secure/com.ibm.rqm.integration.service.IIntegrationService/tasks?adapterId=MyCommandLineAdapter"/>
</tooladapter>
</verbatim> 
| *XML Representation Summary:* tooladapter *Element* ||
| &lt;tooladapter<br /> href = xsd:anyURI &gt; <br /> _Content_: (dc:identifier+, dc:title+, dc:description?, jzalm:owner?, qmadapter:type+, qmadapter:pollinginterval+, qmadapter:state?, qmadapter:hostname+, qmadapter:ipaddress+, qmadapter:macaddress+, qmadapter:fqdn+, qmadapter:capability+)<br />&lt;/tooladapter&gt; ||
| *Property* | *Representation* |
| {dc:identifier} | The *required* id string that identifies this adapter. Note that this element comes from the DC namespace, allowing tools completely ignorant of the quality management domain to access this element. |
| {dc:title} | The *required* title string that gives this adapter a name. Note that this element comes from the DC namespace, allowing tools completely ignorant of the quality management domain to access this element. |
| {dc:description} | The *optional* description string describing this adapter. Note that this element comes from the DC namespace, allowing tools completely ignorant of the quality management domain to access this element. |
| {jzalm:owner} | The *optional* owner element, identifying the owner of this adapter (as specified in the http://example.org/xmlns/alm/v0.1 namespace). The owner is the person (or entity) responsible for the ensuring that this adapter is available for use. |
| {qmadapter:type} | The *required* type of this adapter that binds it to a specific test execution tool. |
| {qmadapter:pollinginterval} | The *required* number of seconds stating how frequently the adapter will poll the test management server for instructions. |
| {qmadapter:state} | The *optional* string describing the current state of the adapter - the permissible values are <pre> AVAILABLE, <br /> BUSY, <br /> DISCONNECTED.<br /> The default state is AVAILABLE.</pre> |
| {qmadapter:hostname} | The *required* string which is the hostname of the machine that the adapter is currently running on. |
| {qmadapter:ipaddress} | The *required* string that is the IP Address of the machine that the adapter is running on. |
| {qmadapter:macaddress} | The *required* physical address of the machine that the adapter is running on. |
| {qmadapter:fqdn} | The *required* Fully Qualified Domaion Name of the machine that theadapter is running on. |
| {qmadapter:capability} | The *required* capabilty of the adapter - permissible values are <pre> EXECUTE,<br /> IMPORT.</pre>Multiple of these capabilities may be specified separately. At-least one should be specified, otherwise there is no need for an adapter. |
| {qmadapter:instructions} | This *calculated* URL that the adapter can invoke to retrieve instructions for that adapter to handle. This is returned in a GET. This is ignored if provided in a POST. |
| {qmadapter:tasks} | This *calculated* URL that the adapter can invoke to retrieve instructions for that adapter to handle. This is returned in a GET. This is ignored if provided in a POST. |
---++++ Notes on Adapter Resource
   * When a tooladapter is posted to a registry, the resulting tooladapter will have its 'instructions' and 'tasks' elements set to point to the appropriate collections.
   * The tooladapter's POST handler will ignore the instructions and tasks elements if present in the POSTed tooladapter.
---+++ XML Representation of Adapter Instructions Collection

This is a set of instructions that may periodically be available for an adapter to handle immediately. Test Management tools may have instructions created by the user of the system to interact with a task that isbeinbg performed by the adapter. These instructions are directly associated with an adapter.
---++++ Example
 <verbatim>
<?xml version="1.0" encoding="utf-8"?>
<instructions xmlns:qmadapter="http://jazz.net/xmlns/alm/qm/qmadapter/v0.1">
  <qmadapter:instruction type="CANCEL"
  task="https://qmserver/jazz/secure/service/com.ibm.rqm.integration.service.IIntegrationService/task/1"/>
  <qmadapter:workavailable>true</qmadapter:workavailable>
</instructions>
</verbatim> 
| *XML Representation Summary:* instructions *Element* ||
| &lt;instructions<br /> id = xsd:string &gt;<br /> _Content_: (qmadapter:instruction?, qmadapter:workavailale+)<br />&lt;/instructions&gt; ||
| *Property* | *Representation* |
| {qmadapter:instruction} | The *optional* instruction for an adapter. The attributes of an instruction are <pre> type, <br /> task<br /> </pre>and both are *required*. The permissible value for type is <pre> CANCEL<br /> </pre>The task is the URL of the task being handled by the adapter that this instructions is destined for. |
| {qmadapter:workavailable} | The *required* boolean value for whether there is work available for the adapter to download and process. Permissible values are <pre> true,<br /> false<br /> </pre>Default when not available is false which means no work is available at the moment. |
---+++ XML Representation of a Adapter Task Collection

The collection of tasks assigned to an adapter.
---++++ Example:
 <verbatim>
<?xml version="1.0" encoding="utf-8"?>
<adapterservice xmlns:qmadapter="http://jazz.net/xmlns/alm/qm/qmadapter/v0.1">
  <qmadapter:task
  href="https://qmserver:9443/jazz/secure/service/com.ibm.rqm.integration.service.IIntegrationService/tasks/1"/>
  <qmadapter:task
  href="https://qmserver:9443/jazz/secure/service/com.ibm.rqm.integration.service.IIntegrationService/tasks/2"/>
</adapterservice>
</verbatim> 
---++++ Notes on the collection
   * The URL for getting a collection of tasks assigned to an adapter may be retrieved by invoking the URL that was provided in the GET of an adapter.
   * The information about which adapter the task is assigned to, is embedded into the resource and is available by doing a GET on that task.
---+++ XML Representation of an adapter Task

A task is a piece of work created to be handled by an adapter.
---++++ Example
 <verbatim>
<?xml version="1.0" encoding="utf-8"?>
<adaptertask xmlns:qmtask="http://jazz.net/xmlns/alm/qm/qmadapter/task/v0.1"
             xmlns:qm="http://jazz.net/xmlns/alm/qm/v0.1/"
             xmlns:dc="http://purl.org/dc/elements/1.1/">
  <dc:identifier>3</dc:identifier>
  <qmtask:selectedAdapterId>9</qmtask:selectedAdapterId>
  <qmtask:type>EXECUTE</qmtask:type>
  <qmtask:progress>0</qmtask:progress>
  <qmtask:taken>false</qmtask:taken>
  <qmtask:managedbyadapter>true</qmtask:managedbyadapter>
  <qmtask:fullpath>c:\windows\notepad.exe</qmtask:fullpath>
  <qmtask:relativepath>null</qmtask:relativepath>
  <qmtask:shareprefix>null</qmtask:shareprefix>
  <qmtask:fileSeperater>\</qmtask:fileSeperater>
  <state>com.ibm.rqm.executionframework.common.requeststate.nottaken</state>
  <qmtask:owner>ADMIN</qmtask:owner>
  <qmtask:requestIndex>2</qmtask:requestIndex>
  <qm:remotescript
   href="https://localhost:9443/jazz/service/com.ibm.rqm.integration.service.IIntegrationService/remotescript/urn:com.ibm.rqm:remotescript:17"/>
  <qm:resource
   href="https://localhost:9443/jazz/secure/service/com.ibm.rqm.integration.service.IIntegrationService/resource?resourceURN=\\9.124.23.228\incoming\notepad.exe"/>
  <qmtask:ewi
   href="https://localhost:9443/jazz/service/com.ibm.rqm.integration.service.IIntegrationService/executionworkitem/urn:com.ibm.rqm:executionworkitem:44"/>
  <qmtask:updateURL
   href="https://localhost:9443/jazz/service/com.ibm.rqm.integration.service.IIntegrationService/tasks/3"/>
  <qmtask:resultURL
   href="https://localhost:9443/jazz/service/com.ibm.rqm.integration.service.IIntegrationService/executionresult/"/>
</adaptertask>
</verbatim> 
| *XML Representation Summary:* task *Element* ||
| &lt;task <br /> href = xsd:anyURI &gt;<br /> _Content_: (dc:identifier+, qmtask:selectedAdapterId+, qmtask:type+, qmtask:progress?, qmtask:taken+, qmtask:managedbyadapter+, qmtask:fullpath?, qmtask:shareprefix?, qmtask:relativepath?, qmtask:absolutePath?, qm:remotescript+, qm:ewi+, qm:scripttype+, dc:owner?, qm:resource?)<br />&lt;/task&gt; ||
| *Property* | *Representation* |
| {dc:identifier} | The *required* identifier of the task. |
| {qmtask:selectedAdapterId} | The *required* ID of the adapter that this task was destined for. |
| {qmtask:type} | The *required* type of the task to be performed. Permissible values are EXECUTE, IMPORT |
| {qmtask:progress} | The *required* number which shows how far the task has been processed. This is a number between 0 & 100. |
| {qmtask:taken} | The *required* boolean that indicates if the task has been taken for processing by any adapter or is still hasnt started to be processed. |
| {qmtask:managedbyadapter} | The *required* boolean that indicates if the executable resource is one thats managed by the adapter and can be accessed locally by the adapter or is one thats managed by the test management system and needs to serve it. Permissible values are true, false |
| {qmtask:fullpath} | The *optional* fullpath is the path to the resource in the case where its managed by the adapter i.e. managedbyadapter is true. |
| {qmtask:shareprefix} | The *optional* leading part of the path to the resource in the case where its managed by the test management solution i.e. managedbyadapter is false. |
| {qmtask:relativepath} | The *optional* trailing part of the path to the resource in the case where its managed by the test management solution i.e. managedbyadapter is false. |
| {qmtask:absolutePath} | The *optional* full path to the resource in the case where its managed by the test management solution i.e. managedbyadapter is false. |
| {qmtask:remotescript} | The *required* URL of the script that this task is executing. |
| {qmtask:ewi} | The *required* URL of the test execution record whose execution lead to the creation of this task. |
| {qmtask:ewi} | The *required* type of the script that this task will execute. |
| {dc:owner} | The *optional* owner of this task. This is the user that started the task to be executed. |
| {qmtask:resourceURL} | The *optional* URL to the external script resource that the adapter may invoke to download and execute. This is served by the test management server or more generically a file server. This is available only in the case where managedbyadapter is true. |
| {qmtask:resultURL} | The *optional* URL to the result of the execution for this task. |
---++++ Notes on the Task resource
   * In order for the task to be taken by an adapter in order to process, the adapter will PUT a single attribute &lt;qmtask:taken&gt; with a value of true. This should be permissible.
   * There is a single URL from the qmtask:script attribute that provides access to the script resource within the test management solution. The adapter may use this URI to fetch the RQM script resource.
   * The resource URL is used to access the external resource referenced by the script being executed and is a resource that is understood by the test tool that will execute it.
   * There is some redundant data in here that needs to be cleaned up a little bit and some that may not be useful for a consumer of this resource. Some have been cleaned, more needs to happen.
   * In a lot of cases, the UUIDs of the resources have made it to the resource documents becsaue the UI can only deal with the UUIDs for the moment. W eneed ot look at how to convert the UI to consume resource URLs.
   * The GET URL used to get this task maybe POSTed against. So we may not need the updateURL in this. This was implemented for conveneince of APIS :-(
   * There is an open defect for proper handling of custom properties in adapter tasks. At present they just show up as any other properties. (9042: Cleanup the list of properties from the adapter request)
---+++ XML Representation of an Execution Result

An Execution Result is the output of executing a Task (script).
---++++ Example
 <verbatim>
<?xml version="1.0" encoding="utf-8"?>
<qm:executionresult xmlns:jzalm="http://jazz.net/xmlns/alm/v0.1/"
             xmlns:qmresult="http://jazz.net/xmlns/alm/qm/v0.1/executionresult/v0.1"
             xmlns:qm="http://jazz.net/xmlns/alm/qm/v0.1/" 
             xmlns:customnamespace="http://externaltool.com/xmlns/qm/custom/v0.1/">
  <jzalm:state>com.ibm.rqm.execution.common.state.passed</jzalm:state>
  <qmresult:buildid>null</qmresult:buildid>
  <qmresult:starttime>1218345415741</qmresult:starttime>
  <qmresult:endtime>1218345418069</qmresult:endtime>
  <qmresult:pointsattempted>10</qmresult:pointsattempted>
  <qmresult:pointspassed>10</qmresult:pointspassed>
  <qmresult:pointsfailed>0</qmresult:pointsfailed>
  <qmresult:pointsblocked>0</qmresult:pointsblocked>
  <qmresult:pointsinconclusive>0</qmresult:pointsinconclusive>
  <qmresult:stepresults result="com.ibm.rqm.execution.common.state.passed"
    startTime="1218355995597" endTime="12183559956247">
    <qmresult:stepresult>
      <qmresult:property propertyName="CustomProperty" propertyValue="CustomValue" propertyType="NamespacePrefix:NamespaceURI"/>
    </qmresult:stepresult>
  </qmresult:stepresults>
  <qm:script
   href="https://localhost:9443/jazz/secure/service/com.ibm.rqm.integration.service.IIntegrationService/remotescript/urn:com.ibm.rqm:remotescript:17"/>
  <qm:executionworkitem
   href="https://localhost:9443/jazz/secure/service/com.ibm.rqm.integration.service.IIntegrationService/executionworkitem/urn:com.ibm.rqm:executionworkitem:34"/>
  <qm:attachment
   href="https://localhost:9443/jazz/secure/service/com.ibm.rqm.planning.service.internal.rest.IAttachmentRestService/1"/>
  <qm:attachment
   href="https://localhost:9443/jazz/secure/service/com.ibm.rqm.planning.service.internal.rest.IAttachmentRestService/2"/>
  <customnamespace:customproperty propertyValue="Some Property Value"/>
</qm:executionresult>
</verbatim> 
| *XML Representation Summary:* executionresult *Element* ||
| &lt;executionresult <sup> [[#execresult_get_put_sync][[1]]]</sup><br /> href = xsd:anyURI &gt;<br /> _Content_: (alm:state+, qmresult:buildid?, qmresult:starttime?, qmresult:endtimte?, qmresult:pointsattempted?, qmresult:pointspassed?,qmresult:pointsfailed?,qmresult:pointsblocked?,qmresult:pointsinconclusive?, qmresult:remoteexecution?, qmresult:script?, qmtask:executionworkitem+, qmresult:adapter?, qmresult:attachment?)<br />&lt;/executionresult&gt; ||
| *Property* | *Representation* |
| {alm:state} | The *required* state of the result. Permissible values are <br /><pre> com.ibm.rqm.execution.common.state.passed<br /> com.ibm.rqm.execution.common.state.failed<br /> com.ibm.rqm.execution.common.state.error<br /> com.ibm.rqm.execution.common.state.blocked<br /> com.ibm.rqm.execution.common.state.inconclusive<br /></pre> |
| {qmresult:buildid} | The *optional* ID of the build of the system under test that this execution was against. |
| {qmresult:starttime} | The *optional* timestamp (UTC) when the execution was started. |
| {qmresult:endtime} | The *optional* timestamp (UTC) when the execution was completed. |
| {qmresult:pointsattempted} | The *optional* number of points that were attempted. |
| {qmresult:pointspassed} | The *optional* number of points that passed. |
| {qmresult:pointsfailed} | The *optional* number of points that failed. |
| {qmresult:pointsblocked} | The *optional* number of points that were blocked. |
| {qmresult:pointsinconclusive} | The *optional* number of points that were inconclusive. |
| {qmresult:remoteexecution} | The *optional* flag to indicate if the execution that resulted in this execution result was local to the server or remote. Permissible values are true, false. |
| {qm:script} | The *optional* URL of the script being executed. |
| {qmexecutionworkitem} | The *required* URL of the execution work item that is executing. |
| {qmresult:adapter} | The *optional* URL of the adapter executing this task. |
| {qm:attachment}<sup> [[#execresult_get_put_sync][[1]]]</sup> | The *optional* URL of an attachment of this execution reuslt. |
| {customnamespace:customproperty}<sup> [[#execresult_get_put_sync][[1]]]</sup> | An *optional* custom property within a custom namespace filed by an external source. |
| {qmresult:stepresults}<sup> [[#execresult_get_put_sync][[1]]]</sup> | An *optional* grouping of step results. |
| {qmresult:stepresult}<sup> [[#execresult_get_put_sync][[1]]]</sup> | An *optional* single step result. This has the attributes of <pre> result - the state of the step. Permissible values are those allowed on the execution result state.<br /> startTime - the beginning time stamp of this step result<br /> endTime - the ending time stamp of this step result.<br /> </pre>A step result may also have properties associated. Each property defined as {qmresult:property} should have the required attributes of <pre> propertyName - this is the name of the property<br /> propertyValue - the value of the property<br /> propertyType - this is the XMLNS definition tha this property belongs to.<br /> </pre> |
| <a name="execresult_get_put_sync"></a>[1] The GET action for execution result does not return the following properties at all in some cases or correctly in some customproperty, stepresults and attachment. See defect 9043: Execution Result GET and PUT handlers are not in sync ||
---++++ Notes on the Execution Result
 This is by far one of the most complicated resource with many characteristics that are desirable 
   * This needs to be a running document that is often updated.
   * Need to figure out if the 'step results' are really individual resources that are refrenced from the master execution result document.
   * How do we deal with attributes that may have more than a value - for instance a type as in the case of properties.
---+++ Adapter / QM Server interactions
 A table of Adapter / QM Server interactions where these resources come into play. All URIs, for example, have a prefix of https://qmserver:9443/jazz/secure/service/com.ibm.rqm.integration.service.IIntegrationService <table cellspacing="0" cellpadding="0" border="1"> <tbody> <tr valign="top"> <th style="text-align: left">Document</th> <th style="text-align: left">Example URI</th> <th style="text-align: left">GET</th> <th style="text-align: left">PUT</th> <th style="text-align: left">POST</th> <th style="text-align: left">DELETE</th></tr> <tr valign="top"> <td>Collection of adapters</td> <td>/adapter</td> <td><sup> [[#point_1][[2]]]</sup>N/A</td> <td>Registers a new adapter; returns 201 (Created) and the URI of the adapter. Updates if already exist; returns 200 (Updated)</td> <td>N/A</td> <td>N/A</td></tr> <tr valign="top"> <td>An Adatper</td> <td>/adapter/1</td> <td>Returns an adapter document.</td> <td>Updates an adapter document.</td> <td>N/A</td> <td>(In the future, will effect deregistration of the adapter)</td></tr> <tr valign="top"> <td>collections of instructions - applicable to a particular adapter</td> <td>/adapter/1/instructions</td> <td>Returns the instructions for the adapter operations which apply to each of the adapter&rsquo;s tasks.</td> <td>N/A</td> <td>N/A</td> <td>N/A</td></tr> <tr valign="top"> <td>collection of adapter specific tasks</td> <td>/tasks?adapter=adapterId</td> <td>Gets a collection of all tasks allocated to this adapter</td> <td>invalid</td> <td>invalid</td> <td>Invalid</td></tr> <tr valign="top"> <td>task info</td> <td>/tasks/task1</td> <td>Gets the current description of a task</td> <td>Updates a task with the content provided in the data section - progress, state etc. This might be better off as a POST</td> <td>N/A</td> <td>N/A</td></tr> <tr valign="top"> <td>execution result collection</td> <td>/executionresults</td> <td>returns a collection of all execution results</td> <td>invalid</td> <td>Adds an ER to the collection</td> <td>invalid</td></tr> <tr valign="top"> <td>an execution result</td> <td>/executionresult/1</td> <td>Get a description of the execution result</td> <td>Updates a result</td> <td>N/A</td> <td>(To be supported)</td></tr> <tr> <td colspan="6"><a name="point_1"></a>[2] 9041: Execution Framework URI GET handlers doesn't correctly support request on collection URL</td></tr></tbody></table> 
---++++ Notes about the interactions
 There are various questions on this table 
   * Maybe the instructions should be its own collection and allow querying based on adapter IDs. Then this would be /instructions?adapter=1 for adapter based query.
   * Need agreement on whether POST - creates a resource and PUT - updates it and if this is OK.
Topic revision: r4 - 07 Dec 2010 - 14:46:24 - PaulMcMahan
Main.QmExecutionAdapter moved from Main.ExecutionAdapter on 27 Feb 2009 - 13:48 by ScottBosworth - put it back
Main
Webs
Main
Sandbox
TWiki
Copyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use
Ideas, requests, problems regarding this site? Send feedback