attachments Collection: Files of an Entity
Description
The collection of attachments of the specified entity.
URL
/qcbin/rest/domains/{domain}/projects/{project}/{entity collection}/{Entity ID}/attachments
Remarks
When posting a new file with the content-type: multipart/form-data
header, the body of the request can have these parts:
Request Part | Required |
---|---|
filename |
![]() |
description | |
override-existing-attachment | |
ref-subtype | |
data |
![]() |
The data must be the last part of the body.
Options details
-
override-existing-attachment =y
If override-existing-attachment="y" an attachment having the same name is replaced. If no attachment of the same name exists, a new attachment is created.
If no description is posted, the existing description is kept.
-
override-existing-attachment=n [default]
If override-existing-attachment="n" or override-existing-attachment is not specified and there is an existing attachment with the same filename, a new attachment is created with a new name. You can see the new name in the returned string.
-
ref-subtype
The type of the attachment is either 0 (not rich content) or 1 (rich content). The default is 0.
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.
See the multipart/form-data example below.
Use multipart/form-data with web-client integrations, or if you want to set the description when posting the file.
For an example of how to post attachments, see the Attachments Code Sample.
Creating a Rich Text Field with an Embedded Graphic
Before reading this section, be familiar with Update an Entity.
This section uses the requirement field, req-rich-content as an example. The procedure is the same for any rich-text field.
Post the graphic file, passing a ref-subtype of 1.
Content-Disposition: form-data; name="ref-subtype" 1
Get the path of the uploaded graphic from the value returned from the POST and use it to create an HTML-encoded XML segment. This segment is the content of the req-rich-content field that you want to PUT to the requirement. For example:
<html><head></head><body><p><img src="../../../../../rest/domains/my_domain/projects/24_01_2012/requirements/1/attachments/ MY_IMAGE.JPG?alt=application/octet-stream" alt="" /></p></body></html>
- PUT the XML to the requirement. See the code sample, Update an Entity.
HTTP Methods
GET: Retrieves the list of attachments.
PUT: N/A
DELETE: N/A
POST: Creates a new attachment.
Media Type | GET
| PUT
| DELETE
| POST
|
---|---|---|---|---|
application/xml | ![]() | - | - | - |
application/json | ![]() | - | - | - |
multipart/form-data | - | - | - | ![]() |
application/octet-stream | - | - | - |
Returns
One of the HTTP Return Codes.
An XML string compliant with the Entities Collection Schema or a string containing the collection data in another supported format.
Examples
multipart/form-data
Header:Content-Type: multipart/form-data; boundary=exampleboundary;
Data:
--exampleboundary Content-Disposition: form-data; name="filename" example.txt --exampleboundary Content-Disposition: form-data; name="description" Here is the text that describes example.txt --exampleboundary Content-Disposition: form-data; name="override-existing-attachment" y --exampleboundary Content-Disposition: form-data; name="ref-subtype" 0 --exampleboundary Content-Disposition: form-data; name="file"; filename="example.txt" Content-Type: text/plain [Content of file] --exampleboundary--
The filename in the filename section must be identical to the filename in the file section .
In the above example, the ref-subtype
is unnecessary because the default is 0. It is shown here as a syntax example.
octet-stream
Headers:Data:Content-Type: application/octet-stream
Slug: filename.txt
Binary content of file.