openmrs@5.0.1

create(path, data)

destroy(path, [options])

get(path, [options])

update(path, data)

upsert(path, data, params)

This adaptor exports the following namespaced functions:

http.delete(path, [options])

http.get(path, [options])

http.post(path, data, [options])

http.request(method, path, [options])

fhir.get(path, query, [callback])

Functions

create

create(path, data) ⇒ Operation

Create a resource. For a list of valid resources, see OpenMRS Docs

Param	Type	Description
path	string	Path to resource (excluding /ws/rest/v1/)
data	object	Resource definition

This operation writes the following keys to state:

State Key	Description
data	The newly created resource, as returned by OpenMRS

Example: Create a person (see OpenMRS API)

create("person", {
  names: [
    {
      givenName: "Mohit",
      familyName: "Kumar",
    },
  ],
  gender: "M",
  birthdate: "1997-09-02",
  addresses: [
    {
      address1: "30, Vivekananda Layout, Munnekolal,Marathahalli",
      cityVillage: "Bengaluru",
      country: "India",
      postalCode: "560037",
    },
  ],
});

Example: Create an encounter (see OpenMRS API)

create("encounter", {
  encounterDatetime: '2023-05-25T06:08:25.000+0000',
  patient: '1fdaa696-e759-4a7d-a066-f1ae557c151b',
  encounterType: 'dd528487-82a5-4082-9c72-ed246bd49591',
  location: 'ba685651-ed3b-4e63-9b35-78893060758a',
  encounterProviders: [],
  visit: {
    patient: '1fdaa696-e759-4a7d-a066-f1ae557c151b',
    visitType: '7b0f5697-27e3-40c4-8bae-f4049abfb4ed',
    startDatetime: '2023-05-25T06:08:25.000+0000',
    stopDatetime: '2023-05-25T06:09:25.000+0000',
  },
})

Example: Create a patient (see OpenMRS API)

create("patient", {
  identifiers: [
    {
      identifier: '4023287',
      identifierType: '05a29f94-c0ed-11e2-94be-8c13b969e334',
      preferred: true,
    },
  ],
  person: {
    gender: 'M',
    age: 42,
    birthdate: '1970-01-01T00:00:00.000+0100',
    birthdateEstimated: false,
    names: [
      {
        givenName: 'Doe',
        familyName: 'John',
      },
    ],
  },
})
  

Example: Create a patientIdentifier subresource (see OpenMRS API)

create("patient/b52ec6f9-0e26-424c-a4a1-c64f9d571eb3/identifier", { 
 "identifier" : "111:CLINIC1",
 "identifierType" : "a5d38e09-efcb-4d91-a526-50ce1ba5011a",
 "location" : "8d6c993e-c2cc-11de-8d13-0010c6dffd0f",
 "preferred" : true
})
}

---

destroy

destroy(path, [options]) ⇒ Operation

Delete a resource. Must include a UUID in the path. Throws an error if the resource does not exist.

Param	Type	Default	Description
path	string		Path to resource (excluding /ws/rest/v1/)
[options]	object	{}
[options.purge]	object	false	The resource will be voided/retired unless true

This operation writes the following keys to state:

State Key	Description
data	The response from OpenMRS

Example: Void a patient

destroy("patient/12346");

Example: Purge a patient

destroy("patient/12346", {
  purge: true
});

---

get

get(path, [options]) ⇒ Operation

Fetch resources from OpenMRS. Use this to fetch a single resource, or to search a list.

Options will be appended as query parameters to the request URL, refer to OpenMRS Docs for details.

Pagination is handled automatically by default (maximum 10k items). Set max to paginate with a higher limit, or pass limit to force a single request, as per the OpenMRS Rest API.

Param	Type	Default	Description
path	string		Path to resource (excluding /ws/rest/v1/)
[options]	GetOptions	{}	Includes max, query, and extra query parameters

This operation writes the following keys to state:

State Key	Description
data	An array of result objects

Example: List all concepts (up to a maximum of 10k items, with pagination)

get("concept")

Example: List all concepts (with pagination)

get("concept", { query: "brian", max: Infinity })

Example: Search up to 100 patients by name (allowing pagination) (see OpenMRS API)

get("patient", { query: "brian", max: 100 })

Example: Fetch patient by UUID (returns an array of 1 item)

get("patient/abc")

Example: Fetch patient by UUID (returns an object of patient data)

get("patient/abc", { singleton: true })

Example: Search up to 10 patients by name (in a single request without pagination) (see OpenMRS API)

get("patient", { query: "brian", limit: 10 })

Example: List allergy subresources

get("patient/abc/allergy")

Example: Get allergy subresource by its UUID and parent patient UUID

get("patient/abc/allergy/xyz")

---

update

update(path, data) ⇒ Operation

Update a resource. Only properties included in the data will be affected. For a list of valid resources and for update rules, see the Update sections of the OpenMRS Docs

Param	Type	Description
path	string	Path to resource (excluding /ws/rest/v1/)
data	Object	Resource properties to update

This operation writes the following keys to state:

State Key	Description
data	The full updated resource, as returned by OpenMRS

Example: Update a person (see OpenMRS API)

update('person/3cad37ad-984d-4c65-a019-3eb120c9c373', {
  'gender': 'M',
  'birthdate':'1997-01-13'
})

---

upsert

upsert(path, data, params) ⇒ Operation

Update a resource if it already exists, or otherwise create a new one.

Upsert will first make a request for the target item (using the path and params) to see if it exists, and then issue a second create or update request. If the query request returns multiple items, the upsert will throw an error.

Param	Type	Description
path	string	Path to resource (excluding /ws/rest/v1/)
data	Object	The resource data
params	Object	Query parameters to append to the initial query

This operation writes the following keys to state:

State Key	Description
data	The created/updated resource, as returned by OpenMRS

Example: Upsert a patient (see OpenMRS API)

upsert("patient/a5d38e09-efcb-4d91-a526-50ce1ba5011a", {
  identifiers: [
    {
      identifier: '4023287',
      identifierType: '05a29f94-c0ed-11e2-94be-8c13b969e334',
      preferred: true,
    },
  ],
  person: {
    gender: 'M',
    age: 42,
    birthdate: '1970-01-01T00:00:00.000+0100',
    birthdateEstimated: false,
    names: [
      {
        givenName: 'Doe',
        familyName: 'John',
      },
    ],
  },
})

Example: Upsert a patient using a query to identify the record

upsert("patient", $.data, { q: "Lamine Yamal" })

---

http

These functions belong to the http namespace.

http.delete

delete(path, [options]) ⇒ operation

Make a DELETE request to an OpenMRS endpoint

Param	Type	Default	Description
path	string		path to resource
[options]	HTTPRequestOptions	{}	An object containing query params and headers for the request

This operation writes the following keys to state:

State Key	Description
data	The response body (as JSON)
response	The HTTP response from the OpenMRS server (excluding the body)
references	An array containing all previous data objects

Example: Delete a resource

http.delete(
 "/ws/rest/v1/patient/abc/"
)

---

http.get

get(path, [options]) ⇒ operation

Make a GET request to any OpenMRS endpoint. Unlike the main get(), this does not append anything to the path you provide.

Param	Type	Default	Description
path	string		path to resource
[options]	HTTPRequestOptions	{}	An object containing query params and headers for the request

This operation writes the following keys to state:

State Key	Description
data	The response body (as JSON)
response	The HTTP response from the OpenMRS server (excluding the body)
references	An array containing all previous data objects

Example: GET a resource with a query

http.get(
 "/ws/rest/v1/patient",
 {
   query: {
     limit: 1
   }
 }
)

Example: Don't throw if OpenMRS returns a 404 error code

http.get(
 "/ws/rest/v1/patient",
 {
   errors: { 404: false }
 }
)

---

http.post

post(path, data, [options]) ⇒ operation

Make a POST request to an OpenMRS endpoint

Param	Type	Default	Description
path	string		path to resource
data	any		the payload
[options]	HTTPRequestOptions	{}	An object containing query params and headers for the request

This operation writes the following keys to state:

State Key	Description
data	The response body (as JSON)
response	The HTTP response from the OpenMRS server (excluding the body)
references	An array containing all previous data objects

Example: Post with a JSON payload

http.post(
 "/ws/rest/v1/patient",
 {
     "person": {
     "gender":"M",
     "age":47,
     "birthdate":"1970-01-01T00:00:00.000+0100",
     "names":[
       {
         "givenName":"Jon",
         "familyName":"Snow"
       }
     ],
   }
   }
)

---

http.request

request(method, path, [options]) ⇒ Operation

Make a HTTP request to any OpenMRS endpoint

Param	Type	Default	Description
method	string		HTTP method to use
path	string		Path to resource
[options]	HTTPRequestOptions	{}	An object containing query, headers, and body for the request

This operation writes the following keys to state:

State Key	Description
data	The response body (as JSON)
response	The HTTP response from the OpenMRS server (excluding the body)
references	An array containing all previous data objects

Example: GET request with a query parameters

http.request("GET",
  "/ws/rest/v1/patient/d3f7e1a8-0114-4de6-914b-41a11fc8a1a8", {
   query:{
      limit: 1,
      startIndex: 20
   },
});

---

fhir

These functions belong to the fhir namespace.

fhir.get

get(path, query, [callback]) ⇒ Operation

Make a get request to any FHIR endpoint in OpenMRS

Param	Type	Description
path	string	Path to resource
query	FhirParameters	Request parameters
[callback]	function	Optional callback to handle the response

This operation writes the following keys to state:

State Key	Description
data	The response body (as JSON)
response	The HTTP response from the OpenMRS server (excluding the body)
references	An array containing all previous data objects

Example: Get encounters based on lastUpdated field

fhir.get('Encounter', { count: 100, lastUpdated: 'ge2024-01-01T00:00:00Z' })

---

Interfaces

FhirParameters

OpenMRS FHIR requests parameters options. This combines FHIR search parameters, resource-specific parameters, and pagination options.

Properties

Name	Type	Description
count	string	Number of results to return (_count in FHIR)
include	string	Resources to include in the response (_include in FHIR)
revinclude	string	Reverse includes to include in the response (_revinclude in FHIR)
summary	string	Summary mode for the response (_summary in FHIR)
total	string	Whether to include a total count of matching resources (_total in FHIR)
elements	string	List of elements to include in the response (_elements in FHIR)
contained	string	Whether to include contained resources (_contained in FHIR)
containedType	string	Type of contained resources (_containedType in FHIR)
id	string	Logical ID of the resource to filter on (_id in FHIR)
lastUpdated	string	Timestamp to filter resources last updated after this date (_lastUpdated in FHIR)
tag	string	Tag to filter resources by (_tag in FHIR)
profile	string	Profile URL to filter resources by (_profile in FHIR)
security	string	Security labels to filter resources by (_security in FHIR)
text	string	Text search on narrative content (_text in FHIR)
content	string	Full-text search on resource content (_content in FHIR)
list	string	Search resources included in a particular list (_list in FHIR)
has	string	Perform search based on reference chains (_has in FHIR)
getPagesOffset	string	Offset for pagination, used to skip a number of results (_getpagesoffset in OpenMRS)
getPages	string	Get specific pages of resources (_getpages in OpenMRS)
bundleType	string	Type of bundle to return (e.g., searchset, batch, history) (_bundleType in FHIR)

---

GetOptions

Options to append to the request. Unless otherwise specified, options are appended to the URL as query parameters - see the OpenMRS Docs for all supported parameters.

Properties

Name	Type	Default	Description
[query]	string		(OpenFn only) Query string. Maps to q in OpenMRS.
[max]	number	10000	(OpenFn only) Restrict the maximum number of retrieved records. May be fetched in several pages. Not used if limit is set.
[pageSize]	number	1000	(OpenFn only) Limits the size of each page of data. Not used if limit is set.
[singleton]	boolean		(OpenFn only) If set to true, only the first result will be returned. Useful for "get by id" APIs.

---

HTTPRequestOptions

Options object

Properties

Name	Type	Default	Description
query	object		An object of query parameters to be encoded into the URL
headers	object		An object of all request headers
body	object		The request body (as JSON)
errors	object | boolean		Pass false to not throw on errors. Pass a map of errorCodes: error messages, ie, { 404: 'Resource not found' }, or false to suppress errors for a specific code.
[parseAs]	string	"'json'"	The response format to parse (e.g., 'json', 'text', or 'stream')

---