Ad Hoc Analysis - openmrs/openmrs-module-reportingrest GitHub Wiki

Table of Contents

• adhocquery
• adhocdataset

adhocquery

Used for evaluating a list of queries +/- columns (that refer to definition libraries) on the fly.

For example this can dynamically fetch a table of data about patients of interest.

Currently only Patient data sets are supported.

POST .../adhocquery

Evaluates an AdHocDataSet which you pass as the POST body. The default representation of this resource will be the complete data set that you're evaluating.

Example response:

{
  "uuid": "f431ae07-85a6-4153-b148-dbbeeb89d30e",
  "metadata": {
    "columns": [
      {
        "datatype": "java.lang.Object",
        "name": "Given Name",
        "label": "Given Name"
      },
      {
        "datatype": "java.lang.Object",
        "name": "Family Name",
        "label": "Family Name"
      }
    ]
  },
  "rows": [
    {
      "Given Name": "Horatio",
      "Family Name": "Hornblower"
    },
    {
      "Given Name": "Johnny",
      "Family Name": "Doe"
    },
    {
      "Given Name": "Collet",
      "Family Name": "Chebaskwony"
    }
  ],
  "definition": {
    "class": "org.openmrs.module.reporting.dataset.definition.PatientDataSetDefinition",
    "uuid": "f431ae07-85a6-4153-b148-dbbeeb89d30e",
    "name": null,
    "description": null,
    "parameters": [
      {
        "name": "startDate",
        "label": null,
        "type": "java.util.Date"
      },
      {
        "name": "endDate",
        "label": null,
        "type": "java.util.Date"
      }
    ],
    "links": [
      {
        "uri": "NEED-TO-CONFIGURE\/ws\/reporting\/v1\/reportingrest\/dataSetDefinition\/f431ae07-85a6-4153-b148-dbbeeb89d30e",
        "rel": "self"
      },
      {
        "uri": "NEED-TO-CONFIGURE\/ws\/reporting\/v1\/reportingrest\/dataSetDefinition\/f431ae07-85a6-4153-b148-dbbeeb89d30e?v=full",
        "rel": "full"
      }
    ],
    "resourceVersion": "1.8"
  },
  "links": [
    {
      "uri": "NEED-TO-CONFIGURE\/ws\/rest\/v1\/reportingrest\/dataSet\/f431ae07-85a6-4153-b148-dbbeeb89d30e",
      "rel": "self"
    }
  ],
  "resourceVersion": "1.8"
}

POST .../adhocquery?v=preview

Evaluates an AdHocDataSet which you pass as the POST body. The preview representation of this resource will evaluate all of the row filters, but it will only fetch column values for the first 10 rows.

Example response:

{
  "uuid": "c98e92aa-97c3-4971-92ce-2aa6fe2ca961",
  "metadata": {
    "columns": [
      {
        "datatype": "java.lang.Object",
        "name": "(1) Given Name",
        "label": "(1) Given Name"
      },
      {
        "datatype": "java.lang.Object",
        "name": "(2) Family Name",
        "label": "(2) Family Name"
      }
    ]
  },
  "rows": [
    {
      "(1) Given Name": "Horatio",
      "(2) Family Name": "Hornblower"
    },
    {
      "(1) Given Name": "Johnny",
      "(2) Family Name": "Doe"
    },
    {
      "(1) Given Name": "Collet",
      "(2) Family Name": "Chebaskwony"
    }
  ],
  "definition": {
    "class": "org.openmrs.module.reporting.dataset.definition.PatientDataSetDefinition",
    "uuid": "c98e92aa-97c3-4971-92ce-2aa6fe2ca961",
    "name": null,
    "description": null,
    "parameters": [
      {
        "name": "startDate",
        "label": null,
        "type": "java.util.Date"
      },
      {
        "name": "endDate",
        "label": null,
        "type": "java.util.Date"
      }
    ],
    "links": [
      {
        "uri": "NEED-TO-CONFIGURE\/ws\/reporting\/v1\/reportingrest\/dataSetDefinition\/c98e92aa-97c3-4971-92ce-2aa6fe2ca961",
        "rel": "self"
      },
      {
        "uri": "NEED-TO-CONFIGURE\/ws\/reporting\/v1\/reportingrest\/dataSetDefinition\/c98e92aa-97c3-4971-92ce-2aa6fe2ca961?v=full",
        "rel": "full"
      }
    ],
    "resourceVersion": "1.8"
  },
  "links": [
    {
      "uri": "NEED-TO-CONFIGURE\/ws\/rest\/v1\/reportingrest\/dataSet\/c98e92aa-97c3-4971-92ce-2aa6fe2ca961",
      "rel": "self"
    }
  ],
  "resourceVersion": "1.8",
  "allRows": {
    "empty": false,
    "size": 3,
    "memberIds": [
      2,
      6,
      7
    ]
  }
}

POST .../adhocquery?v=rowFilters

Evaluates the row filters of an AdHocDataSet which you pass as the POST body, and gives you the results of each individual row filter, as well as the combined filter result.

Example response:

{
  "result": {
    "empty": false,
    "size": 3,
    "memberIds": [
      2,
      6,
      7
    ]
  },
  "individualResults": [
    {
      "empty": false,
      "size": 2,
      "memberIds": [
        2,
        6
      ]
    },
    {
      "empty": false,
      "size": 1,
      "memberIds": [
        7
      ]
    },
    {
      "empty": false,
      "size": 2,
      "memberIds": [
        2,
        7
      ]
    }
  ]
}  

adhocdataset

Used to save an ad hoc query as a DataSetDefinition for use elsewhere in the Reporting module.

POST .../adhocdataset

Saves the AdHocDataSet which you pass as the POST body as a DataSetDefinition.

DELETE .../adhocdataset/:uuid?purge=true

Deletes the previously-saved dataset with the given :uuid forever.

AdHocDataSet format

The format that you POST to the ad-hoc resources should be JSON with the following fields:

• type: this is required to be org.openmrs.module.reporting.dataset.definition.PatientDataSetDefinition. (Eventually this will support row-per-object datasets for other domain object as well.)
• name: what to call this data set (required when saving, not used when evaluating)
• parameters: an array of parameter values that will be passed to individual row and column queries where possible, if they match by name. Elements should have:
  • name: parameter name
  • type: a java classname
  • value: parameter value
• rowFilters: an array of one or more queries that should determine the rows of this dataset. Elements should have:
  • type: must be org.openmrs.module.reporting.cohort.definition.CohortDefinition at present
  • key: used to look up this row filter in a definition library
  • parameterValues: (optional) object
• customRowFilterCombination: By default the results of all the individual rowFilters will be intersected together to determine the rows of this dataset. You can combine the individual row filters in a different way by specifying this optional field, as a boolean algebra expression referring to the individual row filters by their 1-based index.
  • Example: 1 or (2 and not 3)
• columns: an array of column definitions. Elements should have
  • name: label to use in the output
  • type: must be org.openmrs.module.reporting.data.patient.definition.PatientDataDefinition at present
  • key: used to look up the calculation for this column in a definition library

Example POST body:

{
  "type": "org.openmrs.module.reporting.dataset.definition.PatientDataSetDefinition",
  "parameters": [
    {
      "name": "startDate",
      "type": "java.util.Date",
      "value": "2008-08-01"
    },
    {
      "name": "endDate",
      "type": "java.util.Date",
      "value": "2008-08-31"
    }
  ],
  "columns": [
    {
      "type": "org.openmrs.module.reporting.data.patient.definition.PatientDataDefinition",
      "name": "Given Name",
      "key": "reporting.library.patientDataDefinition.builtIn.preferredName.givenName"
    },
    {
      "type": "org.openmrs.module.reporting.data.patient.definition.PatientDataDefinition",
      "name": "Family Name",
      "key": "reporting.library.patientDataDefinition.builtIn.preferredName.familyName"
    }
  ],
  "customRowFilterCombination": "1 OR 2 OR 3",
  "rowFilters": [
    {
      "type": "org.openmrs.module.reporting.cohort.definition.CohortDefinition",
      "key": "reporting.library.cohortDefinition.builtIn.males"
    },
    {
      "type": "org.openmrs.module.reporting.cohort.definition.CohortDefinition",
      "key": "reporting.library.cohortDefinition.builtIn.anyEncounterDuringPeriod"
    },
    {
      "type": "org.openmrs.module.reporting.cohort.definition.CohortDefinition",
      "key": "reporting.library.cohortDefinition.builtIn.atLeastAgeOnDate",
      "parameterValues": {
        "minAge": 15,
        "effectiveDate": "2014-01-01"
      }
    }
  ]
}