apn-app-manager 0.1.6 → 0.2.0

package/README.md

@@ -1,60 +1,57 @@
 # Node.js: apn-app-manager
 
-`apn-app-manager` is a command line tool for managing Appian applications
+`apn-app-manager` is a command line tool for managing Appian applications.
 
 ## Why?
 
-Todo...
+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.
+
+## Disclaimer
+
+The functionality provided by this tool is not supported nor endorsed by Appian. It is merely a tool to manipulate XML files following strict rules. The structure of these XML files will change between platform releases, and that may break this tool.
+
+Importing an application export modified by this tool should be done at your own discretion.
+
+Latest compatible Appian platform version for which we've tested against: **22.3**.
 
 ## Installation
 
-1. Download and install [the latest version of node](https://nodejs.org/en/download/) if you don't already have it
-1. Clone this repository
-1. Navigate to `[repo]\node\app-manager` in your command line
-1. Run `npm i`
-1. Run `npm link`
-
-## Building Solutions Application Package
-
-1. First, ensure you have the latest version of this package installed. Within your Git tool, fetch and pull the latest version from master.
-2. Open up your command line and run the command `apn package --prefix <prefix>` where `<prefix>` should be one of the following:
-   - `IO` - Institutional Onboarding
-   - `KYC` - Know your Customer
-   - `RM` - Requirements Management
-   - `WS` - Workforce Safety
-   - `AM` - Award Management
-   - `MS` - (GAM) Management Suite
-3. This should begin the packaging process, and once complete, all of the files will be available to import into your test environment in a new folder called `/out` which will be inside of the folder in which you ran the command
-   - To wipe the existing database tables, first run the SQL file that contains the word `WIPE`, then the other SQL file
-
-#### Notes regarding packaging
-
-- **Important** If the package script fails (it will be obvious), then navigate to the folder in your file explorer, delete the newly generated folder called `out`, and just re-run the packaging command.
-- The little metrics about how many files are mapped/updated are currently inaccurate. Don't pay them attention at this time.
-
-## Renaming Objects in Bulk (currently broken)
-
-1. Download an application package of objects you'd like to rename
-   - If you are renaming CDTs, ensure that all direct dependents of the CDTs are also included in the application package
-1. Navigate to the folder containing the application package in your command line
-1. Run `apn r`
-   - If this doesn't work, there was likely an issue when running `npm link` above
-1. Follow the prompts to select the application package and provide the new namespace
-   - If you are not renaming to a new namespace, just provide the same value for current and new namespace
-1. Modify the Excel file (appears in a new `/out` directory) with the new names for names, descriptions, and any other values
-   - DO NOT modify the structure of the Excel file or modify any columns that do not end in `_new`
-1. Save the Excel file and the resultant application package will appear in the new `/out` directory
-1. Import your new application package to your environment, including [force_update\_.properties](resources/force_update_.properties) as the properties file to ensure the objects are updated
-
-#### Notes regarding renaming
-
-- It is recommend to always test the import against a sandbox site (e.g. CI site) before importing to your actual site - At worst, the tool may not perform as expected, however it shouldn't corrupt any files - For the future notes about unsupported behavior, you can always try it out and see if it works ¯\\_(ツ)_/¯
-- The prompt for current and new namespace will auto-replace all instances of the current namespace to the new namespace, and is meant to be a shortcut to common renaming use cases - As mentioned above, providing the same value for current and new namespace will result in nothing being auto-renamed prior to the Excel output
-- Renaming multiple objects that currently have the same name to each have different names is not currently supported - e.g. Changing the name of a data store entity and a CDT, which are currently the same, to be different - This INCLUDES setting the description on a number of objects whose description is currently null
-- Description fields with special characters (&, carriage returns, etc) are not currently supported
-- Be careful if renaming any fields that are array types (such as data store entity names), maintain the exact same delimination as exists in the Excel file
-- CDTs cannot actual be renamed, instead new CDTs will be created with the new names, and you'll have to manually delete the old CDTs (all references should be updated)
+1. Download and install [the latest version of node](https://nodejs.org/en/download/) if you don't already have it.
+1. Globally install or upgrade on your local machine in your favorite command-line terminal via command .
+   - `npm i -g apn-app-manager`
+1. Check installation or your current version of this tool by running `npm list -g`.
+1. After installing, you should have access to the command `apn` globally in your terminal.
+   - If this command is not recognized, you will need to troubleshoot. Since this is machine-specific, it's something you may have to google related to the npm "prefix" config. Here are helpful links to troubleshoot for [Windows](https://www.google.com/search?q=npm+global+command+not+found+windows) and [Mac](https://www.google.com/search?q=npm+global+command+not+found+mac).
+
+## Usage
+
+1. Download any Appian application zip and navigate to the folder containing the download in your favorite command-line terminal.
+1. Run the command `apn` and follow the prompts to modify the application.
+
+Currently this tool only supports cloning applications, although more functionality may come in future releases.
+
+### Cloning
+
+Used to duplicate all objects of an application, which replaces the namespace of each object with a new namespace and generates unique UUIDs for each new object.
+
+#### Steps
+
+1. Run the command `apn` in a folder containing your exported application zip.
+1. Select `clone` for "What would you like to do?".
+1. Select your application zip.
+1. Enter your current namespace.
+   - For example, an application with objects such as `SMP APP Artifacts` and `SMP_APP_displayUser` would have a namespace of `SMP_APP`
+1. Enter your new namespace.
+1. Access your cloned application in the generated `/out/` folder.
+
+#### Notes
+
+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. Warnings may appear during cloning around UUIDs that weren't recognized. Generally these can be ignored if your inspection looks good, however these may be actual issues that come up due to XML structure changes in future releases. Please reach out to the authors of this tool if you have any questions about this.
+1. Import properties files and SQL files for your application are not supported at this time. These will have to be adjusted manually to align with the cloned objects.
 
 ## License
 
-Todo...
+Licensed under [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt)