apn-app-manager 1.2.0-beta.3 → 1.2.0

package/README.md

@@ -2,8 +2,6 @@
 
 `apn-app-manager` is a command line tool for managing Appian applications.
 
-Test beta version
-
 ## Why?
 
 When app building you may want to do things in bulk that are easiest to do via an application's exported XML files and a re-import. This tool helps to automate some of those tasks.
@@ -51,7 +49,8 @@ Used to duplicate all objects of an application, which replaces the namespace of
 
 1. Always inspect your cloned zip before importing to verify that what will be imported matches what you'd expect.
 1. The cloning tool is idempotent meaning it will always return the same output zip run against the same input. This also means you can develop an application, clone it, then enhance the original application, re-clone it, and that second clone will deploy over the first clone with objects being recognized as "Changed" as if you had just modified the clone directly.
-1. It is highly recommended that all objects in your application have the same prefix (including objects that generally aren't prefixed such as applications, groups, process models, etc). Otherwise, the cloning tool will not be able to generate a unique name for these objects, and certain objects are required to have unique names.
+1. It is recommended that all objects in your application have the same namespace (including objects that generally aren't prefixed such as applications, groups, process models, etc). Objects that do not match your entered namespace will not be cloned.
+   - If you have multiple namespaces across your objects, you can run the cloner tool recursively against the output package to account for each namespace.
 1. SQL files for your application are not supported for cloning at this time. SQL scripts will have to be adjusted manually to align with the cloned objects (i.e. changing table name references).
 1. There are two other document generated in the `/out/` folder after cloning:
    - `objects.json` - This contains every attribute of collected metadata from every object in the package, including its current value and new value.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apn-app-manager",
-  "version": "1.2.0-beta.3",
+  "version": "1.2.0",
   "description": "Appian App Manager",
   "license": "Apache-2.0",
   "preferGlobal": true,
@@ -26,7 +26,7 @@
     "npm": "^8.18.0",
     "npm-run": "^5.0.1",
     "path": "^0.12.7",
-    "prompts": "^2.3.0",
+    "prompts": "^2.4.2",
     "properties-parser": "^0.3.1",
     "set-immediate-shim": "^2.0.0",
     "uuid": "^9.0.0",

package/src/actions/cloneAction.js

@@ -20,113 +20,65 @@ function main(callback) {
   fileSelect.getAppPackage(function (appZipPath) {
     util.unzipDir(appZipPath, cons.tempDir);
     fileSelect.selectSingleFile("Select import customization properties file", ["properties"], true, function (icfPath) {
-      executeClone(appZipPath, icfPath, callback);
+      promptNamespace("What is your current namespace?", function (curNamespace) {
+        promptNamespace("What is your new namespace?", function (newNamespace) {
+          const namespaceMap = {};
+          namespaceMap[curNamespace] = { newNamespace: newNamespace };
+          executeClone(appZipPath, icfPath, namespaceMap, callback);
+        });
+      });
     });
   });
 }
 
 // Executes all the steps of the clone
-function executeClone(appZipPath, icfPath, callback) {
-  // Initialize variables based on the new namespace
+function executeClone(appZipPath, icfPath, namespaceMap, callback) {
+  // Initialize output variables
   const outZipPath = path.resolve(cons.outDir, path.basename(appZipPath));
   const outIcfPath = icfPath ? path.resolve(cons.outDir, path.basename(icfPath)) : null;
 
   // Extract the metadata including the namespace from each object file
   const objectMaps = {};
   const uuidCollector = { uuids: [] };
-  const namespaceCollector = {};
   util.print(`Collecting all metadata from the objects...`);
-  obExtract.buildObjectMaps(objectMaps, uuidCollector, namespaceCollector, cons.tempDir, obProps.usageTypes.CLONE);
-
-  // Have the user map each namespace to its proper behavior
-  mapNamespaces(namespaceCollector, function onComplete() {
+  obExtract.buildObjectMaps(objectMaps, uuidCollector, cons.tempDir, obProps.usageTypes.CLONE);
+  let nonMatchingObjectCount =
+    obExtract.retrieveObjectMapCount(objectMaps) - obExtract.retrieveObjectMapCount(objectMaps, Object.keys(namespaceMap));
+  if (nonMatchingObjectCount > 0) {
+    util.printWarning(
+      `${nonMatchingObjectCount} objects found not matching namespace ${Object.keys(namespaceMap)}, these objects won't be cloned`
+    );
     util.printGap();
-    // Update the object maps we are cloning based on the application prefix
-    util.print(`Cloning the objects files...`);
-    obMapsUpdates.renameObjectMaps(objectMaps, uuidCollector, namespaceCollector, 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);
-    util.writeJson(path.resolve(cons.outDir, `namespaces.json`), namespaceCollector);
+  }
 
-    // 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, []);
+  // Update the object maps we are cloning based on the application prefix
+  util.print(`Cloning the objects files...`);
+  obMapsUpdates.renameObjectMaps(objectMaps, uuidCollector, namespaceMap, obProps.usageTypes.CLONE);
 
-    // Modify the ICF file
-    obModify.modifySingleFile(icfPath, outIcfPath, objectMaps, 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);
 
-    // Print warnings and output
-    if (uuidCollector["uuids"].length > 0) {
-      util.printGap();
-      util.printWarning(
-        `WARNING: ${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)}).`);
+  // 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, []);
 
-    // Execute callback if passed
-    util.execCallback(callback, outZipPath);
-  });
-}
+  // Modify the ICF file
+  obModify.modifySingleFile(icfPath, outIcfPath, objectMaps, obProps.usageTypes.CLONE, []);
 
-// Prompts the user to select a namespace
-function mapNamespaces(namespaceCollector, onComplete) {
-  let namespacesToChooseFrom = lodash.filter(obExtract.sortNamespaces(namespaceCollector), function (namespace) {
-    return namespaceCollector[namespace]["newNamespace"] == null;
-  });
-  let isFirstIteration = namespacesToChooseFrom.length == Object.keys(namespaceCollector).length;
-  if (namespacesToChooseFrom.length > 0) {
-    let message;
-    if (isFirstIteration) {
-      message = `After analyzing the objects, ${
-        Object.keys(namespaceCollector).length
-      } potential unique namespaces were found. For each namespace, select what behavior you would like (clone or keep as-is). There may be overlap with sub-prefixes, in which case selecting a shorter namespace that matches ones with more prefixes will result in that behavior applying to all longer matching namespaces. For objects without a namespace, a prefix will automatically be added if they will be cloned. All namespaces with more than 1 prefix are represented with '_' delimiters, although the proper delimiter will automatically be determined by the object type.`;
-    } else {
-      message = `Select another namespace`;
-    }
-    let namespacesToChooseFromMap = {};
-    namespacesToChooseFrom.forEach(namespace => {
-      let subNamespaceCount =
-        lodash.filter(namespacesToChooseFrom, function (otherNamespace) {
-          return otherNamespace.startsWith(namespace);
-        }).length - 1;
-      let formattedNamespace =
-        namespace == cons.noNamespace
-          ? namespace
-          : `${" ".repeat(namespace.split("_").length)}${namespace}  [including ${subNamespaceCount} matching sub-namespace(s)]`;
-      namespacesToChooseFromMap[formattedNamespace] = namespace;
-    });
-    prompt.promptList(message, Object.keys(namespacesToChooseFromMap), function (answer) {
-      let chosenNamespace = namespacesToChooseFromMap[answer];
-      promptNamespace(
-        `Namespace: ${chosenNamespace}. Enter a new namespace to clone these objects. Enter nothing to keep them as-is.`,
-        function (answer) {
-          Object.keys(namespaceCollector).forEach(namespace => {
-            if (namespaceCollector[namespace]["newNamespace"] == null) {
-              if (namespace.startsWith(chosenNamespace)) {
-                if (namespace == chosenNamespace) {
-                  namespaceCollector[namespace]["newNamespace"] = answer;
-                } else {
-                  delete namespaceCollector[namespace];
-                }
-              }
-            }
-          });
-          mapNamespaces(namespaceCollector, onComplete);
-        }
-      );
-    });
-  } else {
-    util.print(`All namespaces accounted for. See details below.`);
-    obExtract.sortNamespaces(namespaceCollector).forEach(namespace => {
-      util.print(`   ${namespace} -> ${util.replaceBlank(namespaceCollector[namespace]["newNamespace"], `Will not clone`)}`, true);
-    });
-    onComplete();
+  // 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.print(`Cloning complete. Output can be found in the '/out/' folder (${path.resolve(cons.outDir)}).`);
+
+  // Execute callback if passed
+  util.execCallback(callback, outZipPath);
 }
 
 // Prompts the user for a namespace

package/src/cons.js

@@ -25,7 +25,7 @@ module.exports = {
   },
 
   yesNo: ["Yes", "No"],
-  none: "None",
+  none: "[None]",
 
   // Testing of this regex can be found here: https://regexr.com/6sgu6
   // Note that we can assume any UUID that "must be cloned" must be wrapped in either >uuid< or "uuid"

package/src/handlers/fileSelectHandler.js

@@ -21,10 +21,13 @@ module.exports = {
 };
 
 function selectFile(promptText, fileTypes, optional, callback) {
-  let files = optional ? [cons.none] : [];
+  let files = [];
   util.handleDirFiles(cons.curDir, fileTypes, 1, 1, function (filePath) {
     files.push(path.basename(filePath));
   });
+  if (optional) {
+    files.push(cons.none);
+  }
   prompt.promptList(promptText, files, function (answer) {
     let answerPath = answer == cons.none ? null : path.resolve(cons.curDir, answer);
     util.execCallback(callback, answerPath);

package/src/handlers/objectExtractHandler.js

@@ -11,12 +11,12 @@ const { split } = require("lodash");
 // Exports
 module.exports = {
   // Builds the objectMaps object from the application
-  buildObjectMaps: function (objectMaps, uuidCollector, namespaceCollector, appDir, usageType) {
+  buildObjectMaps: function (objectMaps, uuidCollector, appDir, usageType) {
     let fileCount = { count: 0 };
     initObjectMaps(objectMaps);
     // Extract the name, uuid, etc. from each object file
     util.handleDirFiles(appDir, ["xml", "xsd"], 2, 2, function (obPath) {
-      extractObProps(objectMaps, uuidCollector, namespaceCollector, fileCount, obPath, usageType);
+      extractObProps(objectMaps, uuidCollector, fileCount, obPath, usageType);
     });
     // Set the datatype UUIDs from their name & namespace
     updateDatatypeUuids(objectMaps);
@@ -30,16 +30,6 @@ module.exports = {
 
   // Returns the count of all objects in the objectMap
   retrieveObjectMapCount: retrieveObjectMapCount,
-
-  // Sorts the namespaces by their relative lengths
-  sortNamespaces: function (namespaceCollector) {
-    return lodash.flatten([
-      Object.keys(namespaceCollector).indexOf(cons.noNamespace) >= 0 ? cons.noNamespace : [],
-      lodash.sortBy(lodash.difference(Object.keys(namespaceCollector), [cons.noNamespace]).sort(), function (namespace) {
-        return namespace.split("_").length;
-      }),
-    ]);
-  },
 };
 
 // ---------------------------------------------------
@@ -54,7 +44,7 @@ function initObjectMaps(objectMaps) {
 }
 
 // Extracts the name, uuid, etc. from a single object file
-function extractObProps(objectMaps, uuidCollector, namespaceCollector, fileCount, obPath, usageType) {
+function extractObProps(objectMaps, uuidCollector, fileCount, obPath, usageType) {
   fileCount.count = fileCount.count + 1;
   const obType = util.getFolderName(obPath);
   let isParsed = false;
@@ -80,13 +70,6 @@ function extractObProps(objectMaps, uuidCollector, namespaceCollector, fileCount
         }
       });
 
-      // Get the namespace of the object
-      let objectName = builder[obProps.fieldNames.NAME];
-      let objectNamespace = extractObjectNamespace(objectName);
-      if (Object.keys(namespaceCollector).indexOf(objectNamespace) == -1) {
-        namespaceCollector[objectNamespace] = { newNamespace: null };
-      }
-
       // Set the object metadata in the objectMaps
       objectMaps[haulType.haulName].push({ current: builder });
       isParsed = true;
@@ -95,7 +78,7 @@ function extractObProps(objectMaps, uuidCollector, namespaceCollector, fileCount
 
   // Unknown file type
   if (!isParsed) {
-    util.printWarning(`WARNING: Unknown object type in package: ${obType}/${path.basename(obPath)}`);
+    util.printWarning(`Unknown object type in package: ${obType}/${path.basename(obPath)}`);
   }
 }
 
@@ -116,26 +99,28 @@ function updateDatatypeUuids(objectMaps) {
 }
 
 // Returns the count of all objects in the objectMap
-function retrieveObjectMapCount(objectMaps) {
+function retrieveObjectMapCount(objectMaps, namespacesFilter) {
   let count = 0;
   Object.keys(objectMaps).forEach(key => {
-    count = count + objectMaps[key].length;
+    if (util.isBlank(namespacesFilter)) {
+      count = count + objectMaps[key].length;
+    } else {
+      let countMatchingObjects = lodash.filter(objectMaps[key], function (objectMap) {
+        let isMatch = false;
+        for (const namespace of namespacesFilter) {
+          if (util.doesNameMatchNamespace(objectMap["current"][obProps.fieldNames.NAME], namespace)) {
+            isMatch = true;
+            return true;
+          }
+          return isMatch;
+        }
+      }).length;
+      count = count + countMatchingObjects;
+    }
   });
   return count;
 }
 
-// Returns the namespace from an object name
-function extractObjectNamespace(objectName) {
-  // See regex here with test cases: https://regexr.com/6trnd
-  let namespaceRegex = new RegExp(`^(?:[A-Z0-9]*${cons.namespaceDelimiterRegex}?){0,3}(?=${cons.namespaceDelimiterRegex})`, "g");
-  let namespaceMatch = util.firstMatch(objectName, namespaceRegex, null);
-  if (namespaceMatch) {
-    return namespaceMatch.replace(new RegExp(cons.namespaceDelimiterRegex, "g"), "_");
-  } else {
-    return cons.noNamespace;
-  }
-}
-
 // Utility function to differenciate between debug logging and real logging
 function debug(input) {
   console.log(input);

package/src/handlers/objectMapsUpdateHandler.js

@@ -5,15 +5,15 @@ const lodash = require("lodash");
 const util = require("../util");
 const cons = require("../cons");
 const obProps = require("../objectProps");
-const obExtract = require("./objectExtractHandler");
+const obExtract = require("../handlers/objectExtractHandler");
 const { remove } = require("fs-extra");
 
 // Exports
 module.exports = {
   // Goes through all of the objectMaps and creates new name, uuid, etc.
-  renameObjectMaps: function (objectMaps, uuidCollector, namespaceCollector, usageType) {
+  renameObjectMaps: function (objectMaps, uuidCollector, namespaceMap, usageType) {
     // Update all objectMaps with new names
-    renameObjectMaps(objectMaps, uuidCollector, namespaceCollector, usageType);
+    renameObjectMaps(objectMaps, uuidCollector, namespaceMap, usageType);
   },
 };
 
@@ -22,12 +22,11 @@ module.exports = {
 // ---------------------------------------------------
 
 // Goes through all of the objectMaps and creates new name, uuid, etc.
-function renameObjectMaps(objectMaps, uuidCollector, namespaceCollector, usageType) {
+function renameObjectMaps(objectMaps, uuidCollector, namespaceMap, usageType) {
   obProps.haulTypes.forEach(haulType => {
     objectMaps[haulType.haulName].forEach(function (objectMap, objectMapIndex) {
-      let curNamespaceForObject = findNamespaceForObject(objectMap["current"][obProps.fieldNames.NAME], namespaceCollector);
-      let newNamespaceForObject = namespaceCollector[curNamespaceForObject]["newNamespace"];
-      if (util.isBlank(newNamespaceForObject)) {
+      let curNamespaceForObject = findNamespaceForObject(objectMap["current"][obProps.fieldNames.NAME], namespaceMap);
+      if (Object.keys(namespaceMap).indexOf(curNamespaceForObject) < 0) {
         // Object will not be cloned
         objectMaps[haulType.haulName][objectMapIndex]["new"] = objectMap["current"];
         haulType.fields.forEach(haulField => {
@@ -37,6 +36,7 @@ function renameObjectMaps(objectMaps, uuidCollector, namespaceCollector, usageTy
           }
         });
       } else {
+        let newNamespaceForObject = namespaceMap[curNamespaceForObject]["newNamespace"];
         // Object will be cloned
         objectMaps[haulType.haulName][objectMapIndex]["new"] = {};
         haulType.fields.forEach(haulField => {
@@ -129,9 +129,9 @@ function buildNamespaceReplacementRegex(curNamespace, newNamespace, regexTags) {
 }
 
 // Returns the namespace for an object
-function findNamespaceForObject(objectName, namespaceCollector) {
-  for (const namespace of obExtract.sortNamespaces(namespaceCollector).reverse()) {
-    if (objectName.replace(new RegExp(cons.namespaceDelimiterRegex, "g"), "_").startsWith(namespace)) {
+function findNamespaceForObject(objectName, namespaceMap) {
+  for (const namespace of util.sortNamespaces(Object.keys(namespaceMap)).reverse()) {
+    if (util.doesNameMatchNamespace(objectName, namespace)) {
       return namespace;
     }
   }

package/src/util.js

@@ -57,7 +57,9 @@ module.exports = {
 
   // Validates the new namespace is only letters and numbers with no whitespace
   validateNamespace: function (namespace) {
-    if (!namespace.match(/^\b(?:[A-Za-z0-9]+_?)+\b$/g) && !isBlank(namespace)) {
+    if (isBlank(namespace)) {
+      return `Namespace cannot be null`;
+    } else if (!namespace.match(/^\b(?:[A-Za-z0-9]+_?)+\b$/g) && !isBlank(namespace)) {
       return `Namespace can only be sets of uppercase letters and numbers separated by underscores`;
     } else {
       return true;
@@ -308,7 +310,19 @@ module.exports = {
 
   // Prints a wanring in color
   printWarning: function (log) {
-    colorlog.color("yellow").log(log);
+    colorlog.color("yellow").log(`WARNING: ${log}`);
+  },
+
+  // Returns true if the string matches the namespace
+  doesNameMatchNamespace: function (name, namespace) {
+    return name.replace(new RegExp(cons.namespaceDelimiterRegex, "g"), "_").startsWith(namespace);
+  },
+
+  // Sorts an array of namespaces by their delimited length, then alphabetically
+  sortNamespaces: function (namespaces) {
+    return lodash.sortBy(namespaces.sort(), function (namespace) {
+      return namespace.split("_").length;
+    });
   },
 };