Reporting 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/cohortDefinition	Fetches 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:

{
  "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:

{
  "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:

{
  "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
  ]
}

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

The Reporting REST module lets you do this:

GET http://localhost:8018/openmrs18/ws/rest/v1/reportingrest/cohortdefinition -> lists all available cohort definitions
GET http://localhost:8018/openmrs18/ws/rest/v1/reportingrest/datasetdefinition -> lists all available data set definitions
GET http://localhost:8018/openmrs18/ws/rest/v1/reportingrest/uuid-of-cohort -> lists all patients of that cohort
GET http://localhost:8018/openmrs18/ws/rest/v1/reportingrest/dataset/c6f3a3cf-df0e-4733-9d9e-ff0c6cf9629f?cohort=f6f5a60e-72a9-4e7f-8f92-f95d4000ca2a -> evaluates a DSD against a cohort

And you get back this (this is an old description, it has changed since then, see below for examples):

     {
        "metadata": {
            "columns":[
                {"name":"OpenMRS Identification Number", "label":"OpenMRS Identification Number","datatype":"java.lang.String"},

                {"name":"gender","label":"gender","datatype":"java.lang.String"},

                {"name":"age","label":"age","datatype":"java.lang.Integer"}
            ]},

        "rows":[
            {"OpenMRS Identification Number":"101-6","age":70,"gender":"M"},
            {"OpenMRS Identification Number":"100-8","age":37,"gender":"M"}
        ],
        ...
    }

Here are a few examples with their respective outputs

GET http://localhost:8080/midoctor/ws/rest/v1/reportingrest/cohortdefinition

{ "results" : [ { "display" : "Todos los pacientes - ",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/72f39b6d-2ad2-4b85-8cc4-88bd292d9fb9"
            } ],
        "uuid" : "72f39b6d-2ad2-4b85-8cc4-88bd292d9fb9"
      },
      { "display" : "Pacientes que escogieron track de Alimentacion - ",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/f99c6456-1673-4fe2-b91d-4d8f4a8541e3"
            } ],
        "uuid" : "f99c6456-1673-4fe2-b91d-4d8f4a8541e3"
      },
      { "display" : "Pacientes ingresados el ultimo dia - Pacientes ingresados el ultimo dia",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/6b2511be-b66e-4980-bf84-ae0817997bce"
            } ],
        "uuid" : "6b2511be-b66e-4980-bf84-ae0817997bce"
      },
      { "display" : "Ningun paciente - ",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/7c45ebbc-2b5d-47b7-bc08-378c598ec904"
            } ],
        "uuid" : "7c45ebbc-2b5d-47b7-bc08-378c598ec904"
      },
      { "display" : "SMS pacientes que pidieron ayuda - ",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/3c0c4052-3d95-4fe0-9e45-474629118eb0"
            } ],
        "uuid" : "3c0c4052-3d95-4fe0-9e45-474629118eb0"
      },
      { "display" : "SMS paciente que recibieron ayuda - ",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/ea359508-84f5-42e0-8128-8ab9bf3e943f"
            } ],
        "uuid" : "ea359508-84f5-42e0-8128-8ab9bf3e943f"
      },
      { "display" : "Pacientes que quieren ayuda con SMS - Pacientes que quieren ayuda con SMS y no la han recibido",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/909989f0-dae7-494c-bd55-e428a7bd5d99"
            } ],
        "uuid" : "909989f0-dae7-494c-bd55-e428a7bd5d99"
      },
      { "display" : "Pacientes que escogieron track de Actividad Fisica - ",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/09cacab3-31c4-4926-94a9-606eeab0fed2"
            } ],
        "uuid" : "09cacab3-31c4-4926-94a9-606eeab0fed2"
      },
      { "display" : "Llamadas que no son la persona - ",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/857658df-930e-453e-8458-bcf421990252"
            } ],
        "uuid" : "857658df-930e-453e-8458-bcf421990252"
      },
      { "display" : "Pacientes que no asistiran a su cita - ",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/a0ea0a00-0d8c-4502-9e82-fd345d4f85e3"
            } ],
        "uuid" : "a0ea0a00-0d8c-4502-9e82-fd345d4f85e3"
      },
      { "display" : "Meds No tiene medicamentos - ",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/f2747a05-1790-428b-ae2d-f71eafff4da0"
            } ],
        "uuid" : "f2747a05-1790-428b-ae2d-f71eafff4da0"
      },
      { "display" : "Meds llamada realizada efectiva - ",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/41bda2f2-8738-4f03-9a5e-c2543a6be91f"
            } ],
        "uuid" : "41bda2f2-8738-4f03-9a5e-c2543a6be91f"
      },
      { "display" : "Pacientes que no retiraron medicamentos - ",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/5fe08129-925d-49e9-be96-e6f751b8b7eb"
            } ],
        "uuid" : "5fe08129-925d-49e9-be96-e6f751b8b7eb"
      },
      { "display" : "Meds dudas sobre meds - ",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/fac4fe52-b853-42fa-80ea-d220141e7246"
            } ],
        "uuid" : "fac4fe52-b853-42fa-80ea-d220141e7246"
      },
      { "display" : "Pacientes con dudas sobre medicamentos - ",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/cdee9b23-7205-46c3-9a22-7564f6f73def"
            } ],
        "uuid" : "cdee9b23-7205-46c3-9a22-7564f6f73def"
      },
      { "display" : "Meds olvidado de tomar - ",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/47cc0d48-80c4-4df6-8f56-764e11195681"
            } ],
        "uuid" : "47cc0d48-80c4-4df6-8f56-764e11195681"
      },
      { "display" : "Pacientes con problemas de adherencia - ",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/059a109c-4e07-44d5-afb6-27428caee6d6"
            } ],
        "uuid" : "059a109c-4e07-44d5-afb6-27428caee6d6"
      }
    ] }

GET http://localhost:8080/midoctor/ws/rest/v1/reportingrest/cohort/cdee9b23-7205-46c3-9a22-7564f6f73def(cohort with no patients)

{ "definition" : { "description" : "",
      "links" : [ { "rel" : "self",
            "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/cdee9b23-7205-46c3-9a22-7564f6f73def"
          },
          { "rel" : "full",
            "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/cdee9b23-7205-46c3-9a22-7564f6f73def?v=full"
          }
        ],
      "name" : "Pacientes con dudas sobre medicamentos",
      "parameters" : [  ],
      "resourceVersion" : "1.8",
      "uuid" : "cdee9b23-7205-46c3-9a22-7564f6f73def"
    },
  "links" : [ { "rel" : "self",
        "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohort/cdee9b23-7205-46c3-9a22-7564f6f73def"
      } ],
  "members" : [  ],
  "uuid" : "cdee9b23-7205-46c3-9a22-7564f6f73def"
}

GET http://localhost:8080/midoctor/ws/rest/v1/reportingrest/cohort/857658df-930e-453e-8458-bcf421990252 (cohort with 4 patients)

{ "definition" : { "description" : "",
      "links" : [ { "rel" : "self",
            "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/857658df-930e-453e-8458-bcf421990252"
          },
          { "rel" : "full",
            "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohortDefinition/857658df-930e-453e-8458-bcf421990252?v=full"
          }
        ],
      "name" : "Llamadas que no son la persona",
      "parameters" : [  ],
      "resourceVersion" : "1.8",
      "uuid" : "857658df-930e-453e-8458-bcf421990252"
    },
  "links" : [ { "rel" : "self",
        "uri" : "NEED-TO-CONFIGURE/ws/reporting/cohort/857658df-930e-453e-8458-bcf421990252"
      } ],
  "members" : [ { "display" : "11111222-3 - Nicolas Fuentes",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/rest/v1/patient/eeef3ef2-6307-43de-a016-9d8661efd2bb"
            } ],
        "uuid" : "eeef3ef2-6307-43de-a016-9d8661efd2bb"
      },
      { "display" : "16859632-7 - Prueba Prueba",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/rest/v1/patient/ffc49df0-3d83-4df8-85ab-7b9cf7d8841a"
            } ],
        "uuid" : "ffc49df0-3d83-4df8-85ab-7b9cf7d8841a"
      },
      { "display" : "844543-2 - Maria Paredes",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/rest/v1/patient/6603aa11-b3ad-46fc-aa16-8b7b1d021467"
            } ],
        "uuid" : "6603aa11-b3ad-46fc-aa16-8b7b1d021467"
      },
      { "display" : "1213-2 - Test asdsd",
        "links" : [ { "rel" : "self",
              "uri" : "NEED-TO-CONFIGURE/ws/rest/v1/patient/1f83093d-3238-4a70-aacb-069c13caaed5"
            } ],
        "uuid" : "1f83093d-3238-4a70-aacb-069c13caaed5"
      }
    ],
  "uuid" : "857658df-930e-453e-8458-bcf421990252"
}

Downloads

http://modules.openmrs.org/modules/view.jsp?module=reportingrest

Screenshots

Release Notes

Developer Notes

In 1.3 you could build the module from the code, but it would give the following error, during compiling. Darius mentioned that you should ignore all com.mchange. error messages.

ERROR - SchemaExport.execute(202) |2013-01-29 17:01:32,694| schema export unsuccessful
java.sql.SQLException: com.mchange.v2.c3p0.PoolBackedDataSource@29d9b607