Uploading Files

Files can be uploaded to the system for a variety of purposes;

  • Getting attached to documents

  • Uploading an ID photo to someones profile

  • Getting attached to a persons skill/qualification

To do this, files are;

  1. Uploaded to Amazon S3 to a temporary file storage location

  2. Then moved (internally) to their proper storage location (depending on what they’ll be used for - eg. as a document / ID photo / etc). This step is done by including the file information as part of the request to update data - eg. if you would like a photo to be set as someones ID photo, the temporary-location information is passed in with the request to update someones information.

To upload a file to this temporary storage location;

  1. An API request must first be made to obtain a signed-url

  2. A signed URL with some form fields are returned from your request for a signed-url

  3. Using the signed URL & form-fields, submit your request with the file-data to Amazon S3

A PHP sample of the code required to submit the file data is included below;

composer.json

{ "require": { "guzzlehttp/guzzle": "~6.0" } }

test.php

<?php require 'vendor/autoload.php'; use GuzzleHttp\Client; // This is a demo script which will upload a file (./file.png) to member ID #1 // Variables which should be set $url = 'https://mycompany.vtevents.com.au'; $uploadTo = 'members/1'; $auth = ['auth key', 'auth secret']; $localFilePath = './file.png'; $fileMimeType = 'image/png'; $remoteFileName = 'myfile.png'; $fileSize = filesize($localFilePath); $documentTitle = 'My document title'; $documentDescription = 'My document description'; // end vars to be set $client = new Client([ 'base_uri' => $url ]); // ------------------------------------------------------------------------ // Step 1 - Get a signed url which will be used to upload the files via $response = $client->request( 'POST', '/api/v2/documents/get-upload-url', [ 'auth' => $auth, 'json' => [ 'name' => $remoteFileName, 'type' => $fileMimeType, 'size' => $fileSize ] ] ); $signedUrlVars = json_decode($response->getBody(), true); // ------------------------------------------------------------------------ // Step 2 - Upload the file-data to AWS S3 // prepare the post-data which will be sent to AWS S3 $postVals = []; foreach ($signedUrlVars['formData'] as $key => $val) { $postVals[] = [ 'name' => $key, 'contents' => $val, ]; } $multipart = array_merge( $postVals, [ [ 'name' => 'Content-Type', 'contents' => $fileMimeType, ], [ 'name' => 'file', 'contents' => fopen($localFilePath, 'r'), 'filename' => $remoteFileName, 'headers' => [ 'Content-Type' => $fileMimeType, ], ], ] ); try { $response = $client->request( 'POST', $signedUrlVars['url'], [ 'multipart' => $multipart, ] ); } catch (\GuzzleHttp\Exception\RequestException $e) { echo 'An error occurred while uploading to AWS S3; ' . (string)$e->getResponse()->getBody(); exit; } $s3Response = (string)$response->getBody(); // ------------------------------------------------------------------------ // Step 3 - attach the uploaded file in S3 to an event/member/resource/etc $response = $client->request( 'POST', '/api/v2/' . $uploadTo . '/documents', [ 'auth' => $auth, 'json' => [ 'title' => $documentTitle, 'description' => $documentDescription, 'file' => [ 'name' => $remoteFileName, 'type' => $fileMimeType, 'size' => $fileSize, 'path' => $signedUrlVars['formData']['key'], ], ] ] ); $docData = json_decode((string)$response->getBody(), true); // ------------------------------------------------------------------------ // Done! // Finally - Output the ID of the document which was just uploaded echo 'Document ID: ' . $docData['id'] . "\n";

Running php test.php will output the metadata which is being sent, as well as information about the response received.

A key will be included in the multipart array (the first shown), generally starting with ‘temporary-uploads/…’. This will represent the ‘path’ when referring to this uploaded file in subsequent requests - eg. to attach the file to a new document, or use it as an ID photo for a person in the system.

AWS provides more information on this concept here; https://docs.aws.amazon.com/AmazonS3/latest/dev/PresignedUrlUploadObject.html