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.
Supported Request Methods: Post
- 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:
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)
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.