What is a Property Attachment?

Properties in the Property Store are typically small objects smaller documents like JSON documents data for example. Sometimes, it is necessary to enrich this metadata and link it with binary data “binary attachments” like documents or images for example. This is where Property Attachments come in place: Property Attachments (or just Attachments for short) They contain binary block data and are always linked to exactly one Property. Property Attachments are similar to email attachments with the difference that their size can be theoretically unlimited.

The storage of the binary data of Attachments can heavily scale and its data size be theoretically be unlimitedscale well. Each Property can have 0..n Attachments assigned.

...

Create an Attachment (<=10MB)​

Before you can add binary data to an Attachment, you have to create it first and link it to an existing Property, using the command property.attachment.put.

...

This approach is fast and easy for files with size up to 10 MB. For files bigger than 10 MB, you need chunked uploads.

Create an Attachment (>10MB)​

Since the size of a single request is limited to max. 10 MB, in case you need to add Attachments with content size bigger than this, you must use chunked uploads instead.

...

This needs to be repeated until all content has been uploaded. In this example, the parameter index is omitted. In this case, the chunk index is automatically calculated. Also note to set the Content-Type to application/octet-stream.

Download Attachment​

In order to download the content of an Attachment, you can use the command property.attachment.content which will stream the whole content of the Attachment as as one single file to the client. The chunks will be concatenated automatically in the backend.

...

curl -u 'username:password' \
  -X GET 'https://hub-<your-domain>/api/v3/command/property.attachment.content?key=global/app/jobs/applicant/1&name=my-cv.pdf'

Download Attachment (chunked)​

For big Attachments > ~20 MB it makes sense to use chunked download, if possible in order to reduce system load and increase download speed. Furthermore you can easily implement pause and resume and do integrity checks per chunk. In this approach you first have to load the number of chunks of the Attachment using the command property.attachment.get and then you can call the command property.attachment.chunk.content for each index. At client side you have to merge the chunks finally into a single file. Here is an example how to download a the chunk at index 0:

curl -u 'username:password' \
  -X GET 'https://hub-<your-domain>/api/v3/command/property.attachment.chunk.content?key=global/app/jobs/applicant/1&name=my-cv.pdf&index=0'

Integrity check​

In order to do an integrity check of the chunks downloaded, you can use response header Digest which is sent with the response of the command property.attachment.chunk.content and contains the MD5 checksum of the downloaded chunk in format md5=<hexadecimal>, for example Digest: md5=3ead0df0186e96d94d5ab025c282ed1f.

...