Skip to content

Commit 817bae8

Browse files
chrisknollchrisknoll
committed
Update README.md with latest information.
1 parent 6c1fa34 commit 817bae8

1 file changed

Lines changed: 26 additions & 28 deletions

File tree

‎README.md‎

Lines changed: 26 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -5,32 +5,31 @@ OHDSI WebAPI contains all OHDSI RESTful services that can be called from OHDSI a
55
## Features
66

77
- Provides a centralized API for working with 1 or more databases converted to the [Common Data Model](https://github.com/OHDSI/CommonDataModel) (CDM) v5.
8-
- Searching the OMOP standardized vocabularies for medical concepts and constructing concept sets.
9-
- Defining cohort definitions for use in identifying patient populations.
10-
- Characterizing cohorts
11-
- Computing incidence rates
12-
- Retrieve patient profiles
13-
- Design population level estimation and patient level prediction studies
8+
- Searches the OMOP standardized vocabularies for medical concepts and constructs concept sets.
9+
- Defines cohort definitions for identifying patient populations.
10+
- Characterizes cohorts.
11+
- Computes incidence rates.
12+
- Retrieves patient profiles.
1413

1514
## Technology
1615

17-
OHDSI WebAPI is a Java 8 web application that utilizes a PostgreSQL database for storage.
16+
OHDSI WebAPI is a Java 21 web application that uses a PostgreSQL database for storage.
1817

1918
## API Documentation
2019

2120
The API Documentation is found at [http://webapidoc.ohdsi.org/](http://webapidoc.ohdsi.org/)
2221

2322
## System Requirements & Installation
2423

25-
Documentation can be found a the [Web API Installation Guide](https://github.com/OHDSI/WebAPI/wiki) which covers the system requirements and installation instructions.
24+
Documentation is available in the [WebAPI Installation Guide](https://github.com/OHDSI/WebAPI/wiki), which covers system requirements and installation instructions.
2625

2726
## WebAPI Configuration in version 3.0
2827

29-
Application configuration has moved from a maven build-based pipeline (in version 2.x) to external configuration in WebAPI 3.0 (and using a new YAML format) as described in this [Atlas Sandbox project](https://github.com/OHDSI/AtlasWebAPISandbox/tree/main/ExternalConfig).
28+
Application configuration moved from a Maven build-based pipeline in version 2.x to external YAML configuration in WebAPI 3.0, as described in the [Atlas Sandbox project](https://github.com/OHDSI/AtlasWebAPISandbox/tree/main/ExternalConfig).
3029

31-
### VS.Code Launch settings Example
30+
### VS Code Launch Configuration Example
3231

33-
In VS Code, to launch the app using an external config, you can define a new launch settings in your local .vscode/launch.json file:
32+
In VS Code, to launch the application using an external configuration file, define a new launch configuration in your local `.vscode/launch.json` file:
3433

3534
```
3635
{
@@ -48,7 +47,7 @@ In VS Code, to launch the app using an external config, you can define a new lau
4847
```
4948
_Note the format of Windows paths in this example_
5049

51-
This will pass the necessary VM arg to load additional Spring configuration from the specified file. For example, for a local Postgres install with Windows Authentication enabled:
50+
This passes the necessary VM argument to load additional Spring configuration from the specified file. For example, for a local PostgreSQL installation with Windows Authentication enabled:
5251

5352
```
5453
datasource:
@@ -67,9 +66,9 @@ security:
6766
origin: http://localhost
6867
provider: AtlasRegularSecurity
6968
```
70-
### Deploying WAR to Tomcat
69+
### Deploying a WAR to Tomcat
7170

72-
You can provide the enviornment variable `spring.config.additional-location` using a context.xml that is uploaded along with the WAR:
71+
You can provide the `spring.config.additional-location` environment property using a `context.xml` file deployed with the WAR:
7372

7473
```
7574
<Context>
@@ -125,13 +124,13 @@ The following parameters are used:
125124
- `security.auth.saml.sloUrl=https://localhost:8443/cas/logout` - identity provider logout URL
126125
- `security.auth.saml.callbackUrl=http://localhost:8080/WebAPI/user/saml/callback` - URL called from identity provider after login
127126

128-
Sample idp metadata and sp metadata config files for okta:
127+
Sample IdP and SP metadata configuration files for Okta:
129128
- `saml/dev/idp-metadata-okta.xml`
130129
- `saml/dev/sp-metadata-okta.xml`
131130

132-
## Managing auth providers (Updated for v3.0)
131+
## Managing Auth Providers (Updated for v3.0)
133132

134-
The following parameters are used to enable/disable certain provider:
133+
The following parameters enable or disable authentication providers:
135134

136135
- `security.auth.ad.enabled`
137136
- `security.auth.cas.enabled`
@@ -144,17 +143,17 @@ The following parameters are used to enable/disable certain provider:
144143
- `security.auth.openid.enabled`
145144
- `security.auth.windows.enabled`
146145

147-
Acceptable values are `true` and `false`
146+
Acceptable values are `true` and `false`.
148147

149-
Default paramaters for each of these authentication providers are provided as an example in the embedded application.yaml file. All providers are disabled by default.
148+
Default parameters for each authentication provider are provided as examples in the embedded `application.yaml` file. All providers are disabled by default.
150149

151150
## Geospatial support
152151

153152
Instructions can be found at [webapi-component-geospatial](https://github.com/OHDSI/webapi-component-geospatial)
154153

155154
## Testing
156155

157-
It was chosen to use embedded PG instead of H2 for unit tests since H2 doesn't support window functions, `md5` function, HEX to BIT conversion, `setval`, `set datestyle`, CTAS + CTE.
156+
Embedded PostgreSQL is used instead of H2 for unit tests because H2 does not support window functions, the `md5` function, HEX-to-BIT conversion, `setval`, `set datestyle`, or CTAS with CTEs.
158157

159158
## Support
160159

@@ -170,21 +169,20 @@ It was chosen to use embedded PG instead of H2 for unit tests since H2 doesn't s
170169

171170
### Development Quick Start Guide
172171

173-
To start the application locally, the following quick steps (all commands are executed from repository root directory)
172+
To start the application locally, follow these steps. Run all commands from the repository root directory.
174173

175-
1. Ensure that you have the following tools installed: Java 1.8, maven (check via `mvn -v`), docker-ce (check via `docker -v`), psql command line client
176-
(check via psql --version) or other tool that allows to connect to postgres DB.
174+
1. Ensure that you have the following tools installed: JDK 21, Maven (check with `mvn -v`), Docker (check with `docker -v`), and the `psql` command-line client (check with `psql --version`) or another tool that can connect to a PostgreSQL database.
177175
2. Run `mvn clean install` and make sure it completes successfully, resolve dependency issues if any.
178176
3. Create a new database in docker: `docker create --name postgres-webapi -p 8432:5432 -e POSTGRES_PASSWORD=ohdsi postgres:15.0-alpine`.
179177
4. Start DB container: `docker start postgres-webapi`.
180-
Verify that you can connect via psql console (`PGPASSWORD='ohdsi' psql -d postgresql://localhost:8432/?user=postgres`).
181-
5. If your default java version is too high (e.g. 17), set JAVA_HOME to point to 1.8 installaction, for example `export JAVA_HOME=/usr/lib/jvm/zulu8-ca-amd64`
182-
6. Start WebAPI `mvn clean install spring-boot:run -Dmaven.test.skip=true -P webapi-postgresql -s src/dev/settings.xml -f pom.xml`
178+
Verify that you can connect through the `psql` console (`PGPASSWORD='ohdsi' psql -d postgresql://localhost:8432/?user=postgres`).
179+
5. Ensure that `JAVA_HOME` points to a JDK 21 installation.
180+
6. Start WebAPI: `mvn clean install spring-boot:run -Dmaven.test.skip=true -P webapi-postgresql -s src/dev/settings.xml -f pom.xml`
183181
7. Log in with the username of your liking
184-
8. Grant this newly created user admin privileges by running the following sql `INSERT INTO sec_user_role (user_id, role_id, origin) VALUES (1000, 2, 'SYSTEM');`
182+
8. Grant this newly created user administrative privileges by running the following SQL: `INSERT INTO sec_user_role (user_id, role_id, origin) VALUES (1000, 2, 'SYSTEM');`
185183
and log in again.
186184

187-
At this point you have the application running and admin account operational. To actually use it, additional steps are required to set up privileges
185+
At this point, the application is running and an administrative account is operational. To use it, additional steps are required to set up privileges
188186
and at least one CDM database. They are covered in the respective documentation sections.
189187

190188
## License

0 commit comments

Comments
 (0)