Deployment Automation

Appian Max Team — Tue, 23 Apr 2024 13:21:43 GMT

Current Revision posted to Guide by Appian Max Team on 4/23/2024 1:21:43 PM

Appian provides several DevOps tools to automate the deployment of Appian applications such as Compare & Deploy and Deployment APIs.

The Deployment APIs offer a set of API endpoints that allow you to inspect and deploy applications, packages, import customization files, plug-ins, and execute database scripts. These APIs allow you to programmatically trigger deployments and integrate your Appian release into an automated pipeline. You can set up your pipeline once and run it the exact same way for all future deployments, saving time and avoiding manual errors. It is recommended to use the Deployment APIs whenever possible.

The tools described in this play offer a few alternatives to Appian base product features:

Tightly integrate with a version control system to store and retrieve package files using the Automated Versioning Manager (AVM)
Programmatically deploy Admin Console settings and applications using the Automated Import Manager (AIM) plug-in and the Automated Import Manager (AIM) client

Automated Versioning Manager

Summary

The Automated Versioning Manager - available on the Appian AppMarket - is a tool that helps managing Appian applications and database DDL files in a version control system. Given an Appian application ZIP file, the Automated Versioning Manager performs the following actions:

It unzips the application and organizes the artifact XML files in the repository.
It automates the check-in and checkout operations with the version control system.
It generates application packages for import in Appian based on the contents of the repository and a range of changes to include.

The goal of this tool is to facilitate the adoption and usage of a version control system to perform configuration management of the Appian applications and database DDL files.

Features

Version Control integration (Git, SVN)
Supports Appian applications and patches
Generate import package from hash ranges
Folder Listener to add contents to Version Control
Supports GitHub, GitLab, and BitBucket for Version Control

Usage

The automated versioning tool is a script to be run from the command line or terminal. It contains a wrapper for Windows (version-application.bat) and Linux (version-application.sh) systems. This document will first discuss how to use the tool in general, and then discuss use cases to give concrete examples. All parameters can be passed either on the command line or in the properties file.

Script Execution

To run the script, open a command window and navigate to the directory where the automated versioning scripts are located. They are named version-application.bat or version-application.sh.

Use the -h or -help parameters to view the help menu within the script. The parameters are described here:

Required Parameters (required for all four actions: addContents, buildAllApps, buildSingleApp, buildMultipleApps, and updateLocalRepo)
- -action - Selects which action of the script to run. Acceptable values are: addContents, updateLocalRepo, buildAllApps, buildSingleApp, and buildMultipleApps. Each action is detailed in the use cases below.
- -vc_username -The username associated with the version control (Git or SVN) account. NOTE: these are NOT your Appian credentials.
- -vc_password -Please check the Security Settings of the version control account. If you have 2-factor authentication enabled, the password requires the version control account token. If you do NOT have 2-factor authentication enabled, the password is the one associated with the version control account. NOTE: these are NOT your Appian credentials.
Options for addContents action
- -application_path - The path on your filesystem where the application ZIP is located.
- -admin_console_path - The path on your filesystem where the admin console ZIP file is located.
- -ddl_path - List of comma-separated paths for the DDL files to be included in the deployment package.
- -flyway_path - List of comma-separated paths for the directories to execute DB migrations via Flyway. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions. To learn how the Automated Import Manager uses Flyway, refer to AIM Features.
- -ddl_ds - List of comma-separated datasources associated with the provided DDL files. Must provide the same number of entries as number of DDL files specified with the -ddl_path option or number of directories specified with the -flyway_path option. NOTE: the order of the specified datasource names must match the order of the script paths specified.
- -uuid - The UUID of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -application_name - The name of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -commit_message - The message that will be associated with the commit. If not included, a default commit message Committed by @username is provided.
Options for buildAllApps action
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildSingleApp action
- -uuid - The UUID of the application you want to build.
- -application_name - The name of the application you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildMultipleApps action
- -uuid - Comma separated list of UUIDs of the applications you want to build.
- -application_name - Comma separated list of names of the applications that you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for updateLocalRepo action
- There are no additional options (other than required options) for updateLocalRepo.
Additional Parameters - These parameters are REQUIRED, and may be specified here or in the properties file (described in the following section). If they are specified in both locations, the parameters specified in the command line take precedence.
- -version_control_type - The version control type used, either GIT or SVN.
- -local_repo_path - The path on the filesystem where the local repository is located. All files on the remote repository are cloned to this path. Example: C:\\MyFiles\\ChangeManagementRepo. NOTE: if using Windows, be sure to include double forward slashes (as seen in the example) for path separation.
- -appian_objects_repo_path - Path to the folder containing the Appian objects in the repository. This path is relative to the path of the local repository. If not specified, the Appian objects are checked out to and committed from the root of the local repository path.
- -repo_url - The URL that defines the remote repository. Example: https://github.com/git-username/project-name.git, svn+ssh://svn.code.sf.net/p/project-name/code
- -package_path - For buildAllApps, buildSingleApp, and buildMultipleApps only. The path on the filesystem where packages are generated. Must include filename of package.
- -branch_name - Branch to check out and use (if not master)

Configuring using the Properties File

The tool also provides the ability to specify all parameters in the configuration file version-manager.properties. The default file bundled with the script contains all the options commented out. To use the file, uncomment the necessary options and specify the appropriate values.

In case an option is specified both on the command line and in the properties file, the command line value takes precedence and is used.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

If used, the property appianObjectRepoPath must not reference a file path more than one level below the root directory of the repository. Ex. appianObjectRepoPath = /appian/objects is an acceptable configuration but appianObjectRepoPath = /appian/folder/objects is not valid.

Use Cases

#1: New developer joins team (updateLocalRepo)

In this use case, a new developer has joined the team and wants to get a copy of all the work completed so far. The developer should:

Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using updateLocalRepo as the action flag. The developer must provide the username and password for authenticating against their version control system (-vc_username, -vc_password).

Example Syntax:

> version-application -action updateLocalRepo -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD>

When the script is executed, the developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).

#2: Developer adds artifacts to the repository (addContents)

In this use case, the developer on a team has been working in the development environment and has changes he wishes to add to the repository. The changes may be a new application or a patch to an existing application. Note: the repository serves as a record of changes, and can be thought of as an additional Appian environment. The steps involved are:

In the Appian development environment, create an application (or a patch) that contains the changed objects.
Export those changes and download the application ZIP file.
Run the script, using addContents as the action flag. The developer must provide the path of the ZIP file they exported (-application_path) from Appian in step 2. They must also provide the username and password for authenticating their version control system (-vc_username, -vc_password). NOTE: these are NOT Appian credentials.
1. Optional: if the application specified for -application_path is a patch, update the -uuid option to specify the parent application’s uuid. The script will exit with error if a patch application ZIP is provided but no uuid is passed in.
2. Optional: if DDL scripts have been modified, specify the path(s) and their associated JDBC datasource names. NOTE: The same number of DDL scripts and datasource names must be entered into the script, even if the datasource is the same for all scripts. For example: the developer wishes to add two ddl scripts located at C:\DDLs\script1.sql and C:\DDLs\script2.sql. They do so by setting the -ddl_path option as C:\DDLs\script1.sql,C:\DDLs\script2.sql If both scripts are to be executed on jdbc/AppianDS, they must set the -ddl_ds option as jdbc/AppianDS,jdbc/AppianDS. Note that the datasource name is passed in twice.
Optional: include a custom commit message using the -commit_message option

WARNING: It is HIGHLY recommended that DDL scripts are developed INCREMENTALLY. That is, do not modify existing DDL scripts - instead, create new scripts that only contain the commands the designer wishes to execute.This is because if the designer updates an existing DDL script, all lines in the script will be executed. This can lead to data integrity issues if not managed properly. PLEASE EXERCISE CAUTION WHEN MODIFYING EXISTING DDL SCRIPTS. Example: if the designer modifies a script that contains commands to drop and recreate a table, the script will drop and recreate the table even if the designer did not modify that section.

Example Syntax:

> version-application -action addContents -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -application_path "C:\App.zip" -ddl_ds jdbc/AppianAnywhere -ddl_path “C:\script1.sql” -commit_message “Adding account executive record”

When the script is executed, three things occur:

The developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).
The application ZIP is unzipped and placed into the local repository, and the DDL files are placed into a ddl_files folder within the local repository. If the -uuid option is selected, the appropriate application xml file is updated.
The changes are committed (and pushed, if using Git) to the remote repository.

When the package is imported into Appian, all lines within script1.sql will be executed and contents within the application ZIP are imported.

Using Folder Listener:

Alternatively, instead of running the script, the developer can execute avm-folder-listener-<os> in the folder-listener directory. The following command prompt will appear:

The developer will provide the directory that the application or patch ZIPs will be dropped into as well as the directory of the automated versioning manager tool. Otherwise, the default directories will be used.

Once setup, the developer can drag the desired application ZIP into the specified directory and the application ZIP will be versioned in their GIT repository. This is assuming that all necessary fields have already been configured in the file version-manager.properties.

If the developer is supplying a patch ZIP, the console will prompt the developer for the associated application uuid or name. Once supplied, the patch will be deployed to the specified environment in the file version-manager.properties.

#3: Build master generates new RC deployment package (buildAllApps)

In this use case, all additions made by the team have been incorporated into the remote repository and have gone through sufficient testing. The build master is now ready to promote a new package to the higher environment. The new package should include all additions and changes since the last deployment. The build master will:

(If not done previously) Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using buildAllApps as the action flag. The build master must provide the username and password for authenticating against their version control system (-vc_username, -vc_password). To get a specific set of changes, input a value for the -start_hash option and the -end_hash option. This will generate the package with all new and changed files between the two hash options.
1. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.

Example Command:

> version-application -action buildAllApps -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -start_hash ac37459 -end_hash 6e83b42

When the script is executed, it generates a package at the location specified by the packagePath field in version-manager.properties.

Finally, the build master will import the RC package into the higher environment using the Automated Import tool as described later in this play.

Using Subversion as Version Control System

To allow the Automated Versioning Manager to perform the checkout and commit operations with Subversion, the tool assumes the common Subversion project structure:

trunk
branches
tags

The location of the repository root must be provided by the property repoURL.

Example: The following version-manager.properties configuration checks out the release 1 branch from the repository located at https://svn.code.sf.net/p/deploymentautomationexample/code and commit all changes to the branch "release1". Optionally, you may specify each of these parameters as command line arguments instead of using the version-manager.properties file.

versionControlType=SVN

repoUrl=https://svn.code.sf.net/p/deploymentautomationexample/code

branchName=branches/release1

Using Git as Version Control System

To use Git with the Automated Versioning Manager, properties may be specified on the command line or version-manager.properties should be updated as follows:

versionControlType=GIT

repoUrl=https://github.com/gituser/testgitrepo.git

branchName=newbranch

branchName is an optional field. If the branch does not exist remotely, the tool will automatically create it on the local machine and push it to the remote repository as soon as addContents is executed.

Note: if you are planning to check out a private repository, use the Git SSH URL rather than the HTTPS URL.

Automated Import Manager

Summary

With the Cloud-approved Appian Automated Import Manager plug-in and the Automated Import Manager client available on the AppMarket, users can automatically deploy applications and patch contents (either applications from Appian OR packages generated from the Automated Versioning Manager) to any environment. Users will have three options for deployment: the tool can either deploy from the tool’s user interface in one click, trigger the deployment from an external CI tool, or deploy from the command line.

The Automated Import Manager automates the process of inspecting the application, executing DDL scripts, updating CDTs, republishing the appropriate datastores, and importing the application.

Features

Inspect Application: This tool will automatically mimic the "Inspect" functionality that exists within Appian
Validating Application Content: In addition to inspecting the application, the tool will ensure all CDT dependents are included to avoid objects pointing to older versions.
Execute DDL Scripts: DDL scripts can be uploaded and automatically executed. NOTE: For Microsoft SQL Server, only Transact-SQL statements are valid.
Execute Migrations with Flyway: Flyway is a tool used for managing database migrations. It makes it easier to track SQL script versions and not re-execute SQL scripts that have already been run. If a Flyway directory is provided, the Automated Import Manager will automatically execute migrations against the corresponding datasource. Learn more about Flyway here.
Update CDTs: Users are no longer required to delete CDTs before updating them, this tool will perform this step automatically
Import Application and admin console configuration: Automatically import an application with an optional customization file
Republish Datastores: After application import, datastores will be automatically published or republished
Add Patches: Automatically add patch contents to a specified existing application

Usage

Deploy from the Web Browser UI

The tool collects usage metrics by default. To opt-out of metrics collection, check the below option on the Web Browser UI:

Log into Appian as a system administrator
Navigate to the Deployment Automation UI available at the URL: <appian>/suite/plugins/servlet/deploymentautomation
Upload the patch or application you wish to import.
If this application is a patch, select the parent application to which patch contents should be added.
If the new application requires changes to the database schema (i.e. new or updated CDTs) you must choose one of the following:
1. Upload the corresponding DDL script(s) that accurately reflect these additions and/or updates.
2. Set the datastore to "Automatically update database schema" and set "Allow Database Schema Changes Through Data Stores" in the Deployment section of the Appian Administration Console
Click on the button "Start Deployment".
During the deployment, the screen is automatically refreshed every 5 seconds with the latest status of the deployment.
When the deployment is complete, the browser will update with a status page.

Deploy from the Command Line Script

The command line script - the client - can be downloaded from the Appian AppMarket.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Open a command window in the same folder to which the client script and supporting libraries were unzipped.
Using the help guide pictured above, run the proper command to automatically import the application. Use -h or -help to view this menu at any time.
1. -ac_customization_path: Indicates the path to the customization file to use when deploying the admin console package or the application package.
2. -admin_console_path: Indicates the path to the admin console file to deploy. NOTE: Use quotations around the entry.
3. -application_path: Indicates the path to the application file to deploy. NOTE: Use quotations around the entry.
4. -ddl_ds: Optional, use only if providing DDL scripts. The name of the datasource to use with the corresponding DDL script. Use a comma separator to enter multiple datasources.
5. -ddl_path: Optional, use only if providing DDL scripts. Indicates the path to the DDL scripts to execute. Use a comma separator to enter multiple DDL script paths. NOTE: Use quotations around the entry.
6. -flyway_path: Optional, use only if providing directories to execute DB migrations via Flyway. Use a comma separator to enter multiple directory paths. NOTE: Use quotations around the entry. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions.
7. -force_import: A boolean flag which specifies whether or not the import ignores impact analysis results.If true, the import will occur even if objects with CDT references are missing
8. -import_customization_path: Indicates the path to the import customization file to use
9. -inspect_only: Optional, use to run an inspection of the package. Indicates the package should not be deployed but inspected only.
10. -password: Password of the Appian user account
11. -proxy_port: Optional, port of the proxy server to use to connect to Appian. This parameter is only used if the parameter -proxy_url is defined. The default value is 8080.
12. -proxy_url: Optional, URL of the proxy to use to connect to Appian.
13. -url: URL of the environment, of the format https://example.appian.com/suite.
14. -username: Username of the Appian user account to use for deployment
15. -uuid: UUID of the application to which patch contents will be added
Deploy the application by typing the command deploy-application.bat and including the relevant parameters. Your command will look something like the one pictured below.

deploy-application.bat -application_path "PATH TO APPLICATION ZIP" -username SERVICE_ACCOUNT_USERNAME -password SERVICE_ACCOUNT_PASSWORD -url APPIAN_URL -ddl_path "PATH TO DLL 1, PATH TO DLL 2" -ddl_ds jdbc/Appian1,jdbc/Appian2

The tool also provides the ability to specify all parameters in the configuration file import-manager.properties. The default file bundled with the script contains all the options commented out. To use the file, uncomment the necessary options and specify the appropriate values.

During the deployment, the prompt is automatically refreshed every 5 seconds with the latest status of the deployment. When the deployment is complete, a status response (like the one pictured below) will display.

Deploy from an External Continuous Integration tool

Additional Requirement:

An existing external Continuous Integration tool (such as Jenkins or Hudson) that is properly configured

The steps below provide the high level steps to deploy an application from Jenkins.

Create a new external job
Configure the job to run the import script using the guidance in Deployment Option #2 listed above
Execute the job

When the deployment is complete, check the status page verify that the import was successful.

Troubleshooting

Deciphering Script Error Messages

Inspect Failure

If the Automated Import script fails on inspect, please check the error log and inspect log to determine the root cause of the inspect error. Additionally, please refer to the Inspect Package documentation to determine what common inspect issues may arise.

Package Validation Failure

This feature is only for Appian 7.11 and above. If the Automated Import script fails during package validation, this means that objects with certain CDT dependencies are missing. Please check the error message which will include the list of missing required dependencies. Appian recommends to include these dependencies in the application prior to importing.

In case you want to proceed with deploying the application regardless of missing CDT dependencies, use the flag -f.

Import Failure

If the Automated Import script fails during import, it will produce an error log that contains the reason(s) for import failure. Please refer to the Application Deployment Guidelines documentation on import issues to determine the root cause of the import failure.

Invalid Credentials

Please ensure that these credentials are associated with an active Appian system administrator account. Basic user credentials cannot be used.

Connection Refused With Deployment Command Line Script

A "Connection Refused" error could be the result of using the wrong URL when executing the script. The URL provided as a parameter must:

include the suffix "/suite"
Include a port number if not using the port 80 with HTTP or port 443 with HTTPS

Release Notes

September 2021 - Release 2.5.13

Bug Fixes
- Fixed an issue where setting "appianObjectsRepoPath" prevented a package that included a patches.xml file from being processed successfully

March 2021 - Release 2.5.12

Enhancements
- Updated the link to the import log in the ADM servlet after a change was made to the Appian API.
Bug Fixes
- Fixed a bug that was preventing Flyway files from being included in metadata.properties.

September 2020 - Release 2.5.11

Enhancements
- Upgraded Flyway version to 6.5.5 for compatibility with MariaDB.

August 2020 - Release 2.5.10

Enhancements
- Added the ability to dynamically generate the Metadata file for the "buildAllApps" action to reflect only the list of database scripts that are included in the package for a given commit range.
Bug Fixes
- Fixed the interpretation of "appianObjectsRepoPath" on Windows platforms.

December 2019 - Release 2.5.9

Enhancements
- Added DNS proxy support to ADM
- Added DNS proxy support to AIM
- Added DNS proxy support to AVM
- Added support for special characters in passwords in ADM

July 2019 - Release 2.5.8

Bug Fixes
- Fixed the problem with obtaining TransactionManager and creating DataConfiguration against latest the Appian version

April 2019 - Release 2.5.7

Enhancements
- Added commit message prompt to folder listener
Bug Fixes
- Fixed Windows issue with pushing file updates to versioning manager
- Fixed import patch failure not adding newly created objects issue
- Fixed semicolon separator parsing issue

March 2019 - Release 2.5.6

Enhancements
- Added proxy authentication support for import client

February 2019 - Release 2.5.5

Bug Fixes
- Fixed DDL paths bug

January 2019 - Release 2.5.4

Enhancements
- Improved descriptions of errors encountered during deployments
Bug Fixes
- Fixed "Connection Refused" bug when running on a Jenkins server
- Fixed "buildSingleApp" AVM bug when specifying an appianObjectsRepoPath
- Fixed rare "hanging" bug in AIM Client

November 2018 - Release 2.5.3

Enhancements
- Created a reset command for Remote Automated Deployment Manager
Bug Fixes
- Version and Import Metrics Logger Initialized correctly to fix null pointer exception

October 2018 - Release 2.5.2

Enhancements
- Folder listener to auto trigger “Add Contents” action
- Field validation for import and versioning manager properties files
- Usage metrics collection to better understand tool use
- Updated error log messages
Bug Fixes
- ADM UI: Handle apostrophes in app name
- ZIP type validation for Automated Import Manager

September 2018 - Release 2.5.1

Enhancements
- New buildMultipleApps action
- Check version of tools with -v or -version flags
Bug Fixes
- Fixed ADM SQL errors with non-null statements and forward slash as delimiters

August 2018 - Release 2.5.0

Enhancements
- Added Flyway DB version control tool to command line and AIM GUI
- Allow import of DDL scripts or Flyway scripts without an application zip or patch zip
- Added Folder Listener script that will run addContents automatically when a file is dropped into a folder
Bug Fixes
- Added buildAllApps to list of approved actions
- Set inspect_only properly in AIM
- Fixed bug where repo would be cloned into a folder with an incorrect name
- Passed in correct authentication token for buildAllApps and buildSingleApp

August 2018 - Release 2.4.7

Enhancements
- Added "buildSingleApp" action to extract one app from multi app repo
- Renamed "buildPackage" action to "buildAllApps" to better clarify the functionality
Bug Fixes
- Fixed miscellaneous issues with parsing SQL in DDL file
- Mark/reset issue with large customization files

June 2018 - Release 2.4.6

Enhancements
- Added an import-manager.properties file to set default values for importing applications
- Automated versioning manager supports adding a package with multiple patches
Bug Fixes
- Application version UUID is updated when adding patches to a version control
- Import no longer fails when SQL in DDL file contains a ";", "–" or "/**/"

March 2018 - Release 2.4.5

Add support for proxy configuration in the deployment client script with parameters "proxy_port" and "proxy_url"

January 2018 - Release 2.4.4

Bug fixes

January 2018 - Release 2.4.3

Support for Appian 17.4

September 2017 - Release 2.4.2

Support for Appian 17.3
Better handling of end of line characters in the SQL scripts
Support for customization file when deploying an application package

June 2017 - Release 2.4.1

Support for Appian 17.2
Fix defect preventing to execute DB scripts as part of a deployment

January 2017 - Release 2.4.0

Support for Appian 17.1

October 2016 - Release 2.3

Support for Appian 16.3

September 2016 - Release 2.2.9

Automated Import Manager

Successfully deploy application packages containing new Datastore entities and new dependents on these entities.

September 2016 - Release 2.2.8

Automated Versioning Manager

Fixed defect with missing artifacts in package when using START_HASH and END_HASH.

August 2016 - Release 2.2.7

Automated Versioning Manager

Fixed defect with deploying applications and patches containing updated Documents.

August 2016 - Release 2.2.6

Automated Versioning Manager

New parameter no_update to build a package from the local repository without first performing a checkout
New integrity control when checking in applications and patches

August 2016 - Release 2.2.5

Automated Versioning Manager

Fixed defect with deploying applications and patches containing new CDTs and updated CDTs.

June 2016 - Release 2.2.4

Bug fixes.

June 2016 - Release 2.2.3

Include the source code in all modules.

June 2016 - Release 2.2.2

Automated Versioning Manager

Added new parameter appian_objects_repo_path to specify where the Appian artifacts are located in the repository.

May 2016 - Release 2.2.0

Automated Versioning Manager

Added support for admin console packages

Automated Import Manager

Removed update-database-schema to support native product capability of automatic database updates via datastore and administration console.
Updated Web Browser UI style
Removed option for "Automatically update the database schema when publishing the data stores" from the Web Browser UI
Added support for admin console deployments
Added support in command line for inspect_only parameter

March 2016 - Release 2.1.0

Automated Versioning Manager

Added support for input flexibility. Now, the command line for versioning manager supports all possible parameters.
Allowed tags as inputs to start hash and end hash.
Added inputs of the following predefined keywords: FIRST_COMMIT (which maps to first commit ever made) and LAST_COMMIT (the previous commit). NOTE: this is only allowed on the start hash input.

Automated Import Manager

Added support for 16.1.
Added action for "Inspect Only".

Tags: Delivery, Platform

Deployment Automation

Kim Day — Tue, 31 Oct 2023 17:27:09 GMT

Revision 13 posted to Guide by Kim Day on 10/31/2023 5:27:09 PM

Appian provides several DevOps tools to automate the deployment of Appian applications such as Compare & Deploy and Deployment APIs.

The tools described in this play offer a few alternatives to Appian base product features:

Tightly integrate with a version control system to store and retrieve package files using the Automated Versioning Manager (AVM)
Programmatically deploy Admin Console settings and applications using the Automated Import Manager (AIM) plug-in and the Automated Import Manager (AIM) client

Automated Versioning Manager

Summary

It unzips the application and organizes the artifact XML files in the repository.
It automates the check-in and checkout operations with the version control system.
It generates application packages for import in Appian based on the contents of the repository and a range of changes to include.

The goal of this tool is to facilitate the adoption and usage of a version control system to perform configuration management of the Appian applications and database DDL files.

Features

Version Control integration (Git, SVN)
Supports Appian applications and patches
Generate import package from hash ranges
Folder Listener to add contents to Version Control
Supports GitHub, GitLab, and BitBucket for Version Control

Usage

Script Execution

To run the script, open a command window and navigate to the directory where the automated versioning scripts are located. They are named version-application.bat or version-application.sh.

Use the -h or -help parameters to view the help menu within the script. The parameters are described here:

Required Parameters (required for all four actions: addContents, buildAllApps, buildSingleApp, buildMultipleApps, and updateLocalRepo)
- -action - Selects which action of the script to run. Acceptable values are: addContents, updateLocalRepo, buildAllApps, buildSingleApp, and buildMultipleApps. Each action is detailed in the use cases below.
- -vc_username -The username associated with the version control (Git or SVN) account. NOTE: these are NOT your Appian credentials.
- -vc_password -Please check the Security Settings of the version control account. If you have 2-factor authentication enabled, the password requires the version control account token. If you do NOT have 2-factor authentication enabled, the password is the one associated with the version control account. NOTE: these are NOT your Appian credentials.
Options for addContents action
- -application_path - The path on your filesystem where the application ZIP is located.
- -admin_console_path - The path on your filesystem where the admin console ZIP file is located.
- -ddl_path - List of comma-separated paths for the DDL files to be included in the deployment package.
- -flyway_path - List of comma-separated paths for the directories to execute DB migrations via Flyway. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions. To learn how the Automated Import Manager uses Flyway, refer to AIM Features.
- -ddl_ds - List of comma-separated datasources associated with the provided DDL files. Must provide the same number of entries as number of DDL files specified with the -ddl_path option or number of directories specified with the -flyway_path option. NOTE: the order of the specified datasource names must match the order of the script paths specified.
- -uuid - The UUID of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -application_name - The name of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -commit_message - The message that will be associated with the commit. If not included, a default commit message Committed by @username is provided.
Options for buildAllApps action
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildSingleApp action
- -uuid - The UUID of the application you want to build.
- -application_name - The name of the application you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildMultipleApps action
- -uuid - Comma separated list of UUIDs of the applications you want to build.
- -application_name - Comma separated list of names of the applications that you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for updateLocalRepo action
- There are no additional options (other than required options) for updateLocalRepo.
Additional Parameters - These parameters are REQUIRED, and may be specified here or in the properties file (described in the following section). If they are specified in both locations, the parameters specified in the command line take precedence.
- -version_control_type - The version control type used, either GIT or SVN.
- -local_repo_path - The path on the filesystem where the local repository is located. All files on the remote repository are cloned to this path. Example: C:\\MyFiles\\ChangeManagementRepo. NOTE: if using Windows, be sure to include double forward slashes (as seen in the example) for path separation.
- -appian_objects_repo_path - Path to the folder containing the Appian objects in the repository. This path is relative to the path of the local repository. If not specified, the Appian objects are checked out to and committed from the root of the local repository path.
- -repo_url - The URL that defines the remote repository. Example: https://github.com/git-username/project-name.git, svn+ssh://svn.code.sf.net/p/project-name/code
- -package_path - For buildAllApps, buildSingleApp, and buildMultipleApps only. The path on the filesystem where packages are generated. Must include filename of package.
- -branch_name - Branch to check out and use (if not master)

Configuring using the Properties File

In case an option is specified both on the command line and in the properties file, the command line value takes precedence and is used.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Use Cases

#1: New developer joins team (updateLocalRepo)

In this use case, a new developer has joined the team and wants to get a copy of all the work completed so far. The developer should:

Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using updateLocalRepo as the action flag. The developer must provide the username and password for authenticating against their version control system (-vc_username, -vc_password).

Example Syntax:

> version-application -action updateLocalRepo -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD>

When the script is executed, the developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).

#2: Developer adds artifacts to the repository (addContents)

In the Appian development environment, create an application (or a patch) that contains the changed objects.
Export those changes and download the application ZIP file.
Run the script, using addContents as the action flag. The developer must provide the path of the ZIP file they exported (-application_path) from Appian in step 2. They must also provide the username and password for authenticating their version control system (-vc_username, -vc_password). NOTE: these are NOT Appian credentials.
1. Optional: if the application specified for -application_path is a patch, update the -uuid option to specify the parent application’s uuid. The script will exit with error if a patch application ZIP is provided but no uuid is passed in.
2. Optional: if DDL scripts have been modified, specify the path(s) and their associated JDBC datasource names. NOTE: The same number of DDL scripts and datasource names must be entered into the script, even if the datasource is the same for all scripts. For example: the developer wishes to add two ddl scripts located at C:\DDLs\script1.sql and C:\DDLs\script2.sql. They do so by setting the -ddl_path option as C:\DDLs\script1.sql,C:\DDLs\script2.sql If both scripts are to be executed on jdbc/AppianDS, they must set the -ddl_ds option as jdbc/AppianDS,jdbc/AppianDS. Note that the datasource name is passed in twice.
Optional: include a custom commit message using the -commit_message option

Example Syntax:

> version-application -action addContents -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -application_path "C:\App.zip" -ddl_ds jdbc/AppianAnywhere -ddl_path “C:\script1.sql” -commit_message “Adding account executive record”

When the script is executed, three things occur:

The developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).
The application ZIP is unzipped and placed into the local repository, and the DDL files are placed into a ddl_files folder within the local repository. If the -uuid option is selected, the appropriate application xml file is updated.
The changes are committed (and pushed, if using Git) to the remote repository.

When the package is imported into Appian, all lines within script1.sql will be executed and contents within the application ZIP are imported.

Using Folder Listener:

Alternatively, instead of running the script, the developer can execute avm-folder-listener-<os> in the folder-listener directory. The following command prompt will appear:

#3: Build master generates new RC deployment package (buildAllApps)

(If not done previously) Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using buildAllApps as the action flag. The build master must provide the username and password for authenticating against their version control system (-vc_username, -vc_password). To get a specific set of changes, input a value for the -start_hash option and the -end_hash option. This will generate the package with all new and changed files between the two hash options.
1. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.

Example Command:

> version-application -action buildAllApps -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -start_hash ac37459 -end_hash 6e83b42

When the script is executed, it generates a package at the location specified by the packagePath field in version-manager.properties.

Finally, the build master will import the RC package into the higher environment using the Automated Import tool as described later in this play.

Using Subversion as Version Control System

To allow the Automated Versioning Manager to perform the checkout and commit operations with Subversion, the tool assumes the common Subversion project structure:

trunk
branches
tags

The location of the repository root must be provided by the property repoURL.

versionControlType=SVN

repoUrl=https://svn.code.sf.net/p/deploymentautomationexample/code

branchName=branches/release1

Using Git as Version Control System

To use Git with the Automated Versioning Manager, properties may be specified on the command line or version-manager.properties should be updated as follows:

versionControlType=GIT

repoUrl=https://github.com/gituser/testgitrepo.git

branchName=newbranch

Note: if you are planning to check out a private repository, use the Git SSH URL rather than the HTTPS URL.

Automated Import Manager

Summary

The Automated Import Manager automates the process of inspecting the application, executing DDL scripts, updating CDTs, republishing the appropriate datastores, and importing the application.

Features

Inspect Application: This tool will automatically mimic the "Inspect" functionality that exists within Appian
Validating Application Content: In addition to inspecting the application, the tool will ensure all CDT dependents are included to avoid objects pointing to older versions.
Execute DDL Scripts: DDL scripts can be uploaded and automatically executed. NOTE: For Microsoft SQL Server, only Transact-SQL statements are valid.
Execute Migrations with Flyway: Flyway is a tool used for managing database migrations. It makes it easier to track SQL script versions and not re-execute SQL scripts that have already been run. If a Flyway directory is provided, the Automated Import Manager will automatically execute migrations against the corresponding datasource. Learn more about Flyway here.
Update CDTs: Users are no longer required to delete CDTs before updating them, this tool will perform this step automatically
Import Application and admin console configuration: Automatically import an application with an optional customization file
Republish Datastores: After application import, datastores will be automatically published or republished
Add Patches: Automatically add patch contents to a specified existing application

Usage

Deploy from the Web Browser UI

The tool collects usage metrics by default. To opt-out of metrics collection, check the below option on the Web Browser UI:

Log into Appian as a system administrator
Navigate to the Deployment Automation UI available at the URL: <appian>/suite/plugins/servlet/deploymentautomation
Upload the patch or application you wish to import.
If this application is a patch, select the parent application to which patch contents should be added.
If the new application requires changes to the database schema (i.e. new or updated CDTs) you must choose one of the following:
1. Upload the corresponding DDL script(s) that accurately reflect these additions and/or updates.
2. Set the datastore to "Automatically update database schema" and set "Allow Database Schema Changes Through Data Stores" in the Deployment section of the Appian Administration Console
Click on the button "Start Deployment".
During the deployment, the screen is automatically refreshed every 5 seconds with the latest status of the deployment.
When the deployment is complete, the browser will update with a status page.

Deploy from the Command Line Script

The command line script - the client - can be downloaded from the Appian AppMarket.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Open a command window in the same folder to which the client script and supporting libraries were unzipped.
Using the help guide pictured above, run the proper command to automatically import the application. Use -h or -help to view this menu at any time.
1. -ac_customization_path: Indicates the path to the customization file to use when deploying the admin console package or the application package.
2. -admin_console_path: Indicates the path to the admin console file to deploy. NOTE: Use quotations around the entry.
3. -application_path: Indicates the path to the application file to deploy. NOTE: Use quotations around the entry.
4. -ddl_ds: Optional, use only if providing DDL scripts. The name of the datasource to use with the corresponding DDL script. Use a comma separator to enter multiple datasources.
5. -ddl_path: Optional, use only if providing DDL scripts. Indicates the path to the DDL scripts to execute. Use a comma separator to enter multiple DDL script paths. NOTE: Use quotations around the entry.
6. -flyway_path: Optional, use only if providing directories to execute DB migrations via Flyway. Use a comma separator to enter multiple directory paths. NOTE: Use quotations around the entry. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions.
7. -force_import: A boolean flag which specifies whether or not the import ignores impact analysis results.If true, the import will occur even if objects with CDT references are missing
8. -import_customization_path: Indicates the path to the import customization file to use
9. -inspect_only: Optional, use to run an inspection of the package. Indicates the package should not be deployed but inspected only.
10. -password: Password of the Appian user account
11. -proxy_port: Optional, port of the proxy server to use to connect to Appian. This parameter is only used if the parameter -proxy_url is defined. The default value is 8080.
12. -proxy_url: Optional, URL of the proxy to use to connect to Appian.
13. -url: URL of the environment, of the format https://example.appian.com/suite.
14. -username: Username of the Appian user account to use for deployment
15. -uuid: UUID of the application to which patch contents will be added
Deploy the application by typing the command deploy-application.bat and including the relevant parameters. Your command will look something like the one pictured below.

deploy-application.bat -application_path "PATH TO APPLICATION ZIP" -username SERVICE_ACCOUNT_USERNAME -password SERVICE_ACCOUNT_PASSWORD -url APPIAN_URL -ddl_path "PATH TO DLL 1, PATH TO DLL 2" -ddl_ds jdbc/Appian1,jdbc/Appian2

Deploy from an External Continuous Integration tool

Additional Requirement:

An existing external Continuous Integration tool (such as Jenkins or Hudson) that is properly configured

The steps below provide the high level steps to deploy an application from Jenkins.

Create a new external job
Configure the job to run the import script using the guidance in Deployment Option #2 listed above
Execute the job

When the deployment is complete, check the status page verify that the import was successful.

Troubleshooting

Deciphering Script Error Messages

Inspect Failure

Package Validation Failure

In case you want to proceed with deploying the application regardless of missing CDT dependencies, use the flag -f.

Import Failure

Invalid Credentials

Please ensure that these credentials are associated with an active Appian system administrator account. Basic user credentials cannot be used.

Connection Refused With Deployment Command Line Script

A "Connection Refused" error could be the result of using the wrong URL when executing the script. The URL provided as a parameter must:

include the suffix "/suite"
Include a port number if not using the port 80 with HTTP or port 443 with HTTPS

Release Notes

September 2021 - Release 2.5.13

Bug Fixes
- Fixed an issue where setting "appianObjectsRepoPath" prevented a package that included a patches.xml file from being processed successfully

March 2021 - Release 2.5.12

Enhancements
- Updated the link to the import log in the ADM servlet after a change was made to the Appian API.
Bug Fixes
- Fixed a bug that was preventing Flyway files from being included in metadata.properties.

September 2020 - Release 2.5.11

Enhancements
- Upgraded Flyway version to 6.5.5 for compatibility with MariaDB.

August 2020 - Release 2.5.10

Enhancements
- Added the ability to dynamically generate the Metadata file for the "buildAllApps" action to reflect only the list of database scripts that are included in the package for a given commit range.
Bug Fixes
- Fixed the interpretation of "appianObjectsRepoPath" on Windows platforms.

December 2019 - Release 2.5.9

Enhancements
- Added DNS proxy support to ADM
- Added DNS proxy support to AIM
- Added DNS proxy support to AVM
- Added support for special characters in passwords in ADM

July 2019 - Release 2.5.8

Bug Fixes
- Fixed the problem with obtaining TransactionManager and creating DataConfiguration against latest the Appian version

April 2019 - Release 2.5.7

Enhancements
- Added commit message prompt to folder listener
Bug Fixes
- Fixed Windows issue with pushing file updates to versioning manager
- Fixed import patch failure not adding newly created objects issue
- Fixed semicolon separator parsing issue

March 2019 - Release 2.5.6

Enhancements
- Added proxy authentication support for import client

February 2019 - Release 2.5.5

Bug Fixes
- Fixed DDL paths bug

January 2019 - Release 2.5.4

Enhancements
- Improved descriptions of errors encountered during deployments
Bug Fixes
- Fixed "Connection Refused" bug when running on a Jenkins server
- Fixed "buildSingleApp" AVM bug when specifying an appianObjectsRepoPath
- Fixed rare "hanging" bug in AIM Client

November 2018 - Release 2.5.3

Enhancements
- Created a reset command for Remote Automated Deployment Manager
Bug Fixes
- Version and Import Metrics Logger Initialized correctly to fix null pointer exception

October 2018 - Release 2.5.2

Enhancements
- Folder listener to auto trigger “Add Contents” action
- Field validation for import and versioning manager properties files
- Usage metrics collection to better understand tool use
- Updated error log messages
Bug Fixes
- ADM UI: Handle apostrophes in app name
- ZIP type validation for Automated Import Manager

September 2018 - Release 2.5.1

Enhancements
- New buildMultipleApps action
- Check version of tools with -v or -version flags
Bug Fixes
- Fixed ADM SQL errors with non-null statements and forward slash as delimiters

August 2018 - Release 2.5.0

Enhancements
- Added Flyway DB version control tool to command line and AIM GUI
- Allow import of DDL scripts or Flyway scripts without an application zip or patch zip
- Added Folder Listener script that will run addContents automatically when a file is dropped into a folder
Bug Fixes
- Added buildAllApps to list of approved actions
- Set inspect_only properly in AIM
- Fixed bug where repo would be cloned into a folder with an incorrect name
- Passed in correct authentication token for buildAllApps and buildSingleApp

August 2018 - Release 2.4.7

Enhancements
- Added "buildSingleApp" action to extract one app from multi app repo
- Renamed "buildPackage" action to "buildAllApps" to better clarify the functionality
Bug Fixes
- Fixed miscellaneous issues with parsing SQL in DDL file
- Mark/reset issue with large customization files

June 2018 - Release 2.4.6

Enhancements
- Added an import-manager.properties file to set default values for importing applications
- Automated versioning manager supports adding a package with multiple patches
Bug Fixes
- Application version UUID is updated when adding patches to a version control
- Import no longer fails when SQL in DDL file contains a ";", "–" or "/**/"

March 2018 - Release 2.4.5

Add support for proxy configuration in the deployment client script with parameters "proxy_port" and "proxy_url"

January 2018 - Release 2.4.4

Bug fixes

January 2018 - Release 2.4.3

Support for Appian 17.4

September 2017 - Release 2.4.2

Support for Appian 17.3
Better handling of end of line characters in the SQL scripts
Support for customization file when deploying an application package

June 2017 - Release 2.4.1

Support for Appian 17.2
Fix defect preventing to execute DB scripts as part of a deployment

January 2017 - Release 2.4.0

Support for Appian 17.1

October 2016 - Release 2.3

Support for Appian 16.3

September 2016 - Release 2.2.9

Automated Import Manager

Successfully deploy application packages containing new Datastore entities and new dependents on these entities.

September 2016 - Release 2.2.8

Automated Versioning Manager

Fixed defect with missing artifacts in package when using START_HASH and END_HASH.

August 2016 - Release 2.2.7

Automated Versioning Manager

Fixed defect with deploying applications and patches containing updated Documents.

August 2016 - Release 2.2.6

Automated Versioning Manager

New parameter no_update to build a package from the local repository without first performing a checkout
New integrity control when checking in applications and patches

August 2016 - Release 2.2.5

Automated Versioning Manager

Fixed defect with deploying applications and patches containing new CDTs and updated CDTs.

June 2016 - Release 2.2.4

Bug fixes.

June 2016 - Release 2.2.3

Include the source code in all modules.

June 2016 - Release 2.2.2

Automated Versioning Manager

Added new parameter appian_objects_repo_path to specify where the Appian artifacts are located in the repository.

May 2016 - Release 2.2.0

Automated Versioning Manager

Added support for admin console packages

Automated Import Manager

Removed update-database-schema to support native product capability of automatic database updates via datastore and administration console.
Updated Web Browser UI style
Removed option for "Automatically update the database schema when publishing the data stores" from the Web Browser UI
Added support for admin console deployments
Added support in command line for inspect_only parameter

March 2016 - Release 2.1.0

Automated Versioning Manager

Added support for input flexibility. Now, the command line for versioning manager supports all possible parameters.
Allowed tags as inputs to start hash and end hash.
Added inputs of the following predefined keywords: FIRST_COMMIT (which maps to first commit ever made) and LAST_COMMIT (the previous commit). NOTE: this is only allowed on the start hash input.

Automated Import Manager

Added support for 16.1.
Added action for "Inspect Only".

Tags: Delivery, Platform

Deployment Automation

joel.larin — Thu, 26 Oct 2023 18:31:59 GMT

Revision 12 posted to Guide by joel.larin on 10/26/2023 6:31:59 PM

Appian provides several DevOps tools to automate the deployment of Appian applications such as Compare & Deploy and Deployment APIs.

The tools described in this play offer a few alternatives to Appian base product features:

Tightly integrate with a version control system to store and retrieve package files using the Automated Versioning Manager (AVM)
Programmatically deploy Admin Console settings and applications using the Automated Import Manager (AIM) plug-in and the Automated Import Manager (AIM) client

Automated Versioning Manager

Summary

It unzips the application and organizes the artifact XML files in the repository.
It automates the check-in and checkout operations with the version control system.
It generates application packages for import in Appian based on the contents of the repository and a range of changes to include.

The goal of this tool is to facilitate the adoption and usage of a version control system to perform configuration management of the Appian applications and database DDL files.

Features

Version Control integration (Git, SVN)
Supports Appian applications and patches
Generate import package from hash ranges
Folder Listener to add contents to Version Control
Supports GitHub, GitLab, and BitBucket for Version Control

Usage

Script Execution

To run the script, open a command window and navigate to the directory where the automated versioning scripts are located. They are named version-application.bat or version-application.sh.

Use the -h or -help parameters to view the help menu within the script. The parameters are described here:

Required Parameters (required for all four actions: addContents, buildAllApps, buildSingleApp, buildMultipleApps, and updateLocalRepo)
- -action - Selects which action of the script to run. Acceptable values are: addContents, updateLocalRepo, buildAllApps, buildSingleApp, and buildMultipleApps. Each action is detailed in the use cases below.
- -vc_username -The username associated with the version control (Git or SVN) account. NOTE: these are NOT your Appian credentials.
- -vc_password -Please check the Security Settings of the version control account. If you have 2-factor authentication enabled, the password requires the version control account token. If you do NOT have 2-factor authentication enabled, the password is the one associated with the version control account. NOTE: these are NOT your Appian credentials.
Options for addContents action
- -application_path - The path on your filesystem where the application ZIP is located.
- -admin_console_path - The path on your filesystem where the admin console ZIP file is located.
- -ddl_path - List of comma-separated paths for the DDL files to be included in the deployment package.
- -flyway_path - List of comma-separated paths for the directories to execute DB migrations via Flyway. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions. To learn how the Automated Import Manager uses Flyway, refer to AIM Features.
- -ddl_ds - List of comma-separated datasources associated with the provided DDL files. Must provide the same number of entries as number of DDL files specified with the -ddl_path option or number of directories specified with the -flyway_path option. NOTE: the order of the specified datasource names must match the order of the script paths specified.
- -uuid - The UUID of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -application_name - The name of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -commit_message - The message that will be associated with the commit. If not included, a default commit message Committed by @username is provided.
Options for buildAllApps action
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildSingleApp action
- -uuid - The UUID of the application you want to build.
- -application_name - The name of the application you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildMultipleApps action
- -uuid - Comma separated list of UUIDs of the applications you want to build.
- -application_name - Comma separated list of names of the applications that you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for updateLocalRepo action
- There are no additional options (other than required options) for updateLocalRepo.
Additional Parameters - These parameters are REQUIRED, and may be specified here or in the properties file (described in the following section). If they are specified in both locations, the parameters specified in the command line take precedence.
- -version_control_type - The version control type used, either GIT or SVN.
- -local_repo_path - The path on the filesystem where the local repository is located. All files on the remote repository are cloned to this path. Example: C:\\MyFiles\\ChangeManagementRepo. NOTE: if using Windows, be sure to include double forward slashes (as seen in the example) for path separation.
- -appian_objects_repo_path - Path to the folder containing the Appian objects in the repository. This path is relative to the path of the local repository. If not specified, the Appian objects are checked out to and committed from the root of the local repository path.
- -repo_url - The URL that defines the remote repository. Example: https://github.com/git-username/project-name.git, svn+ssh://svn.code.sf.net/p/project-name/code
- -package_path - For buildAllApps, buildSingleApp, and buildMultipleApps only. The path on the filesystem where packages are generated. Must include filename of package.
- -branch_name - Branch to check out and use (if not master)

Configuring using the Properties File

In case an option is specified both on the command line and in the properties file, the command line value takes precedence and is used.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Use Cases

#1: New developer joins team (updateLocalRepo)

In this use case, a new developer has joined the team and wants to get a copy of all the work completed so far. The developer should:

Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using updateLocalRepo as the action flag. The developer must provide the username and password for authenticating against their version control system (-vc_username, -vc_password).

Example Syntax:

> version-application -action updateLocalRepo -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD>

When the script is executed, the developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).

#2: Developer adds artifacts to the repository (addContents)

In the Appian development environment, create an application (or a patch) that contains the changed objects.
Export those changes and download the application ZIP file.
Run the script, using addContents as the action flag. The developer must provide the path of the ZIP file they exported (-application_path) from Appian in step 2. They must also provide the username and password for authenticating their version control system (-vc_username, -vc_password). NOTE: these are NOT Appian credentials.
1. Optional: if the application specified for -application_path is a patch, update the -uuid option to specify the parent application’s uuid. The script will exit with error if a patch application ZIP is provided but no uuid is passed in.
2. Optional: if DDL scripts have been modified, specify the path(s) and their associated JDBC datasource names. NOTE: The same number of DDL scripts and datasource names must be entered into the script, even if the datasource is the same for all scripts. For example: the developer wishes to add two ddl scripts located at C:\DDLs\script1.sql and C:\DDLs\script2.sql. They do so by setting the -ddl_path option as C:\DDLs\script1.sql,C:\DDLs\script2.sql If both scripts are to be executed on jdbc/AppianDS, they must set the -ddl_ds option as jdbc/AppianDS,jdbc/AppianDS. Note that the datasource name is passed in twice.
Optional: include a custom commit message using the -commit_message option

Example Syntax:

> version-application -action addContents -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -application_path "C:\App.zip" -ddl_ds jdbc/AppianAnywhere -ddl_path “C:\script1.sql” -commit_message “Adding account executive record”

When the script is executed, three things occur:

The developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).
The application ZIP is unzipped and placed into the local repository, and the DDL files are placed into a ddl_files folder within the local repository. If the -uuid option is selected, the appropriate application xml file is updated.
The changes are committed (and pushed, if using Git) to the remote repository.

When the package is imported into Appian, all lines within script1.sql will be executed and contents within the application ZIP are imported.

Using Folder Listener:

Alternatively, instead of running the script, the developer can execute avm-folder-listener-<os> in the folder-listener directory. The following command prompt will appear:

#3: Build master generates new RC deployment package (buildAllApps)

(If not done previously) Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using buildAllApps as the action flag. The build master must provide the username and password for authenticating against their version control system (-vc_username, -vc_password). To get a specific set of changes, input a value for the -start_hash option and the -end_hash option. This will generate the package with all new and changed files between the two hash options.
1. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.

Example Command:

> version-application -action buildAllApps -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -start_hash ac37459 -end_hash 6e83b42

When the script is executed, it generates a package at the location specified by the packagePath field in version-manager.properties.

Finally, the build master will import the RC package into the higher environment using the Automated Import tool as described later in this play.

Using Subversion as Version Control System

To allow the Automated Versioning Manager to perform the checkout and commit operations with Subversion, the tool assumes the common Subversion project structure:

trunk
branches
tags

The location of the repository root must be provided by the property repoURL.

versionControlType=SVN

repoUrl=https://svn.code.sf.net/p/deploymentautomationexample/code

branchName=branches/release1

Using Git as Version Control System

To use Git with the Automated Versioning Manager, properties may be specified on the command line or version-manager.properties should be updated as follows:

versionControlType=GIT

repoUrl=https://github.com/gituser/testgitrepo.git

branchName=newbranch

Note: if you are planning to check out a private repository, use the Git SSH URL rather than the HTTPS URL.

Automated Import Manager

Summary

The Automated Import Manager automates the process of inspecting the application, executing DDL scripts, updating CDTs, republishing the appropriate datastores, and importing the application.

Features

Inspect Application: This tool will automatically mimic the "Inspect" functionality that exists within Appian
Validating Application Content: In addition to inspecting the application, the tool will ensure all CDT dependents are included to avoid objects pointing to older versions.
Execute DDL Scripts: DDL scripts can be uploaded and automatically executed. NOTE: For Microsoft SQL Server, only Transact-SQL statements are valid.
Execute Migrations with Flyway: Flyway is a tool used for managing database migrations. It makes it easier to track SQL script versions and not re-execute SQL scripts that have already been run. If a Flyway directory is provided, the Automated Import Manager will automatically execute migrations against the corresponding datasource. Learn more about Flyway here.
Update CDTs: Users are no longer required to delete CDTs before updating them, this tool will perform this step automatically
Import Application and admin console configuration: Automatically import an application with an optional customization file
Republish Datastores: After application import, datastores will be automatically published or republished
Add Patches: Automatically add patch contents to a specified existing application

Usage

Deploy from the Web Browser UI

The tool collects usage metrics by default. To opt-out of metrics collection, check the below option on the Web Browser UI:

Log into Appian as a system administrator
Navigate to the Deployment Automation UI available at the URL: <appian>/suite/plugins/servlet/deploymentautomation
Upload the patch or application you wish to import.
If this application is a patch, select the parent application to which patch contents should be added.
If the new application requires changes to the database schema (i.e. new or updated CDTs) you must choose one of the following:
1. Upload the corresponding DDL script(s) that accurately reflect these additions and/or updates.
2. Set the datastore to "Automatically update database schema" and set "Allow Database Schema Changes Through Data Stores" in the Deployment section of the Appian Administration Console
Click on the button "Start Deployment".
During the deployment, the screen is automatically refreshed every 5 seconds with the latest status of the deployment.
When the deployment is complete, the browser will update with a status page.

Deploy from the Command Line Script

The command line script - the client - can be downloaded from the Appian AppMarket.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Open a command window in the same folder to which the client script and supporting libraries were unzipped.
Using the help guide pictured above, run the proper command to automatically import the application. Use -h or -help to view this menu at any time.
1. -ac_customization_path: Indicates the path to the customization file to use when deploying the admin console package or the application package.
2. -admin_console_path: Indicates the path to the admin console file to deploy. NOTE: Use quotations around the entry.
3. -application_path: Indicates the path to the application file to deploy. NOTE: Use quotations around the entry.
4. -ddl_ds: Optional, use only if providing DDL scripts. The name of the datasource to use with the corresponding DDL script. Use a comma separator to enter multiple datasources.
5. -ddl_path: Optional, use only if providing DDL scripts. Indicates the path to the DDL scripts to execute. Use a comma separator to enter multiple DDL script paths. NOTE: Use quotations around the entry.
6. -flyway_path: Optional, use only if providing directories to execute DB migrations via Flyway. Use a comma separator to enter multiple directory paths. NOTE: Use quotations around the entry. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions.
7. -force_import: A boolean flag which specifies whether or not the import ignores impact analysis results.If true, the import will occur even if objects with CDT references are missing
8. -import_customization_path: Indicates the path to the import customization file to use
9. -inspect_only: Optional, use to run an inspection of the package. Indicates the package should not be deployed but inspected only.
10. -password: Password of the Appian user account
11. -proxy_port: Optional, port of the proxy server to use to connect to Appian. This parameter is only used if the parameter -proxy_url is defined. The default value is 8080.
12. -proxy_url: Optional, URL of the proxy to use to connect to Appian.
13. -url: URL of the environment, of the format https://example.appian.com/suite.
14. -username: Username of the Appian user account to use for deployment
15. -uuid: UUID of the application to which patch contents will be added
Deploy the application by typing the command deploy-application.bat and including the relevant parameters. Your command will look something like the one pictured below.

deploy-application.bat -application_path "PATH TO APPLICATION ZIP" -username SERVICE_ACCOUNT_USERNAME -password SERVICE_ACCOUNT_PASSWORD -url APPIAN_URL -ddl_path "PATH TO DLL 1, PATH TO DLL 2" -ddl_ds jdbc/Appian1,jdbc/Appian2

Deploy from an External Continuous Integration tool

Additional Requirement:

An existing external Continuous Integration tool (such as Jenkins or Hudson) that is properly configured

The steps below provide the high level steps to deploy an application from Jenkins.

Create a new external job
Configure the job to run the import script using the guidance in Deployment Option #2 listed above
Execute the job

When the deployment is complete, check the status page verify that the import was successful.

Troubleshooting

Deciphering Script Error Messages

Inspect Failure

Package Validation Failure

In case you want to proceed with deploying the application regardless of missing CDT dependencies, use the flag -f.

Import Failure

Invalid Credentials

Please ensure that these credentials are associated with an active Appian system administrator account. Basic user credentials cannot be used.

Connection Refused With Deployment Command Line Script

A "Connection Refused" error could be the result of using the wrong URL when executing the script. The URL provided as a parameter must:

include the suffix "/suite"
Include a port number if not using the port 80 with HTTP or port 443 with HTTPS

Release Notes

September 2021 - Release 2.5.13

Bug Fixes
- Fixed an issue where setting "appianObjectsRepoPath" prevented a package that included a patches.xml file from being processed successfully

March 2021 - Release 2.5.12

Enhancements
- Updated the link to the import log in the ADM servlet after a change was made to the Appian API.
Bug Fixes
- Fixed a bug that was preventing Flyway files from being included in metadata.properties.

September 2020 - Release 2.5.11

Enhancements
- Upgraded Flyway version to 6.5.5 for compatibility with MariaDB.

August 2020 - Release 2.5.10

Enhancements
- Added the ability to dynamically generate the Metadata file for the "buildAllApps" action to reflect only the list of database scripts that are included in the package for a given commit range.
Bug Fixes
- Fixed the interpretation of "appianObjectsRepoPath" on Windows platforms.

December 2019 - Release 2.5.9

Enhancements
- Added DNS proxy support to ADM
- Added DNS proxy support to AIM
- Added DNS proxy support to AVM
- Added support for special characters in passwords in ADM

July 2019 - Release 2.5.8

Bug Fixes
- Fixed the problem with obtaining TransactionManager and creating DataConfiguration against latest the Appian version

April 2019 - Release 2.5.7

Enhancements
- Added commit message prompt to folder listener
Bug Fixes
- Fixed Windows issue with pushing file updates to versioning manager
- Fixed import patch failure not adding newly created objects issue
- Fixed semicolon separator parsing issue

March 2019 - Release 2.5.6

Enhancements
- Added proxy authentication support for import client

February 2019 - Release 2.5.5

Bug Fixes
- Fixed DDL paths bug

January 2019 - Release 2.5.4

Enhancements
- Improved descriptions of errors encountered during deployments
Bug Fixes
- Fixed "Connection Refused" bug when running on a Jenkins server
- Fixed "buildSingleApp" AVM bug when specifying an appianObjectsRepoPath
- Fixed rare "hanging" bug in AIM Client

November 2018 - Release 2.5.3

Enhancements
- Created a reset command for Remote Automated Deployment Manager
Bug Fixes
- Version and Import Metrics Logger Initialized correctly to fix null pointer exception

October 2018 - Release 2.5.2

Enhancements
- Folder listener to auto trigger “Add Contents” action
- Field validation for import and versioning manager properties files
- Usage metrics collection to better understand tool use
- Updated error log messages
Bug Fixes
- ADM UI: Handle apostrophes in app name
- ZIP type validation for Automated Import Manager

September 2018 - Release 2.5.1

Enhancements
- New buildMultipleApps action
- Check version of tools with -v or -version flags
Bug Fixes
- Fixed ADM SQL errors with non-null statements and forward slash as delimiters

August 2018 - Release 2.5.0

Enhancements
- Added Flyway DB version control tool to command line and AIM GUI
- Allow import of DDL scripts or Flyway scripts without an application zip or patch zip
- Added Folder Listener script that will run addContents automatically when a file is dropped into a folder
Bug Fixes
- Added buildAllApps to list of approved actions
- Set inspect_only properly in AIM
- Fixed bug where repo would be cloned into a folder with an incorrect name
- Passed in correct authentication token for buildAllApps and buildSingleApp

August 2018 - Release 2.4.7

Enhancements
- Added "buildSingleApp" action to extract one app from multi app repo
- Renamed "buildPackage" action to "buildAllApps" to better clarify the functionality
Bug Fixes
- Fixed miscellaneous issues with parsing SQL in DDL file
- Mark/reset issue with large customization files

June 2018 - Release 2.4.6

Enhancements
- Added an import-manager.properties file to set default values for importing applications
- Automated versioning manager supports adding a package with multiple patches
Bug Fixes
- Application version UUID is updated when adding patches to a version control
- Import no longer fails when SQL in DDL file contains a ";", "–" or "/**/"

March 2018 - Release 2.4.5

Add support for proxy configuration in the deployment client script with parameters "proxy_port" and "proxy_url"

January 2018 - Release 2.4.4

Bug fixes

January 2018 - Release 2.4.3

Support for Appian 17.4

September 2017 - Release 2.4.2

Support for Appian 17.3
Better handling of end of line characters in the SQL scripts
Support for customization file when deploying an application package

June 2017 - Release 2.4.1

Support for Appian 17.2
Fix defect preventing to execute DB scripts as part of a deployment

January 2017 - Release 2.4.0

Support for Appian 17.1

October 2016 - Release 2.3

Support for Appian 16.3

September 2016 - Release 2.2.9

Automated Import Manager

Successfully deploy application packages containing new Datastore entities and new dependents on these entities.

September 2016 - Release 2.2.8

Automated Versioning Manager

Fixed defect with missing artifacts in package when using START_HASH and END_HASH.

August 2016 - Release 2.2.7

Automated Versioning Manager

Fixed defect with deploying applications and patches containing updated Documents.

August 2016 - Release 2.2.6

Automated Versioning Manager

New parameter no_update to build a package from the local repository without first performing a checkout
New integrity control when checking in applications and patches

August 2016 - Release 2.2.5

Automated Versioning Manager

Fixed defect with deploying applications and patches containing new CDTs and updated CDTs.

June 2016 - Release 2.2.4

Bug fixes.

June 2016 - Release 2.2.3

Include the source code in all modules.

June 2016 - Release 2.2.2

Automated Versioning Manager

Added new parameter appian_objects_repo_path to specify where the Appian artifacts are located in the repository.

May 2016 - Release 2.2.0

Automated Versioning Manager

Added support for admin console packages

Automated Import Manager

Removed update-database-schema to support native product capability of automatic database updates via datastore and administration console.
Updated Web Browser UI style
Removed option for "Automatically update the database schema when publishing the data stores" from the Web Browser UI
Added support for admin console deployments
Added support in command line for inspect_only parameter

March 2016 - Release 2.1.0

Automated Versioning Manager

Added support for input flexibility. Now, the command line for versioning manager supports all possible parameters.
Allowed tags as inputs to start hash and end hash.
Added inputs of the following predefined keywords: FIRST_COMMIT (which maps to first commit ever made) and LAST_COMMIT (the previous commit). NOTE: this is only allowed on the start hash input.

Automated Import Manager

Added support for 16.1.
Added action for "Inspect Only".

Deployment Automation

joel.larin — Thu, 26 Oct 2023 18:29:35 GMT

Revision 11 posted to Guide by joel.larin on 10/26/2023 6:29:35 PM

Appian provides several DevOps tools to automate the deployment of Appian applications such as Compare & Deploy and Deployment APIs.

The tools described in this play offer a few alternatives to Appian base product features:

Tightly integrate with a version control system to store and retrieve package files using the Automated Versioning Manager (AVM)
Programmatically deploy Admin Console settings and applications using the Automated Import Manager (AIM) plug-in and the Automated Import Manager (AIM) client

Automated Versioning Manager

Summary

It unzips the application and organizes the artifact XML files in the repository.
It automates the check-in and checkout operations with the version control system.
It generates application packages for import in Appian based on the contents of the repository and a range of changes to include.

The goal of this tool is to facilitate the adoption and usage of a version control system to perform configuration management of the Appian applications and database DDL files.

Features

Version Control integration (Git, SVN)
Supports Appian applications and patches
Generate import package from hash ranges
Folder Listener to add contents to Version Control
Supports GitHub, GitLab, and BitBucket for Version Control

Usage

Script Execution

To run the script, open a command window and navigate to the directory where the automated versioning scripts are located. They are named version-application.bat or version-application.sh.

Use the -h or -help parameters to view the help menu within the script. The parameters are described here:

Required Parameters (required for all four actions: addContents, buildAllApps, buildSingleApp, buildMultipleApps, and updateLocalRepo)
- -action - Selects which action of the script to run. Acceptable values are: addContents, updateLocalRepo, buildAllApps, buildSingleApp, and buildMultipleApps. Each action is detailed in the use cases below.
- -vc_username -The username associated with the version control (Git or SVN) account. NOTE: these are NOT your Appian credentials.
- -vc_password -Please check the Security Settings of the version control account. If you have 2-factor authentication enabled, the password requires the version control account token. If you do NOT have 2-factor authentication enabled, the password is the one associated with the version control account. NOTE: these are NOT your Appian credentials.
Options for addContents action
- -application_path - The path on your filesystem where the application ZIP is located.
- -admin_console_path - The path on your filesystem where the admin console ZIP file is located.
- -ddl_path - List of comma-separated paths for the DDL files to be included in the deployment package.
- -flyway_path - List of comma-separated paths for the directories to execute DB migrations via Flyway. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions. To learn how the Automated Import Manager uses Flyway, refer to AIM Features.
- -ddl_ds - List of comma-separated datasources associated with the provided DDL files. Must provide the same number of entries as number of DDL files specified with the -ddl_path option or number of directories specified with the -flyway_path option. NOTE: the order of the specified datasource names must match the order of the script paths specified.
- -uuid - The UUID of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -application_name - The name of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -commit_message - The message that will be associated with the commit. If not included, a default commit message Committed by @username is provided.
Options for buildAllApps action
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildSingleApp action
- -uuid - The UUID of the application you want to build.
- -application_name - The name of the application you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildMultipleApps action
- -uuid - Comma separated list of UUIDs of the applications you want to build.
- -application_name - Comma separated list of names of the applications that you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for updateLocalRepo action
- There are no additional options (other than required options) for updateLocalRepo.
Additional Parameters - These parameters are REQUIRED, and may be specified here or in the properties file (described in the following section). If they are specified in both locations, the parameters specified in the command line take precedence.
- -version_control_type - The version control type used, either GIT or SVN.
- -local_repo_path - The path on the filesystem where the local repository is located. All files on the remote repository are cloned to this path. Example: C:\\MyFiles\\ChangeManagementRepo. NOTE: if using Windows, be sure to include double forward slashes (as seen in the example) for path separation.
- -appian_objects_repo_path - Path to the folder containing the Appian objects in the repository. This path is relative to the path of the local repository. If not specified, the Appian objects are checked out to and committed from the root of the local repository path.
- -repo_url - The URL that defines the remote repository. Example: https://github.com/git-username/project-name.git, svn+ssh://svn.code.sf.net/p/project-name/code
- -package_path - For buildAllApps, buildSingleApp, and buildMultipleApps only. The path on the filesystem where packages are generated. Must include filename of package.
- -branch_name - Branch to check out and use (if not master)

Configuring using the Properties File

In case an option is specified both on the command line and in the properties file, the command line value takes precedence and is used.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Use Cases

#1: New developer joins team (updateLocalRepo)

In this use case, a new developer has joined the team and wants to get a copy of all the work completed so far. The developer should:

Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using updateLocalRepo as the action flag. The developer must provide the username and password for authenticating against their version control system (-vc_username, -vc_password).

Example Syntax:

> version-application -action updateLocalRepo -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD>

When the script is executed, the developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).

#2: Developer adds artifacts to the repository (addContents)

In the Appian development environment, create an application (or a patch) that contains the changed objects.
Export those changes and download the application ZIP file.
Run the script, using addContents as the action flag. The developer must provide the path of the ZIP file they exported (-application_path) from Appian in step 2. They must also provide the username and password for authenticating their version control system (-vc_username, -vc_password). NOTE: these are NOT Appian credentials.
1. Optional: if the application specified for -application_path is a patch, update the -uuid option to specify the parent application’s uuid. The script will exit with error if a patch application ZIP is provided but no uuid is passed in.
2. Optional: if DDL scripts have been modified, specify the path(s) and their associated JDBC datasource names. NOTE: The same number of DDL scripts and datasource names must be entered into the script, even if the datasource is the same for all scripts. For example: the developer wishes to add two ddl scripts located at C:\DDLs\script1.sql and C:\DDLs\script2.sql. They do so by setting the -ddl_path option as C:\DDLs\script1.sql,C:\DDLs\script2.sql If both scripts are to be executed on jdbc/AppianDS, they must set the -ddl_ds option as jdbc/AppianDS,jdbc/AppianDS. Note that the datasource name is passed in twice.
Optional: include a custom commit message using the -commit_message option

Example Syntax:

> version-application -action addContents -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -application_path "C:\App.zip" -ddl_ds jdbc/AppianAnywhere -ddl_path “C:\script1.sql” -commit_message “Adding account executive record”

When the script is executed, three things occur:

The developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).
The application ZIP is unzipped and placed into the local repository, and the DDL files are placed into a ddl_files folder within the local repository. If the -uuid option is selected, the appropriate application xml file is updated.
The changes are committed (and pushed, if using Git) to the remote repository.

When the package is imported into Appian, all lines within script1.sql will be executed and contents within the application ZIP are imported.

Using Folder Listener:

Alternatively, instead of running the script, the developer can execute avm-folder-listener-<os> in the folder-listener directory. The following command prompt will appear:

#3: Build master generates new RC deployment package (buildAllApps)

(If not done previously) Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using buildAllApps as the action flag. The build master must provide the username and password for authenticating against their version control system (-vc_username, -vc_password). To get a specific set of changes, input a value for the -start_hash option and the -end_hash option. This will generate the package with all new and changed files between the two hash options.
1. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.

Example Command:

> version-application -action buildAllApps -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -start_hash ac37459 -end_hash 6e83b42

When the script is executed, it generates a package at the location specified by the packagePath field in version-manager.properties.

Finally, the build master will import the RC package into the higher environment using the Automated Import tool as described later in this play.

Using Subversion as Version Control System

To allow the Automated Versioning Manager to perform the checkout and commit operations with Subversion, the tool assumes the common Subversion project structure:

trunk
branches
tags

The location of the repository root must be provided by the property repoURL.

versionControlType=SVN

repoUrl=https://svn.code.sf.net/p/deploymentautomationexample/code

branchName=branches/release1

Using Git as Version Control System

To use Git with the Automated Versioning Manager, properties may be specified on the command line or version-manager.properties should be updated as follows:

versionControlType=GIT

repoUrl=https://github.com/gituser/testgitrepo.git

branchName=newbranch

Note: if you are planning to check out a private repository, use the Git SSH URL rather than the HTTPS URL.

Automated Import Manager

Summary

The Automated Import Manager automates the process of inspecting the application, executing DDL scripts, updating CDTs, republishing the appropriate datastores, and importing the application.

Features

Inspect Application: This tool will automatically mimic the "Inspect" functionality that exists within Appian
Validating Application Content: In addition to inspecting the application, the tool will ensure all CDT dependents are included to avoid objects pointing to older versions.
Execute DDL Scripts: DDL scripts can be uploaded and automatically executed. NOTE: For Microsoft SQL Server, only Transact-SQL statements are valid.
Execute Migrations with Flyway: Flyway is a tool used for managing database migrations. It makes it easier to track SQL script versions and not re-execute SQL scripts that have already been run. If a Flyway directory is provided, the Automated Import Manager will automatically execute migrations against the corresponding datasource. Learn more about Flyway here.
Update CDTs: Users are no longer required to delete CDTs before updating them, this tool will perform this step automatically
Import Application and admin console configuration: Automatically import an application with an optional customization file
Republish Datastores: After application import, datastores will be automatically published or republished
Add Patches: Automatically add patch contents to a specified existing application

Usage

Deploy from the Web Browser UI

The tool collects usage metrics by default. To opt-out of metrics collection, check the below option on the Web Browser UI:

Log into Appian as a system administrator
Navigate to the Deployment Automation UI available at the URL: <appian>/suite/plugins/servlet/deploymentautomation
Upload the patch or application you wish to import.
If this application is a patch, select the parent application to which patch contents should be added.
If the new application requires changes to the database schema (i.e. new or updated CDTs) you must choose one of the following:
1. Upload the corresponding DDL script(s) that accurately reflect these additions and/or updates.
2. Set the datastore to "Automatically update database schema" and set "Allow Database Schema Changes Through Data Stores" in the Deployment section of the Appian Administration Console
Click on the button "Start Deployment".
During the deployment, the screen is automatically refreshed every 5 seconds with the latest status of the deployment.
When the deployment is complete, the browser will update with a status page.

Deploy from the Command Line Script

The command line script - the client - can be downloaded from the Appian AppMarket.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Open a command window in the same folder to which the client script and supporting libraries were unzipped.
Using the help guide pictured above, run the proper command to automatically import the application. Use -h or -help to view this menu at any time.
1. -ac_customization_path: Indicates the path to the customization file to use when deploying the admin console package or the application package.
2. -admin_console_path: Indicates the path to the admin console file to deploy. NOTE: Use quotations around the entry.
3. -application_path: Indicates the path to the application file to deploy. NOTE: Use quotations around the entry.
4. -ddl_ds: Optional, use only if providing DDL scripts. The name of the datasource to use with the corresponding DDL script. Use a comma separator to enter multiple datasources.
5. -ddl_path: Optional, use only if providing DDL scripts. Indicates the path to the DDL scripts to execute. Use a comma separator to enter multiple DDL script paths. NOTE: Use quotations around the entry.
6. -flyway_path: Optional, use only if providing directories to execute DB migrations via Flyway. Use a comma separator to enter multiple directory paths. NOTE: Use quotations around the entry. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions.
7. -force_import: A boolean flag which specifies whether or not the import ignores impact analysis results.If true, the import will occur even if objects with CDT references are missing
8. -import_customization_path: Indicates the path to the import customization file to use
9. -inspect_only: Optional, use to run an inspection of the package. Indicates the package should not be deployed but inspected only.
10. -password: Password of the Appian user account
11. -proxy_port: Optional, port of the proxy server to use to connect to Appian. This parameter is only used if the parameter -proxy_url is defined. The default value is 8080.
12. -proxy_url: Optional, URL of the proxy to use to connect to Appian.
13. -url: URL of the environment, of the format https://example.appian.com/suite.
14. -username: Username of the Appian user account to use for deployment
15. -uuid: UUID of the application to which patch contents will be added
Deploy the application by typing the command deploy-application.bat and including the relevant parameters. Your command will look something like the one pictured below.

deploy-application.bat -application_path "PATH TO APPLICATION ZIP" -username SERVICE_ACCOUNT_USERNAME -password SERVICE_ACCOUNT_PASSWORD -url APPIAN_URL -ddl_path "PATH TO DLL 1, PATH TO DLL 2" -ddl_ds jdbc/Appian1,jdbc/Appian2

Deploy from an External Continuous Integration tool

Additional Requirement:

An existing external Continuous Integration tool (such as Jenkins or Hudson) that is properly configured

The steps below provide the high level steps to deploy an application from Jenkins.

Create a new external job
Configure the job to run the import script using the guidance in Deployment Option #2 listed above
Execute the job

When the deployment is complete, check the status page verify that the import was successful.

Troubleshooting

Deciphering Script Error Messages

Inspect Failure

Package Validation Failure

In case you want to proceed with deploying the application regardless of missing CDT dependencies, use the flag -f.

Import Failure

Invalid Credentials

Please ensure that these credentials are associated with an active Appian system administrator account. Basic user credentials cannot be used.

Connection Refused With Deployment Command Line Script

A "Connection Refused" error could be the result of using the wrong URL when executing the script. The URL provided as a parameter must:

include the suffix "/suite"
Include a port number if not using the port 80 with HTTP or port 443 with HTTPS

Release Notes

September 2021 - Release 2.5.13

Bug Fixes
- Fixed an issue where setting "appianObjectsRepoPath" prevented a package that included a patches.xml file from being processed successfully

March 2021 - Release 2.5.12

Enhancements
- Updated the link to the import log in the ADM servlet after a change was made to the Appian API.
Bug Fixes
- Fixed a bug that was preventing Flyway files from being included in metadata.properties.

September 2020 - Release 2.5.11

Enhancements
- Upgraded Flyway version to 6.5.5 for compatibility with MariaDB.

August 2020 - Release 2.5.10

Enhancements
- Added the ability to dynamically generate the Metadata file for the "buildAllApps" action to reflect only the list of database scripts that are included in the package for a given commit range.
Bug Fixes
- Fixed the interpretation of "appianObjectsRepoPath" on Windows platforms.

December 2019 - Release 2.5.9

Enhancements
- Added DNS proxy support to ADM
- Added DNS proxy support to AIM
- Added DNS proxy support to AVM
- Added support for special characters in passwords in ADM

July 2019 - Release 2.5.8

Bug Fixes
- Fixed the problem with obtaining TransactionManager and creating DataConfiguration against latest the Appian version

April 2019 - Release 2.5.7

Enhancements
- Added commit message prompt to folder listener
Bug Fixes
- Fixed Windows issue with pushing file updates to versioning manager
- Fixed import patch failure not adding newly created objects issue
- Fixed semicolon separator parsing issue

March 2019 - Release 2.5.6

Enhancements
- Added proxy authentication support for import client

February 2019 - Release 2.5.5

Bug Fixes
- Fixed DDL paths bug

January 2019 - Release 2.5.4

Enhancements
- Improved descriptions of errors encountered during deployments
Bug Fixes
- Fixed "Connection Refused" bug when running on a Jenkins server
- Fixed "buildSingleApp" AVM bug when specifying an appianObjectsRepoPath
- Fixed rare "hanging" bug in AIM Client

November 2018 - Release 2.5.3

Enhancements
- Created a reset command for Remote Automated Deployment Manager
Bug Fixes
- Version and Import Metrics Logger Initialized correctly to fix null pointer exception

October 2018 - Release 2.5.2

Enhancements
- Folder listener to auto trigger “Add Contents” action
- Field validation for import and versioning manager properties files
- Usage metrics collection to better understand tool use
- Updated error log messages
Bug Fixes
- ADM UI: Handle apostrophes in app name
- ZIP type validation for Automated Import Manager

September 2018 - Release 2.5.1

Enhancements
- New buildMultipleApps action
- Check version of tools with -v or -version flags
Bug Fixes
- Fixed ADM SQL errors with non-null statements and forward slash as delimiters

August 2018 - Release 2.5.0

Enhancements
- Added Flyway DB version control tool to command line and AIM GUI
- Allow import of DDL scripts or Flyway scripts without an application zip or patch zip
- Added Folder Listener script that will run addContents automatically when a file is dropped into a folder
Bug Fixes
- Added buildAllApps to list of approved actions
- Set inspect_only properly in AIM
- Fixed bug where repo would be cloned into a folder with an incorrect name
- Passed in correct authentication token for buildAllApps and buildSingleApp

August 2018 - Release 2.4.7

Enhancements
- Added "buildSingleApp" action to extract one app from multi app repo
- Renamed "buildPackage" action to "buildAllApps" to better clarify the functionality
Bug Fixes
- Fixed miscellaneous issues with parsing SQL in DDL file
- Mark/reset issue with large customization files

June 2018 - Release 2.4.6

Enhancements
- Added an import-manager.properties file to set default values for importing applications
- Automated versioning manager supports adding a package with multiple patches
Bug Fixes
- Application version UUID is updated when adding patches to a version control
- Import no longer fails when SQL in DDL file contains a ";", "–" or "/**/"

March 2018 - Release 2.4.5

Add support for proxy configuration in the deployment client script with parameters "proxy_port" and "proxy_url"

January 2018 - Release 2.4.4

Bug fixes

January 2018 - Release 2.4.3

Support for Appian 17.4

September 2017 - Release 2.4.2

Support for Appian 17.3
Better handling of end of line characters in the SQL scripts
Support for customization file when deploying an application package

June 2017 - Release 2.4.1

Support for Appian 17.2
Fix defect preventing to execute DB scripts as part of a deployment

January 2017 - Release 2.4.0

Support for Appian 17.1

October 2016 - Release 2.3

Support for Appian 16.3

September 2016 - Release 2.2.9

Automated Import Manager

Successfully deploy application packages containing new Datastore entities and new dependents on these entities.

September 2016 - Release 2.2.8

Automated Versioning Manager

Fixed defect with missing artifacts in package when using START_HASH and END_HASH.

August 2016 - Release 2.2.7

Automated Versioning Manager

Fixed defect with deploying applications and patches containing updated Documents.

August 2016 - Release 2.2.6

Automated Versioning Manager

New parameter no_update to build a package from the local repository without first performing a checkout
New integrity control when checking in applications and patches

August 2016 - Release 2.2.5

Automated Versioning Manager

Fixed defect with deploying applications and patches containing new CDTs and updated CDTs.

June 2016 - Release 2.2.4

Bug fixes.

June 2016 - Release 2.2.3

Include the source code in all modules.

June 2016 - Release 2.2.2

Automated Versioning Manager

Added new parameter appian_objects_repo_path to specify where the Appian artifacts are located in the repository.

May 2016 - Release 2.2.0

Automated Versioning Manager

Added support for admin console packages

Automated Import Manager

Removed update-database-schema to support native product capability of automatic database updates via datastore and administration console.
Updated Web Browser UI style
Removed option for "Automatically update the database schema when publishing the data stores" from the Web Browser UI
Added support for admin console deployments
Added support in command line for inspect_only parameter

March 2016 - Release 2.1.0

Automated Versioning Manager

Added support for input flexibility. Now, the command line for versioning manager supports all possible parameters.
Allowed tags as inputs to start hash and end hash.
Added inputs of the following predefined keywords: FIRST_COMMIT (which maps to first commit ever made) and LAST_COMMIT (the previous commit). NOTE: this is only allowed on the start hash input.

Automated Import Manager

Added support for 16.1.
Added action for "Inspect Only".

Deployment Automation

joel.larin — Thu, 26 Oct 2023 18:26:46 GMT

Revision 10 posted to Guide by joel.larin on 10/26/2023 6:26:46 PM

Appian provides several DevOps tools to automate the deployment of Appian applications such as Compare & Deploy and Deployment APIs.

The tools described in this play offer a few alternatives to Appian base product features:

Tightly integrate with a version control system to store and retrieve package files using the Automated Versioning Manager (AVM)
Programmatically deploy Admin Console settings and applications using the Automated Import Manager (AIM) plug-in and the Automated Import Manager (AIM) client

Automated Versioning Manager

Summary

It unzips the application and organizes the artifact XML files in the repository.
It automates the check-in and checkout operations with the version control system.
It generates application packages for import in Appian based on the contents of the repository and a range of changes to include.

The goal of this tool is to facilitate the adoption and usage of a version control system to perform configuration management of the Appian applications and database DDL files.

Features

Version Control integration (Git, SVN)
Supports Appian applications and patches
Generate import package from hash ranges
Folder Listener to add contents to Version Control
Supports GitHub, GitLab, and BitBucket for Version Control

Usage

Script Execution

To run the script, open a command window and navigate to the directory where the automated versioning scripts are located. They are named version-application.bat or version-application.sh.

Use the -h or -help parameters to view the help menu within the script. The parameters are described here:

Required Parameters (required for all four actions: addContents, buildAllApps, buildSingleApp, buildMultipleApps, and updateLocalRepo)
- -action - Selects which action of the script to run. Acceptable values are: addContents, updateLocalRepo, buildAllApps, buildSingleApp, and buildMultipleApps. Each action is detailed in the use cases below.
- -vc_username -The username associated with the version control (Git or SVN) account. NOTE: these are NOT your Appian credentials.
- -vc_password -Please check the Security Settings of the version control account. If you have 2-factor authentication enabled, the password requires the version control account token. If you do NOT have 2-factor authentication enabled, the password is the one associated with the version control account. NOTE: these are NOT your Appian credentials.
Options for addContents action
- -application_path - The path on your filesystem where the application ZIP is located.
- -admin_console_path - The path on your filesystem where the admin console ZIP file is located.
- -ddl_path - List of comma-separated paths for the DDL files to be included in the deployment package.
- -flyway_path - List of comma-separated paths for the directories to execute DB migrations via Flyway. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions. To learn how the Automated Import Manager uses Flyway, refer to AIM Features.
- -ddl_ds - List of comma-separated datasources associated with the provided DDL files. Must provide the same number of entries as number of DDL files specified with the -ddl_path option or number of directories specified with the -flyway_path option. NOTE: the order of the specified datasource names must match the order of the script paths specified.
- -uuid - The UUID of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -application_name - The name of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -commit_message - The message that will be associated with the commit. If not included, a default commit message Committed by @username is provided.
Options for buildAllApps action
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildSingleApp action
- -uuid - The UUID of the application you want to build.
- -application_name - The name of the application you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildMultipleApps action
- -uuid - Comma separated list of UUIDs of the applications you want to build.
- -application_name - Comma separated list of names of the applications that you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for updateLocalRepo action
- There are no additional options (other than required options) for updateLocalRepo.
Additional Parameters - These parameters are REQUIRED, and may be specified here or in the properties file (described in the following section). If they are specified in both locations, the parameters specified in the command line take precedence.
- -version_control_type - The version control type used, either GIT or SVN.
- -local_repo_path - The path on the filesystem where the local repository is located. All files on the remote repository are cloned to this path. Example: C:\\MyFiles\\ChangeManagementRepo. NOTE: if using Windows, be sure to include double forward slashes (as seen in the example) for path separation.
- -appian_objects_repo_path - Path to the folder containing the Appian objects in the repository. This path is relative to the path of the local repository. If not specified, the Appian objects are checked out to and committed from the root of the local repository path.
- -repo_url - The URL that defines the remote repository. Example: https://github.com/git-username/project-name.git, svn+ssh://svn.code.sf.net/p/project-name/code
- -package_path - For buildAllApps, buildSingleApp, and buildMultipleApps only. The path on the filesystem where packages are generated. Must include filename of package.
- -branch_name - Branch to check out and use (if not master)

Configuring using the Properties File

In case an option is specified both on the command line and in the properties file, the command line value takes precedence and is used.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Use Cases

#1: New developer joins team (updateLocalRepo)

In this use case, a new developer has joined the team and wants to get a copy of all the work completed so far. The developer should:

Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using updateLocalRepo as the action flag. The developer must provide the username and password for authenticating against their version control system (-vc_username, -vc_password).

Example Syntax:

> version-application -action updateLocalRepo -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD>

When the script is executed, the developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).

#2: Developer adds artifacts to the repository (addContents)

In the Appian development environment, create an application (or a patch) that contains the changed objects.
Export those changes and download the application ZIP file.
Run the script, using addContents as the action flag. The developer must provide the path of the ZIP file they exported (-application_path) from Appian in step 2. They must also provide the username and password for authenticating their version control system (-vc_username, -vc_password). NOTE: these are NOT Appian credentials.
1. Optional: if the application specified for -application_path is a patch, update the -uuid option to specify the parent application’s uuid. The script will exit with error if a patch application ZIP is provided but no uuid is passed in.
2. Optional: if DDL scripts have been modified, specify the path(s) and their associated JDBC datasource names. NOTE: The same number of DDL scripts and datasource names must be entered into the script, even if the datasource is the same for all scripts. For example: the developer wishes to add two ddl scripts located at C:\DDLs\script1.sql and C:\DDLs\script2.sql. They do so by setting the -ddl_path option as C:\DDLs\script1.sql,C:\DDLs\script2.sql If both scripts are to be executed on jdbc/AppianDS, they must set the -ddl_ds option as jdbc/AppianDS,jdbc/AppianDS. Note that the datasource name is passed in twice.
Optional: include a custom commit message using the -commit_message option

Example Syntax:

> version-application -action addContents -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -application_path "C:\App.zip" -ddl_ds jdbc/AppianAnywhere -ddl_path “C:\script1.sql” -commit_message “Adding account executive record”

When the script is executed, three things occur:

The developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).
The application ZIP is unzipped and placed into the local repository, and the DDL files are placed into a ddl_files folder within the local repository. If the -uuid option is selected, the appropriate application xml file is updated.
The changes are committed (and pushed, if using Git) to the remote repository.

When the package is imported into Appian, all lines within script1.sql will be executed and contents within the application ZIP are imported.

Using Folder Listener:

Alternatively, instead of running the script, the developer can execute avm-folder-listener-<os> in the folder-listener directory. The following command prompt will appear:

#3: Build master generates new RC deployment package (buildAllApps)

(If not done previously) Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using buildAllApps as the action flag. The build master must provide the username and password for authenticating against their version control system (-vc_username, -vc_password). To get a specific set of changes, input a value for the -start_hash option and the -end_hash option. This will generate the package with all new and changed files between the two hash options.
1. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.

Example Command:

> version-application -action buildAllApps -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -start_hash ac37459 -end_hash 6e83b42

When the script is executed, it generates a package at the location specified by the packagePath field in version-manager.properties.

Finally, the build master will import the RC package into the higher environment using the Automated Import tool as described later in this play.

Using Subversion as Version Control System

To allow the Automated Versioning Manager to perform the checkout and commit operations with Subversion, the tool assumes the common Subversion project structure:

trunk
branches
tags

The location of the repository root must be provided by the property repoURL.

versionControlType=SVN

repoUrl=https://svn.code.sf.net/p/deploymentautomationexample/code

branchName=branches/release1

Using Git as Version Control System

To use Git with the Automated Versioning Manager, properties may be specified on the command line or version-manager.properties should be updated as follows:

versionControlType=GIT

repoUrl=https://github.com/gituser/testgitrepo.git

branchName=newbranch

Note: if you are planning to check out a private repository, use the Git SSH URL rather than the HTTPS URL.

Automated Import Manager

Summary

The Automated Import Manager automates the process of inspecting the application, executing DDL scripts, updating CDTs, republishing the appropriate datastores, and importing the application.

Features

Inspect Application: This tool will automatically mimic the "Inspect" functionality that exists within Appian
Validating Application Content: In addition to inspecting the application, the tool will ensure all CDT dependents are included to avoid objects pointing to older versions.
Execute DDL Scripts: DDL scripts can be uploaded and automatically executed. NOTE: For Microsoft SQL Server, only Transact-SQL statements are valid.
Execute Migrations with Flyway: Flyway is a tool used for managing database migrations. It makes it easier to track SQL script versions and not re-execute SQL scripts that have already been run. If a Flyway directory is provided, the Automated Import Manager will automatically execute migrations against the corresponding datasource. Learn more about Flyway here.
Update CDTs: Users are no longer required to delete CDTs before updating them, this tool will perform this step automatically
Import Application and admin console configuration: Automatically import an application with an optional customization file
Republish Datastores: After application import, datastores will be automatically published or republished
Add Patches: Automatically add patch contents to a specified existing application

Usage

Deploy from the Web Browser UI

The tool collects usage metrics by default. To opt-out of metrics collection, check the below option on the Web Browser UI:

Log into Appian as a system administrator
Navigate to the Deployment Automation UI available at the URL: <appian>/suite/plugins/servlet/deploymentautomation
Upload the patch or application you wish to import.
If this application is a patch, select the parent application to which patch contents should be added.
If the new application requires changes to the database schema (i.e. new or updated CDTs) you must choose one of the following:
1. Upload the corresponding DDL script(s) that accurately reflect these additions and/or updates.
2. Set the datastore to "Automatically update database schema" and set "Allow Database Schema Changes Through Data Stores" in the Deployment section of the Appian Administration Console
Click on the button "Start Deployment".
During the deployment, the screen is automatically refreshed every 5 seconds with the latest status of the deployment.
When the deployment is complete, the browser will update with a status page.

Deploy from the Command Line Script

The command line script - the client - can be downloaded from the Appian AppMarket.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Open a command window in the same folder to which the client script and supporting libraries were unzipped.
Using the help guide pictured above, run the proper command to automatically import the application. Use -h or -help to view this menu at any time.
1. -ac_customization_path: Indicates the path to the customization file to use when deploying the admin console package or the application package.
2. -admin_console_path: Indicates the path to the admin console file to deploy. NOTE: Use quotations around the entry.
3. -application_path: Indicates the path to the application file to deploy. NOTE: Use quotations around the entry.
4. -ddl_ds: Optional, use only if providing DDL scripts. The name of the datasource to use with the corresponding DDL script. Use a comma separator to enter multiple datasources.
5. -ddl_path: Optional, use only if providing DDL scripts. Indicates the path to the DDL scripts to execute. Use a comma separator to enter multiple DDL script paths. NOTE: Use quotations around the entry.
6. -flyway_path: Optional, use only if providing directories to execute DB migrations via Flyway. Use a comma separator to enter multiple directory paths. NOTE: Use quotations around the entry. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions.
7. -force_import: A boolean flag which specifies whether or not the import ignores impact analysis results.If true, the import will occur even if objects with CDT references are missing
8. -import_customization_path: Indicates the path to the import customization file to use
9. -inspect_only: Optional, use to run an inspection of the package. Indicates the package should not be deployed but inspected only.
10. -password: Password of the Appian user account
11. -proxy_port: Optional, port of the proxy server to use to connect to Appian. This parameter is only used if the parameter -proxy_url is defined. The default value is 8080.
12. -proxy_url: Optional, URL of the proxy to use to connect to Appian.
13. -url: URL of the environment, of the format https://example.appian.com/suite.
14. -username: Username of the Appian user account to use for deployment
15. -uuid: UUID of the application to which patch contents will be added
Deploy the application by typing the command deploy-application.bat and including the relevant parameters. Your command will look something like the one pictured below.

deploy-application.bat -application_path "PATH TO APPLICATION ZIP" -username SERVICE_ACCOUNT_USERNAME -password SERVICE_ACCOUNT_PASSWORD -url APPIAN_URL -ddl_path "PATH TO DLL 1, PATH TO DLL 2" -ddl_ds jdbc/Appian1,jdbc/Appian2

Deploy from an External Continuous Integration tool

Additional Requirement:

An existing external Continuous Integration tool (such as Jenkins or Hudson) that is properly configured

The steps below provide the high level steps to deploy an application from Jenkins.

Create a new external job
Configure the job to run the import script using the guidance in Deployment Option #2 listed above
Execute the job

When the deployment is complete, check the status page verify that the import was successful.

Troubleshooting

Deciphering Script Error Messages

Inspect Failure

Package Validation Failure

In case you want to proceed with deploying the application regardless of missing CDT dependencies, use the flag -f.

Import Failure

Invalid Credentials

Please ensure that these credentials are associated with an active Appian system administrator account. Basic user credentials cannot be used.

Connection Refused With Deployment Command Line Script

A "Connection Refused" error could be the result of using the wrong URL when executing the script. The URL provided as a parameter must:

include the suffix "/suite"
Include a port number if not using the port 80 with HTTP or port 443 with HTTPS

Release Notes

September 2021 - Release 2.5.13

Bug Fixes
- Fixed an issue where setting "appianObjectsRepoPath" prevented a package that included a patches.xml file from being processed successfully

March 2021 - Release 2.5.12

Enhancements
- Updated the link to the import log in the ADM servlet after a change was made to the Appian API.
Bug Fixes
- Fixed a bug that was preventing Flyway files from being included in metadata.properties.

September 2020 - Release 2.5.11

Enhancements
- Upgraded Flyway version to 6.5.5 for compatibility with MariaDB.

August 2020 - Release 2.5.10

Enhancements
- Added the ability to dynamically generate the Metadata file for the "buildAllApps" action to reflect only the list of database scripts that are included in the package for a given commit range.
Bug Fixes
- Fixed the interpretation of "appianObjectsRepoPath" on Windows platforms.

December 2019 - Release 2.5.9

Enhancements
- Added DNS proxy support to ADM
- Added DNS proxy support to AIM
- Added DNS proxy support to AVM
- Added support for special characters in passwords in ADM

July 2019 - Release 2.5.8

Bug Fixes
- Fixed the problem with obtaining TransactionManager and creating DataConfiguration against latest the Appian version

April 2019 - Release 2.5.7

Enhancements
- Added commit message prompt to folder listener
Bug Fixes
- Fixed Windows issue with pushing file updates to versioning manager
- Fixed import patch failure not adding newly created objects issue
- Fixed semicolon separator parsing issue

March 2019 - Release 2.5.6

Enhancements
- Added proxy authentication support for import client

February 2019 - Release 2.5.5

Bug Fixes
- Fixed DDL paths bug

January 2019 - Release 2.5.4

Enhancements
- Improved descriptions of errors encountered during deployments
Bug Fixes
- Fixed "Connection Refused" bug when running on a Jenkins server
- Fixed "buildSingleApp" AVM bug when specifying an appianObjectsRepoPath
- Fixed rare "hanging" bug in AIM Client

November 2018 - Release 2.5.3

Enhancements
- Created a reset command for Remote Automated Deployment Manager
Bug Fixes
- Version and Import Metrics Logger Initialized correctly to fix null pointer exception

October 2018 - Release 2.5.2

Enhancements
- Folder listener to auto trigger “Add Contents” action
- Field validation for import and versioning manager properties files
- Usage metrics collection to better understand tool use
- Updated error log messages
Bug Fixes
- ADM UI: Handle apostrophes in app name
- ZIP type validation for Automated Import Manager

September 2018 - Release 2.5.1

Enhancements
- New buildMultipleApps action
- Check version of tools with -v or -version flags
Bug Fixes
- Fixed ADM SQL errors with non-null statements and forward slash as delimiters

August 2018 - Release 2.5.0

Enhancements
- Added Flyway DB version control tool to command line and AIM GUI
- Allow import of DDL scripts or Flyway scripts without an application zip or patch zip
- Added Folder Listener script that will run addContents automatically when a file is dropped into a folder
Bug Fixes
- Added buildAllApps to list of approved actions
- Set inspect_only properly in AIM
- Fixed bug where repo would be cloned into a folder with an incorrect name
- Passed in correct authentication token for buildAllApps and buildSingleApp

August 2018 - Release 2.4.7

Enhancements
- Added "buildSingleApp" action to extract one app from multi app repo
- Renamed "buildPackage" action to "buildAllApps" to better clarify the functionality
Bug Fixes
- Fixed miscellaneous issues with parsing SQL in DDL file
- Mark/reset issue with large customization files

June 2018 - Release 2.4.6

Enhancements
- Added an import-manager.properties file to set default values for importing applications
- Automated versioning manager supports adding a package with multiple patches
Bug Fixes
- Application version UUID is updated when adding patches to a version control
- Import no longer fails when SQL in DDL file contains a ";", "–" or "/**/"

March 2018 - Release 2.4.5

Add support for proxy configuration in the deployment client script with parameters "proxy_port" and "proxy_url"

January 2018 - Release 2.4.4

Bug fixes

January 2018 - Release 2.4.3

Support for Appian 17.4

September 2017 - Release 2.4.2

Support for Appian 17.3
Better handling of end of line characters in the SQL scripts
Support for customization file when deploying an application package

June 2017 - Release 2.4.1

Support for Appian 17.2
Fix defect preventing to execute DB scripts as part of a deployment

January 2017 - Release 2.4.0

Support for Appian 17.1

October 2016 - Release 2.3

Support for Appian 16.3

September 2016 - Release 2.2.9

Automated Import Manager

Successfully deploy application packages containing new Datastore entities and new dependents on these entities.

September 2016 - Release 2.2.8

Automated Versioning Manager

Fixed defect with missing artifacts in package when using START_HASH and END_HASH.

August 2016 - Release 2.2.7

Automated Versioning Manager

Fixed defect with deploying applications and patches containing updated Documents.

August 2016 - Release 2.2.6

Automated Versioning Manager

New parameter no_update to build a package from the local repository without first performing a checkout
New integrity control when checking in applications and patches

August 2016 - Release 2.2.5

Automated Versioning Manager

Fixed defect with deploying applications and patches containing new CDTs and updated CDTs.

June 2016 - Release 2.2.4

Bug fixes.

June 2016 - Release 2.2.3

Include the source code in all modules.

June 2016 - Release 2.2.2

Automated Versioning Manager

Added new parameter appian_objects_repo_path to specify where the Appian artifacts are located in the repository.

May 2016 - Release 2.2.0

Automated Versioning Manager

Added support for admin console packages

Automated Import Manager

Removed update-database-schema to support native product capability of automatic database updates via datastore and administration console.
Updated Web Browser UI style
Removed option for "Automatically update the database schema when publishing the data stores" from the Web Browser UI
Added support for admin console deployments
Added support in command line for inspect_only parameter

March 2016 - Release 2.1.0

Automated Versioning Manager

Added support for input flexibility. Now, the command line for versioning manager supports all possible parameters.
Allowed tags as inputs to start hash and end hash.
Added inputs of the following predefined keywords: FIRST_COMMIT (which maps to first commit ever made) and LAST_COMMIT (the previous commit). NOTE: this is only allowed on the start hash input.

Automated Import Manager

Added support for 16.1.
Added action for "Inspect Only".

Deployment Automation

joel.larin — Thu, 26 Oct 2023 18:25:27 GMT

Revision 9 posted to Guide by joel.larin on 10/26/2023 6:25:27 PM

Appian provides several DevOps tools to automate the deployment of Appian applications such as Compare & Deploy and Deployment APIs.

The tools described in this play offer a few alternatives to Appian base product features:

Tightly integrate with a version control system to store and retrieve package files using the Automated Versioning Manager (AVM)
Programmatically deploy Admin Console settings and applications using the Automated Import Manager (AIM) plug-in and the Automated Import Manager (AIM) client

Automated Versioning Manager

Summary

It unzips the application and organizes the artifact XML files in the repository.
It automates the check-in and checkout operations with the version control system.
It generates application packages for import in Appian based on the contents of the repository and a range of changes to include.

The goal of this tool is to facilitate the adoption and usage of a version control system to perform configuration management of the Appian applications and database DDL files.

Features

Version Control integration (Git, SVN)
Supports Appian applications and patches
Generate import package from hash ranges
Folder Listener to add contents to Version Control
Supports GitHub, GitLab, and BitBucket for Version Control

Usage

Script Execution

To run the script, open a command window and navigate to the directory where the automated versioning scripts are located. They are named version-application.bat or version-application.sh.

Use the -h or -help parameters to view the help menu within the script. The parameters are described here:

Required Parameters (required for all four actions: addContents, buildAllApps, buildSingleApp, buildMultipleApps, and updateLocalRepo)
- -action - Selects which action of the script to run. Acceptable values are: addContents, updateLocalRepo, buildAllApps, buildSingleApp, and buildMultipleApps. Each action is detailed in the use cases below.
- -vc_username -The username associated with the version control (Git or SVN) account. NOTE: these are NOT your Appian credentials.
- -vc_password -Please check the Security Settings of the version control account. If you have 2-factor authentication enabled, the password requires the version control account token. If you do NOT have 2-factor authentication enabled, the password is the one associated with the version control account. NOTE: these are NOT your Appian credentials.
Options for addContents action
- -application_path - The path on your filesystem where the application ZIP is located.
- -admin_console_path - The path on your filesystem where the admin console ZIP file is located.
- -ddl_path - List of comma-separated paths for the DDL files to be included in the deployment package.
- -flyway_path - List of comma-separated paths for the directories to execute DB migrations via Flyway. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions. To learn how the Automated Import Manager uses Flyway, refer to AIM Features.
- -ddl_ds - List of comma-separated datasources associated with the provided DDL files. Must provide the same number of entries as number of DDL files specified with the -ddl_path option or number of directories specified with the -flyway_path option. NOTE: the order of the specified datasource names must match the order of the script paths specified.
- -uuid - The UUID of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -application_name - The name of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -commit_message - The message that will be associated with the commit. If not included, a default commit message Committed by @username is provided.
Options for buildAllApps action
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildSingleApp action
- -uuid - The UUID of the application you want to build.
- -application_name - The name of the application you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildMultipleApps action
- -uuid - Comma separated list of UUIDs of the applications you want to build.
- -application_name - Comma separated list of names of the applications that you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for updateLocalRepo action
- There are no additional options (other than required options) for updateLocalRepo.
Additional Parameters - These parameters are REQUIRED, and may be specified here or in the properties file (described in the following section). If they are specified in both locations, the parameters specified in the command line take precedence.
- -version_control_type - The version control type used, either GIT or SVN.
- -local_repo_path - The path on the filesystem where the local repository is located. All files on the remote repository are cloned to this path. Example: C:\\MyFiles\\ChangeManagementRepo. NOTE: if using Windows, be sure to include double forward slashes (as seen in the example) for path separation.
- -appian_objects_repo_path - Path to the folder containing the Appian objects in the repository. This path is relative to the path of the local repository. If not specified, the Appian objects are checked out to and committed from the root of the local repository path.
- -repo_url - The URL that defines the remote repository. Example: https://github.com/git-username/project-name.git, svn+ssh://svn.code.sf.net/p/project-name/code
- -package_path - For buildAllApps, buildSingleApp, and buildMultipleApps only. The path on the filesystem where packages are generated. Must include filename of package.
- -branch_name - Branch to check out and use (if not master)

Configuring using the Properties File

In case an option is specified both on the command line and in the properties file, the command line value takes precedence and is used.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Use Cases

#1: New developer joins team (updateLocalRepo)

In this use case, a new developer has joined the team and wants to get a copy of all the work completed so far. The developer should:

Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using updateLocalRepo as the action flag. The developer must provide the username and password for authenticating against their version control system (-vc_username, -vc_password).

Example Syntax:

> version-application -action updateLocalRepo -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD>

When the script is executed, the developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).

#2: Developer adds artifacts to the repository (addContents)

In the Appian development environment, create an application (or a patch) that contains the changed objects.
Export those changes and download the application ZIP file.
Run the script, using addContents as the action flag. The developer must provide the path of the ZIP file they exported (-application_path) from Appian in step 2. They must also provide the username and password for authenticating their version control system (-vc_username, -vc_password). NOTE: these are NOT Appian credentials.
1. Optional: if the application specified for -application_path is a patch, update the -uuid option to specify the parent application’s uuid. The script will exit with error if a patch application ZIP is provided but no uuid is passed in.
2. Optional: if DDL scripts have been modified, specify the path(s) and their associated JDBC datasource names. NOTE: The same number of DDL scripts and datasource names must be entered into the script, even if the datasource is the same for all scripts. For example: the developer wishes to add two ddl scripts located at C:\DDLs\script1.sql and C:\DDLs\script2.sql. They do so by setting the -ddl_path option as C:\DDLs\script1.sql,C:\DDLs\script2.sql If both scripts are to be executed on jdbc/AppianDS, they must set the -ddl_ds option as jdbc/AppianDS,jdbc/AppianDS. Note that the datasource name is passed in twice.
Optional: include a custom commit message using the -commit_message option

Example Syntax:

> version-application -action addContents -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -application_path "C:\App.zip" -ddl_ds jdbc/AppianAnywhere -ddl_path “C:\script1.sql” -commit_message “Adding account executive record”

When the script is executed, three things occur:

The developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).
The application ZIP is unzipped and placed into the local repository, and the DDL files are placed into a ddl_files folder within the local repository. If the -uuid option is selected, the appropriate application xml file is updated.
The changes are committed (and pushed, if using Git) to the remote repository.

When the package is imported into Appian, all lines within script1.sql will be executed and contents within the application ZIP are imported.

Using Folder Listener:

Alternatively, instead of running the script, the developer can execute avm-folder-listener-<os> in the folder-listener directory. The following command prompt will appear:

#3: Build master generates new RC deployment package (buildAllApps)

(If not done previously) Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using buildAllApps as the action flag. The build master must provide the username and password for authenticating against their version control system (-vc_username, -vc_password). To get a specific set of changes, input a value for the -start_hash option and the -end_hash option. This will generate the package with all new and changed files between the two hash options.
1. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.

Example Command:

> version-application -action buildAllApps -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -start_hash ac37459 -end_hash 6e83b42

When the script is executed, it generates a package at the location specified by the packagePath field in version-manager.properties.

Finally, the build master will import the RC package into the higher environment using the Automated Import tool as described later in this play.

Using Subversion as Version Control System

To allow the Automated Versioning Manager to perform the checkout and commit operations with Subversion, the tool assumes the common Subversion project structure:

trunk
branches
tags

The location of the repository root must be provided by the property repoURL.

Example: The following version-manager.properties configuration checks out the release 1 branch from the repository located at https://svn.code.sf.net/p/deploymentautomationexample/code and commit all changes to the branch "release1". Optionally, you may specify each of these parameters as command line arguments instead of using the version-manager.properties file.

versionControlType=SVN

repoUrl=https://svn.code.sf.net/p/deploymentautomationexample/code

branchName=branches/release1

Using Git as Version Control System

To use Git with the Automated Versioning Manager, properties may be specified on the command line or version-manager.properties should be updated as follows:

versionControlType=GIT

repoUrl=https://github.com/gituser/testgitrepo.git

branchName=newbranch

Note: if you are planning to check out a private repository, use the Git SSH URL rather than the HTTPS URL.

Automated Import Manager

Summary

The Automated Import Manager automates the process of inspecting the application, executing DDL scripts, updating CDTs, republishing the appropriate datastores, and importing the application.

Features

Inspect Application: This tool will automatically mimic the "Inspect" functionality that exists within Appian
Validating Application Content: In addition to inspecting the application, the tool will ensure all CDT dependents are included to avoid objects pointing to older versions.
Execute DDL Scripts: DDL scripts can be uploaded and automatically executed. NOTE: For Microsoft SQL Server, only Transact-SQL statements are valid.
Execute Migrations with Flyway: Flyway is a tool used for managing database migrations. It makes it easier to track SQL script versions and not re-execute SQL scripts that have already been run. If a Flyway directory is provided, the Automated Import Manager will automatically execute migrations against the corresponding datasource. Learn more about Flyway here.
Update CDTs: Users are no longer required to delete CDTs before updating them, this tool will perform this step automatically
Import Application and admin console configuration: Automatically import an application with an optional customization file
Republish Datastores: After application import, datastores will be automatically published or republished
Add Patches: Automatically add patch contents to a specified existing application

Usage

Deploy from the Web Browser UI

The tool collects usage metrics by default. To opt-out of metrics collection, check the below option on the Web Browser UI:

Log into Appian as a system administrator
Navigate to the Deployment Automation UI available at the URL: <appian>/suite/plugins/servlet/deploymentautomation
Upload the patch or application you wish to import.
If this application is a patch, select the parent application to which patch contents should be added.
If the new application requires changes to the database schema (i.e. new or updated CDTs) you must choose one of the following:
1. Upload the corresponding DDL script(s) that accurately reflect these additions and/or updates.
2. Set the datastore to "Automatically update database schema" and set "Allow Database Schema Changes Through Data Stores" in the Deployment section of the Appian Administration Console
Click on the button "Start Deployment".
During the deployment, the screen is automatically refreshed every 5 seconds with the latest status of the deployment.
When the deployment is complete, the browser will update with a status page.

Deploy from the Command Line Script

The command line script - the client - can be downloaded from the Appian AppMarket.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Open a command window in the same folder to which the client script and supporting libraries were unzipped.
Using the help guide pictured above, run the proper command to automatically import the application. Use -h or -help to view this menu at any time.
1. -ac_customization_path: Indicates the path to the customization file to use when deploying the admin console package or the application package.
2. -admin_console_path: Indicates the path to the admin console file to deploy. NOTE: Use quotations around the entry.
3. -application_path: Indicates the path to the application file to deploy. NOTE: Use quotations around the entry.
4. -ddl_ds: Optional, use only if providing DDL scripts. The name of the datasource to use with the corresponding DDL script. Use a comma separator to enter multiple datasources.
5. -ddl_path: Optional, use only if providing DDL scripts. Indicates the path to the DDL scripts to execute. Use a comma separator to enter multiple DDL script paths. NOTE: Use quotations around the entry.
6. -flyway_path: Optional, use only if providing directories to execute DB migrations via Flyway. Use a comma separator to enter multiple directory paths. NOTE: Use quotations around the entry. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions.
7. -force_import: A boolean flag which specifies whether or not the import ignores impact analysis results.If true, the import will occur even if objects with CDT references are missing
8. -import_customization_path: Indicates the path to the import customization file to use
9. -inspect_only: Optional, use to run an inspection of the package. Indicates the package should not be deployed but inspected only.
10. -password: Password of the Appian user account
11. -proxy_port: Optional, port of the proxy server to use to connect to Appian. This parameter is only used if the parameter -proxy_url is defined. The default value is 8080.
12. -proxy_url: Optional, URL of the proxy to use to connect to Appian.
13. -url: URL of the environment, of the format https://example.appian.com/suite.
14. -username: Username of the Appian user account to use for deployment
15. -uuid: UUID of the application to which patch contents will be added
Deploy the application by typing the command deploy-application.bat and including the relevant parameters. Your command will look something like the one pictured below.

deploy-application.bat -application_path "PATH TO APPLICATION ZIP" -username SERVICE_ACCOUNT_USERNAME -password SERVICE_ACCOUNT_PASSWORD -url APPIAN_URL -ddl_path "PATH TO DLL 1, PATH TO DLL 2" -ddl_ds jdbc/Appian1,jdbc/Appian2

Deploy from an External Continuous Integration tool

Additional Requirement:

An existing external Continuous Integration tool (such as Jenkins or Hudson) that is properly configured

The steps below provide the high level steps to deploy an application from Jenkins.

Create a new external job
Configure the job to run the import script using the guidance in Deployment Option #2 listed above
Execute the job

When the deployment is complete, check the status page verify that the import was successful.

Troubleshooting

Deciphering Script Error Messages

Inspect Failure

Package Validation Failure

In case you want to proceed with deploying the application regardless of missing CDT dependencies, use the flag -f.

Import Failure

Invalid Credentials

Please ensure that these credentials are associated with an active Appian system administrator account. Basic user credentials cannot be used.

Connection Refused With Deployment Command Line Script

A "Connection Refused" error could be the result of using the wrong URL when executing the script. The URL provided as a parameter must:

include the suffix "/suite"
Include a port number if not using the port 80 with HTTP or port 443 with HTTPS

Release Notes

September 2021 - Release 2.5.13

Bug Fixes
- Fixed an issue where setting "appianObjectsRepoPath" prevented a package that included a patches.xml file from being processed successfully

March 2021 - Release 2.5.12

Enhancements
- Updated the link to the import log in the ADM servlet after a change was made to the Appian API.
Bug Fixes
- Fixed a bug that was preventing Flyway files from being included in metadata.properties.

September 2020 - Release 2.5.11

Enhancements
- Upgraded Flyway version to 6.5.5 for compatibility with MariaDB.

August 2020 - Release 2.5.10

Enhancements
- Added the ability to dynamically generate the Metadata file for the "buildAllApps" action to reflect only the list of database scripts that are included in the package for a given commit range.
Bug Fixes
- Fixed the interpretation of "appianObjectsRepoPath" on Windows platforms.

December 2019 - Release 2.5.9

Enhancements
- Added DNS proxy support to ADM
- Added DNS proxy support to AIM
- Added DNS proxy support to AVM
- Added support for special characters in passwords in ADM

July 2019 - Release 2.5.8

Bug Fixes
- Fixed the problem with obtaining TransactionManager and creating DataConfiguration against latest the Appian version

April 2019 - Release 2.5.7

Enhancements
- Added commit message prompt to folder listener
Bug Fixes
- Fixed Windows issue with pushing file updates to versioning manager
- Fixed import patch failure not adding newly created objects issue
- Fixed semicolon separator parsing issue

March 2019 - Release 2.5.6

Enhancements
- Added proxy authentication support for import client

February 2019 - Release 2.5.5

Bug Fixes
- Fixed DDL paths bug

January 2019 - Release 2.5.4

Enhancements
- Improved descriptions of errors encountered during deployments
Bug Fixes
- Fixed "Connection Refused" bug when running on a Jenkins server
- Fixed "buildSingleApp" AVM bug when specifying an appianObjectsRepoPath
- Fixed rare "hanging" bug in AIM Client

November 2018 - Release 2.5.3

Enhancements
- Created a reset command for Remote Automated Deployment Manager
Bug Fixes
- Version and Import Metrics Logger Initialized correctly to fix null pointer exception

October 2018 - Release 2.5.2

Enhancements
- Folder listener to auto trigger “Add Contents” action
- Field validation for import and versioning manager properties files
- Usage metrics collection to better understand tool use
- Updated error log messages
Bug Fixes
- ADM UI: Handle apostrophes in app name
- ZIP type validation for Automated Import Manager

September 2018 - Release 2.5.1

Enhancements
- New buildMultipleApps action
- Check version of tools with -v or -version flags
Bug Fixes
- Fixed ADM SQL errors with non-null statements and forward slash as delimiters

August 2018 - Release 2.5.0

Enhancements
- Added Flyway DB version control tool to command line and AIM GUI
- Allow import of DDL scripts or Flyway scripts without an application zip or patch zip
- Added Folder Listener script that will run addContents automatically when a file is dropped into a folder
Bug Fixes
- Added buildAllApps to list of approved actions
- Set inspect_only properly in AIM
- Fixed bug where repo would be cloned into a folder with an incorrect name
- Passed in correct authentication token for buildAllApps and buildSingleApp

August 2018 - Release 2.4.7

Enhancements
- Added "buildSingleApp" action to extract one app from multi app repo
- Renamed "buildPackage" action to "buildAllApps" to better clarify the functionality
Bug Fixes
- Fixed miscellaneous issues with parsing SQL in DDL file
- Mark/reset issue with large customization files

June 2018 - Release 2.4.6

Enhancements
- Added an import-manager.properties file to set default values for importing applications
- Automated versioning manager supports adding a package with multiple patches
Bug Fixes
- Application version UUID is updated when adding patches to a version control
- Import no longer fails when SQL in DDL file contains a ";", "–" or "/**/"

March 2018 - Release 2.4.5

Add support for proxy configuration in the deployment client script with parameters "proxy_port" and "proxy_url"

January 2018 - Release 2.4.4

Bug fixes

January 2018 - Release 2.4.3

Support for Appian 17.4

September 2017 - Release 2.4.2

Support for Appian 17.3
Better handling of end of line characters in the SQL scripts
Support for customization file when deploying an application package

June 2017 - Release 2.4.1

Support for Appian 17.2
Fix defect preventing to execute DB scripts as part of a deployment

January 2017 - Release 2.4.0

Support for Appian 17.1

October 2016 - Release 2.3

Support for Appian 16.3

September 2016 - Release 2.2.9

Automated Import Manager

Successfully deploy application packages containing new Datastore entities and new dependents on these entities.

September 2016 - Release 2.2.8

Automated Versioning Manager

Fixed defect with missing artifacts in package when using START_HASH and END_HASH.

August 2016 - Release 2.2.7

Automated Versioning Manager

Fixed defect with deploying applications and patches containing updated Documents.

August 2016 - Release 2.2.6

Automated Versioning Manager

New parameter no_update to build a package from the local repository without first performing a checkout
New integrity control when checking in applications and patches

August 2016 - Release 2.2.5

Automated Versioning Manager

Fixed defect with deploying applications and patches containing new CDTs and updated CDTs.

June 2016 - Release 2.2.4

Bug fixes.

June 2016 - Release 2.2.3

Include the source code in all modules.

June 2016 - Release 2.2.2

Automated Versioning Manager

Added new parameter appian_objects_repo_path to specify where the Appian artifacts are located in the repository.

May 2016 - Release 2.2.0

Automated Versioning Manager

Added support for admin console packages

Automated Import Manager

Removed update-database-schema to support native product capability of automatic database updates via datastore and administration console.
Updated Web Browser UI style
Removed option for "Automatically update the database schema when publishing the data stores" from the Web Browser UI
Added support for admin console deployments
Added support in command line for inspect_only parameter

March 2016 - Release 2.1.0

Automated Versioning Manager

Added support for input flexibility. Now, the command line for versioning manager supports all possible parameters.
Allowed tags as inputs to start hash and end hash.
Added inputs of the following predefined keywords: FIRST_COMMIT (which maps to first commit ever made) and LAST_COMMIT (the previous commit). NOTE: this is only allowed on the start hash input.

Automated Import Manager

Added support for 16.1.
Added action for "Inspect Only".

Deployment Automation

joel.larin — Thu, 26 Oct 2023 18:23:03 GMT

Revision 8 posted to Guide by joel.larin on 10/26/2023 6:23:03 PM

Appian provides several DevOps tools to automate the deployment of Appian applications such as Compare & Deploy and Deployment APIs.

The tools described in this play offer a few alternatives to Appian base product features:

Tightly integrate with a version control system to store and retrieve package files using the Automated Versioning Manager (AVM)
Programmatically deploy Admin Console settings and applications using the Automated Import Manager (AIM) plug-in and the Automated Import Manager (AIM) client

Automated Versioning Manager

Summary

It unzips the application and organizes the artifact XML files in the repository.
It automates the check-in and checkout operations with the version control system.
It generates application packages for import in Appian based on the contents of the repository and a range of changes to include.

The goal of this tool is to facilitate the adoption and usage of a version control system to perform configuration management of the Appian applications and database DDL files.

Features

Version Control integration (Git, SVN)
Supports Appian applications and patches
Generate import package from hash ranges
Folder Listener to add contents to Version Control
Supports GitHub, GitLab, and BitBucket for Version Control

Usage

Script Execution

To run the script, open a command window and navigate to the directory where the automated versioning scripts are located. They are named version-application.bat or version-application.sh.

Use the -h or -help parameters to view the help menu within the script. The parameters are described here:

Required Parameters (required for all four actions: addContents, buildAllApps, buildSingleApp, buildMultipleApps, and updateLocalRepo)
- -action - Selects which action of the script to run. Acceptable values are: addContents, updateLocalRepo, buildAllApps, buildSingleApp, and buildMultipleApps. Each action is detailed in the use cases below.
- -vc_username -The username associated with the version control (Git or SVN) account. NOTE: these are NOT your Appian credentials.
- -vc_password -Please check the Security Settings of the version control account. If you have 2-factor authentication enabled, the password requires the version control account token. If you do NOT have 2-factor authentication enabled, the password is the one associated with the version control account. NOTE: these are NOT your Appian credentials.
Options for addContents action
- -application_path - The path on your filesystem where the application ZIP is located.
- -admin_console_path - The path on your filesystem where the admin console ZIP file is located.
- -ddl_path - List of comma-separated paths for the DDL files to be included in the deployment package.
- -flyway_path - List of comma-separated paths for the directories to execute DB migrations via Flyway. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions. To learn how the Automated Import Manager uses Flyway, refer to AIM Features.
- -ddl_ds - List of comma-separated datasources associated with the provided DDL files. Must provide the same number of entries as number of DDL files specified with the -ddl_path option or number of directories specified with the -flyway_path option. NOTE: the order of the specified datasource names must match the order of the script paths specified.
- -uuid - The UUID of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -application_name - The name of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -commit_message - The message that will be associated with the commit. If not included, a default commit message Committed by @username is provided.
Options for buildAllApps action
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildSingleApp action
- -uuid - The UUID of the application you want to build.
- -application_name - The name of the application you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildMultipleApps action
- -uuid - Comma separated list of UUIDs of the applications you want to build.
- -application_name - Comma separated list of names of the applications that you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for updateLocalRepo action
- There are no additional options (other than required options) for updateLocalRepo.
Additional Parameters - These parameters are REQUIRED, and may be specified here or in the properties file (described in the following section). If they are specified in both locations, the parameters specified in the command line take precedence.
- -version_control_type - The version control type used, either GIT or SVN.
- -local_repo_path - The path on the filesystem where the local repository is located. All files on the remote repository are cloned to this path. Example: C:\\MyFiles\\ChangeManagementRepo. NOTE: if using Windows, be sure to include double forward slashes (as seen in the example) for path separation.
- -appian_objects_repo_path - Path to the folder containing the Appian objects in the repository. This path is relative to the path of the local repository. If not specified, the Appian objects are checked out to and committed from the root of the local repository path.
- -repo_url - The URL that defines the remote repository. Example: https://github.com/git-username/project-name.git, svn+ssh://svn.code.sf.net/p/project-name/code
- -package_path - For buildAllApps, buildSingleApp, and buildMultipleApps only. The path on the filesystem where packages are generated. Must include filename of package.
- -branch_name - Branch to check out and use (if not master)

Configuring using the Properties File

In case an option is specified both on the command line and in the properties file, the command line value takes precedence and is used.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Use Cases

#1: New developer joins team (updateLocalRepo)

In this use case, a new developer has joined the team and wants to get a copy of all the work completed so far. The developer:

Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using updateLocalRepo as the action flag. The developer must provide the username and password for authenticating against their version control system (-vc_username, -vc_password).

Example Syntax:

> version-application -action updateLocalRepo -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD>

When the script is executed, the developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).

#2: Developer adds artifacts to the repository (addContents)

In the Appian development environment, create an application (or a patch) that contains the changed objects.
Export those changes and download the application ZIP file.
Run the script, using addContents as the action flag. The developer must provide the path of the ZIP file they exported (-application_path) from Appian in step 2. They must also provide the username and password for authenticating their version control system (-vc_username, -vc_password). NOTE: these are NOT Appian credentials.
1. Optional: if the application specified for -application_path is a patch, update the -uuid option to specify the parent application’s uuid. The script will exit with error if a patch application ZIP is provided but no uuid is passed in.
2. Optional: if DDL scripts have been modified, specify the path(s) and their associated JDBC datasource names. NOTE: The same number of DDL scripts and datasource names must be entered into the script, even if the datasource is the same for all scripts. For example: the developer wishes to add two ddl scripts located at C:\DDLs\script1.sql and C:\DDLs\script2.sql. They do so by setting the -ddl_path option as C:\DDLs\script1.sql,C:\DDLs\script2.sql If both scripts are to be executed on jdbc/AppianDS, they must set the -ddl_ds option as jdbc/AppianDS,jdbc/AppianDS. Note that the datasource name is passed in twice.
Optional: include a custom commit message using the -commit_message option

Example Syntax:

> version-application -action addContents -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -application_path "C:\App.zip" -ddl_ds jdbc/AppianAnywhere -ddl_path “C:\script1.sql” -commit_message “Adding account executive record”

When the script is executed, three things occur:

The developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).
The application ZIP is unzipped and placed into the local repository, and the DDL files are placed into a ddl_files folder within the local repository. If the -uuid option is selected, the appropriate application xml file is updated.
The changes are committed (and pushed, if using Git) to the remote repository.

When the package is imported into Appian, all lines within script1.sql will be executed and contents within the application ZIP are imported.

Using Folder Listener:

Alternatively, instead of running the script, the developer can execute avm-folder-listener-<os> in the folder-listener directory. The following command prompt will appear:

#3: Build master generates new RC deployment package (buildAllApps)

(If not done previously) Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using buildAllApps as the action flag. The build master must provide the username and password for authenticating against their version control system (-vc_username, -vc_password). To get a specific set of changes, input a value for the -start_hash option and the -end_hash option. This will generate the package with all new and changed files between the two hash options.
1. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.

Example Command:

> version-application -action buildAllApps -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -start_hash ac37459 -end_hash 6e83b42

When the script is executed, it generates a package at the location specified by the packagePath field in version-manager.properties.

Finally, the build master will import the RC package into the higher environment using the Automated Import tool as described later in this play.

Using Subversion as Version Control System

To allow the Automated Versioning Manager to perform the checkout and commit operations with Subversion, the tool assumes the common Subversion project structure:

trunk
branches
tags

The location of the repository root must be provided by the property repoURL.

versionControlType=SVN

repoUrl=https://svn.code.sf.net/p/deploymentautomationexample/code

branchName=branches/release1

Using Git as Version Control System

To use Git with the Automated Versioning Manager, properties may be specified on the command line or version-manager.properties should be updated as follows:

versionControlType=GIT

repoUrl=https://github.com/gituser/testgitrepo.git

branchName=newbranch

Note: if you are planning to check out a private repository, use the Git SSH URL rather than the HTTPS URL.

Automated Import Manager

Summary

The Automated Import Manager automates the process of inspecting the application, executing DDL scripts, updating CDTs, republishing the appropriate datastores, and importing the application.

Features

Inspect Application: This tool will automatically mimic the "Inspect" functionality that exists within Appian
Validating Application Content: In addition to inspecting the application, the tool will ensure all CDT dependents are included to avoid objects pointing to older versions.
Execute DDL Scripts: DDL scripts can be uploaded and automatically executed. NOTE: For Microsoft SQL Server, only Transact-SQL statements are valid.
Execute Migrations with Flyway: Flyway is a tool used for managing database migrations. It makes it easier to track SQL script versions and not re-execute SQL scripts that have already been run. If a Flyway directory is provided, the Automated Import Manager will automatically execute migrations against the corresponding datasource. Learn more about Flyway here.
Update CDTs: Users are no longer required to delete CDTs before updating them, this tool will perform this step automatically
Import Application and admin console configuration: Automatically import an application with an optional customization file
Republish Datastores: After application import, datastores will be automatically published or republished
Add Patches: Automatically add patch contents to a specified existing application

Usage

Deploy from the Web Browser UI

The tool collects usage metrics by default. To opt-out of metrics collection, check the below option on the Web Browser UI:

Log into Appian as a system administrator
Navigate to the Deployment Automation UI available at the URL: <appian>/suite/plugins/servlet/deploymentautomation
Upload the patch or application you wish to import.
If this application is a patch, select the parent application to which patch contents should be added.
If the new application requires changes to the database schema (i.e. new or updated CDTs) you must choose one of the following:
1. Upload the corresponding DDL script(s) that accurately reflect these additions and/or updates.
2. Set the datastore to "Automatically update database schema" and set "Allow Database Schema Changes Through Data Stores" in the Deployment section of the Appian Administration Console
Click on the button "Start Deployment".
During the deployment, the screen is automatically refreshed every 5 seconds with the latest status of the deployment.
When the deployment is complete, the browser will update with a status page.

Deploy from the Command Line Script

The command line script - the client - can be downloaded from the Appian AppMarket.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Open a command window in the same folder to which the client script and supporting libraries were unzipped.
Using the help guide pictured above, run the proper command to automatically import the application. Use -h or -help to view this menu at any time.
1. -ac_customization_path: Indicates the path to the customization file to use when deploying the admin console package or the application package.
2. -admin_console_path: Indicates the path to the admin console file to deploy. NOTE: Use quotations around the entry.
3. -application_path: Indicates the path to the application file to deploy. NOTE: Use quotations around the entry.
4. -ddl_ds: Optional, use only if providing DDL scripts. The name of the datasource to use with the corresponding DDL script. Use a comma separator to enter multiple datasources.
5. -ddl_path: Optional, use only if providing DDL scripts. Indicates the path to the DDL scripts to execute. Use a comma separator to enter multiple DDL script paths. NOTE: Use quotations around the entry.
6. -flyway_path: Optional, use only if providing directories to execute DB migrations via Flyway. Use a comma separator to enter multiple directory paths. NOTE: Use quotations around the entry. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions.
7. -force_import: A boolean flag which specifies whether or not the import ignores impact analysis results.If true, the import will occur even if objects with CDT references are missing
8. -import_customization_path: Indicates the path to the import customization file to use
9. -inspect_only: Optional, use to run an inspection of the package. Indicates the package should not be deployed but inspected only.
10. -password: Password of the Appian user account
11. -proxy_port: Optional, port of the proxy server to use to connect to Appian. This parameter is only used if the parameter -proxy_url is defined. The default value is 8080.
12. -proxy_url: Optional, URL of the proxy to use to connect to Appian.
13. -url: URL of the environment, of the format https://example.appian.com/suite.
14. -username: Username of the Appian user account to use for deployment
15. -uuid: UUID of the application to which patch contents will be added
Deploy the application by typing the command deploy-application.bat and including the relevant parameters. Your command will look something like the one pictured below.

deploy-application.bat -application_path "PATH TO APPLICATION ZIP" -username SERVICE_ACCOUNT_USERNAME -password SERVICE_ACCOUNT_PASSWORD -url APPIAN_URL -ddl_path "PATH TO DLL 1, PATH TO DLL 2" -ddl_ds jdbc/Appian1,jdbc/Appian2

Deploy from an External Continuous Integration tool

Additional Requirement:

An existing external Continuous Integration tool (such as Jenkins or Hudson) that is properly configured

The steps below provide the high level steps to deploy an application from Jenkins.

Create a new external job
Configure the job to run the import script using the guidance in Deployment Option #2 listed above
Execute the job

When the deployment is complete, check the status page verify that the import was successful.

Troubleshooting

Deciphering Script Error Messages

Inspect Failure

Package Validation Failure

In case you want to proceed with deploying the application regardless of missing CDT dependencies, use the flag -f.

Import Failure

Invalid Credentials

Please ensure that these credentials are associated with an active Appian system administrator account. Basic user credentials cannot be used.

Connection Refused With Deployment Command Line Script

A "Connection Refused" error could be the result of using the wrong URL when executing the script. The URL provided as a parameter must:

include the suffix "/suite"
Include a port number if not using the port 80 with HTTP or port 443 with HTTPS

Release Notes

September 2021 - Release 2.5.13

Bug Fixes
- Fixed an issue where setting "appianObjectsRepoPath" prevented a package that included a patches.xml file from being processed successfully

March 2021 - Release 2.5.12

Enhancements
- Updated the link to the import log in the ADM servlet after a change was made to the Appian API.
Bug Fixes
- Fixed a bug that was preventing Flyway files from being included in metadata.properties.

September 2020 - Release 2.5.11

Enhancements
- Upgraded Flyway version to 6.5.5 for compatibility with MariaDB.

August 2020 - Release 2.5.10

Enhancements
- Added the ability to dynamically generate the Metadata file for the "buildAllApps" action to reflect only the list of database scripts that are included in the package for a given commit range.
Bug Fixes
- Fixed the interpretation of "appianObjectsRepoPath" on Windows platforms.

December 2019 - Release 2.5.9

Enhancements
- Added DNS proxy support to ADM
- Added DNS proxy support to AIM
- Added DNS proxy support to AVM
- Added support for special characters in passwords in ADM

July 2019 - Release 2.5.8

Bug Fixes
- Fixed the problem with obtaining TransactionManager and creating DataConfiguration against latest the Appian version

April 2019 - Release 2.5.7

Enhancements
- Added commit message prompt to folder listener
Bug Fixes
- Fixed Windows issue with pushing file updates to versioning manager
- Fixed import patch failure not adding newly created objects issue
- Fixed semicolon separator parsing issue

March 2019 - Release 2.5.6

Enhancements
- Added proxy authentication support for import client

February 2019 - Release 2.5.5

Bug Fixes
- Fixed DDL paths bug

January 2019 - Release 2.5.4

Enhancements
- Improved descriptions of errors encountered during deployments
Bug Fixes
- Fixed "Connection Refused" bug when running on a Jenkins server
- Fixed "buildSingleApp" AVM bug when specifying an appianObjectsRepoPath
- Fixed rare "hanging" bug in AIM Client

November 2018 - Release 2.5.3

Enhancements
- Created a reset command for Remote Automated Deployment Manager
Bug Fixes
- Version and Import Metrics Logger Initialized correctly to fix null pointer exception

October 2018 - Release 2.5.2

Enhancements
- Folder listener to auto trigger “Add Contents” action
- Field validation for import and versioning manager properties files
- Usage metrics collection to better understand tool use
- Updated error log messages
Bug Fixes
- ADM UI: Handle apostrophes in app name
- ZIP type validation for Automated Import Manager

September 2018 - Release 2.5.1

Enhancements
- New buildMultipleApps action
- Check version of tools with -v or -version flags
Bug Fixes
- Fixed ADM SQL errors with non-null statements and forward slash as delimiters

August 2018 - Release 2.5.0

Enhancements
- Added Flyway DB version control tool to command line and AIM GUI
- Allow import of DDL scripts or Flyway scripts without an application zip or patch zip
- Added Folder Listener script that will run addContents automatically when a file is dropped into a folder
Bug Fixes
- Added buildAllApps to list of approved actions
- Set inspect_only properly in AIM
- Fixed bug where repo would be cloned into a folder with an incorrect name
- Passed in correct authentication token for buildAllApps and buildSingleApp

August 2018 - Release 2.4.7

Enhancements
- Added "buildSingleApp" action to extract one app from multi app repo
- Renamed "buildPackage" action to "buildAllApps" to better clarify the functionality
Bug Fixes
- Fixed miscellaneous issues with parsing SQL in DDL file
- Mark/reset issue with large customization files

June 2018 - Release 2.4.6

Enhancements
- Added an import-manager.properties file to set default values for importing applications
- Automated versioning manager supports adding a package with multiple patches
Bug Fixes
- Application version UUID is updated when adding patches to a version control
- Import no longer fails when SQL in DDL file contains a ";", "–" or "/**/"

March 2018 - Release 2.4.5

Add support for proxy configuration in the deployment client script with parameters "proxy_port" and "proxy_url"

January 2018 - Release 2.4.4

Bug fixes

January 2018 - Release 2.4.3

Support for Appian 17.4

September 2017 - Release 2.4.2

Support for Appian 17.3
Better handling of end of line characters in the SQL scripts
Support for customization file when deploying an application package

June 2017 - Release 2.4.1

Support for Appian 17.2
Fix defect preventing to execute DB scripts as part of a deployment

January 2017 - Release 2.4.0

Support for Appian 17.1

October 2016 - Release 2.3

Support for Appian 16.3

September 2016 - Release 2.2.9

Automated Import Manager

Successfully deploy application packages containing new Datastore entities and new dependents on these entities.

September 2016 - Release 2.2.8

Automated Versioning Manager

Fixed defect with missing artifacts in package when using START_HASH and END_HASH.

August 2016 - Release 2.2.7

Automated Versioning Manager

Fixed defect with deploying applications and patches containing updated Documents.

August 2016 - Release 2.2.6

Automated Versioning Manager

New parameter no_update to build a package from the local repository without first performing a checkout
New integrity control when checking in applications and patches

August 2016 - Release 2.2.5

Automated Versioning Manager

Fixed defect with deploying applications and patches containing new CDTs and updated CDTs.

June 2016 - Release 2.2.4

Bug fixes.

June 2016 - Release 2.2.3

Include the source code in all modules.

June 2016 - Release 2.2.2

Automated Versioning Manager

Added new parameter appian_objects_repo_path to specify where the Appian artifacts are located in the repository.

May 2016 - Release 2.2.0

Automated Versioning Manager

Added support for admin console packages

Automated Import Manager

Removed update-database-schema to support native product capability of automatic database updates via datastore and administration console.
Updated Web Browser UI style
Removed option for "Automatically update the database schema when publishing the data stores" from the Web Browser UI
Added support for admin console deployments
Added support in command line for inspect_only parameter

March 2016 - Release 2.1.0

Automated Versioning Manager

Added support for input flexibility. Now, the command line for versioning manager supports all possible parameters.
Allowed tags as inputs to start hash and end hash.
Added inputs of the following predefined keywords: FIRST_COMMIT (which maps to first commit ever made) and LAST_COMMIT (the previous commit). NOTE: this is only allowed on the start hash input.

Automated Import Manager

Added support for 16.1.
Added action for "Inspect Only".

Deployment Automation

joel.larin — Thu, 26 Oct 2023 18:18:40 GMT

Revision 7 posted to Guide by joel.larin on 10/26/2023 6:18:40 PM

Appian provides several DevOps tools to automate the deployment of Appian applications such as Compare & Deploy and Deployment APIs.

The tools described in this play offer a few alternatives to Appian base product features:

Tightly integrate with a version control system to store and retrieve package files using the Automated Versioning Manager (AVM)
Programmatically deploy Admin Console settings and applications using the Automated Import Manager (AIM) plug-in and the Automated Import Manager (AIM) client

Automated Versioning Manager

Summary

It unzips the application and organizes the artifact XML files in the repository.
It automates the check-in and checkout operations with the version control system.
It generates application packages for import in Appian based on the contents of the repository and a range of changes to include.

The goal of this tool is to facilitate the adoption and usage of a version control system to perform configuration management of the Appian applications and database DDL files.

Features

Version Control integration (Git, SVN)
Supports Appian applications and patches
Generate import package from hash ranges
Folder Listener to add contents to Version Control
Supports GitHub, GitLab, and BitBucket for Version Control

Usage

Script Execution

To run the script, open a command window and navigate to the directory where the automated versioning scripts are located. They are named version-application.bat or version-application.sh.

Use the -h or -help parameters to view the help menu within the script. The parameters are described here:

Required Parameters (required for all four actions: addContents, buildAllApps, buildSingleApp, buildMultipleApps, and updateLocalRepo)
- -action - Selects which action of the script to run. Acceptable values are: addContents, updateLocalRepo, buildAllApps, buildSingleApp, and buildMultipleApps. Each action is detailed in the use cases below.
- -vc_username -The username associated with the version control (Git or SVN) account. NOTE: these are NOT your Appian credentials.
- -vc_password -Please check the Security Settings of the version control account. If you have 2-factor authentication enabled, the password requires the version control account token. If you do NOT have 2-factor authentication enabled, the password is the one associated with the version control account. NOTE: these are NOT your Appian credentials.
Options for addContents action
- -application_path - The path on your filesystem where the application ZIP is located.
- -admin_console_path - The path on your filesystem where the admin console ZIP file is located.
- -ddl_path - List of comma-separated paths for the DDL files to be included in the deployment package.
- -flyway_path - List of comma-separated paths for the directories to execute DB migrations via Flyway. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions. To learn how the Automated Import Manager uses Flyway, refer to AIM Features.
- -ddl_ds - List of comma-separated datasources associated with the provided DDL files. Must provide the same number of entries as number of DDL files specified with the -ddl_path option or number of directories specified with the -flyway_path option. NOTE: the order of the specified datasource names must match the order of the script paths specified.
- -uuid - The UUID of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -application_name - The name of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -commit_message - The message that will be associated with the commit. If not included, a default commit message Committed by @username is provided.
Options for buildAllApps action
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildSingleApp action
- -uuid - The UUID of the application you want to build.
- -application_name - The name of the application you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildMultipleApps action
- -uuid - Comma separated list of UUIDs of the applications you want to build.
- -application_name - Comma separated list of names of the applications that you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for updateLocalRepo action
- There are no additional options (other than required options) for updateLocalRepo.
Additional Parameters - These parameters are REQUIRED, and may be specified here or in the properties file (described in the following section). If they are specified in both locations, the parameters specified in the command line take precedence.
- -version_control_type - The version control type used, either GIT or SVN.
- -local_repo_path - The path on the filesystem where the local repository is located. All files on the remote repository are cloned to this path. Example: C:\\MyFiles\\ChangeManagementRepo. NOTE: if using Windows, be sure to include double forward slashes (as seen in the example) for path separation.
- -appian_objects_repo_path - Path to the folder containing the Appian objects in the repository. This path is relative to the path of the local repository. If not specified, the Appian objects are checked out to and committed from the root of the local repository path.
- -repo_url - The URL that defines the remote repository. Example: https://github.com/git-username/project-name.git, svn+ssh://svn.code.sf.net/p/project-name/code
- -package_path - For buildAllApps, buildSingleApp, and buildMultipleApps only. The path on the filesystem where packages are generated. Must include filename of package.
- -branch_name - Branch to check out and use (if not master)

Configuring using the Properties File

In case an option is specified both on the command line and in the properties file, the command line value takes precedence and is used.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Use Cases

#1: New developer joins team (updateLocalRepo)

In this use case, a new developer has joined the team and wants to get a copy of all the work completed so far. The developer:

Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using updateLocalRepo as the action flag. The developer must provide the username and password for authenticating against their version control system (-vc_username, -vc_password).

Example Syntax:

> version-application -action updateLocalRepo -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD>

When the script is executed, the developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).

#2: Developer adds artifacts to the repository (addContents)

In the Appian development environment, create an application (or a patch) that contains the changed objects.
Export those changes and download the application ZIP file.
Run the script, using addContents as the action flag. The developer must provide the path of the ZIP file they exported (-application_path) from Appian in step 2. They must also provide the username and password for authenticating their version control system (-vc_username, -vc_password). NOTE: these are NOT Appian credentials.
1. Optional: if the application specified for -application_path is a patch, update the -uuid option to specify the parent application’s uuid. The script will exit with error if a patch application ZIP is provided but no uuid is passed in.
2. Optional: if DDL scripts have been modified, specify the path(s) and their associated JDBC datasource names. NOTE: The same number of DDL scripts and datasource names must be entered into the script, even if the datasource is the same for all scripts. For example: the developer wishes to add two ddl scripts located at C:\DDLs\script1.sql and C:\DDLs\script2.sql. They do so by setting the -ddl_path option as C:\DDLs\script1.sql,C:\DDLs\script2.sql If both scripts are to be executed on jdbc/AppianDS, they must set the -ddl_ds option as jdbc/AppianDS,jdbc/AppianDS. Note that the datasource name is passed in twice.
Optional: include a custom commit message using the -commit_message option

Example Syntax:

> version-application -action addContents -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -application_path "C:\App.zip" -ddl_ds jdbc/AppianAnywhere -ddl_path “C:\script1.sql” -commit_message “Adding account executive record”

When the script is executed, three things occur:

The developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).
The application ZIP is unzipped and placed into the local repository, and the DDL files are placed into a ddl_files folder within the local repository. If the -uuid option is selected, the appropriate application xml file is updated.
The changes are committed (and pushed, if using Git) to the remote repository.

When the package is imported into Appian, all lines within script1.sql will be executed and contents within the application ZIP are imported.

Using Folder Listener:

Alternatively, instead of running the script, the developer can execute avm-folder-listener-<os> in the folder-listener directory. The following command prompt will appear:

#3: Build master generates new RC deployment package (buildAllApps)

(If not done previously) Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using buildAllApps as the action flag. The build master must provide the username and password for authenticating against their version control system (-vc_username, -vc_password). To get a specific set of changes, input a value for the -start_hash option and the -end_hash option. This will generate the package with all new and changed files between the two hash options.
1. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.

Example Command:

> version-application -action buildAllApps -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -start_hash ac37459 -end_hash 6e83b42

When the script is executed, it generates a package at the location specified by the packagePath field in version-manager.properties.

Finally, the build master will import the RC package into the higher environment using the Automated Import tool as described later in this play.

Using Subversion as Version Control System

To allow the Automated Versioning Manager to perform the checkout and commit operations with Subversion, the tool assumes the common Subversion project structure:

trunk
branches
tags

The location of the repository root must be provided by the property repoURL.

versionControlType=SVN

repoUrl=https://svn.code.sf.net/p/deploymentautomationexample/code

branchName=branches/release1

Using Git as Version Control System

To use Git with the Automated Versioning Manager, properties may be specified on the command line or version-manager.properties should be updated as follows:

versionControlType=GIT

repoUrl=https://github.com/gituser/testgitrepo.git

branchName=newbranch

Note: if you are planning to check out a private repository, use the Git SSH URL rather than the HTTPS URL.

Automated Import Manager

Summary

The Automated Import Manager automates the process of inspecting the application, executing DDL scripts, updating CDTs, republishing the appropriate datastores, and importing the application.

Features

Inspect Application: This tool will automatically mimic the "Inspect" functionality that exists within Appian
Validating Application Content: In addition to inspecting the application, the tool will ensure all CDT dependents are included to avoid objects pointing to older versions.
Execute DDL Scripts: DDL scripts can be uploaded and automatically executed. NOTE: For Microsoft SQL Server, only Transact-SQL statements are valid.
Execute Migrations with Flyway: Flyway is a tool used for managing database migrations. It makes it easier to track SQL script versions and not re-execute SQL scripts that have already been run. If a Flyway directory is provided, the Automated Import Manager will automatically execute migrations against the corresponding datasource. Learn more about Flyway here.
Update CDTs: Users are no longer required to delete CDTs before updating them, this tool will perform this step automatically
Import Application and admin console configuration: Automatically import an application with an optional customization file
Republish Datastores: After application import, datastores will be automatically published or republished
Add Patches: Automatically add patch contents to a specified existing application

Usage

Deploy from the Web Browser UI

The tool collects usage metrics by default. To opt-out of metrics collection, check the below option on the Web Browser UI:

Log into Appian as a system administrator
Navigate to the Deployment Automation UI available at the URL: <appian>/suite/plugins/servlet/deploymentautomation
Upload the patch or application you wish to import.
If this application is a patch, select the parent application to which patch contents should be added.
If the new application requires changes to the database schema (i.e. new or updated CDTs) you must choose one of the following:
1. Upload the corresponding DDL script(s) that accurately reflect these additions and/or updates.
2. Set the datastore to "Automatically update database schema" and set "Allow Database Schema Changes Through Data Stores" in the Deployment section of the Appian Administration Console
Click on the button "Start Deployment".
During the deployment, the screen is automatically refreshed every 5 seconds with the latest status of the deployment.
When the deployment is complete, the browser will update with a status page.

Deploy from the Command Line Script

The command line script - the client - can be downloaded from the Appian AppMarket.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Open a command window in the same folder to which the client script and supporting libraries were unzipped.
Using the help guide pictured above, run the proper command to automatically import the application. Use -h or -help to view this menu at any time.
1. -ac_customization_path: Indicates the path to the customization file to use when deploying the admin console package or the application package.
2. -admin_console_path: Indicates the path to the admin console file to deploy. NOTE: Use quotations around the entry.
3. -application_path: Indicates the path to the application file to deploy. NOTE: Use quotations around the entry.
4. -ddl_ds: Optional, use only if providing DDL scripts. The name of the datasource to use with the corresponding DDL script. Use a comma separator to enter multiple datasources.
5. -ddl_path: Optional, use only if providing DDL scripts. Indicates the path to the DDL scripts to execute. Use a comma separator to enter multiple DDL script paths. NOTE: Use quotations around the entry.
6. -flyway_path: Optional, use only if providing directories to execute DB migrations via Flyway. Use a comma separator to enter multiple directory paths. NOTE: Use quotations around the entry. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions.
7. -force_import: A boolean flag which specifies whether or not the import ignores impact analysis results.If true, the import will occur even if objects with CDT references are missing
8. -import_customization_path: Indicates the path to the import customization file to use
9. -inspect_only: Optional, use to run an inspection of the package. Indicates the package should not be deployed but inspected only.
10. -password: Password of the Appian user account
11. -proxy_port: Optional, port of the proxy server to use to connect to Appian. This parameter is only used if the parameter -proxy_url is defined. The default value is 8080.
12. -proxy_url: Optional, URL of the proxy to use to connect to Appian.
13. -url: URL of the environment, of the format https://example.appian.com/suite.
14. -username: Username of the Appian user account to use for deployment
15. -uuid: UUID of the application to which patch contents will be added
Deploy the application by typing the command deploy-application.bat and including the relevant parameters. Your command will look something like the one pictured below.

deploy-application.bat -application_path "PATH TO APPLICATION ZIP" -username SERVICE_ACCOUNT_USERNAME -password SERVICE_ACCOUNT_PASSWORD -url APPIAN_URL -ddl_path "PATH TO DLL 1, PATH TO DLL 2" -ddl_ds jdbc/Appian1,jdbc/Appian2

Deploy from an External Continuous Integration tool

Additional Requirement:

An existing external Continuous Integration tool (such as Jenkins or Hudson) that is properly configured

The steps below provide the high level steps to deploy an application from Jenkins.

Create a new external job
Configure the job to run the import script using the guidance in Deployment Option #2 listed above
Execute the job

When the deployment is complete, check the status page verify that the import was successful.

Troubleshooting

Deciphering Script Error Messages

Inspect Failure

Package Validation Failure

In case you want to proceed with deploying the application regardless of missing CDT dependencies, use the flag -f.

Import Failure

Invalid Credentials

Please ensure that these credentials are associated with an active Appian system administrator account. Basic user credentials cannot be used.

Connection Refused With Deployment Command Line Script

A "Connection Refused" error could be the result of using the wrong URL when executing the script. The URL provided as a parameter must:

include the suffix "/suite"
Include a port number if not using the port 80 with HTTP or port 443 with HTTPS

Release Notes

September 2021 - Release 2.5.13

Bug Fixes
- Fixed an issue where setting "appianObjectsRepoPath" prevented a package that included a patches.xml file from being processed successfully

March 2021 - Release 2.5.12

Enhancements
- Updated the link to the import log in the ADM servlet after a change was made to the Appian API.
Bug Fixes
- Fixed a bug that was preventing Flyway files from being included in metadata.properties.

September 2020 - Release 2.5.11

Enhancements
- Upgraded Flyway version to 6.5.5 for compatibility with MariaDB.

August 2020 - Release 2.5.10

Enhancements
- Added the ability to dynamically generate the Metadata file for the "buildAllApps" action to reflect only the list of database scripts that are included in the package for a given commit range.
Bug Fixes
- Fixed the interpretation of "appianObjectsRepoPath" on Windows platforms.

December 2019 - Release 2.5.9

Enhancements
- Added DNS proxy support to ADM
- Added DNS proxy support to AIM
- Added DNS proxy support to AVM
- Added support for special characters in passwords in ADM

July 2019 - Release 2.5.8

Bug Fixes
- Fixed the problem with obtaining TransactionManager and creating DataConfiguration against latest the Appian version

April 2019 - Release 2.5.7

Enhancements
- Added commit message prompt to folder listener
Bug Fixes
- Fixed Windows issue with pushing file updates to versioning manager
- Fixed import patch failure not adding newly created objects issue
- Fixed semicolon separator parsing issue

March 2019 - Release 2.5.6

Enhancements
- Added proxy authentication support for import client

February 2019 - Release 2.5.5

Bug Fixes
- Fixed DDL paths bug

January 2019 - Release 2.5.4

Enhancements
- Improved descriptions of errors encountered during deployments
Bug Fixes
- Fixed "Connection Refused" bug when running on a Jenkins server
- Fixed "buildSingleApp" AVM bug when specifying an appianObjectsRepoPath
- Fixed rare "hanging" bug in AIM Client

November 2018 - Release 2.5.3

Enhancements
- Created a reset command for Remote Automated Deployment Manager
Bug Fixes
- Version and Import Metrics Logger Initialized correctly to fix null pointer exception

October 2018 - Release 2.5.2

Enhancements
- Folder listener to auto trigger “Add Contents” action
- Field validation for import and versioning manager properties files
- Usage metrics collection to better understand tool use
- Updated error log messages
Bug Fixes
- ADM UI: Handle apostrophes in app name
- ZIP type validation for Automated Import Manager

September 2018 - Release 2.5.1

Enhancements
- New buildMultipleApps action
- Check version of tools with -v or -version flags
Bug Fixes
- Fixed ADM SQL errors with non-null statements and forward slash as delimiters

August 2018 - Release 2.5.0

Enhancements
- Added Flyway DB version control tool to command line and AIM GUI
- Allow import of DDL scripts or Flyway scripts without an application zip or patch zip
- Added Folder Listener script that will run addContents automatically when a file is dropped into a folder
Bug Fixes
- Added buildAllApps to list of approved actions
- Set inspect_only properly in AIM
- Fixed bug where repo would be cloned into a folder with an incorrect name
- Passed in correct authentication token for buildAllApps and buildSingleApp

August 2018 - Release 2.4.7

Enhancements
- Added "buildSingleApp" action to extract one app from multi app repo
- Renamed "buildPackage" action to "buildAllApps" to better clarify the functionality
Bug Fixes
- Fixed miscellaneous issues with parsing SQL in DDL file
- Mark/reset issue with large customization files

June 2018 - Release 2.4.6

Enhancements
- Added an import-manager.properties file to set default values for importing applications
- Automated versioning manager supports adding a package with multiple patches
Bug Fixes
- Application version UUID is updated when adding patches to a version control
- Import no longer fails when SQL in DDL file contains a ";", "–" or "/**/"

March 2018 - Release 2.4.5

Add support for proxy configuration in the deployment client script with parameters "proxy_port" and "proxy_url"

January 2018 - Release 2.4.4

Bug fixes

January 2018 - Release 2.4.3

Support for Appian 17.4

September 2017 - Release 2.4.2

Support for Appian 17.3
Better handling of end of line characters in the SQL scripts
Support for customization file when deploying an application package

June 2017 - Release 2.4.1

Support for Appian 17.2
Fix defect preventing to execute DB scripts as part of a deployment

January 2017 - Release 2.4.0

Support for Appian 17.1

October 2016 - Release 2.3

Support for Appian 16.3

September 2016 - Release 2.2.9

Automated Import Manager

Successfully deploy application packages containing new Datastore entities and new dependents on these entities.

September 2016 - Release 2.2.8

Automated Versioning Manager

Fixed defect with missing artifacts in package when using START_HASH and END_HASH.

August 2016 - Release 2.2.7

Automated Versioning Manager

Fixed defect with deploying applications and patches containing updated Documents.

August 2016 - Release 2.2.6

Automated Versioning Manager

New parameter no_update to build a package from the local repository without first performing a checkout
New integrity control when checking in applications and patches

August 2016 - Release 2.2.5

Automated Versioning Manager

Fixed defect with deploying applications and patches containing new CDTs and updated CDTs.

June 2016 - Release 2.2.4

Bug fixes.

June 2016 - Release 2.2.3

Include the source code in all modules.

June 2016 - Release 2.2.2

Automated Versioning Manager

Added new parameter appian_objects_repo_path to specify where the Appian artifacts are located in the repository.

May 2016 - Release 2.2.0

Automated Versioning Manager

Added support for admin console packages

Automated Import Manager

Removed update-database-schema to support native product capability of automatic database updates via datastore and administration console.
Updated Web Browser UI style
Removed option for "Automatically update the database schema when publishing the data stores" from the Web Browser UI
Added support for admin console deployments
Added support in command line for inspect_only parameter

March 2016 - Release 2.1.0

Automated Versioning Manager

Added support for input flexibility. Now, the command line for versioning manager supports all possible parameters.
Allowed tags as inputs to start hash and end hash.
Added inputs of the following predefined keywords: FIRST_COMMIT (which maps to first commit ever made) and LAST_COMMIT (the previous commit). NOTE: this is only allowed on the start hash input.

Automated Import Manager

Added support for 16.1.
Added action for "Inspect Only".

Deployment Automation

joel.larin — Thu, 26 Oct 2023 18:17:11 GMT

Revision 6 posted to Guide by joel.larin on 10/26/2023 6:17:11 PM

Appian provides several DevOps tools to automate the deployment of Appian applications such as Compare & Deploy and Deployment APIs.

The tools described in this play offer a few alternatives to Appian base product features:

Tightly integrate with a version control system to store and retrieve package files using the Automated Versioning Manager (AVM)
Programmatically deploy Admin Console settings and applications using the Automated Import Manager (AIM) plug-in and the Automated Import Manager (AIM) client

Table Of Content

Automated Versioning Manager
Automated Import Manager
Troubleshooting
Release Notes

Automated Versioning Manager

Summary

It unzips the application and organizes the artifact XML files in the repository.
It automates the check-in and checkout operations with the version control system.
It generates application packages for import in Appian based on the contents of the repository and a range of changes to include.

The goal of this tool is to facilitate the adoption and usage of a version control system to perform configuration management of the Appian applications and database DDL files.

Features

Version Control integration (Git, SVN)
Supports Appian applications and patches
Generate import package from hash ranges
Folder Listener to add contents to Version Control
Supports GitHub, GitLab, and BitBucket for Version Control

Usage

Script Execution

To run the script, open a command window and navigate to the directory where the automated versioning scripts are located. They are named version-application.bat or version-application.sh.

Use the -h or -help parameters to view the help menu within the script. The parameters are described here:

Required Parameters (required for all four actions: addContents, buildAllApps, buildSingleApp, buildMultipleApps, and updateLocalRepo)
- -action - Selects which action of the script to run. Acceptable values are: addContents, updateLocalRepo, buildAllApps, buildSingleApp, and buildMultipleApps. Each action is detailed in the use cases below.
- -vc_username -The username associated with the version control (Git or SVN) account. NOTE: these are NOT your Appian credentials.
- -vc_password -Please check the Security Settings of the version control account. If you have 2-factor authentication enabled, the password requires the version control account token. If you do NOT have 2-factor authentication enabled, the password is the one associated with the version control account. NOTE: these are NOT your Appian credentials.
Options for addContents action
- -application_path - The path on your filesystem where the application ZIP is located.
- -admin_console_path - The path on your filesystem where the admin console ZIP file is located.
- -ddl_path - List of comma-separated paths for the DDL files to be included in the deployment package.
- -flyway_path - List of comma-separated paths for the directories to execute DB migrations via Flyway. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions. To learn how the Automated Import Manager uses Flyway, refer to AIM Features.
- -ddl_ds - List of comma-separated datasources associated with the provided DDL files. Must provide the same number of entries as number of DDL files specified with the -ddl_path option or number of directories specified with the -flyway_path option. NOTE: the order of the specified datasource names must match the order of the script paths specified.
- -uuid - The UUID of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -application_name - The name of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -commit_message - The message that will be associated with the commit. If not included, a default commit message Committed by @username is provided.
Options for buildAllApps action
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildSingleApp action
- -uuid - The UUID of the application you want to build.
- -application_name - The name of the application you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildMultipleApps action
- -uuid - Comma separated list of UUIDs of the applications you want to build.
- -application_name - Comma separated list of names of the applications that you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for updateLocalRepo action
- There are no additional options (other than required options) for updateLocalRepo.
Additional Parameters - These parameters are REQUIRED, and may be specified here or in the properties file (described in the following section). If they are specified in both locations, the parameters specified in the command line take precedence.
- -version_control_type - The version control type used, either GIT or SVN.
- -local_repo_path - The path on the filesystem where the local repository is located. All files on the remote repository are cloned to this path. Example: C:\\MyFiles\\ChangeManagementRepo. NOTE: if using Windows, be sure to include double forward slashes (as seen in the example) for path separation.
- -appian_objects_repo_path - Path to the folder containing the Appian objects in the repository. This path is relative to the path of the local repository. If not specified, the Appian objects are checked out to and committed from the root of the local repository path.
- -repo_url - The URL that defines the remote repository. Example: https://github.com/git-username/project-name.git, svn+ssh://svn.code.sf.net/p/project-name/code
- -package_path - For buildAllApps, buildSingleApp, and buildMultipleApps only. The path on the filesystem where packages are generated. Must include filename of package.
- -branch_name - Branch to check out and use (if not master)

Configuring using the Properties File

In case an option is specified both on the command line and in the properties file, the command line value takes precedence and is used.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Use Cases

#1: New developer joins team (updateLocalRepo)

In this use case, a new developer has joined the team and wants to get a copy of all the work completed so far. The developer:

Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using updateLocalRepo as the action flag. The developer must provide the username and password for authenticating against their version control system (-vc_username, -vc_password).

Example Syntax:

> version-application -action updateLocalRepo -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD>

When the script is executed, the developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).

#2: Developer adds artifacts to the repository (addContents)

In the Appian development environment, create an application (or a patch) that contains the changed objects.
Export those changes and download the application ZIP file.
Run the script, using addContents as the action flag. The developer must provide the path of the ZIP file they exported (-application_path) from Appian in step 2. They must also provide the username and password for authenticating their version control system (-vc_username, -vc_password). NOTE: these are NOT Appian credentials.
1. Optional: if the application specified for -application_path is a patch, update the -uuid option to specify the parent application’s uuid. The script will exit with error if a patch application ZIP is provided but no uuid is passed in.
2. Optional: if DDL scripts have been modified, specify the path(s) and their associated JDBC datasource names. NOTE: The same number of DDL scripts and datasource names must be entered into the script, even if the datasource is the same for all scripts. For example: the developer wishes to add two ddl scripts located at C:\DDLs\script1.sql and C:\DDLs\script2.sql. They do so by setting the -ddl_path option as C:\DDLs\script1.sql,C:\DDLs\script2.sql If both scripts are to be executed on jdbc/AppianDS, they must set the -ddl_ds option as jdbc/AppianDS,jdbc/AppianDS. Note that the datasource name is passed in twice.
Optional: include a custom commit message using the -commit_message option

Example Syntax:

> version-application -action addContents -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -application_path "C:\App.zip" -ddl_ds jdbc/AppianAnywhere -ddl_path “C:\script1.sql” -commit_message “Adding account executive record”

When the script is executed, three things occur:

The developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).
The application ZIP is unzipped and placed into the local repository, and the DDL files are placed into a ddl_files folder within the local repository. If the -uuid option is selected, the appropriate application xml file is updated.
The changes are committed (and pushed, if using Git) to the remote repository.

When the package is imported into Appian, all lines within script1.sql will be executed and contents within the application ZIP are imported.

Using Folder Listener:

Alternatively, instead of running the script, the developer can execute avm-folder-listener-<os> in the folder-listener directory. The following command prompt will appear:

#3: Build master generates new RC deployment package (buildAllApps)

(If not done previously) Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using buildAllApps as the action flag. The build master must provide the username and password for authenticating against their version control system (-vc_username, -vc_password). To get a specific set of changes, input a value for the -start_hash option and the -end_hash option. This will generate the package with all new and changed files between the two hash options.
1. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.

Example Command:

> version-application -action buildAllApps -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -start_hash ac37459 -end_hash 6e83b42

When the script is executed, it generates a package at the location specified by the packagePath field in version-manager.properties.

Finally, the build master will import the RC package into the higher environment using the Automated Import tool as described later in this play.

Using Subversion as Version Control System

To allow the Automated Versioning Manager to perform the checkout and commit operations with Subversion, the tool assumes the common Subversion project structure:

trunk
branches
tags

The location of the repository root must be provided by the property repoURL.

versionControlType=SVN

repoUrl=https://svn.code.sf.net/p/deploymentautomationexample/code

branchName=branches/release1

Using Git as Version Control System

To use Git with the Automated Versioning Manager, properties may be specified on the command line or version-manager.properties should be updated as follows:

versionControlType=GIT

repoUrl=https://github.com/gituser/testgitrepo.git

branchName=newbranch

Note: if you are planning to check out a private repository, use the Git SSH URL rather than the HTTPS URL.

Automated Import Manager

Summary

The Automated Import Manager automates the process of inspecting the application, executing DDL scripts, updating CDTs, republishing the appropriate datastores, and importing the application.

Features

Inspect Application: This tool will automatically mimic the "Inspect" functionality that exists within Appian
Validating Application Content: In addition to inspecting the application, the tool will ensure all CDT dependents are included to avoid objects pointing to older versions.
Execute DDL Scripts: DDL scripts can be uploaded and automatically executed. NOTE: For Microsoft SQL Server, only Transact-SQL statements are valid.
Execute Migrations with Flyway: Flyway is a tool used for managing database migrations. It makes it easier to track SQL script versions and not re-execute SQL scripts that have already been run. If a Flyway directory is provided, the Automated Import Manager will automatically execute migrations against the corresponding datasource. Learn more about Flyway here.
Update CDTs: Users are no longer required to delete CDTs before updating them, this tool will perform this step automatically
Import Application and admin console configuration: Automatically import an application with an optional customization file
Republish Datastores: After application import, datastores will be automatically published or republished
Add Patches: Automatically add patch contents to a specified existing application

Usage

Deploy from the Web Browser UI

The tool collects usage metrics by default. To opt-out of metrics collection, check the below option on the Web Browser UI:

Log into Appian as a system administrator
Navigate to the Deployment Automation UI available at the URL: <appian>/suite/plugins/servlet/deploymentautomation
Upload the patch or application you wish to import.
If this application is a patch, select the parent application to which patch contents should be added.
If the new application requires changes to the database schema (i.e. new or updated CDTs) you must choose one of the following:
1. Upload the corresponding DDL script(s) that accurately reflect these additions and/or updates.
2. Set the datastore to "Automatically update database schema" and set "Allow Database Schema Changes Through Data Stores" in the Deployment section of the Appian Administration Console
Click on the button "Start Deployment".
During the deployment, the screen is automatically refreshed every 5 seconds with the latest status of the deployment.
When the deployment is complete, the browser will update with a status page.

Deploy from the Command Line Script

The command line script - the client - can be downloaded from the Appian AppMarket.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Open a command window in the same folder to which the client script and supporting libraries were unzipped.
Using the help guide pictured above, run the proper command to automatically import the application. Use -h or -help to view this menu at any time.
1. -ac_customization_path: Indicates the path to the customization file to use when deploying the admin console package or the application package.
2. -admin_console_path: Indicates the path to the admin console file to deploy. NOTE: Use quotations around the entry.
3. -application_path: Indicates the path to the application file to deploy. NOTE: Use quotations around the entry.
4. -ddl_ds: Optional, use only if providing DDL scripts. The name of the datasource to use with the corresponding DDL script. Use a comma separator to enter multiple datasources.
5. -ddl_path: Optional, use only if providing DDL scripts. Indicates the path to the DDL scripts to execute. Use a comma separator to enter multiple DDL script paths. NOTE: Use quotations around the entry.
6. -flyway_path: Optional, use only if providing directories to execute DB migrations via Flyway. Use a comma separator to enter multiple directory paths. NOTE: Use quotations around the entry. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions.
7. -force_import: A boolean flag which specifies whether or not the import ignores impact analysis results.If true, the import will occur even if objects with CDT references are missing
8. -import_customization_path: Indicates the path to the import customization file to use
9. -inspect_only: Optional, use to run an inspection of the package. Indicates the package should not be deployed but inspected only.
10. -password: Password of the Appian user account
11. -proxy_port: Optional, port of the proxy server to use to connect to Appian. This parameter is only used if the parameter -proxy_url is defined. The default value is 8080.
12. -proxy_url: Optional, URL of the proxy to use to connect to Appian.
13. -url: URL of the environment, of the format https://example.appian.com/suite.
14. -username: Username of the Appian user account to use for deployment
15. -uuid: UUID of the application to which patch contents will be added
Deploy the application by typing the command deploy-application.bat and including the relevant parameters. Your command will look something like the one pictured below.

deploy-application.bat -application_path "PATH TO APPLICATION ZIP" -username SERVICE_ACCOUNT_USERNAME -password SERVICE_ACCOUNT_PASSWORD -url APPIAN_URL -ddl_path "PATH TO DLL 1, PATH TO DLL 2" -ddl_ds jdbc/Appian1,jdbc/Appian2

Deploy from an External Continuous Integration tool

Additional Requirement:

An existing external Continuous Integration tool (such as Jenkins or Hudson) that is properly configured

The steps below provide the high level steps to deploy an application from Jenkins.

Create a new external job
Configure the job to run the import script using the guidance in Deployment Option #2 listed above
Execute the job

When the deployment is complete, check the status page verify that the import was successful.

Troubleshooting

Deciphering Script Error Messages

Inspect Failure

Package Validation Failure

In case you want to proceed with deploying the application regardless of missing CDT dependencies, use the flag -f.

Import Failure

Invalid Credentials

Please ensure that these credentials are associated with an active Appian system administrator account. Basic user credentials cannot be used.

Connection Refused With Deployment Command Line Script

A "Connection Refused" error could be the result of using the wrong URL when executing the script. The URL provided as a parameter must:

include the suffix "/suite"
Include a port number if not using the port 80 with HTTP or port 443 with HTTPS

Release Notes

September 2021 - Release 2.5.13

Bug Fixes
- Fixed an issue where setting "appianObjectsRepoPath" prevented a package that included a patches.xml file from being processed successfully

March 2021 - Release 2.5.12

Enhancements
- Updated the link to the import log in the ADM servlet after a change was made to the Appian API.
Bug Fixes
- Fixed a bug that was preventing Flyway files from being included in metadata.properties.

September 2020 - Release 2.5.11

Enhancements
- Upgraded Flyway version to 6.5.5 for compatibility with MariaDB.

August 2020 - Release 2.5.10

Enhancements
- Added the ability to dynamically generate the Metadata file for the "buildAllApps" action to reflect only the list of database scripts that are included in the package for a given commit range.
Bug Fixes
- Fixed the interpretation of "appianObjectsRepoPath" on Windows platforms.

December 2019 - Release 2.5.9

Enhancements
- Added DNS proxy support to ADM
- Added DNS proxy support to AIM
- Added DNS proxy support to AVM
- Added support for special characters in passwords in ADM

July 2019 - Release 2.5.8

Bug Fixes
- Fixed the problem with obtaining TransactionManager and creating DataConfiguration against latest the Appian version

April 2019 - Release 2.5.7

Enhancements
- Added commit message prompt to folder listener
Bug Fixes
- Fixed Windows issue with pushing file updates to versioning manager
- Fixed import patch failure not adding newly created objects issue
- Fixed semicolon separator parsing issue

March 2019 - Release 2.5.6

Enhancements
- Added proxy authentication support for import client

February 2019 - Release 2.5.5

Bug Fixes
- Fixed DDL paths bug

January 2019 - Release 2.5.4

Enhancements
- Improved descriptions of errors encountered during deployments
Bug Fixes
- Fixed "Connection Refused" bug when running on a Jenkins server
- Fixed "buildSingleApp" AVM bug when specifying an appianObjectsRepoPath
- Fixed rare "hanging" bug in AIM Client

November 2018 - Release 2.5.3

Enhancements
- Created a reset command for Remote Automated Deployment Manager
Bug Fixes
- Version and Import Metrics Logger Initialized correctly to fix null pointer exception

October 2018 - Release 2.5.2

Enhancements
- Folder listener to auto trigger “Add Contents” action
- Field validation for import and versioning manager properties files
- Usage metrics collection to better understand tool use
- Updated error log messages
Bug Fixes
- ADM UI: Handle apostrophes in app name
- ZIP type validation for Automated Import Manager

September 2018 - Release 2.5.1

Enhancements
- New buildMultipleApps action
- Check version of tools with -v or -version flags
Bug Fixes
- Fixed ADM SQL errors with non-null statements and forward slash as delimiters

August 2018 - Release 2.5.0

Enhancements
- Added Flyway DB version control tool to command line and AIM GUI
- Allow import of DDL scripts or Flyway scripts without an application zip or patch zip
- Added Folder Listener script that will run addContents automatically when a file is dropped into a folder
Bug Fixes
- Added buildAllApps to list of approved actions
- Set inspect_only properly in AIM
- Fixed bug where repo would be cloned into a folder with an incorrect name
- Passed in correct authentication token for buildAllApps and buildSingleApp

August 2018 - Release 2.4.7

Enhancements
- Added "buildSingleApp" action to extract one app from multi app repo
- Renamed "buildPackage" action to "buildAllApps" to better clarify the functionality
Bug Fixes
- Fixed miscellaneous issues with parsing SQL in DDL file
- Mark/reset issue with large customization files

June 2018 - Release 2.4.6

Enhancements
- Added an import-manager.properties file to set default values for importing applications
- Automated versioning manager supports adding a package with multiple patches
Bug Fixes
- Application version UUID is updated when adding patches to a version control
- Import no longer fails when SQL in DDL file contains a ";", "–" or "/**/"

March 2018 - Release 2.4.5

Add support for proxy configuration in the deployment client script with parameters "proxy_port" and "proxy_url"

January 2018 - Release 2.4.4

Bug fixes

January 2018 - Release 2.4.3

Support for Appian 17.4

September 2017 - Release 2.4.2

Support for Appian 17.3
Better handling of end of line characters in the SQL scripts
Support for customization file when deploying an application package

June 2017 - Release 2.4.1

Support for Appian 17.2
Fix defect preventing to execute DB scripts as part of a deployment

January 2017 - Release 2.4.0

Support for Appian 17.1

October 2016 - Release 2.3

Support for Appian 16.3

September 2016 - Release 2.2.9

Automated Import Manager

Successfully deploy application packages containing new Datastore entities and new dependents on these entities.

September 2016 - Release 2.2.8

Automated Versioning Manager

Fixed defect with missing artifacts in package when using START_HASH and END_HASH.

August 2016 - Release 2.2.7

Automated Versioning Manager

Fixed defect with deploying applications and patches containing updated Documents.

August 2016 - Release 2.2.6

Automated Versioning Manager

New parameter no_update to build a package from the local repository without first performing a checkout
New integrity control when checking in applications and patches

August 2016 - Release 2.2.5

Automated Versioning Manager

Fixed defect with deploying applications and patches containing new CDTs and updated CDTs.

June 2016 - Release 2.2.4

Bug fixes.

June 2016 - Release 2.2.3

Include the source code in all modules.

June 2016 - Release 2.2.2

Automated Versioning Manager

Added new parameter appian_objects_repo_path to specify where the Appian artifacts are located in the repository.

May 2016 - Release 2.2.0

Automated Versioning Manager

Added support for admin console packages

Automated Import Manager

Removed update-database-schema to support native product capability of automatic database updates via datastore and administration console.
Updated Web Browser UI style
Removed option for "Automatically update the database schema when publishing the data stores" from the Web Browser UI
Added support for admin console deployments
Added support in command line for inspect_only parameter

March 2016 - Release 2.1.0

Automated Versioning Manager

Added support for input flexibility. Now, the command line for versioning manager supports all possible parameters.
Allowed tags as inputs to start hash and end hash.
Added inputs of the following predefined keywords: FIRST_COMMIT (which maps to first commit ever made) and LAST_COMMIT (the previous commit). NOTE: this is only allowed on the start hash input.

Automated Import Manager

Added support for 16.1.
Added action for "Inspect Only".

Deployment Automation

joel.larin — Thu, 26 Oct 2023 18:16:16 GMT

Revision 5 posted to Guide by joel.larin on 10/26/2023 6:16:16 PM

Appian provides several DevOps tools to automate the deployment of Appian applications such as Compare & Deploy and Deployment APIs.

The tools described in this play offer a few alternatives to Appian base product features:

Tightly integrate with a version control system to store and retrieve package files using the Automated Versioning Manager (AVM)
Programmatically deploy Admin Console settings and applications using the Automated Import Manager (AIM) plug-in and the Automated Import Manager (AIM) client

Table Of Content

Automated Versioning Manager
Automated Import Manager
Troubleshooting
Release Notes

Automated Versioning Manager

Summary

It unzips the application and organizes the artifact XML files in the repository.
It automates the check-in and checkout operations with the version control system.
It generates application packages for import in Appian based on the contents of the repository and a range of changes to include.

The goal of this tool is to facilitate the adoption and usage of a version control system to perform configuration management of the Appian applications and database DDL files.

Features

Version Control integration (Git, SVN)
Supports Appian applications and patches
Generate import package from hash ranges
Folder Listener to add contents to Version Control
Supports GitHub, GitLab, and BitBucket for Version Control

Usage

Script Execution

To run the script, open a command window and navigate to the directory where the automated versioning scripts are located. They are named version-application.bat or version-application.sh.

Use the -h or -help parameters to view the help menu within the script. The parameters are described here:

Required Parameters (required for all four actions: addContents, buildAllApps, buildSingleApp, buildMultipleApps, and updateLocalRepo)
- -action - Selects which action of the script to run. Acceptable values are: addContents, updateLocalRepo, buildAllApps, buildSingleApp, and buildMultipleApps. Each action is detailed in the use cases below.
- -vc_username -The username associated with the version control (Git or SVN) account. NOTE: these are NOT your Appian credentials.
- -vc_password -Please check the Security Settings of the version control account. If you have 2-factor authentication enabled, the password requires the version control account token. If you do NOT have 2-factor authentication enabled, the password is the one associated with the version control account. NOTE: these are NOT your Appian credentials.
Options for addContents action
- -application_path - The path on your filesystem where the application ZIP is located.
- -admin_console_path - The path on your filesystem where the admin console ZIP file is located.
- -ddl_path - List of comma-separated paths for the DDL files to be included in the deployment package.
- -flyway_path - List of comma-separated paths for the directories to execute DB migrations via Flyway. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions. To learn how the Automated Import Manager uses Flyway, refer to AIM Features.
- -ddl_ds - List of comma-separated datasources associated with the provided DDL files. Must provide the same number of entries as number of DDL files specified with the -ddl_path option or number of directories specified with the -flyway_path option. NOTE: the order of the specified datasource names must match the order of the script paths specified.
- -uuid - The UUID of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -application_name - The name of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -commit_message - The message that will be associated with the commit. If not included, a default commit message Committed by @username is provided.
Options for buildAllApps action
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildSingleApp action
- -uuid - The UUID of the application you want to build.
- -application_name - The name of the application you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildMultipleApps action
- -uuid - Comma separated list of UUIDs of the applications you want to build.
- -application_name - Comma separated list of names of the applications that you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for updateLocalRepo action
- There are no additional options (other than required options) for updateLocalRepo.
Additional Parameters - These parameters are REQUIRED, and may be specified here or in the properties file (described in the following section). If they are specified in both locations, the parameters specified in the command line take precedence.
- -version_control_type - The version control type used, either GIT or SVN.
- -local_repo_path - The path on the filesystem where the local repository is located. All files on the remote repository are cloned to this path. Example: C:\\MyFiles\\ChangeManagementRepo. NOTE: if using Windows, be sure to include double forward slashes (as seen in the example) for path separation.
- -appian_objects_repo_path - Path to the folder containing the Appian objects in the repository. This path is relative to the path of the local repository. If not specified, the Appian objects are checked out to and committed from the root of the local repository path.
- -repo_url - The URL that defines the remote repository. Example: https://github.com/git-username/project-name.git, svn+ssh://svn.code.sf.net/p/project-name/code
- -package_path - For buildAllApps, buildSingleApp, and buildMultipleApps only. The path on the filesystem where packages are generated. Must include filename of package.
- -branch_name - Branch to check out and use (if not master)

Configuring using the Properties File

In case an option is specified both on the command line and in the properties file, the command line value takes precedence and is used.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Use Cases

#1: New developer joins team (updateLocalRepo)

In this use case, a new developer has joined the team and wants to get a copy of all the work completed so far. The developer:

Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using updateLocalRepo as the action flag. The developer must provide the username and password for authenticating against their version control system (-vc_username, -vc_password).

Example Syntax:

> version-application -action updateLocalRepo -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD>

When the script is executed, the developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).

#2: Developer adds artifacts to the repository (addContents)

In the Appian development environment, create an application (or a patch) that contains the changed objects.
Export those changes and download the application ZIP file.
Run the script, using addContents as the action flag. The developer must provide the path of the ZIP file they exported (-application_path) from Appian in step 2. They must also provide the username and password for authenticating their version control system (-vc_username, -vc_password). NOTE: these are NOT Appian credentials.
1. Optional: if the application specified for -application_path is a patch, update the -uuid option to specify the parent application’s uuid. The script will exit with error if a patch application ZIP is provided but no uuid is passed in.
2. Optional: if DDL scripts have been modified, specify the path(s) and their associated JDBC datasource names. NOTE: The same number of DDL scripts and datasource names must be entered into the script, even if the datasource is the same for all scripts. For example: the developer wishes to add two ddl scripts located at C:\DDLs\script1.sql and C:\DDLs\script2.sql. They do so by setting the -ddl_path option as C:\DDLs\script1.sql,C:\DDLs\script2.sql If both scripts are to be executed on jdbc/AppianDS, they must set the -ddl_ds option as jdbc/AppianDS,jdbc/AppianDS. Note that the datasource name is passed in twice.
Optional: include a custom commit message using the -commit_message option

Example Syntax:

> version-application -action addContents -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -application_path "C:\App.zip" -ddl_ds jdbc/AppianAnywhere -ddl_path “C:\script1.sql” -commit_message “Adding account executive record”

When the script is executed, three things occur:

The developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).
The application ZIP is unzipped and placed into the local repository, and the DDL files are placed into a ddl_files folder within the local repository. If the -uuid option is selected, the appropriate application xml file is updated.
The changes are committed (and pushed, if using Git) to the remote repository.

When the package is imported into Appian, all lines within script1.sql will be executed and contents within the application ZIP are imported.

Using Folder Listener:

Alternatively, instead of running the script, the developer can execute avm-folder-listener-<os> in the folder-listener directory. The following command prompt will appear:

#3: Build master generates new RC deployment package (buildAllApps)

(If not done previously) Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using buildAllApps as the action flag. The build master must provide the username and password for authenticating against their version control system (-vc_username, -vc_password). To get a specific set of changes, input a value for the -start_hash option and the -end_hash option. This will generate the package with all new and changed files between the two hash options.
1. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.

Example Command:

> version-application -action buildAllApps -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -start_hash ac37459 -end_hash 6e83b42

When the script is executed, it generates a package at the location specified by the packagePath field in version-manager.properties.

Finally, the build master will import the RC package into the higher environment using the Automated Import tool as described later in this play.

Using Subversion as Version Control System

To allow the Automated Versioning Manager to perform the checkout and commit operations with Subversion, the tool assumes the common Subversion project structure:

trunk
branches
tags

The location of the repository root must be provided by the property repoURL.

versionControlType=SVN

repoUrl=https://svn.code.sf.net/p/deploymentautomationexample/code

branchName=branches/release1

Using Git as Version Control System

To use Git with the Automated Versioning Manager, properties may be specified on the command line or version-manager.properties should be updated as follows:

versionControlType=GIT

repoUrl=https://github.com/gituser/testgitrepo.git

branchName=newbranch

Note: if you are planning to check out a private repository, use the Git SSH URL rather than the HTTPS URL.

Automated Import Manager

Summary

The Automated Import Manager automates the process of inspecting the application, executing DDL scripts, updating CDTs, republishing the appropriate datastores, and importing the application.

Features

Inspect Application: This tool will automatically mimic the "Inspect" functionality that exists within Appian
Validating Application Content: In addition to inspecting the application, the tool will ensure all CDT dependents are included to avoid objects pointing to older versions.
Execute DDL Scripts: DDL scripts can be uploaded and automatically executed. NOTE: For Microsoft SQL Server, only Transact-SQL statements are valid.
Execute Migrations with Flyway: Flyway is a tool used for managing database migrations. It makes it easier to track SQL script versions and not re-execute SQL scripts that have already been run. If a Flyway directory is provided, the Automated Import Manager will automatically execute migrations against the corresponding datasource. Learn more about Flyway here.
Update CDTs: Users are no longer required to delete CDTs before updating them, this tool will perform this step automatically
Import Application and admin console configuration: Automatically import an application with an optional customization file
Republish Datastores: After application import, datastores will be automatically published or republished
Add Patches: Automatically add patch contents to a specified existing application

Usage

Deploy from the Web Browser UI

The tool collects usage metrics by default. To opt-out of metrics collection, check the below option on the Web Browser UI:

Log into Appian as a system administrator
Navigate to the Deployment Automation UI available at the URL: <appian>/suite/plugins/servlet/deploymentautomation
Upload the patch or application you wish to import.
If this application is a patch, select the parent application to which patch contents should be added.
If the new application requires changes to the database schema (i.e. new or updated CDTs) you must choose one of the following:
1. Upload the corresponding DDL script(s) that accurately reflect these additions and/or updates.
2. Set the datastore to "Automatically update database schema" and set "Allow Database Schema Changes Through Data Stores" in the Deployment section of the Appian Administration Console
Click on the button "Start Deployment".
During the deployment, the screen is automatically refreshed every 5 seconds with the latest status of the deployment.
When the deployment is complete, the browser will update with a status page.

Deploy from the Command Line Script

The command line script - the client - can be downloaded from the Appian AppMarket.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Open a command window in the same folder to which the client script and supporting libraries were unzipped.
Using the help guide pictured above, run the proper command to automatically import the application. Use -h or -help to view this menu at any time.
1. -ac_customization_path: Indicates the path to the customization file to use when deploying the admin console package or the application package.
2. -admin_console_path: Indicates the path to the admin console file to deploy. NOTE: Use quotations around the entry.
3. -application_path: Indicates the path to the application file to deploy. NOTE: Use quotations around the entry.
4. -ddl_ds: Optional, use only if providing DDL scripts. The name of the datasource to use with the corresponding DDL script. Use a comma separator to enter multiple datasources.
5. -ddl_path: Optional, use only if providing DDL scripts. Indicates the path to the DDL scripts to execute. Use a comma separator to enter multiple DDL script paths. NOTE: Use quotations around the entry.
6. -flyway_path: Optional, use only if providing directories to execute DB migrations via Flyway. Use a comma separator to enter multiple directory paths. NOTE: Use quotations around the entry. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions.
7. -force_import: A boolean flag which specifies whether or not the import ignores impact analysis results.If true, the import will occur even if objects with CDT references are missing
8. -import_customization_path: Indicates the path to the import customization file to use
9. -inspect_only: Optional, use to run an inspection of the package. Indicates the package should not be deployed but inspected only.
10. -password: Password of the Appian user account
11. -proxy_port: Optional, port of the proxy server to use to connect to Appian. This parameter is only used if the parameter -proxy_url is defined. The default value is 8080.
12. -proxy_url: Optional, URL of the proxy to use to connect to Appian.
13. -url: URL of the environment, of the format https://example.appian.com/suite.
14. -username: Username of the Appian user account to use for deployment
15. -uuid: UUID of the application to which patch contents will be added
Deploy the application by typing the command deploy-application.bat and including the relevant parameters. Your command will look something like the one pictured below.

deploy-application.bat -application_path "PATH TO APPLICATION ZIP" -username SERVICE_ACCOUNT_USERNAME -password SERVICE_ACCOUNT_PASSWORD -url APPIAN_URL -ddl_path "PATH TO DLL 1, PATH TO DLL 2" -ddl_ds jdbc/Appian1,jdbc/Appian2

Deploy from an External Continuous Integration tool

Additional Requirement:

An existing external Continuous Integration tool (such as Jenkins or Hudson) that is properly configured

The steps below provide the high level steps to deploy an application from Jenkins.

Create a new external job
Configure the job to run the import script using the guidance in Deployment Option #2 listed above
Execute the job

When the deployment is complete, check the status page verify that the import was successful.

Troubleshooting

Deciphering Script Error Messages

Inspect Failure

Package Validation Failure

In case you want to proceed with deploying the application regardless of missing CDT dependencies, use the flag -f.

Import Failure

Invalid Credentials

Please ensure that these credentials are associated with an active Appian system administrator account. Basic user credentials cannot be used.

Connection Refused With Deployment Command Line Script

A "Connection Refused" error could be the result of using the wrong URL when executing the script. The URL provided as a parameter must:

include the suffix "/suite"
Include a port number if not using the port 80 with HTTP or port 443 with HTTPS

Release Notes

September 2021 - Release 2.5.13

Bug Fixes
- Fixed an issue where setting "appianObjectsRepoPath" prevented a package that included a patches.xml file from being processed successfully

March 2021 - Release 2.5.12

Enhancements
- Updated the link to the import log in the ADM servlet after a change was made to the Appian API.
Bug Fixes
- Fixed a bug that was preventing Flyway files from being included in metadata.properties.

September 2020 - Release 2.5.11

Enhancements
- Upgraded Flyway version to 6.5.5 for compatibility with MariaDB.

August 2020 - Release 2.5.10

Enhancements
- Added the ability to dynamically generate the Metadata file for the "buildAllApps" action to reflect only the list of database scripts that are included in the package for a given commit range.
Bug Fixes
- Fixed the interpretation of "appianObjectsRepoPath" on Windows platforms.

December 2019 - Release 2.5.9

Enhancements
- Added DNS proxy support to ADM
- Added DNS proxy support to AIM
- Added DNS proxy support to AVM
- Added support for special characters in passwords in ADM

July 2019 - Release 2.5.8

Bug Fixes
- Fixed the problem with obtaining TransactionManager and creating DataConfiguration against latest the Appian version

April 2019 - Release 2.5.7

Enhancements
- Added commit message prompt to folder listener
Bug Fixes
- Fixed Windows issue with pushing file updates to versioning manager
- Fixed import patch failure not adding newly created objects issue
- Fixed semicolon separator parsing issue

March 2019 - Release 2.5.6

Enhancements
- Added proxy authentication support for import client

February 2019 - Release 2.5.5

Bug Fixes
- Fixed DDL paths bug

January 2019 - Release 2.5.4

Enhancements
- Improved descriptions of errors encountered during deployments
Bug Fixes
- Fixed "Connection Refused" bug when running on a Jenkins server
- Fixed "buildSingleApp" AVM bug when specifying an appianObjectsRepoPath
- Fixed rare "hanging" bug in AIM Client

November 2018 - Release 2.5.3

Enhancements
- Created a reset command for Remote Automated Deployment Manager
Bug Fixes
- Version and Import Metrics Logger Initialized correctly to fix null pointer exception

October 2018 - Release 2.5.2

Enhancements
- Folder listener to auto trigger “Add Contents” action
- Field validation for import and versioning manager properties files
- Usage metrics collection to better understand tool use
- Updated error log messages
Bug Fixes
- ADM UI: Handle apostrophes in app name
- ZIP type validation for Automated Import Manager

September 2018 - Release 2.5.1

Enhancements
- New buildMultipleApps action
- Check version of tools with -v or -version flags
Bug Fixes
- Fixed ADM SQL errors with non-null statements and forward slash as delimiters

August 2018 - Release 2.5.0

Enhancements
- Added Flyway DB version control tool to command line and AIM GUI
- Allow import of DDL scripts or Flyway scripts without an application zip or patch zip
- Added Folder Listener script that will run addContents automatically when a file is dropped into a folder
Bug Fixes
- Added buildAllApps to list of approved actions
- Set inspect_only properly in AIM
- Fixed bug where repo would be cloned into a folder with an incorrect name
- Passed in correct authentication token for buildAllApps and buildSingleApp

August 2018 - Release 2.4.7

Enhancements
- Added "buildSingleApp" action to extract one app from multi app repo
- Renamed "buildPackage" action to "buildAllApps" to better clarify the functionality
Bug Fixes
- Fixed miscellaneous issues with parsing SQL in DDL file
- Mark/reset issue with large customization files

June 2018 - Release 2.4.6

Enhancements
- Added an import-manager.properties file to set default values for importing applications
- Automated versioning manager supports adding a package with multiple patches
Bug Fixes
- Application version UUID is updated when adding patches to a version control
- Import no longer fails when SQL in DDL file contains a ";", "–" or "/**/"

March 2018 - Release 2.4.5

Add support for proxy configuration in the deployment client script with parameters "proxy_port" and "proxy_url"

January 2018 - Release 2.4.4

Bug fixes

January 2018 - Release 2.4.3

Support for Appian 17.4

September 2017 - Release 2.4.2

Support for Appian 17.3
Better handling of end of line characters in the SQL scripts
Support for customization file when deploying an application package

June 2017 - Release 2.4.1

Support for Appian 17.2
Fix defect preventing to execute DB scripts as part of a deployment

January 2017 - Release 2.4.0

Support for Appian 17.1

October 2016 - Release 2.3

Support for Appian 16.3

September 2016 - Release 2.2.9

Automated Import Manager

Successfully deploy application packages containing new Datastore entities and new dependents on these entities.

September 2016 - Release 2.2.8

Automated Versioning Manager

Fixed defect with missing artifacts in package when using START_HASH and END_HASH.

August 2016 - Release 2.2.7

Automated Versioning Manager

Fixed defect with deploying applications and patches containing updated Documents.

August 2016 - Release 2.2.6

Automated Versioning Manager

New parameter no_update to build a package from the local repository without first performing a checkout
New integrity control when checking in applications and patches

August 2016 - Release 2.2.5

Automated Versioning Manager

Fixed defect with deploying applications and patches containing new CDTs and updated CDTs.

June 2016 - Release 2.2.4

Bug fixes.

June 2016 - Release 2.2.3

Include the source code in all modules.

June 2016 - Release 2.2.2

Automated Versioning Manager

Added new parameter appian_objects_repo_path to specify where the Appian artifacts are located in the repository.

May 2016 - Release 2.2.0

Automated Versioning Manager

Added support for admin console packages

Automated Import Manager

Removed update-database-schema to support native product capability of automatic database updates via datastore and administration console.
Updated Web Browser UI style
Removed option for "Automatically update the database schema when publishing the data stores" from the Web Browser UI
Added support for admin console deployments
Added support in command line for inspect_only parameter

March 2016 - Release 2.1.0

Automated Versioning Manager

Added support for input flexibility. Now, the command line for versioning manager supports all possible parameters.
Allowed tags as inputs to start hash and end hash.
Added inputs of the following predefined keywords: FIRST_COMMIT (which maps to first commit ever made) and LAST_COMMIT (the previous commit). NOTE: this is only allowed on the start hash input.

Automated Import Manager

Added support for 16.1.
Added action for "Inspect Only".

Deployment Automation

joel.larin — Thu, 26 Oct 2023 18:14:23 GMT

Revision 4 posted to Guide by joel.larin on 10/26/2023 6:14:23 PM

Appian provides several DevOps tools to automate the deployment of Appian applications such as Compare & Deploy and Deployment APIs.

The tools described in this play offer a few alternatives to Appian base product features:

Tightly integrate with a version control system to store and retrieve package files using the Automated Versioning Manager (AVM)
Programmatically deploy Admin Console settings and applications using the Automated Import Manager (AIM) plug-in and the Automated Import Manager (AIM) client

Table Of Content

Automated Versioning Manager
Automated Import Manager
Troubleshooting
Release Notes

Automated Versioning Manager

Summary

It unzips the application and organizes the artifact XML files in the repository.
It automates the check-in and checkout operations with the version control system.
It generates application packages for import in Appian based on the contents of the repository and a range of changes to include.

The goal of this tool is to facilitate the adoption and usage of a version control system to perform configuration management of the Appian applications and database DDL files.

Features

Version Control integration (Git, SVN)
Supports Appian applications and patches
Generate import package from hash ranges
Folder Listener to add contents to Version Control
Supports GitHub, GitLab, and BitBucket for Version Control

Usage

Script Execution

To run the script, open a command window and navigate to the directory where the automated versioning scripts are located. They are named version-application.bat or version-application.sh.

Use the -h or -help parameters to view the help menu within the script. The parameters are described here:

Required Parameters (required for all four actions: addContents, buildAllApps, buildSingleApp, buildMultipleApps, and updateLocalRepo)
- -action - Selects which action of the script to run. Acceptable values are: addContents, updateLocalRepo, buildAllApps, buildSingleApp, and buildMultipleApps. Each action is detailed in the use cases below.
- -vc_username -The username associated with the version control (Git or SVN) account. NOTE: these are NOT your Appian credentials.
- -vc_password -Please check the Security Settings of the version control account. If you have 2-factor authentication enabled, the password requires the version control account token. If you do NOT have 2-factor authentication enabled, the password is the one associated with the version control account. NOTE: these are NOT your Appian credentials.
Options for addContents action
- -application_path - The path on your filesystem where the application ZIP is located.
- -admin_console_path - The path on your filesystem where the admin console ZIP file is located.
- -ddl_path - List of comma-separated paths for the DDL files to be included in the deployment package.
- -flyway_path - List of comma-separated paths for the directories to execute DB migrations via Flyway. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions. To learn how the Automated Import Manager uses Flyway, refer to AIM Features.
- -ddl_ds - List of comma-separated datasources associated with the provided DDL files. Must provide the same number of entries as number of DDL files specified with the -ddl_path option or number of directories specified with the -flyway_path option. NOTE: the order of the specified datasource names must match the order of the script paths specified.
- -uuid - The UUID of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -application_name - The name of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -commit_message - The message that will be associated with the commit. If not included, a default commit message Committed by @username is provided.
Options for buildAllApps action
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildSingleApp action
- -uuid - The UUID of the application you want to build.
- -application_name - The name of the application you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildMultipleApps action
- -uuid - Comma separated list of UUIDs of the applications you want to build.
- -application_name - Comma separated list of names of the applications that you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for updateLocalRepo action
- There are no additional options (other than required options) for updateLocalRepo.
Additional Parameters - These parameters are REQUIRED, and may be specified here or in the properties file (described in the following section). If they are specified in both locations, the parameters specified in the command line take precedence.
- -version_control_type - The version control type used, either GIT or SVN.
- -local_repo_path - The path on the filesystem where the local repository is located. All files on the remote repository are cloned to this path. Example: C:\\MyFiles\\ChangeManagementRepo. NOTE: if using Windows, be sure to include double forward slashes (as seen in the example) for path separation.
- -appian_objects_repo_path - Path to the folder containing the Appian objects in the repository. This path is relative to the path of the local repository. If not specified, the Appian objects are checked out to and committed from the root of the local repository path.
- -repo_url - The URL that defines the remote repository. Example: https://github.com/git-username/project-name.git, svn+ssh://svn.code.sf.net/p/project-name/code
- -package_path - For buildAllApps, buildSingleApp, and buildMultipleApps only. The path on the filesystem where packages are generated. Must include filename of package.
- -branch_name - Branch to check out and use (if not master)

Configuring using the Properties File

In case an option is specified both on the command line and in the properties file, the command line value takes precedence and is used.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Use Cases

#1: New developer joins team (updateLocalRepo)

In this use case, a new developer has joined the team and wants to get a copy of all the work completed so far. The developer:

Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using updateLocalRepo as the action flag. The developer must provide the username and password for authenticating against their version control system (-vc_username, -vc_password).

Example Syntax:

> version-application -action updateLocalRepo -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD>

When the script is executed, the developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).

#2: Developer adds artifacts to the repository (addContents)

In the Appian development environment, create an application (or a patch) that contains the changed objects.
Export those changes and download the application ZIP file.
Run the script, using addContents as the action flag. The developer must provide the path of the ZIP file they exported (-application_path) from Appian in step 2. They must also provide the username and password for authenticating their version control system (-vc_username, -vc_password). NOTE: these are NOT Appian credentials.
1. Optional: if the application specified for -application_path is a patch, update the -uuid option to specify the parent application’s uuid. The script will exit with error if a patch application ZIP is provided but no uuid is passed in.
2. Optional: if DDL scripts have been modified, specify the path(s) and their associated JDBC datasource names. NOTE: The same number of DDL scripts and datasource names must be entered into the script, even if the datasource is the same for all scripts. For example: the developer wishes to add two ddl scripts located at C:\DDLs\script1.sql and C:\DDLs\script2.sql. They do so by setting the -ddl_path option as C:\DDLs\script1.sql,C:\DDLs\script2.sql If both scripts are to be executed on jdbc/AppianDS, they must set the -ddl_ds option as jdbc/AppianDS,jdbc/AppianDS. Note that the datasource name is passed in twice.
Optional: include a custom commit message using the -commit_message option

Example Syntax:

> version-application -action addContents -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -application_path "C:\App.zip" -ddl_ds jdbc/AppianAnywhere -ddl_path “C:\script1.sql” -commit_message “Adding account executive record”

When the script is executed, three things occur:

The developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).
The application ZIP is unzipped and placed into the local repository, and the DDL files are placed into a ddl_files folder within the local repository. If the -uuid option is selected, the appropriate application xml file is updated.
The changes are committed (and pushed, if using Git) to the remote repository.

When the package is imported into Appian, all lines within script1.sql will be executed and contents within the application ZIP are imported.

Using Folder Listener:

Alternatively, instead of running the script, the developer can execute avm-folder-listener-<os> in the folder-listener directory. The following command prompt will appear:

#3: Build master generates new RC deployment package (buildAllApps)

(If not done previously) Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using buildAllApps as the action flag. The build master must provide the username and password for authenticating against their version control system (-vc_username, -vc_password). To get a specific set of changes, input a value for the -start_hash option and the -end_hash option. This will generate the package with all new and changed files between the two hash options.
1. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.

Example Command:

> version-application -action buildAllApps -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -start_hash ac37459 -end_hash 6e83b42

When the script is executed, it generates a package at the location specified by the packagePath field in version-manager.properties.

Finally, the build master will import the RC package into the higher environment using the Automated Import tool as described later in this play.

Using Subversion as Version Control System

To allow the Automated Versioning Manager to perform the checkout and commit operations with Subversion, the tool assumes the common Subversion project structure:

trunk
branches
tags

The location of the repository root must be provided by the property repoURL.

versionControlType=SVN

repoUrl=https://svn.code.sf.net/p/deploymentautomationexample/code

branchName=branches/release1

Using Git as Version Control System

To use Git with the Automated Versioning Manager, properties may be specified on the command line or version-manager.properties should be updated as follows:

versionControlType=GIT

repoUrl=https://github.com/gituser/testgitrepo.git

branchName=newbranch

Note: if you are planning to check out a private repository, use the Git SSH URL rather than the HTTPS URL.

Automated Import Manager

Summary

The Automated Import Manager automates the process of inspecting the application, executing DDL scripts, updating CDTs, republishing the appropriate datastores, and importing the application.

Features

Inspect Application: This tool will automatically mimic the "Inspect" functionality that exists within Appian
Validating Application Content: In addition to inspecting the application, the tool will ensure all CDT dependents are included to avoid objects pointing to older versions.
Execute DDL Scripts: DDL scripts can be uploaded and automatically executed. NOTE: For Microsoft SQL Server, only Transact-SQL statements are valid.
Execute Migrations with Flyway: Flyway is a tool used for managing database migrations. It makes it easier to track SQL script versions and not re-execute SQL scripts that have already been run. If a Flyway directory is provided, the Automated Import Manager will automatically execute migrations against the corresponding datasource. Learn more about Flyway here.
Update CDTs: Users are no longer required to delete CDTs before updating them, this tool will perform this step automatically
Import Application and admin console configuration: Automatically import an application with an optional customization file
Republish Datastores: After application import, datastores will be automatically published or republished
Add Patches: Automatically add patch contents to a specified existing application

Usage

Deploy from the Web Browser UI

The tool collects usage metrics by default. To opt-out of metrics collection, check the below option on the Web Browser UI:

Log into Appian as a system administrator
Navigate to the Deployment Automation UI available at the URL: <appian>/suite/plugins/servlet/deploymentautomation
Upload the patch or application you wish to import.
If this application is a patch, select the parent application to which patch contents should be added.
If the new application requires changes to the database schema (i.e. new or updated CDTs) you must choose one of the following:
1. Upload the corresponding DDL script(s) that accurately reflect these additions and/or updates.
2. Set the datastore to "Automatically update database schema" and set "Allow Database Schema Changes Through Data Stores" in the Deployment section of the Appian Administration Console
Click on the button "Start Deployment".
During the deployment, the screen is automatically refreshed every 5 seconds with the latest status of the deployment.
When the deployment is complete, the browser will update with a status page.

Deploy from the Command Line Script

The command line script - the client - can be downloaded from the Appian AppMarket.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Open a command window in the same folder to which the client script and supporting libraries were unzipped.
Using the help guide pictured above, run the proper command to automatically import the application. Use -h or -help to view this menu at any time.
1. -ac_customization_path: Indicates the path to the customization file to use when deploying the admin console package or the application package.
2. -admin_console_path: Indicates the path to the admin console file to deploy. NOTE: Use quotations around the entry.
3. -application_path: Indicates the path to the application file to deploy. NOTE: Use quotations around the entry.
4. -ddl_ds: Optional, use only if providing DDL scripts. The name of the datasource to use with the corresponding DDL script. Use a comma separator to enter multiple datasources.
5. -ddl_path: Optional, use only if providing DDL scripts. Indicates the path to the DDL scripts to execute. Use a comma separator to enter multiple DDL script paths. NOTE: Use quotations around the entry.
6. -flyway_path: Optional, use only if providing directories to execute DB migrations via Flyway. Use a comma separator to enter multiple directory paths. NOTE: Use quotations around the entry. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions.
7. -force_import: A boolean flag which specifies whether or not the import ignores impact analysis results.If true, the import will occur even if objects with CDT references are missing
8. -import_customization_path: Indicates the path to the import customization file to use
9. -inspect_only: Optional, use to run an inspection of the package. Indicates the package should not be deployed but inspected only.
10. -password: Password of the Appian user account
11. -proxy_port: Optional, port of the proxy server to use to connect to Appian. This parameter is only used if the parameter -proxy_url is defined. The default value is 8080.
12. -proxy_url: Optional, URL of the proxy to use to connect to Appian.
13. -url: URL of the environment, of the format https://example.appian.com/suite.
14. -username: Username of the Appian user account to use for deployment
15. -uuid: UUID of the application to which patch contents will be added
Deploy the application by typing the command deploy-application.bat and including the relevant parameters. Your command will look something like the one pictured below.

deploy-application.bat -application_path "PATH TO APPLICATION ZIP" -username SERVICE_ACCOUNT_USERNAME -password SERVICE_ACCOUNT_PASSWORD -url APPIAN_URL -ddl_path "PATH TO DLL 1, PATH TO DLL 2" -ddl_ds jdbc/Appian1,jdbc/Appian2

Deploy from an External Continuous Integration tool

Additional Requirement:

An existing external Continuous Integration tool (such as Jenkins or Hudson) that is properly configured

The steps below provide the high level steps to deploy an application from Jenkins.

Create a new external job
Configure the job to run the import script using the guidance in Deployment Option #2 listed above
Execute the job

When the deployment is complete, check the status page verify that the import was successful.

Troubleshooting

Deciphering Script Error Messages

Inspect Failure

Package Validation Failure

In case you want to proceed with deploying the application regardless of missing CDT dependencies, use the flag -f.

Import Failure

Invalid Credentials

Please ensure that these credentials are associated with an active Appian system administrator account. Basic user credentials cannot be used.

Connection Refused With Deployment Command Line Script

A "Connection Refused" error could be the result of using the wrong URL when executing the script. The URL provided as a parameter must:

include the suffix "/suite"
Include a port number if not using the port 80 with HTTP or port 443 with HTTPS

Release Notes

September 2021 - Release 2.5.13

Bug Fixes
- Fixed an issue where setting "appianObjectsRepoPath" prevented a package that included a patches.xml file from being processed successfully

March 2021 - Release 2.5.12

Enhancements
- Updated the link to the import log in the ADM servlet after a change was made to the Appian API.
Bug Fixes
- Fixed a bug that was preventing Flyway files from being included in metadata.properties.

September 2020 - Release 2.5.11

Enhancements
- Upgraded Flyway version to 6.5.5 for compatibility with MariaDB.

August 2020 - Release 2.5.10

Enhancements
- Added the ability to dynamically generate the Metadata file for the "buildAllApps" action to reflect only the list of database scripts that are included in the package for a given commit range.
Bug Fixes
- Fixed the interpretation of "appianObjectsRepoPath" on Windows platforms.

December 2019 - Release 2.5.9

Enhancements
- Added DNS proxy support to ADM
- Added DNS proxy support to AIM
- Added DNS proxy support to AVM
- Added support for special characters in passwords in ADM

July 2019 - Release 2.5.8

Bug Fixes
- Fixed the problem with obtaining TransactionManager and creating DataConfiguration against latest the Appian version

April 2019 - Release 2.5.7

Enhancements
- Added commit message prompt to folder listener
Bug Fixes
- Fixed Windows issue with pushing file updates to versioning manager
- Fixed import patch failure not adding newly created objects issue
- Fixed semicolon separator parsing issue

March 2019 - Release 2.5.6

Enhancements
- Added proxy authentication support for import client

February 2019 - Release 2.5.5

Bug Fixes
- Fixed DDL paths bug

January 2019 - Release 2.5.4

Enhancements
- Improved descriptions of errors encountered during deployments
Bug Fixes
- Fixed "Connection Refused" bug when running on a Jenkins server
- Fixed "buildSingleApp" AVM bug when specifying an appianObjectsRepoPath
- Fixed rare "hanging" bug in AIM Client

November 2018 - Release 2.5.3

Enhancements
- Created a reset command for Remote Automated Deployment Manager
Bug Fixes
- Version and Import Metrics Logger Initialized correctly to fix null pointer exception

October 2018 - Release 2.5.2

Enhancements
- Folder listener to auto trigger “Add Contents” action
- Field validation for import and versioning manager properties files
- Usage metrics collection to better understand tool use
- Updated error log messages
Bug Fixes
- ADM UI: Handle apostrophes in app name
- ZIP type validation for Automated Import Manager

September 2018 - Release 2.5.1

Enhancements
- New buildMultipleApps action
- Check version of tools with -v or -version flags
Bug Fixes
- Fixed ADM SQL errors with non-null statements and forward slash as delimiters

August 2018 - Release 2.5.0

Enhancements
- Added Flyway DB version control tool to command line and AIM GUI
- Allow import of DDL scripts or Flyway scripts without an application zip or patch zip
- Added Folder Listener script that will run addContents automatically when a file is dropped into a folder
Bug Fixes
- Added buildAllApps to list of approved actions
- Set inspect_only properly in AIM
- Fixed bug where repo would be cloned into a folder with an incorrect name
- Passed in correct authentication token for buildAllApps and buildSingleApp

August 2018 - Release 2.4.7

Enhancements
- Added "buildSingleApp" action to extract one app from multi app repo
- Renamed "buildPackage" action to "buildAllApps" to better clarify the functionality
Bug Fixes
- Fixed miscellaneous issues with parsing SQL in DDL file
- Mark/reset issue with large customization files

June 2018 - Release 2.4.6

Enhancements
- Added an import-manager.properties file to set default values for importing applications
- Automated versioning manager supports adding a package with multiple patches
Bug Fixes
- Application version UUID is updated when adding patches to a version control
- Import no longer fails when SQL in DDL file contains a ";", "–" or "/**/"

March 2018 - Release 2.4.5

Add support for proxy configuration in the deployment client script with parameters "proxy_port" and "proxy_url"

January 2018 - Release 2.4.4

Bug fixes

January 2018 - Release 2.4.3

Support for Appian 17.4

September 2017 - Release 2.4.2

Support for Appian 17.3
Better handling of end of line characters in the SQL scripts
Support for customization file when deploying an application package

June 2017 - Release 2.4.1

Support for Appian 17.2
Fix defect preventing to execute DB scripts as part of a deployment

January 2017 - Release 2.4.0

Support for Appian 17.1

October 2016 - Release 2.3

Support for Appian 16.3

September 2016 - Release 2.2.9

Automated Import Manager

Successfully deploy application packages containing new Datastore entities and new dependents on these entities.

September 2016 - Release 2.2.8

Automated Versioning Manager

Fixed defect with missing artifacts in package when using START_HASH and END_HASH.

August 2016 - Release 2.2.7

Automated Versioning Manager

Fixed defect with deploying applications and patches containing updated Documents.

August 2016 - Release 2.2.6

Automated Versioning Manager

New parameter no_update to build a package from the local repository without first performing a checkout
New integrity control when checking in applications and patches

August 2016 - Release 2.2.5

Automated Versioning Manager

Fixed defect with deploying applications and patches containing new CDTs and updated CDTs.

June 2016 - Release 2.2.4

Bug fixes.

June 2016 - Release 2.2.3

Include the source code in all modules.

June 2016 - Release 2.2.2

Automated Versioning Manager

Added new parameter appian_objects_repo_path to specify where the Appian artifacts are located in the repository.

May 2016 - Release 2.2.0

Automated Versioning Manager

Added support for admin console packages

Automated Import Manager

Removed update-database-schema to support native product capability of automatic database updates via datastore and administration console.
Updated Web Browser UI style
Removed option for "Automatically update the database schema when publishing the data stores" from the Web Browser UI
Added support for admin console deployments
Added support in command line for inspect_only parameter

March 2016 - Release 2.1.0

Automated Versioning Manager

Added support for input flexibility. Now, the command line for versioning manager supports all possible parameters.
Allowed tags as inputs to start hash and end hash.
Added inputs of the following predefined keywords: FIRST_COMMIT (which maps to first commit ever made) and LAST_COMMIT (the previous commit). NOTE: this is only allowed on the start hash input.

Automated Import Manager

Added support for 16.1.
Added action for "Inspect Only".

Deployment Automation

joel.larin — Thu, 26 Oct 2023 18:13:22 GMT

Revision 3 posted to Guide by joel.larin on 10/26/2023 6:13:22 PM

Appian provides several DevOps tools to automate the deployment of Appian applications such as Compare & Deploy and Deployment APIs.

The tools described in this play offer a few alternatives to Appian base product features:

Tightly integrate with a version control system to store and retrieve package files using the Automated Versioning Manager (AVM)
Programmatically deploy Admin Console settings and applications using the Automated Import Manager (AIM) plug-in and the Automated Import Manager (AIM) client

Table Of Content

Automated Versioning Manager
Automated Import Manager
Troubleshooting
Release Notes

Automated Versioning Manager

Summary

It unzips the application and organizes the artifact XML files in the repository.
It automates the check-in and checkout operations with the version control system.
It generates application packages for import in Appian based on the contents of the repository and a range of changes to include.

The goal of this tool is to facilitate the adoption and usage of a version control system to perform configuration management of the Appian applications and database DDL files.

Features

Version Control integration (Git, SVN)
Supports Appian applications and patches
Generate import package from hash ranges
Folder Listener to add contents to Version Control
Supports GitHub, GitLab, and BitBucket for Version Control

Usage

Script Execution

To run the script, open a command window and navigate to the directory where the automated versioning scripts are located. They are named version-application.bat or version-application.sh.

Use the -h or -help parameters to view the help menu within the script. The parameters are described here:

Required Parameters (required for all four actions: addContents, buildAllApps, buildSingleApp, buildMultipleApps, and updateLocalRepo)
- -action - Selects which action of the script to run. Acceptable values are: addContents, updateLocalRepo, buildAllApps, buildSingleApp, and buildMultipleApps. Each action is detailed in the use cases below.
- -vc_username -The username associated with the version control (Git or SVN) account. NOTE: these are NOT your Appian credentials.
- -vc_password -Please check the Security Settings of the version control account. If you have 2-factor authentication enabled, the password requires the version control account token. If you do NOT have 2-factor authentication enabled, the password is the one associated with the version control account. NOTE: these are NOT your Appian credentials.
Options for addContents action
- -application_path - The path on your filesystem where the application ZIP is located.
- -admin_console_path - The path on your filesystem where the admin console ZIP file is located.
- -ddl_path - List of comma-separated paths for the DDL files to be included in the deployment package.
- -flyway_path - List of comma-separated paths for the directories to execute DB migrations via Flyway. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions. To learn how the Automated Import Manager uses Flyway, refer to AIM Features.
- -ddl_ds - List of comma-separated datasources associated with the provided DDL files. Must provide the same number of entries as number of DDL files specified with the -ddl_path option or number of directories specified with the -flyway_path option. NOTE: the order of the specified datasource names must match the order of the script paths specified.
- -uuid - The UUID of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -application_name - The name of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -commit_message - The message that will be associated with the commit. If not included, a default commit message Committed by @username is provided.
Options for buildAllApps action
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildSingleApp action
- -uuid - The UUID of the application you want to build.
- -application_name - The name of the application you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildMultipleApps action
- -uuid - Comma separated list of UUIDs of the applications you want to build.
- -application_name - Comma separated list of names of the applications that you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for updateLocalRepo action
- There are no additional options (other than required options) for updateLocalRepo.
Additional Parameters - These parameters are REQUIRED, and may be specified here or in the properties file (described in the following section). If they are specified in both locations, the parameters specified in the command line take precedence.
- -version_control_type - The version control type used, either GIT or SVN.
- -local_repo_path - The path on the filesystem where the local repository is located. All files on the remote repository are cloned to this path. Example: C:\\MyFiles\\ChangeManagementRepo. NOTE: if using Windows, be sure to include double forward slashes (as seen in the example) for path separation.
- -appian_objects_repo_path - Path to the folder containing the Appian objects in the repository. This path is relative to the path of the local repository. If not specified, the Appian objects are checked out to and committed from the root of the local repository path.
- -repo_url - The URL that defines the remote repository. Example: https://github.com/git-username/project-name.git, svn+ssh://svn.code.sf.net/p/project-name/code
- -package_path - For buildAllApps, buildSingleApp, and buildMultipleApps only. The path on the filesystem where packages are generated. Must include filename of package.
- -branch_name - Branch to check out and use (if not master)

Configuring using the Properties File

In case an option is specified both on the command line and in the properties file, the command line value takes precedence and is used.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Use Cases

#1: New developer joins team (updateLocalRepo)

In this use case, a new developer has joined the team and wants to get a copy of all the work completed so far. The developer:

Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using updateLocalRepo as the action flag. The developer must provide the username and password for authenticating against their version control system (-vc_username, -vc_password).

Example Syntax:

> version-application -action updateLocalRepo -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD>

When the script is executed, the developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).

#2: Developer adds artifacts to the repository (addContents)

In the Appian development environment, create an application (or a patch) that contains the changed objects.
Export those changes and download the application ZIP file.
Run the script, using addContents as the action flag. The developer must provide the path of the ZIP file they exported (-application_path) from Appian in step 2. They must also provide the username and password for authenticating their version control system (-vc_username, -vc_password). NOTE: these are NOT Appian credentials.
1. Optional: if the application specified for -application_path is a patch, update the -uuid option to specify the parent application’s uuid. The script will exit with error if a patch application ZIP is provided but no uuid is passed in.
2. Optional: if DDL scripts have been modified, specify the path(s) and their associated JDBC datasource names. NOTE: The same number of DDL scripts and datasource names must be entered into the script, even if the datasource is the same for all scripts. For example: the developer wishes to add two ddl scripts located at C:\DDLs\script1.sql and C:\DDLs\script2.sql. They do so by setting the -ddl_path option as C:\DDLs\script1.sql,C:\DDLs\script2.sql If both scripts are to be executed on jdbc/AppianDS, they must set the -ddl_ds option as jdbc/AppianDS,jdbc/AppianDS. Note that the datasource name is passed in twice.
Optional: include a custom commit message using the -commit_message option

Example Syntax:

> version-application -action addContents -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -application_path "C:\App.zip" -ddl_ds jdbc/AppianAnywhere -ddl_path “C:\script1.sql” -commit_message “Adding account executive record”

When the script is executed, three things occur:

The developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).
The application ZIP is unzipped and placed into the local repository, and the DDL files are placed into a ddl_files folder within the local repository. If the -uuid option is selected, the appropriate application xml file is updated.
The changes are committed (and pushed, if using Git) to the remote repository.

When the package is imported into Appian, all lines within script1.sql will be executed and contents within the application ZIP are imported.

Using Folder Listener:

Alternatively, instead of running the script, the developer can execute avm-folder-listener-<os> in the folder-listener directory. The following command prompt will appear:

#3: Build master generates new RC deployment package (buildAllApps)

(If not done previously) Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using buildAllApps as the action flag. The build master must provide the username and password for authenticating against their version control system (-vc_username, -vc_password). To get a specific set of changes, input a value for the -start_hash option and the -end_hash option. This will generate the package with all new and changed files between the two hash options.
1. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.

Example Command:

> version-application -action buildAllApps -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -start_hash ac37459 -end_hash 6e83b42

When the script is executed, it generates a package at the location specified by the packagePath field in version-manager.properties.

Finally, the build master will import the RC package into the higher environment using the Automated Import tool as described later in this play.

Using Subversion as Version Control System

To allow the Automated Versioning Manager to perform the checkout and commit operations with Subversion, the tool assumes the common Subversion project structure:

trunk
branches
tags

The location of the repository root must be provided by the property repoURL.

versionControlType=SVN

repoUrl=https://svn.code.sf.net/p/deploymentautomationexample/code

branchName=branches/release1

Using Git as Version Control System

To use Git with the Automated Versioning Manager, properties may be specified on the command line or version-manager.properties should be updated as follows:

versionControlType=GIT

repoUrl=https://github.com/gituser/testgitrepo.git

branchName=newbranch

Note: if you are planning to check out a private repository, use the Git SSH URL rather than the HTTPS URL.

Automated Import Manager

Summary

The Automated Import Manager automates the process of inspecting the application, executing DDL scripts, updating CDTs, republishing the appropriate datastores, and importing the application.

Features

Inspect Application: This tool will automatically mimic the "Inspect" functionality that exists within Appian
Validating Application Content: In addition to inspecting the application, the tool will ensure all CDT dependents are included to avoid objects pointing to older versions.
Execute DDL Scripts: DDL scripts can be uploaded and automatically executed. NOTE: For Microsoft SQL Server, only Transact-SQL statements are valid.
Execute Migrations with Flyway: Flyway is a tool used for managing database migrations. It makes it easier to track SQL script versions and not re-execute SQL scripts that have already been run. If a Flyway directory is provided, the Automated Import Manager will automatically execute migrations against the corresponding datasource. Learn more about Flyway here.
Update CDTs: Users are no longer required to delete CDTs before updating them, this tool will perform this step automatically
Import Application and admin console configuration: Automatically import an application with an optional customization file
Republish Datastores: After application import, datastores will be automatically published or republished
Add Patches: Automatically add patch contents to a specified existing application

Usage

Deploy from the Web Browser UI

The tool collects usage metrics by default. To opt-out of metrics collection, check the below option on the Web Browser UI:

Log into Appian as a system administrator
Navigate to the Deployment Automation UI available at the URL: <appian>/suite/plugins/servlet/deploymentautomation
Upload the patch or application you wish to import.
If this application is a patch, select the parent application to which patch contents should be added.
If the new application requires changes to the database schema (i.e. new or updated CDTs) you must choose one of the following:
1. Upload the corresponding DDL script(s) that accurately reflect these additions and/or updates.
2. Set the datastore to "Automatically update database schema" and set "Allow Database Schema Changes Through Data Stores" in the Deployment section of the Appian Administration Console
Click on the button "Start Deployment".
During the deployment, the screen is automatically refreshed every 5 seconds with the latest status of the deployment.
When the deployment is complete, the browser will update with a status page.

Deploy from the Command Line Script

The command line script - the client - can be downloaded from the Appian AppMarket.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Open a command window in the same folder to which the client script and supporting libraries were unzipped.
Using the help guide pictured above, run the proper command to automatically import the application. Use -h or -help to view this menu at any time.
1. -ac_customization_path: Indicates the path to the customization file to use when deploying the admin console package or the application package.
2. -admin_console_path: Indicates the path to the admin console file to deploy. NOTE: Use quotations around the entry.
3. -application_path: Indicates the path to the application file to deploy. NOTE: Use quotations around the entry.
4. -ddl_ds: Optional, use only if providing DDL scripts. The name of the datasource to use with the corresponding DDL script. Use a comma separator to enter multiple datasources.
5. -ddl_path: Optional, use only if providing DDL scripts. Indicates the path to the DDL scripts to execute. Use a comma separator to enter multiple DDL script paths. NOTE: Use quotations around the entry.
6. -flyway_path: Optional, use only if providing directories to execute DB migrations via Flyway. Use a comma separator to enter multiple directory paths. NOTE: Use quotations around the entry. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions.
7. -force_import: A boolean flag which specifies whether or not the import ignores impact analysis results.If true, the import will occur even if objects with CDT references are missing
8. -import_customization_path: Indicates the path to the import customization file to use
9. -inspect_only: Optional, use to run an inspection of the package. Indicates the package should not be deployed but inspected only.
10. -password: Password of the Appian user account
11. -proxy_port: Optional, port of the proxy server to use to connect to Appian. This parameter is only used if the parameter -proxy_url is defined. The default value is 8080.
12. -proxy_url: Optional, URL of the proxy to use to connect to Appian.
13. -url: URL of the environment, of the format https://example.appian.com/suite.
14. -username: Username of the Appian user account to use for deployment
15. -uuid: UUID of the application to which patch contents will be added
Deploy the application by typing the command deploy-application.bat and including the relevant parameters. Your command will look something like the one pictured below.

deploy-application.bat -application_path "PATH TO APPLICATION ZIP" -username SERVICE_ACCOUNT_USERNAME -password SERVICE_ACCOUNT_PASSWORD -url APPIAN_URL -ddl_path "PATH TO DLL 1, PATH TO DLL 2" -ddl_ds jdbc/Appian1,jdbc/Appian2

Deploy from an External Continuous Integration tool

Additional Requirement:

An existing external Continuous Integration tool (such as Jenkins or Hudson) that is properly configured

The steps below provide the high level steps to deploy an application from Jenkins.

Create a new external job
Configure the job to run the import script using the guidance in Deployment Option #2 listed above
Execute the job

When the deployment is complete, check the status page verify that the import was successful.

Troubleshooting

Deciphering Script Error Messages

Inspect Failure

Package Validation Failure

In case you want to proceed with deploying the application regardless of missing CDT dependencies, use the flag -f.

Import Failure

Invalid Credentials

Please ensure that these credentials are associated with an active Appian system administrator account. Basic user credentials cannot be used.

Connection Refused With Deployment Command Line Script

A "Connection Refused" error could be the result of using the wrong URL when executing the script. The URL provided as a parameter must:

include the suffix "/suite"
Include a port number if not using the port 80 with HTTP or port 443 with HTTPS

Release Notes

September 2021 - Release 2.5.13

Bug Fixes
- Fixed an issue where setting "appianObjectsRepoPath" prevented a package that included a patches.xml file from being processed successfully

March 2021 - Release 2.5.12

Enhancements
- Updated the link to the import log in the ADM servlet after a change was made to the Appian API.
Bug Fixes
- Fixed a bug that was preventing Flyway files from being included in metadata.properties.

September 2020 - Release 2.5.11

Enhancements
- Upgraded Flyway version to 6.5.5 for compatibility with MariaDB.

August 2020 - Release 2.5.10

Enhancements
- Added the ability to dynamically generate the Metadata file for the "buildAllApps" action to reflect only the list of database scripts that are included in the package for a given commit range.
Bug Fixes
- Fixed the interpretation of "appianObjectsRepoPath" on Windows platforms.

December 2019 - Release 2.5.9

Enhancements
- Added DNS proxy support to ADM
- Added DNS proxy support to AIM
- Added DNS proxy support to AVM
- Added support for special characters in passwords in ADM

July 2019 - Release 2.5.8

Bug Fixes
- Fixed the problem with obtaining TransactionManager and creating DataConfiguration against latest the Appian version

April 2019 - Release 2.5.7

Enhancements
- Added commit message prompt to folder listener
Bug Fixes
- Fixed Windows issue with pushing file updates to versioning manager
- Fixed import patch failure not adding newly created objects issue
- Fixed semicolon separator parsing issue

March 2019 - Release 2.5.6

Enhancements
- Added proxy authentication support for import client

February 2019 - Release 2.5.5

Bug Fixes
- Fixed DDL paths bug

January 2019 - Release 2.5.4

Enhancements
- Improved descriptions of errors encountered during deployments
Bug Fixes
- Fixed "Connection Refused" bug when running on a Jenkins server
- Fixed "buildSingleApp" AVM bug when specifying an appianObjectsRepoPath
- Fixed rare "hanging" bug in AIM Client

November 2018 - Release 2.5.3

Enhancements
- Created a reset command for Remote Automated Deployment Manager
Bug Fixes
- Version and Import Metrics Logger Initialized correctly to fix null pointer exception

October 2018 - Release 2.5.2

Enhancements
- Folder listener to auto trigger “Add Contents” action
- Field validation for import and versioning manager properties files
- Usage metrics collection to better understand tool use
- Updated error log messages
Bug Fixes
- ADM UI: Handle apostrophes in app name
- ZIP type validation for Automated Import Manager

September 2018 - Release 2.5.1

Enhancements
- New buildMultipleApps action
- Check version of tools with -v or -version flags
Bug Fixes
- Fixed ADM SQL errors with non-null statements and forward slash as delimiters

August 2018 - Release 2.5.0

Enhancements
- Added Flyway DB version control tool to command line and AIM GUI
- Allow import of DDL scripts or Flyway scripts without an application zip or patch zip
- Added Folder Listener script that will run addContents automatically when a file is dropped into a folder
Bug Fixes
- Added buildAllApps to list of approved actions
- Set inspect_only properly in AIM
- Fixed bug where repo would be cloned into a folder with an incorrect name
- Passed in correct authentication token for buildAllApps and buildSingleApp

August 2018 - Release 2.4.7

Enhancements
- Added "buildSingleApp" action to extract one app from multi app repo
- Renamed "buildPackage" action to "buildAllApps" to better clarify the functionality
Bug Fixes
- Fixed miscellaneous issues with parsing SQL in DDL file
- Mark/reset issue with large customization files

June 2018 - Release 2.4.6

Enhancements
- Added an import-manager.properties file to set default values for importing applications
- Automated versioning manager supports adding a package with multiple patches
Bug Fixes
- Application version UUID is updated when adding patches to a version control
- Import no longer fails when SQL in DDL file contains a ";", "–" or "/**/"

March 2018 - Release 2.4.5

Add support for proxy configuration in the deployment client script with parameters "proxy_port" and "proxy_url"

January 2018 - Release 2.4.4

Bug fixes

January 2018 - Release 2.4.3

Support for Appian 17.4

September 2017 - Release 2.4.2

Support for Appian 17.3
Better handling of end of line characters in the SQL scripts
Support for customization file when deploying an application package

June 2017 - Release 2.4.1

Support for Appian 17.2
Fix defect preventing to execute DB scripts as part of a deployment

January 2017 - Release 2.4.0

Support for Appian 17.1

October 2016 - Release 2.3

Support for Appian 16.3

September 2016 - Release 2.2.9

Automated Import Manager

Successfully deploy application packages containing new Datastore entities and new dependents on these entities.

September 2016 - Release 2.2.8

Automated Versioning Manager

Fixed defect with missing artifacts in package when using START_HASH and END_HASH.

August 2016 - Release 2.2.7

Automated Versioning Manager

Fixed defect with deploying applications and patches containing updated Documents.

August 2016 - Release 2.2.6

Automated Versioning Manager

New parameter no_update to build a package from the local repository without first performing a checkout
New integrity control when checking in applications and patches

August 2016 - Release 2.2.5

Automated Versioning Manager

Fixed defect with deploying applications and patches containing new CDTs and updated CDTs.

June 2016 - Release 2.2.4

Bug fixes.

June 2016 - Release 2.2.3

Include the source code in all modules.

June 2016 - Release 2.2.2

Automated Versioning Manager

Added new parameter appian_objects_repo_path to specify where the Appian artifacts are located in the repository.

May 2016 - Release 2.2.0

Automated Versioning Manager

Added support for admin console packages

Automated Import Manager

Removed update-database-schema to support native product capability of automatic database updates via datastore and administration console.
Updated Web Browser UI style
Removed option for "Automatically update the database schema when publishing the data stores" from the Web Browser UI
Added support for admin console deployments
Added support in command line for inspect_only parameter

March 2016 - Release 2.1.0

Automated Versioning Manager

Added support for input flexibility. Now, the command line for versioning manager supports all possible parameters.
Allowed tags as inputs to start hash and end hash.
Added inputs of the following predefined keywords: FIRST_COMMIT (which maps to first commit ever made) and LAST_COMMIT (the previous commit). NOTE: this is only allowed on the start hash input.

Automated Import Manager

Added support for 16.1.
Added action for "Inspect Only".

Deployment Automation

joel.larin — Thu, 26 Oct 2023 18:08:30 GMT

Revision 2 posted to Guide by joel.larin on 10/26/2023 6:08:30 PM

Appian provides several DevOps tools to automate the deployment of Appian applications such as Compare & Deploy and Deployment APIs.

The tools described in this play offer a few alternatives to Appian base product features:

Tightly integrate with a version control system to store and retrieve package files using the Automated Versioning Manager (AVM)
Programmatically deploy Admin Console settings and applications using the Automated Import Manager (AIM) plug-in and the Automated Import Manager (AIM) client

Table Of Content

Automated Versioning Manager
Automated Import Manager
Troubleshooting
Release Notes

Automated Versioning Manager

Summary

It unzips the application and organizes the artifact XML files in the repository.
It automates the check-in and checkout operations with the version control system.
It generates application packages for import in Appian based on the contents of the repository and a range of changes to include.

The goal of this tool is to facilitate the adoption and usage of a version control system to perform configuration management of the Appian applications and database DDL files.

Features

Version Control integration (Git, SVN)
Supports Appian applications and patches
Generate import package from hash ranges
Folder Listener to add contents to Version Control
Supports GitHub, GitLab, and BitBucket for Version Control

Usage

Script Execution

To run the script, open a command window and navigate to the directory where the automated versioning scripts are located. They are named version-application.bat or version-application.sh.

Use the -h or -help parameters to view the help menu within the script. The parameters are described here:

Required Parameters (required for all four actions: addContents, buildAllApps, buildSingleApp, buildMultipleApps, and updateLocalRepo)
- -action - Selects which action of the script to run. Acceptable values are: addContents, updateLocalRepo, buildAllApps, buildSingleApp, and buildMultipleApps. Each action is detailed in the use cases below.
- -vc_username -The username associated with the version control (Git or SVN) account. NOTE: these are NOT your Appian credentials.
- -vc_password -Please check the Security Settings of the version control account. If you have 2-factor authentication enabled, the password requires the version control account token. If you do NOT have 2-factor authentication enabled, the password is the one associated with the version control account. NOTE: these are NOT your Appian credentials.
Options for addContents action
- -application_path - The path on your filesystem where the application ZIP is located.
- -admin_console_path - The path on your filesystem where the admin console ZIP file is located.
- -ddl_path - List of comma-separated paths for the DDL files to be included in the deployment package.
- -flyway_path - List of comma-separated paths for the directories to execute DB migrations via Flyway. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions. To learn how the Automated Import Manager uses Flyway, refer to AIM Features.
- -ddl_ds - List of comma-separated datasources associated with the provided DDL files. Must provide the same number of entries as number of DDL files specified with the -ddl_path option or number of directories specified with the -flyway_path option. NOTE: the order of the specified datasource names must match the order of the script paths specified.
- -uuid - The UUID of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -application_name - The name of the application to which the contents of the application should be added. This option is only used if deploying a patch application (Appian 7.9+).
- -commit_message - The message that will be associated with the commit. If not included, a default commit message Committed by @username is provided.
Options for buildAllApps action
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildSingleApp action
- -uuid - The UUID of the application you want to build.
- -application_name - The name of the application you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for buildMultipleApps action
- -uuid - Comma separated list of UUIDs of the applications you want to build.
- -application_name - Comma separated list of names of the applications that you want to build.
- -start_hash - Start hash or revision of the commit you want to start building the package. If not populated, the generated package will include all files starting from the earliest commit. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.
- -end_hash - End hash or revision of the commit you want to end building the package. If this option is not populated, the generated package will include all files up to the latest commit.
- no_update - Build a package from the local repository without first performing a checkout from a remote server.
Options for updateLocalRepo action
- There are no additional options (other than required options) for updateLocalRepo.
Additional Parameters - These parameters are REQUIRED, and may be specified here or in the properties file (described in the following section). If they are specified in both locations, the parameters specified in the command line take precedence.
- -version_control_type - The version control type used, either GIT or SVN.
- -local_repo_path - The path on the filesystem where the local repository is located. All files on the remote repository are cloned to this path. Example: C:\\MyFiles\\ChangeManagementRepo. NOTE: if using Windows, be sure to include double forward slashes (as seen in the example) for path separation.
- -appian_objects_repo_path - Path to the folder containing the Appian objects in the repository. This path is relative to the path of the local repository. If not specified, the Appian objects are checked out to and committed from the root of the local repository path.
- -repo_url - The URL that defines the remote repository. Example: https://github.com/git-username/project-name.git, svn+ssh://svn.code.sf.net/p/project-name/code
- -package_path - For buildAllApps, buildSingleApp, and buildMultipleApps only. The path on the filesystem where packages are generated. Must include filename of package.
- -branch_name - Branch to check out and use (if not master)

Configuring using the Properties File

In case an option is specified both on the command line and in the properties file, the command line value takes precedence and is used.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Use Cases

#1: New developer joins team (updateLocalRepo)

In this use case, a new developer has joined the team and wants to get a copy of all the work completed so far. The developer:

Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using updateLocalRepo as the action flag. The developer must provide the username and password for authenticating against their version control system (-vc_username, -vc_password).

Example Syntax:

> version-application -action updateLocalRepo -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD>

When the script is executed, the developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).

#2: Developer adds artifacts to the repository (addContents)

In the Appian development environment, create an application (or a patch) that contains the changed objects.
Export those changes and download the application ZIP file.
Run the script, using addContents as the action flag. The developer must provide the path of the ZIP file they exported (-application_path) from Appian in step 2. They must also provide the username and password for authenticating their version control system (-vc_username, -vc_password). NOTE: these are NOT Appian credentials.
1. Optional: if the application specified for -application_path is a patch, update the -uuid option to specify the parent application’s uuid. The script will exit with error if a patch application ZIP is provided but no uuid is passed in.
2. Optional: if DDL scripts have been modified, specify the path(s) and their associated JDBC datasource names. NOTE: The same number of DDL scripts and datasource names must be entered into the script, even if the datasource is the same for all scripts. For example: the developer wishes to add two ddl scripts located at C:\DDLs\script1.sql and C:\DDLs\script2.sql. They do so by setting the -ddl_path option as C:\DDLs\script1.sql,C:\DDLs\script2.sql If both scripts are to be executed on jdbc/AppianDS, they must set the -ddl_ds option as jdbc/AppianDS,jdbc/AppianDS. Note that the datasource name is passed in twice.
Optional: include a custom commit message using the -commit_message option

Example Syntax:

> version-application -action addContents -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -application_path "C:\App.zip" -ddl_ds jdbc/AppianAnywhere -ddl_path “C:\script1.sql” -commit_message “Adding account executive record”

When the script is executed, three things occur:

The developer’s local repository is updated to include all changes other developers may have committed (pull in Git, update in SVN).
The application ZIP is unzipped and placed into the local repository, and the DDL files are placed into a ddl_files folder within the local repository. If the -uuid option is selected, the appropriate application xml file is updated.
The changes are committed (and pushed, if using Git) to the remote repository.

When the package is imported into Appian, all lines within script1.sql will be executed and contents within the application ZIP are imported.

Using Folder Listener:

Alternatively, instead of running the script, the developer can execute avm-folder-listener-<os> in the folder-listener directory. The following command prompt will appear:

#3: Build master generates new RC deployment package (buildAllApps)

(If not done previously) Update version-manager.properties with the appropriate fields. See the Script Setup section for details.
Run the script, using buildAllApps as the action flag. The build master must provide the username and password for authenticating against their version control system (-vc_username, -vc_password). To get a specific set of changes, input a value for the -start_hash option and the -end_hash option. This will generate the package with all new and changed files between the two hash options.
1. NOTE: the package will NOT include the changes introduced in the start hash, but WILL include changes introduced in the end hash.

Example Command:

> version-application -action buildAllApps -vc_username <VC_USERNAME> -vc_password <VC_PASSWORD> -start_hash ac37459 -end_hash 6e83b42

When the script is executed, it generates a package at the location specified by the packagePath field in version-manager.properties.

Finally, the build master will import the RC package into the higher environment using the Automated Import tool as described later in this play.

Using Subversion as Version Control System

To allow the Automated Versioning Manager to perform the checkout and commit operations with Subversion, the tool assumes the common Subversion project structure:

trunk
branches
tags

The location of the repository root must be provided by the property repoURL.

versionControlType=SVN

repoUrl=https://svn.code.sf.net/p/deploymentautomationexample/code

branchName=branches/release1

Using Git as Version Control System

To use Git with the Automated Versioning Manager, properties may be specified on the command line or version-manager.properties should be updated as follows:

versionControlType=GIT

repoUrl=https://github.com/gituser/testgitrepo.git

branchName=newbranch

Note: if you are planning to check out a private repository, use the Git SSH URL rather than the HTTPS URL.

Automated Import Manager

Summary

The Automated Import Manager automates the process of inspecting the application, executing DDL scripts, updating CDTs, republishing the appropriate datastores, and importing the application.

Features

Inspect Application: This tool will automatically mimic the "Inspect" functionality that exists within Appian
Validating Application Content: In addition to inspecting the application, the tool will ensure all CDT dependents are included to avoid objects pointing to older versions.
Execute DDL Scripts: DDL scripts can be uploaded and automatically executed. NOTE: For Microsoft SQL Server, only Transact-SQL statements are valid.
Execute Migrations with Flyway: Flyway is a tool used for managing database migrations. It makes it easier to track SQL script versions and not re-execute SQL scripts that have already been run. If a Flyway directory is provided, the Automated Import Manager will automatically execute migrations against the corresponding datasource. Learn more about Flyway here.
Update CDTs: Users are no longer required to delete CDTs before updating them, this tool will perform this step automatically
Import Application and admin console configuration: Automatically import an application with an optional customization file
Republish Datastores: After application import, datastores will be automatically published or republished
Add Patches: Automatically add patch contents to a specified existing application

Usage

Deploy from the Web Browser UI

The tool collects usage metrics by default. To opt-out of metrics collection, check the below option on the Web Browser UI:

Log into Appian as a system administrator
Navigate to the Deployment Automation UI available at the URL: <appian>/suite/plugins/servlet/deploymentautomation
Upload the patch or application you wish to import.
If this application is a patch, select the parent application to which patch contents should be added.
If the new application requires changes to the database schema (i.e. new or updated CDTs) you must choose one of the following:
1. Upload the corresponding DDL script(s) that accurately reflect these additions and/or updates.
2. Set the datastore to "Automatically update database schema" and set "Allow Database Schema Changes Through Data Stores" in the Deployment section of the Appian Administration Console
Click on the button "Start Deployment".
During the deployment, the screen is automatically refreshed every 5 seconds with the latest status of the deployment.
When the deployment is complete, the browser will update with a status page.

Deploy from the Command Line Script

The command line script - the client - can be downloaded from the Appian AppMarket.

If not configured otherwise, the tool collects usage metrics by default. To opt-out of metrics collection, set collectMetrics=false in the file metrics.properties.

Open a command window in the same folder to which the client script and supporting libraries were unzipped.
Using the help guide pictured above, run the proper command to automatically import the application. Use -h or -help to view this menu at any time.
1. -ac_customization_path: Indicates the path to the customization file to use when deploying the admin console package or the application package.
2. -admin_console_path: Indicates the path to the admin console file to deploy. NOTE: Use quotations around the entry.
3. -application_path: Indicates the path to the application file to deploy. NOTE: Use quotations around the entry.
4. -ddl_ds: Optional, use only if providing DDL scripts. The name of the datasource to use with the corresponding DDL script. Use a comma separator to enter multiple datasources.
5. -ddl_path: Optional, use only if providing DDL scripts. Indicates the path to the DDL scripts to execute. Use a comma separator to enter multiple DDL script paths. NOTE: Use quotations around the entry.
6. -flyway_path: Optional, use only if providing directories to execute DB migrations via Flyway. Use a comma separator to enter multiple directory paths. NOTE: Use quotations around the entry. Make sure your SQL script files in each directory adhere to proper Flyway naming conventions.
7. -force_import: A boolean flag which specifies whether or not the import ignores impact analysis results.If true, the import will occur even if objects with CDT references are missing
8. -import_customization_path: Indicates the path to the import customization file to use
9. -inspect_only: Optional, use to run an inspection of the package. Indicates the package should not be deployed but inspected only.
10. -password: Password of the Appian user account
11. -proxy_port: Optional, port of the proxy server to use to connect to Appian. This parameter is only used if the parameter -proxy_url is defined. The default value is 8080.
12. -proxy_url: Optional, URL of the proxy to use to connect to Appian.
13. -url: URL of the environment, of the format https://example.appian.com/suite.
14. -username: Username of the Appian user account to use for deployment
15. -uuid: UUID of the application to which patch contents will be added
Deploy the application by typing the command deploy-application.bat and including the relevant parameters. Your command will look something like the one pictured below.

deploy-application.bat -application_path "PATH TO APPLICATION ZIP" -username SERVICE_ACCOUNT_USERNAME -password SERVICE_ACCOUNT_PASSWORD -url APPIAN_URL -ddl_path "PATH TO DLL 1, PATH TO DLL 2" -ddl_ds jdbc/Appian1,jdbc/Appian2

Deploy from an External Continuous Integration tool

Additional Requirement:

An existing external Continuous Integration tool (such as Jenkins or Hudson) that is properly configured

The steps below provide the high level steps to deploy an application from Jenkins.

Create a new external job
Configure the job to run the import script using the guidance in Deployment Option #2 listed above
Execute the job

When the deployment is complete, check the status page verify that the import was successful.

Troubleshooting

Deciphering Script Error Messages

Inspect Failure

Package Validation Failure

In case you want to proceed with deploying the application regardless of missing CDT dependencies, use the flag -f.

Import Failure

Invalid Credentials

Please ensure that these credentials are associated with an active Appian system administrator account. Basic user credentials cannot be used.

Connection Refused With Deployment Command Line Script

A "Connection Refused" error could be the result of using the wrong URL when executing the script. The URL provided as a parameter must:

include the suffix "/suite"
Include a port number if not using the port 80 with HTTP or port 443 with HTTPS

Release Notes

September 2021 - Release 2.5.13

Bug Fixes
- Fixed an issue where setting "appianObjectsRepoPath" prevented a package that included a patches.xml file from being processed successfully

March 2021 - Release 2.5.12

Enhancements
- Updated the link to the import log in the ADM servlet after a change was made to the Appian API.
Bug Fixes
- Fixed a bug that was preventing Flyway files from being included in metadata.properties.

September 2020 - Release 2.5.11

Enhancements
- Upgraded Flyway version to 6.5.5 for compatibility with MariaDB.

August 2020 - Release 2.5.10

Enhancements
- Added the ability to dynamically generate the Metadata file for the "buildAllApps" action to reflect only the list of database scripts that are included in the package for a given commit range.
Bug Fixes
- Fixed the interpretation of "appianObjectsRepoPath" on Windows platforms.

December 2019 - Release 2.5.9

Enhancements
- Added DNS proxy support to ADM
- Added DNS proxy support to AIM
- Added DNS proxy support to AVM
- Added support for special characters in passwords in ADM

July 2019 - Release 2.5.8

Bug Fixes
- Fixed the problem with obtaining TransactionManager and creating DataConfiguration against latest the Appian version

April 2019 - Release 2.5.7

Enhancements
- Added commit message prompt to folder listener
Bug Fixes
- Fixed Windows issue with pushing file updates to versioning manager
- Fixed import patch failure not adding newly created objects issue
- Fixed semicolon separator parsing issue

March 2019 - Release 2.5.6

Enhancements
- Added proxy authentication support for import client

February 2019 - Release 2.5.5

Bug Fixes
- Fixed DDL paths bug

January 2019 - Release 2.5.4

Enhancements
- Improved descriptions of errors encountered during deployments
Bug Fixes
- Fixed "Connection Refused" bug when running on a Jenkins server
- Fixed "buildSingleApp" AVM bug when specifying an appianObjectsRepoPath
- Fixed rare "hanging" bug in AIM Client

November 2018 - Release 2.5.3

Enhancements
- Created a reset command for Remote Automated Deployment Manager
Bug Fixes
- Version and Import Metrics Logger Initialized correctly to fix null pointer exception

October 2018 - Release 2.5.2

Enhancements
- Folder listener to auto trigger “Add Contents” action
- Field validation for import and versioning manager properties files
- Usage metrics collection to better understand tool use
- Updated error log messages
Bug Fixes
- ADM UI: Handle apostrophes in app name
- ZIP type validation for Automated Import Manager

September 2018 - Release 2.5.1

Enhancements
- New buildMultipleApps action
- Check version of tools with -v or -version flags
Bug Fixes
- Fixed ADM SQL errors with non-null statements and forward slash as delimiters

August 2018 - Release 2.5.0

Enhancements
- Added Flyway DB version control tool to command line and AIM GUI
- Allow import of DDL scripts or Flyway scripts without an application zip or patch zip
- Added Folder Listener script that will run addContents automatically when a file is dropped into a folder
Bug Fixes
- Added buildAllApps to list of approved actions
- Set inspect_only properly in AIM
- Fixed bug where repo would be cloned into a folder with an incorrect name
- Passed in correct authentication token for buildAllApps and buildSingleApp

August 2018 - Release 2.4.7

Enhancements
- Added "buildSingleApp" action to extract one app from multi app repo
- Renamed "buildPackage" action to "buildAllApps" to better clarify the functionality
Bug Fixes
- Fixed miscellaneous issues with parsing SQL in DDL file
- Mark/reset issue with large customization files

June 2018 - Release 2.4.6

Enhancements
- Added an import-manager.properties file to set default values for importing applications
- Automated versioning manager supports adding a package with multiple patches
Bug Fixes
- Application version UUID is updated when adding patches to a version control
- Import no longer fails when SQL in DDL file contains a ";", "–" or "/**/"

March 2018 - Release 2.4.5

Add support for proxy configuration in the deployment client script with parameters "proxy_port" and "proxy_url"

January 2018 - Release 2.4.4

Bug fixes

January 2018 - Release 2.4.3

Support for Appian 17.4

September 2017 - Release 2.4.2

Support for Appian 17.3
Better handling of end of line characters in the SQL scripts
Support for customization file when deploying an application package

June 2017 - Release 2.4.1

Support for Appian 17.2
Fix defect preventing to execute DB scripts as part of a deployment

January 2017 - Release 2.4.0

Support for Appian 17.1

October 2016 - Release 2.3

Support for Appian 16.3

September 2016 - Release 2.2.9

Automated Import Manager

Successfully deploy application packages containing new Datastore entities and new dependents on these entities.

September 2016 - Release 2.2.8

Automated Versioning Manager

Fixed defect with missing artifacts in package when using START_HASH and END_HASH.

August 2016 - Release 2.2.7

Automated Versioning Manager

Fixed defect with deploying applications and patches containing updated Documents.

August 2016 - Release 2.2.6

Automated Versioning Manager

New parameter no_update to build a package from the local repository without first performing a checkout
New integrity control when checking in applications and patches

August 2016 - Release 2.2.5

Automated Versioning Manager

Fixed defect with deploying applications and patches containing new CDTs and updated CDTs.

June 2016 - Release 2.2.4

Bug fixes.

June 2016 - Release 2.2.3

Include the source code in all modules.

June 2016 - Release 2.2.2

Automated Versioning Manager

Added new parameter appian_objects_repo_path to specify where the Appian artifacts are located in the repository.

May 2016 - Release 2.2.0

Automated Versioning Manager

Added support for admin console packages

Automated Import Manager

Removed update-database-schema to support native product capability of automatic database updates via datastore and administration console.
Updated Web Browser UI style
Removed option for "Automatically update the database schema when publishing the data stores" from the Web Browser UI
Added support for admin console deployments
Added support in command line for inspect_only parameter

March 2016 - Release 2.1.0

Automated Versioning Manager

Added support for input flexibility. Now, the command line for versioning manager supports all possible parameters.
Allowed tags as inputs to start hash and end hash.
Added inputs of the following predefined keywords: FIRST_COMMIT (which maps to first commit ever made) and LAST_COMMIT (the previous commit). NOTE: this is only allowed on the start hash input.

Automated Import Manager

Added support for 16.1.
Added action for "Inspect Only".

Deployment Automation

joel.larin — Thu, 07 Sep 2023 19:31:37 GMT

Revision 1 posted to Guide by joel.larin on 9/7/2023 7:31:37 PM

FASD