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:
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.
Version Control integration (Git, SVN)
Supports Appian applications and patches
Generate import package from hash ranges
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.
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)
Options for addContents action
Options for buildAllApps action
Options for buildSingleApp action
Options for buildMultipleApps action
Options for updateLocalRepo action
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.
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.
appianObjectRepoPath
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).
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.
Optional: include a custom commit message using the -commit_message option
> 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.
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.
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.
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.
https://svn.code.sf.net/p/deploymentautomationexample/code
versionControlType=SVN repoUrl=https://svn.code.sf.net/p/deploymentautomationexample/code branchName=branches/release1
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.
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.
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
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:
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.
The command line script - the client - can be downloaded from the Appian AppMarket.
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.
https://example.appian.com/suite
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.
Additional Requirement:
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
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.
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.
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.
Please ensure that these credentials are associated with an active Appian system administrator account. Basic user credentials cannot be used.
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