apn-app-manager 1.13.1 → 1.14.2

package/README.md

@@ -47,11 +47,11 @@ Used to duplicate all objects of an application, which replaces the namespace of
         - For example, an application with objects such as `SMP APP Artifacts` and `SMP_APP_displayUser` would have a namespace of `SMP_APP`
         - Note that this tool can only clone objects of one namepsace at a time with regular options.
    - Advanced options:
-     1. Select your application or package zip.
-     1. If cloning a package, select the zip file(s) that contain the entire application to ensure all references to objects not in the package are captured.
+     1. Select your application or package zip you wish to clone.
+     1. If cloning a package which is part of an application which is already cloned in the target environment, select the zip file(s) that your package from the first step contains references to, to ensure all references to objects not in the package are remapped. Use the same namespace configuration you did on the application(s) which were already cloned.
      1. Select your import customization properties file, if you have one.
      1. The tool will search through all object files and attempt to find every unique namespace, allowing you to specify cloning logic for each namepsace.
-     1. Database tables can be skipped during cloning.
+     1. Select whether you want database table names (within CDTs and records) to be renamed or not during cloning.
 1. Access your cloned application in the generated `/out/` folder.
 
 #### Notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apn-app-manager",
-  "version": "1.13.1",
+  "version": "1.14.2",
   "description": "Appian App Manager",
   "license": "Apache-2.0",
   "preferGlobal": true,

package/src/actions/cloneAction.js

@@ -22,6 +22,7 @@ const options = {
 const objectMaps = {};
 const uuidCollector = { uuids: [] };
 const namespaceCollector = {};
+const problemWordCollector = { words: [] };
 
 let outZipPath;
 let icfPath;
@@ -37,7 +38,7 @@ function main(callback) {
       fileSelect.selectSingleFile("Select application or package zip", ["zip"], false, function (appZipPath) {
         outZipPath = deriveOutPath(appZipPath);
         fileSelect.selectMultipleFiles(
-          "Select base application(s) and package(s) with objects that are referenced in the first zip selection",
+          "Select application(s) and package(s) that are referenced by the zip you specified to clone",
           ["zip"],
           [appZipPath],
           function (allAppZipPaths) {
@@ -99,36 +100,43 @@ function executeClone(callback) {
     }
   }
 
-  util.writeJson(path.resolve(cons.outDir, `objects.json`), objectMaps);
-
   // Update the object maps we are cloning based on the application prefix
-  util.print(`Cloning the objects files...`);
-  obMapsUpdates.renameObjectMaps(objectMaps, uuidCollector, namespaceCollector, options, obProps.usageTypes.CLONE);
+  obMapsUpdates.renameObjectMaps(objectMaps, uuidCollector, namespaceCollector, problemWordCollector, options, obProps.usageTypes.CLONE);
 
-  // These output files are helpful for debugging
-  util.writeJson(path.resolve(cons.outDir, `objects.json`), objectMaps);
-  util.writeJson(path.resolve(cons.outDir, `not-cloned-uuids.json`), uuidCollector);
+  // Prompts the user to tell us how to handle problem words
+  addressProblemWords(function () {
+    // These output files are helpful for debugging
+    util.writeJson(path.resolve(cons.outDir, `objects.json`), objectMaps);
+    util.writeJson(path.resolve(cons.outDir, `not-cloned-uuids.json`), uuidCollector);
+    if (!util.isBlank(namespaceCollector)) {
+      util.writeJson(path.resolve(cons.outDir, `namespaces.json`), namespaceCollector);
+    }
+    if (!util.isBlank(problemWordCollector.words)) {
+      util.writeJson(path.resolve(cons.outDir, `problem-terms.json`), problemWordCollector.words);
+    }
 
-  // Modify the underlying object XML files & zip the package
-  obModify.modifyObjectFiles(cons.tempDir, objectMaps, obProps.usageTypes.CLONE, []);
-  util.zipDir(cons.tempDir, outZipPath, false);
-  obModify.renameSingleFile(outZipPath, objectMaps, obProps.usageTypes.CLONE, []);
+    // Modify the underlying object XML files & zip the package
+    util.print(`Cloning the objects files...`);
+    obModify.modifyObjectFiles(cons.tempDir, objectMaps, problemWordCollector.words, obProps.usageTypes.CLONE, []);
+    util.zipDir(cons.tempDir, outZipPath, false);
+    obModify.renameSingleFile(outZipPath, objectMaps, problemWordCollector.words, obProps.usageTypes.CLONE, []);
 
-  // Modify the ICF file
-  obModify.modifySingleFile(icfPath, deriveOutPath(icfPath), objectMaps, obProps.usageTypes.CLONE, []);
+    // Modify the ICF file
+    obModify.modifySingleFile(icfPath, deriveOutPath(icfPath), objectMaps, problemWordCollector.words, obProps.usageTypes.CLONE, []);
 
-  // Print warnings and output
-  if (uuidCollector["uuids"].length > 0) {
+    // Print warnings and output
+    if (uuidCollector["uuids"].length > 0) {
+      util.printGap();
+      util.printWarning(
+        `${uuidCollector["uuids"].length} uuids were found in your zip but not parsed via cloning (see output file 'not-cloned-uuids.json'). Check the count of missing precedents from your app package in your source environment. If it is ${uuidCollector["uuids"].length} objects, then those are likely just the missing precedents, otherwise please reach out to the authors of this tool, since the XML structure of Appian objects has probably changed and this tool needs to be updated.`
+      );
+    }
     util.printGap();
-    util.printWarning(
-      `${uuidCollector["uuids"].length} uuids were found in your zip but not parsed via cloning (see output file 'not-cloned-uuids.json'). Check the count of missing precedents from your app package in your source environment. If it is ${uuidCollector["uuids"].length} objects, then those are likely just the missing precedents, otherwise please reach out to the authors of this tool, since the XML structure of Appian objects has probably changed and this tool needs to be updated.`
-    );
-  }
-  util.printGap();
-  util.print(`Cloning complete. Output can be found in the '/out/' folder (${path.resolve(cons.outDir)}).`);
+    util.print(`Cloning complete. Output can be found in the '/out/' folder (${path.resolve(cons.outDir)}).`);
 
-  // Execute callback if passed
-  util.execCallback(callback, outZipPath);
+    // Execute callback if passed
+    util.execCallback(callback, outZipPath);
+  });
 }
 
 // Returns the output path from an input path file
@@ -195,6 +203,55 @@ function mapNamespaces(onComplete) {
     obExtract.sortNamespaces(namespaceCollector).forEach(namespace => {
       util.print(`   ${namespace} -> ${util.replaceBlank(namespaceCollector[namespace]["newNamespace"], `Will not clone`)}`, true);
     });
+    util.printGap();
+    onComplete();
+  }
+}
+
+// Prompts the user to tell us how to handle problem words
+function addressProblemWords(onComplete) {
+  let problemWordsToDecide = lodash.filter(problemWordCollector.words, function (wordMap) {
+    return util.isBlank(wordMap["decision"]);
+  });
+  let isFirstIteration = problemWordsToDecide.length == problemWordCollector.words.length;
+  if (problemWordsToDecide.length > 0) {
+    let message;
+    if (isFirstIteration) {
+      message = `After analyzing the objects, ${problemWordCollector.words.length} potential problem terms were found. For each term, select what behavior you would like (remap or skip). The cloning tool assumes every reference to a term in the zip should be remapped, therefore it's recommended to skip terms that could also be XML tags or system object terms.`;
+    } else {
+      message = `Select another term`;
+    }
+    let problemWordsToDecideMap = {};
+    problemWordsToDecide.forEach(wordMap => {
+      let formattedMessage = `'${wordMap.current}' -> '${wordMap.new}' (object: '${wordMap.objectName}', property: '${wordMap.haulField}')`;
+      problemWordsToDecideMap[formattedMessage] = wordMap;
+    });
+    prompt.promptList(message, Object.keys(problemWordsToDecideMap), function (answer) {
+      let chosenProblemWordMap = problemWordsToDecideMap[answer];
+      let options = [];
+      Object.keys(cons.problemWordOptions).forEach(option => {
+        options.push(cons.problemWordOptions[option]);
+      });
+      let optionLabels = [];
+      options.forEach(option => {
+        optionLabels.push(option.label);
+      });
+      prompt.promptList(`Term: ${answer}. Choose what behavior to do when remapping this term.`, optionLabels, function (answer) {
+        let chosenDecision = lodash.filter(options, function (option) {
+          return option.label == answer;
+        })[0];
+        problemWordCollector.words.forEach(function (wordMap, index) {
+          if (wordMap.current == chosenProblemWordMap.current && wordMap.new == chosenProblemWordMap.new) {
+            problemWordCollector.words[index]["decision"] = chosenDecision.key;
+          }
+        });
+        addressProblemWords(onComplete);
+      });
+    });
+  } else {
+    if (problemWordCollector.words.length > 0) {
+      util.print(`All potential problem terms accounted for.`);
+    }
     onComplete();
   }
 }

package/src/cons.js

@@ -44,4 +44,16 @@ module.exports = {
   ],
 
   appianUrlRegex: /^https:\/\/.*\/suite/g,
+
+  appianSystemObjectUuidRegex: /^SYSTEM_.*$/g,
+
+  // Problem words are words like "user" or "studio" which can easily map to
+  // existing platform terminology/XML tabs like <user></user> or #"SYSTEM_SYSRULES_studio_rule"
+  // Testing can be found here: https://regexr.com/827su
+  problemWordRegex: /^[a-z0-9]+$/g,
+
+  problemWordOptions: {
+    REMAP_ALL: { key: "REMAP_ALL", label: "Remap all references of this term" },
+    REMAP_NONE: { key: "REMAP_NONE", label: "Do not remap this term" },
+  },
 };

package/src/handlers/objectExtractHandler.js

@@ -28,6 +28,9 @@ module.exports = {
     updateDatatypeUuids(objectMaps);
   },
 
+  // Returns the count of all objects in the objectMap
+  retrieveObjectMapCount: retrieveObjectMapCount,
+
   // Sorts the namespaces by their relative lengths
   sortNamespaces: function (namespaceCollector) {
     return lodash.flatten([

package/src/handlers/objectMapsUpdateHandler.js

@@ -11,9 +11,9 @@ const { remove } = require("fs-extra");
 // Exports
 module.exports = {
   // Goes through all of the objectMaps and creates new name, uuid, etc.
-  renameObjectMaps: function (objectMaps, uuidCollector, namespaceMap, options, usageType) {
+  renameObjectMaps: function (objectMaps, uuidCollector, namespaceMap, problemWordCollector, options, usageType) {
     // Update all objectMaps with new names
-    renameObjectMaps(objectMaps, uuidCollector, namespaceMap, options, usageType);
+    renameObjectMaps(objectMaps, uuidCollector, namespaceMap, problemWordCollector, options, usageType);
   },
 };
 
@@ -22,13 +22,18 @@ module.exports = {
 // ---------------------------------------------------
 
 // Goes through all of the objectMaps and creates new name, uuid, etc.
-function renameObjectMaps(objectMaps, uuidCollector, namespaceMap, options, usageType) {
+function renameObjectMaps(objectMaps, uuidCollector, namespaceMap, problemWordCollector, options, usageType) {
   obProps.haulTypes.forEach(haulType => {
     objectMaps[haulType.haulName].forEach(function (objectMap, objectMapIndex) {
       let curNamespaceForObject = findNamespaceForObject(objectMap, namespaceMap, haulType, objectMaps);
       let newNamespaceForObject;
-      // Logic to determine if the object will be skipped, either not in the namespaceMap, or the newNamespace is null
-      let objectWillNotBeCloned = Object.keys(namespaceMap).indexOf(curNamespaceForObject) < 0;
+      // Logic to determine if the object will be skipped, either not in the namespaceMap, or the newNamespace is null, or it's a system object
+      let uuidHaulField = lodash.filter(haulType.fields, function (haulField) {
+        return haulField.fieldName == obProps.fieldNames.UUID;
+      })[0];
+      let objectUuid = objectMap["current"][uuidHaulField.fieldName];
+      let objectWillNotBeCloned =
+        Object.keys(namespaceMap).indexOf(curNamespaceForObject) < 0 || objectUuid.match(cons.appianSystemObjectUuidRegex);
       if (!objectWillNotBeCloned) {
         newNamespaceForObject = namespaceMap[curNamespaceForObject]["newNamespace"];
         objectWillNotBeCloned = util.isBlank(newNamespaceForObject);
@@ -45,10 +50,14 @@ function renameObjectMaps(objectMaps, uuidCollector, namespaceMap, options, usag
       } else {
         // Object will be cloned
         objectMaps[haulType.haulName][objectMapIndex]["new"] = {};
+        let objectName = "";
         haulType.fields.forEach(haulField => {
           if (lodash.includes(haulField.usage, usageType)) {
             let newValue;
             let curValue = objectMap["current"][haulField.fieldName];
+            if (haulField.fieldName == obProps.fieldNames.NAME) {
+              objectName = curValue;
+            }
             removeFoundUuids(uuidCollector, haulField, curValue);
             if (haulField.fieldName == obProps.fieldNames.DB_TABLE && !options.renameDbTables) {
               newValue = curValue;
@@ -56,14 +65,17 @@ function renameObjectMaps(objectMaps, uuidCollector, namespaceMap, options, usag
               if (haulField.isArray) {
                 let newValueArray = [];
                 curValue.forEach(curValueIter => {
-                  newValueArray.push(renameObjectProp(curValueIter, haulField, curNamespaceForObject, newNamespaceForObject));
+                  let newValueIter = renameObjectProp(curValueIter, haulField, curNamespaceForObject, newNamespaceForObject);
+                  newValueArray.push(newValueIter);
+                  checkProblemWord(curValueIter, newValueIter, objectName, haulField, haulType, problemWordCollector);
                 });
                 newValue = newValueArray;
               } else {
                 newValue = renameObjectProp(curValue, haulField, curNamespaceForObject, newNamespaceForObject);
+                checkProblemWord(curValue, newValue, objectName, haulField, haulType, problemWordCollector);
               }
-              objectMaps[haulType.haulName][objectMapIndex]["new"][haulField.fieldName] = newValue;
             }
+            objectMaps[haulType.haulName][objectMapIndex]["new"][haulField.fieldName] = newValue;
           }
         });
       }
@@ -174,6 +186,19 @@ function findNamespaceForObjectByName(objectName, namespaceMap) {
   return cons.noNamespace;
 }
 
+// Check if a word might be a problem
+function checkProblemWord(curValue, newValue, objectName, haulField, haulType, problemWordCollector) {
+  if (!util.isBlank(newValue) && curValue != newValue && curValue.match(cons.problemWordRegex)) {
+    problemWordCollector["words"].push({
+      current: curValue,
+      new: newValue,
+      objectName: objectName,
+      haulField: haulField.fieldName,
+      haulType: haulType.haulName,
+    });
+  }
+}
+
 // Utility function to differenciate between debug logging and real logging
 function debug(input) {
   console.log(input);

package/src/handlers/objectModifyHandler.js

@@ -18,10 +18,10 @@ module.exports = {
   modifyObjectFiles: modifyObjectFiles,
 
   // Modify a single file
-  modifySingleFile: function (filePath, outPath, objectMaps, usageType, additionalReplacementMaps) {
+  modifySingleFile: function (filePath, outPath, objectMaps, problemWordsMaps, usageType, additionalReplacementMaps) {
     if (filePath) {
       // Convert the extracted names & uuids to a flat replacement array
-      let replacementMaps = buildReplacementMaps(objectMaps, usageType, additionalReplacementMaps);
+      let replacementMaps = buildReplacementMaps(objectMaps, problemWordsMaps, usageType, additionalReplacementMaps);
       // Create the file we will update
       util.copyFile(filePath, outPath);
       // Actually modify the file
@@ -30,10 +30,10 @@ module.exports = {
   },
 
   // Renames a single file
-  renameSingleFile: function (filePath, objectMaps, usageType, additionalReplacementMaps) {
+  renameSingleFile: function (filePath, objectMaps, problemWordsMaps, usageType, additionalReplacementMaps) {
     if (filePath) {
       // Convert the extracted names & uuids to a flat replacement array
-      let replacementMaps = buildReplacementMaps(objectMaps, usageType, additionalReplacementMaps);
+      let replacementMaps = buildReplacementMaps(objectMaps, problemWordsMaps, usageType, additionalReplacementMaps);
       // Actually modify the file
       renameObjectFile(replacementMaps, filePath);
     }
@@ -45,9 +45,9 @@ module.exports = {
 // ---------------------------------------------------
 
 // Actually modifies all of the objects based on the objectMaps
-function modifyObjectFiles(appDir, objectMaps, usageType, additionalReplacementMaps) {
+function modifyObjectFiles(appDir, objectMaps, problemWordsMaps, usageType, additionalReplacementMaps) {
   // Convert the extracted names & uuids to a flat replacement array
-  let replacementMaps = buildReplacementMaps(objectMaps, usageType, additionalReplacementMaps);
+  let replacementMaps = buildReplacementMaps(objectMaps, problemWordsMaps, usageType, additionalReplacementMaps);
   // Determine how many files to change
   let totalCount = 0;
   util.handleDirFiles(appDir, ["xml", "xsd", "properties"], 3, 2, function (obPath) {
@@ -69,7 +69,7 @@ function modifyObjectFiles(appDir, objectMaps, usageType, additionalReplacementM
 }
 
 // Builds the replacementMaps object
-function buildReplacementMaps(objectMaps, usageType, additionalReplacementMaps) {
+function buildReplacementMaps(objectMaps, problemWordsMaps, usageType, additionalReplacementMaps) {
   let replacementMaps = [];
   obProps.haulTypes.forEach(haulType => {
     haulType.fields.forEach(haulField => {
@@ -81,13 +81,19 @@ function buildReplacementMaps(objectMaps, usageType, additionalReplacementMaps)
                 buildSingleReplacementMap(
                   haulField,
                   objectMap["current"][haulField.fieldName][index],
-                  objectMap["new"][haulField.fieldName][index]
+                  objectMap["new"][haulField.fieldName][index],
+                  problemWordsMaps
                 )
               );
             });
           } else {
             replacementMaps.push(
-              buildSingleReplacementMap(haulField, objectMap["current"][haulField.fieldName], objectMap["new"][haulField.fieldName])
+              buildSingleReplacementMap(
+                haulField,
+                objectMap["current"][haulField.fieldName],
+                objectMap["new"][haulField.fieldName],
+                problemWordsMaps
+              )
             );
           }
         });
@@ -104,9 +110,11 @@ function buildReplacementMaps(objectMaps, usageType, additionalReplacementMaps)
 }
 
 // Returns a single new value for the replacementMap
-function buildSingleReplacementMap(haulField, from, to) {
+function buildSingleReplacementMap(haulField, from, to, problemWordsMaps) {
   if (to == undefined) {
     return null;
+  } else if (isReplacementAProblemWordtoSkip(from, to, problemWordsMaps)) {
+    return null;
   } else {
     let wordBounded = lodash.includes(obProps.wordBoundedReplacements, haulField.type);
     if (util.isBlank(haulField.replaceFormat)) {
@@ -121,6 +129,21 @@ function buildSingleReplacementMap(haulField, from, to) {
   }
 }
 
+// Checks if a replacement is a problem word that should be skipped
+function isReplacementAProblemWordtoSkip(from, to, problemWordsMaps) {
+  if (util.isBlank(problemWordsMaps)) {
+    return false;
+  }
+  let matches = lodash.filter(problemWordsMaps, function (map) {
+    return from == map["current"] && to == map["new"];
+  });
+  if (matches.length > 0) {
+    return matches[0]["decision"] == cons.problemWordOptions.REMAP_NONE["key"];
+  } else {
+    return false;
+  }
+}
+
 // Modifies a single object files
 function modifyObjectFile(replacementMaps, fileCount, obPath, trackProgress) {
   let content = util.readFile(obPath);
@@ -138,7 +161,9 @@ function modifyObjectFile(replacementMaps, fileCount, obPath, trackProgress) {
 
 // Renames a single object file
 function renameObjectFile(replacementMaps, obPath) {
-  util.renameFile(obPath, util.replaceMaps(obPath, replacementMaps));
+  let relativePath = path.relative(".", obPath).toString();
+  let newRelativePath = util.replaceMaps(relativePath, replacementMaps);
+  util.renameFile(obPath, path.resolve(newRelativePath));
 }
 
 // Utility function to differenciate between debug logging and real logging

package/src/objectProps.js

@@ -9,7 +9,7 @@ const propTypes = {
   URL_STUB: "URL_STUB",
 };
 
-const wordBoundedReplacements = [propTypes.URL_STUB];
+const wordBoundedReplacements = [propTypes.NAME, propTypes.URL_STUB];
 
 const obTypes = {
   DATATYPE: "datatype",
@@ -52,6 +52,7 @@ const fieldNames = {
   PAGE_UUIDS: "pageUuids",
   APP_PREFIX: "appPrefix",
   APP_ACTION_UUIDS: "appActionUuids",
+  RECORD_PLURAL_NAME: "pluralName",
   RECORD_ACTION_UUIDS: "recordActionUuids",
   RECORD_ACTION_REF_IDS: "recordActionRefIds",
   RECORD_FIELD_UUIDS: "fieldUuids",
@@ -286,6 +287,13 @@ const haulTypes = [
         usage: [usageTypes.CLONE, usageTypes.BUILD],
         isArray: true,
       },
+      {
+        fieldName: fieldNames.RECORD_PLURAL_NAME,
+        xpath: `recordTypeHaul/recordType/a:pluralName/node()`,
+        type: propTypes.TEXT,
+        usage: [usageTypes.CLONE, usageTypes.BUILD, usageTypes.RENAME],
+        replaceFormat: "<a:pluralName>{VALUE}</a:pluralName>",
+      },
       {
         fieldName: fieldNames.URL_STUB,
         xpath: `recordTypeHaul/recordType/a:urlStub/node()`,

package/src/util.js

@@ -492,7 +492,9 @@ function replaceMaps(inStr, maps) {
   let replaceMaps = [];
 
   maps.forEach(map => {
-    replaceMaps.push({ from: map.from, temp: buildNewUuid(), to: map.to, wordBounded: map.wordBounded });
+    if (!isBlank(map) && map.from != map.to) {
+      replaceMaps.push({ from: map.from, temp: buildNewUuid(), to: map.to, wordBounded: map.wordBounded });
+    }
   });
 
   replaceMaps = arrayByFieldLenth(replaceMaps, "from"); // Order the array by longest to shortest