Checkpoints::attachments

Manage attachments attached to a Checkpoint

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.

NameDescription
idInteger (unique)
source_idString (max 255 chars)
storageString
nameString, visible in interface
filenameString, original filename
created_atDatetime
updated_atDatetime
labelString, for virtual folders
sizeInteger, size in bytes
urlDownload url for attachment or external url for external storage
mime_typeString

Some fields are only available if the attachment is an image:

NameDescription
px40Url to 40px cropped version
px75Url to 75px cropped version
px150Url to 150px cropped version
nc1000Url to 100px non-cropped version

This field is only available when the version is stored outside of winddle:

NameDescription
external_idString (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 XML

GET /api/v1/checkpoints/:checkpoint_id/attachments

Retrieve attachments for a given Checkpoint

Accessible to whoever can participate to the checkpoint.

GET /api/v1/checkpoints/:checkpoint_id/attachments/:id

Retrieve one attachment for a given Checkpoint

Accessible to whoever can participate to the checkpoint.

POST /api/v1/checkpoints/:checkpoint_id/attachments

Create a new attachment for a given Checkpoint

This operation is authorized to whoever can participate on the checkpoint.

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:

NameType
noteNote for that version
base64_dataFile content encoded in base 64
remote_attached_urlString (unique, max 255 chars)
attachedFile (HTML multipart form)

Examples

POST /checkpoints/:checkpoint_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/checkpoints/:checkpoint_id/attachments/:id

Update an attachment for a given Checkpoint - including adding a new version

Also see Checkpoints::Attachments#create.

This operation is authorized to whoever can participate on the checkpoint.

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 /checkpoints/:checkpoint_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/checkpoints/:checkpoint_id/attachments/:id

Delete the attachment and all its versions/comments

This operation is authorized to whoever can update the checkpoint and/or is the original owner of this attachment.

PATCH /api/v1/checkpoints/:checkpoint_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 original checkpoint (the one the attachment is currently attached to).

This operation is authorized to whoever can update the checkpoint and/or is the original owner of this attachment.

The current user must be able to participate on the target checkpoint.

Params

Param name Description
target_id
optional

Target checkpoint id

Must be a Integer

PATCH /api/v1/checkpoints/:checkpoint_id/attachments/:id/move_to_line_item

Move an attachment from this checkpoint to its line item

This operation is authorized to whoever can update the checkpoint and/or is the original owner of this attachment.