The CED2AR Configuration Files
- Description of fields
- User Authorization
- UI Navigation Customization
- Services
- Configuration Properties page
- Configuration Examples
- Generate PDF Files page
The primary config files are found in the source code under: /profiles/{profile name}/config.properties.
When CED2AR is built the file can also be changed after being deployed to Tomcat: /webapps/ced2ar-web/WEB-INF/classes/ced2ar-web-config.properties
If you imported the source code to your IDE, and ran in through Tomcat, CED2AR might be deployed under wtpwebapps in the Tomcat directory, rather than the webapps directory.
The appearance of CED2AR (primarily the banner color and text) is controlled based on the hostname in WEB-INF/tags/main.tag.
All config property/field definitions are now in the Source/src/main/resources/ced2ar-web-config.properties file.
-
Each property has a one line definition.
-
Processes or more complex interactions between properties are listed below.
-
Definitions in other locations are deprecated.
-
To view only the metadata, do a grep on the file.
grep -h '#' <path>/Source/src/main/resources/ced2ar-web-config.properties
Note that many field values are case sensitive.
baseXDB - The URL to the BaseX web application used as a database. For best security, run locally on the same system with a port that is not exposed.
baseXReaderHash,basex.writer.hash,basex.admin.hash - Base 64 encodings of service account credentials. Formatted with the syntax user:password. For example, if the admin user has a password of admin, encoding admin:admin in BaseX yields YWRtaW46YWRtaW4=
Changing the passwords in the CED2AR config file also require changing the passwords in BaseX (see here).
In UNIX you can do e.g. echo -n "admin:admin" | base64, or you can find a base 64 encoder online.
basex.generate.random.passwords - If ced2ar generates a random admin password on startup. Leave off.
basex.allow.change.passwords= If the /config UI allows the admin to change BaseX passwords after deployment
port - port on which the applications runs
env.restricted - if true, the application will use local js/css
openAccess - if true, any user who authenticates with e.g. OAuth2 or ORCID assumes a user role. This is useful for wiki (crowd-sourced) servers.
accessMode - Configures the access restrictions for various pages in CED2AR. The currently supported options are:
-
UserDefault: No access restrictions for browse-oriented pages. Edit pages require either User or Admin access, depending on the nature of the edits. -
AdminOnly: A user must be logged in as an admin to access any page. This is primarily used for codebook-development servers where crowd-sourced edits are curated and edited by administrators.
pwd.israndom - Creates random admin password, and locks down entire application on startup
Bug report settings are as follows: bug.report.email - Admin to send to bug.report.sender - Account to send from bug.report.pwd - Base64 encoding of password bug.report.enable - If bug reporting is turned on
schema.uri - DDI schema URL, do not change
pdf.enabled - Whether or not to generate pdf codebooks pdf.generator.scheduled.task.cron.interval -Seconds Minutes Hours Day_of_week Month Year So 0 59 23 * * * will run everyday at 11:59:00pm
pwd.hash - SHA-1 hash of password for admin account under default authentication type echo -n 'password here' | sha1sum. Alternatively, try a Java-based utility such as this online tool or, for better security, run the accompanied code on your own system.
authentication.type= Either: OPENID,OAUTH2,DEFAULT. OPENID and OAUTH2 require additional configuration
CED2AR currently doesn't allow automated user signup, though on crowd-sourced servers any user with an OAuth2 account of a specified type may login (see openAccess); authorized users must be manually added to WEB-INF/classes/ced2ar-user-config.properties. For instance, for Google OAuth2, this would include Google-provided e-mail addresses, and for ORCID, the ORCID IDs:
ced2ar.roles=ROLE_USER,ROLE_ADMIN
# SpringSecurity is authenticating users with their account identity url as the user name.
# The account identity url is what you are going to get when you call request.getRemoteUser().
[email protected],[email protected],0000-000X-YYYY-ZZZZ
[email protected],[email protected]
If you want any user that authenticates with an OAuth2 account as above to have access to the system (e.g. for demoing or crowd sourcing), then you can set openAccess to true in ced2ar-web-config.properties (see above).
Note that additional configuration is needed for OAuth2 with Google or ORCID. Briefly:
As noted above, the authentication type should be set to OAUTH2 for the authenticationType property (other values that are supported are OPENID and DEFAULT (source link). Add a space-separated list of OAUTH2 providers to supportedOauth2Providers (at least one; currently one or more of GOOGLE or ORCID). To use the user authorization properties file mentioned above, change authorizationStorage accordingly:
authenticationType=OAUTH2
supportedOauth2Providers=GOOGLE ORCID
authorizationStorage=PROPERTIES_FILE
authorizationStorage can be set to BASEX so that users and admins are stored in BASEX.
Set authCode in config.properties as follows:
#OAUTH2 Configuration
authCode=authorization_code
- Go to https://console.developers.google.com/project and create a new project
- Click on 'Credentials' and click on 'Create new Client Id'. Google will create a new client id, client secret.
- In the 'redirect uris' section please enter http://localhost:8080/ced2ar-web/google_oauth2_login - the http://localhost:8080 part should have the base URL replaced accordingly for your server. Note that leaving it as "localhost" will not work - it must be a public address.
- Click on 'Consent Screen' and enter
- email adddress
- product name (this should be same as the project name)
- Copy the client id, client secret and redirect (callback) URI and store them somewhere safe.
Add those values into the config.properties file in the profile
oauth2.clientId=oauth2.clientSecret=oauth2.preEstabledUrl=
Example with sensitive strings replaces with Xs:
googleDefaultFilterURL=google_oauth2_login
googleClientId=xxxxxxxxxx.apps.googleusercontent.com
googleClientSecret=XXXXXXXXXXXXXX
googleAccessTokenURL=https://accounts.google.com/o/oauth2/token
googleAuthURL=https://accounts.google.com/o/oauth2/auth
googleTokenURL=https://www.googleapis.com/oauth2/v1/tokeninfo
googlePreEstabledURL=https://demo.ncrn.cornell.edu/ced2ar-web/google_oauth2_login
googleInfoReq=email
googlePersonInfoURL=https://www.googleapis.com/plus/v1/people/me
-
Go to http://orcid.org/content/register-client-application-2 and register the appropriate type of API credentials
-
After filling out other project info, in the 'Redirect URIs' section please enter http://localhost:8080/ced2ar-web/orcid_oauth2_login - the http://localhost:8080 part should have the base URL replaced accordingly for your server.
-
Copy the client id, client secret and redirect URI and store them somewhere safe. Add those values into the config.properties file in the profile
oauth2.clientId=oauth2.clientSecret=oauth2.preEstabledUrl=
-
To add more redirect_uris to the project in the future, visit https://orcid.org/developer-tools
Example with sensitive strings replaced with Xs:
orcidDefaultFilterURL=orcid_oauth2_login
orcidClientId=APP-XXXXXXXXXXXX
orcidClientSecret=XXXXXXXXXXXXXXXXXXX
orcidAccessTokenURL=https://pub.orcid.org/oauth/token
orcidAuthURL=https://orcid.org/oauth/authorize
orcidTokenURL=https://api.orcid.org/oauth/token
orcidPreEstabledURL=https://demo.ncrn.cornell.edu/ced2ar-web/orcid_oauth2_login
orcidInfoReq=/authenticate
orcidPersonInfoURL=https://pub.orcid.org/v1.2
These properties are used to display/hide navigation tabs and the names of those tabs. Look at the Configuration Properties page screenshot before reading this section. The screenshot is easier to understand than these dry property definitions.
- Setting a ui nav (bar/tab) item to true displays that tab. Setting it to false removes that tab. Allowable values: true, false.
- Any of the .label properties can be set to any name you want to suit your environment.
These are top level navigation items that can be set.
ui.nav.bar.browse.codebook - If true, displays the Browse by Codebook tab. Default: true
ui.nav.bar.browse.codebook.label – Tab label. Default: Browse by Codebook
ui.nav.bar.browse.study - If true, displays the Browse by Study tab. Default: true
ui.nav.bar.browse.study.label – Tab label. Default: Browse by Study
If your site is using the Browse by Study tab (ui.nav.bar.browse.study=true), you can set these subtabs on the …/study page. (aka DDI tabs).
ui.nav.tab.doc - If true, displays the Doc tab. Default: true
ui.nav.tab.doc.label – Tab label. Default: Doc
ui.nav.tab.stdy - If true, displays the Study tab. Default: true. (Cannot be set to false.)
ui.nav.tab.stdy.label – Tab label. Default: Study
ui.nav.tab.file - If true, displays the File tab. Default: true
ui.nav.tab.file.label – Tab label. Default: File
ui.nav.tab.data - If true, displays the Data tab. Default: true
ui.nav.tab.data.label – Tab label. Default: Data
ui.nav.tab.otherMat - If true, displays the Other Material tab. Currently, CED2AR does not expose any /otherMat elements so this is turned off. Default: false
ui.nav.tab.otherMat.label – Tab label. Default: Other Material
A new SOA service has been added to support the conversion of datasets into DDI-C codebook format. The service receives a message with a dataset file and returns an xml response in DDI-C codebook format. The dataset file can be a Stata (.sav) or SPSS (.dta) file.
This experimental service is used in the Create tab on the Manage codebooks page. There is an about page that you can hit to see if the service up and the version number. Hitting https://localhost:8080/ced2ardata2ddi/ returns the about page.
- By default, the service runs in the same tomcat container as CED2AR.
- If you are running multiple instances of CED2AR, the system administrator could run a single instance of this service and point the other CED2AR instances to the one running the service.
- System administrators have the option of turning off/unchecking this service.
- If the administrator unchecks the service, the Create tab will not be displayed to users.
- To install/uninstall this service, the administrator needs to go into the tomcat manager page and install/uninstall the ced2ardata2ddi application.
These are the properties used for the data2ddi (ced2ardata2ddi) service and the default values. You can set them using the Configuration Properties page. See the Configuration Properties page screenshot.
data2ddiSvc - If true, displays the Create tab on the Manage codebooks page. Default: true
data2ddiUrl - URL for the data2ddi service. This may need to be modified by the system administrator to work for the environment. The default value is set for a generic tomcat server environment. Default: http://localhost:8080/ced2ardata2ddi/data2ddi
data2ddiSvc=true
data2ddiUrl=http://localhost:8080/ced2ardata2ddi/data2ddi
Many properties can be modified with the Configuration Properties page. The remaining properties are in: ced2ar-web/WEB-INF/classes/ced2ar-web-config.properties, ced2ar-web-beans.xml, or log4j.properties
NOTE: Some configuration property changes may not take immediate effect. In these cases, you will need to stop and restart the CED2AR application OR the Tomcat server.
CED2AR has 77 properties that can be set. The number you need, depends on the type of system you want and your configuration choices. Type roughly translates to the crowdSourcingRole property.
Below are the types with a quick description and a link to an example config file. The example config files have been modified using the following notation:
-
<domain>- Your domain. Example: ncrn.cornell.edu -
<gitProvider>- Your git Provider (and organization). Example: bitbucket.org/ncrncornell -
<MasterServerName>Your Master (main) server name. Example: prod -
<WikiServerName>- Your Wiki (crowdsourcing) server name. Example: wiki-prod -
<xxx>- Supply your sensitive (hash/password/id) value. -
<removeServerName>- Your remote server name. Only for a Development environment under unusual development/testing.
Use these example files as a guide to help you set up your actual ced2ar-web-config.properties file.
Remember to back up your configuration files before making changes.
This is the simplest and also the default config file. It allows a java developer to get the CED2AR application up and running on a developer’s laptop. This is a simple stand-alone system. It does not do any crowdsourcing or OAuth2 authorization.
crowdSourcingRole=none
The master contains its own set of codebooks. The master can look at changes that occur on the wiki system.
crowdSourcingRole=master- It is configured to work with a wiki system.
- It uses git to help manage versioning.
- This particular system is configured to use two OAuth2 providers: GOOGLE and ORCID.
The wiki (aka crowdsourcing) is usually a public facing system that allows authenticated users to make changes/comments on a codebook in the wiki system.
crowdSourcingRole=wiki- It is configured to work with a master system.
- It uses git to help manage versioning.
- This particular system is configured to use one OAuth2 provider: ORCID.
This page allows an administrator the ability to generate pdf files for all the codebooks in the BaseX database.
- Enter URL for the page.
- Click the Generate PDFs button.
- Wait until you see a green message box.
- Example: "Complete. generatePDFsAll took 22 Seconds"
