documentation:software:webapi:webapi_installation_guide
Differences
This shows you the differences between two versions of the page.
| Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
| documentation:software:webapi:webapi_installation_guide [2016/08/23 20:22] – jhardin | documentation:software:webapi:webapi_installation_guide [2019/04/19 16:23] (current) – anthonysena | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ~~NOTOC~~ | ~~NOTOC~~ | ||
| - | =====WebAPI Installation Guide ===== | + | |
| - | ---- | + | ===== IMPORTANT NOTE ===== |
| + | |||
| + | All WebAPI documentation has moved to [[https:// | ||
| + | |||
| + | ===== WebAPI Installation Guide (LEGACY) | ||
| ==== Overview ==== | ==== Overview ==== | ||
| Line 13: | Line 17: | ||
| === MS SQL Server === | === MS SQL Server === | ||
| ---- | ---- | ||
| - | Coming Soon. | + | |
| + | Please refer to the [[documentation: | ||
| === PostgreSQL 9.3 === | === PostgreSQL 9.3 === | ||
| ---- | ---- | ||
| - | Please refer to the [[https:// | + | Please refer to the [[documentation:software: |
| Line 24: | Line 29: | ||
| ---- | ---- | ||
| - | Please refer to the [[https:// | + | Please refer to the [[documentation:software: |
| Line 31: | Line 36: | ||
| === Installing Maven=== | === Installing Maven=== | ||
| + | ---- | ||
| Download Maven binary zip from https:// | Download Maven binary zip from https:// | ||
| Unzip to Program Files folder | Unzip to Program Files folder | ||
| Add Maven bin folder to system path | 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 | + | ===Cloning the WebAPI project=== |
| + | ---- | ||
| Clone the WebApi project to a local folder, e.g.: | Clone the WebApi project to a local folder, e.g.: | ||
| - | ``` | ||
| - | git clone https:// | ||
| - | ``` | ||
| - | ## WebAPI Configuration | + | 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. | 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 | + | === Microsoft SQL Server |
| - | Coming Soon. | + | **Create settings.xml File** |
| - | ### PostgreSQL | + | Specify user name, password, and location of the OHDSI database (this was created as ‘ohdsi_app_user’ from the [[documentation: |
| + | |||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | </ | ||
| + | |||
| + | Note: this file above is saved as / | ||
| + | |||
| + | **Download the appropriate JDBC driver** | ||
| + | |||
| + | For SQL Server, the driver is available from the Maven repository, so no additional steps are required. | ||
| + | |||
| + | === PostgreSQL | ||
| **Create settings.xml File** | **Create settings.xml File** | ||
| - | Specify user name, password, and location of the OHDSI schema (this was created as ‘webapi’ from the [PostgreSQL Setup Guide](https:// | + | Specify user name, password, and location of the OHDSI schema (this was created as ‘webapi’ from the [[documentation: |
| Here is an example XML that is based on the above configuration: | Here is an example XML that is based on the above configuration: | ||
| - | ```xml | + | |
| - | < | + | < |
| < | < | ||
| < | < | ||
| Line 70: | Line 117: | ||
| < | < | ||
| < | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| </ | </ | ||
| </ | </ | ||
| </ | </ | ||
| - | </ | + | |
| - | ``` | + | |
| Note: this file above is saved as / | Note: this file above is saved as / | ||
| Line 81: | Line 138: | ||
| For PostgreSQL, the driver is available from the Maven repository, so no additional steps are required. | For PostgreSQL, the driver is available from the Maven repository, so no additional steps are required. | ||
| - | ### Oracle | + | === Oracle |
| **Create settings.xml File** | **Create settings.xml File** | ||
| - | Specify user name, password, and location of the OHDSI schema (this was created as ‘ohdsi’ | + | Specify user name, password, and location of the OHDSI schema (this was created as ‘ohdsi’ |
| Here is an example XML that is based on the above configuration: | Here is an example XML that is based on the above configuration: | ||
| - | ```xml | + | |
| - | < | + | < |
| < | < | ||
| < | < | ||
| Line 101: | Line 158: | ||
| < | < | ||
| < | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| </ | </ | ||
| </ | </ | ||
| </ | </ | ||
| - | </ | + | |
| - | ``` | + | |
| Note: this file above is saved as / | Note: this file above is saved as / | ||
| **Download the Oracle JDBC driver** | **Download the Oracle JDBC driver** | ||
| You will need to download the Oracle JDBC driver, and install it into your local maven repository. | You will need to download the Oracle JDBC driver, and install it into your local maven repository. | ||
| - | ``` | + | |
| - | mvn install: | + | mvn install: |
| - | ``` | + | |
| (The above is all a single line command.) | (The above is all a single line command.) | ||
| - | ## Building the .war file | + | ==== Building the .war file ==== |
| + | |||
| + | Open command prompt, **go to the 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 -DskipTests -s WebAPIConfig/ | ||
| - | 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. | 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. | + | //Note: {profile id} is set to the value of the profile ID from the example configuration. |
| - | ## Deploy the war file | + | === Deploy the war file === |
| - | In Tomcat (e.g. using the manager app), deploy the war file. | + | ---- |
| + | |||
| + | In Tomcat, you will need to increase the maximum file size allowed for WAR files. Go to webapps/ | ||
| + | |||
| + | < | ||
| + | < | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| + | |||
| + | 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. | This should automatically create a large number of tables in the webapi schema. | ||
| - | # Verify Application | + | ===== 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): | 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: |
| - | 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. | Other platforms should see similar output, except for the JDBC url in the connection. | ||
| - | ## Configure source and source_daimon tables | + | ==== 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. | The webapi.source and webapi.source_daimon tables were created when you started the tomcat service with the WebAPI war deployed. | ||
| For this example it is assumed that the CDM and Vocabulary exist as a separate schema in the same database instance. | 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 | + | === WebAPI SOURCE and SOURE_DAIMON Inserts |
| - | ```sql | + | ---- |
| - | 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 ohdsi.source (source_id, source_name, |
| - | INSERT INTO webapi.source_daimon (source_daimon_id, | + | 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, |
| + | 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. | 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: 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_ | + | //Note: IF using postgresql, the jdbc connection string is of the form// |
| - | `jdbc: | + | |
| - | ## Verify Configuration | + | === Verify Configuration |
| + | ---- | ||
| Once WebAPI is started, and the source/ | Once WebAPI is started, and the source/ | ||
| - | ``` | + | |
| - | http:// | + | http:// |
| - | ``` | + | |
| This should result in the following output: | This should result in the following output: | ||
| - | ```json | + | |
| - | [ | + | [ |
| {" | {" | ||
| [ | [ | ||
| Line 207: | Line 287: | ||
| ] | ] | ||
| }] | }] | ||
| - | ``` | + | |
| WebAPI is now configured and ready to serve OHDSI tools! | WebAPI is now configured and ready to serve OHDSI tools! | ||
| - | #Troubleshooting | + | =====Troubleshooting===== |
| - | ##Errors during WebAPI startup | + | ---- |
| + | ====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!), | 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 | + | ====Errors when calling sources URL==== |
| - | The most likely error you will receive when accessing http:// | + | ---- |
| + | The most likely error you will receive when accessing | ||
| is the ohdsi_app_user does not have permission on relation ‘source’. | 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. | 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/webapi_installation_guide.1471983756.txt.gz · Last modified: by jhardin