The TrackTik API features an endpoint to submit file data.

File data can be submitted in two different ways:

1. Classic Form Data
2. Base64 encoding in a JSON payload

Method 1 : Sending one or more files as Form Data

When using an HTTP request building tool like Postman, you can choose to submit a payload as form-data, with an array key of file[] and one or more files selected via the operating system’s file requestor when you click the “File” datatype next to the key’s name:

In C# RestSharp for example that can be done as (suggested by Postman):

var options = new RestClientOptions("https://innovation.staffr.net") { MaxTimeout = -1, }; var client = new RestClient(options); var request = new RestRequest("/rest/v1/file-upload", Method.Post); request.AddHeader("Authorization", "Bearer eyJ0eXAiOiJKV<snip>"); request.AddHeader("Cookie", "PHPSESSID=4ertorvrpdc3t90vkr5qoltilnr262vj"); request.AlwaysMultipartFormData = true; request.AddFile("file[]", "/C:/Users/homefolder/Desktop/file upload/2023-05-03 14_59_50-Post Order API Review please _ Microsoft Teams.png"); RestResponse response = await client.ExecuteAsync(request); Console.WriteLine(response.Content);

The filename will be retained when stored so be sure to de-identify its name if you’d like to obfuscate its contents some.

Method 2 : Sending one or more files as JSON with Base64 encoding

If you’d prefer encoding your file data into a JSON payload, use Base64 for the file part, and take note of the file’s mime-type. Both are needed to build the payload. You can submit multiple files at once within the “file”: [] array container. Here’s an example:

{ "file" : [ "data:image/png;base64,iVBORwOKG<etc.>" ] }

Responses

When you submit the file as form data, you will receive JSON as a response with an ID number generated for each of the file submitted. Retain these ID values so that you can use them again elsewhere in your integration, like the integer value for “attachment” in the entity “post-orders”.

Sample response:

{ "id": 9560 }

Headers

While not always shown in the tool or library used for making REST calls, they tend to take care of certain header values for you like Content-Type and Content-Length. If you run into difficulty, be sure that the header being generated includes a Content-Type of multipart/form-data and Content-Length in an integer value of bytes.

Limits

The maximum size of data you can submit as form data or JSON data, is 100 MB total per request.

Using the File ID: Post Orders

Sample usage where a /post-order was patched with the ID number as the “attachment” key’s value:

BEFORE

{ "subject": 25, "details": "Read link", "account": 687, "version": null, "attachment": null, "id": 50 }

[PATCH] /post-orders/50

{ "attachment" : 9560 }

AFTER

{ "subject": 25, "details": "Read link", "account": 687, "version": 1683147010, "id": 50, "attachment": { "url": "https://innovation.staffr.net/rest/v1/media/9560/4b282876371982fc2b2e1bf79408c0b01b1349b1", "tag": "PICTURE", "format": "png", "name": "2023-05-03 14_59_50-Post Order API Review please _ Microsoft Teams.png", "id": 9560 }

You can de-link the image by re-patching the attachment key’s value to null:

[PATCH] /post-orders/50

{ "attachment" : null }

Result

{ "subject": 25, "details": "Read link", "account": 687, "version": 1683147139, "attachment": null, "id": 50 }

Using the File ID: Report Fields

When creating a new report via the API, you can also include a JSON object of the array of report field values. To do this you must already know the IDs of the values of the Report Template Fields that hold the data definition of the data to expect in the Report Fields.

If you’ve uploaded an image you’d like to have included in a Report’s Report Fields data, you can include this for the Image Report Template Fields types.

Example of posting a Report and its Report Fields (based on Report Template Fields) in the same payload:

[POST] /reports

{ "reportTemplate": 1128, "timeZone": "America/New_York", "reportDateTime": "2023-10-26T15:24:17-04:00", "submitTime": 1698089057, "submittedOn": "2023-10-26T19:24:17+00:00", "account": 687, "reportFlag": 352, "siteLocation": 470, "reportFields": [ {"field": 1129, "value": "sometext"}, {"field": 1130, "value": "Property Damage"}, {"field": 1133, "value": "Test for report attachments"}, ==> {"field": 1138, "value" : 9686} ] }

In this example, on line 14 of the of the list of Report Fields, is a Report Template Field who’s ID is 1138, and its datatype is that of Image. The value 9686 is the File ID returned when a media file is uploaded in a previous step.

TrackTik creates a lot of context-sensitive relations between its data objects and while most of the time these will be the IDs of the stand-alone records themselves, sometimes there are foreign key tables that provide different IDs for additional opportunities in data referrentiality. Providing the File ID for an Image Report Template Field in a Report as a Report Field is one of those examples. When you submit the above report payload and let’s say it creates a new report of ID 4675, and do a GET with include parameter to check the Report Fields that are persisted, you will see that the File ID of 9686 is not preserved. A new ID is generated for this new Report’s Report Field:

[GET] /reports/4675?include=reportFields

{ "reportTemplate": 1128, "timeZone": "America/New_York", "reportDateTime": "2023-10-26T15:24:17-04:00", "submitTime": 1698348257, "submittedOn": "2023-10-26T19:24:17+00:00", "account": 687, "position": null, "approvedOn": "2023-10-26T14:38:28+00:00", "approvalDateTime": "2023-10-26T14:38:28+00:00", "status": "APPROVED", "approvedBy": 1, "checkpoint": null, "reportFlag": null, "siteLocation": null, "id": 4675, "reportFields": [ { "fieldTag": "", "report": 4675, "templateField": 1129, "value": { "type": "text", "value": "sometext" }, "archived": false, "id": 23205 }, <snip> { "fieldTag": "", "report": 4675, "templateField": 1138, "value": { "type": "image", ==> "fileId": 9702, "value": "https://innovation.staffr.net/rest/v1/media/9702/86d36fe7118eb5d1f9575faf5a26155ef94dac48" }, "archived": false, "id": 23208 } ]

Notice how even if File ID 9686 was provided, the File ID associated with the Report Field of that Image datatype is 9702. The URI value can be downloaded (by means of mediaToken authentication) and the image will be the same as the original file upload from before the Report’s creation.

Uploading Employee Profile Pictures

The Employee entity has a dedicated action for uploading pictures so you don’t need to use the generic uploader and then do any patching. It can all be achieved in a single request.

You need to base64 encode your image data, set the request headers and prefix the base64 data with a mime type just the same though.

E.g.

[POST] /employees/1404/actions/upload-picture

{ "base64" : "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABDAAAAL6CAYAAAD etc." }

Notice the prefix:

data:image/png;base64,

This must be ahead of any base64 stream of text. The image/png is the mime type. Whatever you’re sending as image data needs to have this mime type. For a PNG image, it’s image/png. For JPG it’s image/jpg etc.

After uploading an image the web portal’s cache should respond to it as a new image and display it, but if not, you might have to close the browser or the tab with the portal loaded and re-load the employee profile.