Merge pull request #664 from OpenFn/openmrs-5

OpenMRS: Docs for v5

Author: taylordowns2000

adaptors/openmrs.md

@@ -4,19 +4,36 @@ title: OpenMRS Adaptor
 
 ## About OpenMRS
 
-[OpenMRS (Open Medical Record System)](https://openmrs.org/) is an open-source platform designed to manage electronic medical records (EMRs) in low-resource environments. It provides a framework that allows developers to extend its core functionality through custom modules and APIs.
+[OpenMRS (Open Medical Record System)](https://openmrs.org/) is an open-source
+platform designed to manage electronic medical records (EMRs) in low-resource
+environments. It provides a framework that allows developers to extend its core
+functionality through custom modules and APIs.
 
 ## Integration Options
 
-**1. Rest API:** OpenMRS offers a REST API that enables external applications to interact with its database and perform bulk operations. This option is ideal for applications requiring scheduled or bulk synchronization with OpenMRS. Refer to the OpenMRS REST API [documentation](https://wiki.openmrs.org/) for detailed guidelines on endpoints and payload formats.
+**1. Rest API:** OpenMRS offers a REST API that enables external applications to
+interact with its database and perform bulk operations. This option is ideal for
+applications requiring scheduled or bulk synchronization with OpenMRS. Refer to
+the OpenMRS REST API [documentation](https://wiki.openmrs.org/) for detailed
+guidelines on endpoints and payload formats.
 
-**2. Webhook:** OpenMRS does not natively support webhooks as a standard feature. However, the platform is highly extensible and allows for customization through its module system. More details can be found on the OpenMRS [documentation page​](https://wiki.openmrs.org/).
+**2. Webhook:** OpenMRS does not natively support webhooks as a standard
+feature. However, the platform is highly extensible and allows for customization
+through its module system. More details can be found on the OpenMRS
+[documentation page​](https://wiki.openmrs.org/).
 
 ## Authentication
 
-When integrating with OpenMRS via OpenFn, **Basic Authentication** is supported. See this adaptor's [Configuration docs](/adaptors/packages/openmrs-configuration-schema) for more on the required authentication parameters.
+When integrating with OpenMRS via OpenFn, **Basic Authentication** is supported.
 
-See platform docs on [managing credentials](documentation/manage-projects/manage-credentials) for how to configure a credential in OpenFn. If working locally or if using a Raw JSON credential type, then your configuration will look something like this:
+The `instanceUrl`, `username` an `password` properties are all required to
+access your OpenMRS instance.
+
+See [Managing Credentials](documentation/manage-projects/manage-credentials) to
+configure a credential in OpenFn.
+
+If working locally or if using a Raw JSON credential type, then your
+configuration will look something like this:
 
 ```
 {
@@ -26,15 +43,139 @@ See platform docs on [managing credentials](documentation/manage-projects/manage
 }
 ```
 
-### Helpful Links
+See this adaptor's
+[Configuration docs](/adaptors/packages/openmrs-configuration-schema) for more
+details.
 
-1. [OpenMRS Developer Guide](https://openmrs.atlassian.net/wiki/spaces/docs/pages/25476048/Developer+Guide)
-2. Community Forums: [OpenMRS Talk](https://talk.openmrs.org/)
+## API Basics
 
-### Implementation Examples
+There are three ways you can use the OpenMRS API, all available interchangeable
+in the same step in a workflow.
+
+Like other adaptors, the FHIR adaptor "returns" output by writing to
+`state.data`:
+
+```js
+get('patient/71075074-f02e-4270-89a3-f2dcda436f70');
+fn(state => {
+  console.log(state.data); // the downloaded patient is available here
+  return state;
+});
+```
+
+### REST API Operations
+
+The main namespace contains high-level helper functions, which are designed as
+the primary interface. These are designed to handle the most common use cases,
+like downloading OpenMRS resources. They will configure default values and
+handle some complications for you, like authorization and pagination.
+
+All requests generated by these operations are made against your instance URL
+plus `ws/rest/v1`.
+
+For a list of valid resource types, see the
+[OpenMRS REST API Docs](https://rest.openmrs.org/#openmrs-rest-api). These docs
+are a useful resource when using OpenMRS, as different resources have different
+usage rules.
+
+For example, to download all concepts:
+
+```js
+get('concept');
+// calls <instanceUrl>/ws/rest/v1/concept
+```
+
+Each resource in OpenMRS defines a number of query parameters. These can be
+passed as an options object as the second argument. For example, to set the
+[`source` parameter](https://rest.openmrs.org/#list-all-concepts) on the concept
+resource:
+
+```js
+get('concept', { source: 'SNOWMED' });
+// calls <instanceUrl>/ws/rest/v1/concept?source=SNOWMED
+```
+
+Most options are appended to the request URL as query parameters, so you can
+pass whatever parameters OpenMRS requires.
+
+The adaptor will download resources over multiple pages. Each individual request
+to OpenMRS will be logged, for debugging and optimization.
+
+Note that by default, the function imposes a download limit of 10,000 records.
+You can force all data to be downloaded by passing `max: Infinity`, like this:
+
+```js
+get('concept', { max: Infinity });
+```
 
-1. OpenFn Prototype for Médecins Sans Frontières (MSF) LIME Project - OpenMRS -> DHIS2 sync: [https://github.com/OpenFn/openfn-lime](https://github.com/OpenFn/openfn-lime)
+When paging, the adaptor will make multiple requests. By default each request
+will download a page of data according to the instance's configuration. To force
+a larger page size (and reduce the number of requests, pass `pageSize`)
 
+```js
+get('concept', { pageSize: 1000 });
+```
+
+To disable pagination and force a single request, set `limit`.
+
+You can page from a specific position by passing `startIndex`. This works with
+pagination and with `limit`.
+
+## HTTP Utility Functions
+
+The REST API operations are be opinionated, and in some cases can make too many
+assumptions about what you want to do.
+
+The operations in the `http` namespace are simpler, lower-level helpers and work
+more like curl or postman. They'll do exactly what you ask for them. They'll
+handle authorization for you but won't paginate or prepend anything to the
+requested path.
+
+To request a single page of concepts, you can do:
+
+```js
+http.get('ws/rest/v1/concept');
+```
+
+You can pass a query via the options object:
+
+```js
+http.get('ws/rest/v1/concept', {
+  query: {
+    limit: 1000,
+    source: 'SNOWMED',
+  },
+});
+```
 
+Using the http helpers, pagination must be implemented manually.
 
+The HTTP helpers write to things to your state object:
+
+- `state.data` is the response body returned by OpenMRS
+- `state.response` is the rest of the HTTP response (excluding the body),
+  including `statusCode`, `statusMessage` and `headers`.
+
+## FHIR Helpers
+
+The OpenMRS adaptor also provides a
+[FHIR helper API](https://docs.openfn.org/adaptors/packages/openmrs-docs#fhir),
+which allows you to make requests against FHIR endpoints and download FHIR data.
+
+```js
+fhir.get('Encounter', {
+  count: 100,
+  lastUpdated: 'ge2024-01-01T00:00:00Z',
+});
+```
+
+### Helpful Links
+
+1. [OpenMRS Developer Guide](https://openmrs.atlassian.net/wiki/spaces/docs/pages/25476048/Developer+Guide)
+2. Community Forums: [OpenMRS Talk](https://talk.openmrs.org/)
+
+### Implementation Examples
 
+1. OpenFn Prototype for Médecins Sans Frontières (MSF) LIME Project - OpenMRS ->
+   DHIS2 sync:
+   [https://github.com/OpenFn/openfn-lime](https://github.com/OpenFn/openfn-lime)