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"
If you are upgrading from 2.3.6 or earlier to 2.4.0, the following properties should be added to your topcat.properties: facility.list, facility.[facilityName].icatUrl, facility.[facilityName].idsUrl (for each facilityName in facility.list).
Where a facility offers multiple download transfer types (as specified in topcat.json), a specific URL (prefix) for a particular facility and download type can be specified by defining facility.[facilityName].downloadType.[transport] - see below for examples. If the property is not defined for a particular facility and download type, the facility’s idsUrl will be used instead.
Note: ’#’s are comments.
# List of Facility names # These names will be used by Topcat over the REST API; # each facility name in topcat.json must contain a match in this list, # and each name must be mapped to ICAT / IDS urls. # Edit these values to match your installation. facility.list = LILS YFH facility.LILS.icatUrl = http://localhost:8080 facility.LILS.idsUrl = http://localhost:8080 facility.YFH.icatUrl = https://your.facility.icatUrl.here facility.YFH.idsUrl = https://your.facility.idsUrl.here # Download transport URLs # topcat.json can specify one or more download transport types for each facility, egs "https", "globus"; # each may have a distinct download URL (prefix). To specify the download URL for a specific facility # and transport type, set an appropriate property as below. # Note that the transport type will be set in requests from the Topcat Javascript application, # but the URL to specify here should be the IDS url that will be used in the Java clients; # so it may be that the Javascript transport type https should be mapped here to an # internal http URL. # If the property is not defined, Topcat will use the facility's idsUrl by default. facility.LILS.downloadType.http = http://localhost:8080 facility.YFH.downloadType.https = https://your.facility.downloadIdsUrl.here facility.YFH.downloadType.globus = https://your.facility.globusUrl.here # 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": { "disabled": false, "enableTextBox": true, "enableDateRange": true, "enableParameters": true, "enableSamples": true, "enableInvestigation": true, "enableDataset": true, "enableDatafile": true, "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" : [ { "name" : "about", "addToNavBar": { "label" : "About", "align" : "left" } } ] } }
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.
After unzipping a Topcat release you will be presented with a directory called “content.example”, which you need to make a copy of called “content” i.e.
cp -R content.example content
This newly created directory allows you to either replace or add files within the war file (which is actually the same format as a zip file), to view the existing contents of this war (i.e. zip) file by running the following:
unzip -l topcat-2.4.0.war
after running:
./setup install
the contents of the “content” directory will be injected into the war file just before deploying.
You can use this feature to create a “pages” directory, which is where the html content specified within topcat.json’s “pages” section is defined, you can also this feature to replace or add any other content e.g. the favicon.
Allows you to replace text/phrases within Topcat’s interface with your own prefered alternatives e.g. rather than term “Investigation” you might prefer “Visit”.
Within lang.json is a json object that represents a hierarchy of translation strings, with a bit of experimentation you can modify virtually any text in Topcat’s front end e.g. if you wanted to change the “My Data” tab text simply edit “MAIN_NAVIGATION” -> “MAIN_TAB” -> “MY_DATA”.