Node.js: apn-app-manager

apn-app-manager is a command line tool that ingests an Appian application zip file, makes changes to the underlying XML files, and outputs a new Appian application zip file. It currently supports cloning an application.

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.

Disclaimer

The functionality provided by this tool is not supported, nor endorsed by Appian. It is merely a community tool to manipulate XML files following strict rules. The structure of these XML files may change between Appian platform releases, and those changes may break this tool.

Importing an application export modified by this tool should be done at your own discretion.

Latest compatible Appian platform version tested against: 23.3.

Installation

1. Download and install the latest version of node if you don't already have it.
2. Globally install or upgrade on your local machine in your favorite command-line terminal via command .
   • npm i -g apn-app-manager
3. Check installation or your current version of this tool by running npm list -g.
4. 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 can Google related to the npm "prefix" config. To fix this, the command is npm config set prefix _, where the _ is specific to your operating system. Here are helpful links to troubleshoot for Windows and Mac.

Usage

1. Download any Appian application zip and navigate to the folder containing the download in your favorite command-line terminal.
2. 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.
2. Select clone for "What would you like to do?".
3. Select your application zip.
4. Select your import customization properties file, if you have one.
5. Choose advanced options or not:
   • Regular options:
     1. Enter your current namespace.
     2. Enter your new namespace.
        • 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. The tool will search through all object files and attempt to find every unique namespace, allowing you to specify cloning logic for each namepsace.
     2. Database tables can be skipped during cloning.
6. 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.
2. 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.
3. 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).
4. 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.
   • not-cloned-uuids.json - Warnings may appear during cloning about UUIDs in the package that the tool didn't know how to handle, which will be listed in this file. If no warnings appeared, this file will be empty. 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 Appian platform releases. Please reach out to the authors of this tool if you have any questions about this.

License

Licensed under Apache 2.0