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.

Quality Management-Execution Framework Resource Specification

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:

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

<?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>
XML Representation Summary:* tooladapter *Element
<tooladapter
href = xsd:anyURI >
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+)
</tooladapter>
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
 AVAILABLE, 
BUSY,
DISCONNECTED.
The default state is AVAILABLE.
{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
 EXECUTE,
IMPORT.
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

<?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>
XML Representation Summary:* instructions *Element
<instructions
id = xsd:string >
Content: (qmadapter:instruction?, qmadapter:workavailale+)
</instructions>
Property Representation
{qmadapter:instruction} The optional instruction for an adapter. The attributes of an instruction are
 type, 
task
and both are required. The permissible value for type is
 CANCEL
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
 true,
false
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:

<?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>

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

<?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>
XML Representation Summary:* task *Element
<task
href = xsd:anyURI >
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?)
</task>
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 <qmtask:taken> 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 frown
  • 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

<?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>
XML Representation Summary:* executionresult *Element
<executionresult [1]
href = xsd:anyURI >
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?)
</executionresult>
Property Representation
{alm:state} The required state of the result. Permissible values are
 com.ibm.rqm.execution.common.state.passed
com.ibm.rqm.execution.common.state.failed
com.ibm.rqm.execution.common.state.error
com.ibm.rqm.execution.common.state.blocked
com.ibm.rqm.execution.common.state.inconclusive
{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} [1] The optional URL of an attachment of this execution reuslt.
{customnamespace:customproperty} [1] An optional custom property within a custom namespace filed by an external source.
{qmresult:stepresults} [1] An optional grouping of step results.
{qmresult:stepresult} [1] An optional single step result. This has the attributes of
 result - the state of the step. Permissible values are those allowed on the execution result state.
startTime - the beginning time stamp of this step result
endTime - the ending time stamp of this step result.
A step result may also have properties associated. Each property defined as {qmresult:property} should have the required attributes of
 propertyName - this is the name of the property
propertyValue - the value of the property
propertyType - this is the XMLNS definition tha this property belongs to.
[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
Document Example URI GET PUT POST DELETE
Collection of adapters /adapter [2]N/A Registers a new adapter; returns 201 (Created) and the URI of the adapter. Updates if already exist; returns 200 (Updated) N/A N/A
An Adatper /adapter/1 Returns an adapter document. Updates an adapter document. N/A (In the future, will effect deregistration of the adapter)
collections of instructions - applicable to a particular adapter /adapter/1/instructions Returns the instructions for the adapter operations which apply to each of the adapter’s tasks. N/A N/A N/A
collection of adapter specific tasks /tasks?adapter=adapterId Gets a collection of all tasks allocated to this adapter invalid invalid Invalid
task info /tasks/task1 Gets the current description of a task Updates a task with the content provided in the data section - progress, state etc. This might be better off as a POST N/A N/A
execution result collection /executionresults returns a collection of all execution results invalid Adds an ER to the collection invalid
an execution result /executionresult/1 Get a description of the execution result Updates a result N/A (To be supported)
[2] 9041: Execution Framework URI GET handlers doesn't correctly support request on collection URL

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
 
This site is powered by the TWiki collaboration platform 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