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