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.

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.

Request PartCommentRequired
filenameFor example, myfile.txt
descriptionA 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.typeThe type of resource the attachment will be associated with. For example, "defect".
entity.idThe ID of the entity associated with the attachment.
fileThe file contents must be the last part of the body.
Attachments
*** 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>\attachment 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

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

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

See Also