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;

Uploaded to Amazon S3 to a temporary file storage location
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;

An API request must first be made to obtain a signed-url
A signed URL with some form fields are returned from your request for a signed-url
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