documentation:software:webapi:setup
Differences
This shows you the differences between two versions of the page.
| Next revision | Previous revision | ||
| documentation:software:webapi:setup [2016/08/19 14:35] – created frank_defalco | documentation:software:webapi:setup [2018/04/23 19:11] (current) – lee | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ==== WebAPI Setup & Installation ==== | + | ~~NOTOC~~ |
| + | |||
| + | ===== WebAPI | ||
| + | |||
| + | |||
| + | |||
| + | ==== Overview ==== | ||
| + | This page describes the database setup, maven build configuration and deployment of OHDSI/ | ||
| + | |||
| + | ==== Database Preparation ==== | ||
| + | ---- | ||
| + | === MS SQL Server === | ||
| + | ---- | ||
| + | Coming Soon. | ||
| + | |||
| + | === PostgreSQL 9.3 === | ||
| + | ---- | ||
| + | |||
| + | Please refer to the [[https:// | ||
| + | |||
| + | |||
| + | === Oracle 11g XE === | ||
| + | ---- | ||
| + | Please refer to the [[https:// | ||
| + | |||
| + | |||
| + | ==== Installing WebAPI ==== | ||
| + | ---- | ||
| + | === Installing Maven === | ||
| + | ---- | ||
| + | Download Maven binary zip from https:// | ||
| + | Unzip to Program Files folder | ||
| + | Add Maven bin folder to system path | ||
| + | //Make sure JAVA_HOME is set (Note: You will not be able to build multi-architecture R projects when JAVA_HOME is set)// | ||
| + | |||
| + | === Cloning the WebAPI project === | ||
| + | ---- | ||
| + | Clone the WebApi project to a local folder, e.g.: | ||
| + | |||
| + | git clone https:// | ||
| + | |||
| + | |||
| + | ==== WebAPI Configuration ==== | ||
| + | ---- | ||
| + | Each database platform will have their own JDBC driver class name and connection string URL. The following sections describes how PostgreSQL, MSSql and Oracle could be configured to connect to the DB server. | ||
| + | |||
| + | === Microsoft SQL Server === | ||
| + | Coming Soon. | ||
| + | |||
| + | === PostgreSQL=== | ||
| + | **Create settings.xml File** | ||
| + | |||
| + | Specify user name, password, and location of the OHDSI schema (this was created as ‘webapi’ from the [[https:// | ||
| + | Here is an example XML that is based on the above configuration: | ||
| + | |||
| + | |||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | |||
| + | Note: this file above is saved as / | ||
| + | |||
| + | **Download the appropriate JDBC driver** | ||
| + | |||
| + | For PostgreSQL, the driver is available from the Maven repository, so no additional steps are required. | ||
| + | |||
| + | ==== Oracle ==== | ||
| + | ---- | ||
| + | **Create settings.xml File** | ||
| + | Specify user name, password, and location of the OHDSI schema (this was created as ‘ohdsi’ above). Note that the user should have read, write, and create privileges on the OHDSI schema because this user is the owner of the ' | ||
| + | Here is an example XML that is based on the above configuration: | ||
| + | |||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | |||
| + | Note: this file above is saved as / | ||
| + | |||
| + | **Download the Oracle JDBC driver** | ||
| + | You will need to download the Oracle JDBC driver, and install it into your local maven repository. | ||
| + | |||
| + | mvn install: | ||
| + | |||
| + | (The above is all a single line command.) | ||
| + | |||
| + | ==== Building the .war file ==== | ||
| + | ---- | ||
| + | |||
| + | Open command prompt, go to WebAPI folder, type | ||
| + | |||
| + | set JAVA_HOME=C:/ | ||
| + | |||
| + | //Make sure you point to a JDK, not a JRE. It is probably a good idea to stick to the same Java version that is running Tomcat// | ||
| + | |||
| + | mvn clean package -s / | ||
| + | |||
| + | This will create the file WebAPI.war in the target subfolder. | ||
| + | //Note: {profile id} is set to the value of the profile ID from the example configuration. | ||
| + | |||
| + | ==== Deploy the war file ==== | ||
| + | ---- | ||
| + | In Tomcat (e.g. using the manager app), deploy the war file. | ||
| + | This should automatically create a large number of tables in the webapi schema. | ||
| + | |||
| + | === Verify Application === | ||
| + | ---- | ||
| + | Reading the Tomcat logs, the following output should appear indicating that the tables have been created (in this example, we see an Oracle output): | ||
| + | |||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | 2016-02-24 11: | ||
| + | |||
| + | |||
| + | Other platforms should see similar output, except for the JDBC url in the connection. | ||
| + | |||
| + | === Configure source and source_daimon tables === | ||
| + | ---- | ||
| + | The webapi.source and webapi.source_daimon tables were created when you started the tomcat service with the WebAPI war deployed. | ||
| + | |||
| + | Here are the valid values for the daimon_type in the source_daimon table: | ||
| + | 0 = CDM, 1 = VOCABULARY, 2 = RESULTS, 3 = EVIDENCE | ||
| + | |||
| + | For this example it is assumed that the CDM and Vocabulary exist as a separate schema in the same database instance. | ||
| + | |||
| + | === WebAPI SOURCE and SOURE_DAIMON Inserts === | ||
| + | |||
| + | INSERT INTO ohdsi.source (source_id, source_name, | ||
| + | INSERT INTO ohdsi.source (source_id, source_name, | ||
| + | INSERT INTO webapi.source_daimon (source_daimon_id, | ||
| + | INSERT INTO webapi.source_daimon (source_daimon_id, | ||
| + | INSERT INTO webapi.source_daimon (source_daimon_id, | ||
| + | INSERT INTO webapi.source_daimon (source_daimon_id, | ||
| + | |||
| + | |||
| + | The above inserts create 2 Sources: One used to point to the instance containing the CDM tables, the second pointing to the server containing a Vocabulary. | ||
| + | //Note: WebAPI will need to be restarted in order to see the the new sources (Issue# TBD).// | ||
| + | |||
| + | //Note: IF using postgresql, the jdbc connection string is of the form// | ||
| + | |||
| + | jdbc: | ||
| + | |||
| + | === Verify Configuration === | ||
| + | ---- | ||
| + | Once WebAPI is started, and the source/ | ||
| + | |||
| + | http:// | ||
| + | |||
| + | This should result in the following output: | ||
| + | |||
| + | [ | ||
| + | {" | ||
| + | [ | ||
| + | {" | ||
| + | {" | ||
| + | {" | ||
| + | ] | ||
| + | }, | ||
| + | {" | ||
| + | [ | ||
| + | {" | ||
| + | ] | ||
| + | }] | ||
| + | |||
| + | |||
| + | WebAPI is now configured and ready to serve OHDSI tools! | ||
| + | |||
| + | ==== Troubleshooting ==== | ||
| + | ---- | ||
| + | ===Errors during WebAPI startup=== | ||
| + | ---- | ||
| + | If errors are encountered in the logs of WebAPI, the most likely reason is JDBC url was not set properly (note: database names are case sensitive!), | ||
| + | ===Errors when calling sources URL=== | ||
| + | ---- | ||
| + | The most likely error you will receive when accessing %%http:// | ||
| + | is the ohdsi_app_user does not have permission on relation ‘source’. | ||
| + | If no error is appearing in the logs at all, please confirm the Tomcat servlet engine is listening on port 8080. If it is on a different port, you will need to adjust the URLs above to the correct port. | ||
documentation/software/webapi/setup.1471617308.txt.gz · Last modified: by frank_defalco