Measure Authoring Tool (MAT)

Installation

The Measure Authoring Tool (MAT) was designed using many open source products including, the Google Web Toolkit (GWT) framework, Java JDK, and MySQL. GWT allows a developer to write client side code in Java and GWT converts it to JavaScript. The MAT uses MySQL as its backend database server.

Due to the use of these open source products, a working knowledge of Java development and some research into how the products work with each other in your environment may be necessary. Research from discussions on product forums, help documents, internet searches and knowledge of the local environment where the MAT will be running may all need to be checked if there are errors during install.

Configure Java (JDK)

• The application has not been tested with version above Java 15; (OPEN JDK is fine) please ensure this version is in the environment.
• Verify that JAVA_HOME and PATH system variables are pointing to the proper folder(s).
  • For example, the JAVA_HOME should point to the Java SDK 15.0.x folder and PATH should point to the Java 15.0.x/bin.

Configure Maven

You should install the latest Maven locally.

Windows:

• Install and Configure Maven (3.6.3+)

OSX:

• brew install maven or if already installed brew update maven

Create MAT Database

MAT uses MySQL Community Version 8.0.22. Here are some instructions for installing it using brew.

MySQL Install:

• Install MySQL (MAT currently has been tested with MySQL Community Version 8.0.22) available from MySQL
• Run the MySQL community server installer for your operating system and the MySQL workbench (which comes with the download).
• Enter a password and click on Use Legacy Password Encryption. (Remember the username/pwd you will need these in future steps.)
• For Mac:
• Go to System Preferences/ MY SQL after installing.
• Click Initialize Database.
• Start the MYSQL Db.
• Create a new MySQL Connection to the database. (example tooling: IDE Built-in Tooling, Jetbrains datagrip, MySQL Workbench)
• If you have access to a data dump, create a schema and load it with your dump script.
• If you do not you can load the dump script located in scripts.
• From the MAT Code base, find the scripts/Dump*.sql file and then execute the script in the database that was just created.
  (Note this script is from a dump and drops and create a schema called MAT_APP_BLANK)
• There are other more recent dump files located here.

Tomcat installation

Download tomcat 9

• After installing, you may need to sudo chmod -R 777 on the tomcat directory.

Add the JDBC Resource to the Tomcat context file ($CATALINA_HOME/conf/context.xml). Match the username, password, and schema name to your mysql configuration.

<Resource name="jdbc/mat_app_tomcat"
         cachingAllowed="true"
         cacheMaxSize="1000000"
         auth="Container"
         type="javax.sql.DataSource"
         factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
         testWhileIdle="true"
         testOnBorrow="true"
         testOnReturn="false"
         validationQuery="SELECT 1"
         validationInterval="30000"
         timeBetweenEvictionRunsMillis="30000"
         maxActive="100"
         minIdle="10"
         maxWait="10000"
         initialSize="10"
         removeAbandonedTimeout="60"
         removeAbandoned="true"
         logAbandoned="true"
         minEvictableIdleTimeMillis="30000"
         jmxEnabled="true"
         jdbcInterceptors="org.apache.tomcat.jdbc.pool.interceptor.ConnectionState;
           org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer"
         username="<USERNAME>"
         password="<PASSWORD>"
         driverClassName="com.mysql.jdbc.Driver"
         url="jdbc:mysql://localhost:3306/<SCHEMA_NAME>"/>

Copy mysql jdbc to tomcat lib directory. bash cp ~/.m2/repository/mysql/mysql-connector-java/8.0.22/mysql-connector-java-8.0.22.jar $CATALINA_HOME/lib

Create an OKTA account to use locally.

You need to create an Okta developer account to run MAT locally. This is a stand-in for HARP. After creating one and going to settings my url looks like this:

https://${yourOktaDomain}/admin/settings/account

The ${yourOktaDomain} part is what you will use to configure okta below.

If you started from a blank ID you can run this to update your user row with your okta id:

update USER set HARP_ID = '${YOUR_OKTA_ID:john-doe}' where LOGIN_ID='devUser8762';

If you started from a db dump you will need to overwrite a HARP_ID in the user table with your HARP_ID to login.

Setup microservices needed for MAT

Follow the instructions here: https://github.com/MeasureAuthoringTool/QDM-QICore-Conversion

Setup local environment IntelliJ configurations (mvn, tomcat, super dev mode)

GWT takes a while to compile so if you setup like this locally you will save a lot of time. These instructions are written for IntelliJ.

• Install the GWT intellij plugin.
• Go to Edit Configurations

• Click the + in the top left and add a tomcat server.

• Example Tomcat Run Configuration

• Paste in the following for VM options: Replace https://${yourOtkaDomain} with the domain from your Okta Developer Account. See Find your Okta domain.

-DENVIRONMENT=DEV
-Dlog4j.ignoreTCL=true
-D2FA_AUTH_CLASS=mat.server.twofactorauth.DefaultOTPValidatorForUser
-D2FA_AUTH_CLASS1=mat.server.twofactorauth.DefaultOTPValidatorForUser
-DBONNIE_RESPONSE_TYPE=code
-DBONNIE_REDIRECT_URI=https//yourredirectURI.com
-DBONNIE_CLIENT_ID=1234567890
-DBONNIE_CLIENT_SECRET=1234567890
-DBONNIE_URI=https://bonnieURL.org
-DALGORITHM=EncyptionAlgorithm
-DPASSWORDKEY=PasswordKey
-DFHIR_SRVC_URL=http://localhost:9080
-DQDM_QICORE_MAPPING_SERVICES_URL=http://localhost:9090
-DCQL_ELM_TRANSLATION_URL=http://localhost:7070
-DHARP_BASE_URL=https://${yourOktaDomain}
-DHARP_URL=https://${yourOktaDomain}/oauth2/v1
-DHARP_CLIENT_ID=$OKTA_CLIENT_ID
-DMAT_API_KEY=DISABLED
-DVSAC_TICKET_URL_BASE=https://utslogin.nlm.nih.gov/cas/v1
-DVSAC_URL_BASE=https://vsac.nlm.nih.gov
-Dgwt.codeserver.port=9876

• Go to Edit Configurations again and this time click the + and pick maven.

Maven Configuration

Maven Configuration with Test skip

GWT Configuration

• Dev mode params:

  -noserver -war /Users/carson.day/git/MeasureAuthoringTool/target/MeasureAuthoringTool
  

• Start page:

  http://localhost:8080/MeasureAuthoringTool_war_exploded/Login.html
  

How to build locally and run with super dev mode.

To compile faster you can make these changes, but DO NOT check them in.

• In the *gwt.xml files in MAT. Change user agent to this:

<set-property name="user.agent" value="safari"/>

1. Select Mat Code Server and start it up.
2. Select Mat Tomcat and start it up. (wait until the server starts)
3. A browser should pop up and you are off and running in super dev mode.
4. Go to http://localhost:9876/
5. Drag the Dev Mode On button onto your bookmark bar.
6. Go to the browser page that popped up. View -> Developer.
7. Click sources.
8. The java GWT code from super dev mode will show up here under source maps
9. You set break points in the browser and debug from the js.
10. To recompile code click the bookmark you dragged to the bar in step 6 while in MAT.

Tomcat 10

Tomcat 10 is an implementation of the Servlet 5 specification (part of Jakarta EE 9) that renamed all of the packages from javax.servlet to jakarta.servlet. Neither Spring Boot nor Spring Framework supports Jakarta EE 9 at this time. (source)

See Specification API section of the Tomcat 9 to 10 Migration Guide for details on the changes between Tomcat 9 and 10.

IntelliJ: Tomcat 10 Configuration

Run the Apache Tomcat Migration Tool for Jakarta EE against the generated WAR and place the result in the target directory. IntelliJ will pick up the WAR and copy it to the Tomcat 10 webapps directory.

Prerequisite: Download the Migration tool

Download and expand the Binary Distribution for the Tomcat Migration Tool for Jakarta EE.

Prerequisite: Install Tomcat 10

Install Tomcat 10 locally by following the Tomcat 9 installation described above using the Tomcat 10 installer.

Run Configuration

1. Repeat the IntelliJ Run Configuration described above using the Tomcat 10 installation directory.
2. In the IntelliJ Run Configuration for Tomcat 10 > Before launch section > add an entry of Run External tool:
3. Add a new Entry to the External Tools dialog:
   • Name: <Anything memorable>
   • Group: External Tools
   • Description: <Optional>
   • Program: <Migration Tool location>/bin/migrate.sh
   • Arguments $ProjectFileDir$/target/MeasureAuthoringTool.war $ProjectFileDir$/target/MeasureAuthoringTool.war
   • Working directory: $ProjectFileDir$
4. Click OK to close the Edit Tool window.
5. Click OK to close the External Tools window.
6. Click OK to close the Run Configuration window.

Release build (NON-local)

mvn clean install

Log in to MAT

To login to MAT, open MySQL Workbench and run the following queries:

• SELECT * FROM USER where USER_ID='Admin'
  • Look at the LOGIN_ID is your UserID.
  • The password default is ‘gargleBlaster_10’.
  • Enter any three digit code for security code.
• Navigate to the MAT log in page GUI and use the UserID and password from the previous step and log in to MAT.
• Once logged in, navigate to the Mat Account tab and enter the Admin user details under the Personal Information tab and the Security Questions tab to setup user’s security questions.
• To change the password to something new, use the Password tab.
• To create users an email is sent and this must be configured to obtain user names and passwords.

Important Security Setup With Git Secrets

1. Use brew to install git secrets brew install git-secrets
2. Clone this repository (you can skip this if you've already cloned it from previous steps)
3. Note: You may have to reinitialize these hooks each time you clone a new copy of the repo
4. Follow these instructions for setting up the pre-commit hooks:

   cd /path/to/MeasureAuthoringTool
   git secrets --install
   git secrets --register-aws

5. Done! Now each commit should be automatically scanned for accidental AWS secret leaks.