Before you add a discount or price increase to an invoice make sure that the entrant has created and saved one entry.

How to Add an Individual Discount to an Invoice

1. Log into the Admin Interface
2. Go to Award>Overview> View Entries
3. In the table search for the entry where you want to make the amend
4. Select Edit from the Actions menu
5. Scroll to the bottom of the entry and look for Invoice Options section
6. In the Discount Reason type a description of the discount that will be printed on the invoice
7. In the Discount Amount enter the amount of the discount. Note that if you want to add a price increase to the invoice you need to enter a – before the number:
   1. 10 – will give a £10 discount
   2. – 10 – will add £10 to the invoice total
8. Click Save and Close
9. When the invoice for the entry is generated it will include the price change defined in this section

Note – if the entry where the price change has been added is deleted before the invoice is generated then the amendment will not appear on the invoice.

However, we appreciate that some awards may want to use specific emails for different awards eg. for your 2022 Awards you may have had a customised 2022 logo produced.

You can now use these, or a per award basis, in the new Logo Override setting that appears in the Payment Paperwork section of your main Awards set-up page. To access it:

• Go to Awards
• Select your Award from the list and click Settings
• Scroll down to Payment Paperwork and in the field Logo Override, click on the Image icon and enter the URL of a web-hosted version of the logo.
• Click Save and Close

This logo override will now apply exclusively to that award. The default logo will continue to apply to all those awards that are unaltered.

To action this, you will need to follow a 3 stages process starting by revoking the invoice, then adding the discount to the required Entry and finally raising a new invoice to apply the discount.

How to Revoke an Invoice

1. Login to the Admin Interface
2. Go to Awards>Overview>Invoices
3. Find the invoice from the Invoice List
4. Click on Actions > Revoke invoice
5. Click OK where requested. A Credit Note will automatically be raised against it

How to Add a Discount Code to an Unpaid Entry

1. Go to Award>View Entries
2. Look for the relevant Entry
3. Click on Actions>Edit Form
4. Scroll down to the Invoice Options section (which is hidden from the Entrant). Please just note that if you are using paginated dividers, this will be under the “Entry Setting” section.
5. In the Discount Reason field, type the reason for the discount
6. In the Discount Amount field, type the amount
7. Click Save and Close. The discount is now applied

How to Raise a New Invoice with a Discount Applied

After you have actioned the steps above, you will just need to CloseDown the order in order to raise the new invoice.

1. Go to Awards>Overview>Organisations
2. Look for the relevant Organisation/Entrant and click Edit alongside them
3. Scroll down to the Entry Summary for this Organisation
4. Click Closedown. A summary of their order will be displayed
5. Click Continue to Payment
6. On the pop-up that appears add in a PO Number if applicable
7. Type I AM SURE where instructed
8. Click Proceed to Payment. The updated invoice will now be generated and emailed to the Entrant

For occasions where you need to guarantee a quicker response, it is possible to book dedicated and continual ‘consultational support’ for a premium cost in additional to your agree annual support package.

If you think might require this, please get in touch with your contact on our Support Team and tell us your scenario and requirements. We will consider whether the additional support is necessary and, if so, will provide you with a quote accordingly.

Every Nucleus instance – and peoples’ usage of it – differs, so this Guide is by no means exhaustive. It may not include workflows and processes that are specific to your Nucleus instance. However, it has been compiled with a view to present the most common workflows in a general chronological order in which they would expect to be done throughout an entire awards or funding cycle – from creating a project, through managing entries/submission and processing payment to judging.

As such, it provides a comprehensive guide to new Nucleus users – including handing over/on-boarding to new team members. Equally, it can be used as a refresher tool for occasional users or regular users embarking on a new awards/funding cycle.

This Guide will be updated periodically as new functionalities and workflows are added to Nucleus. Feel free to download the current Guide and check back for future updates.

For ease of reference, the Contents section at the front of the Guide is hyperlinked. To enable you to skip to the section you require, just click on the section you require.

To action this process, there are 5 key steps you should be following:

1. Copying the Award
2. Checking the Email Templates
3. Checking the Categories
4. Bulk copying and creating instant entries
5. Setting up Viewers

Step 1: Copying the Award

1. Log into the Admin Interface
2. Go to Awards & Projects
3. Select the relevant Award
4. Click on … >Copy
5. The copied version of your orginal Award will open. You will now need to edit some key settings as follows:
6. Internal and Display names: update both. Please note that they must be unique and different from the original Award. We recommend you use something that will be understood by your Viewers. For example: <Awards Name> 2022 Final Jury Round
7. Active question: set to No. In this way, it will be hidden from the Entrant’s Dashboard. On the Admin Interface, when you go to Actions>Awards, please always make sure to filter the Show menu to ‘Both’ in order to see both inactive and active Awards
8. Show Entries on Entrant Dashboard question: set to No. In this way, you prevent users from seeing they have advanced before you have announced it
9. Open, Create and Submit dates questions: set an ideal date that enables enough time for you to Copy all of the entries across
10. Keep Pay Date, Closed Message and Delete Data dates as they were
11. Scroll down to the Viewing section
12. Edit the Require Scores and Comments to be Submitted question as you need
13. Scroll down to the Pricing section
14. Alongside the Requires Payment? question choose No payment. This will prevent advancing entries being (re) invoiced
15. Click Save & Close

Step 2: Checking the Email Templates

It is very important that before you attempt to copy any of your advancing entries across to your new ‘Award’, you must disable certain Email Templates that may be triggered by your actions. This is to ensure that the entrants are not informed automatically of their advancement ahead of any announcement you plan to make.

1. Log into the Admin Interface
2. Go to Email Management
3. Select Email Templates from the Email Management section. Please note that you will need to amend these 4 templates:

entry/approve
entry/progress
entry/submit
entry/unsubmit

4. Go to the relevant template and click Default in the Edit Template column
5. Go to the Enabled setting and switch this to No
6. The selected template is now disabled

Step 3: Checking the Categories

Depending on what has changed from your first round of judging, you may need to edit your Categories. There could be two different scenarios you might want to consider:

a) If your judging format, rules and/or jury Viewers have changed, you may have to edit the CMS for each Category on the Viewing Portal. Please do as follows:

1. Go to Overview>Categories
2. Click Edit alongside the Category you want to edit
3. To edit the title, amend the Name field
4. To edit the Viewing Portal Category Intro, scroll down to the Viewing Portal section
5. Amend the Viewing portal intro (full) field as required
6. Click Save & Close

b) If you use scoring for your judging, you MUST re-set these for the new round:

1. Go to Overview>Categories
2. Click Edit alongside the Category you want to edit
3. To edit the Scores and Commenting, scroll down to the Scoring with Viewing section
4. Amend these fields as required
5. Click Save & Close

Step 4 – Bulk copying and creating instant entries

With all of the round-specific settings confirmed in your new round, you can now copy your advancing entries across to it and automatically Approve them for Viewing.

1. Go to View Entries
2. Make sure you select your original Award from the dropdown menu at the top of the page
3. Filter your full Entry List as required (eg. by Category)
4. In the far left Action column, select Copy
5. Checkboxes will appear alongside each entry
6. Select each of the entries to advance
7. Once ready, click the OK button at the top of the column
8. A pop-up will appear, displaying the following:

• The list of entries you have selected – Please check
• A dropdown from which to select the award or round you are advancing these entries to – Please select your new copied Award
• An option to Choose the Status For the Copied Entries:
  a) Select Unsubmitted if you need the entrants to supply more info
  b) Select Submitted if you don’t need them to supply more info BUT do still want to pre-screen the entries before sharing them with your Viewers
  c) Select Approved if you want the entries to advance as they are and are Viewer-ready
  d) Select As Existing if the entries are currently in a variety of statuses and you want each of these to preserved when they land in the new round.

9. Type I AM SURE to confirm this and click Continue
10. Your selected entries will now be advanced to the Entry List of your new round or award

Step 5: Setting up Viewers

Now that your advancing Entries are in your new round, you simply need to re-allocate them to your required jury groups.

a) Existing Viewers
You can use the Bulk Assign tool to assign additional Categories to existing Viewers. Please follow this guide to see how to do this. Once actioned, these new round Categories will be assigned to your Viewers’ existing accounts on the Viewing portal.

Note – Existing Viewers will NOT receive an email notifying this – the Viewer/Welcome email is only generated for NEW Viewers. If you would like to use Nucleus to inform them of their new categories, you can use the Entrant Mailout functionality – and filter according to Viewers, the new Award/Round and Categories. Please review this guide to see how to use it.

Note 2 – Your Viewers’ previous round Categories will, by default, still be available for them to view on their Viewing Portal Dashboard. However, their Scores and Comments will be locked. As long as they Submitted them, Viewers will NOT be able to change or delete them in error. Only Admin Users can give permission for them to edit and re-submit previously submitted scores and comments.
If you want to remove these previous rounds from their Dashboard, please do as follows:

1. Go to Awards
2. Find your original Award/round
3. Click Overview>Settings
4. Scroll down to the Viewing section
5. To the setting Viewing Enabled select No

The categories from that award/round will no longer be viewable on your Viewers’ Dashboards. However, the data from them will remain intact, and can be instantly recalled to the Viewers’ Dashboards by simply adjusting this Viewing Enabled setting to Yes.

b) New Viewers
If you are adding any new Viewers to your new round, you can add them by using the Bulk Create process described here.

To activate this, please raise a Support Ticket and request it from our Development team.

Once activated, the ‘Admin User’ of each entrant organisation (ie. their user with enhanced permissions over the Normal Users) will have a tab headed MANAGE USERS on their menu bar. From here they will be able to carry out the desired actions.

1. Introduction

This guide outlines the operation of the Nucleus API which allows external systems to programmatically access details of awards, categories, entries and videos. All of the data that is used to build the structure of the viewing interface can be accessed via the API and used within another system.

The first part of this guide will detail the framework and how developers can access the data. The second part of the guide will explain to admin users how to create keys and give developers access to the information that they require.

2. Authentication Framework

In order to prevent unauthorised access to the data all API requests must be digitally signed. The approach employed is designed in accordance with the principles set out here: http://broadcast.oreilly.com/2009/12/principles-for-standardized-rest-authentication.html

This is implemented by adding the following 3 fields to each request as additional CGI parameters:

• expires
  The time at which this request becomes invalid expressed as a unix timestamp i.e. seconds since 1/1/1970 (see Unix time ). This should generally be kept as low as possible – e.g. less than 60 seconds in the future. 
• keyId
  The public key to authenticate against
• signature
  A hash-based message authentication (HMAC) code (see https://en.wikipedia.org/wiki/Hash-based_message_authentication_code ) as generated by the hash_hmac PHP function (see http://php.net/manual/en/function.hash-hmac.php). The data used to generate the HMAC will be the endpoint path combined with the entirety of the query string (see https://en.wikipedia.org/wiki/Query_string) including the expiry and apiKey fields but excluding the hmac field itself. If data is passed using a POST instead of a GET then the HMAC should be based on what the query string would have looked like if the same data had been passed on the query string (in the same order that they occur in the POST). The HMAC should be generated from the data after it has been URL-encoded. The key used to generate the HMAC will be the private key which corresponds to the public key which has been used.

API keys are managed through the Nucleus administrative interface. The API Key administration page can be accessed through the “Misc → API Keys” page. This page lists current API keys and the corresponding private keys and allows new keys to be issued and existing keys to be revoked.

2.1. Signature Example 

If the entries.php endpoint is to be call with the following parameters:

• awardId = 12
• categoryId = 34

First the the expiry time and API key should add to these fields so that the query string is compiled from the following fields:

• awardId = 12
• categoryId = 34
• expires = 1462802582 (replace this with a suitable future timestamp)
• keyId = 5a3b403d4dcfb84f73f383d2e2b8f352 (replace this with your key ID)

This can then be converted to a query string thus:

awardId=12&categoryId=34&expires=1462802582&keyId=5a3b403d4dcfb84f73f383d2e2b8f352

The endpoint is added to the front thus:

entries.php?awardId=12&categoryId=34&expires=1462802582&keyId=5a3b403d4dcfb84f73f383d2e2b8f352

This is then used to generate the hmac. If the secret is, for example, 8iKDKfYOGfmBuLP+nR/nbU59Sh2rw9KV then the following PHP code can be used:

hash_hmac('sha256','entries.php?awardId=12&categoryId=34&expires=1462802582&keyId=5a3b403d4dcfb84f73f383d2e2b8f352','8iKDKfYOGfmBuLP+nR/nbU59Sh2rw9KV');

This gives the HMAC:

13d41665334bb60ee8bf7bdee22fe571291cbd3e4eb1f60f05aa31fc576ca2a6

Note – that although the request is sent to /api/entries.php, the hash is computed using the endpoint address without the initial “/api/”.

This is then appended to the query string to give the final complete URL

https://my.nucleus.domain.com/api/entries.php?awardId=12&categoryId=34&expires=1462802582&keyId=5a3b403d4dcfb84f73f383d2e2b8f352&signature=13d41665334bb60ee8bf7bdee22fe571291cbd3e4eb1f60f05aa31fc576ca2a6

This could equally well be a POST to https://my.nucleus.domain.com/api/entries.php with the following parameters:

• awardId = 12
• categoryId = 34
• expires = 1462802582
• keyId = 5a3b403d4dcfb84f73f383d2e2b8f352
• signature = 13d41665334bb60ee8bf7bdee22fe571291cbd3e4eb1f60f05aa31fc576ca2a6

When using a post it is important that the parameters are passed in the same order as they were included in the query string when generating the signature.

3. Test Harness, Client Library and Sample Code

A simple test harness is available in the entry site administrative interface. This page can be accessed through the “Misc → API Test Harness” page. The test harness page also contains links to a PHP Client library to simplify access to the API and some sample code which uses this client library.

1. Log into the Admin Interface
2. Go to Control Centre
3. Select API Test Harness in the System Administration Section
4. The following page will contain examples and test parameters which can be set.

Note – you will need a Nucleus Admin user to access this page. Contact the Nucleus Admins and ask them to create a user for you.

3.1. Sample Code: API Wrapper Class

<?
 
class BAESClient {
	private $keyId;
	private $secret;
	private $baseUrl;
 
	function __construct($baseUrl,$keyId,$secret) {
		$this->baseUrl = $baseUrl;
		$this->keyId = $keyId;
		$this->secret = $secret;
	}
 
	function call($endpoint, $params) {
		ksort($params);
		$url = $this->baseUrl.'/'.$endpoint.'.php';
 
		$params['expires'] = time()+60;
		$params['keyId'] = $this->keyId;
		$sigStr = $endpoint.'.php?'.http_build_query($params);
 
		$params['signature'] = hash_hmac('sha256',$sigStr,$this->secret);
		// for debug
		// echo "$sigStr , $this->secret\n\n";
		// print_r($params);
		
		$ch = curl_init();
		curl_setopt($ch, CURLOPT_URL,$url);
		curl_setopt($ch, CURLOPT_POST, 1);
		curl_setopt($ch, CURLOPT_POSTFIELDS,$params);
		curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
		// for debug
		// curl_setopt($ch, CURLOPT_HEADER, true);
 
		$response = curl_exec ($ch);
		$responseCode = curl_getinfo($ch,CURLINFO_RESPONSE_CODE);
		curl_close ($ch);
 
		if ($responseCode !== 200) {
			if (preg_match('/<title>(.*?)<\/title>/is',$response,$matches)) $errors = array( $matches[1] );
			else $errors = array( $response );
			return array( $responseCode, array(), $errors );
		}
 
		$data = json_decode($response, true);
		if ($data===null) {
			$reponseCode = 500;
			$errors = array("Unexpected content in API response: ".substr($response,0,200));
			return array( $responseCode, array(), $errors );
		}
 
		if (!isset($data['status']) || !(isset($data['errors']) || isset($data['results']))) {
			$reponseCode = 500;
			$errors = array();
			if (!isset($data['status'])) $errors[] = "API response did not include a status field";
			else $errors[] = "API response did not include errors or results";
			return array( $responseCode, array(), $errors );
		}
 
		if (!isset($data['errors'])) $data['errors']=array();
		if (!isset($data['results'])) $data['results']=array();
 
		return array( $data['status'], $data['results'], $data['errors'] );
	}
 
}

3.2. Sample Code Using Wrapper Class

<?

include('../../lib/api/BAESClient.php');
 
/* here is an example with some parameters set - you will need to edit the videoId for this to work
$endpoint = 'video';
$params = array(
    'videoId' => '329',
    'type'  => 'watch',
    'userId'    => 'test_watch'
);
*/
$endpoint = 'awards';
$params = array();
 
// You will need to place your API Key ID and Secret key in here...
define('API_KEYID','################################');
define('API_SECRET','################################');
 
// You will need to place the base URL for your BAES installation in here...
define('API_BASE_URL','https://#####.#####.##/api/');
 
$baesClient = new BAESClient( API_BASE_URL, API_KEYID,API_SECRET);
 
header('Content-type: text/plain');
 
list($status, $results, $errors) = $baesClient->call($endpoint,$params);
 
echo "STATUS=$status\n";
print_r($results);
print_r($errors);

4. Test Harness, Client Library and Sample Code Javascript

A simple test harness is available in the entry site administrative interface. This page can be accessed:

1. Log into the Admin Interface
2. Go to Control centre
3. Select API Test Harness in the System Administration Section
4. The following page will contain examples and test parameters which can be set.

The test harness page also contains client side and server side sample code.

A Javascript API Client library is available here: https://<Base URL for your BAES installation>/javascript/nucleusApiClient.mjs

Note: The Javascript client is designed for use in both server side and client side (in browser) applications.

***PLEASE NOTE*** that when using the API client in a browser you MUST NOT include the API key and secret. Instead you must implement a small server-side endpoint to implement the request signing. An example of what the server side signing endpoint is included below.

4.1. Client Side Example

Add this code to the web page

<script type="module">

// If this module fails to load you may need to host the nucleusApiClient.mjs file on the same domain as the page the code is running in
import NucleusClient from 'https://<Base URL for your BAES installation>/javascript/nucleusApiClient.mjs'

// Replace "https://app.your-company.com/api/nucluesRequestSigningURL.php" with the appropriate URL on the next line
var client = new NucleusClient('https://<Base URL for your BAES installation>/api/','https://app.your-company.com/api/nucluesRequestSigningURL.php');

// In this example we are going to get the details for the award with ID 280. Your award ID will be different
var endpoint = 'awards';
var awardId = 280;
var response = client.call(endpoint,{
    'awardId' : awardId,
    'expires' : Math.round((new Date()).getTime()/1000)+60
}).then(function(result) {
    // Do something with the result here
    console.log(result);
});
</script>

Add code something like this on your external application server at https://app.your-company.com/api/nucleusRequestSigningURL.php

<?
/*
----------------------------
Add in user authentication here in using whatever mechanism your system uses
----------------------------
*/

if(isset($_POST['endpoint']) && !empty($_POST['endpoint'])) {
    $keyId = '< PUT YOUR API KEY ID HERE >';
    $secret = '< PUT YOUR API SECRET HERE >';
    $params = $_POST;
    $endpoint = $params['endpoint'];
    unset($params['endpoint']);
    $params['keyId'] = $keyId;
    $sigStr = $endpoint.'.php?'.http_build_query($params);
    $signature = hash_hmac('sha256',$sigStr,$secret);
} else {
    $signature = '';
}
echo json_encode(array(
    'signature' => $signature,
    'keyId' => $keyId
));
exit;
?>

4.2. Server Side Example

In order to run this code you will first need to:

1. Download the javascript client library from https://<Base URL for your BAES installation>/javascript/nucleusApiClient.mjs
2. npm install node-fetch

import NucleusClient from './nucleusApiClient.mjs';

var client = new NucleusClient('https://<Base URL for your BAES installation>/api/','< PUT YOUR API KEY ID HERE >','< PUT YOUR API SECRET HERE >')

// In this example we are going to get the details for the award with ID 280. Your award ID will be different
var endpoint = 'awards';
var awardId = 280;
var response = client.call(endpoint,{
    'awardId' : awardId,
    'expires' : Math.round((new Date()).getTime()/1000)+60
}).then(function(result) {
    // Do something with the result here
    console.log(result);
});

5. Endpoints

The endpoints are listed below. Endpoints may accept additional query parameters as detailed below. Some of these parameters are mandatory – this is indicated below where this applies. All endpoints will return data as a JSON encoded data structure (see http://json.org/ ).

The data structure returned will be an associative array with three keys:

• status: A numeric status code using the same codes as conventional http transfers i.e. 200 = OK, 403 = Forbidden etc
• errors: An array of human-readable error messages
• results: An array of associative arrays. If there are no results this will be an empty array (but this will not be treated as an error).

5.1. /api/awards.php

There are no additional input parameters options for this endpoint.

This endpoint will return an array of active awards with the following parameters for each item

• awardId
  The award ID
• name
  The name of the award
• orderNumber
  An integer to indicate what order awards should be displayed in
• opensAt
  The date and time when the award is open for entries expressed as a unix timestamp
• lastCreateDate
  The date and time when award closes for new entries expressed as a unix timestamp
• lastSubmitDate
  The date and time when award closes for submission of existing (already created) entries expressed as a unix timestamp

Example

Request

{ }

Response

[
    {
        "awardId": "123",
        "name": "Jedi Award 2023",
        "orderNumber": "1",
        "opensAt": "1680126900",
        "lastCreateDate": "1698792900",
        "lastSubmitDate": "1698792900"
    },
    {
        "awardId": "124",
        "name": "Jedi Award 2024",
        "orderNumber": "1",
        "opensAt": "1711752900",
        "lastCreateDate": "1722376500",
        "lastSubmitDate": "1722376500"
    },
    {
        "awardId": "127",
        "name": "Short Jedi Award 2024",
        "orderNumber": "2",
        "opensAt": "1665438900",
        "lastCreateDate": "1728597300",
        "lastSubmitDate": "1728510900"
    }
]

5.2. /api/categories.php

Additional parameters for this endpoint are:

• awardId (mandatory)
  The award for which categories should be returned

This endpoint will return an array of categories for the specified award which will include the following parameters for each category:

• categoryId
  The ID for the category
• name
  The name of the category
• type
  This is either “Performance” or “Production”
• introMessage
  The viewing portal introductory message as defined in the category setup on BAFTA Nucleus
• showOnViewingPortal
  Either 0 (do not show) or 1 (show) as set in the category setup in BAFTA Nucleus
• votingSiteCategoryId
  The “Voting site category ID” as specified for the category in the category setup in BAFTA Nucleus

Example

Request

{
    "awardId": "123"
}

Response

[
    {
        "categoryId": "123",
        "name": "Best Hair",
        "introMessage": "",
        "showOnViewingPortal": "1",
        "votingSiteCategoryId": "0"
    },
    {
        "categoryId": "124",
        "name": "Best Mind Bending Skills",
        "introMessage": "",
        "showOnViewingPortal": "1",
        "votingSiteCategoryId": "0"
    },
    {
        "categoryId": "125",
        "name": "Most cool",
        "introMessage": "",
        "showOnViewingPortal": "1",
        "votingSiteCategoryId": "0"
    }
]

5.3. /api/entries.php

Additional parameters for this endpoint

• awardId (mandatory)
  The award for which entry data should be returned.
• status (
  If passed in then only entries with this status will be returned. Valid values are “unsubmitted”,”submitted” or “approved”.
• categoryId
  The categoryId for which entries should be returned. If specified, only entries which are in this category will be returned.
• entryId
  If this is specified then an array containing data about only this single entry will be returned. If this is combined with any other filters and the other filters do not match this entry ID then an empty set will be returned.
• titleEquals
  If this is specified then only entries whose title matches the value provided will be returned. This filter is case insensitive. This can be combined with categoryId and status if you want to find only entries with the specified title, in the specified category and with the specified status.
• titleContains
  If this is specified then only entries whose title contains the string provided will be returned. This filter is case insensitive. This can be combined with categoryId and status if you want to find only entries containing this text in the specified category and with the specified status.

This endpoint will return an array of approved entries with the following parameters for each entry:

• entryId
  The entry ID
• entryTitle
  The title of the entry – this will be taken from the question on the entry form for which the “Include on Entry list for entrant” field has been set to “1”.

N.B If no questions has been defined with “Include on Entry list for entrant” set to “1” then no entries will be returned by the API.

• data
  The data from the entry form which has been given a “Title for viewing portal“. This data will be an associative array keyed on the field name as specified for the corresponding question definition in the “Title for viewing portal” field. Where the data field is a “Media Item” then the value for the question will be the string ‘mediaItem:’ followed by the media item type, followed by a numeric ID for the media item which can be passed to the mediaItem endpoint below e.g. “mediaItem:video:6”
  Media Item Types are as follows:
  • Image
  • Video
  • Audio
  • Document
• categoryNames
  An array of category names
• categoryIds
  An array of category ID’s

Example

Request

{
    "awardId": "19",
    "titleContains": "day",
    "status": "submitted"
}

Response

[
    {
        "entryId": "12345",
        "status": "submitted",
        "categoryNames": [
            "Best Hair",
            "Most Cool",
        ],
        "categoryIds": [
            ”124”,”125”
        ],
        "entryTitle": "bedtime Jedi",
        "data": {
            "Main production country": "Zag",
            "Length": "4800",
            "Language": [
                "Zagdorp"
            ],
            "Year of Production": "2023",
            "Director 1": "James Jameson",
            "Cast 1": "Bob Ambleforth",
            "Cast 2": "",
            "Synopsis": "Jedi gets tired\r\nJedi goes to bed\r\nTHE END",
            "Visual Effects 1": "Fizz bang",
            "Visual": "mediaItem:image:999",
            "Screenwriter 1": "Simon Jones",
            "Co-producer 1": "Jim Joshing",
            "Film website": "",
            "Further images 1": "mediaItem:image:672",
            "Main still \/ preview image": "mediaItem:image:349",
            "Film excerpt 1": "mediaItem::0",
            "Film file": "mediaItem:video:263"
        }
    },
    {
         "entryId": "12345",
        "status": "submitted",
        "categoryNames": [
            "Best Mind Bending Skills",
            "Best Hair"
        ],
        "categoryIds": [
            "123",”124”
        ],
        "entryTitle": "Holiday Time Jedi",
        "data": {
            "Main production country": "Zog",
            "Length": "4800",
            "Language": [
                "Zorgon"
            ],
            "Year of Production": "2023",
            "Director 1": "James Anderson",
            "Cast 1": "Bob Wimblehurst",
            "Cast 2": "",
            "Synopsis": "Jedi goes on holiday\r\nGreat hilarity ensues\r\n",
            "Visual Effects 1": "Bag Whallop",
            "Visual": "mediaItem:image:5005",
            "Screenwriter 1": "Simon Beetles",
            "Co-producer 1": "Jim Anderson",
            "Film website": "",
            "Further images 1": "mediaItem:image:7350",
            "Main still \/ preview image": "mediaItem:image:7349",
            "Film excerpt 1": "mediaItem::273",
            "Film file": "mediaItem:video:2687"
        }
    }
]

5.4. /api/mediaItem.php

Note – Only MediaItems associated with submitted entries can be retrieved

Additional parameters for this endpoint

• mediaItemId (mandatory)
  The ID of the mediaItem being requested.
  This can be a single ID, or a comma separated list of up to 100 media item IDs.
  If multiple ID’s are provided they MUST all be of the same type i.e. all video, or all images.
  If multiple media items are required please try to request these in one go rather than making many separate individual requests.
• type (mandatory)
  When the media type is “video” then this determines whether a link to the HLS stream, a transcoded MP4 file, or the originally uploaded file should be returned as follows:
  • stream (JSON data including both HLS m3u8 file and mp4 alternative will be returned. This JSON can be fed straight to a BitMovin player)
  • download (the URL for a transcoded MP4 file will be returned)
  • original (the URL for the original untranscoded file will be returned)
  • preview (the URL for a thumbnail image for the video)
• When the media type is “image” this determines whether the original file is downloaded or a resized preview version is supplied. Options for images are:
  • preview
  • original
• When the media type is “document” then only valid type is:
  • download

If you supply multiple You can only request one type of media in one call.

• viewerId (mandatory)
  All watch or download requests are logged by BAFTA Nucleus. This must be the numeric ID for a viewer as defined in Nucleus. The viewer must have permission to view the requested mediaItem(s). If the viewer specified doesn’t have permission to view any of the requested mediaItems then these mediaItems will simply be completely omitted from the data returned.
• validityHours
  The duration for which the link which is returned should remain functional (in hours). After this time the video will no longer be playable. The validity time for the URL starts from when the URL is generated by the API. If no value is specified then the default value used by the entry site will be substituted
• maxUses
  The number of times that the link can be used to access the content. If this parameter is missing it defaults to 3. If unlimited access is required this should be set to some arbitrarily high number e.g. 9999

This endpoint will return an associative array of URL’s keyed on the mediaItemId.

An example of the data returned when requesting multiple mediaItems is included below. 

N.B. This example is just for illustration and couldn’t actually be generated on the live system because the data in this example includes mediaItems of differing types – on the live system you can only request items of one type at a time. If you include ID’s for items that don’t support this type then the erroneous ID’s will still be included in the output data, but with an “Invalid Type” error. So, if the requested type is “original” then you can request multiple mediaItems of any variety in the same request (since videos, images and documents all support the “original” type). If the requested type is “preview” then you can request images and videos, but documents will return an “Invalid type” error because documents don’t support the preview type

{
    // Video stream
    289: {
            url: https://…<link to get json stream data>…
    },
 
    // Video mediaItem requested with type=download
    289: {
            url: https://…<link to download mp4>…
    },
 
    // Video mediaItem requested with type=original
    289: {
            url: https://…<link to download original video file>…
    },
 
    // Video mediaItem requested with type=preview
    289: {
            url: https://…<link to download thumbnail image>…
    },
 
    // Image mediaItem requested with type=preview
    289: {
            url: https://…<link to download thumbnail image>…
    },
 
    // Image mediaItem requested with type=download
    289: {
            url: https://…<link to download original image file>…
    },
 
    // mediaItem requested which is incompatible with the requested type
    // e.g. when a “preview” of a document is requested
    288: {
     error: “Invalid Type”
    }
}

The link to get json stream data in the example above will return JSON data in this format.

{
	"result": {
		"hls": "https:\/\/d3cszrd24af8ic.baftaelectron.com\/hls\/…\/index.m3u8",
		"mp4": [{
			"url": "https:\/\/d3cszrd24af8ic.cloudfront.net\/….",
			"type": "video\/mp4",
			"height": "480",
			"label": "480p"
		}, {
			"url": "https:\/\/d3cszrd24af8ic.cloudfront.net\/…",
			"type": "video\/mp4",
			"height": "720",
			"label": "720p"
		}]
	}
}

API Information for Nucleus Admins

The above instructions should be given to your developers but there is some setup required by Nucleus Admins which is covered in the above guide. For convenience this has been broken down here as non-developers might find the above instructions confusing.

The API is accessed using existing functionality, including an admin account, Viewing Portal Title, Award and Category ID’s. Largely an award using the API should be set up in the normal way but it is likely developers will ask you for key information items and this guide will enable you to prepare this form them in advance.

Note – Only Entry Data and MediaItems associated with Approved entries can be retrieved.

Items to Prepare in Advance

• Generate an Admin Account -The API will access the data using an admin account and the developer will need this in order to generate a test harness. When you create the account make sure it only has access the projects the API needs to access. The API can only export form Awards where it has permissions. For more information on creating accounts read the Admin User guide.
• Provide the Award ID/s – Each Award has an ID and the developer will need this to access the data. In the Admin Interface, go to Actions>Awards. On the table take the number from the ID column for all awards you want the developer to access.
• Provide the Category ID/s – Each Category has an ID and the developer will need this to access the data. In the Admin Interface, go to Actions>Categories. On the table take the number from the ID column for all categories you want the developer to access.
• Define a Question for Include on Entry List for Entrants – This is normally completed as part of the award set-up but has been included here as a reference. In order for the API to work one question needs to be set to appear on the Entrant Dashboard. To action this in the Admin Interface for to Actions>Questions. Look in the Display on Entrant column for a 1. If you can’t find this, choose a question, title is the best, and click Edit. On the next screen under Options select Position 1 for Include on Entry list for entrant.
• Set a Title for API name – for each item of data that you wish the API to access it must have a valid name set in the API name field. To set this in the Admin Interface for to Actions>Questions. Choose a question where you wish to include the data set and click Edit. On the next screen under Options enter a value in API name. This data set will not be accessible for the API.

How to Generate an API Key

The developer will not be able to access the data without a valid API key. The developers, once they have an account, may generate this themselves but as the process is simple it can speed up the process if you generate this in advance and send to your developer.

1. Log into the Admin Interface
2. Go to control centre
3. Under System Administration select API Keys
4. On the next page click Add
5. An API Key and Secret will be generated
6. Copy these and keep them secure as the developer will need both
7. Enter a name in Notes so you can retrieve the key and secret in future
8. Click Save and Close

How to Set a Question in the API to be Displayed in the Viewing Interface

There are cases where a question needs to be used in the API to be displayed in the Viewing Interface. This is something you can set from the Question Settings.

1. Log into the Admin Interface
2. Go to Award>Form setup/Question list
3. Click Edit on the question you want to display in the Viewing Portal
4. Scroll down to the Options section in settings page
5. Fill in the API name field. Please note that this must be unique as it won’t work if there are duplicates names in the same award
6. Click Save & Close
7. Your question will now appear in the API

Note – Once you set this up, always check the Viewer’s permission have been set up accordingly. This guide explains how to give Judges permissions to Awards and specific Categories.

Important Note – For the API Name field to be displayed, the Award must be Active.

There is a admin controlled function on the award to delete all the Award, which is a mandatory function and all related data. Admins set a date when the award will be deleted. Any associated Media Item (Videos/Audio/Images/Documents) will become unassociated from their entries and if not linked with another entry will be deleted and clean up by the automate tidy up rules.

This feature can be used to prevent Electron usage becoming too high and ensuring that entry data is not kept longer than required, reducing backup sizes and as a consequence AWS costs.

The date set must be a minimum of 6 months after the submission date and more than 7 days in the future from the current date.

Once the date is set there are two reminder emails that will be sent to all admin users for the award and a confirmation that the data has been deleted. Follow the instructions below to set up the date and to set the date for Entry Data Deletion.

Note – All the automated deletions rules can be amended at client request via a support ticket.

How to set the Entry Deletion Date

The date is a mandatory field on the Award Settings page which means it is not possible to save an award without specifying a date. These instructions can be used to update the date to remove data sooner.

1. Log into the Admin Interface
2. Go to Awards & Projects
3. Click on Settings on the desired award.
4. Scroll down to find the Delete Award On setting, and enter a deletion date of your choice. Note this must be a minimum of 6 months after the Last submit date. The system will prevent you from submitting a date that comes sooner than the 6 months, and an error message will be displayed.
5. Click Save

How to set up the Warning Emails for Admin users

There are two warning templates and a deletion confirmation template that can be activated for admin users. These are recommended as they provide admins with an opportunity to prevent the deletion of entry data if required.

• admin/awarddeletewarn7 – sent 7 days before the deletion
• admin/awarddeletewarn24 – sent 24 hours before the deletion
• admin/awarddeletenotify – sent after the entries have been deleted

For full information on how to manage and edit email templates review the guide.

How does Nucleus Automatically Reject Video Files

The first step is to decide on the criteria of the files that you want entrants to provide. The following criteria can be used as part of the specification:

• Resolution – for example: HD 1920-1080
• Codec – for example: H264 Progressive
• Sound – for example: AAC 44KHz
• File Type – for example: .mov or .mp4

Note – the size of the file can be restricted on a per question basis and this functionality is covered in the Media Library guide

Nucleus can only scan the metadata in the file when it has completed upload.

• If the file meets the requirements then it is accepted and no action is taken
• If the file does not meet the requirements then an email is sent to the user and the file is automatically deleted

How to Set up The Rejection Email Template

For full information on managing email templates review the email template guide. To ensure that emails are sent to users when their videos are rejected admin users will need to set up the mediaItem/fileAssociationRemoved template.

In this template explain to the user that the file they provided did not meet the required specification, that the file has been deleted and that the entrant needs to provide a new file. We recommend also including the specification.

To personalise the email you can include the following special values alongside the usual values:

• @@mediaItem_title@@ – inserts the title of the media item as provided by the entrant
• @@mediaItem_id@@ – inserts the id of the media item

Once the copy and subject have been provided and the template enabled it will be sent to entrants when their videos are rejected.