cht-conf 6.0.1 → 6.1.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [6.1.0](https://github.com/medic/cht-conf/compare/v6.0.2...v6.1.0) (2026-04-02)
+
+
+### Features
+
+* **#653:** add --merge-primary-contacts flag for merge-contacts action ([#654](https://github.com/medic/cht-conf/issues/654)) ([def533d](https://github.com/medic/cht-conf/commit/def533dbca20abca8303aea7f314921c6a1c166b)), closes [#653](https://github.com/medic/cht-conf/issues/653)
+
+## [6.0.2](https://github.com/medic/cht-conf/compare/v6.0.1...v6.0.2) (2026-01-16)
+
+
+### Bug Fixes
+
+* **#787:** upload forms with correct `internalId` property ([#788](https://github.com/medic/cht-conf/issues/788)) ([3a28dce](https://github.com/medic/cht-conf/commit/3a28dce3499c7cc2aac7ad5c8a7327303288986f)), closes [#787](https://github.com/medic/cht-conf/issues/787)
+
 ## [6.0.1](https://github.com/medic/cht-conf/compare/v6.0.0...v6.0.1) (2026-01-14)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cht-conf",
-  "version": "6.0.1",
+  "version": "6.1.0",
   "description": "Configure CHT deployments",
   "main": "./src/lib/main.js",
   "engines": {

package/src/fn/delete-contacts.js

@@ -57,7 +57,7 @@ ${bold('OPTIONS')}
   A comma delimited list of ids of contacts to be deleted.
 
 --disable-users
-  When flag is present, users at any deleted place will be permanently disabled.
+  When flag is present, users at any deleted place will be updated and may be permanently disabled. Supported by CHT Core 4.7 and above.
 
 --docDirectoryPath=<path to stage docs>
   Specifies the folder used to store the documents representing the changes in hierarchy.

package/src/fn/merge-contacts.js

@@ -15,6 +15,7 @@ module.exports = {
     const options = {
       disableUsers: args.disableUsers,
       docDirectoryPath: args.docDirectoryPath,
+      mergePrimaryContacts: args.mergePrimaryContacts,
       force: args.force,
     };
     return HierarchyOperations(db, options).merge(args.sourceIds, args.destinationId);
@@ -50,6 +51,7 @@ const parseExtraArgs = (projectDir, extraArgs = []) => {
     sourceIds,
     disableUsers: !!args['disable-users'],
     docDirectoryPath: path.resolve(projectDir, args.docDirectoryPath || 'json_docs'),
+    mergePrimaryContacts: !!args['merge-primary-contacts'],
     force: !!args.force,
   };
 };
@@ -75,6 +77,9 @@ ${bold('OPTIONS')}
 --disable-users
   When flag is present, users at any deleted place will be updated and may be permanently disabled. Supported by CHT Core 4.7 and above.
 
+--merge-primary-contacts
+  When flag is present, the primary contacts for all the top-level places will also be merged into a single resulting contact.
+
 --docDirectoryPath=<path to stage docs>
   Specifies the folder used to store the documents representing the changes in hierarchy.
 `);

package/src/lib/forms-utils.js

@@ -127,6 +127,13 @@ module.exports = {
   readTitleFrom: xml =>
     xml.substring(xml.indexOf('<h:title>') + 9, xml.indexOf('</h:title>')),
 
+  /**
+   * Get the ID of the form
+   * @param {string} xml the XML string
+   * @returns {string}
+   */
+  readIdFrom: xml => /<model.*?>[^]*?<instance>[^]*?id="([^"]*)"[^]*?<\/instance>[^]*?<\/model>/.exec(xml)?.[1],
+
   /**
    * Escape whitespaces in a path.
    * @param {string} path the path string

package/src/lib/hierarchy-operations/delete-hierarchy.js

@@ -34,7 +34,7 @@ async function deleteReportsForContact(db, options, contact) {
   let skip = 0;
   let reportBatch;
   do {
-    reportBatch = await DataSource.getReportsForContacts(db, [], contact._id, skip);
+    reportBatch = await DataSource.getReportsForContacts(db, [], [contact._id], skip);
 
     for (const report of reportBatch) {
       JsDocs.deleteDoc(options, report);

package/src/lib/hierarchy-operations/hierarchy-data-source.js

@@ -6,6 +6,7 @@ const api = require('../api');
 const HIERARCHY_ROOT = 'root';
 const BATCH_SIZE = 10000;
 const NOUVEAU_MIN_VERSION = '5.0.0';
+const SUBJECT_IDS = ['patient_id', 'patient_uuid', 'place_id', 'place_uuid'];
 
 /*
 Fetches all of the documents associated with the "contactIds" and confirms they exist.
@@ -84,17 +85,17 @@ const fetchReportsByCreator = async (db, createdByIds, skip) => {
   return await getFromDbView(db, 'medic-client/reports_by_freetext', createdByKeys, skip);
 };
 
-const fetchReportsBySubject = async (db, createdAtId, skip) => {
-  if (!createdAtId) {
+const fetchReportsBySubject = async (db, createdAtIds, skip) => {
+  if (!createdAtIds || createdAtIds.length <= 0) {
     return [];
   }
-  return await getFromDbView(db, 'medic-client/reports_by_subject', [createdAtId], skip);
+  return await getFromDbView(db, 'medic-client/reports_by_subject', createdAtIds, skip);
 };
 
-const getReportsForContacts = async (db, createdByIds, createdAtId, skip) => {
+const getReportsForContacts = async (db, createdByIds, createdAtIds, skip) => {
   const [creatorReports, subjectReports] = await Promise.all([
     fetchReportsByCreator(db, createdByIds, skip),
-    fetchReportsBySubject(db, createdAtId, skip)
+    fetchReportsBySubject(db, createdAtIds, skip)
   ]);
 
   const allRows = [...creatorReports, ...subjectReports];
@@ -124,6 +125,7 @@ async function getAncestorsOf(db, contactDoc) {
 module.exports = {
   BATCH_SIZE,
   HIERARCHY_ROOT,
+  SUBJECT_IDS,
   getAncestorsOf,
   getContactWithDescendants,
   getContact,

package/src/lib/hierarchy-operations/index.js

@@ -19,27 +19,27 @@ async function moveHierarchy(db, options, sourceIds, destinationId) {
   for (const sourceId of sourceIds) {
     const sourceDoc = sourceDocs[sourceId];
     const descendantsAndSelf = await DataSource.getContactWithDescendants(db, sourceId);
+
     const moveContext = {
       sourceId,
       destinationId,
       descendantsAndSelf,
       replacementLineage,
       merge: !!options.merge,
+      disableUsers: !!options.disableUsers,
+      mergePrimaryContacts: !!options.mergePrimaryContacts,
+      sourcePrimaryContactId: getPrimaryContactId(sourceDoc),
+      destinationPrimaryContactId: getPrimaryContactId(destinationDoc),
     };
 
     await constraints.assertNoPrimaryContactViolations(sourceDoc, destinationDoc, descendantsAndSelf);
     
-    if (options.merge) {
-      const toDeleteUsers = options.disableUsers && constraints.isPlace(sourceDoc);
-      JsDocs.deleteDoc(options, sourceDoc, toDeleteUsers);
-    }
-        
     const prettyPrintDocument = doc => `'${doc.name}' (${doc._id})`;
     trace(
       `Considering lineage updates to ${descendantsAndSelf.length} descendant(s) of contact `
       + `${prettyPrintDocument(sourceDoc)}.`
     );
-    const updatedDescendants = replaceLineageInContacts(moveContext);
+    const updatedDescendants = updateContacts(moveContext, constraints);
     
     const ancestors = await DataSource.getAncestorsOf(db, sourceDoc);
     trace(
@@ -68,6 +68,10 @@ async function moveHierarchy(db, options, sourceIds, destinationId) {
   );
 }
 
+function getPrimaryContactId(doc) {
+  return typeof doc?.contact === 'string' ? doc.contact : doc?.contact?._id;
+}
+
 async function updateReports(db, options, moveContext) {
   const descendantIds = moveContext.descendantsAndSelf.map(contact => contact._id);
 
@@ -75,8 +79,8 @@ async function updateReports(db, options, moveContext) {
   let reportDocsBatch;
   do {
     info(`Processing ${skip} to ${skip + DataSource.BATCH_SIZE} report docs`);
-    const createdAtId = options.merge && moveContext.sourceId;
-    reportDocsBatch = await DataSource.getReportsForContacts(db, descendantIds, createdAtId, skip);
+    const createdAtIds = getReportsCreatedAtIds(moveContext);
+    reportDocsBatch = await DataSource.getReportsForContacts(db, descendantIds, createdAtIds, skip);
 
     const lineageUpdates = replaceLineageOfReportCreator(reportDocsBatch, moveContext);
     const reassignUpdates = reassignReports(reportDocsBatch, moveContext);
@@ -90,24 +94,53 @@ async function updateReports(db, options, moveContext) {
   return skip;
 }
 
-function reassignReportSubjects(report, { sourceId, destinationId }) {
-  const SUBJECT_IDS = ['patient_id', 'patient_uuid', 'place_id', 'place_uuid'];
-  let updated = false;
-  for (const subjectId of SUBJECT_IDS) {
-    if (report[subjectId] === sourceId) {
-      report[subjectId] = destinationId;
-      updated = true;
-    }
+function getReportsCreatedAtIds(moveContext) {
+  const result = [];
+  if (moveContext.merge) {
+    result.push(moveContext.sourceId);
+  }
+
+  if (moveContext.mergePrimaryContacts && moveContext.sourcePrimaryContactId) {
+    result.push(moveContext.sourcePrimaryContactId);
+  }
 
-    if (report.fields[subjectId] === sourceId) {
-      report.fields[subjectId] = destinationId;
-      updated = true;
+  return result;
+}
+
+function reassignReportSubjects(report, moveContext) {
+  let updated = false;
+  for (const subjectId of DataSource.SUBJECT_IDS) {
+    updated = updated || reassignSingleReport(report, subjectId, moveContext.sourceId, moveContext.destinationId);
+
+    if (
+      moveContext.mergePrimaryContacts && 
+      moveContext.sourcePrimaryContactId && 
+      moveContext.destinationPrimaryContactId
+    ) {
+      updated = updated || reassignSingleReport(
+        report, subjectId, moveContext.sourcePrimaryContactId, moveContext.destinationPrimaryContactId
+      );
     }
   }
   
   return updated;
 }
 
+function reassignSingleReport(report, subjectId, matchId, resultingId) {
+  let result = false;
+  if (report[subjectId] === matchId) {
+    report[subjectId] = resultingId;
+    result = true;
+  }
+
+  if (report.fields[subjectId] === matchId) {
+    report.fields[subjectId] = resultingId;
+    result = true;
+  }
+
+  return result;
+}
+
 function reassignReports(reports, moveContext) {
   const updated = new Set();
   if (!moveContext.merge) {
@@ -179,9 +212,26 @@ function replaceLineageInSingleContact(doc, moveContext) {
   }
 }
 
-function replaceLineageInContacts(moveContext) {
+function updateContacts(moveContext, constraints) {
   return moveContext.descendantsAndSelf
-    .map(descendant => replaceLineageInSingleContact(descendant, moveContext))
+    .map(descendant => {
+      const deleteSource = moveContext.merge && descendant._id === moveContext.sourceId;
+      const deletePrimaryContact = moveContext.mergePrimaryContacts 
+        && descendant._id === moveContext.sourcePrimaryContactId 
+        && moveContext.destinationPrimaryContactId;
+
+      if (deleteSource || deletePrimaryContact) {
+        const toDeleteUsers = moveContext.disableUsers && constraints.isPlace(descendant);
+        return {
+          _id: descendant._id,
+          _rev: descendant._rev,
+          _deleted: true,
+          cht_disable_linked_users: !!toDeleteUsers,
+        };
+      }
+
+      return replaceLineageInSingleContact(descendant, moveContext);
+    })
     .filter(Boolean);
 }
 

package/src/lib/hierarchy-operations/lineage-constraints.js

@@ -9,13 +9,8 @@ module.exports = async (db, options) => {
 
   return {
     assertNoPrimaryContactViolations: async (sourceDoc, destinationDoc, descendantDocs) => {
-      const invalidPrimaryContactDoc = await getPrimaryContactViolations(db, sourceDoc, destinationDoc, descendantDocs);
-      if (invalidPrimaryContactDoc) {
-        throw Error(
-          `Cannot remove contact '${invalidPrimaryContactDoc?.name}' (${invalidPrimaryContactDoc?._id}) from the `
-          + 'hierarchy for which they are a primary contact.'
-        );
-      }
+      await assertOnPrimaryContactRemoval(db, sourceDoc, destinationDoc, descendantDocs);
+      await assertSourcePrimaryContactType(db, contactTypeInfo, sourceDoc);
     },
     assertNoHierarchyErrors: (sourceDocs, destinationDoc) => {
 
@@ -30,7 +25,7 @@ module.exports = async (db, options) => {
           throw Error(`Hierarchy Constraints: ${hierarchyError}`);
         }
       });
-  
+
       /*
        * It is nice that the tool can move lists of contacts as one operation, but strange things happen when two
        * contactIds are in the same lineage. For example, moving a district_hospital and moving a contact under that
@@ -47,13 +42,16 @@ module.exports = async (db, options) => {
         });
     },
 
-    isPlace: (contact) => {
-      const contactType = getContactType(contact);
-      return !contactTypeInfo[contactType]?.person;
-    },
+    isPlace: (contact) => isPlace(contactTypeInfo, contact),
   };
 };
 
+function isPlace(contactTypeInfo, contact) {
+  const contactType = getContactType(contact);
+  const isPerson = contactTypeInfo[contactType]?.person || false;
+  return !isPerson;
+}
+
 /*
 Enforce the list of allowed parents for each contact type
 Ensure we are not creating a circular hierarchy
@@ -133,24 +131,50 @@ A place's primary contact must be a descendant of that place.
 1. Check to see which part of the contact's lineage will be removed
 2. For each removed part of the contact's lineage, confirm that place's primary contact isn't being removed.
 */
-const getPrimaryContactViolations = async (db, contactDoc, destinationDoc, descendantDocs) => {
-  const contactsLineageIds = lineageManipulation.pluckIdsFromLineage(contactDoc?.parent);
-  const parentsLineageIds = lineageManipulation.pluckIdsFromLineage(destinationDoc);
+async function assertOnPrimaryContactRemoval(db, sourceDoc, destinationDoc, descendantDocs) {
+  const sourceLineageIds = lineageManipulation.pluckIdsFromLineage(sourceDoc?.parent);
+  const destinationLineageIds = lineageManipulation.pluckIdsFromLineage(destinationDoc);
 
-  const docIdsRemovedFromContactLineage = contactsLineageIds.filter(value => !parentsLineageIds.includes(value));
+  const docIdsRemovedFromContactLineage = sourceLineageIds.filter(value => !destinationLineageIds.includes(value));
   const docsRemovedFromContactLineage = await db.allDocs({
     keys: docIdsRemovedFromContactLineage,
     include_docs: true,
   });
 
-  const primaryContactIds = docsRemovedFromContactLineage.rows
+  const primaryContactIds = new Set(docsRemovedFromContactLineage.rows
     .map(row => row?.doc?.contact?._id)
-    .filter(Boolean);
-  
-  return descendantDocs.find(descendant => primaryContactIds.some(primaryId => descendant._id === primaryId));
-};
+    .filter(Boolean));
+
+  const invalidPrimaryContactDoc = descendantDocs.find(
+    descendant => primaryContactIds.has(descendant._id)
+  );
+  if (invalidPrimaryContactDoc) {
+    throw new Error('Cannot remove contact '+
+      `'${invalidPrimaryContactDoc?.name}' (${invalidPrimaryContactDoc?._id}) ` +
+      'from the hierarchy for which they are a primary contact.');
+  }
+}
+
+async function assertSourcePrimaryContactType(db, contactTypeInfo, sourceDoc) {
+  const sourcePrimaryContactId = getPrimaryContactId(sourceDoc);
+  if (!sourcePrimaryContactId) {
+    return;
+  }
+
+  const sourcePrimaryContactDoc = await db.get(sourcePrimaryContactId);
+  const primaryContactIsPlace = isPlace(contactTypeInfo, sourcePrimaryContactDoc);
+  if (primaryContactIsPlace) {
+    throw new Error(`Source "${sourceDoc._id}" has primary contact "${sourcePrimaryContactId}" which is of type place`);
+  }
+}
+
+function getContactType(doc) {
+  return doc?.type === 'contact' ? doc?.contact_type : doc?.type;
+}
 
-const getContactType = doc => doc?.type === 'contact' ? doc?.contact_type : doc?.type;
+function getPrimaryContactId(doc) {
+  return typeof doc?.contact === 'string' ? doc.contact : doc?.contact?._id;
+}
 
 async function fetchContactTypeInfo(db) {
   try {

package/src/lib/upload-forms.js

@@ -10,7 +10,7 @@ const warnUploadOverwrite = require('./warn-upload-overwrite');
 const {
   getFormDir,
   getFormFilePaths,
-  readTitleFrom,
+  readTitleFrom, readIdFrom,
 } = require('./forms-utils');
 
 const SUPPORTED_PROPERTIES = ['context', 'icon', 'title', 'xml2sms', 'subject_key', 'hidden_fields'];
@@ -59,7 +59,7 @@ const execute = async (projectDir, subDirectory, options) => {
     log.info(`Preparing form for upload: ${fileName}…`);
 
     const { baseFileName, mediaDir, xformPath, filePath } = getFormFilePaths(formsDir, fileName);
-    const internalId = (options.id_prefix || '') + baseFileName.replaceAll('-', ':');
+    const baseDocId = (options.id_prefix || '') + baseFileName.replaceAll('-', ':');
 
     const mediaDirExists = fs.exists(mediaDir);
     if (!mediaDirExists) {
@@ -74,7 +74,14 @@ const execute = async (projectDir, subDirectory, options) => {
       sha256: hashSum.digest('hex'),
     };
 
-    const docId = `form:${internalId}`;
+    const internalId = readIdFrom(xml);
+    if (internalId.replaceAll('-', ':') !== baseDocId) {
+      throw new Error(`The file name for the form [${baseFileName}] does not match the id in the xml [${
+        internalId
+      }]. Rename the form xlsx/xml files to match the id.`);
+    }
+
+    const docId = `form:${baseDocId}`;
     const doc = {
       _id: docId,
       type: 'form',