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.

Access 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.

A PDF version of many files is available. To determine which files type include a PDF version, please reach out to your technical support contact. Generally, doc, docx, xls, xlsx, jpg, and gifs have PDF versions. We recommend offering the PDF version to end users, when available, as it can be viewed directly in their browser.

Furthermore, end users may need to have an active session in LearningBuilder at the time they access the link (i.e. they must already be logged in).

File Download Url

Original File:

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

PDF Version of File (when available):

https://<LearningBuilder>/Workflow/PDFDownload/{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);
}

NOTICE: It you are not on release 9.5 or later, please reach out to your technical support contact to discuss an upgrade. Until the upgrade is deployed, you can test the feature by constructing the hash with this line of code instead. Do not use this on a live system, as it will break as soon as your site is upgraded to 9.5 or above and you will need to coordinate updating your code.

Computing the hash code in 9.4.0 and earlier

stringToHash = uploadId + dateTime.ToString("MM-dd-yyyy hh:mm") + securityGuid;

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

Related articles

Browser not supported