@dhis2/analytics 26.4.1 → 26.6.0

package/build/es/__fixtures__/json/api/analytics/outlierDetection.json

@@ -0,0 +1,213 @@
+{
+  "headers": [
+    {
+      "name": "dxname",
+      "column": "Data name",
+      "valueType": "TEXT",
+      "type": "java.lang.String",
+      "hidden": false,
+      "meta": false
+    },
+    {
+      "name": "ouname",
+      "column": "Organisation unit name",
+      "valueType": "TEXT",
+      "type": "java.lang.String",
+      "hidden": false,
+      "meta": false
+    },
+    {
+      "name": "value",
+      "column": "Value",
+      "valueType": "NUMBER",
+      "type": "java.lang.Double",
+      "hidden": false,
+      "meta": false
+    },
+    {
+      "name": "absdev",
+      "column": "Absolute deviation",
+      "valueType": "NUMBER",
+      "type": "java.lang.Double",
+      "hidden": false,
+      "meta": false
+    },
+    {
+      "name": "modifiedzscore",
+      "column": "Modified zScore",
+      "valueType": "NUMBER",
+      "type": "java.lang.Double",
+      "hidden": false,
+      "meta": false
+    },
+    {
+      "name": "median",
+      "column": "Median",
+      "valueType": "NUMBER",
+      "type": "java.lang.Double",
+      "hidden": false,
+      "meta": false
+    },
+    {
+      "name": "lowerbound",
+      "column": "Lower boundary",
+      "valueType": "NUMBER",
+      "type": "java.lang.Double",
+      "hidden": false,
+      "meta": false
+    },
+    {
+      "name": "upperbound",
+      "column": "Upper boundary",
+      "valueType": "NUMBER",
+      "type": "java.lang.Double",
+      "hidden": false,
+      "meta": false
+    }
+  ],
+  "metaData": {
+    "maxResults": 100,
+    "count": 13,
+    "orderBy": "mean_abs_dev",
+    "threshold": 3.0,
+    "algorithm": "MOD_Z_SCORE"
+  },
+  "rowContext": {
+
+  },
+  "rows": [
+    [
+      "ANC 2nd visit",
+      "UMC (Urban Centre) Hospital",
+      "1669.0",
+      "920.0",
+      "3.902767295597484",
+      "749.0",
+      "-290.93013894085743",
+      "1788.9301389408574"
+    ],
+    [
+      "ANC 1st visit",
+      "Charlotte CHP",
+      "49.0",
+      "39.0",
+      "7.515857142857143",
+      "10.0",
+      "-23.948490393535913",
+      "43.94849039353591"
+    ],
+    [
+      "ANC 2nd visit",
+      "Charlotte CHP",
+      "40.0",
+      "33.0",
+      "22.258499999999998",
+      "7.0",
+      "-30.86489139031037",
+      "44.86489139031037"
+    ],
+    [
+      "ANC 2nd visit",
+      "Wilberforce CHC",
+      "56.0",
+      "24.5",
+      "3.004590909090909",
+      "31.5",
+      "-1.3890179239210454",
+      "64.38901792392105"
+    ],
+    [
+      "ANC 1st visit",
+      "Deep Eye water MCHP",
+      "40.0",
+      "16.0",
+      "3.5973333333333333",
+      "24.0",
+      "4.850913859925324",
+      "43.14908614007467"
+    ],
+    [
+      "ANC 2nd visit",
+      "Lion for Lion Clinic",
+      "30.0",
+      "16.0",
+      "3.5973333333333333",
+      "14.0",
+      "-5.620896815302167",
+      "33.62089681530217"
+    ],
+    [
+      "ANC 2nd visit",
+      "Deep Eye water MCHP",
+      "33.0",
+      "14.5",
+      "3.9121",
+      "18.5",
+      "-3.4245866551686603",
+      "40.42458665516866"
+    ],
+    [
+      "ANC 2nd visit",
+      "Blessed Mokaka East Clinic",
+      "2.0",
+      "13.0",
+      "4.38425",
+      "15.0",
+      "-3.417043736713012",
+      "33.41704373671301"
+    ],
+    [
+      "ANC 2nd visit",
+      "Malambay CHP",
+      "15.0",
+      "12.0",
+      "5.396",
+      "3.0",
+      "-13.770509831248425",
+      "19.770509831248425"
+    ],
+    [
+      "ANC 2nd visit",
+      "Wellbody MCHP",
+      "20.0",
+      "10.0",
+      "3.3725",
+      "10.0",
+      "-10.999999999999996",
+      "30.999999999999996"
+    ],
+    [
+      "ANC 1st visit",
+      "Blessed Mokaka East Clinic",
+      "26.0",
+      "10.0",
+      "4.496666666666667",
+      "16.0",
+      "1.6734512181055958",
+      "30.326548781894402"
+    ],
+    [
+      "ANC 1st visit",
+      "Murray Town CHC",
+      "18.0",
+      "9.0",
+      "6.0705",
+      "9.0",
+      "-2.43571205496543",
+      "20.43571205496543"
+    ],
+    [
+      "ANC 2nd visit",
+      "Thompson Bay MCHP",
+      "11.0",
+      "6.0",
+      "4.047",
+      "5.0",
+      "-2.038266127580332",
+      "12.038266127580332"
+    ]
+  ],
+  "headerWidth": 8,
+  "width": 8,
+  "height": 13
+}

package/build/es/api/analytics/Analytics.js

@@ -6,12 +6,15 @@ import AnalyticsEnrollments from './AnalyticsEnrollments.js';
 import AnalyticsEvents from './AnalyticsEvents.js';
 import AnalyticsRequest from './AnalyticsRequest.js';
 import AnalyticsResponse from './AnalyticsResponse.js';
+import AnalyticsTrackedEntities from './AnalyticsTrackedEntities.js';
 
 /**
  * @description
  * Analytics class used to request analytics data from Web API.
  *
  * @requires analytics.AnalyticsAggregate
+ * @requires analytics.AnalyticsTrackedEntities
+ * @requires analytics.AnalyticsEnrollments
  * @requires analytics.AnalyticsEvents
  * @requires analytics.AnalyticsRequest
  * @requires analytics.AnalyticsResponse
@@ -31,6 +34,7 @@ import AnalyticsResponse from './AnalyticsResponse.js';
 class Analytics {
   /**
    * @param {!module:analytics.AnalyticsAggregate} analyticsAggregate The AnalyticsAggregate instance
+   * @param {!module:analytics.AnalyticsTrackedEntities} analyticsTrackedEntities The AnalyticsTrackedEntities instance
    * @param {!module:analytics.AnalyticsEnrollments} analyticsEnrollments The AnalyticsEnrollments instance
    * @param {!module:analytics.AnalyticsEvents} analyticsEvents The AnalyticsEvents instance
    * @param {!module:analytics.AnalyticsRequest} analyticsRequest The AnalyticsRequest class
@@ -39,12 +43,14 @@ class Analytics {
   constructor(_ref) {
     let {
       aggregate,
+      trackedEntities,
       enrollments,
       events,
       request,
       response
     } = _ref;
     this.aggregate = aggregate;
+    this.trackedEntities = trackedEntities;
     this.enrollments = enrollments;
     this.events = events;
     this.request = request;
@@ -67,6 +73,7 @@ class Analytics {
     if (!Analytics.getAnalytics.analytics) {
       Analytics.getAnalytics.analytics = new Analytics({
         aggregate: new AnalyticsAggregate(dataEngine),
+        trackedEntities: new AnalyticsTrackedEntities(dataEngine),
         enrollments: new AnalyticsEnrollments(dataEngine),
         events: new AnalyticsEvents(dataEngine),
         request: AnalyticsRequest,

package/build/es/api/analytics/AnalyticsAggregate.js

@@ -68,11 +68,37 @@ class AnalyticsAggregate extends AnalyticsBase {
    *  .withStartDate('2017-10-01')
    *  .withEndDate('2017-10-31');
    *
-   *  analytics.aggregate.getDebugSql(req);
+   *  analytics.aggregate.getDebugSql(req)
    *  .then(console.log);
    */
   getDebugSql(req) {
     return this.fetch(req.withPath('debug/sql'));
   }
+
+  /**
+   * @param {!AnalyticsRequest} req Request object
+   *
+   * @returns {Promise} Promise that resolves with the SQL statement used to query the database.
+   *
+   * @example
+   * const req = new analytics.request()
+   *  .withParameters({
+   *    dx: 'fbfJHSPpUQD,cYeuwXTCPkU',
+   *    pe: 'THIS_YEAR',
+   *    ou: 'USER_ORGUNIT,USER_ORGUNIT_CHILDREN',
+   *    headers: 'dxname,pename,ouname,value,absdev,modifiedzscore,median,lowerbound,upperbound',
+   *    algorithm: 'MODIFIED_Z_SCORE',
+   *    maxResults: 100,
+   *    threshold: 3,
+        orderBy: 'value',
+        sortOrder: 'desc',
+   *  });
+   *
+   *  analytics.aggregate.getOutliersData(req)
+   *  .then(console.log);
+   */
+  getOutliersData(req) {
+    return this.fetch(req.withPath('outlierDetection'));
+  }
 }
 export default AnalyticsAggregate;

package/build/es/api/analytics/AnalyticsBase.js

@@ -1,13 +1,19 @@
 import sortBy from 'lodash/sortBy';
 import AnalyticsRequest from './AnalyticsRequest.js';
+import { formatRequestPath } from './utils.js';
 const analyticsQuery = {
   resource: 'analytics',
   id: _ref => {
     let {
       path,
-      program
+      program,
+      trackedEntityType
     } = _ref;
-    return [path, program].filter(Boolean).join('/');
+    return formatRequestPath({
+      path,
+      program,
+      trackedEntityType
+    });
   },
   params: _ref2 => {
     let {
@@ -16,8 +22,8 @@ const analyticsQuery = {
       parameters
     } = _ref2;
     return {
-      dimension: dimensions,
-      filter: filters,
+      dimension: dimensions.length ? dimensions : undefined,
+      filter: filters.length ? filters : undefined,
       ...parameters
     };
   }
@@ -27,9 +33,14 @@ const analyticsDataQuery = {
   id: _ref3 => {
     let {
       path,
-      program
+      program,
+      trackedEntityType
     } = _ref3;
-    return [path, program].filter(Boolean).join('/');
+    return formatRequestPath({
+      path,
+      program,
+      trackedEntityType
+    });
   },
   params: _ref4 => {
     let {
@@ -38,8 +49,8 @@ const analyticsDataQuery = {
       parameters
     } = _ref4;
     return {
-      dimension: dimensions,
-      filter: filters,
+      dimension: dimensions.length ? dimensions : undefined,
+      filter: filters.length ? filters : undefined,
       ...parameters,
       skipMeta: true,
       skipData: false
@@ -51,9 +62,14 @@ const analyticsMetaDataQuery = {
   id: _ref5 => {
     let {
       path,
-      program
+      program,
+      trackedEntityType
     } = _ref5;
-    return [path, program].filter(Boolean).join('/');
+    return formatRequestPath({
+      path,
+      program,
+      trackedEntityType
+    });
   },
   params: _ref6 => {
     let {
@@ -62,8 +78,8 @@ const analyticsMetaDataQuery = {
       parameters
     } = _ref6;
     return {
-      dimension: dimensions,
-      filter: filters,
+      dimension: dimensions.length ? dimensions : undefined,
+      filter: filters.length ? filters : undefined,
       ...parameters,
       skipMeta: false,
       skipData: true,
@@ -71,7 +87,7 @@ const analyticsMetaDataQuery = {
     };
   }
 };
-const generateDimensionStrings = function () {
+export const generateDimensionStrings = function () {
   let dimensions = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : [];
   let options = arguments.length > 1 ? arguments[1] : undefined;
   if (options && options.sorted) {
@@ -145,6 +161,7 @@ class AnalyticsBase {
       variables: {
         path: req.path,
         program: req.program,
+        trackedEntityType: req.trackedEntityType,
         dimensions: generateDimensionStrings(req.dimensions),
         filters: generateDimensionStrings(req.filters),
         parameters: req.parameters,
@@ -187,6 +204,7 @@ class AnalyticsBase {
       variables: {
         path: req.path,
         program: req.program,
+        trackedEntityType: req.trackedEntityType,
         dimensions: generateDimensionStrings(req.dimensions, options),
         filters: generateDimensionStrings(req.filters, options),
         parameters: req.parameters

package/build/es/api/analytics/AnalyticsRequest.js

@@ -4,6 +4,7 @@ import AnalyticsRequestBase from './AnalyticsRequestBase.js';
 import AnalyticsRequestDimensionsMixin from './AnalyticsRequestDimensionsMixin.js';
 import AnalyticsRequestFiltersMixin from './AnalyticsRequestFiltersMixin.js';
 import AnalyticsRequestPropertiesMixin from './AnalyticsRequestPropertiesMixin.js';
+import { formatDimension } from './utils.js';
 
 /**
  * @description
@@ -41,6 +42,7 @@ class AnalyticsRequest extends AnalyticsRequestDimensionsMixin(AnalyticsRequestF
   fromVisualization(visualization) {
     let passFilterAsDimension = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
     let request = this;
+    const outputType = visualization.outputType;
 
     // extract dimensions from visualization
     const columns = visualization.columns || [];
@@ -51,19 +53,28 @@ class AnalyticsRequest extends AnalyticsRequestDimensionsMixin(AnalyticsRequestF
       if ((_d$legendSet = d.legendSet) !== null && _d$legendSet !== void 0 && _d$legendSet.id) {
         dimension += `-${d.legendSet.id}`;
       }
-      if ((_d$programStage = d.programStage) !== null && _d$programStage !== void 0 && _d$programStage.id) {
-        dimension = `${d.programStage.id}.${dimension}`;
-      }
       if (d.filter) {
         dimension += `:${d.filter}`;
       }
+      const programStageId = (_d$programStage = d.programStage) === null || _d$programStage === void 0 ? void 0 : _d$programStage.id;
       if ((_d$repetition = d.repetition) !== null && _d$repetition !== void 0 && (_d$repetition$indexes = _d$repetition.indexes) !== null && _d$repetition$indexes !== void 0 && _d$repetition$indexes.length) {
         d.repetition.indexes.forEach(index => {
-          request = request.addDimension(dimension.replace(/\./, `[${index}].`));
+          var _d$program;
+          request = request.addDimension(formatDimension({
+            programId: (_d$program = d.program) === null || _d$program === void 0 ? void 0 : _d$program.id,
+            programStageId: `${programStageId}[${index}]`,
+            dimension,
+            outputType
+          }));
         });
       } else {
-        var _d$items;
-        request = request.addDimension(dimension, (_d$items = d.items) === null || _d$items === void 0 ? void 0 : _d$items.map(item => item.id));
+        var _d$program2, _d$items;
+        request = request.addDimension(formatDimension({
+          programId: (_d$program2 = d.program) === null || _d$program2 === void 0 ? void 0 : _d$program2.id,
+          programStageId,
+          dimension,
+          outputType
+        }), (_d$items = d.items) === null || _d$items === void 0 ? void 0 : _d$items.map(item => item.id));
       }
     });
 
@@ -78,17 +89,29 @@ class AnalyticsRequest extends AnalyticsRequestDimensionsMixin(AnalyticsRequestF
         request = request.addDimension(f.dimension, (_f$items = f.items) === null || _f$items === void 0 ? void 0 : _f$items.map(item => item.id));
       } else {
         var _f$programStage, _f$repetition, _f$repetition$indexes;
-        let filterString = (_f$programStage = f.programStage) !== null && _f$programStage !== void 0 && _f$programStage.id ? `${f.programStage.id}.${f.dimension}` : f.dimension;
+        let filterString = f.dimension;
         if (f.filter) {
           filterString += `:${f.filter}`;
         }
+        const programStageId = (_f$programStage = f.programStage) === null || _f$programStage === void 0 ? void 0 : _f$programStage.id;
         if ((_f$repetition = f.repetition) !== null && _f$repetition !== void 0 && (_f$repetition$indexes = _f$repetition.indexes) !== null && _f$repetition$indexes !== void 0 && _f$repetition$indexes.length) {
           f.repetition.indexes.forEach(index => {
-            request = request.addFilter(filterString.replace(/\./, `[${index}].`));
+            var _f$program;
+            request = request.addFilter(formatDimension({
+              programId: (_f$program = f.program) === null || _f$program === void 0 ? void 0 : _f$program.id,
+              programStageId: `${programStageId}[${index}]`,
+              dimension: filterString,
+              outputType
+            }));
           });
         } else {
-          var _f$items2;
-          request = request.addFilter(filterString, (_f$items2 = f.items) === null || _f$items2 === void 0 ? void 0 : _f$items2.map(item => item.id));
+          var _f$program2, _f$items2;
+          request = request.addFilter(formatDimension({
+            programId: (_f$program2 = f.program) === null || _f$program2 === void 0 ? void 0 : _f$program2.id,
+            programStageId,
+            dimension: filterString,
+            outputType
+          }), (_f$items2 = f.items) === null || _f$items2 === void 0 ? void 0 : _f$items2.map(item => item.id));
         }
       }
     });

package/build/es/api/analytics/AnalyticsRequestBase.js

@@ -18,6 +18,7 @@ class AnalyticsRequestBase {
       format = 'json',
       path,
       program,
+      trackedEntityType,
       dimensions = [],
       filters = [],
       parameters = {}
@@ -26,6 +27,7 @@ class AnalyticsRequestBase {
     this.format = format.toLowerCase();
     this.path = path;
     this.program = program;
+    this.trackedEntityType = trackedEntityType;
     this.dimensions = dimensions;
     this.filters = filters;
     this.parameters = {
@@ -47,7 +49,7 @@ class AnalyticsRequestBase {
   buildUrl(options) {
     // at least 1 dimension is required
     let dimensions = this.dimensions;
-    if (options && options.sorted) {
+    if (dimensions.length && options !== null && options !== void 0 && options.sorted) {
       dimensions = sortBy(dimensions, 'dimension');
     }
     const encodedDimensions = dimensions.map(_ref => {
@@ -57,15 +59,19 @@ class AnalyticsRequestBase {
       } = _ref;
       if (Array.isArray(items) && items.length) {
         const encodedItems = items.map(customEncodeURIComponent);
-        if (options && options.sorted) {
+        if (options !== null && options !== void 0 && options.sorted) {
           encodedItems.sort();
         }
         return `${dimension}:${encodedItems.join(';')}`;
       }
       return dimension;
     });
-    const endPoint = [this.endPoint, this.path, this.program].filter(e => !!e).join('/');
-    return `${endPoint}.${this.format}?dimension=${encodedDimensions.join('&dimension=')}`;
+    const endPoint = [this.endPoint, this.path, this.program, this.trackedEntityType].filter(Boolean).join('/');
+    let url = `${endPoint}.${this.format}`;
+    if (encodedDimensions.length) {
+      url += `?dimension=${encodedDimensions.join('&dimension=')}`;
+    }
+    return url;
   }
 
   /**
@@ -83,7 +89,7 @@ class AnalyticsRequestBase {
    */
   buildQuery(options) {
     let filters = this.filters;
-    if (options && options.sorted) {
+    if (filters.length && options !== null && options !== void 0 && options.sorted) {
       filters = sortBy(filters, 'dimension');
     }
     const encodedFilters = filters.map(_ref2 => {
@@ -93,7 +99,7 @@ class AnalyticsRequestBase {
       } = _ref2;
       if (Array.isArray(items) && items.length) {
         const encodedItems = items.map(customEncodeURIComponent);
-        if (options && options.sorted) {
+        if (options !== null && options !== void 0 && options.sorted) {
           encodedItems.sort();
         }
         return `${dimension}:${encodedItems.join(';')}`;

package/build/es/api/analytics/AnalyticsRequestPropertiesMixin.js

@@ -491,6 +491,25 @@ class extends base {
     return new AnalyticsRequest(this);
   }
 
+  /**
+   * Sets the tracked entity type for the request.
+   * It appends the tracked entity type id to the request's path.
+   *
+   * @param {!String} trackedEntityType The tracked entity type id
+   *
+   * @returns {AnalyticsRequest} A new instance of the class for chaining purposes
+   *
+   * @example
+   * const req = new analytics.request()
+   *    .withTrackedEntityType('nEenWmSyUEp');
+   */
+  withTrackedEntityType(trackedEntityType) {
+    if (trackedEntityType) {
+      this.trackedEntityType = trackedEntityType;
+    }
+    return new AnalyticsRequest(this);
+  }
+
   /**
    * Sets the program for the request.
    * It appends the program id to the request's path.

package/build/es/api/analytics/AnalyticsResponse.js

@@ -51,7 +51,8 @@ class AnalyticsResponse {
     }
   }
   extractHeaders() {
-    const dimensions = this.response.metaData.dimensions;
+    // some endpoints (ie. outlierDetection) don't return dimensions in metaData
+    const dimensions = this.response.metaData.dimensions || {};
     const headers = this.response.headers || [];
     return headers.map((header, index) => new AnalyticsResponseHeader(header, {
       isPrefix: isPrefixHeader(header, dimensions[header.name]),
@@ -87,48 +88,50 @@ class AnalyticsResponse {
       items
     } = metaData;
 
-    // populate metaData dimensions and items
-    this.headers.filter(header => !DEFAULT_COLLECT_IGNORE_HEADERS.includes(header.name)).forEach(header => {
-      let ids;
+    // some endpoints (ie. outlierDetection) don't return dimensions or items
+    if (dimensions && items) {
+      this.headers.filter(header => !DEFAULT_COLLECT_IGNORE_HEADERS.includes(header.name)).forEach(header => {
+        let ids;
 
-      // collect row values
-      if (header.isCollect) {
-        ids = this.getSortedUniqueRowIdStringsByHeader(header);
-        dimensions[header.name] = ids;
-      } else {
-        ids = dimensions[header.name];
-      }
-      if (header.isPrefix) {
-        // create prefixed dimensions array
-        dimensions[header.name] = ids.map(id => getPrefixedId(id, header.name));
-
-        // create items
-        dimensions[header.name].forEach((prefixedId, index) => {
-          const id = ids[index];
-          const valueType = header.valueType;
-          const name = getNameByIdsByValueType(id, valueType);
-          items[prefixedId] = {
-            name
-          };
-        });
-      }
-    });
+        // collect row values
+        if (header.isCollect) {
+          ids = this.getSortedUniqueRowIdStringsByHeader(header);
+          dimensions[header.name] = ids;
+        } else {
+          ids = dimensions[header.name];
+        }
+        if (header.isPrefix) {
+          // create prefixed dimensions array
+          dimensions[header.name] = ids.map(id => getPrefixedId(id, header.name));
 
-    // for events, add items from 'ouname'
-    if (this.hasHeader(OUNAME) && this.hasHeader(OU)) {
-      const ouNameHeaderIndex = this.getHeader(OUNAME).getIndex();
-      const ouHeaderIndex = this.getHeader(OU).getIndex();
-      let ouId;
-      let ouName;
-      this.rows.forEach(row => {
-        ouId = row[ouHeaderIndex];
-        if (items[ouId] === undefined) {
-          ouName = row[ouNameHeaderIndex];
-          items[ouId] = {
-            name: ouName
-          };
+          // create items
+          dimensions[header.name].forEach((prefixedId, index) => {
+            const id = ids[index];
+            const valueType = header.valueType;
+            const name = getNameByIdsByValueType(id, valueType);
+            items[prefixedId] = {
+              name
+            };
+          });
         }
       });
+
+      // for events, add items from 'ouname'
+      if (this.hasHeader(OUNAME) && this.hasHeader(OU)) {
+        const ouNameHeaderIndex = this.getHeader(OUNAME).getIndex();
+        const ouHeaderIndex = this.getHeader(OU).getIndex();
+        let ouId;
+        let ouName;
+        this.rows.forEach(row => {
+          ouId = row[ouHeaderIndex];
+          if (items[ouId] === undefined) {
+            ouName = row[ouNameHeaderIndex];
+            items[ouId] = {
+              name: ouName
+            };
+          }
+        });
+      }
     }
     return metaData;
   }