Attachment DTO v16

Attachment represents a binary file together with name, description and a reference to any other object. This object gets usually linked to activities where one can attach photos and audio notes or even pdf documents and other documents (depending on the client).

This can be useful to transmit manuals or weekly detail reports to mobile app users.


Most of the attachments can be displayed inline without opening an external application to display its content.

These include:

png, tiff, gif, jpg, jpeg, bmp, ico, cur, xmb
txt, rtf, htm, html, xml, pdf, doc, ppt, xl
docx, pptx, xlsx, mp4, aac, mov, 3gpp, m4v

Other types of attachments are also supported but they cannot be displayed inside of the application (no native support for reading those files by the operating system). These attachments can be opened by the user in the application that supports opening those types of attachments:

  • 3D images (dwg, dwf, dxf) - can be opened by application AutoCAD (iOS)

Additionally, although all attachments can be displayed inline, the user always have the option to open using an external application that supports displaying/manipulating the given attachment. This action is usually placed in the action button on the attachments detail screen which allows user to select the application in which the attachment shall be opened.

How attachments are stored on the device?

1. After attachment is downloaded from the cloud, it’s stored on the file system of the device.
2. All attachments are stored in one folder.
3. All attachments are stored per company (when company gets deleted, attachments are deleted as well). For more information on when the attachments are deleted from the device see section How does attachments caching work?
4. Attachments are saved to the disk with the file name that equals the guid of the object and the extension that is mentioned in the AttachmentDTO in the field fileExtension.

Exception: In case the value of the property fileExtension equals to THREEGP, the extension 3gp is used.

How does attachments caching work?

1. Attachments caching is the functionality that allows the device to keep already downloaded attachments on disk so that the user can use them offline.
2. Caching can be enabled in the application settings. By default, it’s disabled.
3, When caching is disabled, attachments are deleted upon next synchronization is triggered.
4. When caching is enabled, attachments will be deleted only if ‘Caching’ option will be switched off or company gets deleted.

How attachments are loaded?

Since attachments are cached on the disk permanently or temporarily (see How does attachments caching work?) - they can be either taken from the cache either downloaded from the cloud directly.

When an attachment is loaded, the application completes the following:

  • Firstly check if the attachment is cached on the disk and if so, this one should be displayed
  • If attachment is not cached, it should be downloaded from the cloud and cached correctly according to the current caching settings

How attachments are downloaded from the cloud?

Attachments are downloaded from the cloud using REST request with the given format:




  • DCILocation is the DCI location taken from the settings or from the company, the user is logged into
  • CN - current company name
  • UAN, UAP - credentials of currently logged in user
  • AG - attachment’s guid that should be sent to the client (can be found in the Attachment DTO)
  • CI - client identifier (see Common Mobile Service Specification)
  • UD - unique identifier of the device (in case of iOS device the MAC address of the WiFi card is used)

Error handling

Downloading attachment is considered as not successful if the HTTP response code is not in the range of 200-299.

Field Name Type Category Constraint Reference Description
category String Optional length >= 0 & length <= 255

Allowed values are defined into Enumerations having enumType = ATTACHMENT_CATEGORY.
For learning about Enumerations, please check this.
Provides a way of grouping attachments into categories.
description String Optional length >= 1 & length <= 2147483647 Contains description of the given attachment.
fileContent byte Optional The binary content of the attachment. Please use the Attachment API for reading or writing to this field.
fileName String Required length >= 1 & length <= 512 Name of the attached file.
object ObjectRef Required Referenced object for this attachment, standard referenced objects are activities.
ordinal Integer Optional Provides a way of ordering attachments.
sourceObject ObjectRef Optional Source object out of which this attachment was created, e.g. a checklist instance for attachment containing checklist report.
title String Optional length >= 1 & length <= 512 Attachment title.
type ContentType Optional Allowed values { PNG, TIFF, GIF, JPG, JPEG, TXT, RTF, HTML, HTM, XML, PDF, DOC, XLS, PPT, PPTX, XLSX, DOCX, MP4, AAC, MSG, ZIP, TIF, DWG, DWF, DXF, MOV, M4V, THREEGP, BMP, ICO, CUR, XBM } Type of the attachment (is also used to load the appropriate viewer on the client devices).