Accessing an Uploaded File

Summary

File Upload attributes allow documents to be attached to a Workflow. This document describes how to access those files from a 3rd party system, rather than through the LearningBuilder web interface.

Required Data

In order to access an uploaded file, you need two pieces of information:

File Upload Id - each uploaded file has a unique, system-assigned integer value
Security Guid - each uploaded file also has a unique, system-assigned GUID used to "sign" the download link (see below)

The File Upload Id is not a sensitive value and may be sent over the network.

The Security Guid is a secure value and is used to prevent unauthorized access to uploaded files. It should never be transmitted over an unsecured network connection.

The most common way to expose this information is through a custom report or database view that is available to program administrators.

Accessing the File

To access an uploaded file you must construct a "signed" URL utilizing both a date stamp and the Security Guid of the uploaded file.

The date stamp allows you to share the link with an untrusted third party by limiting the amount of time that the link is good for. By default, file download links are valid within two hours of the date stamp passed in the securityDate parameter. (The timeout is a system-wide configuration setting)
The Security Guid is used to generate a hash code that is appended to the URL. This ensures that the URL is not modified; any attempt to modify a different upload Id, or to modify the date stamp, will invalidate the hash code and prevent the file from being downloaded.

File Download Url

https://<LearningBuilder>/Workflow/Download/{uploadId}?securityDate={currentDate}&securityHash={hashCode}

Parameter Purpose

{uploadId} The File Upload Id associated with the File Upload attribute

{currentDate}

The current date (in Eastern Time), formatted as MM-dd-yyyy HH:mm, and then URL encoded.

6/5/2018 4:54:12 PM → 6/5/2018%2016:54

{hashCode}

A Base64-encoded SHA256 hash used to digitially "sign" the URL, computed as:

Base64Encode(SHA256({uploadId} + {currentDate} + {securityGuid}))

Sample C# code for computing `{hashCode}`

Constructing the hash code should be fairly straightforward in any language or platform that has a SHA256 implementation. Here is sample code for C#:

Computing the hash code in 9.5 and later

private string GenerateHash(int uploadId, DateTime dateTime, string securityGuid) {
	var sha = SHA256.Create();
	var stringToHash = uploadId + dateTime.ToString("MM-dd-yyyy HH:mm") + securityGuid;
	var bytesForHash = Encoding.UTF8.GetBytes(stringToHash);
	var hash = sha.ComputeHash(bytesForHash);

	return Convert.ToBase64String(hash);
}

Computing the hash code in 9.4.0 and earlier

private string GenerateHash(int uploadId, DateTime dateTime, string securityGuid) {
	var sha = SHA256.Create();
	// -------------------------------
	// NOTICE: Prior to 9.5 the datestamp was calculated using a 12-hour clock 
	// without AM/PM indicator
	// -------------------------------
	var stringToHash = uploadId + dateTime.ToString("MM-dd-yyyy hh:mm") + securityGuid;
	var bytesForHash = Encoding.UTF8.GetBytes(stringToHash);
	var hash = sha.ComputeHash(bytesForHash);

	return Convert.ToBase64String(hash);
}

Requirements

Any modern version of LearningBuilder
A Workflow with a File Upload attribute
A report or custom view that exposes the data needed to construct the secure URL

Accessing an Uploaded File

Required Data

Accessing the File

Sample C# code for computing {hashCode}

Requirements

Related articles

Sample C# code for computing `{hashCode}`