Attachments

An attachment is a file that is associated with another resource, such as a defect.

Remarks

Attachments are specified by their numerical ID. The file name cannot be used as the attachment ID. To get a file by name, use a query. See the example under Query Parameters.

The query parameter by-id is not valid.

To GET the binary file content, use header Accept: application/octet-stream.

To GET the binary file content and the meta-data, use header Accept: multipart/mixed.

Example of return value using header Accept: multipart/mixed

TTP/1.1 200 OK
Content-Encoding:   gzip
Content-Type:       multipart/mixed; boundary=b2c3d4
Date:               Mon, 27 Mar 2014 12:11:05 GMT
Server:             Jetty
 
 
--b2c3d4
Content-Disposition: form-data; name="entity.type"
  
defect
--b2c3d4
Content-Disposition: form-data; name="entity.id"
  
1002
--b2c3d4
Content-Disposition: form-data; name="description"
 
Screen capture of defect 1002.
--b2c3d4
Content-Disposition: form-data; name="content"; filename="myAttachment.jpg"
Content-Type: image/jpeg
Content-Transfer-Encoding: binary
  
...contents of myAttachment.jpg...
--b2c3d4--

To POST a new file, use header content-type: multipart/form-data header.

The body of the POST request has these parts:

Request Part	Comment	Required
filename	For example, myfile.txt
description	A free text description of the file
override-existing-attachment	override-existing-attachment="y": If there is an attachment with the same name, the attachment is replaced. If no description is posted, the description of the existing file is kept. If no attachment of the same name exists, a new attachment is created. override-existing-attachment="n" [default]: If there is an existing attachment with the same filename, a new attachment is created with a unique name. The unique name is created by appending a number to the file name. You can see the new name in the returned string.
ref-subtype	The type of the attachment is: 0 - not rich content [default] 1 - rich content If ref-subtype="1", the file can be linked to from a rich text field. For example, the file can be linked from a requirement `req-rich-content` field.
entity.type	The type of resource the attachment will be associated with. For example, "defect".
entity.id	The ID of the entity associated with the attachment.
file	The file contents must be the last part of the body.

Post example:

	Copy Code
* Request * POST http://my-server:8080/qcbin/api/domains/default/projects/REST/attachments/ HTTP/1.1 Content-Type: multipart/form-data; boundary=---------------------------7de23383056e Accept: application/json Referrer: http://my-server:8080/qcbin/doc/index5.html Accept-Language: en-US Accept-Encoding: gzip, deflate User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.1; WOW64; Trident/6.0) Connection: Keep-Alive Content-Length: 647 DNT: 1 Host: my-server:8080 Pragma: no-cache Cookie: JSESSIONID=1234567890; SMSESSION=1234567890; JSESSIONID=1234567890; h LWSSO_COOKIE_KEY=1234567890; QCSession=1234567890; ALM_USER=1234567890; XSRF-TOKEN=1234567890; name="entity.type" defect -----------------------------7de23383056e Content-Disposition: form-data; name="entity.id" 56 -----------------------------7de23383056e Content-Disposition: form-data; name="description" This is the attachment description -----------------------------7de23383056e Content-Disposition: form-data; name="filename" js_blob_file.xml -----------------------------7de23383056e Content-Disposition: form-data; name="file"; filename="blob" Content-Type: text/xml <a id="a"><b id="b">Four-score and seven years ago.</b></a> -----------------------------7de23383056e-- * Response * HTTP/1.1 201 Created Date: Mon, 22 Dec 2014 14:01:08 GMT Location: http://my-server:8080/qcbin/api/domains/default/projects/REST/attachments/4 Content-Type: application/json Content-Length: 283 Server: Jetty(9.1.3.v20140225) { "type":"attachment", "ref-subtype":0, "vc-user-name":null, "id":4, "last-modified":"2014-12-22 16:01:08", "description":"<html><body>\nattachment description\n</body></html>", "vc-cur-ver":null, "name":"js_blob_file.xml", "ref-type":"File", "file-size":60, "entity": {"id":56, "type":"defect"} }

Copy Code

*** Request *** 

POST http://my-server:8080/qcbin/api/domains/default/projects/REST/attachments/ HTTP/1.1
Content-Type: multipart/form-data; boundary=---------------------------7de23383056e
Accept: application/json
Referrer: http://my-server:8080/qcbin/doc/index5.html
Accept-Language: en-US
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.1; WOW64; Trident/6.0)
Connection: Keep-Alive
Content-Length: 647
DNT: 1
Host: my-server:8080
Pragma: no-cache
Cookie:
 JSESSIONID=1234567890;
 SMSESSION=1234567890; JSESSIONID=1234567890; h
 LWSSO_COOKIE_KEY=1234567890;
 QCSession=1234567890;
 ALM_USER=1234567890;
 XSRF-TOKEN=1234567890;
 name="entity.type"
defect
-----------------------------7de23383056e
Content-Disposition: form-data; name="entity.id"
56
-----------------------------7de23383056e
Content-Disposition: form-data; name="description"
This is the attachment description
-----------------------------7de23383056e
Content-Disposition: form-data; name="filename"
js_blob_file.xml
-----------------------------7de23383056e
Content-Disposition: form-data; name="file"; filename="blob"
Content-Type: text/xml
<a id="a"><b id="b">Four-score and seven years ago.</b></a>
-----------------------------7de23383056e--

*** Response ***

HTTP/1.1 201 Created
Date: Mon, 22 Dec 2014 14:01:08 GMT
Location: http://my-server:8080/qcbin/api/domains/default/projects/REST/attachments/4
Content-Type: application/json
Content-Length: 283
Server: Jetty(9.1.3.v20140225)
{
    "type":"attachment",
    "ref-subtype":0,
    "vc-user-name":null,
    "id":4,
    "last-modified":"2014-12-22 16:01:08",
    "description":"<html><body>\nattachment description\n</body></html>",
    "vc-cur-ver":null,
    "name":"js_blob_file.xml",
    "ref-type":"File",
    "file-size":60,
    "entity":
        {"id":56,
         "type":"defect"}
}

URIs

/qcbin/api/domains/{domain}/projects/{project}/attachments

/qcbin/api/domains/{domain}/projects/{project}/attachments/{ID}

Limitations

See General Notes and Limitations
Only the file name and description can be changed with a PUT operation.

To change the contents of the file, POST the new version, using override-existing-attachment="y" in the multipart form data.

To change the ref-subtype, delete the attachment and POST a new version.

Header Parameters

See Standard Headers

Query Parameters

The valid query parameters are:

entity.type - For example, "defect".
entity.id - The ID of the entity associated with the attachment.
name - The file name. Only one file name can be specified. For example, this query is not valid: ?query={entity.type[defect];entity.id[1];name[file1.txt or file2.txt]}.
id - The attachment ID. If you use the id field as a query parameter, no other field can be used. For example: ?query={id[2 or 4]}

For a GET operation, if the file name is used in a filter, the entity.type and entity.id parameters are required. More than one entity.id can be specified.

Example: /qcbin/api/domains/my-domain/projects/my-project/attachments/?query={entity.type[requirement];entity.id[2 or 4];name[my-file.txt]}

Header Parameters

See Standard Headers

Returns

GET with an Accept header of application/json returns a descriptor of the attachment entity.

GET with an Accept header of application/octet-stream, returns the file. The Content-Type header reflects the type of file.

See Return Values

Working_With

Collections

Instances