Versions Compared

Old Version 8

changes.mady.by.user Joaquin Blaya

Saved on

compared with

New Version 9

changes.mady.by.user Darius Jazayeri

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

What this module does

Exposes the reporting module's functionality via REST web services

Documentation / How-To

Modules Required

  1. Reporting
  2. REST web services

...

About

The Reporting REST module lets you do reporting queries against your OpenMRS database, via REST web services. For example you can search for patients matching some criteria, or get a table of data for a given set of patients.

This module exposes the functionality in the Reporting Module, so you should look to that module's documentation for details of the available queries and dataset definitions.

Source code: https://github.com/openmrs/openmrs-module-reportingrest

General Usage

This module requires both the Reporting and REST Web Services modules to be installed.

General conventions, including authentication are documented at REST Web Services API For Clients.

REST Resources

cohortDefinition

Represents saved user-defined cohort definitions.

GET .../ws/rest/v1/reportingrest/cohortDefinitionFetches all saved CohortDefinitions
GET .../ws/rest/v1/reportingrest/cohortDefinition/{UUID}Fetches one saved CohortDefinition
POST .../ws/rest/v1/reportingrest/cohortDefinition/{UUID}

Updates one saved CohortDefinition.

Supports modifying name and description, but not the underlying query definition.

DELETE .../ws/rest/v1/reportingrest/cohortDefinition/{UUID}

Deletes one specific saved CohortDefinition

Specify ?purge=true to do a hard delete

Example full representation:

Code Block
{
  "class": "org.openmrs.module.reporting.cohort.definition.AgeCohortDefinition",
  "uuid": "637ba7e2-8501-43cf-a2ba-d59c68f326b3",
  "name": "Adults",
  "description": "Patients at least 18 years old",
  "parameters": [],
  "links": [
    {
      "rel": "self",
      "uri": "http://127.0.0.1:8080/openmrs/ws/reporting/v1/reportingrest/cohortDefinition/637ba7e2-8501-43cf-a2ba-d59c68f326b3"
    }
  ],
  "resourceVersion": "1.8"
}

cohort

Lets you evaluate cohort definitions, either built-in, saved, or specified on the fly.

GET .../ws/rest/v1/reportingrest/cohort/{UUID}
GET .../ws/rest/v1/reportingrest/cohort/{definitionLibraryKey}

Evaluates a cohort definition. You may specify either the UUID of a saved user-defined cohort definition or the key of a cohort definition in a definition library.

You may pass parameters to the evaluation context either as query parameters, or as fields in a JSON body.

Response will include a "members" array that gives you the UUIDs of patients matching the query.

Examples:
GET .../ws/rest/v1/reportingrest/cohort/22c14ac5-9254-46b9-bff8-860a4eac2a38
GET .../ws/rest/v1/reportingrest/cohort/reporting.library.cohortDefinition.builtIn.atLeastAgeOnDate?minAge=15&effectiveDate=2017-01-01

Sample response:

Code Block
{
  "uuid": "reporting.library.cohortDefinition.builtIn.atLeastAgeOnDate",
  "definition": { /* ... */ },
  "members": [
    {
      "uuid": "5e1eac23-fd0a-4568-ac30-861692b14b56",
      "display": "",
      "links": [
        {
          "rel": "self",
          "uri": "http://qa-refapp.openmrs.org/openmrs/ws/rest/v1/patient/5e1eac23-fd0a-4568-ac30-861692b14b56"
        }
      ]
    }
  ]
}


definitionLibrary

Lets you see the built-in queries available in Definition Libraries.

GET .../ws/rest/v1/reportingrest/definitionlibrary?q=cohort

Lists Cohort Definitions from all definition libraries.

Sample response:

Code Block
{
  "results": [
    {
      "type": "org.openmrs.module.reporting.cohort.definition.AgeCohortDefinition",
      "key": "reporting.library.cohortDefinition.builtIn.atLeastAgeOnDate",
      "name": "reporting.library.cohortDefinition.builtIn.atLeastAgeOnDate.name",
      "description": "reporting.library.cohortDefinition.builtIn.atLeastAgeOnDate.description",
      "parameters": [
        {
          "name": "effectiveDate",
          "label": "reporting.parameter.effectiveDate",
          "type": "java.util.Date",
          "collectionType": null,
          "defaultValue": null,
          "required": true,
          "widgetConfiguration": null,
          "expression": "${effectiveDate}",
          "labelOrName": "reporting.parameter.effectiveDate",
          "widgetConfigurationAsString": ""
        },
        {
          "name": "minAge",
          "label": "reporting.parameter.minAgeInYears",
          "type": "java.lang.Integer",
          "collectionType": null,
          "defaultValue": null,
          "required": true,
          "widgetConfiguration": null,
          "expression": "${minAge}",
          "labelOrName": "reporting.parameter.minAgeInYears",
          "widgetConfigurationAsString": ""
        }
      ]
    },
    {
      "type": "org.openmrs.module.reporting.cohort.definition.GenderCohortDefinition",
      "key": "reporting.library.cohortDefinition.builtIn.females",
      "name": "reporting.library.cohortDefinition.builtIn.females.name",
      "description": "reporting.library.cohortDefinition.builtIn.females.description",
      "parameters": []
    },
    // etc
  ]
}
Warning

Text below here is older, and may not be accurate.

 

The Reporting REST module lets you do this:

...