Lineitems::attachments
Manage attachments attached to a LineItem
File/document vs Attachment vs Versions
On Winddle, a file (also called ‘document’ in the most general case) is:
- Attached to something else (Product, Checkpoint, Quote, etc.), hence the name “attachment” used hereafter
- A collection of versions: every attachment has many versions, one of them being the “current version” (the last one)
As such, the “attachment” is merely a container for versions, as well as the object to which comments can be attached to when discussing a file.
Resource formats
This endpoint (on create/update) is one of the few that will respond to a HTML request as a HTML multipart form is the only way to push an attachment directly to Winddle. If HTML multipart isn’t an option, then Winddle also offers uploading documents using the content encoded as a Base 64 string or using a remote url (winddle will then download the attachment and store it, as if it had been uploaded - it’s a complete copy and there are no differences with other type of attachment upload).
Note that although the request can be in HTML (Content-Type: multipart/form-data), the responses will be in JSON or XML (accept:application/json, text/javascript, /;).
Storage
An attachment is a Winddle object, and so are the versions, however, versions have a “storage” field which defines where the file is actually stored. For an external storage, the external url is also sent in the same url
field, and an additional field, storage_id
is given for reference.
All the versions of an attachment do not need to be on the same storage - it’s possible to mix and match.
Winddle currently only support Google Drive as external storage.
Attachment base fields
Most of those fields are set by Winddle automatically after the upload and are actually version fields for the latest version created for this attachment.
Name | Description |
---|---|
id | Integer (unique) |
source_id | String (max 255 chars) |
storage | String |
name | String, visible in interface |
filename | String, original filename |
created_at | Datetime |
updated_at | Datetime |
label | String, for virtual folders |
size | Integer, size in bytes |
url | Download url for attachment or external url for external storage |
mime_type | String |
Some fields are only available if the attachment is an image:
Name | Description |
---|---|
px40 | Url to 40px cropped version |
px75 | Url to 75px cropped version |
px150 | Url to 150px cropped version |
nc1000 | Url to 100px non-cropped version |
This field is only available when the version is stored outside of winddle:
Name | Description |
---|---|
external_id | String (meaning depends on storage ) |
Attachment associated resources
Owner
The owner is the user who first created the attachment. Its basic information are always returned in any response containing attachments, under the key owner
.
Versions
Full array of versions linked to the attachment. The last one is the “current” one and gives all of its values to the attachment itself. In most cases, the array under the key versions
can thus be completely ignored.
Comments
All attachments on Winddle can be commented on (although this feature isn’t always visible in the interface). All the posted comments are under the key comments
.
Supported Formats
JSON XMLGET /api/v1/line_items/:line_item_id/attachments
Retrieve attachments for a given LineItem
Accessible to any partner of the line item.
GET /api/v1/line_items/:line_item_id/attachments/:id
Retrieve one attachment for a given LineItem
Accessible to any partner of the line item.
POST /api/v1/line_items/:line_item_id/attachments
Create a new attachment for a given LineItem
This operation is authorized to any partner of the line item.
On Winddle, attachments are only containers for versions, which contain the actual file. Although versions_attributes
is an array, only one version of a datafile can be created / request - the array should only contain one element describing the version.
There are 3 ways to upload an attachment on Winddle (in order of priority if more than one provided):
- By providing a base64 data string that represents the file
- By providing a remote url (public)
- By providing the file directly in the body of the multipart request
Here are the fields for the elements in the versions_attributes
array:
Name | Type |
---|---|
note | Note for that version |
base64_data | File content encoded in base 64 |
remote_attached_url | String (unique, max 255 chars) |
attached | File (HTML multipart form) |
Examples
POST /line_items/:line_item_id/attachments { name: "MyFile.png", versions_attributes: [{ note: "Direct upload from our FTP", remote_attached_url: "ftp://www.mycompany.com/images/my_file.png" }] }
Params
Param name | Description |
---|---|
source_id optional |
ID in Customer’s source system (optional, max 255 char.) Must be a String |
name optional |
A name for the attachment. If no name provided, filename will be used Must be a String |
label optional |
The ‘folder’ (virtual) for his attachment Must be a String |
versions_attributes optional |
an array of versions An array of versions. Here is a list version attributes * base64_data allow you to submit an image as a base64 string * attached a file, any kind of format * remote_attached_url an url to find a file. the file is downloaded asynchronously. Please observe that * you can only submit a version at a time * you should only use one of the three attributes |
PUT /api/v1/line_items/:line_item_id/attachments/:id
Update an attachment for a given LineItem - including adding a new version
Also see LineItems::Attachments#create.
This operation is authorized to any partner of the line item.
Existing versions cannot be updated, they can only be deleted.
Examples
This will create a new version for the attachment with the provided :id. PUT /line_items/:line_item_id/attachments/:id { versions_attributes: [{ note: "Direct upload from our FTP", remote_attached_url: "ftp://www.mycompany.com/images/my_file.png" }] }
Params
Param name | Description |
---|---|
source_id optional |
ID in Customer’s source system (optional, max 255 char.) Must be a String |
name optional |
A name for the attachment. If no name provided, filename will be used Must be a String |
label optional |
The ‘folder’ (virtual) for his attachment Must be a String |
versions_attributes optional |
an array of versions An array of versions. Here is a list version attributes * base64_data allow you to submit an image as a base64 string * attached a file, any kind of format * remote_attached_url an url to find a file. the file is downloaded asynchronously. Please observe that * you can only submit a version at a time * you should only use one of the three attributes |
DELETE /api/v1/line_items/:line_item_id/attachments/:id
Delete the attachment and all its versions/comments
This operation is authorized to any line item managers and/or the original owner of this attachment.
PATCH /api/v1/line_items/:line_item_id/attachments/:id/move_to_checkpoint
Move an attachment from this checkpoint to another
The target checkpoint must belong to the same line item than the attachment is currently attached to.
This operation is authorized to any line item managers and/or the original owner of this attachment.
Params
Param name | Description |
---|---|
target_id optional |
Target checkpoint id Must be a Integer |