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.

URL: https://bim360field.autodesk.com/api/attachments

Supported Request Methods: Post

Documentation: https://bim360field.autodesk.com/apidoc/index.html#mobile_api_method_1

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″,

“size”:”25540″,

“content_type”:”application/pdf”,

“filename”:”Test.pdf”,

“container_id”:”f7b20557-2ab7-1543-86f1-08545d54d666″,

“container_type”:”Equipment”

}

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:

{

“id”:null,

“action”:”Create”,

“status”:”Success”,

“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:

Attachments

        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:

APIAttachmentSampleUI

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

AttachmentUI

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

Mikako

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s