Contents
- Installation
- Cookbook
- Release Notes
- RESTful interface (in new window)
- Javascript API (in new window)
Project Documentation
If you are using an older version of Topcat you may need to apply some migrations to your database. These can be found in the “migrations/” directory within the Topcat release.
Topcat is configured in two main places:
The backend configuration consists of two files:
The frontend configuration consists of three files:
Note: ’#’s are comments.
# Derby Database !db.target = derby !db.driver = org.apache.derby.jdbc.ClientDataSource !db.url = jdbc:derby:topcat;create\\=true !db.username = APP !db.password = APP # MySQL Database db.target = mysql db.url = jdbc:mysql://localhost:3306/topcat db.driver = com.mysql.jdbc.jdbc2.optional.MysqlDataSource db.username = icat db.password = icat secure = true container = Glassfish home = /home/fisher/pf/glassfish4 port = 4848 # Email setup see http://docs.oracle.com/cd/E26576_01/doc.312/e24938/create-javamail-resource.htm#GSRFM00035 mail.host=smtp.example.com mail.user=user@example.com mail.from=no-reply@example.com #see https://javamail.java.net/nonav/docs/api/ for list of properties mail.property=mail.smtp.port="25":mail.smtp.from="no-reply@example.com"
Note: ’#’s are comments.
# enable send email
mail.enable=true
# The email subject. Tokens available are:
# ${userName} - user username
# ${email} - user email
# ${facilityName} - the facility key (defined in frontend config)
# ${preparedId} - the prepared Id of the download request
# ${fileName} - the download name
# ${size} - the download size
# ${downloadUrl} - the download url
mail.subject=TopCAT Download ${fileName} Ready
# The email body message for https downloads. All subject tokens as above are available.
mail.body.https=Hi ${userName},\n\nYour ${size} download ${fileName} has been prepared and is ready for download at ${downloadUrl}.\n\nThank you for using TopCAT.
# The email body message for https downloads. All subject tokens as above are available.
mail.body.globus=Hi ${userName}, \n\nYour ${size} Globus download ${fileName} is ready. Please see https:/example.com/#/globus-faq for more information on how to download using Globus.\n\nThank you for using TopCAT
# The email body message for smartclient downloads. All subject tokens as above are available.
mail.body.smartclient=Hi ${userName}, \n\nYour ${size} SmartClient download ${fileName} is ready. Please check your smartclient home directory for your files.\n\nThank you for using TopCAT
# The email body message for SCARF downloads. All subject tokens as above are available.
mail.body.scarf=Hi ${userName}, \n\nYour ${size} SCARF download ${fileName} is ready. Please see https:/example.com/#/scarf-faq for more information on how to download using SCARF.\n\nThank you for using TopCAT
# The maximum number of datafiles for a getStatus call to the IDS for two level storage
ids.getStatus.max=100
# The delay in seconds before polling starts. This delay is to gives the ids a chance to do its thing before we query it
poll.delay=600
# The wait time in seconds between each poll to the IDS.
poll.interval.wait=600
# A list of usernames that can use the admin REST API and Topcat admin user interface
adminUserNames=simple/root, uows/elz087, asd345, ldap/fgh123
A high level overview of the topcat.json file is as follows:
{
"site": {...},
"facilities": {...}
}
from the above example there are two attributes defined:
If we expand the attributes in high level overview we can get a medium overview as follows:
{
"site": {
"topcatUrl": "https://example.com",
"home" : "my-data",
"enableEuCookieLaw" : true,
"paging" : {...},
"breadcrumb": {...},
"serviceStatus": {...},
"maintenanceMode": {...},
"search": {...},
"browse":{...},
"cart":{...},
"myDownloads":{...},
"pages" : [...]
},
"facilities": [
{
"name": "DLS",
"title": "Diamond Light Source",
"icatUrl": "https://example.com",
"idsUrl": "https://example.com",
"idsUploadDatafileFormat": "example_datafile_format_name",
"idsUploadDatasetType": "example_dataset_type_name",
"idsUploadMaxTotalFileSize": 10000000000,
"hierarchy": [...],
"authenticationTypes": [...],
"downloadTransportTypes": [...],
"admin":{...},
"myData": {...},
"browse":{...}
}
]
}
from the above following attributes defined:
Specifies the paging type configuration i.e. for either paged or infinite scroll.
An example configuration for infinite scrolling:
{
"site": {
"paging" : {
"pagingType": "scroll",
"scrollPageSize": 50,
"scrollRowFromEnd": 10
}
}
}
An example configuration for standard page based pagination:
{
"site": {
"paging" : {
"pagingType": "page",
"paginationNumberOfRows": 10,
"paginationPageSizes": [
10,
25,
50,
100,
1000
]
}
}
}
Specifies global breadcrumb options.
An example breadcrumb configuration:
{
"site": {
"breadcrumb": {
"maxTitleLength": 30
}
}
}
Specifies the structure of the search results and search fields for searching across facilities.
An example (partial) configuration:
{
"site": {
"search": {
"enableParameters": false,
"enableSamples": false,
"gridOptions": {
"investigation": {...},
"dataset": {...},
"datafile": {...}
}
}
}
}
Specifies the structure of the root of “browse” section of the site. This only applies to a Topcat with multiple facilities.
An example (partial) configuration:
{
"site": {
"browse":{
"gridOptions": {...},
"metaTabs": [...]
}
}
}
Specifies the structure of the cart.
An example (partial) configuration:
{
"site": {
"cart":{
"maxDatafileCount": 1000000,
"maxTotalSize": 1000000000000,
"gridOptions": {...}
}
}
}
Specifies the structure of ‘downloads’ dialog box.
An example (partial) configuration:
{
"site": {
"myDownloads":{
"gridOptions": {...}
}
}
}
Allows you to define information pages e.g. “About Us” or “Contact” etc…
An example configuration:
{
"site": {
"pages" : [
{
"url" : "/about",
"stateName": "about",
"addToNavBar": {
"linkLabel" : "MAIN_NAVIGATION.ABOUT",
"align" : "left"
},
"contents": "PAGE.ABOUT.HTML"
}
]
}
}
The entity heierachy of the browse section.
An example configuration:
{
"facilities": [
{
"hierarchy": [
"facility",
"proposal",
"investigation",
"dataset",
"datafile"
]
}
]
}
The above configuration will make the user browse via “facility” > “proposal” > “investigation” > “dataset” > “datafile”.
Specifies the authentication plugins to be used e.g. LDAP
An example configuration:
{
"facilities": [
{
"authenticationTypes": [
{
"title": "Simple",
"plugin": "simple"
},
{
"title": "DB",
"plugin": "db"
}
]
}
]
}
Specifies the download delivery methods e.g. ‘https’ (via a browser) or ‘globus’ (a type of glorified ftp to deal with large files).
An example configuration:
{
"facilities": [
{
"downloadTransportTypes": [
{
"type" : "https",
"idsUrl": "https://fdsgos11.fds.rl.ac.uk"
},
{
"type" : "globus",
"idsUrl": "https://fdsgos11.fds.rl.ac.uk"
},
{
"type" : "scarf",
"idsUrl": "https://dls-ids01.scarf.rl.ac.uk"
}
]
]
}
}
Defines the structure of admin interface. This interface is only available to admin users (specified in topcat.properties).
An example (partial) configuration:
{
"facilities": [
{
"admin":{
"gridOptions": {...}
}
}
]
}
Specifies the structure of the “My Data” section.
An example (partial) configuration:
{
"facilities": [
{
"myData": {
"entityType" : "investigation",
"gridOptions": {...}
}
}
]
}
Specifies the structure of the hierachical browse section.
An example (partial) configuration:
{
"facilities": [
{
"browse": {
"investigation": {
"gridOptions": {...},
"metaTabs": [...]
},
"proposal": {...},
"dataset": {...},
"datafile": {...}
}
}
]
}
General principles configuring the gridOptions.
An example configuration:
"gridOptions": {
"enableSelection": true,
"enableUpload": true,
"columnDefs": [
{
"field": "visitId",
"link": true,
"breadcrumb": true
},
{
"field": "size"
},
{
"field": "datasetCount"
},
{
"field": "datafileCount"
},
{
"field": "investigationInstrument.fullName"
},
{
"field": "startDate",
"excludeFuture": true,
"sort": {
"direction": "desc",
"priority": 1
}
},
{
"field": "endDate"
}
]
}
General principles configuring the metaTabs.
An example configuration:
"metaTabs": [
{
"title": "METATABS.DATASET.TABTITLE",
"items": [
{
"field": "name"
},
{
"field": "description"
},
{
"label": "METATABS.DATASET.START_DATE",
"field": "startDate",
"template": "{{content.value | date:'yyyy-MM-dd'}}"
},
{
"label": "METATABS.DATASET.END_DATE",
"field": "endDate",
"template": "{{content.value | date:'yyyy-MM-dd'}}"
}
]
},
{
"title": "METATABS.DATASET_TYPE.TABTITLE",
"items": [
{
"field": "datasetType.name"
},
{
"field": "datasetType.description"
}
]
}
]
Topcat defines the following jpql variables - which if used from any icat entity type will automatically work out any joins required to create a jpql statement for fetching the data from icat:
To get a better understanding of what these jpql variables refer to please view the icat schema documentation.