Thank You Card from NH Department of Education
Uploading a File to the Library

Attaching a File to an Equipment

Programmatically uploading and attaching a file to a Field object is possible using the Field API REST call:

POST /api/attachments

This week, I got an inquiry about how to attach a file to an equipment. I thought a little more explanation with a minimum code sample beyond online document might be helpful to understand the usage.

Attachments – Request

This is a call to upload/delete an attachment.


Supported Request Methods: Post


Required Parameters:

  • ticket : string - a ticket or token obtained from the login call.
  • project_id : string - the ID of the project to perform this action against.
  • thumb : multi-part form file containing the attachment's thumbnail image(*1) 
  • original : multi-part form file containing the attachment's original file
  • attachment : JSON format string - contain the attachment's details. (See more detail below.)   

*1) when I experimented, works without it although it is said to be required. 


"attachment" Parameter in Detail 

The last parameter attachment is defined as follows.

Required Parameters for "attachment":

  • size : int - the size in bytes of the attachment
  • filename : string - the name of the attachment
  • container_type : string - the type of object this attachment is connected to. One of Issue/Task/Equipment/CompletedChecklistItem/CompletedChecklist. 
  • container_id : string - the ID of the object this attachment is connected to
  • content_type : string - the MIME content type of the attachment
  • created_at : string - the date that the attachment was created 
  • updated_at : string - the date that the attachment was modified 
  • fcreate_date : string - the date that the file was created
  • fmod_date : string - the date that the file was modified

where the date time format has to be in the form of: "YYYY-MM-DD HH:MM:SS -HH:MM", for example, "2015-08-05 15:28:17 -0500"


Optional Parameters for "attachment": 

  • id : string - the attachment's unique ID. The ID will be created automatically if not provided
  • deleted : string - if set to true, will remove the attachment from the server
  • width : int - the width in pixels of this attachment's original image
  • height : int - the height in pixels of this attachment's original image
  • num_pages : int - the number of pages that this attachment contains
  • markup : JSON - any associated Vela Viewer markup. This must be sent as an array of SVG strings
  • caption : string - a text caption for the attachment
  • tags : string - a comma-separated list of tags

Note: some of above parameter may make sense depending on container_type of where you are attaching the file. In this post, we are also focusing on the minimum code. (I haven't tried everything myself as usually try out when a developer asks us. Something like markup might be interesting to try out at the next opportunity.) 

Here is an example of attachment JSON string: 


"fcreate_date":"2015-08-04 23:21:09 -04:00",

"fmod_date":"2015-08-04 23:21:09 -04:00",

"created_at":"2015-08-07 22:55:28 -04:00",

"updated_at":"2015-08-07 22:55:28 -04:00",







In this example, I'm uploading a pdf file named "Test.pdf" and attaching to an equipment. container_id is an id of equipment, which you get using /api/get_equipment. Note: line breaks are added for readability. 

Attachments – Response

Upon a successful request call, the response will look like this:  





"message":"Attachment was processed successfully",

"processed_date":"2015-08-08 02:38:52 +0000"


Once again, the line breaks are added for readability.

Attachments – Sample Code 

Here is the code sample to attach a file to an equipment: 

        public static string Attachments(string ticket, string project_id,
            string originalPath, string thumbPath,
            string container_id, string container_type)
            // (1) Build request
            var client = new RestClient();
            client.BaseUrl = new System.Uri(_baseUrl);

            // Set resource or end point
            var request = new RestRequest();
            request.Resource = "/api/attachments";
            request.Method = Method.POST;

            // Add parameters
            request.AddParameter("ticket", ticket);
            request.AddParameter("project_id", project_id);

            // Compose Attachment JSON string
            FileInfo original = new FileInfo(originalPath);
            Dictionary<string, string> att = new Dictionary<string, string>();

            // date time format: "2015-08-05 15:28:17 -0500";
            string dateTimeFormat = "yyyy-MM-dd HH:mm:ss zzz";
            string curTime = DateTime.Now.ToString(dateTimeFormat);
            att["fcreate_date"] = original.CreationTime.ToString(dateTimeFormat);
            att["fmod_date"] = original.LastWriteTime.ToString(dateTimeFormat);
            att["created_at"] = curTime;
            att["updated_at"] = curTime;

            att["size"] = original.Length.ToString();
            att["content_type"] = MimeMapping.GetMimeMapping(original.Name);
            att["filename"] = original.Name;
            att["container_id"] = container_id;     // e.g., equipment_id
            att["container_type"] = container_type; // e.g., "Equipment"

            // Conver to JSON format
            JsonSerializer JsonSerial = new JsonSerializer();
            string attachment = JsonSerial.Serialize(att);

            request.AddParameter("attachment", attachment);

            // Add Files
            request.AddFile("original", originalPath);
            request.AddFile("thumb", thumbPath); // works without it, too.

            // (2) Execute request and get response
            IRestResponse response = client.Execute(request);

            // Save response. This is to see the response for our learning.
            m_lastResponse = response;

            return response.StatusCode.ToString();   

I used Field API Intro Lab2 project as a base and modified to run /api/attachments. The workflow here is: 

  • /api/login (same as in Lab2)
  • /fieldapi/admin/v1/project_names (same as in Lab2) 
  • /api/get_equipment
  • /api/attachments 

The sample application's UI looks like below: 


When the call returns the status “Success”, you can go to the UI and verify if the file is uploaded:   


A minimum, yet, complete sample project can be downloaded from here