Bolte IT Consulting

HP ALM REST Link a defect to another entity

Using the REST API it is possible to link a defect to another entity.

In this article I want to show how to link an existing defect to a requirement using XML.

Identify required fields

According to the REST API documentation a link is described by the entity "defect-link".

First we need to identify required fields for the entity "defect-link". To do so we have to call the following URL e.g. using your browser.

https://{HOST}/qcbin/rest/domains/{DOMAIN}/projects/{PROJECT}/customization/entities/defect-link/fields?required=true

Its important to query for fields?required=true. Else you will receive a list of all fields.

My example project returned the following information in XML format, which matches the standard.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
<?xml version="1.0" encoding="UTF-8" standalone="true"?>
<Fields>
	<Field Label="Defect ID" Name="first-endpoint-id" PhysicalName="LN_BUG_ID">
		<Size>10</Size>
		<History>false</History>
		<Required>true</Required>
		<System>true</System>
		<Type>Number</Type>
		<Verify>false</Verify>
		<Virtual>false</Virtual>
		<Active>true</Active>
		<Editable>false</Editable>
		<Filterable>true</Filterable>
		<Groupable>false</Groupable>
		<SupportsMultivalue>false</SupportsMultivalue>
		<Visible>true</Visible>
		<VersionControlled>false</VersionControlled>
		<References>
			<RelationReference ReferencedEntityType="defect" RelationName="defectToDefectLinkLink_mirrored"/>
		</References>
	</Field>
	<Field Label="Linked Entity ID" Name="second-endpoint-id" PhysicalName="LN_ENTITY_ID">
		<Size>10</Size>
		<History>false</History>
		<Required>true</Required>
		<System>true</System>
		<Type>Number</Type>
		<Verify>false</Verify>
		<Virtual>false</Virtual>
		<Active>true</Active>
		<Editable>false</Editable>
		<Filterable>true</Filterable>
		<Groupable>false</Groupable>
		<SupportsMultivalue>false</SupportsMultivalue>
		<Visible>true</Visible>
		<VersionControlled>false</VersionControlled>
 
		<References ReferenceTypeField="second-endpoint-type">
			<RelationReference ReferencedEntityType="test-set" RelationName="testSetToDefectLinkLink_mirrored"/>
			<RelationReference ReferencedEntityType="defect" RelationName="defectToDefectLinkLinkLeft_mirrored"/>
			<RelationReference ReferencedEntityType="test" RelationName="testToDefectLinkLink_mirrored"/>
			<RelationReference ReferencedEntityType="run-step" RelationName="runStepToDefectLinkLink_mirrored"/>
			<RelationReference ReferencedEntityType="requirement" RelationName="requirementToDefectLinkLink_mirrored"/>
			<RelationReference ReferencedEntityType="test-instance" RelationName="testInstanceToDefectLinkLink_mirrored"/>
			<RelationReference ReferencedEntityType="run" RelationName="runToDefectLinkLink_mirrored"/>
			<RelationReference ReferencedEntityType="test-config" RelationName="testConfigToDefectLinkLink_mirrored"/>
		</References>
	</Field>	
	
	<Field Label="Linked Entity Type" Name="second-endpoint-type" PhysicalName="LN_ENTITY_TYPE">
		<Size>40</Size>
		<History>false</History>
		<Required>true</Required>
		<System>true</System>
		<Type>String</Type>
		<Verify>false</Verify>
		<Virtual>false</Virtual>
		<Active>true</Active>
		<Editable>false</Editable>
		<Filterable>true</Filterable>
		<Groupable>false</Groupable>
		<SupportsMultivalue>false</SupportsMultivalue>
		<Visible>true</Visible>
		<VersionControlled>false</VersionControlled>
	</Field>
</Fields>

So, regarding to the above XML response the minimum set of fields to create a new link between two defects or between a defect and e.g. a requirement is as follows.

  • first-endpoint-id
  • second-endpoint-id
  • second-endpoint-type

POST a new link into the defect-links collection

https://{HOST}/qcbin/rest/domains/{DOMAIN}/projects/{PROJECT}/defect-links

Use the following URL to post a new defect-link.In order to create a new link between two entities, we have to POST an XML matching the Entity schema into the defect-link entity.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Entity Type="defect-link">
  <Fields>
    <Field Name="first-endpoint-id">
      <Value>459</Value>
    </Field>
    <Field Name="second-endpoint-id">
      <Value>2</Value>
    </Field>
    <Field Name="second-endpoint-type">
      <Value>requirement</Value>
    </Field>
  </Fields>
</Entity>

If you receive the HTTP Statuscode 201 ("Created") your request has been successfully processed and the link has been posted into the collection of defect-links.

If you receive the HTTP Statuscode 500 ("Internal Server Error") you will have to handle the returned exception message. For example if a link is already existing and you are trying to create it again, you will receive the following exception.

1
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><QCRestException><Id>qccore.general-error</Id><Title>These entities are already linked.</Title><ExceptionProperties/></QCRestException>

 

Hits: 8637