Attaching a File to an Equipment
08/04/2015
Programmatically uploading and attaching a file to a Field object is possible using the Field API REST call:
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:
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.
Mikako