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:

• 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

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

 AVAILABLE, 
 BUSY, 
 DISCONNECTED.
 The default state is AVAILABLE.

 EXECUTE,
 IMPORT.

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>

 type, 
 task
 

 CANCEL
 

 true,
 false
 

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>

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

 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

 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.
 

 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.
 

Notes on the Execution Result

• 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

Notes about the interactions

• 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.